docs: verify every live document against the code, one subsystem at a time #3522

Goal

Bring every live document under docs/ back in line with the code, one subsystem at a time.

The work is grouped by subsystem rather than by document because that is how the drift arrives. When a subsystem changes, several documents describe it from different angles, and they go stale together. Reviewing them as a group is also the only way to notice that two documents now contradict each other.

Each box below is one subsystem. Tick it when every document under it has been read against the current implementation and either corrected or confirmed accurate. A document that turns out to be accurate needs no change — recording that it was checked is the point.

What a pass over one subsystem covers

• Named symbols still exist: classes, methods, tool names, event types, config keys.
• Described storage matches the implementation. The migration from per-run files to SQLite invalidated file-layout diagrams in more than one place.
• Cited file paths resolve, including test paths offered as the verification route.
• Documents in the group do not contradict each other.
• Paired translations move together. translation_status: synced is the only value used across the paired documents in this repository, so updating one language alone makes that field false.
• last_verified reflects the pass.

Scope

In scope: the 61 documents listed below.

Out of scope:

• docs/archive/** (38 files). Each carries an "Archived on <date> … not current architecture authority" banner. Their historical content is correct as archived material and must not be rewritten.
• docs/eval/** (3 files). These are benchmark run records tied to a specific date and model set, not descriptions of current behaviour.

Subsystems

• Runtime core (2) — done in docs: correct stale runtime-core architecture facts #3523

  • docs/architecture/runtime-core-architecture-draft.md — PermissionEngine, respondToPermission(), the run.json/events.jsonl layout, a step limit of 50, and a deleted test path — addressed by docs: correct stale runtime-core architecture facts #3523
  • docs/architecture/runtime-core-architecture-draft.zh-CN.md — same set as its counterpart — addressed by docs: correct stale runtime-core architecture facts #3523

• Recovery and resume (7)

  • docs/architecture/runtime-recovery-resolver-adr.zh-CN.md
  • docs/architecture/runtime-resume-architecture.md
  • docs/architecture/runtime-resume-architecture.zh-CN.md
  • docs/architecture/runtime-resume-extraction-ledger.zh-CN.md
  • docs/architecture/runtime-resume-phase0-crash-contract.md
  • docs/architecture/runtime-resume-phase1-safe-boundary-contract.md
  • docs/architecture/runtime-resume-phase3-phase4-workspace-checkpoint-design.zh-CN.md

• Context and compaction (2)

  • docs/architecture/llm-compaction-events-log-projection-draft.md — cites packages/storage/src/__tests__/agent-run-store.test.ts, which does not exist
  • docs/architecture/llm-compaction-events-log-projection-draft.zh-CN.md — same citation as its counterpart

• Multi-agent orchestration (4) — done in docs: correct the multi-agent orchestration documents #3555

  • docs/architecture/agent-graph-stream-scheduling-draft.md
  • docs/architecture/agent-graph-stream-scheduling-draft.zh-CN.md
  • docs/agent-swarm.md
  • docs/side-conversation.md

• Runtime host (4) — audited 2026-08-23, no changes needed

  • docs/architecture/runtime-host-architecture.md
  • docs/architecture/runtime-host-architecture.zh-CN.md
  • docs/runtime-host-remote-access.md
  • docs/runtime-host-remote-access.zh-CN.md

• Managed workspace (5)

  • docs/architecture/runtime-managed-workspace-baseline-open-v1.zh-CN.md
  • docs/architecture/runtime-managed-workspace-execution-admission-v1.zh-CN.md
  • docs/architecture/runtime-managed-workspace-owner-v1.zh-CN.md
  • docs/architecture/runtime-workspace-version-authority-v1.zh-CN.md
  • docs/architecture/managed-dependency-storage-authority-v1.zh-CN.md

• Sandbox and privacy (4)

  • docs/architecture/windows-sandbox-rfc-v1.md
  • docs/architecture/windows-sandbox-rfc-v1.zh-CN.md
  • docs/permission-onboarding-plan.md
  • docs/workspace-privacy-context.md

• Workflow state (4)

  • docs/session-task-ledger-lifecycle.md — documents task-events.jsonl and tasks.json; state is the SQLite table workflow_task_ledger_events
  • docs/work-board-contract.md
  • docs/architecture/scheduled-task-unified.md
  • docs/deep-research-durable-workspace.md — documents sessions/<session>/deep-research/events.jsonl; state is the SQLite table workflow_deep_research_events

• Tools and capabilities (3)

  • docs/architecture/mcp-runtime-architecture-draft.zh-CN.md
  • docs/skill-catalog-policy.md
  • docs/web-search-provider-capability.md

• Computer use (9)

  • docs/computer-use-cursor-provenance.md
  • docs/computer-use-evidence-classes.md
  • docs/computer-use-foundation-contract.md
  • docs/computer-use-host-events-contract.md
  • docs/computer-use-model-loop-foundation.md
  • docs/computer-use-provenance.md
  • docs/computer-use-provider-evidence.md
  • docs/computer-use-ui-coverage.md
  • docs/codex-pip-reverse-engineering.md

• Model access (2)

  • docs/architecture/openai-responses-incremental-transport.md
  • docs/model-metadata-firstscreen-optimization.md

• Desktop and frontend (7)

  • docs/frontend-architecture-astryx-review-2026-08-09.md
  • docs/frontend-css-governance.md
  • docs/frontend-css-governance.zh-CN.md
  • docs/settings-astryx-deep-review.zh-CN.md
  • docs/astryx-alignment-inventory.md
  • docs/astryx-full-surface-audit.md
  • docs/astryx-surface-file-inventory.md

• CLI and distribution (5)

  • docs/cli-distribution.md
  • docs/cli-npm-release.md
  • docs/cli-npm-release.zh-CN.md
  • docs/windows-support.md
  • docs/windows-test-inventory.md

• Bots (1)

  • docs/architecture/bot-onboarding-runtime.zh-CN.md

• Provenance records (1)

  • docs/code-origin-audit.md

• Index (1)

  • docs/README.md

Known drift found so far

The notes above came from one sweep, not from reading all 61 documents. Anything unannotated is simply unverified, not confirmed correct.

for pat in 'run\.json' 'events\.jsonl' 'runtime-events\.jsonl' 'PermissionEngine' \
           'respondToPermission' 'agent-run-store\.test\.ts'; do
  grep -rln "$pat" docs/ | grep -v '^docs/archive/'
done

Two matches were checked and are correct as written:

• docs/architecture/mcp-runtime-architecture-draft.zh-CN.md mentions PermissionEngine only to state that no per-call PermissionEngine exists on the ordinary path.
• The resume, agent-graph, recovery-resolver and workspace-version documents mention JSONL only to contrast a legacy or degraded host with the SQLite commit sink.

Contributing

Pick one subsystem, open one PR for it, and reference this issue with Refs #3522. Please do not open a PR that spans several subsystems: the groups are sized so that a reviewer who knows that area can check the whole change.