Documentation style

The treeCopy Anchor Link

User documentation is one tree under docs/, organized by what the reader is doing:

The top level holds README.md, CONTRIBUTING.md and LICENSE, nothing else. The model, architecture and contributor process live in this tree; unresolved work is cards on Volter's board. Cross-repo strategy, proposals and dated work records live in the company workspace. A page that serves two modes is split; a page named after a task that shipped is deleted.

A tutorial page is its own testCopy Anchor Link

When a bash fence launches background work, its following text fence is the output readiness condition. The runner preserves early output and waits for all expected lines, including when the fence ends with a foreground command. This additional wait uses the expectation-bearing step's deadline; the existing background settling period is unchanged. Missing output remains a failure; the runner does not invent readiness commands.

The shared executor, packages/cli/src/journeys/tutorial.ts, parses and executes a page's runnable fences exactly as written. A file-declaring tutorial names it in an author comment. Task guides may link a canonical worked example or describe conditional and interactive steps; being in guides/ does not establish an executed walkthrough. Run only the scope authorized by the owner and repository instructions; the existence of this runner does not establish that every release executes it. Retain the page identity, dependency versions, conditions and actual results when recording a walkthrough. The page's fences are the steps, in order:

• ```bash — every non-comment line is one command the reader types, run in one shell session that persists across the page (env, cwd, background jobs). A trailing & runs a server in the background.
• ```text right after a bash fence — what the reader sees: every line must appear in that command's output, after ports, ids, hashes and times are masked. Show the lines that matter, not the whole screen.
• ```<lang> file=<path> — a file the reader writes at that path before going on. A page declares its own app this way (package.json, .env.example, a script), so it is self-contained. Paths are relative to the app directory in both the runner and recording, including after a shell command changes directory.
• Anything else is illustration and does not run. A console fence can describe an interactive command or a conditional step for an existing app; report those observations separately from the executable walkthrough, rather than claiming the runner exercised them.

Every command runs literally, bun add included: the runner publishes this checkout's packages to a registry on the machine and the page's app installs from it, so bun add -g @volter/world puts volter on the PATH the way it does for a reader. Each page's recording in docs/media/<page>/ was made from the same steps with vhs (bun scripts/docs-media.ts <page>; --check names a page without its recording). Embed a recording only when it corresponds to the current instructions; retain superseded files as historical evidence. A rewritten page does not inherit verification from its old recording. A page that drifts from the product fails by line number when its walkthrough runs. The executor stops at the first failed step, retains its result and performs the existing shell and World cleanup. A documented refusal whose expected output matched remains successful; later steps are not attempted after a failed prerequisite. Failed walkthroughs retain their workspace after the normal cleanup, so their World state and diagnostics can be inspected. The executor selects guides that declare their app files, plus explicitly marked guide and cookbook journeys; conditional task guides remain documentation and carry no automatic execution claim.

WordsCopy Anchor Link

Use the user glossary in every user-facing page, flag and message, and the build glossary in contributor pages. scripts/docs-language-check.ts holds the user pages to the user words. The names that changed:

Three nouns nest, and the README's first sentence says so: a twin is one vendor, a world is the twins an app needs running together, Volter runs worlds.

ClaimsCopy Anchor Link

• Say what is real, deterministic, stubbed or externally dependent.
• Never describe an unmodeled operation as supported; a twin refuses it the way the vendor would.
• Never call a sandbox hermetic. Cooperative refusal is not a network boundary.
• Every example states what it needs beyond this checkout (a real service, another repository's checkout) and its expected runtime past a minute.
• A standing document reads as present-tense truth: no history, no status sections, no amendment narrative. Git is the history; the company repo's notes are the records.
• A number in prose goes stale the day a manifest grows. Link the generated table instead.

NamesCopy Anchor Link

File names are what a reader would search for: lowercase, hyphenated, a task or a noun, never a project word. Headings are sentences a reader would say, not labels.

Canonical ownershipCopy Anchor Link

• concepts/the-model.md owns storage, branching, push and deployment semantics.
• concepts/worlds.md owns lifecycle and capacity; data-and-keys.md owns custody and access.
• reference/cli.md, sdk.md and http-api.md own callable surfaces; verify descriptions against implementation, not only whether method names occur.
• contributing/architecture.md and the corresponding policy rules own implementation boundaries.
• Unresolved Twin work is cards on Volter's board, not a page here. Do not copy cross-repo plans into the docs.
• skills/volter-world/AGENTS.md owns portable operator instructions; SKILL.md links it.
• Package READMEs own vendor-specific usage and limitations. Link shared semantics instead of repeating a storage model. Use the generated catalog for counts and protocol standing.
• Fumadocs in apps/docs renders the canonical docs/ pages and exported cookbook examples. Publishing documentation owns the preview and hosting workflow. The product site's landing page introduces the product and links the tutorial and model rather than maintaining copies of them.

Dated records and captured upstream source documents are historical evidence. Do not rewrite them as current instructions. Documentation checks cover the standing entry points, guides, reference, contributor pages, package READMEs, cookbook and operator sources.