# 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](#1-the-mental-model-shift) 2. [Grounding: what already exists](#2-grounding-what-already-exists) 3. [Stakeholders and their jobs-to-be-done](#3-stakeholders-and-their-jobs-to-be-done) 4. [Top-level information architecture](#4-top-level-information-architecture) 5. [Spaces: products, domains, and platform](#5-spaces-products-domains-and-platform) 6. [The content model — doc types and templates](#6-the-content-model--doc-types-and-templates) 7. [The total-granular-depth model](#7-the-total-granular-depth-model) 8. [Discoverability at scale](#8-discoverability-at-scale) 9. [Keeping it complete and never-stale](#9-keeping-it-complete-and-never-stale) 10. [Build approach: roll our own](#10-build-approach-roll-our-own) 11. [Definition of "complete"](#11-definition-of-complete) 12. [Phased rollout](#12-phased-rollout) 13. [Risks and open questions](#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: | Axis | Meaning | Example entry | | -------------------- | ------------------------------------------------------------------ | ----------------------------------------------------------------------------------------- | | **Space** | a mini-site per product, domain, or platform | V1 Oshun · Maya engine · shared platform | | **Discipline** | cross-product concern | Architecture · Features · API · Operations · Security · Testing · Design · Data · Release | | **Stakeholder lens** | curated "start here" path that filters + sequences canonical pages | PM · Engineer · SRE · Security · Data · Partner · Creator · Exec · New-hire | | **System layer** | vertical drill-down | Surfaces → Domains → Substrates → Foundations → Infra → Engine | --- ## 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: | Source | Quantity | Disposition in the center | | ---------------------------------------------------------------------- | --------- | ----------------------------------------------------------------------------------------- | | Markdown files (repo-wide) | ~7,498 | rendered / indexed where canonical | | Nx projects (`project.json`) | 2,556 | one generated **entity node** each | | Product lines (V1–V9) | 9 | each → a full **product space** (§5) | | `V*/features.md` + `V*_ARCHITECTURE.md` | 9 × 2 | hub + decomposed pages (V1 pattern) | | Capability / engine domains (`libs/*`) | 47 | shared/large → **domain space** (§5); product-specific → its product; small → entity node | | Shared platform foundations (`libs/shared`, `oshun`, `contracts`, BFF) | — | one **platform space** (§5) | | ADRs (`docs/adr`) | 72 | indexed, cross-linked decision register | | Runbooks (`docs/runbooks` + `V*/runbooks`) | 25+ | Operations discipline | | Compliance docs (`docs/compliance`) | 29 | Compliance/Legal discipline | | Reference docs (`docs/reference`) | 27 | Reference section | | Training docs (`docs/training`) | 20 | New-hire / role lenses | | Proposals (`docs/proposals`) | 18 | Decisions / proposals | | Integration guides (`docs/integrations`) | 13 | Partner lens | | OpenAPI specs (`libs/openapi`) | 28 | **generated** API reference | | Contract index files (`libs/contracts/src/*/index.ts`) | 24 | **generated** schema reference | | Per-lib `README.md` | ~107 | entity-node seed content | | `DOMAINS/` domain docs | 54 dirs | imported into the docs-center domain registry; legacy paths become compatibility entries | | `docs/domains/` domain docs | 28 dirs | imported / reconciled as domain supporting docs, not a separate source of truth | | WALKTHROUGH journeys | 58 | canonical journey / flow pages linked to products, surfaces, tests, and systems | | WALKTHROUGH results | 82 | verification evidence / audit trail linked back to each exercised journey | | UE projects (`V*/ue`) | 7 (V2–V8) | per-product **Engine** section | | Top-level `docs/` taxonomy | 24 areas | maps directly onto **Disciplines** | 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//{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 `--check`s 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. | Stakeholder | Primary jobs | What they need | | ------------------------------------------- | ------------------------ | -------------------------------------------------------------------------------------------------------------- | | **Product / PM** | scope, decide, track | feature specs, product promise, exit criteria, journeys, roadmap, release notes | | **Engineer (TS / Rust / UE)** | build, change safely | architecture → subsystem → module → **code path + contract**; sequence flows; "how to work on X"; ADRs | | **QA / Test** | verify | test/coverage maps, journey matrices, eval gates, golden sets, verified-vs-attested status | | **DevOps / SRE** | run, recover | runbooks, SLO/DR, deploy/rollback, infra diagrams, dashboards, on-call | | **Security / Privacy / Legal / Compliance** | gate, attest | threat models, DSAR/residency/consent, control mappings, audit ledgers, crypto-regulatory review, child-safety | | **Data / Analytics** | instrument, measure | event taxonomy, KPI definitions, schema reference, experiment registry | | **Live-ops / Operators** | operate the product/game | operator surfaces, content authoring, moderation, economy/balance, live-service calendars | | **Partners / Tenants / Institutions** | integrate, administer | tenant admin, SSO/SCIM, API keys/webhooks, public API reference, integration guides | | **Creators / Modders** | extend | creator docs, SDKs, asset pipelines, templates | | **Exec / Investor** | understand at altitude | product promise, system landscape, launch readiness, risk register, one-page-per-version | | **Support** | help users | help-center / KB, journeys, troubleshooting, status | | **New hire** | onboard | glossary, "the system in 30 minutes," start-here-by-role, repo map | --- ## 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** | Type | Answers | Authored / **Generated** | | ------------------------- | ------------------------------------------------------------------------------- | -------------------------------- | | Product overview | what / who / why / status | authored | | Feature spec | what it does, surfaces, states, edge cases, copy | authored | | Journey / walkthrough | end-to-end user path, step by step | authored | | E2E journey / flow record | actor, preconditions, steps, assertions, result evidence, automation/test links | authored + **generated** | | Surface / screen | each UI surface: layout, states, entry points | authored | | Design-system reference | tokens, components, variants, usage | authored + **token-generated** | | Accessibility reference | a11y requirements + as-built status per surface | authored | | Localization reference | locale catalog, RTL, translation coverage | **generated** from i18n catalogs | | Generation/content tiers | who can generate/see what; surface boundaries | authored | **System & technical** | Type | Answers | Authored / **Generated** | | -------------------------------- | ----------------------------------------------------------------------- | -------------------------------------------- | | System design | how it's built, C4 L1–L2, flows | authored | | **Subsystem deep-dive** | module-level responsibilities, data, events, failure modes, code paths | authored, **code-linked** | | **Entity node** | one card per domain / substrate / service / lib / contract / UE module | **generated** from project graph | | **API / contract reference** | endpoints, schemas, errors, examples | **generated** from `libs/openapi` + Zod | | **Data / schema reference** | per-domain DB tables, contract shapes, migrations, residency | **generated** from contracts + migrations | | **Event / message catalog** | bus topics, payload schemas, producers/consumers | **generated** + authored | | State machine / lifecycle | the lifecycles (editorial, AgentRun, DSAR, cascades) with states/guards | authored + mermaid | | Sequence / flow | request lifecycle, cascades, hand-offs | authored + mermaid | | **Integration / boundary** | how systems connect (BFF↔domain↔substrate, channels, engine bridges) | authored, **code-linked** | | **Configuration reference** | env vars, feature flags, config surfaces, secret schema (not values) | **generated** from config + `.env.example` | | **Dependency registry & graph** | external SDKs/services + internal who-depends-on-whom | **generated** from manifests + project graph | | **Error / failure catalog** | error codes, failure modes, degradation behavior per subsystem | **generated** + authored | | Performance reference | latency/perf budgets, benchmarks, load characteristics | authored + **benchmark-fed** | | Observability reference | what's instrumented: metrics, traces, logs, dashboards | authored + **generated** | | Security & compliance (as-built) | threat model, DSAR, residency, controls, attestations | authored | | **Engine (UE) reference** | modules, plugins, build graph, automation specs, cook/asset pipeline | authored, **code/buildgraph-linked** | | Runbook | detect → diagnose → remediate | authored | | **ADR** | decision, context, consequences | **indexed** from `docs/adr` | **Cross-cutting & meta** | Type | Answers | Authored / **Generated** | | ----------------------------------- | ---------------------------------------------------------------------------------- | ------------------------------------ | | Developer guide ("work on X") | local dev, build/test/run, conventions, contribution | authored | | Diagram set (C4 / ERD / seq) | system maps, entity-relationship, sequence diagrams | authored + **generated** | | Testing / coverage map | what's tested, eval gates, golden sets, walkthrough evidence, verified-vs-attested | **generated** + authored | | Release / launch | readiness, go/no-go, changelog | authored + **gate-status generated** | | Changelog / migration / deprecation | what changed, how to migrate, what's deprecated | authored + **generated** | | Glossary term | ubiquitous-language definition + where used | authored + backlinks generated | | Role guide | "start here as X" (reference lens, see §3) | authored, links canonical pages | | **Coverage / health** | what's documented, stale, or orphaned (§11) | **generated** | **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 | Phase | Deliverable | Why first / value | | ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **P0 — Unify the front door** | Bring all 9 products into the index (today V1–V6); import every applicable existing doc surface (`docs/`, `DOMAINS/`, `docs/domains/`, `WALKTHROUGH/`, per-version subtrees, code-adjacent READMEs) into the docs-center manifest; convert every `WALKTHROUGH/` journey, user flow, result, and evidence artifact into canonical, thoroughly documented docs-center records with product/surface/test/evidence traceability; redesign the generated reader into a dark-mode-only, beautiful, minimalist, ergonomic UI for the portal, space hubs, article reader, entity nodes, search/facets, and mobile navigation; add the four browse axes, role lenses, and the first structural gates: freshness, generated-index determinism, rendered-doc links, source paths, walkthrough/result traceability, facet vocabulary, static-load, accessibility, layout-stability screenshots, keyboard navigation, dark-palette coverage, visual-polish review, and search UI automation | Highest value per effort — surfaces ~7,498 existing docs plus the full E2E/user-journey evidence trail in a usable, polished front door and blocks regressions in content discovery, journey coverage, and reader ergonomics | | **P1 — Decompose all versions + consolidate domains** | Apply the V1 hub+pages pattern to V2–V9, fold `DOMAINS/` + `docs/domains/` into canonical docs-center domain IDs, retire the standalone domain reader/checker behind docs-center wrappers, and give the major capability domains their own spaces, so every space is deep, not a monolith | Makes every product and domain space navigable and granular without duplicate domain systems | | **P2 — Generated reference** | Entity catalog from the project graph; API reference from OpenAPI; schema reference from contracts | Where "total granular depth" actually arrives | | **P3 — Cross-cutting + lenses** | Discipline views, stakeholder start-here paths, faceted search, knowledge-graph backlinks | Serves all stakeholders explicitly | | **P4 — Depth and ownership gates** | Depth proxy, graded completeness score, owner derivation, and honesty-status rollups in CI, alongside the P0/P2 structural gates | Makes completeness durable and enforced — without ever licensing a thin page | **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//` 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._