Start here

What you are adding to your game

A mind for each character. You give a character three things: a personality, a list of what they can do, and a list of what they must never do. From there they notice what happens to them, remember it, form plans and act on them, reacting to the player and to each other. Reflexes, memory and acting run inside your build. Planning is a small hosted call, made only when something worth planning about happens.

Step 1 — See it work, no engine (5 minutes)

pipx install https://canonopy.com/dl/canonopy-0.1.5-py3-none-any.whl
lw init
lw dev --mock

lw init writes lw.manifest.json and lw.env into your folder. lw dev --mock starts the brain and a small town with four named characters and no engine. In a second terminal:

lw trigger theft --char hulda --value 40

You will see the chain: the line lands in Hulda's journal, the gate classes it as a theft, the deliberator wakes, composes a plan, ranks it, and step one fires. Then:

lw watch          who is doing what, live
lw why hulda      the receipt: what she believed, what she chose, why

Try your own sentence: lw trigger raw "made away with the contents of my till" --char adrianne. Phrasing does not matter; meaning does. lw dev --down stops everything.

→ Every command: the lw CLI

Let your coding agent do the rest

The package carries an MCP server, so an agent working in your repo can drive the brain and read these docs itself instead of you relaying. One line registers it once lw is installed:

claude mcp add lw -- lw mcp

Any other MCP client takes the same server as a command: {"mcpServers": {"lw": {"command": "lw", "args": ["mcp"]}}} in its config.

From then on the agent has twelve tools. It can read every page of these docs (lw_docs), check your manifest and explain a load error (lw_manifest_check), start from a running town and plant an event, give an order, watch the cast and read a receipt (lw_perceive, lw_command, lw_trigger, lw_watch, lw_mind), see what the flywheel has queued and how a retrain is going, and request a verb you do not have yet. So "wire my engine's state feed to this" or "why did Hulda refuse to serve the player" are questions it answers from the same pages and the same receipts you would use.

Two things are deliberately not tools: sending captured moments up (lw sync --send) and requesting a retrain (lw train). Those are yours to do at the terminal.

Step 2 — Connect your engine (a first character in about two hours)

Your engine does three things. It sends a state feed on one websocket several times a second: where the player and each character are, who is armed. It executes two commands that come back on the same socket: move this character like this (loadScenario), say this (say). And it tells characters what happened through one HTTP call, in plain words: "the newcomer took a purse right off me".

A first adapter needs eight movements your engine can already do: walk to, approach and face, follow, hold and watch, back off, flee, square up, speak. That covers every reflex and every shipped plan.

→ Field by field, with the exact JSON: Wiring your engine → A finished adapter to copy: Unity runtime

Step 3 — Author your characters (an afternoon)

Everything you author lives in one file per level, lw.manifest.json, checked when it loads, never at runtime:

• verbs: the level's vocabulary, each naming the engine action it maps to
• characters: per character, can (a narrowing of the level's verbs) and never (rules: never here, never now, never to them)
• places: by type, so one rule covers every temple, not one shrine
• events: your world's own phrasings, classed by you ("the forge test-fires" is ambient, "the captain's tithe" is a theft)
• speech: what this level lets characters say: facts, names, places

A character with no can list gets a sensible default from their archetype, and the load report tells you what was assumed.

→ The contract, section by section: Characters SDK (start with §⁠02, then §⁠08, §⁠11, §⁠16, §⁠18)

Step 4 — Watch it, then ship it

lw watch shows every character's rung, what they are doing, the open plan and its step, and warns loudly (LW4001) if a character wants something and never gets to do it. lw why <name> explains any single decision. The same stream is an HTTP endpoint you can wire to a debug overlay.

To ship: lw licence activate <key> fetches your local weights and points the build at the hosted deliberator; lw bundle --target windows --build-key <key> packs the brain as one folder your installer carries and your game launches (the player installs nothing). When the trial ends, lw licence subscribe ($20 a month) turns the same key into the paid licence. Reflexes, memory and acting stay on the player's machine; one small request per wake goes out. If the licence lapses, characters lose the ability to plan and to be emergent; reflexes keep running, nothing breaks.

→ Receipts, field by field: Receipts v1 Captured moments (never text) improve your own weights on request and, pooled with everyone else's as agreed at signup, the base every new studio starts from.

→ Licensing, the flywheel, retrains and new verbs: the lw CLI §⁠07 and §⁠08

When something does not happen

Three different gaps look alike from outside: a character "won't do the thing".

Nothing here is a config flag you have to guess at, and nothing is silent.