# Docs Center — Audit & Suggestions for Improvement **Date:** 2026-06-29 **Scope:** the Oshun Documentation Center — generator (`tools/docs_center/`, ~37 modules / ~12K LOC Python), rendered output (`docs-center/**`, 228 pages), portal front door (`vdocs-index.html`), search index (`vdocs-search-index.js`), measured against `docs/proposals/DOCS_CENTER_PROPOSAL.md`. **Method:** a 12-dimension adversarial multi-agent audit — every finding was refuted-or-confirmed by an independent skeptic, then a completeness critic named blind spots and merged duplicates — plus lead-verified deterministic checks (contrast math, gate runs, parser repro). 43 findings survived verification; the headline correctness bugs were reproduced by hand and are cited with exact `file:line`. > **The central framing.** Both of the docs center's own gates are **green** > right now — freshness (`--check`: 2976 files fresh, 2643 entity nodes) and > integrity (`--verify`: 0 broken links, 0 dead source paths), and the > self-report shows every product space at "100%". So "the gates pass" tells us > nothing, and the large entity-scaffold authoring backlog is the system's own > openly-published worklist — **neither is re-litigated here.** Every finding > below is something the gates _cannot or do not_ measure, or a place where the > center's self-description out-runs reality. **The recurring shape of the > problem: the gates verify that committed output matches a re-render of source, > but almost nothing verifies that the source _parsers_ extracted the source > correctly — so wrong/incomplete data ships fully green.** --- ## Scorecard | Dimension | Grade | Headline | | ------------------------------ | -------------- | -------------------------------------------------------------------------------------------------------------------------------------- | | Content depth (where authored) | **strong** | Authored prose genuinely meets the V1 bar (V8 leaves 2.2–3.3K words); the scaffold backlog is a real queue, not a cover for thin pages | | Content accuracy / drift | adequate | Prose claims are remarkably accurate; drift is concentrated, not pervasive | | Coverage blind spots | **needs-work** | Discovery roots are narrower than the surfaces the center claims to cover | | Generator code quality | adequate | Disciplined overall; a few regex parsers silently under-enumerate, one is outright wrong | | Gate robustness | adequate | Strong link/path/facet gates, but real holes (orphan output, `#anchors`, parser output) | | Reader UX / IA | adequate | One strong shared chrome; the 2,643-node headline asset is poorly navigable in the large aggregates | | Accessibility | adequate | Strong foundation (skip-link, focus, reduced-motion); one real WCAG-AA contrast failure + a silent search palette | | Performance / scale | adequate | Lean median page, but a 1 MB render-blocking search index ships on every page | | Search quality | needs-work | Whole-query substring match — multi-word / out-of-order queries miss | | Generator testing | **needs-work** | ~12K LOC, 35 modules, **zero** Python unit tests | | Maintainability | adequate | Strong docstrings; adding a surface is a 3-place shotgun edit; the only safety net is tautological | | Honesty ledger / proposal | adequate | Mostly scrupulous; one localized over-claim about what the depth gate enforces | --- ## Top priorities (the high-leverage fixes) 1. **Validate parser _output_, not just output-matches-source.** Today nothing catches silent under-enumeration: the Yemaya API reference renders ~18 of a real **499-path / 719-operation** spec; the Prisma enum parser drops values so **91 enums render "0 values"**; the contract parser drops name-re-exported modules. All ship green. Add golden-output unit tests + a `--verify` parser-sanity pass. _(Themes A & B)_ 2. **Widen discovery, or stop claiming "every part."** Entity/reference discovery keys on tracked `project.json` and a hardcoded root `.env.example`, so ~40 Rust crates (~160K LOC), npm packages without a `project.json`, app-level OpenAPI specs, and 26+ per-service env files are structurally invisible while the report advertises "100%." _(Theme A)_ 3. **Give the generator a test suite.** ~12K LOC across 35 parser/render modules has no `test_*.py` and pytest isn't even a dependency; the freshness gate is _tautological_ for logic bugs (a wrong computation passes the moment its buggy output is committed). This is the root enabler of #1. _(Theme C)_ 4. **Make the 2,643 entity nodes navigable.** On the 1 MB aggregate pages most entities are reachable by neither the 12-item TOC nor global search — directly contradicting the §8 "every entity node is addressable" promise. One fix (`
` cards + real `

