Skip to main content

ADR 0005 — Adopt canonical owner pages and navigation views for concrete quest docs outside lore and story

  • Status: Accepted
  • Date: 2026-05-12
  • Deciders: User (project owner)

Context​

ad-0002-lore-docs-migration.md already decided that gd-* files remain outside examples/valenar/docs/lore/. ad-0003-story-content-layer-and-agent-audit.md then established examples/valenar/docs/story/ as a separate non-canon-by-default story layer with its own branch ledgers and reveal governance.

What remains missing is a placement rule for future concrete quest-design docs: Quest Threads, Local Quests, Missions, and design-branch surfaces that are more specific than the abstract taxonomy in ../../systems/gd-quest-and-lore-design.md and ../../systems/gd-objectives-clues-missions.md.

Without that rule, future waves would be pushed toward three incorrect patterns:

  • putting cross-act Quest Threads under one act as if the act owned them
  • duplicating the same Markdown content into multiple navigation categories to satisfy act, faction, and package browsing
  • leaking gameplay branch ownership into story ledgers or story prose because no separate design-branch surface was reserved

Wave O needs the owner-model decision recorded before any neutral quest-owner subtree is created.

Decision​

Adopt the canonical owner-page versus navigation-view model recorded in ../../pr-quest-owner-and-navigation-model.md.

The model extends and refines ad-0002 as follows:

  • gd-* stays outside lore/, and future concrete quest owner pages also stay outside story/.
  • Act docs in examples/valenar/docs/acts/ remain the canonical owners of Act Arcs and act-level outcome framing, but they are not the canonical home for a cross-act Quest Thread.
  • Future concrete quest owner pages are reserved as top-level siblings under examples/valenar/docs/: quest-threads/, local-quests/, missions/, and design-branches/.
  • Future navigation and index views are reserved as view surfaces rather than owner surfaces. They may include act views, package views, and future indexes/ docs.
  • Story branch ledgers and story prose remain in story/. They do not become the canonical design owners for gameplay branching.
  • Docusaurus sidebars, category links, sidebar refs, and generated indexes are navigation mechanisms over canonical owner pages, not a reason to duplicate Markdown files.

Wave O records the model only. It does not create the reserved directories, owner pages, index pages, or Docusaurus metadata files.

Rationale​

  • Cross-act ownership needs a neutral home. A Quest Thread that spans more than one act cannot be canonically owned by one act page without distorting the model.
  • Navigation multiplicity is not content multiplicity. Docusaurus can show the same owner page from more than one sidebar or landing page; the correct response is navigation wiring, not duplicate Markdown.
  • The distinct layers stay distinct. Act Arc, Quest Thread, Local Quest, Mission, Objective, Clue, Activity Beat, design branch, story artifact, and lore truth each keep separate ownership boundaries.
  • Story remains story. ad-0003 established branch ledgers and non-canon story artifacts for narrative work. This ADR preserves that boundary instead of using story files as gameplay-design owners.
  • Future content packages need stable anchors. A package-specific act view or faction view can point at canonical owners without forcing a later repository reshuffle.

Alternatives considered and rejected​

  • Make acts/ the canonical home for every quest-shaped object. Rejected. Cross-act Quest Threads would either be mis-owned by one act or duplicated across multiple act pages.
  • Duplicate the same Markdown file into multiple sidebar categories. Rejected. The duplication would create drift between act, location, faction, and package views.
  • Use missions/cross-act/ as the default multi-act bucket. Rejected. Multi-act material is either a Quest Thread or a set of act-specific mission slices; a default cross-act mission bucket hides that distinction.
  • Move concrete quest docs into lore/. Rejected. ad-0002 already fixed the gd-* boundary outside the lore tree.
  • Use story branch ledgers as the branch design source of truth. Rejected. Story branch ledgers track prose artifacts, not gameplay-design ownership.

Consequences​

  • Future quest-design waves have a committed owner/view architecture before any new quest-owner subtree is created.
  • Existing paths remain unchanged.
  • examples/valenar/docs/README.md can route readers to owner-model governance without pretending current act or system docs already own every future quest artifact.
  • .claude/rules/lore-conventions.md can direct gd-* authors toward the new owner-model convention while preserving the lore-tree naming rules.
  • Story prose remains non-canon-by-default and stays outside the canonical gameplay owner surfaces.

Explicit deferrals​

  • This ADR does not create any concrete Quest Thread, Local Quest, Mission, or design-branch owner docs.
  • This ADR does not create _category_.*, sidebar configuration, or generated index files.
  • This ADR does not rename, move, or migrate any existing doc.
  • This ADR does not invent quest canon, NPCs, branch outcomes, or story prose.

References​

  • ad-0002-lore-docs-migration.md (same directory) — established that gd-* remains outside lore/.
  • ad-0003-story-content-layer-and-agent-audit.md (same directory) — established the story layer and its non-canon-by-default rule.
  • ../../pr-quest-owner-and-navigation-model.md — the living Valenar-wide convention this ADR adopts for future owner and view placement.
  • ../../systems/gd-quest-and-lore-design.md — taxonomy authority for quest sizes and types.
  • ../../systems/gd-objectives-clues-missions.md — planning vocabulary authority.