Documentation: README, scenarios authoring guide, terms.md updates

Motivation

The codebase has shipped two substrate-level changes recently — scenarios-as-data with snapshot/hash provenance, and cognition-as-data — and the documentation has not kept up.

Three concrete gaps:

• docs/terms.md is partially stale. Its "Adjudication retry semantics" section still describes the retry budget as ADJUDICATION_RETRY_BUDGET = 2 overridable via CHUKWA_ADJUDICATE_RETRY_BUDGET. Neither construct exists anymore — the budget is now world.cognition.adjudication_retry_budget, declared per-scenario. There are no glossary entries for cognition, scenario_snapshot, or scenario_hash, all of which are first-class concepts now.
• No README.md at the repo root. A new contributor or research collaborator who clones the repo lands on a Cargo.toml, a Containerfile, four narrowly-scoped docs, and a src/ directory with 24 files. Nothing tells them what chukwa is, what the conceptual model is, or where to go next.
• No author-facing doc for scenarios. Scenarios are now the primary authoring surface (entities + environment + cognition all live in JSON), but the only documentation is the two existing scenario files themselves and the rustdoc on scenarios.rs. A scenario author has to read code to know the shape, the validation rules, the snapshot guarantee, and the token-substitution requirements on cognition templates.

The existing docs that do exist — particularly terms.md — are excellent. The gap isn't quality, it's coverage of recent work.

This ticket fixes those three gaps and the small in-code stalenesses that pair with them. Hard discipline: every word written must describe something that exists and has been demonstrated. No speculation, no "future" sections, no features that haven't shipped, no roadmap. Drift detection, scenario lineage, parent_hash, scenario forking — none of these are mentioned anywhere in the new docs because none have shipped.

Caller / handler back-and-forth

This is a documentation ticket. Most of it can be done by the handler autonomously. There is no schema cut, no worlds to delete, no production state to coordinate against, no MCP smoke required. The handler can edit markdown, run cargo build, run cargo test --lib, and request review on a feature branch.

Where the caller is in the loop:

1. Prose review before merge. The handler delivers all changes on a feature branch and posts a comment summarizing what each file says. The caller reviews the drafts on the branch (via git_diff or read_code on the worktree path the handler provides) and either approves or pushes back on specific bits. This is the main loop point — docs are easier to drift than code, especially toward speculation, and a review pass before merge is the cheapest way to keep the discipline tight.
2. No deploy required. Markdown files in docs/ and README.md are repo content, not embedded in the binary. The small in-code stalenesses (lib.rs, worlds.rs module-doc) compile but don't change runtime behavior — the binary is functionally equivalent. The handler may merge to main without rolling the pod; the next functional ticket will carry the rebuild.

Block-surfacing rule applies: any block (compile failure, missing context for a doc claim, anything that stops forward motion) gets a comment on this ticket immediately.

The change

1. docs/terms.md updates

Three modifications, named precisely:

Fix the stale retry-budget paragraph. Under "Adjudication retry semantics → Budget," replace the existing text:

Default: ADJUDICATION_RETRY_BUDGET = 2, i.e. three total attempts (one initial + two retries). Override at process startup via the environment variable CHUKWA_ADJUDICATE_RETRY_BUDGET.

with text reflecting the current state:

The retry budget is world.cognition.adjudication_retry_budget, declared per-scenario in the scenario's cognition block. The adjudicator gets (1 + retry_budget) attempts total. Both shipped scenarios (ant_on_plate, locked_vending_room) declare a budget of 2.

No environment variable, no compile-time constant — those are gone.

Add three glossary entries. Place them in a new sub-section under "World structure" (or "Scenario structure" if the handler wants to add that grouping):

• cognition. The set of prompts, schema, and budget that interprets a world. Seven fields: perceive_system, intend_system, adjudicate_system, adjudicate_user_template (must contain {world}, {agent}, {intent}), adjudicate_corrective_template (must contain {complaint}), adjudication_schema (JSON schema as Value), adjudication_retry_budget. Declared in scenario JSON; frozen into World.cognition at seed time; read by minds::perceive/intend/adjudicate at turn time. There is no default and no test placeholder — every scenario must declare a complete cognition block.
• scenario_snapshot. Full serialized scenario content embedded in WorldMeta at world-creation time. Lets a world describe what it was seeded from regardless of later edits to the source scenario file.
• scenario_hash. sha256 hex digest of the canonical (sorted-key, no-whitespace) form of scenario_snapshot. The indexing key for "which worlds ran this exact scenario content."

Update the existing scenario entry. It currently says "Scenarios are defined in the codebase and enumerated by list_scenarios." Replace with text reflecting that scenarios are now JSON files under /scenarios/, embedded at compile time via include_dir!, each declaring a scenario_slug, description, chronon_seconds, environment, entities, and a complete cognition block. Catalog load panics on malformed input. Pointer to the new docs/scenarios.md for author-facing detail.

2. README.md at repo root (new file)

Brief, calibrated to what's shipped. Suggested sections:

• What chukwa is. One paragraph. A simulation kernel with prose worlds, LLM-driven cognition, turn-based commits, append-only audit, and per-world isolation.
• Conceptual model. Two paragraphs. (a) A world is the canonical state at one moment in simulated time, identified by an operator-typed slug; multiple worlds coexist independently, each with its own turn chain and audit log. (b) A turn is one perceive → intend → adjudicate → commit step, scheduled by run_turn. The prompts and schema that drive cognition live in scenario data, not in code.
• Where to go next. Bullet list of pointers:
  • docs/terms.md — precise vocabulary
  • docs/scenarios.md — how to author a scenario
  • scenarios/ — the two shipped scenarios as worked examples
  • docs/llm-router.md — LLM transport
  • docs/oauth.md — auth
  • docs/watcher.md — the live event stream
  • k8s/ — deploy manifests
  • tests/ — behavioral expectations

