ORA Index

Indexes are views over the entries, not sources of truth. The source of truth is the frontmatter in each entry file under ../entries/.

Index files

• by_domain.md — entries grouped by tags[0] (primary domain)
• by_maturity.md — entries grouped by M0-M4 level, newest first within each
• by_pillar.md — entries grouped by pillar frontmatter
• clusters.md — entries grouped by evidence clusters (who sources whom)
• supersession_chains.md — entries that replaced or were replaced by others
• tags.md — canonical tag vocabulary (keep the tag space small)

Regeneration

Run python3 ../../scripts/regenerate-indexes.py from this directory, or python3 scripts/regenerate-indexes.py from the repo root. The generator walks docs/entries/{doctrines,patterns,observations,failures,hypotheses,decisions,syntheses}/*.md, parses frontmatter, and rewrites only the regions bounded by <!-- AUTOGEN-START --> / <!-- AUTOGEN-END -->.

Use python3 scripts/regenerate-indexes.py --check in CI-style checks.

Do NOT commit indexes that are out of sync with entries. Stale indexes are worse than no indexes — they silently lie about what exists.

When to read an index vs. ripgrep directly

• Index: when you want a curated view (maturity, chains, clusters)
• ripgrep: when you know exactly what you're looking for

Both are fine. The index exists to help you find entries you didn't know existed.