Quest Owner And Navigation Model

Purpose

This file is the living Valenar-wide convention for concrete quest-related documentation outside lore/ and story/. It defines the difference between canonical owner pages and navigation or index views so future waves can add Quest Threads, Local Quests, Missions, and design-branch docs without re-foldering the tree or duplicating Markdown to satisfy Docusaurus navigation.

Wave O recorded the model before any concrete quest-owner surface existed. Wave M begins the first concrete Quest Thread and design-branch owner docs and adds the minimum identity contract those owner pages follow.

Existing Authorities This Convention Preserves

• systems/gd-quest-and-lore-design.md owns the abstract taxonomy for Act Arc, Quest Thread, Local Quest, Mission, Objective, Clue, and Activity Beat.
• systems/gd-objectives-clues-missions.md owns the live planning vocabulary above the queue.
• lore/adr/ad-0002-lore-docs-migration.md keeps gd-* outside lore/.
• lore/adr/ad-0003-story-content-layer-and-agent-audit.md keeps story prose, branch ledgers, and canon-delta handling in the story layer and preserves the non-canon-by-default rule.
• story/README.md owns story-layer branch ledgers, reveal-ledger workflow, and story artifact governance.

This convention does not replace any of those sources. It only defines where future concrete quest-owner docs and view docs belong.

Core Rule

One durable gameplay object gets one canonical owner page. Additional act, location, faction, package, or journal-facing views link to that owner page. They do not duplicate it.

• A canonical owner page owns the stable design truth for one concrete object.
• A navigation or index view groups links for one audience or browsing path.
• A taxonomy page defines vocabulary and rules, not concrete content ownership.
• A story artifact may reference the object, but it does not become the object's design owner or canon owner.

Canonical Owner Surfaces

The owner surfaces below are top-level siblings under examples/valenar/docs/. Quest Thread and design-branch surfaces are now live. Local Quest and Mission surfaces remain reserved for later waves.

Object class	Canonical owner surface	File kind	Ownership rule
Act Arc	existing acts/ docs	gd-*	acts/gd-act-*.md remain the canonical owners for act arcs and act-level outcome framing.
Quest Thread	quest-threads/	gd-*	A Quest Thread can span acts, so its canonical owner must not live under a single act doc.
Local Quest	reserved local-quests/	gd-*	Local Quests stay act-bounded and locale-bounded, but each Local Quest still gets one owner page rather than being duplicated across act and thread views.
Mission	reserved missions/	gd-*	A Mission gets a standalone owner page when it has a stable identity across more than one act view, thread view, or content package; otherwise it stays embedded in its owning page until promoted.
Design Branch	design-branches/	gd-*	Gameplay branch structure, gates, and downstream design consequences live here. Story prose and story branch ledgers do not move here.
Objective / Clue / Activity Beat	owned by the containing design doc by default	gd-*	These remain distinct layers in the taxonomy, but they do not receive standalone owner pages by default in Wave O.

Navigation And Index Views

Navigation and index views exist to make the same owner pages discoverable from multiple browsing paths.

• acts/ remains the act-view surface. Act docs may summarize which Quest Threads, Local Quests, Missions, and design branches matter in that act, but the act doc is not the canonical home for a cross-act thread.
• systems/ remains the taxonomy and rules surface. System docs explain the model; they do not own concrete quest content.
• Future indexes/ pages may group owner docs by act, location, faction, character, settlement tier, reveal gate, or content package. Indexes are view surfaces only.
• Future content-package docs may add package-local index views, but the owner page for a Quest Thread, Local Quest, Mission, or design branch remains in its reserved owner surface.
• Story-layer ledgers and story prose remain in story/. They may cite the owner docs, but they do not replace design ownership.
• Lore truth remains in lore/. A quest owner page can point to lore exposure authorities through the existing lore governance rules, but it does not move lore truth into the design layer.

Placement Rules

• Do not put a cross-act Quest Thread under acts/ as its canonical home.
• Do not create a default missions/cross-act/ bucket. If material spans acts, either promote it to a Quest Thread or split the Missions into act-specific slices beneath the owning Thread or act view.
• Do not treat a story artifact, story branch ledger, or reveal ledger as the canonical owner for gameplay-design branching.
• Do not move gd-* files into lore/.
• Do not duplicate the same Markdown owner file in multiple sidebar or index categories.
• Do not collapse Act Arc, Quest Thread, Local Quest, Mission, Objective, Clue, Activity Beat, Branch, and Story into one generic bucket.

Minimum Identity / Frontmatter Contract

Each concrete owner doc under quest-threads/, local-quests/, missions/, or design-branches/ must carry enough frontmatter to stay stable through later Docusaurus navigation work without requiring _category_.* metadata in the same wave.

• Required shared fields: prefix, layer, game, status, date
• Required owner fields: owner_kind, owner_key, act_scope
• Optional but recommended when they are already known: parent_arc, appearance_views
• The H1 remains the human-facing display title. The frontmatter identifies the owner doc; it does not turn a taxonomy page or a view page into an owner.

owner_kind records which object class the page owns (quest-thread, local-quest, mission, design-branch). owner_key is the stable machine-readable identity future indexes, sidebars, or generated views can reuse. act_scope records a single act label or cross-act so later navigation work does not have to infer scope from prose.

Docusaurus Navigation Contract

The content model above exists so Docusaurus can expose the same owner page in multiple places without creating duplicate Markdown.

• The canonical owner page carries the stable doc identity.
• Sidebars, sidebar refs, category links, and generated index pages are navigation layers that point to the owner page; they do not fork ownership.
• If an owner page needs to appear in more than one sidebar context, reuse the same doc id and set displayed_sidebar or related sidebar wiring instead of creating a second file.
• Category landing pages and future generated indexes are view surfaces only.
• A view page may summarize why an owner matters in that browsing context, but the detailed design truth stays in the owner page.

Path Stability

• Existing files keep their current paths in Wave O.
• This convention reserves future owner surfaces so later waves do not need to re-folder the existing act, system, lore, or story trees.
• Any future rename or migration remains a separate explicit migration task.

Design-Branch Boundary

Design branches and story branches are related but not interchangeable.

• A design-branch page records gameplay-state divergence, gating, surface consequences, and rejoin rules.
• A story branch ledger records artifact-specific prose continuity and branch tracking in the story layer.
• Story prose remains non-canon-by-default.
• If a branch needs both surfaces, the design owner page and the story ledger must link to each other explicitly rather than merging the layers.

Promotion Rule For Future Waves

Future waves should promote embedded content to a standalone owner page when at least one of the following becomes true:

• the same object needs to appear in more than one act view or index view
• the object has stable identity across more than one content package
• the object owns branch-sensitive design consequences that no longer fit cleanly inside an act summary
• the object needs a stable Docusaurus destination that other docs can link to

Until one of those triggers fires, an act doc or another owner page may carry the concrete content inline. Promotion creates one canonical owner page; it does not create duplicates.