Glossary

Data Pipeline Terms

Canonical homebrew

The author-once class or subclass format stored in homebrew/. Canonical homebrew is edition-agnostic — a single JSON file describes a class or subclass once, and the pipeline projects it into edition-specific representations during ingestion. This matters because it means homebrew authors don't need to maintain separate 2014 and 2024 versions of the same content. The canonical format is the single source of truth; everything downstream is derived.

Projection

The transformation of canonical homebrew into edition-specific rows during the db-refresh pipeline. Projection maps abstract class features, hit dice, and proficiency definitions into concrete database rows that match the shape of SRD-sourced data. The term distinguishes the authored input (canonical) from the generated output (projected). If a projection produces unexpected results, the fix belongs in the projection logic, not in the canonical homebrew file.

Merged view

A SQLite view that combines SRD-sourced rows and projected homebrew rows into a single queryable table. The merged view is what downstream consumers (progression generation, the API, the level-up engine) actually read from — they don't distinguish between SRD and homebrew content at query time. This abstraction is critical for treating homebrew classes as first-class citizens in the system without forking every query into SRD-vs-homebrew branches.

Wiki Health Terms

Source paths

Frontmatter references (source_paths field) that anchor wiki claims to specific repo files. Every non-index wiki page must declare at least one source path, per the contract in Decision: Wiki Maintenance Contract. Source paths serve two purposes: they give readers a direct link to the code being described, and they enable automated stale detection by comparing file timestamps against page timestamps. Defined and enforced in server/wiki.py and AGENTS.md.

Stale page

A wiki page whose modification time is older than at least one file listed in its source_paths. Staleness is a signal, not an error — it means the underlying code has changed since the page was last updated, and the page may no longer accurately describe current behavior. The GET /api/wiki/health endpoint reports stale pages so they can be prioritized for review. Staleness is resolved by running an ingest operation that refreshes the page content and updates wiki/log.md.

Backlink count

The number of wiki pages that link to a given page using a slug enclosed in double brackets. Backlink count is a graph-health metric: pages with zero backlinks and no children (orphan pages) may indicate documentation that was created but never integrated into the wiki's navigation structure. The backlink graph is computed at render time in both server/wiki.py and site/lib/wiki.ts by scanning all pages for outgoing double-bracket wiki-link references.

Design Rationale

The glossary exists to reduce ambiguity in engineering discussions and wiki pages. Terms like "projection" and "merged view" have specific meanings in this codebase that differ from their general usage. By defining them here, wiki pages can use these terms without re-explaining them, and new contributors can build accurate mental models of the system.

The terms are grouped by domain (data pipeline vs. wiki health) because they serve different audiences. Pipeline terms matter when debugging ingestion or progression generation. Wiki health terms matter when maintaining the documentation system itself.

Assumptions & Constraints

• Terms are codebase-specific. This glossary defines terms as they are used in Lorewright, not their general industry meanings. "Projection" here is not a database projection or a geometric projection — it's a homebrew-to-edition transformation.
• The glossary is append-only in practice. Terms are added as new abstractions emerge. Removing a term risks breaking the mental models of people who learned the codebase using earlier versions of this page.
• Wiki-links from other pages assume these definitions. When a wiki page uses the term "canonical homebrew" without further explanation, it relies on this glossary providing the authoritative definition.

Conceptual Model

The glossary terms form a dependency chain that mirrors the data flow:

canonical homebrew → projection → merged view → progression generation

Each term represents a stage in the pipeline where authored content is transformed into something the system consumes. Understanding this chain is essential for debugging: if a class feature is missing from the API, you trace backward through merged view → projection → canonical homebrew to find where the data was lost or malformed.

The wiki health terms (source_paths, stale page, backlink count) describe a parallel system — the documentation graph — that monitors itself for consistency. They form a smaller feedback loop: source paths enable stale detection, stale detection triggers ingest, and ingest refreshes both content and backlink structure.