Skip to content
Murmur Atlas · Internal

ADR-0003: Generated reference docs start from example manifests

ADR-0003 ACCEPTED 2026-09-20

Context

Section titled “Context”

The build brief’s target end-state is “CODE CHANGES -> MANIFEST CHANGES -> DOCS CHANGES” — reference docs generated from machine-readable sources (a real JUCE parameter export, a real OpenAPI spec exported from murmur-api). Neither exists yet: murmur-app has no parameter-manifest JSON, and murmur-api (Go) doesn’t currently export an OpenAPI spec. It also explicitly says: “NEVER silently invent production architecture” and “if information requires verification, mark it clearly.”

Decision

Section titled “Decision”

Build the generator pipeline now (generators/generate-parameter-docs.mjs, generators/generate-openapi-docs.mjs) against hand-authored example sources (schemas/manifests/murmur-classic.example.json, schemas/openapi/murmur-api.example.yaml) that are grounded in verified facts (real engine names, real route paths from murmur-web/docs/CLOUD.md) but have illustrative parameter ranges/response schemas. Every generated page carries a machine-checkable verified: false frontmatter flag and a visible <MurmurCallout kind="unverified"> banner explaining exactly what’s real and what’s representative, sourced from the manifest’s own $comment field.

Alternatives Considered

Section titled “Alternatives Considered”
  • Wait for real exports before building the pipeline — rejected: the pipeline and its CI checks (schema validation, “don’t hand-edit generated files”) are the deliverable the build brief actually asked for; a real export is a drop-in replacement for the example manifest, not a prerequisite for the tooling.
  • Hand-write the parameter reference page directly in MDX — rejected: reintroduces exactly the manual-drift problem generated docs exist to solve, and doesn’t prove the manifest -> docs pipeline works.
  • Fabricate “verified” values to look more finished — explicitly rejected by the build brief’s “never silently invent production architecture” rule.

Consequences

Section titled “Consequences”
  • npm run docs:generate is safe to run repeatedly (idempotent, overwrites its own output) and CI fails a PR that edits content/docs/public/reference/* or .../developers/*-reference.mdx by hand without regenerating.
  • The moment murmur-app or murmur-api exports a real manifest/spec, swapping the file in schemas/manifests/ or schemas/openapi/ and removing its $comment/# ILLUSTRATIVE marker flips verified to true and removes the banner — no template change needed.

Update (post-merge)

Section titled “Update (post-merge)”

The first real, verified: true manifest landed: schemas/manifests/splay.json, extracted from murmur-app’s actual implemented JUCE parameter tree (splay_plugin/src/SplayParamLayout.cpp), not hand-authored. The generator now distinguishes a $comment field (unverified-example marker, renders the amber “GENERATED FROM AN EXAMPLE MANIFEST” banner) from a $source field (verified-real citation, renders a plain “SOURCE” note) — see generators/generate-parameter-docs.mjs. MURMUR’s own parameter tree is still the example manifest: murmur-app’s plugin/src/parameters/ is explicitly a documented, not-yet-implemented scaffold (docs/ROADMAP.md Phase 16), so there’s no real MURMUR manifest to extract yet — Splay’s was real and implemented, which is why it was first.

Two more real manifests followed the same audit pass: Fathom (schemas/manifests/fathom.json, 31 parameters — its reverb plugin turned out to be a substantially real, 3-mode engine, correcting an earlier mischaracterization; see design-source.md) and Cast (schemas/manifests/cast.json, 2 parameters — deliberately tiny by design). Undertow was checked and confirmed to have no real manifest possible: undertow_plugin/src/UndertowProcessor.h explicitly notes it has no host-automatable APVTS surface yet, same as MURMUR’s own core.

Section titled “Related Work”