Expand the documentation with measured figures and operational detail

Most of this replaces "roughly 550 characters per tool" with the actual
per-tool measurements, and fills in the parts a reader hits after the happy
path: what a specific error means, what a setting costs, what is not covered.

Measured rather than estimated:
- Per-tool byte cost, all fourteen, and the per-set totals. 7,673 B for the
  full set, averaging 548.
- Builtin skill bodies at 5,284 B against a 681 B catalogue, which is the
  argument for loading bodies on demand.
- Full system prompt 3,571 chars, core-only 2,045.

New sections:
- tools: which sets to keep and why, the jail function itself, an output-cap
  table, and the real error strings for edit_file and multi_edit.
- configuration: env var per provider preset, cost-estimate limits, what each
  --no-* flag isolates, and three settings that do more than they look like.
- agents: step caps per variant, which variant to reach for, and the fact that
  reasoning is charged as output and discarded first by compaction.
- headless: exit code 0 means "the turn completed", not "the answer was yes" —
  with the jq pattern for gating on content. Timeouts, concurrent -c runs
  fighting over one session, CI recipes for --no-skills.
- mcp: parallel connect, startup cost, a debugging ladder, and that toolSets
  does not gate MCP tools.
- registry: publishing, local testing over http://localhost, and a
  troubleshooting section keyed on the actual validator messages.
- memory: what compaction discards in what order, /compact versus automatic
  pruning, and that -c matches on cwd.
- skills: the frontmatter reader's limits, and how to verify a skill loaded.

Corrections found while cross-checking against the source:
- The guard table was missing --force-with-lease and > /dev/sd…
- The done event's token fields are optional, so the jq example filters on one
  rather than assuming it.

Two honest limits now written down: the guard matches command strings, so a
base64-decoded or script-wrapped command is not caught; and a registry index is
trusted for its contents, not its authorship.

Verified: all internal links and heading anchors resolve, every docs/ page is
reachable from the README, 538 tests pass, typecheck clean.

README.md

@@ -106,21 +106,24 @@ core ones and a disabled set reaches neither the wire nor the prompt.
 
 ## Documentation
 
+Start with whichever question you have. Each guide says what it decided and why, not just what
+the flags are.
+
 | Guide | Contents |
 |---|---|
-| [Configuration](docs/configuration.md) | config file, environment variables, every flag |
-| [Tools](docs/tools.md) | every tool, tool sets, the approval model, the guard |
-| [Agents and thinking](docs/agents.md) | variants, thinking levels, read-only modes |
-| [Skills](docs/skills.md) | the bundled skills and writing your own |
-| [Plugins](docs/plugins.md) | the plugin interface and the builtins |
-| [Registry](docs/registry.md) | installing external skills and plugins |
-| [Memory and state](docs/memory.md) | memory, task lists, sessions, compaction |
-| [MCP](docs/mcp.md) | connecting Model Context Protocol servers |
+| [Configuration](docs/configuration.md) | config file, provider presets, environment, every flag |
+| [Tools](docs/tools.md) | every tool, tool sets and what they cost, the approval model |
+| [Agents and thinking](docs/agents.md) | variants, thinking levels, step caps, which to reach for |
+| [Skills](docs/skills.md) | the bundled skills, writing your own, why the catalogue is split |
+| [Plugins](docs/plugins.md) | the interface, the guard and its limits, builtin versus installed |
+| [Registry](docs/registry.md) | installing external skills and plugins, publishing your own |
+| [Memory and state](docs/memory.md) | memory, task lists, sessions, compaction and its repair |
+| [MCP](docs/mcp.md) | connecting servers, namespacing, cost, debugging one |
 | [Headless mode](docs/headless.md) | `-p`, JSON events, exit codes, CI recipes |
 | [Architecture](docs/architecture.md) | how the loop works and why it is built this way |
-| [Development](docs/development.md) | building, testing, releasing |
+| [Development](docs/development.md) | building, testing, adding a tool, releasing |
 | [Roadmap](ROADMAP.md) | what is next and what has been declined |
-| [TODO](TODO.md) | the current work list |
+| [TODO](TODO.md) | the current work list, with known rough edges |
 
 ## Commands