Oshun Documentation Center — Proposal

Date: 2026-06-26 Scope: V1–V9 product lines + shared platform; the vdocs HTML reader (tools/render-vdocs.py, vdocs-index.html) and the repo-wide documentation surface (docs/, WALKTHROUGH/, V*/, libs/, apps/). Status: Proposal Author: Claude (Opus 4.8)

Executive Summary#

The repository already contains an enormous documentation surface — ~7,498 Markdown files, 72 ADRs, 25+ runbooks, 29 compliance docs, 58 user-journey walkthroughs, 28 OpenAPI specs, 24 contract index files, across 9 product lines (V1–V9) and 2,556 Nx projects — but the HTML reader at vdocs-index.html exposes only a 12-card sliver (V1–V6 × features/architecture).

This proposal turns that reader into a complete documentation center: a single, generated, never-stale front door to the entire system, organized so that any stakeholder can drill from "what is this product" down to "this exact function, contract, and test" without leaving the center.

It also explicitly redesigns the reader itself. V1 of the center is not allowed to be only a larger index on the old visual shell: it must ship a dark-mode only, beautiful, minimalist, ergonomic UI/UX for reading, searching, browsing, and drilling through the system. The target is a quiet technical atlas: high-readability typography, dense but calm navigation, keyboard-first search, restrained visual hierarchy, accessible focus states, mobile reading comfort, and no decorative chrome that does not help orientation or comprehension. There is no light theme and no theme toggle in scope; dark mode is the product surface, not an alternate skin.

The same explicitness applies to user journeys and E2E coverage. Every committed journey, flow, walkthrough, result, and evidence artifact under WALKTHROUGH/ is a first-class docs-center object: thoroughly documented, searchable, linked to the product surface it exercises, connected to its automation/test source where one exists, and folded into the coverage report. The center is incomplete if WALKTHROUGH/ remains a side archive instead of a canonical, navigable map of how users actually move through the products.

The core idea is a mental-model inversion: instead of rendering a hand-picked list of monoliths, treat the repository as the source of truth and make the center a generated projection of it, sliced along four orthogonal axes (spaces — products, domains, and platform — plus disciplines, stakeholder lenses, and system layers), with a strict five-level granularity model (Landscape → Space → Component → Module → Code & Contract) so every part of every system reaches total, code-linked depth.

Two of the hardest enablers already exist and are reused unchanged: a deterministic generator with a CI freshness gate, and a client-side global search index. The center is largely registry + structure + generated reference layered on top of those.

Scope: the understanding/reference surface, made total#

This center is deliberately one thing, done completely: the understanding/reference surface — everything needed to comprehend the product, its features, its user journeys, and its technical systems to total, code-linked depth, for every stakeholder, across V1–V9. The goal is not breadth across company functions; it is exhaustive depth and completeness within that surface — nothing about how any part of any system works is missing, shallow, or stale.

Explicitly out of scope (by choice): business/strategy, monetization and unit economics, finance, go-to-market, company-level decision logs, and AI/agent business operations. Those are a different system and are not part of these docs. The success criterion here is total comprehensiveness of the technical + product + journey reference — measured and enforced (§11), not aspirational.

Consolidation principle: every applicable documentation surface should come under the docs center's manifest, generator, freshness gate, search index, and coverage report. Some Markdown should physically move into a canonical docs-center source layout; some code-adjacent Markdown should remain beside the code for maintainability. Either way, there is only one docs-center record for a page, one generated reader surface, and one governing check suite. Legacy paths survive only as compatibility entry points, redirects, or rich overview stubs while consumers migrate — not as competing documentation systems.

Table of Contents#

1. The mental-model shift
2. Grounding: what already exists
3. Stakeholders and their jobs-to-be-done
4. Top-level information architecture
5. Spaces: products, domains, and platform
6. The content model — doc types and templates
7. The total-granular-depth model
8. Discoverability at scale
9. Keeping it complete and never-stale
10. Build approach: roll our own
11. Definition of "complete"
12. Phased rollout
13. Risks and open questions

1. The mental-model shift#

Today tools/render-vdocs.py renders 12 hand-picked monolith documents. A documentation center inverts that:

• The repository is the source of truth. The center is a generated, never-stale projection of everything in it.
• Generate the scaffolding; author the understanding. Mechanical structure that must track code — the enumeration of endpoints, schema fields, entities, dependencies, cross-links, indexes, and the freshness/coverage reports — is generated, because hand-maintaining it across 2,556 projects guarantees rot. But everything a reader needs to understand — the explanation, the rationale, the "why it works this way," the worked examples, the edge cases, the narrative that connects the facts — is authored, in full, well-written prose. Generation removes toil; it never stands in for writing.
• The same canonical page is reached many ways. Spaces, disciplines, stakeholder lenses, and system layers are views over one set of pages, never duplicated content.