` headings) serves UX, a11y, and perf at once. _(Themes D & F)_ 5. **Defer the 1 MB search index.** It loads render-blocking at top-of-`` on all 228 pages + portal, though its only consumer is the palette on first keypress; half of it (504 KB) is secondary heading-anchor data. _(Theme E)_ --- ## What's genuinely strong (so the rest is credible) - **Where content is authored, it is deep and on-spec — not padded.** Measured: V8 leaf deep-dives 2,235–3,326 prose words; gate-enforced platform pages 1,231–3,620; 771 walkthrough "view" pages median 645 (min 356) with real source-path frontmatter. The disclosed scaffold backlog is an honest authoring queue, not thin pages dressed up. - **Deterministic by construction.** No `datetime.now` / `random` / `time.time` in the generator; sets are sorted before emit; discovery is built from `git ls-files` (not a raw FS walk), so build output and vendored checkouts can't surface phantom nodes. This is why `--check` is stable. - **An honest disclosure culture.** The depth proxy is repeatedly and correctly described as _advisory / necessary-but-not-sufficient / never certifying_; entity scaffolds are counted as a worklist, not passed off as prose; a deferred-surfaces ledger and an orphan report both exist; as-built-vs-aspirational is scrupulously labeled in prose (`@nyx/sdk` "an aspirational SDK surface", `@maat/contracts` "a scaffold, honestly labelled"). - **Disciplined code.** Zero bare `except:`; `html.escape` used consistently (no injection vector found); real responsive media queries (`@media 980px/1200px`, `min-width:0` guards); the integrity gate genuinely validates that every entity `source_dir` and journey spec exists and that page facets bind to live space slugs — so dead paths and stale facets can't ship. - **A11y foundation is real:** a verified skip-link, a high-contrast `:focus-visible` outline, a `role=dialog`/`aria-modal` palette, labeled icon controls, and a comprehensive `prefers-reduced-motion` CSS block; body text contrast is excellent (16.4:1). --- ## Findings by theme Severity: **HIGH** = ships wrong/incomplete data or breaks a core promise · **MEDIUM** = real defect, meaningful reader/maintainer impact · **LOW/NIT** = polish. Findings are grouped by root cause (per the completeness critic's merge guidance), not by audit dimension. ### Theme A — Silent under-enumeration: gates green, data wrong or incomplete **A1 · [HIGH] App-level OpenAPI specs are never discovered — the Yemaya API reference renders a small fraction of the real surface.** `apps/yemaya/api/openapi/openapi.json` defines **499 paths / 719 operations** (git-tracked), yet the rendered `docs-center/api-and-contracts/api-yemaya.html` is built from a different, much smaller bundled spec (the auditor measured ~18 operations). The reference discovery roots scan `libs/openapi` bundles + source specs but never `apps/**/openapi/`. → **Fix:** extend reference discovery to enumerate tracked `apps/**/openapi*.json` (the same instinct already applied to rescue source-only `libs/openapi/src/specs`), and add a `--verify` check that flags any large tracked OpenAPI spec with no corresponding reference page. **A2 · [HIGH] The Prisma enum-value parser silently drops values — 91 enums render "0 values" in the shipped Data reference.** `tools/docs_center/data.py:136`: `vals = re.findall(r"^\s+([A-Z][A-Z0-9_]*)\s*$", ebody, re.M)`. The `[A-Z]` start-anchor drops any lowercase/PascalCase value and the `\s*$` end-anchor drops any value carrying a trailing `@map("…")` or `//` comment. Reproduced: `veritas SourceStatus` (`active/paused/retired/pending` — all lowercase) and `bellona BuildStatus` (6 values with trailing attributes) both render **0 values**; `grep "0 values" docs-center/data/` returns **91** hits — all green. → **Fix:** broaden to `^\s*([A-Za-z][A-Za-z0-9_]*)\b` and strip trailing `@map(...)`/comments; add a golden test asserting a known enum's values render (see C2). **A3 · [MEDIUM] The contract reference drops modules re-exported by name (not `export *`).** `reference.py:39` `_REEXPORT_RE` matches only `export * from`. `libs/contracts/src/tts/index.ts:27` surfaces `./client` solely via `export { TTSProviderStatusSchema, … } from './client'`, so `contract-tts.html` shows 8 modules (the star-exports) and the `./client` module — including `OshunTTSClient` and 6 symbols — vanishes with its source link; `llm` similarly drops `./client`. `check_reference_coverage` only proves the page file exists, so the loss is invisible. → **Fix:** unify on the robust parser the repo already has in `entities.py:327-330` (`_API_EXPORT_RE` handles `abstract`/`async`/`let`/`var`; `_API_NAMED_RE` handles `export { X as Y }`), extended to capture the `from '…'` target of a named re-export and resolve it as a module. (The `export abstract/async` weakness is real but currently _latent_ for contract pages — the named-re-export drop is the observable loss today.) **A4 · [MEDIUM] The configuration reference reads only the root `.env.example`, missing 26+ per-service config surfaces incl. feature flags.** `config.py:39` hardcodes `ENV_EXAMPLE = ROOT / ".env.example"` and the docstring calls it "the platform's single authoritative configuration surface." But `git ls-files` shows 27 tracked `*.env*.example` files; `apps/oshun/bff/.env.example` alone has 23 variables absent from root — `FEATURE_FLAGS`, `AUTH_ISSUER`, `AUTH_JWKS_URL`, `CORS_ORIGINS`, `RATE_LIMIT_MAX_REQUESTS`, `OSHUN_NYX_API_BASE_URL` — and `apps/lilith/svc-ai/.env.example` adds 17 more. None are surfaced. → **Fix:** enumerate all tracked `**/.env*.example` via `git ls-files`; render each file's unique-to-it variables attributed to its owning app/service; add a `--verify` check that every tracked env-example is parsed. **A5 · [MEDIUM] Real npm packages without a `project.json` are invisible to the entity catalog _and_ silently drop their dependency-graph edges.** Entity discovery is keyed entirely on tracked `project.json` (`entities.py:382`), so a workspace package that ships only a `package.json` is absent from a catalog that advertises "Every part of the system, addressable" — and any dependency edge pointing at it is dropped from the graph with no gate noise. This is the same root cause as the missing Rust crates (H-series) — see the merge note below. > **Merge note (per critic):** A1/A5 and the missing Rust crates are **one root > cause** — discovery keyed on `project.json` — with several instances. Fixing > discovery (add `package.json`-only packages, `Cargo.toml` crates, and > `apps/**/openapi`) closes them together. **A5 is the meta-fix that makes A1–A4 > detectable: nothing validates parser _output_.** ### Theme B — Gate blind spots (things that can rot fully green) **B1 · [MEDIUM] Orphaned/stale _output_ files pass both gates forever — the literal hole in "never-stale."** `cli.py:63-65` `emit()` is one-directional: it proves every file the build _emits_ matches disk, but never that disk contains _only_ what the build emits. Delete a project or rename a page and its old rendered `.html` lingers, fully green. → **Fix:** add a reverse pass to `--check` — collect the set of emitted paths, enumerate all generated locations (`docs-center/**/*.html` + portal + index + rendered siblings), and fail on any tracked generated file not emitted this run. **B2 · [MEDIUM] "0 broken links" never validates `#fragment` anchors and never scans the search index.** `coverage.py:40-41`: `_SKIP_PREFIXES` skips `#` and `//` wholesale, and cross-page links are reduced by `target = href.split("#",1)[0]` before the file-existence check — so the fragment is never resolved. External URLs are skipped entirely. The entire TOC / permalink / deep-link / palette target set (8,731 anchors) is unverified, and a heading-id rename silently breaks every link to it. → **Fix:** when a target carries `#frag`, parse the destination page's emitted `id="…"` set and fail if absent (same-page and cross-page); add a pass asserting every search-index `h` resolves to an emitted file + anchor. Optionally a non-blocking external-link liveness report. **B3 · [MEDIUM] No gate or test validates parser output — under-enumeration ships silently.** The unifying defect behind Theme A. The freshness diff only proves output is _reproducible_, not _correct_; the depth proxy measures prose, not generated-table completeness. → **Fix:** golden-fixture tests per parser (TS/Prisma/OpenAPI/env/Build.cs/event/error) + a `--verify` sanity layer (e.g. "an `enum` block with `{…}` body must yield ≥1 value", "a discovered OpenAPI spec must yield ≥1 operation"). ### Theme C — The generator has zero automated logic tests **C1 · [HIGH] ~12K LOC across 35 modules has no Python unit test; the only safety net is tautological.** No `test_*.py`, no `conftest`, no pytest config; pytest isn't in `tools/requirements.txt`. The sole automated test is a 662-line Playwright `reader.spec.ts` that asserts against rendered DOM with loose lower-bound floors (`count > 3`, `> 5`, `> 100`) — it never checks parser output and can't catch a catastrophic drop from 499→18. The freshness gate is _tautological_ for logic bugs: a wrong computation passes the instant its buggy output is regenerated and committed (exactly how A2 ships green). → **Fix:** add a `pytest` suite — golden-corpus parser tests (B3), a discovery test asserting known projects/crates/specs appear, and the depth-proxy fixture (C2). This is the highest-leverage structural fix in the report. **C2 · [MEDIUM] The §11 depth proxy that gates "complete" has no fixture proving it works.** The proxy (`coverage.py:317-350`) is `prose_words < 150` OR (`≥12 table rows` AND `<260` prose) OR (no link/backtick). Nothing proves it _flags_ a known-thin page and _passes_ a known-good one, so a future tweak could quietly neuter the one gate that defends "complete." → **Fix:** two fixtures (a 100-word filler page → flagged; a real V1-quality page → clears) asserted in CI. ### Theme D — Navigability of the 2,643-node headline asset **D1 · [MEDIUM] Most entity nodes on the large aggregate pages are reachable by neither the on-page TOC nor global search.** The 1 MB `lib-iris.html` inlines ~262 entity sections but the TOC is capped at 12 items and search section-anchors are capped at 12/page (`MAX_SEARCH_SECTIONS`), so the long tail is addressable only by manual scroll or Ctrl-F — contradicting the §8 "every entity node" promise. (The page _does_ carry per-entity `id=` anchors — 293 of them — so the deep-links exist; they're just not surfaced in any index.) → **Fix:** raise/remove the per-page section cap for entity pages, or index every entity node as its own search entry with its anchor (see D2's structural fix, which enables this). **D2 · [MEDIUM] The 1 MB aggregate pages are a fully-expanded ~21K-word DOM with no collapse or virtualization.** `lib-iris.html` is a single always-rendered ~18,880-node DOM; entity deep-dives are emitted as `` runs, not headings, so they don't appear in the document outline either (see F3). → **Fix (one change, three payoffs):** wrap each entity card in `
` and emit a real `

` per entity. This collapses the DOM (perf), restores the screen-reader/outline structure (a11y), and lets every entity be TOC- and search-addressable (D1/UX). **D3 · [MEDIUM] Search is whole-query substring matching — multi-word or out-of-order queries return "No matches."** `search.py:246` `var q = input.value.trim().toLowerCase()` and `:230` `var h = row.hay, i = h.indexOf(q)` — the entire query is matched as one contiguous, in-order substring. Searching `instancing iris` (when the haystack reads "iris … instancing") returns nothing. → **Fix:** tokenize on whitespace and require all tokens to hit (AND), scoring by summed per-token position with the existing title-prefix/kind boosts — a ~5-line change to `score()`/`render()`. **D4 · [LOW] The portal front door has drifted into a 24-section vertical scroll (14 single-card rails); first-run orientation is buried.** → **Fix:** collapse single-card rails into a compact directory or merge them; lift a "new here? start with the repo map / role lenses" band to the first screen. ### Theme E — Performance & scale **E1 · [MEDIUM] The 1 MB search index loads render-blocking at top-of-`` on every one of 228 pages + portal.** `shell.py:155-157` injects `