neokarma.md is on GitHub: a story you can open and change

The repository contains the current specification snapshot, a complete short story, status notes and contribution guidance. The illustrated guide and latest spec remain at neokarma.md.

Give the story a shape, and leave room to play

A neokarma.md file describes a premise, a universe, the way a character speaks and the important moments ahead. You can set the pace, write rules for the world, add branches and describe how actions have consequences. Optional game sections add dice, health, dangers and blessings.

In AI Pets, code tracks the story’s structure and game state. The AI character tells each turn around what you say. Milestones give the adventure a direction; scenes give you time to try an idea. A character’s voice belongs in the file too, while the pet you choose keeps its own identity.

You can write the file yourself or give the specification to an AI agent and work on it together. Either way, you can open the result in a text editor and see what you’re asking the story to do.

A small scene

Here’s a passage from The Lantern Path, the new three-milestone example. This is an excerpt; download the complete file to import it.

# Milestones

## the garden gate
Miri, a neighbour in a floury apron, stands beside a lantern that has tipped into wet soil. Its light is out. She asks for help lighting the path for people walking home.
Signs: A gate creaks ahead; a small patch of the path is dark.
Scene: Help Miri find a safe way to light the path. The scene ends when the path is lit or your owner chooses to move on.
Max turns: 5

The text introduces the problem. Signs hints at it on the way. Scene says what you’re trying to resolve, including the choice to walk on. Max turns keeps this stretch from going on forever. You can change the lantern, the neighbour or the whole village without changing that structure.

Try your file on aipets.com

1. Sign in and open Studio → Stories. Choose Import neokarma.md and select the complete file.
2. Review the text and the reader’s errors or warnings. Choose Import and open story to save a new private story. Importing it does not assign it to a pet.
3. Choose Play story, select your pet and add the provider keys required by its voice and model settings. You can play in your browser without a device; turns use your providers.
4. Change a scene or a rule, then try it again. Export neokarma.md saves the text back to a file. Assignment to a pet on supported AI Pets hardware is a separate step.

Start with an unassigned copy while experimenting. Saving an assigned story restarts it for its assigned pets and clears their adventure diaries.

What works today, and what’s still ahead

Standalone files, import and export, browser play, milestones, scenes, voice, pacing, branches, consequences and dice mechanics are implemented. The small example and both full examples in the spec pass the current AI Pets reader. That checks their structure; it doesn’t promise every model will tell them equally well.

Some features have narrower support. The spec includes fights, but scored fights are still behind an internal test gate. For ordinary accounts and Pocket devices, a Fight: place plays as an ordinary milestone. Animation and sound references also need the corresponding assets and runtime support; those assets aren’t embedded in the Markdown.

I’d like reusable worlds, characters and rules to make larger projects easier. That is future direction, not a new module system you need to learn today. A complete, editable story in one file remains supported. The neokarma.md site is the documentation; this announcement isn’t a marketplace launch.

The GitHub publication does not introduce a new reuse license. A specification-wide license has not yet been selected, and the repository says so explicitly.

Read the spec and download the example on GitHub. If a line is confusing, or a story behaves differently from what the format describes, open an issue with a small example. That’s useful feedback while we keep making this better.