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

## 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 `` … 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

- [x] **Runtime core** (2) — done in #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 #3523
- `docs/architecture/runtime-core-architecture-draft.zh-CN.md` — same set as its counterpart — addressed by #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

- [x] **Multi-agent orchestration** (4) — done in #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`

- [x] ~~**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//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.

```sh
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.

Start by choosing one unchecked subsystem, then run the provided grep command over docs/ and read its listed documents alongside the current implementation. Verify symbols, storage descriptions, paths, cross-document consistency, paired translations, and last_verified; the subsystem is done when every listed document is corrected or confirmed accurate and one PR references #3522.

Written by the indexing model from the issue text.