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. Granularity follows the natural unit of coherence per source-type. Exceptions:
- Bible: one file per book (since chapters are short, with headings
## 3/### 16for chapter/verse). - Anthologies (e.g. WorldScripture per ADR-0020): one file per sub-theme. Each sub-theme in an anthology bundles a coherent set of cross-source citations plus editorial framing — analogous to a chapter in a monograph. Splitting at the next-larger unit (chapter) produces files too large for reader and AI context loads (1,700+ lines empirically on WS-II ch1).
- Divine Principle (per ADR-0021): one file per section. Sections (e.g. “The Root of Sin”, “The Four Position Foundation”) are themselves coherent doctrinal units typically 3–15 paragraphs, the natural citation anchor, and a full-chapter file would run 70–100 KB / ~3000–5000 words — past comfortable reader and AI-context limits, comparable to the WS-II case that drove the anthology carve-out.
- 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