No roadmap, no "future plans," no contribution guide, no quickstart for local dev (we don't have a clean local-dev story documented and shouldn't fabricate one). If the README runs longer than ~80 lines, something is wrong.

3. docs/scenarios.md (new file)

The how-to-author-a-scenario doc. Suggested structure:

• Overview. Scenarios are named starting templates for create_world. Declared as JSON files under scenarios/; embedded into the binary at compile time via include_dir!; loaded once on first access; cached for process lifetime.
• File location and naming. One file per scenario, named <slug>.json. The filename stem must pass the slug grammar (see docs/terms.md) and must equal the file's scenario_slug field. Mismatch panics at catalog load.
• Required fields. For each top-level field, shape and meaning: scenario_slug (string, slug grammar), description (string, prose), chronon_seconds (integer, seconds of simulated time per turn), environment (string, prose describing the setting), entities (array of entities — agents have goal + memory, props have state), cognition (object — see below).
• The cognition object. Each of the seven fields with what it drives. Token requirements: adjudicate_user_template must contain {world}, {agent}, {intent}; adjudicate_corrective_template must contain {complaint}. Validated at catalog load; missing tokens panic.
• Catalog load behavior. Panics on: malformed JSON, filename/slug mismatch, slug grammar violation, missing template tokens. Rationale: a bad scenario file is a build-time fault, not a runtime fallback.
• The snapshot guarantee. When create_world seeds a world, the full scenario content (including cognition) is serialized into WorldMeta.scenario_snapshot and a sha256 of the canonical form is stored as scenario_hash. Editing a scenario file thereafter does not affect existing worlds; new worlds pick up the edit. The two are independent: same slug, different content over time, with each world remembering exactly what it was seeded from.
• A worked example. Walk through scenarios/ant_on_plate.json field by field. Use the actual file contents.

4. Small in-code stalenesses (paired with the docs work)

These are mechanical, not prose. Group them in one commit if convenient.

• src/lib.rs — extend the existing pub use scenarios::{...}; line to also export Cognition. Currently a library consumer must write chukwa::scenarios::Cognition; this lets them write chukwa::Cognition consistent with Scenario, ScenarioCatalog.
• src/lib.rs — refresh the crate-level docstring. Current text says "Phase 2 adds prose worlds, typed agents and props, and a cognitive turn loop." Add a sentence noting that scenarios and cognition are now both data, with provenance via scenario_snapshot + scenario_hash.
• src/worlds.rs — update the on-disk-layout diagram in the module doc. The meta.json summary line currently reads # scenario, name, created_at, slug — extend it to mention scenario_snapshot and scenario_hash.

Acceptance

Mechanical

• docs/terms.md no longer mentions ADJUDICATION_RETRY_BUDGET or CHUKWA_ADJUDICATE_RETRY_BUDGET.
• docs/terms.md contains entries (sections, headers, or definitional paragraphs — handler's call on form) for cognition, scenario_snapshot, scenario_hash.
• docs/terms.md::scenario entry mentions JSON files, include_dir!, and the cognition block.
• README.md exists at the repo root.
• docs/scenarios.md exists.
• src/lib.rs exports Cognition via the existing scenarios pub use.
• src/worlds.rs module-doc on-disk diagram lists scenario_snapshot and scenario_hash in the meta.json summary.
• cargo build clean.
• cargo test --lib green (no test changes expected; the build needs to compile).

Prose discipline

This is the main acceptance gate beyond mechanics:

• The handler grep-checks all new prose for forward-looking language before requesting review. Specifically: no occurrences of "future," "planned," "will eventually," "TODO," "we plan to," "roadmap," or similar in any new doc file. (The handler may use these in their own ticket comments, but not in the docs themselves.)
• No new doc file describes drift detection, scenario lineage, parent_hash, scenario forking, an extract script, or any other unshipped concept.
• No new doc file documents an MCP tool, kernel function, or helper that does not currently exist in the codebase.

Caller review

After mechanical acceptance, the handler posts a comment on this ticket naming the feature branch and the worktree path where the drafts live. The caller reads each new and modified file and either approves or pushes back on specific bits. The handler then merges to main. The handler does not merge before caller review.

Deploy

Optional on this ticket. The docs are repo content. The in-code changes are functionally inert. The handler may merge to main without rolling the pod and let the next functional ticket carry any rebuild. If the handler chooses to deploy anyway, that is fine and they should report it in proposed_resolution.

Explicitly out of scope

• API reference for the MCP surface. The inline tool descriptions are the closest thing today and a hand-written reference would duplicate and stale.
• Local-dev / quickstart guide. We don't have a clean documented local-dev path and inventing one is out of scope.
• Drift-detection helper or any associated docs.
• Scenario lineage, parent_hash, fork, mutation_note — none have shipped.
• Migrating, restructuring, or rewriting docs/llm-router.md, docs/oauth.md, docs/watcher.md. They cover different concerns and are fine as-is.
• Adding an architecture diagram, a sequence diagram, or any other visual aid. Worth doing eventually but not in this ticket.
• Documenting feature flags, deploy procedures, or runbook material beyond what k8s/ already exposes.
• Editing the existing scenario JSON files. Their contents are the contract; the new doc references them, doesn't modify them.

No open knobs

The three deliverables are named. The acceptance bar is named. The discipline (no speculation, no unshipped features) is named. If a question arises during implementation, the handler should leave a comment on this ticket rather than guess.