Skip to main content

Lore / Design File Conventions

Purpose​

This file is the in-repo source of truth for the prefix scheme used under examples/valenar/docs/lore/. Every new file created under that tree must conform to the rules below. This file also records the boundary between the lore tree and non-lore gd-* material: non-lore quest-owner and navigation placement is governed by ../pr-quest-owner-and-navigation-model.md and adr/ad-0005-owner-pages-and-navigation-views.md, while adr/ad-0002-lore-docs-migration.md records the completed migration that kept non-lore gd-* and pr-* docs outside lore/. This file is committed before any other file in the lore tree so that no file under the tree is authored against an undocumented convention.

Prefix table​

The two-letter prefix on every filename signals which layer the document belongs to. The full prefix set, with no synonyms or aliases:

  • ul- — Universe lore. Cross-game canon: deep history, pantheon, cosmology, metaphysical mechanics that transcend any single game in this setting. Includes bible-only material that exists for internal consistency but is never surfaced in player-facing content.
  • gl- — Game-local lore. Per-game canon: factions present in this game, named NPCs, in-game-era specifics, the particular instances of universe-scale patterns that this game's storyline grounds.
  • lh- — Lore hooks / cross-reference tables. Maps universe-scope facts (ul-*) to where, when, and how they surface in a specific game's content, with explicit exposure tiers per entry.
  • gd- — Game design. Mechanics, balance, economy, content tables, and rule systems specific to one game. Distinct from lore; design facts are about how the game plays, not about what is true in the world.
  • ud- — Universe design. Mechanics that span games — for example, world-law rules that govern how demon essence resists mundane force across every game in the setting.
  • ad- — Architecture / accepted decision records. ADRs governing the lore tree itself or any design decision documented under docs/lore/.
  • sp- — Specs. Authoring contracts, data shape specifications, schema definitions.
  • rn- — Runtime / engine docs scoped to the lore tree.
  • pr- — Project / process / meta. Conventions, governance, workflow documents (this file, for example).

No new prefix may be introduced ad hoc. Adding a prefix to the table above requires a new ADR.

Rules for new files​

  • Every new file under examples/valenar/docs/lore/ must carry a valid prefix from the table above.
  • The prefix and the subdirectory must agree:
    • ul-* files live in lore/universe/.
    • gl-* files live in lore/local/.
    • lh-* files live in lore/hooks/.
    • ad-* files live in lore/adr/.
    • pr-* files live at lore/ root unless an ADR explicitly creates a subfolder for them.
    • ud-* files co-locate inside lore/universe/ because universe design is, like universe lore, cross-game.
    • gd-* files do not live under examples/valenar/docs/lore/. Their broader placement in the per-game design layer is recorded in adr/ad-0002-lore-docs-migration.md; concrete quest-owner and navigation-view placement is governed by ../pr-quest-owner-and-navigation-model.md and adr/ad-0005-owner-pages-and-navigation-views.md.
    • sp-* and rn-* placement inside the lore tree remains reserved until a lore-tree ADR defines it.
  • Post-prefix names must be globally unique within the lore tree. A ul-shroud.md and a gd-shroud.md are not permitted to coexist; the post-prefix slug shroud is the unique key.
  • Filenames must be lowercase-hyphenated. No spaces, no underscores except where the prefix table dictates the leading hyphen.
  • A new file must declare its layer in YAML frontmatter at the top: prefix:, layer:, status:, date: are required. ad-* files additionally declare id: and title:.

Rules for existing files outside docs/lore/​

  • This convention does NOT retroactively rename or re-place files outside examples/valenar/docs/lore/.
  • adr/ad-0002-lore-docs-migration.md records the completed migration that added gd-* and pr-* prefixes while keeping non-lore files in their existing per-game design and process directories.
  • ../pr-quest-owner-and-navigation-model.md and adr/ad-0005-owner-pages-and-navigation-views.md govern canonical owner pages and navigation views for concrete quest docs outside lore/ and story/.
  • Existing files keep their current paths unless a separate explicit migration task authorizes a rename.
  • No silent renames. No redirect stubs. Migration remains a deliberate sweep, not a side effect of authoring.

Cross-layer reference rules​

  • ul-* files may reference other ul-* files and ud-* files. They may not reference gl-*, gd-*, or any game-specific layer. The universe layer must be authorable independently of any single game.
  • ud-* files follow the same rule: they may reference ul-* and other ud-* files only.
  • gl-* files may reference gl-* files within the same game, plus ul-* and ud-* files. They may not reference gl-* files belonging to a different game; cross-game links route through ul-* instead.
  • gd-* files may reference other gd-* files within the same game and may reference ud-* mechanics. They may not reference gl-* files except through lh-* exposure tables.
  • lh-* files reference both ul-* sources and the gl-* or game-design files where the fact surfaces. lh-* is the only layer where a universe reference and a game reference may sit in the same row.
  • A ul-* or ud-* file referencing a gl-* file is a layering FAIL. The verifier must reject it.

