:::note Immutable
BDRs are never edited. If this decision changes → create a new BDR that supersedes this one.
:::
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.