Agent-facing docs state four numbers the code disproves, and root AGENTS.md predates the output-schema change its first recipe depends on

[serge-ivo]

Four numbers in the agent-facing docs are wrong against the code, and root AGENTS.md predates a contract change its own first recipe depends on

All verified against source 2026-08-15. pnpm docs:drift passes all 13 checks with these present — see the companion guard-gap issue.

Hard errors

location	says	actual
workers/mcp/AGENTS.md:15	"18 of the 124 registrations are gated"	19 of 136 (tool-count.ts: MCP_TOOL_COUNT = 136, MCP_TOOL_ALWAYS_ON = 117)
workers/mcp/CLAUDE.md:83	"31 in index.ts … 13 in storage-tools.ts, and 88 across instance-tools/"	31 + 13 + 92 = 136. The doc's own arithmetic gives 132 and never reaches its own headline
workers/mcp/CLAUDE.md:87,96	"86 instance tools", present tense	86 is historical. contract.test.ts:29 uses it correctly as history ("while 67 of the 86 … lived in one 1871-line file")
workers/mcp/CLAUDE.md:228	"server.json and platform-docs/mcp.md restate it and docs:drift fails when any of the three disagree"	Four statements. The omitted one is store/.well-known/mcp-server.json
README.md:416	biome "packages workers/mcp: the two trees", listing workers/api ~234, store/** ~54, agents/coder 1 as blocked	ci.yml runs packages workers store agents/coder; its own comment says "Every tree is now in." All three landed 2026-08-07

CLAUDE.md:228 is the sharpest: the statement it omits is the one #573's first pass already missed once — scripts/lib/wire-surface.mjs:285 exists precisely because of that miss. The doc reproduces the original bug in prose.

Root AGENTS.md — stale by omission, and standing on a changed contract

Last commit 2026-06-22. Nothing in it is false: every rule, tool name and both flows were traced and still behave as described; dry_run, the exact-confirm rule and mcp_audit_log are all correct. For a two-month-old contract that is a better result than expected.

The problem is what it cannot tell a caller, and one item is a contract change it sits directly on top of: its first recipe opens with list_agents, whose payload is now {"agents":[…]} and no longer a bare array (tool-metadata.ts:344, same for my_instances). A consumer following this file literally breaks.

Also absent, all verified present in code:

• tool annotations readOnlyHint/destructiveHint (tool-metadata.ts:98) — these make its own rule "prefer read-only tools" mechanically answerable instead of a judgement call
• the server instructions block sent on initialize (index.ts:45)
• RUN_HEALTH_STATES — four members incl. ended (work-report.ts:93), and ended is the common answer since runHealth() returns it for any status !== "running"
• lastAliveAt (heartbeat) vs lastProgressAt (instruction advance) as different facts; runHealth deliberately reads liveness only (work-report.ts:179)
• TOOL_TIERS — four (builtin-tool-policy.ts:57); TOOL_REACHES — three, failing closed at internet (tool-reach.ts:71)

The verdict field lists omit the two fields that answer the questions

workers/mcp/AGENTS.md:62 lists (allowed, scope, disabled, reason, tier, invocableBy); workers/mcp/README.md:~340 lists (allowed, scope, disabled, reason). Both omit mutates and reach.

Neither recommends connector as the reach proxy — that specific wrong advice was removed by #585 and is genuinely gone. But naming scope while omitting mutates leaves the same wrong inference available, and tool-registry.ts:149 says outright that mutates is the field that answers it.

Already correct — leave alone

• workers/mcp/README.md's tool table: 136 rows, exact match against registration per the gate; the coding_timeline row is present and accurate.
• workers/mcp/AGENTS.md rule 3, "this server does not set isError": still true. registration.ts:114-116 attaches structuredContent: {error: …} rather than letting the SDK's validateToolOutput rejection fire, closing the one path that could produce it.
• SECURITY.md:38's write-consent gate. Missing (additions, not corrections): the mutates/scope distinction, fail-closed reach, the append-only surface lock (The surface lock can be rewritten in place, so a silent surface change is still shippable #576), the status-domain guard.
• README.md:331-332,358-359 correctly names the tool table and tool-count.ts as sources.

One documented behaviour narrower than the code

AGENTS.md:36 frames the runtime flow as "when local Playwright is needed". The flow and register_instance_runtime exist and work, but the transport is now the unconditional WebSocket relay and the runner serves coding engines as well as browsers. Narrower framing, not a false claim.

Acceptance criteria

1. All five numeric errors corrected against their cited source.
2. Root AGENTS.md states the {"agents":[…]} / {"instances":[…]} payload shape — this is the one that breaks a caller.
3. Annotations, server instructions, and the mutates / reach / four-value tier and RunHealth vocabularies are documented where a calling agent will read them.
4. reach and mutates added to both verdict field lists.
5. The four security mechanisms added to SECURITY.md.
6. README tool table untouched — it is exact.
7. pnpm docs:drift and docs:build green. Baseline is green today, so any red is yours.

Verified vs inferred

• Verified: every file:line; the per-file .tool( counts; the four-way version statement set from the gate's own output; ci.yml's biome invocation; both flows in root AGENTS.md traced end to end.
• Inferred: nothing.

[serge-ivo]

Done in a24b5b5. CI green, MCP deploy green.

Against the acceptance criteria

1. All five numeric errors corrected. workers/mcp/AGENTS.md:15 18/124 → 19/136; CLAUDE.md 88 → 92 (the paragraph now sums to its own headline: 31 + 13 + 92 = 136); the historical 86 relabelled as history with the current 92 stated beside it; CLAUDE.md:228 three → four; README.md biome now names packages workers store agents/coder.
2. {"agents":[…]} / {"instances":[…]} stated in root AGENTS.md (new "Reading results" section) and in workers/mcp/AGENTS.md rule 3, both calling out objects, not bare arrays.
3. Annotations, server instructions, and the vocabularies are in root AGENTS.md and as new rules 13/14 in workers/mcp/AGENTS.md. Rules 1–12 keep their numbers — CLAUDE.md's gotcha cross-references "rule 3" by name, so renumbering would have broken it.
4. mutates + reach added to both verdict field lists, each with the reason the obvious inference is wrong.
5. SECURITY.md gained the write-consent gate, the mutates/scope distinction, fail-closed reach, the append-only surface lock and the status-domain guard.
6. README tool table untouched — still 136 rows, exact match per the gate. Only the list_instance_tools Purpose cell changed; no row added, removed, or renamed, and no Scope/Dry/Confirm cell touched.
7. docs:drift and docs:build green.

The stale number is now defended, not just correct

Worth recording, because it is the part that stops recurrence. workers/mcp/AGENTS.md was already in the swept set (docs-drift.mjs:119-120), so the miss was never coverage — the old sentence put words between the number and "are gated" and matched neither detector. Measured directly against the real parsers:

AFTER  (now)           | gated claims: [19] | toolcount claims: [136]
BEFORE (old phrasing)  | gated claims: []   | toolcount claims: []

Rephrasing into the shape the gate already reads moved its denominators: split check 10 claims / 4 files → 11 / 5, count check 5 claims → 6. So this specific line is now checked by CI rather than merely fixed once.

Verified in production

• GET https://mcp.proagentstore.online/health → {"ok":true,"service":"proagentstore-mcp","tools":136} — matches the number now documented.
• https://proagentstore.online/.well-known/mcp-server.json → "version": "0.1.4" — confirming the fourth version statement exists and is served exactly where CLAUDE.md now says it is.

Not done, deliberately

• platform-docs/**, docs/*.md, store/llms*.txt, store/.well-known/* — owned by other lanes, untouched.
• pnpm test:e2e skipped: no change under store/, agents/coder/web, or anything Playwright exercises. Everything else in ci.yml was run locally and CI has since confirmed it.
• The one narrower-than-code framing flagged in the issue (root AGENTS.md:36's "local Playwright") is corrected — it now describes the runner as serving a browser or a coding CLI over the WebSocket relay.