Canonicity tier definitions​

Every fact in a ul-* or ud-* file must declare exactly one canonicity tier. Tier definitions are:

  • hard canon — committed, non-negotiable. Future games and content must respect this fact. Demoting a hard-canon fact requires an explicit user decision in a wave brief.
  • soft canon — the intended direction. Subject to revision by an explicit decision, but treated as authoritative for current authoring.
  • proposed — surfaced as a candidate. Used for terms whose exact name is deferred or whose mechanism is still being decided. A proposed fact requires a confirming user decision before it may be promoted to soft canon or hard canon.
  • bible-only — exists in the design bible for internal consistency but must never be surfaced in any player-facing content. Bible-only facts cap at the hidden exposure tier in every lh-* table.

Exposure tier definitions and Game 1 ceiling​

Every lh-* row must declare exactly one exposure tier for the fact in the named game. Tier definitions are:

  • revealed — the player can see and understand this fact directly during the game. Reserved for in-Zone observables such as the Nexus / Wardheart structure, ward stones, the failure of the Ancient Shield, and visible demon presence.
  • hinted — the player encounters enough evidence to strongly suspect the fact but never receives a clean statement of it. Maximum tier for cosmological facts in Game 1.
  • referenced once — the fact appears obliquely, exactly once, in a discoverable text fragment or a single NPC line. It does not repeat or compound across other surfaces.
  • hidden — the fact exists in the universe lore but is not surfaced in this game's content at all. Bible-only facts must always be hidden.

Game 1 reveal-tier ceiling rule (binding for every lh-* entry tagged game: valenar):

No cosmological fact (Demon Cycle mechanism, Shroud, gods, super-world, gate-network truth) may exceed hinted in Game 1 lh-* entries. revealed is reserved for in-Zone observables: Nexus / Wardheart, ward stones, demon presence, failing Ancient Shield. The false-king / heart-fragment fact may reach hinted early and revealed only in a deliberate late-game political reveal.

Cosmology hook tables (e.g. lh-game1-cosmology-hooks.md) MUST contain only hinted, referenced once, or hidden entries — never revealed. World hook tables (e.g. lh-game1-world-hooks.md) MAY use revealed for in-Zone observables but the cosmological mechanism behind a revealed effect must remain capped at hinted. A reveal of the surface effect does not authorize a reveal of the underlying cosmology.

Conflict resolution​

  • A ul-* hard-canon fact overrides any gl-*, gd-*, or game-design choice that contradicts it. The gl-* or gd-* file must be revised, not the ul-* source.
  • Promoting a gl-* fact to ul-* scope requires a promotion wave with a new ADR establishing the cross-game scope.
  • Demoting a ul-* hard-canon fact to proposed requires an explicit user decision recorded in a wave brief and reflected as a status change on the fact.
  • A reverse reference direction (ul-* referencing gl-*) is always a layering FAIL.
  • A gd-* file may not assert a cosmological fact directly; it must reference a ul-* source through an lh-* row.

Edit order convention​

When a wave authors multiple lore files at once, the convention file (pr-file-conventions.md) and the governing ADR (adr/ad-0001-lore-prefix-scheme.md) are committed before any other file in the tree. After those, ul-* files are authored before any lh-* file that references them, because lh-* rows must point at concrete ul-* paths and facts. gl-* files are authored only after the ul-* facts they instantiate exist.

ADR namespaces​

The ad- prefix under examples/valenar/docs/lore/ is a SEPARATE ADR namespace from the workspace-root docs/decisions/ tree. Each tree maintains its own sequential ADR numbering, and a numeric collision across the two trees is permitted by design rather than treated as a defect.

  • Workspace-root ADRs live in docs/decisions/ with the filename pattern ADR-NNNN-<name>.md (uppercase, dash separator). They cover engine, runtime, language, and cross-cutting workspace decisions — for example, ADR-0002-behavior-vocabulary.md.
  • Lore-tree ADRs live in examples/valenar/docs/lore/adr/ with the filename pattern ad-NNNN-<name>.md (lowercase, conforming to the prefix scheme in this file). They cover decisions about the lore tree itself, the prefix scheme, doc-tree migrations, and game-local design governance — for example, adr/ad-0001-lore-prefix-scheme.md, adr/ad-0002-lore-docs-migration.md.

When citing an ADR in cross-tree prose, qualify which namespace applies. Use the full path (e.g. docs/decisions/ADR-0002-behavior-vocabulary.md vs examples/valenar/docs/lore/adr/ad-0002-lore-docs-migration.md) or name the subject (e.g. "the behavior-vocabulary ADR" vs "the lore migration ADR"). A bare ADR-0002 reference is ambiguous and should be avoided.

Future games introduced under examples/<game>/docs/lore/ inherit this convention: each game's lore/adr/ad-* ADRs form their own namespace, independent of both the workspace-root and any other game's lore-tree ADRs.