The center is sliced four ways:

2. Grounding: what already exists#

A survey of the repo (2026-06-26) establishes that the center is mostly a surfacing and structuring problem, not a write-everything-from-scratch problem:

The existing docs/ taxonomy (adr, api, audits, compliance, conventions, domains, guides, infrastructure, integrations, launch, migration, operations, performance, proposals, reference, releases, research, runbooks, security, testing, training, …) is already a discipline taxonomy; the center adopts it rather than reinventing it.

WALKTHROUGH/ is treated with the same seriousness as code and product docs, not as a loose evidence dump. Each journey/flow is imported into the manifest, classified by product, surface, actor, role lens, discipline, and system layer, and rendered as a canonical page that explains the scenario, prerequisites, steps, expected states, edge cases, assertions, automation status, result history, and links to the features, systems, tests, and evidence it covers. Result artifacts become supporting evidence pages or attachments, never orphaned files.

The repo also already has a separate, enforced domain source-of-truth surface: DOMAINS/<domain>/{features,architecture,specifications}.md, rendered by tools/render-domain-docs.py and checked by pnpm domains:check (scripts/docs/verify-domains-source-of-truth.mjs). The docs center must consolidate that surface, not duplicate it. The target state is one docs-center-owned domain registry, one generated domain reader, and one freshness/coverage report that owns the checks currently split across tools/render-domain-docs.py, pnpm docs:html:check, and pnpm domains:check. During migration, DOMAINS/ and docs/domains/ remain compatibility entry points with redirect/overview stubs where needed, but they stop being independent canonical sources once their records are imported into the docs-center manifest.

The quantities above are a 2026-06-26 snapshot, shown to size the work — and they are exactly the kind of hand-maintained count this proposal argues will rot. So the center does not keep them by hand: the meta/coverage report (§9, §11) regenerates them from the live repo and --checks them in CI, and this table itself becomes a generated artifact. Treat the figures here as indicative; the generated report is the source of truth.

3. Stakeholders and their jobs-to-be-done#

The audience model drives the IA. Every canonical page is tagged with audience, discipline, layer, and space; lenses are saved filters, not copies.

4. Top-level information architecture#

