Valenar Story Layer

This tree holds story artifacts for Valenar: diary entries, letters, reports, inscriptions, ledgers, fragments, scene packages, and other readable or playable narrative surfaces. These files are not truth-layer canon by default. Story prose can contain limited point of view, rumor, omission, bias, propaganda, or deliberate concealment. Canon truth remains externalized in the authority files under ../lore/ and the design contracts under ../.

Ownership Boundary

What belongs here:

• story drafts and accepted story artifacts
• frontmatter that declares reveal scope, branch scope, audits, and canon-delta status
• indexes that track entity continuity, chronology, reveal gating, branch-sensitive consequences, and proposed canon changes
• downstream playable-lore hooks that connect a story artifact to clues, missions, locations, sites, Journal readback, or world-state change

What does not belong here:

• canon truth updates; those belong in the cited ul-*, ud-*, gl-*, and lh-* authority files under ../lore/
• mechanics or runtime truth; those belong in ../gd-canon.md, the ../systems/ docs, the ../ux/ docs, or other accepted design/process surfaces
• .secs source, Generated provenance, compiler/lowering claims, or runtime behavior claims
• silent canon promotion, reveal-tier escalation, or branch consequences that are not logged explicitly

Tree Layout

• drafts/ - in-progress story artifacts. Drafts are non-authoritative and may still fail story, reveal, or branch review.
• accepted/ - story artifacts that passed all required audits and have their indexes updated. Acceptance does not promote the story text into canon by itself.
• templates/story-entry-template.md - reusable entry template with the required frontmatter shape.
• indexes/entity-index.md - recurring people, places, factions, sites, artifacts, and symbols used by story entries.
• indexes/timeline-index.md - chronological placement and sequencing.
• indexes/reveal-ledger.md - reveal gating and exposure tracking.
• indexes/branch-ledger.md - branch boundaries and consequence tracking.
• indexes/canon-delta-log.md - proposed canon changes and their follow-up targets.

Source-Of-Truth Authorities

Story files must cite existing authority surfaces instead of restating their contents.

Primary lore and reveal authorities:

• ../lore/universe/ul-cosmology.md
• ../lore/universe/ul-divine-layer.md
• ../lore/universe/ul-shroud.md
• ../lore/universe/ul-demon-cycle.md
• ../lore/universe/ul-demon-cosmology.md
• ../lore/universe/ul-demon-king-remains.md
• ../lore/universe/ul-wardhearts-and-nexuses.md
• ../lore/universe/ul-hero-calling.md
• ../lore/universe/ud-world-law.md
• ../lore/hooks/lh-game1-cosmology-hooks.md
• ../lore/hooks/lh-game1-world-hooks.md

Relevant design and readback authorities for playable-lore consequences:

• ../systems/gd-quest-and-lore-design.md
• ../systems/gd-objectives-clues-missions.md
• ../ux/gd-journal.md
• ../gd-canon.md

Caution surfaces that require explicit exposure discipline:

• ../lore/local/gl-game1-demon-remains.md
• ../lore/local/gl-game1-old-hero-traces.md
• ../lore/local/gl-game1-false-king.md

Drafts vs Accepted

• Drafts may explore voice, document shape, and playable consequence framing, but they still need full frontmatter and must not pretend to be canon truth.
• Accepted entries are story artifacts that passed story, reveal, and branch audits and have corresponding rows in the relevant indexes.
• Accepted means the artifact is approved as a story surface. It does not mean the artifact's claims became canon automatically.
• Moving a file from drafts/ to accepted/ requires the frontmatter to be complete, the audit block to show passing review, and the related index rows to be updated.

Required Frontmatter

Every story entry uses the template in templates/story-entry-template.md and must include the following YAML frontmatter fields.

Field	Purpose	Notes
title	Artifact-facing title for the story document.	Required as part of the story-document identity contract from ADR 0003.
entry_id	Stable identifier for the story artifact.	Use the same identifier in every index row.
status	Workflow state for the file.	Typical values are draft, under-audit, accepted, or superseded.
format	Artifact classification.	Examples: diary-entry, letter, report, inscription, ledger, scene-package.
pov	Point-of-view and knowledge limit.	Use this to preserve uncertainty and prevent omniscient leakage.
act	Act scope for the artifact.	Use a single act, act range, or cross-act when justified.
location	Primary place, route, or site context.	If the place is unknown in-world, say so explicitly instead of inventing certainty.
branch	Branch key or linear.	Every entry must declare branch scope even when it is non-branching.
canon_tier	Declared canon impact for this artifact.	Use none when no canon change is proposed. If a change is proposed, treat it as explicit proposal metadata rather than automatic truth.
exposure_tier	Highest player-facing reveal level the artifact may surface.	Must not exceed the cited lh-* authority rows.
preconditions	Required discoveries, world states, or prior entries.	Keep reveal and branch gates explicit.
asserted_facts	In-world claims made by the artifact.	Distinguish what the artifact says from what the authority files confirm.
revealed_to_player	What the player can actually learn from this artifact.	Keep the player-facing reveal narrower than any hidden author knowledge.
touched_lore	Authority files and caution surfaces this entry depends on.	Cite exact lore/design files rather than paraphrasing them into story truth.
downstream_hooks	Playable consequences created by the artifact.	Link the artifact to clues, missions, Journal entries, sites, or world-state changes.
audit	Story, reveal, and branch audit state.	Keep each audit explicit; acceptance requires all three to pass.
canon_delta	Explicit declaration of whether this artifact proposes a canon change.	none is valid and should be common. Proposed changes must also be logged in indexes/canon-delta-log.md.

