[futurepaul]

docs/api.md is now the wire contract alone: each route and method, who may call it, its shapes, statuses and error codes, and its limits by constant name.

Removed: narrative of how the cell does each thing; history and status notes; the Configuration table (cell/src/config.rs documents each variable); test-lever ops (levers.rs, ops.rs); the shell's look and behaviour (cell/shell/); computers' behaviour (docs/computers.md owns it); the export archive's layout (its README); the MCP mapping (cli/src/mcp.rs); examples, and the permission table cli/GUIDE.md carries.

Kept, tersely, including what landed since 10-30: an agent's role (agentRole), the session archive (sessions), a fragment's search (#783), embeddings, an org's ledger and budget, org content and its governance log, the payer, hosted doors (/api/f/{name}/door, __door, job.door) and connector ids, and secrets in a job's fetch URL (#805). The __live protocol, the browser library's surface, the stylesheet's variables and the shell's postMessage table stay, since app authors and framed pages rely on them.

Corrected against the code:

• No connector template ships yet: blessed::CONNECTORS is empty (crates/templates/src/blessed.rs).
• A bound hosted door may publish relayed records (cell/src/doors.rs, effects::check_record).
• The computer's door route takes any connector's id: malformed is 400, one the deployment doesn't allow is 403 (cell/src/runs_on.rs).
• Sessions fragments can't claim a public address either (cell/src/address.rs).
• The shell's message table gains session-archive, which the code sends and the doc lacked.

References: code comments that cited removed sections now point at what survives, or drop the pointer: cell/shell/apps-page.js, cell/shell/launcher.js, cell/src/levers.rs, cell/src/ops.rs, crates/core/src/levers.rs, e2e shell.rs and sync.rs, crates/proto/src/computer.rs, crates/templates/src/lib.rs. Two other docs get one-line fixes: docs/chat-records.md (three pointers) and docs/billing.md (one). The dead link to docs/fragment-boats.md is gone.

file	before	after
docs/api.md	3,988	1,852

cargo xtask check passes, including the doc-phrase tests (the_contract_names_the_step_limit, the_docs_name_the_templates_create_takes).

Decision for Paul:

• Should the shell's postMessage protocol become a shared code module instead of a doc table? It just grew a message (session-archive).

🤖 Generated with Claude Code

[alexlwn123]

Pass at 8719de7645bc716d4056dd4297cf420bb652287b.

This cuts the API document to its client-facing contract and points implementation details back to their owners. The source edits are comments only. I checked the corrections for connector IDs, hosted-door relayed records, session archives, public addresses, and shell messages against the implementation; I found no blocking regression. The large deletion is appropriate to the stated purpose and adds no implementation machinery.

Validation: both focused documentation tests passed (the_contract_names_the_step_limit, the_docs_name_the_templates_create_takes), as did git diff --check. CI check and images check are green; e2e shards and real-Hermes Docker checks are still running. I did not run the full suite locally. The engineering-style document referenced by AGENTS.md was unavailable at its specified path.

[alexlwn123]

Pass at b8aa86a1c187b259883f251c173f50b7a8b54a86.

The earlier head was approved with no blockers. This rereview covers the merge of master and the added inbox-secret contract: the declared header replaces token admission, an unset secret refuses delivery, and template users cannot override the template's inbox declaration. The documentation matches the implementation. The PR remains documentation and source-comment changes relative to its base; no new implementation machinery or blocking regression found.

Validation: the_contract_names_the_step_limit, the_docs_name_the_templates_create_takes, and an_inbox_reads_a_secret_from_a_header passed on this head, as did git diff --check. CI check, images check, and real-Hermes Docker checks were still running when inspected; the PR's e2e job passes through with shards skipped under the current workflow. Full suite not run locally. The engineering-style document referenced by AGENTS.md is unavailable at its specified path.

[alexlwn123]

Pass at 9441912d9dfee72e4838d370d1fbca46ae25135a.

The previous head was approved with no blockers. This rereview covers the master merge and its one-line addition to the shortened API contract: PUT __secrets/{KEY}. The documented editor admission, JSON requirement, shared API body/response, and write-only behavior match serve.rs and members.rs; the event records the secret's name, never its value. The PR remains documentation and source-comment changes against its base, with no added implementation machinery or blocking regression found.

Validation: the_contract_names_the_step_limit, the_docs_name_the_templates_create_takes, and git diff --check passed on this head. CI check, images check, and real-Hermes Docker checks were still pending when inspected; e2e passes with shards skipped. Full suite not run locally. The engineering-style document referenced by AGENTS.md remains unavailable at its specified path.

[alexlwn123]

Pass at 513f36224bd91bdc45481ed02ded3ecfc88c761d.

The previous head was approved with no blockers. This rereview covers the two subsequent master merges: the shortened API document is unchanged from that approved head, billing.md now matches the base, and the merged test-lever changes remain owned by the implementation as intended. The PR delta remains documentation and source comments only. No blocking regression found; the reduction adds no implementation machinery.

Validation: the_contract_names_the_step_limit, the_docs_name_the_templates_create_takes, and git diff --check passed on this head. CI check, images check, and real-Hermes Docker checks were pending when inspected; e2e passes with shards skipped. Full suite not run locally. The engineering-style document referenced by AGENTS.md remains unavailable at its specified path.

[alexlwn123]

Pass at c3c7bf2032dca1454dc349692b6c3001bb52ee54.

The previous head was approved with no blockers. This rereview covers the subsequent master merge: docs/api.md is unchanged from that approved head, its admin rows retain no canary reference, and docs/chat-records.md now matches the base. The PR remains documentation and source-comment changes only. No blocking regression found; the reduction adds no implementation machinery.

Non-blocking: the merge restored three stale pointers in docs/chat-records.md: “The shell, Search” (line 387), “The launcher” (line 685), and “The first run, in its chat” (line 691). Point search to Control API / Search, and the launcher and first-run descriptions to their implementation or surviving shell contract.

Validation: the_contract_names_the_step_limit, the_docs_name_the_templates_create_takes, and git diff --check passed on this head. Images check is green; CI check and real-Hermes Docker checks were still running when inspected; e2e passes with shards skipped. Full suite not run locally. The engineering-style document referenced by AGENTS.md remains unavailable at its specified path.