docs-center/
├── index            ← portal: search, "start here by role", product grid, what's-new
├── start-here/      ← role lenses: pm · engineer · sre · security · data · partner · creator · exec · new-hire
├── products/        ← the 9 shipping product lines, each a full product space (§5)
│   ├── v1-oshun/    (contemplative platform)    v6-egbe/    (agentic companions)
│   ├── v2-fighting/ (UE5 competitive fighter)   v7-mawu/
│   ├── v3-metaverse/(embodied multi-user world) v8-ariadne/ (self-authoring detective)
│   ├── v4-tactical/ (tactical action universe)  v9-metis/   (curious ape's guide)
│   └── v5-openworld/(open-world narrative)
├── domains/         ← generated browse view over the consolidated domain
│   │                  registry imported from DOMAINS/, docs/domains/, and the
│   │                  code graph. Major ones get a full space (§5); the rest are
│   │                  entity nodes. Several are larger than a product (Kalika 96,
│   │                  Neith 71, Yemaya 60, Bellona 40, Maya 35 sub-packages).
│   ├── maya/ (real-time engine) · neith/ (inverse modeling) · yemaya/ (rendering)
│   ├── hathor/ (worldbuilding) · bellona/ (build & engine bridge) · kalika/ (scientific computing)
│   └── sophia/ · iris/ · lilith/ · isis/ · themis/ · saraswati/ · … (platform domains)
├── platform/        ← shared foundations every product & domain builds on:
│                      libs/shared, libs/oshun, libs/contracts, BFF, persistence, auth
├── disciplines/     ← cross-cutting views; the list mirrors the §6 content types
│   ├── architecture/      system landscapes, C4 maps, every subsystem
│   ├── features/          product-shaped capability catalog
│   ├── journeys/          all E2E/user journeys + per-surface walkthroughs
│   ├── api-and-contracts/ generated from openapi + Zod
│   ├── data-events/       data models, migrations, the event/message catalog
│   ├── config-deps/       env/flags/config + dependency registry & graph
│   ├── integration/       boundary contracts, lifecycles, state machines
│   ├── operations/        runbooks, SLO/DR, deploy, on-call, observability
│   ├── performance/       latency/perf budgets, benchmarks
│   ├── security-privacy/  threat models, DSAR, residency, controls, audits
│   ├── compliance/        compliance, crypto-regulatory, child-safety (as-built)
│   ├── testing-qa/        coverage maps, journey matrix, eval gates, error catalog
│   ├── design-a11y-i18n/  tokens, components, accessibility, localization
│   ├── engine/            UE: modules, plugins, build graph, automation (V2–V8)
│   ├── release-launch/    readiness, go/no-go, changelogs, migration/deprecation
│   ├── develop/           how-to-work-on-X guides, conventions, repo map
│   └── decisions/         the 72 ADRs (technical), indexed + cross-linked
├── systems/         ← the entity catalog (knowledge graph, §7): every domain,
│                      substrate, service, lib, app, contract, UE module —
│                      one canonical, code-linked node each
├── journeys/        ← the WALKTHROUGH journey/flow registry, result evidence,
│                      and per-surface walkthroughs
├── reference/       ← glossary / ubiquitous language, repo map, dependency
│                      registries, conventions
└── meta/            ← how the docs center works, coverage report, freshness
                       report, contribution guide

Two orthogonal entry styles, same canonical pages underneath:

• "I know the product / system" → products/v4-tactical/… or domains/maya/…
• "I know my discipline/role" → disciplines/security-privacy/… or start-here/sre

5. Spaces: products, domains, and platform#

The V1 decomposition already shipped (a slim hub + ~80 focused, code-grounded pages, with a sidebar navigator, prev/next, breadcrumbs, and command-palette search) is the template. Every version gets the same skeleton, generated from its V*/features.md + V*_ARCHITECTURE.md plus its rich subtrees. (V3 alone already ships api, runbooks, security, regions, privacy, help-center, creator-docs, qa, operations, ….)

products/v3-metaverse/
├── overview              ← promise, audience, "the system in one page", status
├── architecture/         ← hub + decomposed pages (high-level → subsystem deep-dives)
├── features/             ← hub + decomposed capability pages
├── journeys/             ← end-to-end user paths + per-surface walkthroughs
├── domains-&-systems/    ← per-subsystem nodes, each drilling to code (§7)
├── api-&-contracts/      ← V3/api + generated API + contract/schema reference
├── data-&-events/        ← data model, migrations, event/message catalog, state machines
├── integration-&-config/ ← boundary contracts, env vars, feature flags, dependency registry
├── design-a11y-i18n/     ← design system, accessibility, localization/locale catalog
├── performance-&-obs/    ← latency/perf budgets, benchmarks, instrumentation
├── operations/           ← V3/runbooks, V3/operations, SLO/DR
├── security-privacy/     ← V3/security, V3/privacy, V3/regions (residency), threat model
├── creator-&-help/       ← V3/creator-docs, V3/help-center, V3/public-web
├── release-&-changelog/  ← V3/release, V3/launch, readiness, changelog, migration/deprecation
├── testing-&-qa/         ← V3/qa, V3/validation, coverage map, eval gates
├── engine/ (UE only)     ← V3/ue: modules, plugins, build graph, automation, asset/cook pipeline
├── develop/              ← how to work on V3: local dev, build/test/run, conventions
├── diagrams/             ← C4, ERD, sequence (generated where possible)
└── backlog & exit        ← V3/TODOS, exit criteria (linked, not duplicated)

Applying this turns the 12-card index into 9 deep product spaces that surface everything V*/ already contains, fully searchable.

The same skeleton applies to three kinds of space, not just products — this closes the gap between "9 products" and "thousands of entity nodes" while obeying the no-duplication rule: every system has exactly one canonical home, referenced from everywhere else, never re-documented.

1. Products — the 9 shipping lines (V1–V9). A product space documents what is specific to it (its surfaces, composition, journeys) and references the shared domains it composes rather than copying them.
2. Capability / engine / substrate domains — the shared systems products are built from. A domain gets its own canonical space when it is used across products (Maya engine → V2–V8; Yemaya/Bellona/Hathor/Neith → Studio; the Sophia/Iris/Psyche substrates) or is a large standalone system; several are larger than a product. A domain used by only one product lives inside that product space. Of the 47 top-level domain libs, the cross-product/large ones become domain spaces, the product-specific ones live in their product, and the small remainder are entity nodes.
3. Platform — the shared foundations every product and domain builds on (libs/shared, libs/oshun, libs/contracts, the BFF, persistence, auth), documented once and referenced everywhere.

The full-space-vs-entity-node threshold (governed, so the coverage gate can enforce it): a system earns a full space if it is cross-product, a multi-package domain, owns its own architecture/feature docs or backlog/proposal, or exceeds a sub-package/size threshold; everything else is a single entity node in systems/ (§7). Either way it has exactly one canonical home and is code-linked — the threshold only decides depth of treatment, never whether it is documented.

Not every space fills every section (V9 has no UE engine today; a pure-logic domain has no design system), but the skeleton is identical so a reader always knows where a kind of knowledge lives, and the coverage gate (§11) flags the sections a space is expected to have but doesn't.

Expected sections are derived from tracked repo structure, not hand-written exceptions. For engine coverage, the rule is simple: if a product has a tracked V*/ue directory, its product space must include the Engine section. Today that means V2–V8 require Engine coverage; V9 is the current no-UE example.

6. The content model — doc types and templates#

Completeness comes from having a defined page type for every kind of knowledge, each with a template so nothing is shallow. The set below is the full reference surface — if a part of any system cannot be described by one of these types, that is a gap in the model, not a thing left undocumented.

Product & experience

System & technical

Cross-cutting & meta

Governing rule — generate the skeleton, never the understanding. A "generated" page above is a scaffold that demands prose, not a finished page. Generation is used only for what must stay mechanically in lockstep with code: enumerations (endpoints, schema fields, entities, dependencies), indexes, cross-links/backlinks, and the freshness/coverage reports. Only a handful of types are generated end to end because they carry no understanding to convey — the coverage/health report, the search index, and link/backlink maps. Everywhere else, generation produces the factual scaffold and a human-quality author (person or agent) writes the understanding on top of it — and is never sparing with the pen: wherever a competent technical writer would motivate a system, explain how and why it works, walk a flow, surface the non-obvious, or give an example, the author does exactly that, fully and well. The shipped V1 pages are the standard — richly written, code-grounded, complete — not stubs dressed up by a generator. The anti-shallow gate (§11) enforces this: a page that is only generated facts where explanation is warranted is flagged as incomplete.

Prose quality is non-negotiable — no schedule or gate may erode it. None of the completeness machinery in this proposal — the coverage gate, the staged enforcement ramp, the graded score (§11), the phased rollout (§12) — exists to trade depth for speed, and none may be read that way. They schedule, measure, and assign the writing; they never excuse writing less of it or writing it less well. An author (person or agent) is expected to spend the time a subject deserves — to research the system, read the code, walk the flows, and write comprehensive, well-structured, genuinely explanatory prose to the V1 standard. "There was a deadline" or "the gate already passed" is never a reason to ship a thin page. When thoroughness and a date collide, prose quality wins and the schedule moves, not the other way around.

Separately, every entity must resolve through all the technical types above that apply to it (a domain has feature + design + API + data + events + config + tests + journeys; a UE module has engine + build + automation), so depth is uniform, not patchy.

7. The total-granular-depth model#

Adopt a strict, consistent five-level drill-down (C4 + code) so every part of every system reaches total depth and lands on real code:

L1 Landscape   All products, domains, and platform on one map
   └─ L2 Space (product / domain)   e.g. V1 Oshun, or the Maya engine: its containers
        └─ L3 System / Component   e.g. Veritas: adapter, cascade worker, contracts, routes
             └─ L4 Module / Unit   e.g. retraction-cascade: the worker, the event, the gate
                  └─ L5 Code & Contract   real path + symbol + Zod schema + test + ADR
                       libs/oshun/veritas-cascade-worker/src/… · VeritasContracts · spec

The enabler is a systems/ entity catalog — one canonical node per domain, substrate, service, lib, app, UE module, and contract — auto-built from the tracked Nx project graph (the ~2,556 committed project.json files, read via nx graph / git ls-files, never a raw filesystem walk — so untracked working-tree leftovers, such as a stale directory left behind by a rename, can never surface a phantom node) joined with the contracts and OpenAPI. Each entity node carries:

• purpose, owner, layer, package name;
• real source path (clickable file:line);
• public API (generated);
• contracts it owns; events it emits / consumes; services it calls;
• docs that mention it (backlinks);
• tests and ADRs;
• an honest implemented / spec-only / provider-gated status (the no-stub signal the repo already enforces).

These nodes are what make the center complete: there is no part of the system without an addressable, code-linked page, and a reader can travel product → feature → architecture → subsystem → module → exact file and back, from anywhere.

8. Discoverability at scale#

• Global command-palette search (already built) — extend the index to cover all 9 products + every entity node + ADRs + runbooks, with type / version / audience facets ("only V4 runbooks," "only security pages").
• Faceted browse — every page tagged space · discipline · layer · audience · status; the portal pivots on any facet.
• Knowledge-graph backlinks — "what links here," "where is this implemented," "who depends on this," derived from the project graph + cross-references; entity nodes are the graph hubs.
• Stable deep-links — anchor preservation (already a principle) so any heading is linkable; entity nodes carry permanent IDs.
• "You are here" everywhere — breadcrumb (product / discipline / layer / page) + prev/next reading order (already built for V1).

Reader UI/UX redesign#

The center must include a first-class redesign of the generated reader, not just more generated pages. The visual thesis is a dark-mode-only minimalist technical atlas: quiet near-black surfaces, rigorous spacing, strong typography, restrained color, and a small number of persistent orientation controls. It should feel like a tool that experts can live in all day — calm, dense, fast, and beautifully made without turning the documentation into marketing chrome.

Design requirements:

• The docs center is dark mode only. It must not ship a light theme, theme toggle, or half-supported alternate palette. All components, diagrams, generated tables, code blocks, search overlays, status labels, and empty states are designed and verified against the same dark system.
• The palette must be meticulous and restrained: near-black foundations, readable foreground contrast, one primary accent for action/focus, semantic status colors only where they carry meaning, and no generic purple/blue gradient wash.
• Typography must carry the interface: generous article leading, clear heading scale, readable code blocks, compact metadata, and no viewport-scaled type.
• Spacing and alignment must be deliberate at every density: article pages, entity nodes, generated reference tables, side navigation, command palette, and mobile drawers should look designed, not merely styled.
• Visual quality is a gate. Representative screenshots should be reviewed for polish, hierarchy, overlap, long-title handling, table legibility, contrast, and coherent empty/loading/error states before P0 is considered complete.

Required reader states:

• Portal / index — product and domain entry points, role starts, what's-new, global search, and facet pivots in one scannable first screen.
• Space hub — the product/domain/platform overview with expected sections, coverage status, reading order, and the highest-value next links.
• Article reader — a comfortable reading column, sticky local table of contents, left navigation, breadcrumbs, prev/next, copy-link anchors, and visible implemented/spec-only/provider-gated status.
• Entity node — compact purpose, owner, layer, source path, public API, contracts, events, dependencies, backlinks, tests, and related ADRs.
• Search and facets — keyboard-first command palette, typed result groups, saved filters, empty states, and fast refinement without losing context.

Ergonomic requirements:

• Keyboard paths must cover open search, move through results, apply facets, jump to headings, copy deep links, and return to the previous context.
• Navigation must support both browsing and focused reading: collapsible global navigation, persistent "you are here," predictable backtracking, and no layout shift when search results, status labels, or long titles appear.
• Mobile must be a first-class reader, with a stable drawer model for global navigation, local table of contents, search, and facets.
• Accessibility is part of the design, not a cleanup pass: visible focus, contrast, skip links, semantic headings/landmarks, reduced-motion support, and screen-reader names for icon-only controls.
• Motion should be restrained and useful: palette open/close, facet drawer transitions, local-navigation state, and anchor/heading reveals. It should improve orientation, never decorate routine reading.

The redesign is complete only when representative portal, space, article, entity, search, facet, and mobile flows pass Playwright coverage with screenshot checks for non-overlap, stable layout, keyboard operation, accessibility smoke coverage, and file:///static-host loading. If P0 expands the corpus but leaves the reader feeling like the old 12-card index, P0 is not done.

9. Keeping it complete and never-stale#

The freshness gate already shipped generalizes into the governing principle of the whole center:

1. Generate the factual scaffold from code — the API endpoint/schema enumeration from OpenAPI, the schema-field list from Zod, the entity catalog from the project graph, the ADR index from docs/adr, coverage/health from the file system. Generation keeps the facts in lockstep with code; the explanation on top is authored (§6). Regenerate and --check in CI (already done for the committed V-doc HTML set via .github/workflows/vdocs-html-fresh.yml; scale it to the whole center).
2. Coverage gates (the completeness counterpart to the freshness gate) land in layers, so the early phases can block what they actually own without pretending the full entity catalog exists yet. P0 blocks freshness, generated-index determinism, broken links among rendered docs, dead source paths, facet vocabulary errors, and file:// / static-load regressions for the expanded front door. P2 adds the entity/reference structural gate: CI fails if any project.json / lib / public route / contract has no entity node, or any entity node points at a path that no longer exists. Both gates run nx affected-scoped per PR where possible — only entities touched by the change are re-derived and diffed, so the gate stays fast on a ~2,556-project graph rather than re-walking the whole tree on every push. Enforcement is staged, never lax (§11): cheap structural checks block as soon as their artifact exists, while the depth checks block space-by-space as each space is authored to the V1 standard — the bar is fixed; only the set of spaces it is enforced over grows. This makes "complete" measurable and enforced, not aspirational.
3. Honesty status carried through — the implemented / spec-only / provider-gated labeling stays first-class, so the center never over-claims (matching the repo's no-stub culture).
4. Authored prose stays in the repo as Markdown next to the code, rendered by the pipeline — one source, two outputs (GitHub + the center).
5. Existing docs are consolidated under docs-center governance, and any canonical-home migration is link-preserving. The center imports docs/, DOMAINS/, docs/domains/, WALKTHROUGH/, per-version subtrees, and code-adjacent READMEs into one manifest. A doc may remain physically next to code when that is the right maintenance model, or move into a canonical docs-center source location when it is a standalone reference page, but it must have exactly one canonical docs-center record and one generated reader entry. When prose moves, the source keeps a stable page/entity ID, the old path leaves a rich redirect/overview stub, inbound links are rewritten or covered by generated redirects, and the link checker must prove both old and new entry points resolve. This preserves current consumers — the 72 ADRs, runbook links, and inbound references keep resolving — while retiring duplicate generation surfaces instead of preserving them forever.

10. Build approach: roll our own#

Decision: build the documentation center on our own generator — the bespoke render-vdocs.py, extended — rather than adopt a third-party docs framework (Docusaurus, Astro Starlight, mkdocs, or any other). This is the right call today and the bar for revisiting it is deliberately high, but it is a reasoned engineering choice, not a vow: we would reconsider only on a concrete trigger (enumerated at the end of this section). Whatever capability the center needs in the meantime, we build it ourselves on a pipeline we fully control. Why this is the right call here, not a compromise:

• file:// zero-server reading already works (no build server, no hosting required), and the search index is engineered for that constraint.
• The deterministic-render + freshness-gate is the single most valuable property here and it is already built and proven. It is bespoke by nature; an off-the-shelf framework would not give us this, and bolting it onto one would cost more than owning the whole pipeline.
• The decomposition, navigator, and palette patterns already exist and apply unchanged.
• Owning the generator means every behaviour is ours to shape exactly — no plugin ecosystem to wait on, no upstream breaking changes, no theme we have to fight.

What to add to the generator:

• a doc registry / manifest covering all 9 products plus the existing docs/, DOMAINS/, docs/domains/, WALKTHROUGH/, and per-version subtrees (not 12 hardcoded files);
• a repo-wide consolidation importer that classifies each existing doc as move-to-docs-center, keep-beside-code-but-register, generated-reference, or compatibility stub;
• a WALKTHROUGH / E2E journey importer that creates canonical journey and flow records from every committed walkthrough, result, and evidence artifact, then maps each record to product, surface, actor, role lens, test/automation path, result history, screenshots/logs where present, and the systems it exercises;
• an entity-catalog generator (project graph → nodes);
• reference generators (OpenAPI / Zod → API & schema pages);
• facet tagging + a faceted index;
• stakeholder landing pages;
• a dark-mode-only, minimalist, ergonomic reader shell redesign covering the portal, space hubs, article reader, entity nodes, search/facet UI, mobile navigation, accessible focus states, visual polish QA, and restrained orientation motion;
• UI/search verification for the generated portal: Playwright checks for file:// or static-host loading, command-palette search, facet filtering, representative deep links, mobile layout, accessibility, keyboard navigation, screenshot-backed layout stability, and search-index size/performance budgets;
• the coverage gate.

The "advanced" capabilities are ours to build too — not, on their own, a reason to switch. If the center later needs hosting, per-audience permissioning, version pinning, or interactive "try-it" API calls, each is a contained addition to our own pipeline, not a migration:

• Hosting — the generator already emits a static site; serving it is a static host or an internal route, not a framework change.
• Permissioning — emit per-audience builds (the facet tags already exist) or gate at the serving layer; either is a small generator/serving change we own.
• Versioning — the product spaces are already version-scoped; pinning is a manifest concern under our control.
• Interactivity — drop in our own small web components against the same generated index/contract data; no third-party runtime or build required.

Adopting a framework today would only force us to re-implement the freshness and coverage gates — the part that actually matters — inside someone else's build. Rolling our own keeps those gates first-class and the entire surface under our control.

When we would revisit. The decision is reopened — not before — if a concrete trigger appears: external or community contributors who need a familiar authoring toolchain; a hard requirement for hosted, access-controlled, multi-tenant serving that genuinely outgrows a static host; or interactive features (live API "try-it," versioned API explorers) that would cost more to hand-build than to adopt. Even then the test is narrow: any replacement must carry the deterministic-render freshness gate and the coverage gate as first-class properties, because those — not the theme or the navigation chrome — are what the center is actually made of. Absent such a trigger, we do not switch; and the trigger is a real, named requirement, never a vague "wouldn't it be nicer."

11. Definition of "complete"#

"Complete" means the reference surface (§Scope) is exhaustive — not that some doc exists per area, but that every applicable reference type exists for every part. A generated, CI-gated meta/coverage report asserts:

Structural coverage

• every space — each product (V1–V9), each full-space capability domain, and the platform — has all standard sections present (or an explicit, justified "n/a", e.g. no engine for V9 while V2–V8 require one because V*/ue exists);
• every Nx project / lib / app / UE module has either a full space or an entity node, and every project above the full-space threshold (§5) has a space;
• every public route (BFF + OpenAPI) and every contract is referenced.
• every committed WALKTHROUGH/ journey, user flow, walkthrough result, and evidence artifact has a canonical docs-center record, and every record links back to its source path.

Journey and E2E coverage — for every documented user journey, user flow, and E2E walkthrough:

• the page identifies product, surface, actor, audience/role lens, prerequisites, test data or fixtures, starting state, step-by-step path, expected UI/system states, assertions, edge cases, and exit criteria;
• automation-backed flows link to the real E2E/test source, command or harness where applicable, latest result/evidence, and any screenshots, logs, traces, or result artifacts stored under WALKTHROUGH/;
• manual or partially automated flows are labeled honestly and carry the same expected-state and evidence requirements, with the automation gap visible in the coverage report;
• every product surface and important user-facing workflow has at least one linked journey/flow or an explicit, justified "n/a";
• no walkthrough result can be orphaned: each result maps to the journey/flow it verifies, the product/surface it covers, and the systems/entities exercised by the path.

Per-dimension depth (the anti-shallowness gate) — for every domain / substrate / service:

• a feature spec, a system-design page, and ≥1 subsystem deep-dive;
• API/contract, data/schema, event, and configuration reference resolved;
• every public symbol in its API surface appears in the generated reference;
• every env var / feature flag it reads has a configuration entry;
• every event it emits/consumes is in the event catalog;
• its lifecycle/state machines, error/failure modes, and integration boundaries are documented;
• at least one journey, its E2E/user-flow record, and its testing/coverage map link to it where that system participates in a user-facing or operator-facing path;
• UE modules additionally resolve engine + build-graph + automation pages.

Drill-down integrity — every L1→L5 path (§7) terminates at a real file:line, and every entity links down to its modules and up to its product.

Hygiene & honesty

• zero broken links, zero stale renders, zero orphaned entity paths;

• every entity carries an honest implemented / spec-only / gated status;

• the reader UI passes its ergonomic and visual-quality gates: dark-mode-only palette coverage, no incoherent overlap at desktop or mobile viewports, readable typography, stable navigation dimensions, keyboard-operable search and facets, accessible focus and contrast, and responsive article/entity layouts that keep status, links, and long titles legible;

• no shallow pages. Any page whose type warrants explanation but carries only generated facts — a schema dump with no prose, an entity node with no "what / why / how it fits," an API list with no usage narrative — is flagged as incomplete, the same way the repo's no-stub culture flags hollow code. Meeting the bar means human-quality writing: oriented, motivated, exampled, and readable, to the standard of the shipped V1 pages — not merely "a page exists."

  How this is detected, honestly. "Human-quality prose" cannot be measured mechanically, and the gate does not pretend otherwise. It computes a proxy from signals that are necessary-but-not-sufficient for depth — the ratio of authored prose to generated tables, the presence of the sections a page type requires ("what / why / how it fits," at least one worked example or flow where the type calls for it, motivation that is more than a restated title), and outbound links to the code and neighbours the page discusses — and an advisory LLM reviewer may additionally score a page against a depth rubric. These signals only ever flag suspects; they never certify quality and never auto-pass a page. The real bar is held by a human (or agent) reviewer against the V1 standard — exactly as code review, not a linter, is the real bar for code. The proxy is deliberately tuned to err toward flagging (better to mark a good page for a second look than to wave through a thin one), so it can only ever prompt more writing, never license less.

When that report is green, the center provably covers every part of every system at every level — the concrete, enforced meaning of "complete and total granular depth."

A graded score, so progress is visible — but 100% is the only "done." Because green across ~2,556 entities is a long road, the coverage report does not reduce to a single pass/fail: it publishes a per-space and per-dimension completeness score (what fraction of expected pages exist, and of those, how many clear the depth proxy), so the team can see exactly where authoring stands and assign the gaps. This grading is a worklist and a progress meter, never a lowered bar: a partial score is an explicit statement of unfinished work, not a grade of "good enough." A space is done only when its score reaches 100% and its prose meets the V1 standard; until then the score names precisely what is left to write. The graded view exists so thoroughness can be scheduled and tracked — never so it can be skipped.

12. Phased rollout#

The dominant cost is authoring, and it is sequenced, not compressed. The generated scaffolding (P0, P2) is days-to-weeks of engineering; the authored understanding across every space and entity is the real, large, ongoing investment, and the honest expectation is that it lands space-by-space over time, not in one sweep. P1 is therefore not a single milestone but a rolling program: each space is taken to full V1-standard depth, and only then does the depth gate begin enforcing over it (§9, §11). This is deliberate — it ships the structural value immediately while protecting the one thing that must not be rushed, the writing. The graded score (§11) is how the program is tracked: it makes the remaining authoring visible and assignable without ever implying a thinner page is acceptable. No phase, deadline, or gate state is grounds for thinning prose (§6); if depth and a date collide, the date moves.

Two natural first steps to choose between:

• Start with P0 — generalize the generator's registry to ingest all 9 products + docs/ + DOMAINS/ + docs/domains/ + WALKTHROUGH/ + per-version subtrees + code-adjacent READMEs; build the walkthrough importer and journey/result traceability report; and ship a redesigned portal index plus reader shell with the product grid + discipline/role browse axes, so the real shape is visible and pleasant to use before committing to the deeper phases.
• Start with the entity catalog (part of P2) — prototype the project-graph → entity-node generator first, since it is the spine everything else hangs from.

13. Risks and open questions#

• Scale of generation. 2,556 projects → thousands of entity nodes. The generator must stay deterministic and fast; incremental rendering and a size/perf budget for the search index will matter. (Mitigation: the --check/coverage gates keep correctness; perf is an engineering budget.)
• Authored-content gaps — the dominant cost. Generation surfaces that a part exists and where its code is; it cannot invent the narrative "why." Subsystem deep-dives still need authoring, and across ~2,556 entities that is a large, ongoing program, not a one-time pass. The coverage gate's graded per-space score (§11) makes the gaps visible and assignable, and the staged-enforcement ramp (§9) ships structural value while the writing proceeds space-by-space. The non-negotiable from §6 holds throughout: the gaps are closed by writing well and taking the time it needs — never by lowering the bar to make the score move.
• Reconciling the shipped V1 pages with the one-canonical-home rule. The V1 product space already documents shared substrates (Sophia, Iris, Psyche, Lilith, Isis) in depth inside V1/architecture and V1/features. Under the rule in §5, a cross-product substrate's canonical home is its domains/ space, which V1 then references. So a P1 task is to decide, per substrate, whether it is genuinely V1-specific (its prose stays in V1) or shared (its deep prose is promoted to domains/<x>/ and V1's pages become rich, linked overviews). This is a link-preserving canonical-home migration, not a rewrite: the promoted page keeps a stable entity/page ID, the old V1 path leaves a redirect or rich overview stub, inbound links are rewritten or redirected, and the link checker must prove both old and new entry points resolve. It must preserve, not thin, the existing depth (the V1 substrate prose is some of the best in the repo; the migration relocates it intact and leaves a rich, linked overview behind, never a thinner page). The sequencing matters: until the migration is done, those substrates have two homes, and the coverage gate treats that as a warning, not a merge-block, so the one space that is actually finished is never penalised for being early. The duplicate is surfaced and assigned — it must not be silently tolerated — but blocking enforcement turns on only once the canonical home exists, the staged-enforcement rule from §9 applied to this specific case.
• Consolidating legacy doc roots and renderers. The repo currently has multiple real documentation surfaces and generators: vdocs, DOMAINS/, docs/domains/, WALKTHROUGH/, per-version trees, and code-adjacent READMEs. The center must not create one more system beside them. P0/P1 therefore import each applicable surface into one docs-center manifest, classify each source as move, register-in-place, generated reference, or compatibility stub, and fold tools/render-domain-docs.py plus pnpm domains:check into the docs-center generator/check suite. During the transition, old paths and package scripts may remain as wrappers or redirect/overview entry points; the done state is one generated reader, one search index, one freshness gate, and one coverage/improvement report.
• Hosting vs file://. The bespoke route optimizes for local/file:// reading. If a hosted, access-controlled portal becomes a requirement, we build it on our own pipeline (§10) — a serving/permissioning layer over the same generated output, not a framework migration.
• Taxonomy drift. Facets (space/audience/discipline/layer/status) must be a small, governed vocabulary or browse degrades. (Mitigation: enumerate facet values in the manifest; lint unknown tags.)
• Ownership. "Complete" is only durable if entity nodes have owners and the coverage gate is enforced. Ownership is derived, not hand-maintained: seeded from CODEOWNERS where present, package.json authors/maintainers, and git-blame / git log on each entity's source as the fallback, then recorded per node and surfaced in the coverage report so unowned, under-documented, or stale-owner areas are visible and assignable. Without an owner a flagged gap has no one to write it — so owner-derivation ships with the coverage gate (P4), not after.

This is a proposal, not an implementation. The recommended first move is P0 (unify the front door over existing material) or the entity-catalog prototype (the spine of the granular-depth model); either can be built on the existing render-vdocs.py pipeline without disrupting the shipped V-doc readers.