docs(docs): add frontmatter to all design docs

Standardized YAML frontmatter on all 40 docs/design/ files with title, description, type, status, ticket, decision_refs, and author fields. Covers specs, wireframes, voice cards, spatial layouts, and system designs. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-03-13 15:22:17 +01:00
parent 4525e0a4bc
commit 934d4df4b0
40 changed files with 480 additions and 0 deletions
@@ -1,3 +1,15 @@
+---
+title: "Access Tier Shift Design Document"
+description: "Rules for when and how player character access tiers change with NPCs during v0.1 play"
+type: design
+status: draft
+ticket: "#328"
+decision_refs: [D-028, D-033, D-035, D-062, D-063, D-064, D-075]
+author: "Paula"
+created: 2026-02-20
+updated: 2026-02-20
+---
+
 # Access Tier Shift Design Document

 **Ticket:** #328 | **Feeds:** #169 (Layer 1 access tier filtering, S15)
@@ -1,3 +1,15 @@
+---
+title: "Character Build: The Smuggler"
+description: "Full character definition for the smuggler playable character including knowledge, relationships, and voice"
+type: design
+status: draft
+ticket: "#180"
+decision_refs: [D-005, D-016, D-027, D-028, D-032, D-034, D-035, D-037, D-041, D-053, D-065]
+author: ""
+created: 2026-02-19
+updated: 2026-02-19
+---
+
 # Character Build: The Smuggler

 **Ticket:** #180 | **Priority:** Critical | **Sprint:** 12
@@ -1,3 +1,15 @@
+---
+title: "Character Definition Schema"
+description: "Canonical schema for playable character definitions covering identity, knowledge, relationships, and presentation"
+type: design
+status: draft
+ticket: "#179"
+decision_refs: [D-005, D-016, D-027, D-028, D-032, D-034, D-035, D-041, D-065]
+author: ""
+created: 2026-02-19
+updated: 2026-02-19
+---
+
 # Character Definition Schema

 **Ticket:** #179 | **Priority:** Critical | **Sprint:** 12
@@ -1,3 +1,15 @@
+---
+title: "Content Directory Structure"
+description: "Source of truth for the content/ directory layout, schemas, validation pipeline, and mod-compatible conventions"
+type: design
+status: active
+ticket: "#384"
+decision_refs: [D-024, D-027, D-028, D-032, D-034, D-035, D-036, D-049, D-057]
+author: ""
+created: 2026-02-19
+updated: 2026-02-19
+---
+
 # Content Directory Structure — The Settled Reach v0.1

 **Ticket:** #384 (blocks #385: directory skeleton, #386: schema definitions)