Audit Workflow

1. Author the artifact in drafts/ using the required frontmatter.
2. Run the structural validator: python3 ../../../../tools/valenar-story-audit/validate-story-docs.py or ../../../../scripts/validate-valenar-story-docs.sh.
3. Run the story audit: voice consistency, structure, artifact identity, and alignment with cited sources.
4. Run the reveal audit: check cited ul-*, ud-*, gl-*, and lh-* authorities; confirm the entry does not exceed allowed exposure.
5. Run the branch audit: confirm branch scope, prerequisites, consequence surfaces, and any rejoin plan are explicit.
6. Update the indexes, then move the file to accepted/ only after all three audits pass.

Passing audits approves the artifact as a story document. It does not authorize runtime support, .secs lowering, or lore/design truth updates.

Structural Validator

The committed structural validator lives at ../../../../tools/valenar-story-audit/validate-story-docs.py. A thin repo-style wrapper lives at ../../../../scripts/validate-valenar-story-docs.sh.

The validator machine-checks only deterministic structure:

• required frontmatter keys and nested audit / canon_delta blocks
• required story-template section headings
• duplicate entry_id values across drafts/ and accepted/
• touched_lore and canon_delta.target_authorities path existence
• committed exposure_tier values from ../lore/pr-file-conventions.md
• ledger coverage in timeline-index.md, reveal-ledger.md, branch-ledger.md, conditional canon-delta-log.md, and entity-index.md for accepted entries
• accepted-entry strictness for audit.story.status, audit.reveal.status, and audit.branch.status
• placeholder-only index rows only while the ledger is otherwise empty

The validator does not judge prose quality, reveal adequacy against nuanced authority interpretation, branch design quality, or canon-promotion merit. Those remain separate story, reveal, and branch audit responsibilities.

Canon-Delta Workflow

• Story artifacts may propose canon implications, but they may not update canon truth on their own.
• If canon_delta is anything other than none, add a row to indexes/canon-delta-log.md naming the target authority files and the follow-up wave or review surface.
• A story artifact can be accepted while its canon proposal remains pending, rejected, or deferred. The story layer records the proposal; the truth layer decides it elsewhere.
• Never promote a fact from story prose into ../lore/ or ../gd-* implicitly.

Reveal-Tier Workflow

• Every entry declares exposure_tier and cites the authority rows that allow that exposure.
• revealed_to_player records the actual player-facing outcome for the entry.
• indexes/reveal-ledger.md records the gap between the allowed exposure and the actual surfaced reveal, plus the gate that made it legal.
• bible-only truth remains hidden. Do not surface it through accepted story prose.
• If an entry touches a caution surface, the reveal audit notes must explain why the exposure remains within the allowed tier.

Branch-Ledger Workflow

• Every entry declares a branch value, including linear for non-branching content.
• Every accepted entry gets a row in indexes/branch-ledger.md so branch scope stays explicit even when the answer is "no branch divergence".
• Branch-sensitive entries must name the decision boundary, prerequisites, consequence surfaces, and any rejoin or permanent split rule.
• downstream_hooks in the entry and the branch-ledger row should agree. If they disagree, the artifact is not ready for acceptance.

The Five Indexes

• indexes/entity-index.md - continuity tracker for recurring entities across drafts and accepted artifacts.
• indexes/timeline-index.md - chronological placement, sequencing, preconditions, and outcomes.
• indexes/reveal-ledger.md - exposure control, reveal gates, and player-facing knowledge.
• indexes/branch-ledger.md - branch keys, divergence points, consequence tracking, and rejoin status.
• indexes/canon-delta-log.md - proposed truth-layer changes and their follow-up path.

An accepted story artifact is incomplete if its frontmatter points to indexes that were not updated.

Playable-Lore Connection

Valenar's lore is playable. Story artifacts therefore need explicit downstream consequences rather than flavor-only prose. Use the existing quest and Journal contracts to place an artifact in the playable-lore chain:

ruin -> clue -> investigation -> artifact -> partial truth -> new quest -> world-state change

Not every artifact owns every step, but every artifact should say where it sits in the chain and what it unlocks next. If an entry has no downstream_hooks, it is not ready for acceptance.

Explicit Deferrals

• This tree is Markdown-only. It does not claim .secs, Generated, runtime, or compiler support.
• No lore/design authority files are updated from this tree.
• No broader docs navigation changes are made in this wave.
• No dedicated filename prefix is introduced for story files in this wave.
• The committed structural validator is intentionally narrow. Prose quality, reveal judgment, branch judgment, and truth-layer canon decisions remain separate read-only audit or review responsibilities.

Deviations

No scope deviation is recorded in this scaffold. The explicit deferrals above match ADR 0003 and keep Wave S inside the new story layer only.