Pouchy World — documentation index

Twenty-odd world documents live in this directory and, until this file existed, a reader arriving at the repository had no way to tell the three they need from the seventeen written for whoever was on shift that week. This is the routing table.

What it is, in one paragraph. The Companion SDK gives you one character talking to one person. A world is several characters sharing a single committed state — so the questions change: who speaks this beat, what actually changed, and who is allowed to know it. A cast of independent chatbots is not a story; three agents each holding a private idea of what happened contradict each other by the third exchange. A world has one writer. A beat selects who speaks, runs them, and commits once; nothing reaches a reader until the state their lines narrate is true.

See one running: pouchy.ai/world — FLIGHT ZERO, an interactive drama in Chinese and English.

Start here

The npm package's own README (packages/world-sdk/README.md, also on npm) is the method-by-method reference; this index does not duplicate it.

The four things integrators get wrong first

Each of these cost a real support round, so they are named here rather than left in the document that explains them.

1. The two lanes are not one lane. The machine lane (sessions, turns, events) needs a project Secret Key and a provider signature over the exact bytes sent. The owner lane (authoring, reading, script drafts) takes an owner token, or a project admin key for an unattended backend. Every signed door answers the same uniform 403 on a bad signature — deliberately, because an endpoint that names the failing credential is an oracle. → world-sdk-errors.md

2. The turn id IS the idempotency key. Mint one per beat and re-send the same one to retry. A new id is a new beat: new model calls, a new commit.

3. executionStatus and deliveryStatus answer different questions. The first says whether the world moved; the second says whether the audience has heard yet. A pending delivery is a durable outbox retrying, not a failed turn.

4. Patch validation is all-or-nothing. One invalid op voids the whole batch — including the ops that were fine — so the beat moves nothing. rejectedEffects on the thrown error names which op and why; an undeclared id means the instance is pinned to an older story revision, while an unmet node prerequisite means an earlier beat never committed. Those two need completely different fixes.

Operating and release

These are not published — they describe how we operate the platform rather than how you build on it, and they are named here so the list is honest about what exists rather than implying this index is everything.

Internal records — history, not instructions

These are acceptance logs and plans kept for provenance. They describe what was done on a given day and are not guidance for building against the platform; read them only when tracing why something is the way it is.

pouchy-world-batches.md · pouchy-world-batch10-plan.md · pouchy-world-public-demo-plan.md · world-batch8-* · world-batch10-* · world-deliberation-sandbox-audit.md · world-environment-deletion-proposal.md · dispatch-serial-world-providerref.md

Where the code lives

The demo is worth reading as an example precisely because it takes no shortcuts: it drives the platform through PouchyWorldClient against the public /v1 plane, exactly as a third party would, and never imports an internal world store.