docs: README was stale across two releases — scout/integrator, agy and Cursor pins

[jmvbambico]

The README had drifted across two releases, and one cell had been wrong since v0.7.0. Every claim it makes about the agent catalog is now checked against installer/registry.json rather than by eye.

v0.12.0's roles were undocumented

scout and integrator shipped in v0.12.0 and appeared in the README zero times — not in the agent table, not in the architecture sketch, not in the install walkthrough, not anywhere. A reader had no way to learn the roles existed, let alone why.

Now:

• a ### Roles table giving each of the five roles its write capability, whether it is required, and what it is for;
• the measured rationale for why the two optional ones exist, taken from the code comments that justify them — reading and searching a repo by hand was 52% of the orchestrator's result bytes across 30 audited sessions, and git plus gate plumbing was 727 git calls (725 kB) and 185 gate calls (84 kB). That is the argument for offloading them, and it belongs in front of the reader;
• both questions in the install walkthrough, in the order the installer asks them, with the note that skipping one yields no spec and no dangling reference;
• both in the architecture sketch, as a compact + optional: tier rather than by widening the ASCII art;
• the reconfigure section now says adding or dropping them is a re-run.

v0.13.0's pin changes, and one older error

The agent table said Antigravity's model pin was optional. It is required as of v0.13.0 — and an unpinned agy resolves to no model and dies on launch, so that cell was actively misleading.

Checking the whole table against the registry turned up two more:

• Cursor was listed optional and has been required since v0.7.0 — five releases stale. With no pin the id passed is the orchestrator's, which cursor-agent rejects (Cannot use this model) and exits 1.
• Hermes is reviewer-capable in the registry but was lumped into a coder-only row.

Since every agent in the catalog gained scout and integrator, repeating those in all thirteen rows would have been noise — the table now states it once above and the Roles column carries only what distinguishes the agents.

Step 4 of the walkthrough also said pins are picked "per coder". They are per worker, and validate() now refuses a blank where the row requires one, in any role.

A sixth property

The properties section gains the antigravity-native completion gap: a dispatch produces its answer and then sits status: running forever, because the harness scrapes an interactive TUI that has no completion marker — while already writing active_turn_id: null to its own state file. That belongs in the README rather than only in docs/, because a reader meeting a hung dispatch needs it on the way past. The workaround it points at is load-bearing right now: the cross-vendor review of the change that introduced it was recovered exactly that way.

Docs index

Was missing STATS.md, CMDCODE.md and ANTIGRAVITY-NATIVE-COMPLETION.md, all three of which the prose already links to inline.

Verification

• python3 -m pytest -q → 279 passed (docs-only change; no code touched).
• Every mapped row in the agent table cross-checked programmatically against installer/registry.json for model.required and the reviewer role — all agree.
• All six markdown tables internally consistent in column count; all five docs/ links resolve to real files; the [Roles](#roles) anchor has its heading.

Note on sequencing

This should land before the v0.13.0 tag, so the release ships documentation that describes it. Tagging first would publish a release whose README is wrong about its own headline feature.

🤖 Generated with Claude Code