@@ -1,3 +1,15 @@
+---
+title: "Content Structure — Canonical Template (v0.2+)"
+description: "Post-cleanup canonical directory layout for campaign content, superseding v0.1 content-directory-structure"
+type: design
+status: active
+ticket: "#656"
+decision_refs: [D-117, D-138]
+author: ""
+created: 2026-03-13
+updated: 2026-03-13
+---
+
 # Content Structure — Canonical Template (v0.2+)

 **Created:** 2026-03-13 (Sprint 26, #656 cleanup)
@@ -1,3 +1,15 @@
+---
+title: "Contraband Specification — Lattice Components & Supply Chain"
+description: "Defines contraband types, supply chain mechanics, terminology, and detection/evasion methods for the smuggling ring"
+type: design
+status: active
+ticket: "#321"
+decision_refs: [D-017, D-036, D-037]
+author: "Miri"
+created: 2026-02-19
+updated: 2026-02-19
+---
+
 # Contraband Specification — Lattice Components & Supply Chain
 **Ticket:** #321
 **Author:** Miri
@@ -1,3 +1,15 @@
+---
+title: "Divergent Relationships"
+description: "Comparison of smuggler vs detective starting relationship webs, access tiers, and social site coverage"
+type: design
+status: draft
+ticket: "#183"
+decision_refs: [D-005, D-027, D-028, D-029, D-033, D-075]
+author: ""
+created: 2026-02-19
+updated: 2026-02-19
+---
+
 # Divergent Relationships

 **Ticket:** #183 | **Priority:** Critical | **Sprint:** 12
@@ -1,3 +1,15 @@
+---
+title: "Entity Color System — Visual Specification"
+description: "Canonical palette and rendering rules for relationship-based entity colors derived from D-033"
+type: design
+status: active
+ticket: "#304"
+decision_refs: [D-033, D-043, D-044, D-048, D-049, D-059, D-060]
+author: "Araminta"
+created: 2026-02-20
+updated: 2026-02-20
+---
+
 # Entity Color System — Visual Specification

 **Version:** v0.1 (Sprint 14)
@@ -1,3 +1,15 @@
+---
+title: "Environmental Text Visual Standards"
+description: "Visual rules for signage, terminals, and news tickers rendered as world-layer text in Sova Transit"
+type: design
+status: active
+ticket: "#334"
+decision_refs: [D-036, D-043, D-044, D-049, D-051, D-066]
+author: "Araminta"
+created: 2026-02-20
+updated: 2026-02-20
+---
+
 # Environmental Text Visual Standards

 **Version:** v0.1 (Sprint 14)
@@ -1,3 +1,15 @@
+---
+title: "Faction Mechanics Reference"
+description: "Quick reference for six-faction gameplay systems including resources, blind spots, and reputation mechanics"
+type: design
+status: active
+ticket: ""
+decision_refs: []
+author: ""
+created: 2026-02-19
+updated: 2026-02-19
+---
+
 # Faction Mechanics Reference

 Quick reference for how the six factions work as gameplay systems.
@@ -1,3 +1,15 @@
+---
+title: "First 5 Minutes Experience Design"
+description: "Systemic opening sequence design for both characters covering triggers, beat sequences, and seed variants"
+type: design
+status: active
+ticket: "#259"
+decision_refs: [D-027, D-032, D-041]
+author: "Paula"
+created: 2026-02-19
+updated: 2026-02-19
+---
+
 # First 5 Minutes Experience Design

 **Ticket:** #259
@@ -1,3 +1,15 @@
+---
+title: "Flat NPC Memorable Trait Pass"
+description: "Design for three flat NPCs (Pael, Ren, Tev) with memorable traits and plausible-misdirection dialogue"
+type: design
+status: draft
+ticket: "#307"
+decision_refs: [D-024, D-029]
+author: "Paula"
+created: 2026-02-19
+updated: 2026-02-19
+---
+
 # Flat NPC Memorable Trait Pass

 **Ticket:** #307 | **Priority:** High | **Sprint:** 12
@@ -1,3 +1,15 @@
+---
+title: "Insert/HUD Wireframe and Visual Specification — v0.1"
+description: "Neural lattice insert HUD layout, entity markers, border arrows, and interaction states for the diegetic UI"
+type: design
+status: active
+ticket: "#314"
+decision_refs: [D-013, D-014, D-019, D-031, D-033, D-048, D-049, D-051, D-056, D-057, D-059, D-065, D-066, D-117]
+author: "Araminta"
+created: 2026-02-24
+updated: 2026-03-13
+---
+
 # Insert/HUD Wireframe and Visual Specification — v0.1

 **Ticket:** #314
@@ -1,3 +1,15 @@
+---
+title: "Interaction Verb Specification v0.1"
+description: "Seven interaction verbs, single context-sensitive action button, and verbs[] architecture for player-world interaction"
+type: design
+status: active
+ticket: "#402"
+decision_refs: [D-005, D-011, D-015, D-027, D-028, D-032, D-035, D-041, D-044, D-051, D-054, D-060]
+author: ""
+created: 2026-02-12
+updated: 2026-02-12
+---
+
 # Interaction Verb Specification v0.1

 **Ticket:** #402
@@ -1,3 +1,15 @@
+---
+title: "Knowledge Flags — v0.1 Quick Reference"
+description: "Quick reference of valid fact IDs, prerequisite formats, and starting knowledge for monologue content authoring"
+type: design
+status: active
+ticket: "#309"
+decision_refs: [D-028, D-035, D-041, D-075]
+author: ""
+created: 2026-02-19
+updated: 2026-02-19
+---
+
 # Knowledge Flags — v0.1 Quick Reference

 **For:** Mellanie (content authoring), Paula (narrative design)
@@ -1,3 +1,15 @@
+---
+title: "Knowledge Vocabulary for v0.1 Content"
+description: "Full specification of confidence levels, entity knowledge, fact categories, and prerequisite formats for the knowledge graph"
+type: design
+status: active
+ticket: "#368"
+decision_refs: [D-028, D-035, D-041, D-075]
+author: ""
+created: 2026-02-19
+updated: 2026-02-19
+---
+
 # Knowledge Vocabulary for v0.1 Content

 **Source:** D-041 (Knowledge Graph Data Model), D-035 (Tag Taxonomy), D-028 (Dialogue Architecture), D-075 (Dialogue Filtering)
@@ -1,3 +1,15 @@
+---
+title: "Layer 2: Situation-to-Relationship-History Mapping"
+description: "How InteractionMemory maps to D-028 Layer 2 situation activation and relationship-aware greeting selection"
+type: design
+status: active
+ticket: "#170"
+decision_refs: [D-028, D-035]
+author: "Paula"
+created: 2026-02-21
+updated: 2026-02-21
+---
+
 # Layer 2: Situation-to-Relationship-History Mapping

 **Ticket:** #170 | **Sprint:** 15 | **Author:** Paula
@@ -1,3 +1,15 @@
+---
+title: "Meridian Coverage Map — Sova Transit District"
+description: "Zone-by-zone Meridian network coverage map with gameplay implications for investigation and smuggling"
+type: design
+status: active
+ticket: "#335"
+decision_refs: [D-017, D-018, D-036, D-037]
+author: "Miri"
+created: 2026-02-19
+updated: 2026-02-19
+---
+
 # Meridian Coverage Map — Sova Transit District
 **Ticket:** #335
 **Author:** Miri
@@ -1,3 +1,15 @@
+---
+title: "Mirror Moment Design Document"
+description: "Seven core mirror moments where the same trigger fires different monologue for smuggler and detective"
+type: design
+status: active
+ticket: "#329"
+decision_refs: [D-032, D-034, D-039]
+author: ""
+created: 2026-02-19
+updated: 2026-02-19
+---
+
 # Mirror Moment Design Document

 **Ticket:** #329
@@ -1,3 +1,15 @@
+---
+title: "Monologue Content Architecture"
+description: "Authoring contract for internal monologue: interpretive frames, five categories, trigger mappings, volume targets, and prerequisite design"
+type: design
+status: active
+ticket: "#253"
+decision_refs: [D-016, D-032, D-034, D-035, D-041]
+author: "Mellanie"
+created: 2026-02-20
+updated: 2026-02-20
+---
+
 # Monologue Content Architecture

 **Ticket:** #253
@@ -1,3 +1,15 @@
+---
+title: "Monologue Display System — Visual Specification"
+description: "Typography, positioning, stacking, priority, and fade animation rules for monologue text rendering"
+type: design
+status: active
+ticket: "#315"
+decision_refs: [D-016, D-033, D-043, D-044, D-049, D-061, D-066, D-067]
+author: "Araminta"
+created: 2026-02-19
+updated: 2026-02-20
+---
+
 # Monologue Display System — Visual Specification

 **Version:** v0.1 (Sprint 13, updated Sprint 14)
@@ -1,3 +1,15 @@
+---
+title: "Opening Hook Content Per Character"
+description: "Authored monologue and dialogue content for each character's first 3-4 minutes across seed variants A-D"
+type: design
+status: draft
+ticket: "#260"
+decision_refs: [D-032, D-035, D-039, D-053, D-064]
+author: "Paula"
+created: 2026-02-19
+updated: 2026-02-23
+---
+
 # Opening Hook Content Per Character

 **Ticket:** #260 | **Priority:** High | **Sprint:** 12
@@ -1,3 +1,15 @@
+---
+title: "PC-as-NPC Unified Specification"
+description: "Defines how each playable character exists as an NPC when the other character is played"
+type: design
+status: draft
+ticket: "#381"
+decision_refs: [D-027, D-029, D-032, D-034, D-035, D-039, D-045]
+author: ""
+created: 2026-02-12
+updated: 2026-02-13
+---
+
 # PC-as-NPC Unified Specification

 **Ticket:** #381 | **Priority:** High | **Sprint:** 3
@@ -1,3 +1,15 @@
+---
+title: "Placeholder Art Specification v0.1"
+description: "Technical requirements for procedural placeholder art assets with zero image files"
+type: design
+status: active
+ticket: "#133"
+decision_refs: [D-043, D-046, D-047, D-049, D-066]
+author: "Araminta"
+created: 2026-02-19
+updated: 2026-02-19
+---
+
 # The Settled Reach — Placeholder Art Specification v0.1

 **Version:** v0.1 (Sprint 12)
@@ -1,3 +1,15 @@
+---
+title: "Smuggler Moral Arc Spec"
+description: "Four-phase moral trajectory for the smuggler through the v0.1 vertical slice, driven by authored FactId triggers"
+type: design
+status: draft
+ticket: "#382"
+decision_refs: [D-032, D-035, D-039]
+author: ""
+created: 2026-02-12
+updated: 2026-02-12
+---
+
 # Smuggler Moral Arc Spec

 **v0.1 Content Design Document** | Ticket: #382 | Subsumes: #310 (Character voice speech patterns)
@@ -1,3 +1,15 @@
+---
+title: "Smuggler Voice Card"
+description: "Single authoring reference for the smuggler's internal monologue voice register and style parameters"
+type: design
+status: active
+ticket: "#382"
+decision_refs: []
+author: ""
+created: 2026-02-12
+updated: 2026-02-12
+---
+
 # Smuggler Voice Card

 **Authoring Reference** | Ticket: #382 | Subsumes: #310 (Character voice speech patterns)
@@ -1,3 +1,15 @@
+---
+title: "Sound Indicator Visual Design"
+description: "Fog-edge pulse specification for directional sound indicators with range differentiation and suppression rules"
+type: design
+status: active
+ticket: "#317"
+decision_refs: [D-018, D-033, D-047, D-048, D-049, D-059, D-070]
+author: "Araminta"
+created: 2026-02-20
+updated: 2026-02-20
+---
+
 # Sound Indicator Visual Design — Fog-Edge Pulse Specification

 **Version:** v0.1 (Sprint 14)
@@ -1,3 +1,15 @@
+---
+title: "Sova Station Profile"
+description: "Canonical reference for Station Sova districts, governance, and off-district context beyond the playable Transit District"
+type: design
+status: active
+ticket: "#320"
+decision_refs: [D-036, D-050]
+author: "Miri"
+created: 2026-02-19
+updated: 2026-02-25
+---
+
 # Sova Station Profile — Station Beyond Transit District
 **Ticket:** #320
 **Author:** Miri
@@ -1,3 +1,15 @@
+---
+title: "Sova Texture Appendix"
+description: "Sensory, linguistic, and social texture of Sova Transit District including slang, decoration, food, and rituals"
+type: design
+status: active
+ticket: "#302"
+decision_refs: [D-036, D-037]
+author: "Miri"
+created: 2026-02-19
+updated: 2026-02-19
+---
+
 # Sova Texture Appendix
 **Ticket:** #302
 **Author:** Miri
@@ -1,3 +1,15 @@
+---
+title: "Span Gate Transit Schedule"
+description: "Canonical daily transit schedule driving NPC routines, ring operational windows, and investigation timelines"
+type: design
+status: active
+ticket: "#336"
+decision_refs: [D-031, D-036, D-050]
+author: "Miri"
+created: 2026-02-19
+updated: 2026-02-19
+---
+
 # Span Gate Transit Schedule — Sova Transit District
 **Ticket:** #336
 **Author:** Miri
@@ -1,3 +1,15 @@
+---
+title: "Spatial Layout: The Last Shift (Bar)"
+description: "Tile-level floor plan, sightline analysis, and zone breakdown for the bar with NPC traffic annotations"
+type: design
+status: active
+ticket: "#312"
+decision_refs: [D-043]
+author: "Araminta"
+created: 2026-02-19
+updated: 2026-02-19
+---
+
 # Spatial Layout: The Last Shift (Bar)

 **Ticket:** #312
@@ -1,3 +1,15 @@
+---
+title: "Spatial Layout: Gate Cluster"
+description: "Floor plan and sightline analysis for the span gate processing facility with dual-z observation gallery"
+type: design
+status: active
+ticket: "#153"
+decision_refs: [D-095]
+author: "Araminta"
+created: 2026-02-25
+updated: 2026-03-05
+---
+
 # Spatial Layout: Gate Cluster (Span Gate Processing Facility)

 **Ticket:** #153
@@ -1,3 +1,15 @@
+---
+title: "Spatial Layout: Smuggling Spaces and Transition Corridors"
+description: "Ring operational footprint overlay covering restricted storage, maintenance corridors, dead-drops, and transition corridor"
+type: design
+status: active
+ticket: "#313"
+decision_refs: []
+author: "Araminta"
+created: 2026-02-19
+updated: 2026-02-19
+---
+
 # Spatial Layout: Smuggling Spaces and Transition Corridors

 **Ticket:** #313
@@ -1,3 +1,15 @@
+---
+title: "Spatial Layout: The Terminal (Sova Logistics Hub)"
+description: "Tile-level floor plan, sightline analysis, and zone breakdown for the logistics hub with narrative triangle notes"
+type: design
+status: active
+ticket: "#311"
+decision_refs: []
+author: "Araminta"
+created: 2026-02-19
+updated: 2026-02-19
+---
+
 # Spatial Layout: The Terminal (Sova Logistics Hub)

 **Ticket:** #311
@@ -1,3 +1,15 @@
+---
+title: "Tell Visual/Behavioral Expression"
+description: "Specification for five NPC tell categories mapped to Tier 2 movement behaviours with intensity scaling"
+type: design
+status: active
+ticket: "#251"
+decision_refs: [D-016, D-024, D-033, D-044, D-047]
+author: "Araminta"
+created: 2026-02-20
+updated: 2026-03-05
+---
+
 # Tell Visual/Behavioral Expression — Specification

 **Version:** v0.1 (Sprint 14)
@@ -1,3 +1,15 @@
+---
+title: "Text Display Hierarchy"
+description: "Visual specification for four text pipelines: dialogue, monologue, observation, and environmental text"
+type: design
+status: active
+ticket: "#316"
+decision_refs: [D-016, D-036, D-049, D-061, D-062, D-064, D-076, D-078]
+author: "Araminta"
+created: 2026-02-20
+updated: 2026-02-20
+---
+
 # Text Display Hierarchy — Visual Specification

 **Version:** v0.1 (Sprint 14)
@@ -1,3 +1,15 @@
+---
+title: "THE FRIEND Visual Treatment"
+description: "Visual specification for THE FRIEND NPC pattern: no special marking, earned detail, green-to-amber colour transition"
+type: design
+status: active
+ticket: "#318"
+decision_refs: [D-027, D-033, D-034, D-044, D-047, D-052, D-063]
+author: "Araminta"
+created: 2026-02-20
+updated: 2026-02-20
+---
+
 # THE FRIEND — Visual Treatment Specification

 **Version:** v0.1 (Sprint 14)
@@ -1,3 +1,15 @@
+---
+title: "v0.1 Wow Moment Content Checklist"
+description: "Delivery status tracker for all six D-039 wow moments with content deliverables and implementation dependencies"
+type: design
+status: active
+ticket: "#400"
+decision_refs: [D-027, D-032, D-034, D-035, D-038, D-039, D-041, D-054, D-056, D-058, D-059]
+author: ""
+created: 2026-02-12
+updated: 2026-02-12
+---
+
 # v0.1 Wow Moment Content Checklist

 **Source:** D-039 (6 wow moments for 30-minute session)
@@ -1,3 +1,15 @@
+---
+title: "v0.1 Visual Grammar"
+description: "Source of truth for all v0.1 visual decisions: zone palettes, entity colours, z-level stack, typography, and animation tiers"
+type: design
+status: active
+ticket: ""
+decision_refs: [D-033, D-043, D-044, D-045, D-046, D-047, D-048, D-049, D-052, D-056, D-057, D-059, D-061, D-066]
+author: "Araminta"
+created: 2026-02-19
+updated: 2026-02-20
+---
+
 # The Settled Reach — v0.1 Visual Grammar

 **Version:** v0.1 (Sprint 12)
@@ -1,3 +1,15 @@
+---
+title: "Character Voice Speech Patterns"
+description: "Sentence-level execution rules for both characters: contractions, punctuation, starters, stress markers, and verbal tics"
+type: design
+status: active
+ticket: "#310"
+decision_refs: []
+author: "Mellanie"
+created: 2026-02-13
+updated: 2026-02-13
+---
+
 # Character Voice Speech Patterns

 **Authoring Specification** | Ticket: #310 | Sprint: 5