ADR-017: YAML Expansion Files for Content Enrichment

Date: 2025-11-10 Status: ✅ Accepted Deciders: CTO (Claude Code AI), CEO Tags: #documentation #content #architecture

Context

Need to add examples, diagrams, and verbose explanations to HTML while keeping MD compressed for AI consumption. Three approaches considered: 1. Inline expansions in MD (bloats token count) 2. Separate HTML files (breaks single source of truth) 3. YAML expansion files (separate data storage)

Decision

Store content expansions in separate YAML files (.expansions.yml) alongside each MD file.

Structure:

Documentation/1-CONTEXT/
├── _SYSTEM.md                    # Compressed source (AI)
├── _SYSTEM.expansions.yml        # Expansion data (build system)
└── ...

Directive Syntax in MD:

<!-- EXPAND:type:key -->

YAML Format:

example:
  rule_name:
    title: "Example Title"
    lang: python
    code: |
      # Code here
    explanation: |
      Why this matters

Rationale

Keeps MD Compressed: - MD files stay at ~11K tokens (22% of 50K budget) - Expansions don't count toward token budget (YAML not read by AI) - Perfect for dual-format goal

Single Source of Truth Maintained: - MD controls structure and flow - YAML provides educational content - Build system combines them for HTML

Easy to Maintain: - Update YAML without touching MD - Non-technical users can add examples - Clear separation of concerns

Scalable: - Add unlimited expansions without token impact - Can create expansion files for any MD file - Incremental enhancement possible

Consequences

Positive

✅ Zero token impact on Layer 1
✅ Perfect dual format (compressed MD, verbose HTML)
✅ Easy to maintain and update
✅ Scalable to any Layer 1 file

Negative

❌ Two files per doc (MD + YAML)
❌ Need to learn YAML syntax
❌ Build system dependency

Implementation

Current State: - ✅ Build system supports expansion directives - ✅ 4 expansion files created (_SYSTEM, _STANDARDS, _CODEBASE, _WORKFLOWS) - ✅ 150+ expansion entries total - ✅ All 5 expansion types working

Expansion Types: example, diagram, verbose, pitfall, why (see ADR-018)

Adr 017 Yaml Expansion Files