Documentation audit — 7 October 2026
The documentation has substantial useful material, but its size and mixed evidence make it difficult to choose an explanation and know when to rely on it. The first repair is a coherent reading and evidence layer: short entry points, preserved source editions, exact section addresses, a shared graph and visible qualification limits.
This audit covers every document structurally and reconciles the two supplied sources, navigation and documentation-assistant claims. It does not establish that every runtime claim is current or that every example compiles. Those require checks against the relevant source and target, recorded as evidence.
Scope and measured findings
The measurement snapshot contained 161 public documents, including the generated home page, and 47 private documents. Public text measured approximately 936,000 words, including deliberate source preservation. The measurement revision was 1d52274a186965e425dc4af83686973712c9662cb613b64ad7a59aa5fac76282; this audit page and later classification repairs were added afterward. The current per-document audit is regenerated with each edition.
The snapshot reported 125 pages without a current verification receipt, 41 long-document review signals, 58 architecture/design pages without a detected inline or image diagram, and 15 guide/module/architecture pages without a fenced sample. These are review signals, not scores. A text fence may contain a table or diagram rather than executable code; an image may lack sufficient architectural explanation. The corpus has no page-wide implemented or qualified declarations backed by the new receipt contract yet.
The structural repair resolved 204 repeated authored heading addresses while keeping each first address. Both corpora now pass the document and anchor checks. Twenty repeated prose blocks still need contextual comparison; another 201 were identified as intentional reuse within preserved source editions. The latter should retain source lineage rather than be deleted to improve a duplication score.
Assessment against the requested criteria
| Criterion | Finding | Change or next acceptance test |
|---|---|---|
| Freshness | Edit dates, dated surveys and current implementation claims were easily confused. | Status, content revision, source date and verification are now separate. Explicit plans are marked design; the supplied FlexBuffers first edition is marked historical and pinned to its source hash. Verify remaining current claims against a source revision. |
| Quality | The overview, task guides, design books and implementation reports serve different reader needs. | The library gives each reader a starting path. Review a task guide by completing its intended task and comparing the result with its stated limits. |
| Redundancy | Source editions deliberately overlap; old Shadow/performance drafts repeat merged material. Module review and execution plan also share context. | Preserve the archive and source hashes. Keep module review for assessment and execution plan for tasks; link shared context. Compare claims before merging explanations. |
| Organisation | A very long home-page catalogue competed with the sidebar and interactive library. | Start here is first and follows a deliberate reading order. Other groups collapse. Subject summaries open shareable filtered library views; old routes remain available. |
| HLD diagrams | The latest report's diagrams and inspection notes were isolated from the ordinary documentation. | All 50 atlas diagrams and 242 inspection notes are incorporated with surrounding prose and machine-readable diagram text. Each subsystem still needs a clear context, component, interaction or deployment view where that explains its boundary. |
| Streamlining | Readers repeatedly encountered whole-book links and large introductions. | Search opens exact sections; the graph inspector exposes all section addresses. Manna can read, question or export a selected section. Use shared prerequisites instead of repeating setup in future task guides. |
| Language | Multiple meanings of graph, capability, source, generation and authority need their context preserved. Sentence-length signals alone cannot judge that prose. | The atlas vocabulary is indexed, and source caveats remain near the material. Review terms against their canonical definitions before simplifying a conditional statement. |
| Bloat | The desktop master plan exceeds 41,000 words; the UI audit exceeds 30,000. Large reference works can be useful but are poor entry points. | The home page was reduced from about 6,700 words to 1,320 in this snapshot. Keep deep registers and dated reviews as reference; write short task-oriented entry points and link the relevant section. |
| Connectivity | Duplicate addresses weakened citations; ordinary references did not express prerequisites or lineage. | Heading repairs and inline-HTML anchor recognition close the structural findings. Typed requires, explains, derived-from, implements and supersedes relations are available beside references. Add them only when the relationship is justified. |
| Code samples | A fenced block or proposed API can look like a supported example. | Preserve language and source text, expose the document's evidence status, and record target/result receipts for runnable samples. Do not treat preprint listings or mathematical text as an implementation test. |
| Vision | The September roadmap, October synthesis and implementation surveys answer different questions. | The roadmap owns direction and proposed dates; the October atlas owns its design synthesis; current module guides own their implementation claims. Link a proposal to its acceptance evidence instead of copying its vision into every guide. |
| Industry and theoretical precedents | The preprint's citations, conditional propositions and finite constructed studies need their original scope. | References, notation, exercises and appendices are incorporated. Current product/API comparisons need primary-source refreshes; historical citations retain their dates. The missing finite-model and coverage-map companions cannot be claimed as reproduced. |
Canonical roles and editorial order
| Material | Role in the library | Review priority |
|---|---|---|
| Framework overview and contributing | Explain the model and complete a first contribution | First: check source paths, build tasks and the worked outcome. Use the current website contribution contract. |
| Module guides and current data/operations maps | Explain today's API and platform boundary | Next: qualify current claims and runnable examples. A recently edited guide still needs a receipt. |
| Graph, Surface and workbench design families | Explain different layers of one system | Reconcile names and authority boundaries; choose a short entry point for each layer and retain detailed reference. |
| September engine book and October architecture atlas | Preserve the complete technical sources and their design scope | Keep exact lineage and section citations. Use the original web page layouts when mathematical typography needs checking. |
| Roadmaps, task registers and master plans | Describe proposed delivery and acceptance | Link tasks to qualifying evidence and keep schedules explicitly proposed. |
| Superseded plans and original audits | Explain how a decision was reached | Preserve as history; link the current explanation. Avoid promoting historical source claims through search. |
The maintained website now has full-text section search, area/status/type filters, shareable filter URLs, an interactive Blueprint graph, a section inspector, collapsible navigation and a revisioned corpus for retrieval systems. The separate docs assistant is removed. Manna provides the reader, scoped questions with numbered context, and queued reading-PDF export.
The next website improvements are synonym/semantic retrieval with explained results; graph neighbourhoods and prerequisite paths; saved reading position and graph views; qualified executable example sandboxes; and an editorial dashboard with accountable maintainers, review dates and evidence tasks. Connecting private documents to Manna requires a qualified identity and permission bridge; the public integration does not bypass existing private access controls.
Rechecking the work
Use the library programme for the source coverage maps and reading contract. npm run nav:check, npm run test:corpus and npm run corpus reproduce structural checks in the docs project. The public and authenticated website builds remain separate. Manna's documentation tests exercise scope admission, revision changes, source packets, workspace isolation, figures and PDF storage; cloud rendering and browser journeys require runtime verification in addition to those tests.
The architecture report contributes all 55 panels and all 18 prose chapters. The engine preprint contributes all 45 outlined units; every one of its 114 pages is also preserved as a web vector image with extracted text. The original attached PDF is therefore unnecessary for accessing its content. Source preservation is complete; further editorial simplification and implementation qualification remain distinct work.
Retirement candidates
The source inventory records the current public edition; the authenticated audit includes private documents. Retirement requires preserving unique laws, acceptance criteria and evidence, updating incoming section links, and providing redirects for published addresses. The following are recommendations; no documents are deleted.
| Whole-document candidate | Canonical destination | Condition before retirement |
|---|---|---|
| Codex Roadmap, Strategic Roadmap, Implementation Plan | Module execution plan, workbench layers, and Astra master plan | All three are marked superseded. Carry over any unfinished acceptance criteria and preserve the dated prototype-to-product decisions. Replace old current-state/completion tables with current evidence links. |
| Claude Dev Environment, Codex Dev Environment | Shadow foundations, workspaces, capture/replay, verification | Compare capsule, isolation, privacy, retention and failure contracts section by section. Remove obsolete staging recipes and permanent-pinning proposals only after the current guides state the surviving policy. |
| Prototype architecture analysis | WorkBench layers, current UX audit, module execution plan | Preserve any unique entity/inspector coverage requirements. The old prototype inventory and prioritized delivery list can then retire with a dated archive record. |
| Graph migration plan | Graph theory, graph language, workbench layers | Preserve unresolved polyglot binding, source/runtime identity and shared-state requirements. Prototype ScenarioContext inventories, file maps and sprint schedules can retire after current task ownership is linked. |
Sections that can be removed or replaced
| Document and section | Disposition | Material to retain |
|---|---|---|
| Implementation Plan: inventory and schedule; Strategic Roadmap: current state and module completion tables | Replace with links to current source/evidence and one delivery register. | Original snapshot date and unique acceptance criteria. Old labels such as complete or production-ready must not imply current qualification. |
| Codex Roadmap: code-level analysis and implementation phases | Remove repeated gap descriptions after the corresponding current module task is identified. | Any gap or failure requirement that the current plan does not yet carry. |
| Graph migration: state decomposition, migration file map, sprint plan | Retire obsolete prototype file inventories and schedules. | State ownership, lifetime, common Kotlin/target binding and migration acceptance rules. |
| Shadow design history: early MVP recipes, repeated tool comparisons and deployment walkthroughs | Replace repeated setup and comparisons with current Shadow/Operations links; retain the history as a source edition until semantic coverage is complete. | Capture fidelity, privacy, isolation, failure-capsule and acceptance contracts. The shorter current chapters do not yet duplicate the entire book. |
| Performance design history: repeated profiler inventories and old operating walkthroughs | Link to profiling, instance diagnostics, load/resilience and current performance scope. | Distinct benchmark methodology, budgets and failure requirements. Retire the whole history only after these are covered. |
| Nodes, Ports and Hyperedges: mandatory-class interpretations and generic provider/binding/consumer miniatures | Replace with task designs and classification. Retain source IDs and published type anchors. | Behavioral laws and domain mappings. H34 access/lineage is a legacy composite; use H23 for authority and H27 for provenance. |
| Repeated introductory vision, lifecycle, authority and setup paragraphs in master plans and module guides | Keep the canonical explanation and link to its exact section. | Local differences, counterexamples, algorithms, constraints and target qualification. Exact textual duplication alone is not enough to merge distinct claims. |
| Engine preprint facsimile navigation and repeated OCR text | Optional removal from the default reading/search path after the text edition and section coverage are checked. | Complete notation, listings, references, appendices, source hashes and mathematical source images where needed. The text edition remains available without the attached PDF. |
Material to preserve
Keep the complete engine text edition, architecture source qualification, combined architecture atlas, and unique foundation/source audits. The engine implementation report is cited by the preprint; removing its route would break source lineage unless a dated source record and section redirects replace it. Original critical reviews contain different arguments and are not automatically duplicates.
Private copies require a separate comparison and private destination for any unique material. A public document is not a permissible destination merely because most paragraphs match. The source inventory and retirement conditions apply equally to agent/RAG retrieval: retired content needs an explicit status and canonical destination rather than disappearing behind a broken citation.
Anchor and example contract
Headings carry explicit stable anchors. Worked designs use contextual addresses such as mobile-community-logic instead of numbering repeated generic headings. Renamed published addresses remain aliases; incoming references and graph-port anchors use the canonical address. Type IDs N01–N40, P01–P24 and H01–H36 remain stable.
Task diagrams declare their nodes, named ports, contracts and relation roles in Markdown. Their browser scenes, portable figures and machine-readable definitions derive from those declarations. The renderer is the shared Atlas view. Structural tests preserve every incidence and check concrete boundaries including transaction/outbox scope, navigation return paths, independent acknowledgements, stream credits and migration fencing.