Valenar Docs

Canonical documentation for the Valenar example game.

This tree is organized by stable owner surfaces plus navigation views. Use the first-pass path below for live reading, then branch into the topical clusters you need.

Start Here

• gd-canon.md - canonical act names, progression boundaries, Nexus/Wardheart wording, and live behavior vocabulary.
• gd-glossary.md - shared terms for acts, Core/Camp/Settlement distinctions, polity ladder terms, and planning vocabulary.

Read these two pages first. If a support contract still carries older prototype wording, canon and glossary wording controls.

Surface Legend

• Canonical owner surface - one Markdown file owns one design, lore, or story object. Other docs link to it instead of duplicating it.
• Navigation / view surface - act views, indexes, generated landings, and other reader-facing groupings that point at canonical owners without taking over ownership themselves.
• Current contract - the canon, glossary, acts, systems, generation, catalogs, and current UX contracts in this tree.
• Intended source surface - examples/valenar/Content/*.secs. Future designer-facing source.
• Current executable stand-in - examples/valenar/Generated/*.cs. Hand-written stand-ins the runtime consumes today.
• Compiler / shared-language backlog - workspace docs/design/ plus SECS-Compiler-Plan.md. Secondary for Valenar readers unless a doc explicitly sends you there.
• Working docs - implementation/pr-roadmap.md, implementation/pr-wave-template.md, and implementation/pr-docs-codegen-rules.md.
• Proposal-only docs - any page explicitly labeled proposal in the index below.

Ownership And Navigation Governance

• pr-quest-owner-and-navigation-model.md - living Valenar-wide convention for canonical owner pages versus act views, index views, and future Docusaurus navigation reuse for Quest Threads, Local Quests, Missions, and design branches.
• lore/adr/ad-0005-owner-pages-and-navigation-views.md - accepted decision that extends the gd-* placement rule from ADR 0002 so future concrete quest owners stay outside lore/ and story/ while navigation stays view-only.
• story/README.md - story-layer boundary, branch-ledger ownership, and the rule that story prose is not canon by default.
• systems/gd-quest-and-lore-design.md and systems/gd-objectives-clues-missions.md - the taxonomy and planning-vocabulary authorities this owner model preserves.

Quest Owners

• quest-threads/gd-quest-thread-index.md - canonical Quest Thread owner surface.
• quest-threads/gd-quest-thread-act-0-survive.md - Act 0's first visible multi-part survival thread.
• quest-threads/gd-quest-thread-act-0-the-old-stones.md - the Act 0 observation-earned lead chain.
• quest-threads/gd-quest-thread-act-0-the-ruin-beneath.md - the Act 0 buried-ruin interpretation thread.
• quest-threads/gd-quest-thread-act-0-make-this-place-hold.md - the late-threshold Act 0 stabilization thread.
• design-branches/gd-design-branch-index.md - gameplay-branch owner surface.
• design-branches/gd-design-branch-act-0-lost-hours.md - the failure-forward missing-time branch attached to Survive.

Local Quest and Mission owner surfaces remain reserved for later waves; until promotion, Local Quest guidance stays in pr-quest-owner-and-navigation-model.md and systems/gd-quest-and-lore-design.md, while current Mission appearance and planning vocabulary live in acts/gd-act-0-mission-spine.md and systems/gd-objectives-clues-missions.md.

Generated provenance stays strict: a generated file either cites a real Content/ source, uses an auto-generated marker, or uses the canonical no-source stand-in marker. Valenar docs should not invent a compiler run or a .secs source relationship.

First-pass path

• gd-canon.md
• gd-glossary.md
• acts/act-0-arrival-and-core.md
• acts/act-0-mission-spine.md
• acts/act-1-first-people.md
• acts/act-2-first-outpost.md
• systems/locations-features-sites.md
• systems/settlements-and-outposts.md
• systems/core-base.md
• systems/camp.md
• queue and activity execution
• systems/world-pressure-nexus.md
• generation/world-generation-contract.md
• generation/location-generation-contract.md
• generation/feature-generation-contract.md
• ux/shell-screen-model.md
• ux/location-dossier.md
• ux/current-plan.md
• ux/journal.md

Quick Clusters

• Character Model: gd-canon.md, gd-glossary.md, systems/character-skills.md, systems/characters-and-retinue.md, and ux/character-screen.md.
• Planning Vocabulary: gd-canon.md, gd-glossary.md, queue and activity execution, systems/objectives-clues-missions.md, ux/current-plan.md, ux/journal.md, ux/objectives-screen.md, and ux/queue-screen.md.

Lore

• lore/pr-file-conventions.md - prefix scheme, cross-layer rules, canonicity and exposure tier definitions, Game 1 reveal-tier ceiling.
• lore/adr/ - accepted lore-tree ADRs, including the decision to keep ADRs in a dedicated folder.
• lore/universe/ul-cosmology.md - entry point for the ul-* universe lore set (cross-game canon: cosmology, demon cycle, hero calling, Wardhearts, super-world structure). The universe-design counterpart is lore/universe/ud-world-law.md.
• lore/local/gl-afterwar-state.md - entry point for the gl-* game-local lore set for Valenar (Game 1): Afterwar state, MC Corebound origin, Earthborn backgrounds, demon remains, false-king arc, surviving nations, old hero traces, and cosmology traces.
• lore/hooks/lh-game1-world-hooks.md - entry point for the lh-* exposure tables that map universe-scope facts to where, when, and how they surface in Game 1.

Story

• story/README.md - story-layer boundary, required frontmatter, audit flow, and the rule that story prose is not canon by default.
• story/templates/story-entry-template.md - reusable frontmatter and review skeleton for story drafts and accepted artifacts.
• Indexes: entity, timeline, reveal ledger, branch ledger, and canon-delta log.
• implementation/llm-story-authoring-pipeline.md - thin local-agent process contract for story drafting, read-only audits, and acceptance routing.

Acts

• acts/act-0-arrival-and-core.md - MC-alone survival, first temporary camp routines, the dormant Nexus/Wardheart, and establishing the Core.
• acts/act-0-mission-spine.md - authored Act 0 mission ladder from Survive through establishing the Core, with spoiler-safe naming thresholds and surface-integration notes.
• acts/act-1-first-people.md - rescues, escorts, guest quarters, the first household or retinue, and early character assignments.
• acts/act-2-first-outpost.md - the first population-bearing site, the first Outpost-tier Settlement, and the start of the settlement layer.
• acts/act-3-settlement.md - broader settlement growth, districts, labor, buildings, and stable population-scale play.
• acts/act-4-banner-network.md - connected settlements, defended routes, and governor-scale expansion.
• acts/act-5-province.md - Province administration, taxation, and standing forces.
• acts/act-6-crown.md - crown-scale rule, national policy, diplomacy, and fronts.
• acts/act-7-reclamation.md - late-game reclamation, Realm projects, and other-Zone reach.

Act docs are the canonical owners for Act Arcs and act-level outcome framing. They are also view surfaces for quest content that matters inside that act. A future cross-act Quest Thread or reusable Mission should link in from the act view rather than moving its canonical owner under acts/.

Systems

• queue and activity execution - activity vocabulary, queue semantics, and policy-shaped execution.
• systems/objectives-clues-missions.md - objectives, clues, missions, and activity planning vocabulary.
• systems/quest-and-lore-design.md - quest structure, lore surfacing, and player-facing clue cadence.
• systems/characters-and-retinue.md - the MC, named companions, leaders, and small personal groups.
• systems/character-skills.md - character growth, training, and assignment-facing skill design.
• systems/core-base.md - the fixed personal Core anchored on the starting Nexus/Wardheart.
• systems/camp.md - the mobile Camp, its modules, and expedition sustainment.
• systems/locations-features-sites.md - the Location model plus feature and site ownership.
• systems/sites-and-dungeons.md - site families, dungeons, and enterable place handling.
• systems/settlements-and-outposts.md - settlement tiers, connected footprint, districts, and outposts.
• systems/settlement-buildings-economy.md - building families, economic layers, and settlement-side production.
• systems/resources-items-crafting.md - resources, items, recipes, tools, and crafting direction.
• systems/corruption-reclamation.md - corruption pressure, cleansing, and reclamation loops.
• systems/world-pressure-nexus.md - the Ancient Shield, gates, taint, Nexus rules, and escalation.
• systems/realm-ranks-and-polity.md - polity ladder above settlements, founding tier, and crown-scale capabilities.
• systems/tags-and-classification.md - tag namespace rules, modifier vs structural-predicate split, and Feature category distinction.
• systems/state-axes-and-thresholds.md - Feature discovery, Location knowledge, and Site state axes with committed labels and target thresholds.

Generation

• generation/world-generation-contract.md - world-data import boundary, scale budget, determinism, and validation.
• generation/location-generation-contract.md - Location facts, topology, terrain composition, and knowledge inputs.
• generation/feature-generation-contract.md - feature placement, discovery, activities, rewards, and site conversion.
• generation/start-location-contract.md - the opening pocket, starting anchor chain, and first-play survivability.

UX

• ux/shell-screen-model.md - shell ownership, compact vs expanded behavior, and map-first layout rules.
• ux/current-plan.md - the synthesized top layer above Objectives and Queue.
• ux/journal.md - the persistent day-based memory layer for readable narrative readback, annotations, and links back into planning and world surfaces.
• ux/location-dossier.md - the dossier workspace for Locations, features, threats, and sites.
• ux/objectives-screen.md - the planning workspace for objectives, clues, missions, and current-plan context.
• ux/queue-screen.md - atomic activity inspection, scheduling, and progress readouts.
• ux/core-screen.md - the Core-facing management surface.
• ux/camp-screen.md - the Camp-facing module, loadout, and readiness surface.
• ux/character-screen.md - the MC and named-character surface for channels, skills, gear, and roles.
• ux/settlement-screen.md - the settlement-facing surface for footprint, districts, buildings, and administration.
• ux/combat-dungeon-screen.md - proposal only; not part of the current client contract.

Catalogs

• activity catalog - grounded activity families already supported by the docs.
• catalogs/feature-catalog.md - grounded feature families and example map content.
• catalogs/site-catalog.md - grounded site families and development endpoints.
• catalogs/dungeon-catalog.md - dungeon archetypes and their relationship to sites.
• catalogs/core-building-catalog.md - Core-side building families and unlock direction.
• catalogs/camp-building-catalog.md - Camp modules and expedition tradeoffs.
• catalogs/settlement-building-catalog.md - settlement building families by function and scale.
• catalogs/character-archetype-catalog.md - named-character and leadership archetypes.
• catalogs/item-resource-catalog.md - current resource, item, tool, and special-material families.
• catalogs/tag-catalog.md - committed and planned Valenar tags, with canonical id strings and one-line semantics.

Working And Proposal Surfaces

• implementation/roadmap.md - current implementation surfaces, prototype boundaries, and near-term focus.
• implementation/docs-codegen-rules.md - how docs should describe Content, Generated, and future compiler lowering.
• implementation/wave-template.md - reusable wave brief template; working process doc, not live game canon.
• implementation/status-and-sync-policy.md - status vocabulary and per-doc status block format.
• implementation/code-sync-audit.md - drift tracker between docs/Content/Generated/Host/Server/Client/src/tests; populated by waves.
• implementation/open-questions.md - open questions surfaced by waves, awaiting user decision or ADR.
• implementation/llm-story-authoring-pipeline.md - thin process contract for local-agent story drafting, read-only audits, and acceptance flow.
• implementation/wave-roadmap.md - pending-wave dispatch plan; tier dependencies, dispatch graph, and ADR thread stubs.

Working Rules

• Acts are the canonical progression frame.
• Core, Camp, Settlement, and Outpost are distinct systems.
• Founding the Core does not create the Settlement or the player-facing Realm.
• Sites are first-class; dungeons are one site family once discovered or entered.
• Named characters have skills and assignments; pops fill ordinary settlement jobs.
• Current Plan sits above Objectives and Queue.
• Objective, clue, mission, planning context, and activity remain distinct.
• Live behavior vocabulary uses activity and policy; higher-level planning docs do not promote a separate executable term above activities.
• Live behavior vocabulary uses activity and policy.
• The current executable map is a stepping-in prototype fixture, not the final world-scale commitment.