ADR-0004: One resource file per chapter
Status: Accepted Date: 2026-05-19
Context
Need to decide file granularity for ingested resources. Three options: per-book (huge files), per-chapter (moderate), per-section (hundreds of files).
Decision
One file per chapter or major section. Bible is the exception — one file per book (since chapters are short, with headings ## 3 / ### 16 for chapter/verse). Transcripts and SMM speeches: one file per talk/speech.
User has reusable OCR scripts from a prior attempt that produced chapter-level files; that work is leveraged.
Alternatives considered
- Per-book: rejected — single 500-page files blow token budgets on every read; backlinks collapse to one node and graph becomes useless.
- Per-section: rejected — hundreds of resource files explode the vault; editing corrections becomes a hunt.
Consequences
- (+) Token economy: AI loads one chapter’s worth, not a whole book
- (+) Backlinks aggregate meaningfully (chapter density visible on the graph)
- (+) Editing corrections is tractable (one chapter file at a time)
- (−) Ingestion pipeline must normalize headings consistently for citations to resolve