Docs Architecture: Chunked Source + Generated Full Artifact

BDR 0002 – Docs Architecture: Chunked Source + Generated Full Artifact

The business plan lives as chapter files under `src/content/docs/business-plan/` and is concatenated into `ai/business-plan-full.md` for upload to the Claude Project. The chapters had inconsistent metadata and no machine-readable manifest, making it hard for both humans and AI tools to navigate the plan or know which file is the source of truth.

The repo’s standing Hard Constraint is “NEVER modify docs/ — read-only source of truth.” A deliberate, owner-approved restructure required a one-time, consciously scoped exception.

1. **Chunked source, generated artifact.** The per-chapter files under `src/content/docs/business-plan/` are the single working SOURCE. `ai/business-plan-full.md` is a GENERATED ARTIFACT produced by `scripts/build-full.sh` and remains the single file uploaded to the Claude Project. 2. **One-directional flow.** Chunks → full only. The full file is never hand-edited or reverse-merged into the chunks. 3. **Frontmatter standard (additive).** Each chapter carries `id`, `title`, `summary`, `status`, `domain`, plus the pre-existing `type`, `order`, `version`, `updated`, `visibility`, `confidence`, and now `tags[]` and `related[]`. No existing field was removed. (`scope` was considered and rejected — `visibility` + `tags[]` already cover it.) 4. **BLUF.** Every chapter opens with a one-sentence "Bottom line" after its H1. 5. **Manifest.** `ai/_index.md` lists every chapter, the glossary and the decision index with one-line descriptions, and is prepended to the top of the generated full artifact. 6. **Read-only exception.** The "NEVER modify `docs/`" Hard Constraint was consciously suspended for this single restructure task by explicit owner approval. After completion, the read-only rule is back in full force. - A manifest + consistent frontmatter make the plan navigable for AI tools without guessing. - Keeping the full file as a pure generated artifact prevents source drift between the two. - Additive frontmatter avoids breaking the Starlight build and loses no existing metadata. - BLUF sentences give each chapter an at-a-glance takeaway for skim-reading and AI summarization. **Positive:** - Clear source-of-truth: edit chunks, regenerate the artifact. - `_index.md` gives a sub-800-token map of the whole plan. - Richer, queryable metadata (`tags[]`, `related[]`) across chapters.

Risks / obligations:

build-full.sh must be re-run after every chapter change, or the artifact goes stale.
The implicit “monolith” mental model (treating the full file as editable) is now retired; no prior BDR existed for it, so there is no formal BDR to supersede.
The docs/ read-only suspension was task-scoped; any future docs edit needs its own approval.

What follows:

Run scripts/build-full.sh and re-upload ai/business-plan-full.md to the Claude Project after BP changes.
New chapters must follow the frontmatter standard and BLUF convention above.