Proposal I: DOCS-AS-SITE-SOURCE spec (SPEC + HOLD, no build)

[WilfordGrimley]

Summary

New HOLD spec, docs/proposals/proposal-i-docs-as-site-source.md — no build, owner review pending. Goal per the task: the site consumes docs/ the way the wiki already does, single source, multi-target, everything updating per-merge.

§0 Grounding (added before the requested sections, since it corrects two premises the task assumed): docs/features/catalog-completion-plan.md's status tracking is nested bulleted prose, not a markdown table, and docs/theory.md's weight/constant citations are inline prose, not an isolated block — neither is extraction-ready under §3's own marked-region-only contract without a small content restructure first. Flagged explicitly rather than silently built around or silently reshaping the premise. Also records the concrete facts the rest of the spec is built on: no markdown-rendering library exists in frontend/package.json yet, the frontend is already a static export, generate-keyrune-assets.js is a real precedent for build-time codegen into frontend/src/common/generated/, about.tsx already establishes a dangerouslySetInnerHTML pattern for pre-rendered content, and — the one finding that changes the sequencing design — deploy-frontend.yml does not currently trigger on docs/** at all.

§1 Architecture: a Next.js catch-all SSG route for rendered site pages (markdown → HTML at build time, wrapped in existing site chrome/Superhero styling) + a Node prebuild script for structured JSON data extracts, mirroring the keyrune codegen precedent's output-location convention. Flags link-rewriting as a real three-way problem (site route / wiki page / GitHub blob, vs. publish_wiki.py's existing two-way case) and proposes sharing its transform_links/rewrite_link logic rather than reimplementing it.

§2 The map: extends .github/wiki-publish-map.json's schema with a targets array (wiki/site/data) and proposes an initial mapping, with judgment calls called out explicitly (e.g. whether to publish user-guide.md's current skeleton state to the site now or wait for it to be finished).

§3 Extraction contract: <!-- DATA-EXTRACT: name --> ... <!-- END DATA-EXTRACT --> markers around markdown tables only, mirroring publish_wiki.py's existing GENERATED_MARKER convention. A broken or missing marker is a hard build error, matching its existing link-resolution fail-fast philosophy.

§4 Sequencing: the required deploy-frontend.yml trigger-path fix (found by reading the workflow, not assumed), where the data-extract script hooks into the build (prebuild, not postinstall — docs don't change on npm install), and the full merge → wiki regenerate → site rebuild sequence.

§5 What v1 is not: no CMS, no runtime doc fetching, no site-side editing, build-time only.

Also updates docs/README.md's "Plans & proposals" table with the new entry, and adds one docs_lint.py ALLOWLIST entry for the spec's one proposed-not-yet-built script path (frontend/scripts/generate-docs-data.js).

Test plan

• python3 .github/scripts/docs_lint.py — clean.
• npx prettier@2.7.1 --check (pinned version) on the touched markdown files — clean.
• python3 -m black --check --diff .github/scripts/docs_lint.py (pinned 22.8.0) — clean.
• Every factual claim in §0 (dependency list, next.config.js contents, about.tsx's rendering approach, deploy-frontend.yml's trigger paths, catalog-completion-plan.md/theory.md's actual structure) verified directly against the repo, not assumed from the task's own framing.

🤖 Generated with Claude Code

https://claude.ai/code/session_01AHfxN9bbWAWHs8rfzVtBWt

---

Generated by Claude Code