Skip to content

ADR-083: Docs-site visual layer (Mermaid) and research consolidation

Status: Accepted Date: 2026-06-01 Context: The internal docs site (docs/, MkDocs Material rendered at pulse-game-docs.vercel.app) has grown to 79 ADRs and ~23 research files. The two sections CoachJ reads most — ADRs and Research — had become hard to navigate: a flat 79-row ADR index sorted by number (chronological, not conceptual), several multi-thousand-word ADRs and research docs presented as undifferentiated walls of text, and duplicate clusters (the measurement-schema and cube docs each carried both a canonical version and its iteration log in the same folder). The site had no diagram support configured. A previously hand-built "Reader's Guide" for the measurement schema proved that a plain-language explainer plus a structural diagram makes dense material far easier to absorb; this ADR generalises that pattern.

Decision

Adopt a docs visual layer and consolidate the research folder. Four parts:

  1. Enable Mermaid inline. Add a pymdownx.superfences custom fence for mermaid in mkdocs.yml. Material bundles mermaid.js, so this adds no new pip dependency. Diagrams now live in markdown — version-controlled, searchable, rendered in-page next to the prose.

  2. Establish the visual-layer convention for any dense section:

    • a plain-language "Start here" / "At a glance" callout at the top;
    • a Mermaid diagram for the structure or flow ("how it fits together and moves");
    • themed grouping in place of flat lists.
    • Hybrid rendering: Mermaid for flow/relationship diagrams embedded in docs; standalone self-contained HTML reserved for richer explorable artifacts (e.g. a future cube explorer), linked from the markdown.

  3. Restructure the ADR index (decisions/README.md): a theme-overview diagram, a collapsible full 79-ADR map (status-coloured, superseded greyed), and the index regrouped into 8 themes instead of one flat table. Per-ADR treatment piloted on the densest record (ADR-077: an "At a glance" header + a defense-layer diagram).

  4. Consolidate research. Keep the canonical doc + reader's guide in research/; move promoted iteration history to archive/ (measurement-schema working notes + ADR-074 alignment brief; cube working notes + prompt-iteration notes). Every moved file gets a forwarding banner; archive/ gains an index README. Nothing is deleted.

Rationale

  • Walls of text impede the primary reader. Chronological numbering buries the conceptual structure that the theme grouping + diagrams expose.
  • Mermaid-in-Material is the lowest-cost rendering path: zero new dependencies, in-page, searchable, diffs cleanly in PRs.
  • The consolidation follows the repo's own taxonomy — the research README defines archive/ as "truly dead-history," and the reader's guide already told readers to "skip the working notes unless you want the iteration history." Moving them formalises advice the docs already gave.
  • Archiving (not deleting) preserves the deliberation trail, consistent with how superseded ADRs (052, 067, 069) are kept in place.

Alternatives Considered

  • mkdocs-mermaid2 plugin — rejected: adds a pip dependency and a Vercel build surface for capability Material already ships via superfences.
  • Standalone HTML for all diagrams — rejected as the default: diagrams would leave the doc flow and drop out of site search. Retained only for rich/explorable pieces (the hybrid clause).
  • Delete redundant docs — rejected: loses deliberation context; archive achieves dedup without loss.
  • Add visual layers but move nothing — rejected: leaves the duplicate-info problem the cleanup set out to solve.
  • One giant 79-node graph as the primary visual — rejected as the primary view (unreadable at a glance); kept as a collapsible secondary, with the 8-theme overview as the glance-level entry.

Discussion

Scope was deliberately pilot-first: treat ADRs + Research (the most-read sections) plus the shared infrastructure, then let CoachJ react to the pattern before sweeping briefs / handoffs / design / twin / orchestrator. "Show all ADRs, grey out superseded" was CoachJ's explicit call for the full map.

Two hazards surfaced mid-task and changed execution:

  • Mid-session branch switch. Work started on spof-audit-closure-a (which carries ADR-080) but the tree was switched to solo-conviction-before-rationale (ADR-081) while exploring. To avoid commingling a cross-cutting docs cleanup with feature-branch history — and to leave CoachJ's uncommitted WIP untouched — the cleanup was anchored in a dedicated git worktree off main (docs-cleanup-visuals).
  • ADR numbering across parallel branches. main shows ADRs only through 079, but 080 (spof), 081 (solo-conviction), and 082 (NoTA flow cleanup) are already allocated on other branches / in the vault. This ADR takes 083 to avoid collision. The episode is itself evidence that next-number guidance must check active branches + the vault, not just main — captured in the updated "Adding a New ADR" steps.

Deferred within this effort: a standalone HTML cube explorer (the one genuinely net-new "explorable" artifact) — held pending a look at CoachJ's existing hand-built cube HTML so its design isn't reinvented, consistent with the "verify before building elaborate things" working rule. ADR-080/081 fold into the ADR map when their branches merge.

Consequences

  • Mermaid is available repo-wide; the superfences custom fence is now load-bearing for rendering — removing it turns every diagram back into a raw code block.
  • Future dense docs are expected to follow the visual-layer convention; the ADR README's "Adding a New ADR" steps now require theme-table placement + drawing supersede/extends edges on the map.
  • research/ is slimmer (canonical + reader's guide per cluster); archive/ is indexed and carries forwarding banners.
  • Watch: the 79-node map needs upkeep as ADRs accrue; the theme assignment of new ADRs is a small recurring judgement call.
  • Pending follow-ups: second sweep across the remaining sections; the cube HTML explorer; rolling the per-ADR "At a glance" header beyond ADR-077; folding ADR-080/081/082 into the map post-merge.

Key files: - mkdocs.yml — Mermaid custom fence under pymdownx.superfences. - docs/stylesheets/extra.css — .mermaid, .figure-caption, .start-here styles in the Pulse palette. - docs/decisions/README.md — theme-overview + full-map diagrams, 8-theme regrouped index, updated authoring steps. - docs/decisions/077-anti-gaming-defenses-token-bearing-surfaces.md — per-ADR "At a glance" + layer diagram (pattern exemplar). - docs/research/README.md — research map + grouped, navigable contents. - docs/research/foundations/measurement-schema-readers-guide.md — 5-layer flow diagram. - docs/research/foundations/scenario-dimension-cube.md — three-concepts axis diagram. - docs/archive/README.md + 4 moved files — archive index + forwarding banners.