docs: strip build history, fix drift, add missing pages

[pbWise]

Full audit of docs/, then the fixes. The docs were still shaped like a pre-release design corpus — docs-first, "the implementation was built from these" — while the product is a published 2.0 library. Every finding below follows from that mismatch.

Correctness

Was	Now
42 of 62 pages said Stable — 1.0; npm has 2.0.0	Banners carry no version at all — only package/peer facts or a real caveat. Version lives in README + index.md
reference/cli.md documented createAgentRuntime({ policies: [...] })	ADR-016 deleted that key; AgentRuntimeOptions takes only governance
index.md cited "ADR-001…012"	They run to 017
FAQ still asked "When is v0.1?" and answered "waiting on scope registration"	Replaced with the 1.x → 2.0 upgrade question
Package trees listed 5 packages	7 — postgres and cli were documented lower on the same page
"ESM-first with CJS compatibility left to the build tool"	ADR-012 §9 says ESM-only, no CJS ships
Every command in the dev-setup block failed	Wrong package name, no such scripts, no SQLite anywhere in that example
contributing/documentation.md capped citations at ADR ≤ 012, Q ≤ 11	The checklist had itself gone stale; now enforced by CI
v0.1 meaning "today" across 12 pages	Present tense — a reader can't tell whether "v0.1 has no rewrite mechanism" means then or now
13 dead #anchors, most pre-existing	vitepress build validates link targets but not fragments. Em-dash headings emit ids like scope-—-discovery-shaping-…; six pages had guessed the GitHub-style slug

History and internal notes leave docs/

brief, milestones, plan-0.2, plan-1.1 → docs-internal/, unpublished. ~700 lines of imperative instructions to a build that finished, sitting in the published sidebar above the user docs. Also removed: the contributing/governance.md stub (duplicated appendix/governance), and process framing like "these documents are the source of truth the implementation was built from" and "per the review protocol".

Structure

• Nav split into Guides / Patterns / Releases / Contributing; duplicate governance entry gone, FAQ/glossary no longer listed twice
• index.md 120 → 73 lines — the "Documentation map" was re-listing the sidebar
• One home per fact: the warnings-flag argument, the defineGovernance rationale, scope vs filter, and the audit-vs-tracing table each lost their duplicates
• ADR-015/016/017 compressed to the house format (016: 1453 → 1180 words, vs ADR-004's 137). Cut the three-paragraph defence of deleting a boolean flag and ADR-017's argument with a planning doc

New pages

• migration/1-to-2.md — the gap that mattered most. A major shipped with a documented breaking change whose migration lived in an ADR consequences paragraph
• guides/troubleshooting.md — indexed by what you saw. Startup failures quote the actual strings from registry.ts and meta-validate.ts
• guides/ci-drift-gate.md — task-first CLI setup; the reference page specified it but never taught it
• reference/performance.md — measured against the compiled packages, not asserted:

	ms/op
call() — oRPC directly	0.004
runtime.invoke — no policies, no audit	0.070
runtime.invoke — 3 policies + audit sink	0.071

~65 µs of overhead, and policies plus a sink add nothing measurable. describe at 300 capabilities: 3.03 ms; scoped to a 50-capability tag group: 0.62 ms.

getting-started also gained a step that runs invoke directly and shows the failure envelope — the page previously claimed "the model can now call orders_search" with nothing verifiable before it.

Gates, so this can't recur

• check:docs now fails on a version string in a status banner, and on any SI-n/ADR-nnn/Tn/Qn/stage citation above what its owning page defines — read from the source pages, so the caps can't go stale like the hand-written ones did
• check:anchors (new) reads ids back out of the rendered HTML rather than reimplementing the slugifier. In CI after docs:build

Source change

Two registry validation messages said "in v0.1" — user-facing strings, so they carry a changeset.

---

Green: 366 tests · check:docs · check:api · check:boundaries · check:capabilities · check:anchors · typecheck · docs:build

61 pages / 6,309 lines, from 62 / 6,698 — despite ~390 lines of genuinely new content.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
orpc-agent-docs	Ready	Preview	Aug 1, 2026 2:07pm