Skip to main content

Lore Tree Conventions

Files under examples/valenar/docs/lore/ (plus gd-*.md files anywhere under examples/valenar/docs/) use a two-letter prefix scheme. The authoritative source for lore-tree rules is examples/valenar/docs/lore/pr-file-conventions.md — read that for full details and edge cases. For non-lore quest-design owner pages and navigation views, also read examples/valenar/docs/pr-quest-owner-and-navigation-model.md. The TL;DR below is enough to author safely without violating the layering rule.

Workspace-root guidance for the shared prefix vocabulary lives in .claude/rules/docs-conventions.md; this file is the per-tree specialization for examples/valenar/docs/lore/**. Both files agree on the prefix table by convention; each governs its own tree.

Prefixes and directories​

  • ul- Universe lore → lore/universe/
  • gl- Game-local lore → lore/local/
  • lh- Lore hooks / cross-reference tables → lore/hooks/
  • ud- Universe design → lore/universe/
  • ad- ADRs → lore/adr/ (separate namespace from workspace-root docs/decisions/ — see pr-file-conventions.md § ADR namespaces)
  • pr- Project / process / meta → lore/ root

gd- (game design) files live OUTSIDE the lore tree, in the relevant per-domain subdirectory (e.g. examples/valenar/docs/systems/gd-*.md, acts/gd-*.md, generation/gd-*.md, plus gd-canon.md and gd-glossary.md at docs root). Quest Thread, Local Quest, Mission, design-branch, and related index placement is governed by examples/valenar/docs/pr-quest-owner-and-navigation-model.md; this rule keeps those files outside lore/ and preserves the lore-layer reference rules.

Cross-layer reference rule (load-bearing)​

This is the rule that most often gets violated by accident. Follow it exactly.

  • ul-* and ud-* files may reference ONLY other ul-* / ud-* files.
  • gl-* files may reference same-game gl-* plus ul-* and ud-*. Cross-game gl-→gl- is forbidden.
  • gd-* files (outside this tree) must route lore references through lh-* table rows. They may NOT directly cite ul-* or gl-* files inline. The correct lore-link form in a gd-* file is (See lore exposure: [lh-game1-world-hooks.md](relative-path) — TopicHint row), NOT (See lore: [ul-X](path); Game 1: [gl-Y](path)).
  • lh-* is the mediation layer. It is the only place where universe and game-local references coexist in one row.
  • A ul-* or ud-* file referencing a gl-* file is a layering FAIL.

Canonicity tiers (per-fact)​

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

  • hard canon — committed, non-negotiable.
  • soft canon — intended direction, revisable by explicit decision.
  • proposed — candidate term or mechanism, awaiting user confirmation.
  • bible-only — universe-bible material that must never surface in player-facing content.

Exposure tiers (for lh-* rows) and Game 1 ceiling​

Every lh-* row declares one exposure tier: revealed / hinted / referenced once / hidden. 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, Calling Shrines, surviving-nation artefacts, Earthborn background selection, MC origin. The false-king / heart-fragment fact may reach hinted early and revealed only in a deliberate late-game political reveal.

lh-game1-cosmology-hooks.md MUST contain only hinted, referenced once, or hidden entries — never revealed. lh-game1-world-hooks.md MAY use revealed for in-Zone observables; the underlying cosmological mechanism stays capped at hinted.

Deferred terms (do not invent committed names)​

The following terms appear as PROPOSED TERM: markers in existing files because their canonical names are deferred. Do not invent committed values; preserve the markers exactly:

  • continent name
  • fallen capital name
  • Hero Order name
  • individual god names
  • specific Shield-King NPC name (Shield-King itself is the working title; Bastion King and Warden King are attested variants)
  • Zone Wardheart name
  • surviving-nation names
  • specific Demon Knight names
  • specific True Harm materials

Shroud, Accord of Intervention, Demon Knight, Corebound, Heartbound, Crownfire, Starwells, and the moon labels (White, Red, Black) appear in source material verbatim and are committed as the working canonical labels at proposed canonicity — they may be used in lore text but are flagged with PROPOSED TERM: markers until the user promotes them to soft or hard canon.

When editing existing files in this scope​

Read the file's YAML frontmatter first — prefix: and layer: tell you which layer's rules apply. Cross-references must respect the layer-direction rules above.

When adding a lore link to a gd-* file, route through an lh-* table row. Do not add direct (See lore: [ul-...]; Game 1: [gl-...]) annotations — they are layering violations.

When adding new files in this scope​

Read pr-file-conventions.md in full before authoring. Confirm the prefix, the target subdirectory, the canonicity tiers, and the cross-references match the convention. Add new files in the wave order documented in pr-file-conventions.md § Edit order convention.

If the new file is a non-lore gd-* quest-design doc, decide first whether it is a canonical owner page or a navigation or index view. Use examples/valenar/docs/pr-quest-owner-and-navigation-model.md for that placement decision before choosing a directory.

Tone​

Medieval high-fantasy. Use ritual / divine / leyline vocabulary. Avoid modern / Victorian / industrial / electrical terms except in explicit negative-constraint contexts (e.g. gl-mc-earthborn-backgrounds.md prohibiting industrial dominance).