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

[Joob1n]

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.

[Joob1n]

The runtime-core entry is addressed by #3523. The remaining three entries are open.

[Joob1n]

Multi-agent orchestration is addressed by #3555. docs/side-conversation.md was audited as part of that group and needs no change — its unresolved symbols are all inside sections that describe OpenAI Codex rather than Maka.

[Joob1n]

Runtime host: audited, no changes needed.

All four documents in this group were read against the code and are accurate as written, so there is no PR for this group.

docs/architecture/runtime-host-architecture.{md,zh-CN.md}

• All 9 paths in the reading map resolve.
• All 16 backticked identifiers in the prose resolve to real symbols.
• Named contracts match the code exactly, not by interpretation:

Document statement	Code
Two Host lifetimes: Ephemeral and Service	RuntimeHostLifecycleMode = 'ephemeral' | 'service' (server/host-kernel.ts)
A drain request must carry the Host Epoch the Client observed	HostUpgradePrepareInput.expectedHostEpoch (protocol/host-status.ts)
Interrupting active work requires an explicit Client choice	HostUpgradePrepareInput.allowInterruptActiveTasks
The Host may return bounded counts of active connections, operations and residencies	HostStatusResult.{connections, activeOperations, activeResidencies}
Invariant 8 — provider dispatch waits for the Run Composition durable commit	beforeRunProviderDispatch: commitRunComposition (server/execution-model-composition.ts)
Invariant 11 — only the Runtime Host resolves a WorkspaceTarget to a canonical Host path	server/workspace-resolver.ts, handling the host_path and project targets

Also checked against a live Host on macOS: its registration.json carries lifecycleMode: "ephemeral", state: "ready" and compositionId: "maka.interactive", and the control directory holds the owner.lock the document calls the exclusive write lease.

docs/runtime-host-remote-access.{md,zh-CN.md}

• Every maka runtime-host command in the document is still accepted by parseRuntimeHostCommand: serve, service, access, project, profile. (setup and capability-provider also exist but the document does not use them.)
• Every sub-command used resolves too: service install|status, access issue, project add|list, profile set.

Worth noting for the remaining groups: this document survived because it is written in terms of boundaries and invariants rather than file layouts, class names and default values. The runtime-core chapter drifted precisely where it had pinned those details.

[fxl112233]

I’m taking the Context and compaction documentation-audit slice only.

Plan:

• audit both llm-compaction-events-log-projection-draft.md and its zh-CN counterpart against the current Runtime and Storage implementation;
• verify every named symbol, file/test path, persistence claim, limit, and paired translation;
• correct confirmed drift, keep both documents synchronized, and update last_verified;
• run the repository documentation, formatting, and link/path checks that apply.

This PR will use Refs #3522 rather than close the tracking issue.

Automated disclosure: this claim was drafted and posted by OpenAI Codex at @fxl112233’s direction. @fxl112233 remains the human contributor of record.