# docs/

Everything an agent needs that is not a rule and not code. `CLAUDE.md` at the
root carries the rules and points here. Nothing here restates a rule.

The tier is the path, so staleness is visible from the filename.

| path | holds | lifetime |
| --- | --- | --- |
| `docs/*.md` | living. One file per subsystem: the reasoning, corrected in place. Each carries `Last verified: <date> @ <sha>`. | until it is wrong |
| `docs/evals/` | dated measurements, one file per measurement. **Never edited after the day.** A newer number is a new file. Indexed in `docs/evals/CLAUDE.md`, which marks each one live or superseded. | forever |
| `docs/caveats/` | known limits, one entry per limit, each with a task id and a revisit trigger. Indexed in `docs/caveats/CLAUDE.md`. | until fixed, then deleted |
| `docs/plans/` | the plan for one piece of work, frozen once it starts. Indexed in `docs/plans/CLAUDE.md`. | until the work lands |
| `docs/capabilities/` | generated. The capability ledger and its probe harness, regenerated from `docs/spec.md` plus a named eval. **Never hand-edited**, except `domains.yaml`, `probes_field.json` and the scripts, which are its sources. Indexed in `docs/capabilities/README.md`. | until the spec or the measurement moves |
| `docs/architecture/` | generated. The architecture observation and its evidence pack, rebuilt from source by the scripts beside it. Indexed in `docs/architecture/README.md`. | until the shape changes |
| `docs/archive/` | dead. Read by nobody by default. | forever |

## Rules for this directory

* One fact, one home. A measurement is cited from a living doc, never copied
  into it. The two drift the moment they are both edited.
* A living doc is corrected in place and its `Last verified` line moves with the
  correction. Do not append a changelog to it.
* A number in prose with no `docs/evals/` file behind it is an opinion.
* Fixing something deletes its caveat. It does not edit the eval that found it.
* **A generated tier is rebuilt, never corrected.** A wrong row in
  `docs/capabilities/` or `docs/architecture/` is a bug in the generator or in
  one of its hand-written inputs. Editing the output makes the next rebuild
  silently undo the fix.

## Where a subsystem's reasoning lives

`routing.md`, `language.md`, `world.md`, `offload.md`, `deployment.md`,
`ecosystem.md`, `workflow.md`, `design.md`, `rearchitecture.md`,
`determinism.md`, `protocol.md`, `handler-wiring.md`, `operations.md`, `qa.md`.
The root `CLAUDE.md` says which one to read before touching what.