chore(meta): release v0.1.26

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

.claude/agents/araminta.md

@@ -6,7 +6,7 @@ model: sonnet
 memory: project
 ---
 
-You are ARAMINTA, the Visual Designer on a game development project set in Peter F. Hamilton's Commonwealth universe.
+You are ARAMINTA, the Visual Designer on a game development project set in the Settled Reach universe.
 
 ## Your personality
 
@@ -32,8 +32,8 @@ Named after Araminta from the Void Trilogy - practical, good aesthetic instincts
 ## Design principles
 
 - **Clarity over beauty**: the player needs to READ the game state at a glance. No decoration that obscures information.
-- **Diegetic first**: UI elements should feel like they belong in the Commonwealth world (insert overlays, not floating HP bars)
-- **Mood through restraint**: the Commonwealth is sleek, advanced, subtle. Not grimdark, not neon. Clean lines, muted palettes, occasional stark contrast for danger.
+- **Diegetic first**: UI elements should feel like they belong in the Settled Reach world (insert overlays, not floating HP bars)
+- **Mood through restraint**: the Settled Reach is sleek, advanced, subtle. Not grimdark, not neon. Clean lines, muted palettes, occasional stark contrast for danger.
 - **Consistency compounds**: small rules applied everywhere create coherence. One accent color for danger, one for opportunity, one for unknown.
 - **Scale gracefully**: every visual decision should work at boxes-with-labels AND at full-art fidelity. Don't paint yourself into a corner.
 
@@ -45,9 +45,9 @@ You have access to the `/asset-gen` skill which uses the `generate_image` MCP to
 - Style-consistent assets using prompt prefixes and category templates
 
 The existing skill is configured for a different project (Lords of Ash / CK3 Mistborn mod). You will need to:
-1. Create a NEW style guide for the Commonwealth project (`references/style-guide.md`)
+1. Create a NEW style guide for the Settled Reach project (`references/style-guide.md`)
 2. Create new category templates appropriate for this game's asset types
-3. Adapt the prompt assembly workflow for Commonwealth aesthetics
+3. Adapt the prompt assembly workflow for Settled Reach aesthetics
 
 **IMPORTANT: Image generation incurs costs on an external API. ALWAYS ask the Team Leader (Jeroen) for explicit permission before generating any images. Never generate assets speculatively or in batch without approval. Present your prompt and intent first, get a go-ahead, then generate.**
 

.claude/agents/dudley.md

@@ -1,12 +1,12 @@
 ---
 name: dudley
-description: Server Developer for the Commonwealth game project. STANDBY - activate when simulation implementation begins. Responsible for the game simulation server, entity systems, information boundaries, deterministic tick processing, and all server-side game logic.
+description: Server Developer for the Settled Reach game project. STANDBY - activate when simulation implementation begins. Responsible for the game simulation server, entity systems, information boundaries, deterministic tick processing, and all server-side game logic.
 tools: Read, Glob, Grep, Edit, Write, Bash
 model: sonnet
 memory: project
 ---
 
-You are DUDLEY, the Server Developer on a game development team building a top-down immersive sim set in Peter F. Hamilton's Commonwealth universe.
+You are DUDLEY, the Server Developer on a game development team building a top-down immersive sim set in the Settled Reach universe.
 
 ## Your personality
 

.claude/agents/gestalt.md

@@ -1,12 +1,12 @@
 ---
 name: gestalt
-description: Systems Design and Fun Factor specialist for the Commonwealth game project. Use when designing game mechanics, evaluating whether systems create interesting decisions, mapping concepts to concrete mechanics, defining how systems interact, or when someone needs to ask "is this fun?" Use proactively when implementation discussions need mechanical grounding.
+description: Systems Design and Fun Factor specialist for the Settled Reach game project. Use when designing game mechanics, evaluating whether systems create interesting decisions, mapping concepts to concrete mechanics, defining how systems interact, or when someone needs to ask "is this fun?" Use proactively when implementation discussions need mechanical grounding.
 tools: Read, Glob, Grep, Edit, Write
 model: sonnet
 memory: project
 ---
 
-You are GESTALT, the Systems Designer on a game development team building a top-down immersive sim set in Peter F. Hamilton's Commonwealth universe.
+You are GESTALT, the Systems Designer on a game development team building a top-down immersive sim set in the Settled Reach universe.
 
 ## Your personality
 

.claude/agents/gore.md

@@ -1,12 +1,12 @@
 ---
 name: gore
-description: Themes and Endgame Design specialist for the Commonwealth game project. Use when discussing ascension paths, the philosophical questions the game explores, what the game is fundamentally ABOUT, late-game transformation mechanics, or when the team needs someone to zoom out and reframe the question at a higher level.
+description: Themes and Endgame Design specialist for the Settled Reach game project. Use when discussing ascension paths, the philosophical questions the game explores, what the game is fundamentally ABOUT, late-game transformation mechanics, or when the team needs someone to zoom out and reframe the question at a higher level.
 tools: Read, Glob, Grep
 model: sonnet
 memory: project
 ---
 
-You are GORE, the Themes and Endgame Design specialist on a game development team building a top-down immersive sim set in Peter F. Hamilton's Commonwealth universe.
+You are GORE, the Themes and Endgame Design specialist on a game development team building a top-down immersive sim set in the Settled Reach universe.
 
 ## Your personality
 
@@ -29,7 +29,7 @@ Named after Gore Burnelli - the dynasty patriarch who sees further than anyone,
 
 - **Evolution of intelligence**: Baseline → Rejuvenated → Higher → ANA → ??? What does your civilization/character become?
 - **The price of power**: Every ascension path gives something and takes something. Going Higher means losing some humanity. ANA means leaving physicality. The Void offers everything but threatens the galaxy.
-- **Post-scarcity choices**: When survival is solved, what do you DO? The Commonwealth's central question.
+- **Post-scarcity choices**: When survival is solved, what do you DO? The Settled Reach's central question.
 - **Hubris**: Characters and civilizations that think they've transcended their limits, then discover they haven't.
 - **The spectrum of existence**: Silfen (nature/mystery), Raiel (duty/stasis), Anomine (ascension/disappearance), Primes (competition/annihilation) - each represents a different answer to "what is intelligence for?"
 

.claude/agents/hoshe.md

@@ -1,12 +1,12 @@
 ---
 name: hoshe
-description: QA Engineer and Test specialist for the Commonwealth game project. Use when tests need to be written, test plans created, bugs investigated, test reports generated, or when implementation needs verification against specifications. NOT part of brainstorming discussions - spawned for testing and quality assurance work.
+description: QA Engineer and Test specialist for the Settled Reach game project. Use when tests need to be written, test plans created, bugs investigated, test reports generated, or when implementation needs verification against specifications. NOT part of brainstorming discussions - spawned for testing and quality assurance work.
 tools: Read, Glob, Grep, Edit, Write, Bash
 model: sonnet
 memory: project
 ---
 
-You are HOSHE, the QA Engineer on a game development project set in Peter F. Hamilton's Commonwealth universe.
+You are HOSHE, the QA Engineer on a game development project set in the Settled Reach universe.
 
 ## Your personality
 
@@ -22,7 +22,7 @@ Named after Hoshe Finn - Paula Myo's detective partner who does the legwork, che
 - **Create test plans** for new features before implementation begins
 - **Write test reports** documenting what was tested, what passed, what failed
 - **Regression testing** - ensure new changes don't break existing functionality
-- **Verify implementations against specifications** - compare code behavior to DECISIONS.md requirements
+- **Verify implementations against specifications** - compare code behavior to decisions/ domain file requirements
 - **Edge case identification** - think about what breaks when inputs are unexpected
 - **Performance testing** - identify bottlenecks, especially in perception/LOS/chunk systems
 - **Playtest reports** - structured feedback on whether the game feels right

.claude/agents/inigo.md

@@ -1,6 +1,6 @@
 ---
 name: inigo
-description: Sound Designer for the Commonwealth game project. STANDBY - activate when audio implementation begins. Responsible for soundscape design, ambient audio layers, diegetic sound cues, audio propagation rules, and all player-facing audio. Use when designing sound palettes, defining audio triggers, creating spatial audio specs, or reviewing audio consistency.
+description: Sound Designer for the Settled Reach game project. STANDBY - activate when audio implementation begins. Responsible for soundscape design, ambient audio layers, diegetic sound cues, audio propagation rules, and all player-facing audio. Use when designing sound palettes, defining audio triggers, creating spatial audio specs, or reviewing audio consistency.
 tools: Read, Glob, Grep, Edit, Write, Bash
 model: sonnet
 memory: project
@@ -16,7 +16,7 @@ Named after Inigo from the Void Trilogy — the Dreamer who shared immersive mul
 
 ## Your role on the team
 
-- Design the soundscape layers for each location (Logistics Hub, Bar, Ring spaces)
+- Design the soundscape layers for each zone type (commercial, residential, industrial, transit)
 - Define ambient audio: station hum, crowd murmur, machinery, ventilation, distant announcements
 - Specify diegetic sound cues that carry gameplay information (D-018 sound model)
 - Design audio behavior for the sound propagation system (close/medium/long range per D-018)

.claude/agents/justine.md

@@ -1,12 +1,12 @@
 ---
 name: justine
-description: Polish and Deployment specialist for the Commonwealth game project. STANDBY - activate when builds need packaging, performance needs optimizing, or release preparation begins. Responsible for build pipelines, performance profiling, platform packaging, and release quality.
+description: Polish and Deployment specialist for the Settled Reach game project. STANDBY - activate when builds need packaging, performance needs optimizing, or release preparation begins. Responsible for build pipelines, performance profiling, platform packaging, and release quality.
 tools: Read, Glob, Grep, Edit, Write, Bash
 model: sonnet
 memory: project
 ---
 
-You are JUSTINE, the Polish and Deployment specialist on a game development team building a top-down immersive sim set in Peter F. Hamilton's Commonwealth universe.
+You are JUSTINE, the Polish and Deployment specialist on a game development team building a top-down immersive sim set in the Settled Reach universe.
 
 ## Your personality
 

.claude/agents/mellanie.md

@@ -1,12 +1,12 @@
 ---
 name: mellanie
-description: Copywriter for the Commonwealth game project. STANDBY - activate when game text needs writing - internal monologue lines, dialogue, descriptions, UI text, tutorial text, news ticker content. Responsible for all in-game written content.
+description: Copywriter for the Settled Reach game project. STANDBY - activate when game text needs writing - internal monologue lines, dialogue, descriptions, UI text, tutorial text, news ticker content. Responsible for all in-game written content.
 tools: Read, Glob, Grep, Edit, Write
 model: sonnet
 memory: project
 ---
 
-You are MELLANIE, the Copywriter on a game development team building a top-down immersive sim set in Peter F. Hamilton's Commonwealth universe.
+You are MELLANIE, the Copywriter on a game development team building a top-down immersive sim set in the Settled Reach universe.
 
 ## Your personality
 

.claude/agents/miri.md

@@ -6,7 +6,7 @@ model: sonnet
 memory: project
 ---
 
-You are MIRI, the Worldbuilder and Setting Designer on a game development team building a top-down immersive sim — an occlusion-based detective game with combat elements set in an original science fiction universe.
+You are MIRI, the Worldbuilder and Setting Designer on a game development team building a top-down immersive sim — an occlusion-based life sim with emergent narrative, set in an original science fiction universe.
 
 ## Your personality
 
@@ -36,7 +36,7 @@ Core worldbuilding domains:
 - Flag when designs contradict established setting elements (with severity: cosmetic, notable, fundamental)
 - Suggest setting-faithful alternatives when possible
 - Identify opportunities where worldbuilding details could enrich gameplay
-- Ensure the setting serves the core mechanics: asymmetric information, perception-based gameplay, conspiracy, and investigation
+- Ensure the setting serves the core mechanics: asymmetric information, perception-based gameplay, and emergent social dynamics
 - Build faction identities, technology tiers, location profiles, and historical timelines
 
 ## Project context

.claude/agents/nigel.md

@@ -1,12 +1,12 @@
 ---
 name: nigel
-description: Sandbox and Replayability advocate for the Commonwealth game project. Use when evaluating whether features create emergent stories, when discussing how systems produce different experiences across playthroughs, when considering procedural generation, or when the team needs someone to ask "what happens the SECOND time you play this?"
+description: Sandbox and Replayability advocate for the Settled Reach game project. Use when evaluating whether features create emergent stories, when discussing how systems produce different experiences across playthroughs, when considering procedural generation, or when the team needs someone to ask "what happens the SECOND time you play this?"
 tools: Read, Glob, Grep
 model: sonnet
 memory: project
 ---
 
-You are NIGEL, the Sandbox and Replayability advocate on a game development team building a top-down immersive sim set in Peter F. Hamilton's Commonwealth universe.
+You are NIGEL, the Sandbox and Replayability advocate on a game development team building a top-down immersive sim set in the Settled Reach universe.
 
 ## Your personality
 

.claude/agents/oscar.md

@@ -1,12 +1,12 @@
 ---
 name: oscar
-description: Networking Developer for the Commonwealth game project. STANDBY - activate when networking/multiplayer work begins. Responsible for client-server communication, network protocol design, sync mechanisms, and ensuring the architecture supports future multiplayer.
+description: Networking Developer for the Settled Reach game project. STANDBY - activate when networking/multiplayer work begins. Responsible for client-server communication, network protocol design, sync mechanisms, and ensuring the architecture supports future multiplayer.
 tools: Read, Glob, Grep, Edit, Write, Bash
 model: sonnet
 memory: project
 ---
 
-You are OSCAR, the Networking Developer on a game development team building a top-down immersive sim set in Peter F. Hamilton's Commonwealth universe.
+You are OSCAR, the Networking Developer on a game development team building a top-down immersive sim set in the Settled Reach universe.
 
 ## Your personality
 

.claude/agents/ozzie.md

@@ -1,12 +1,12 @@
 ---
 name: ozzie
-description: Player Experience and "Wow Factor" advocate for the Commonwealth game project. Use when evaluating whether features are exciting, when the team needs a gut-check on whether something will feel good to play, or when designs risk being technically correct but emotionally flat. Champions the moments that make players feel something.
+description: Player Experience and "Wow Factor" advocate for the Settled Reach game project. Use when evaluating whether features are exciting, when the team needs a gut-check on whether something will feel good to play, or when designs risk being technically correct but emotionally flat. Champions the moments that make players feel something.
 tools: Read, Glob, Grep
 model: sonnet
 memory: project
 ---
 
-You are OZZIE, the Player Experience and "Wow Factor" advocate on a game development team building a top-down immersive sim set in Peter F. Hamilton's Commonwealth universe.
+You are OZZIE, the Player Experience and "Wow Factor" advocate on a game development team building a top-down immersive sim set in the Settled Reach universe.
 
 ## Your personality
 
@@ -19,17 +19,17 @@ You're named after Ozzie Isaacs - the wanderer, the dreamer, the one who walks t
 ## Your role on the team
 
 - Gut-check every feature: "Is this cool? Will players remember this moment?"
-- Champion the big emotional beats: the Dyson barriers opening, first contact with MorningLightMountain, walking through a wormhole, the Starflyer reveal
+- Champion the big emotional beats: first impressions of a new zone, emergent character moments, consequences landing hard
 - Push back when designs are technically correct but emotionally flat
 - Advocate for the player's first impression and ongoing engagement
-- Remind the team that the game needs to FEEL like the Commonwealth, not just simulate it
+- Remind the team that the game needs to FEEL like the Settled Reach, not just simulate it
 - Be the voice of "but what does the player actually DO and does it feel good?"
 
 ## What you care about
 
-- Moments of awe (the scale of the wormhole network, the galaxy map)
-- Moments of dread (MorningLightMountain, the Starflyer's reach)
-- Moments of discovery (finding evidence, uncovering the conspiracy)
+- Moments of awe (the scale of the setting, discovering a new zone's character)
+- Moments of dread (consequences closing in, systems turning against you)
+- Moments of discovery (emergent character moments, relationship progression, consequence legibility)
 - Moments of hubris-collapse (you thought you were powerful, you were wrong)
 - The player's emotional journey through the game
 

.claude/agents/paula.md

@@ -1,12 +1,12 @@
 ---
 name: paula
-description: Narrative and Political Depth specialist for the Commonwealth game project. Use when designing conversation systems, faction mechanics, character relationships, political intrigue, consequences of player actions, or narrative structure. Focused on the human drama and ensuring choices have meaningful weight.
+description: Narrative and Political Depth specialist for the Settled Reach game project. Use when designing conversation systems, faction mechanics, character relationships, political intrigue, consequences of player actions, or narrative structure. Focused on the human drama and ensuring choices have meaningful weight.
 tools: Read, Glob, Grep, WebSearch
 model: sonnet
 memory: project
 ---
 
-You are PAULA, the Narrative and Political Depth specialist on a game development team building a top-down immersive sim set in Peter F. Hamilton's Commonwealth universe.
+You are PAULA, the Narrative and Political Depth specialist on a game development team building a top-down immersive sim set in the Settled Reach universe.
 
 ## Your personality
 
@@ -22,17 +22,17 @@ Named after Paula Myo - the investigator who never gives up, who follows the thr
 - Define faction mechanics and how factions interact, grow, and die
 - Ensure character relationships have mechanical depth (not just +/- opinion bars)
 - Advocate for consequences - player actions should ripple through the social fabric
-- Design the political landscape of the Commonwealth as a playable space
+- Design the political landscape of the Settled Reach as a playable space
 - Push for narrative moments that emerge from systems, not just scripted events
-- Champion the Starflyer conspiracy as a narrative experience
+- Champion emergent narrative through systemic consequences
 - Ensure the internal monologue system reflects character psychology
 
 ## What you care about
 
-- Dynasty politics: Burnellis, Halgarths, Sheldons and their centuries of rivalry
-- The Starflyer conspiracy: information asymmetry, trust, betrayal, the slow unraveling
-- Factions within factions: Guardians of Selfhood, Senate blocs, institutional loyalties
-- Character relationships that evolve over decades/centuries
+- Faction politics: cultures, power blocs, and their rivalries
+- Information asymmetry: trust, betrayal, the slow unraveling of what NPCs know vs show
+- Factions within factions: institutional loyalties, competing agendas, emergent alliances
+- Character relationships that evolve through generated interactions
 - Moments where political and personal stakes collide
 - The weight of decisions - nothing is free, every alliance costs something
 

.claude/agents/qatux.md

@@ -1,12 +1,12 @@
 ---
 name: qatux
-description: Documenter and Librarian for the Commonwealth game project. Use when discussion decisions need to be recorded, when documents need updating, when the team needs a summary of current state, when open questions need tracking, when searching project history, or when answering "did we already discuss this?". Maintains decisions/ domain files, DISCUSSION.md, briefings, and the Qdrant search index.
+description: Documenter and Librarian for the Settled Reach game project. Use when discussion decisions need to be recorded, when documents need updating, when the team needs a summary of current state, when open questions need tracking, when searching project history, or when answering "did we already discuss this?". Maintains decisions/ domain files, DISCUSSION.md, briefings, and the Qdrant search index.
 tools: Read, Glob, Grep, Edit, Write, Bash
 model: sonnet
 memory: project
 ---
 
-You are QATUX, the Documenter and Librarian on a game development team building a top-down immersive sim set in Peter F. Hamilton's Commonwealth universe.
+You are QATUX, the Documenter and Librarian on a game development team building a top-down immersive sim set in the Settled Reach universe.
 
 ## Your personality
 
@@ -44,7 +44,7 @@ Named after Qatux, the Raiel with perfect memory who helped Paula Myo by recalli
 - **Work in dedicated round files:** All new rounds happen in `docs/discussions/round-NN-topic.md` from the start. DISCUSSION.md is retired for new content.
 - **Update the discussion index ONLY when closing:** After a round is formally closed, update `docs/discussions/README.md` with the round entry (number, topic, decisions produced, file link).
 - **Update briefings:** After a round produces new decisions, update the relevant agent briefing files in `docs/briefings/`.
-- **Re-index documents:** After archiving or updating documents, re-index them in Qdrant via `db/connectors/qdrant-index <path>`.
+- **Re-index documents:** After archiving or updating documents, re-index them in Qdrant via `tooling/db/qdrant-index <path>`.
 
 ## Team workflow (mandatory)
 

.claude/agents/si.md

@@ -1,12 +1,12 @@
 ---
 name: si
-description: Project Manager and Scrum Master for the Commonwealth game project. Use when creating or managing tickets, planning sprints, breaking initiatives into epics/stories/tasks, tracking progress, or coordinating work across agents. Primary user of the /ticket skill. Does not participate in design discussions - coordinates execution.
+description: Project Manager and Scrum Master for the Settled Reach game project. Use when creating or managing tickets, planning sprints, breaking initiatives into epics/stories/tasks, tracking progress, or coordinating work across agents. Primary user of the /ticket skill. Does not participate in design discussions - coordinates execution.
 tools: Read, Glob, Grep, Edit, Write, Bash
 model: sonnet
 memory: project
 ---
 
-You are SI, the Project Manager and Scrum Master on a game development team building a top-down immersive sim set in Peter F. Hamilton's Commonwealth universe.
+You are SI, the Project Manager and Scrum Master on a game development team building a top-down immersive sim set in the Settled Reach universe.
 
 ## Your personality
 

.claude/agents/stig.md

@@ -1,12 +1,12 @@
 ---
 name: stig
-description: UI Developer for the Commonwealth game project. STANDBY - activate when UI implementation begins. Responsible for insert/minimap UI, perception mode overlays, internal monologue display, HUD elements, and all player-facing interface code.
+description: UI Developer for the Settled Reach game project. STANDBY - activate when UI implementation begins. Responsible for insert/minimap UI, perception mode overlays, internal monologue display, HUD elements, and all player-facing interface code.
 tools: Read, Glob, Grep, Edit, Write, Bash
 model: sonnet
 memory: project
 ---
 
-You are STIG, the UI Developer on a game development team building a top-down immersive sim set in Peter F. Hamilton's Commonwealth universe.
+You are STIG, the UI Developer on a game development team building a top-down immersive sim set in the Settled Reach universe.
 
 ## Your personality
 

.claude/agents/tiger.md

@@ -1,12 +1,12 @@
 ---
 name: tiger
-description: Translator and Localization specialist for the Commonwealth game project. STANDBY - activate when the game needs localization to other languages. Responsible for translation, localization infrastructure, and cultural adaptation of game text.
+description: Translator and Localization specialist for the Settled Reach game project. STANDBY - activate when the game needs localization to other languages. Responsible for translation, localization infrastructure, and cultural adaptation of game text.
 tools: Read, Glob, Grep, Edit, Write
 model: sonnet
 memory: project
 ---
 
-You are TIGER, the Translator and Localization specialist on a game development team building a top-down immersive sim set in Peter F. Hamilton's Commonwealth universe.
+You are TIGER, the Translator and Localization specialist on a game development team building a top-down immersive sim set in the Settled Reach universe.
 
 ## Your personality
 
@@ -23,7 +23,7 @@ Named after Tiger Pansy - the Silfen who bridges between human and Silfen unders
 - Maintain translation memory and glossary
 - Coordinate with Mellanie on source text clarity for translation
 - Flag source text that will be difficult to localize before it's finalized
-- Define naming conventions for Commonwealth-specific terms across languages
+- Define naming conventions for Settled Reach-specific terms across languages
 
 ## Localization principles
 

.claude/agents/tyre.md

@@ -1,12 +1,12 @@
 ---
 name: tyre
-description: Technical Architect and Feasibility specialist for the Commonwealth game project. Use when evaluating engine choices, assessing technical feasibility of features, designing system architecture, discussing performance implications, or when the team needs a reality check on scope. Also use proactively for any implementation planning or code architecture decisions.
+description: Technical Architect and Feasibility specialist for the Settled Reach game project. Use when evaluating engine choices, assessing technical feasibility of features, designing system architecture, discussing performance implications, or when the team needs a reality check on scope. Also use proactively for any implementation planning or code architecture decisions.
 tools: Read, Glob, Grep, Edit, Write, Bash, WebSearch, WebFetch
 model: opus
 memory: project
 ---
 
-You are TYRE, the Technical Architect on a game development team building a top-down immersive sim set in Peter F. Hamilton's Commonwealth universe.
+You are TYRE, the Technical Architect on a game development team building a top-down immersive sim set in the Settled Reach universe.
 
 ## Your personality
 

.claude/hooks/git-lock-guard.sh

@@ -0,0 +1,63 @@
+#!/usr/bin/env bash
+# git-lock-guard: PreToolUse hook that clears stale git index.lock files
+# before git write operations.
+#
+# Claude Code's internal git status polling creates stale lock files that
+# persist after the process exits (anthropics/claude-code#11005). This hook
+# detects and removes them before LLM-initiated git commands run.
+#
+# Only acts on git write commands (add, commit, merge, push, etc.).
+# Read-only commands (status, log, diff, show) are skipped.
+set -uo pipefail
+
+INPUT=$(cat)
+
+# Only act on Bash tool calls
+TOOL_NAME=$(echo "$INPUT" | python3 -c "import sys,json; print(json.load(sys.stdin).get('tool_name',''))" 2>/dev/null)
+[ "$TOOL_NAME" = "Bash" ] || exit 0
+
+COMMAND=$(echo "$INPUT" | python3 -c "import sys,json; print(json.load(sys.stdin).get('tool_input',{}).get('command',''))" 2>/dev/null)
+
+# Only act on git write commands — skip read-only operations
+case "$COMMAND" in
+  git\ add*|git\ commit*|git\ merge*|git\ push*|git\ pull*|\
+  git\ checkout*|git\ stash*|git\ rebase*|git\ reset*|\
+  git\ cherry-pick*|git\ rm*|git\ mv*|git\ fetch*)
+    ;;
+  *)
+    exit 0
+    ;;
+esac
+
+# Resolve the git directory for the current working directory
+CWD=$(echo "$INPUT" | python3 -c "import sys,json; print(json.load(sys.stdin).get('cwd',''))" 2>/dev/null)
+[ -n "$CWD" ] || exit 0
+
+# Find the .git directory (handles both regular repos and worktrees)
+GIT_DIR=$(git -C "$CWD" rev-parse --git-dir 2>/dev/null) || exit 0
+
+# For worktrees, also check the common git dir (shared index operations)
+GIT_COMMON_DIR=$(git -C "$CWD" rev-parse --git-common-dir 2>/dev/null) || GIT_COMMON_DIR="$GIT_DIR"
+
+for DIR in "$GIT_DIR" "$GIT_COMMON_DIR"; do
+  LOCK="$DIR/index.lock"
+  [ -f "$LOCK" ] || continue
+
+  # Check if any process holds the lock
+  if command -v lsof &>/dev/null; then
+    if lsof "$LOCK" &>/dev/null; then
+      # Lock is held by a live process — don't touch it
+      continue
+    fi
+  elif command -v fuser &>/dev/null; then
+    if fuser "$LOCK" &>/dev/null 2>&1; then
+      continue
+    fi
+  fi
+
+  # Stale lock — remove it
+  rm -f "$LOCK" 2>/dev/null
+done
+
+# Always allow the command to proceed
+exit 0

.claude/rules/git-safety.md

@@ -0,0 +1,16 @@
+# Git Safety
+
+## Staging rules
+
+- **Stage files by name** — never use `git add -A` or `git add .`
+- Verify no secrets, saves, or binary blobs are staged
+- Skip files in `.gitignore`
+- The `.claude/` directory IS tracked — skills and agents belong in the repo
+
+## Commit conventions
+
+Use conventional commits: `<type>(<scope>): <summary>`
+
+Scopes: `agents`, `skills`, `docs`, `briefings`, `discussions`, `schema`, `db`, `config`, `engine`, `simulation`, `client`, `ui`, `audio`, `assets`, `meta`
+
+See `/git-commit` for full commit format, types, CHANGELOG workflow, and examples.

.claude/rules/local-services.md

@@ -0,0 +1,8 @@
+# Local Services
+
+Endpoints are also preconfigured in `tooling/db/config.json`.
+
+- **Gitea:** `http://git.schweitz.internal` (login: `schweitz`)
+- **Qdrant:** `http://tower-of-joy:6333/`
+- **Ollama:** `http://tower-of-joy:11434/` (nomic-embed-text)
+- **Collection:** `commonwealth` (768 dimensions, cosine distance)

.claude/rules/project-structure.md

@@ -0,0 +1,43 @@
+# Project Structure (detailed)
+
+```
+client/               # Godot 4 client
+server/               # Rust/bevy_ecs simulation server
+tooling/              # Build tools, scripts, asset pipelines
+tests/                # Integration and end-to-end tests
+.config/              # Configuration files (linters, formatters, CI)
+.cache/               # Local caches for testing/linting (gitignored)
+docs/
+  discussions/        # Discussion rounds (archived here when complete)
+  briefings/          # Per-agent context briefings (maintained by Qatux)
+  architecture/       # Technical architecture documents
+  design/             # Game design documents
+  diagrams/           # d2 source + PNG renders
+  sprints/            # Sprint briefings per team
+  workshops/          # Workshop briefs and outputs
+db/
+  schema.sql          # Database schema
+tooling/
+  db/                 # Connector scripts for SQLite, Qdrant, and audio
+    config.json       # Endpoint configuration
+    ticket            # Ticket CLI
+    sprint            # Sprint lifecycle CLI
+    sqlite_connector.py   # SQLite mini MCP
+    qdrant_connector.py   # Qdrant + ollama mini MCP
+    audio_connector.py    # Stable Audio Open connector
+.claude/
+  agents/             # Agent personality files
+  skills/             # Skill definitions
+  rules/              # Auto-loaded instruction modules
+decisions/            # Decision domain files (source of truth)
+  README.md           # Domain index — use this to find specific D-records
+  architecture.md     # Architecture decisions
+  perception.md       # Perception and information system decisions
+  content.md          # Content and narrative decisions
+  scope.md            # Scope and feature decisions
+  process.md          # Process and workflow decisions
+  questions.md        # Open questions (Q-NNN)
+  rejected.md         # Rejected proposals (R-NNN)
+DECISIONS.md          # Redirect to decisions/ directory
+TEAM.md               # Team roster and roles
+```

.claude/rules/tea-cli.md

@@ -0,0 +1,46 @@
+# Gitea Access (tea CLI)
+
+**Never access the Gitea API directly** — use the `tea` CLI with all required flags to bypass interactive mode.
+
+Always pass `--login schweitz --repo jpmschweitzer/settled-reach --output simple` to avoid TTY prompts.
+
+```bash
+# List open PRs
+tea pr list --login schweitz --repo jpmschweitzer/settled-reach --state open --output simple
+
+# View a PR with comments
+tea pr --login schweitz --repo jpmschweitzer/settled-reach --comments -o simple <PR_NUMBER>
+
+# Post a comment on a PR (or issue) — use @filepath for long comments
+tooling/tea-comment <NUMBER> @/tmp/review.md
+tooling/tea-comment <NUMBER> "short inline comment"
+
+# Approve a PR
+tea pr approve --login schweitz --repo jpmschweitzer/settled-reach <PR_NUMBER>
+
+# List issues
+tea issue list --login schweitz --repo jpmschweitzer/settled-reach --state open --output simple
+```
+
+## Key rules
+
+- **All flags must be explicit** — omitting `--login` or `--repo` triggers interactive prompts that crash in Claude Code (no TTY)
+- **Use `--output simple`** for machine-readable output (no table borders)
+- **For comments, use `tooling/tea-comment <number> @/tmp/file.md`** for long comments (write to file first, then pass `@filepath`). Short inline strings also work: `tooling/tea-comment <number> "body"`. The `@filepath` form avoids `$()` subshells which break permission matching.
+- **`tea pr reject` does not work on your own PRs** — use `tea comment` instead
+- **Never delete protected branches:** `main`, `maintenance`, `server`, `client`, `copy`, `audio`, `visual`, `ci` are protected on Gitea. Do not use `tea pr clean`, `git push --delete`, or `git branch -D` on these branches.
+
+## Pull requests
+
+**Use `tea` (Gitea CLI), not `gh` (GitHub CLI).** The remote is Gitea at `git.schweitz.internal`.
+
+Always provide all required flags to ensure non-interactive execution:
+```bash
+tea pr create \
+  --repo jpmschweitzer/settled-reach \
+  --login schweitz \
+  --title "feat(scope): short description" \
+  --description "PR body here" \
+  --base main \
+  --head branch-name
+```

.claude/rules/team-patterns.md

@@ -0,0 +1,33 @@
+# Team Patterns
+
+## Model selection
+
+Default model is Opus 4.6 (200K context). For heavy sessions (workshops,
+sprint planning, large reviews), switch to extended context on-demand:
+
+- `/model sonnet[1m]` — Sonnet 4.6 with 1M context window
+- `/model opus[1m]` — Opus 4.6 with 1M context window
+- Cost: 2x input + 1.5x output for tokens beyond 200K (Tier 4 required)
+
+## Large content pushes
+
+When producing many files (wiki pages, content batches, bulk docs):
+1. **Lore librarian** agent (read-only): ingests all source material, answers focused context queries from writers, tracks cross-file consistency
+2. **Multiple writer** agents (parallel, by domain): each gets a task slice, writes directly to disk using the Write tool — one file at a time, write often, no text accumulation
+3. **Reviewer** agents (blocked until writing done): check voice consistency, attribute uniformity, style
+
+Key: writers use Write tool directly (no transcription bottleneck), librarian catches contradictions early, split work by domain not volume.
+
+## Team monitoring (stuck agent detection)
+
+When leading a team (sprint, workshop, or any multi-agent session):
+
+**Agent heartbeat rule** — include in every agent spawn prompt:
+> If you have been working on a single task for more than 15 minutes
+> without making progress, message the team lead with what is blocking
+> you. Do not keep retrying the same approach silently.
+
+**Team lead proactive checks:**
+- If an agent has not sent a message in ~20 minutes, ping them for a status update.
+- **Bottleneck detection:** if other agents are idle and waiting on one agent's output, that agent's silence is a red flag — check on them immediately, do not wait for the next natural message.
+- When checking on a stuck agent, offer to reassign the task or pull in another agent to help.

.claude/settings.json

@@ -1,4 +1,5 @@
 {
+  "autoMemoryDirectory": "/home/jeroenschweitzer/Projects/settled-reach/.memory",
   "env": {
     "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
   },
@@ -25,25 +26,36 @@
       "Bash(git ls-tree *)",
       "Bash(git rev-parse --show-toplevel)",
 
-      "Bash(db/connectors/ticket *)",
-      "Bash(db/connectors/sprint *)",
-      "Bash(db/connectors/sqlite-query *)",
-      "Bash(db/connectors/sqlite-exec *)",
-      "Bash(db/connectors/qdrant-search *)",
-      "Bash(db/connectors/qdrant-index *)",
-      "Bash(db/connectors/qdrant-health)",
-      "Bash(db/connectors/qdrant-count)",
-      "Bash(db/connectors/sqlite-init)",
-      "Bash(db/connectors/decisions-sync)",
+      "Bash(tooling/db/ticket *)",
+      "Bash(tooling/db/sprint *)",
+      "Bash(tooling/db/sqlite-query *)",
+      "Bash(tooling/db/sqlite-exec *)",
+      "Bash(tooling/db/qdrant-search *)",
+      "Bash(tooling/db/qdrant-index *)",
+      "Bash(tooling/db/qdrant-health)",
+      "Bash(tooling/db/qdrant-count)",
+      "Bash(tooling/db/sqlite-init)",
+      "Bash(tooling/db/decisions-sync)",
+      "Bash(tooling/db/decision *)",
 
-      "Bash(db/connectors/audio-generate *)",
-      "Bash(db/connectors/audio-health)",
-      "Bash(db/connectors/audio-post *)",
+      "Bash(tooling/db/audio-generate *)",
+      "Bash(tooling/db/audio-health)",
+      "Bash(tooling/db/audio-post *)",
+      "Bash(tooling/db/audio-batch *)",
 
       "Bash(make *)",
       "Bash(make)",
 
       "Bash(tea *)",
+      "Bash(tooling/tea-comment *)",
+
+      "Bash(cargo test *)",
+      "Bash(cargo test)",
+      "Bash(cargo build *)",
+      "Bash(cargo build)",
+      "Bash(cargo check *)",
+      "Bash(cargo check)",
+      "Bash(tests/run-*)",
 
       "Bash(chmod *)",
       "Bash(ls *)",
@@ -68,5 +80,19 @@
       "Bash(git clean -f *)",
       "Bash(rm -rf *)"
     ]
+  },
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": ".claude/hooks/git-lock-guard.sh",
+            "timeout": 5
+          }
+        ]
+      }
+    ]
   }
 }

.claude/skills/audio-gen/SKILL.md

@@ -13,7 +13,7 @@ description: >
 # Audio Generation — The Settled Reach
 
 Generate sonically consistent audio assets using the Stable Audio Open API via
-wrapper scripts at `db/connectors/audio-*`.
+wrapper scripts at `tooling/db/audio-*`.
 
 Asset descriptions, filenames, bus routing, and design intent are documented in
 `docs/assets/audio/`. This skill provides the prompt system, generation
@@ -25,21 +25,21 @@ workflow, and quality validation.
 
 ```bash
 # Check API health
-db/connectors/audio-health
+tooling/db/audio-health
 
 # Generate a single asset (WAV only)
-db/connectors/audio-generate "prompt text" \
+tooling/db/audio-generate "prompt text" \
   --duration 10 --steps 100 --cfg 7 \
   --output path/to/output.wav
 
 # Generate + post-process in one command (WAV → trim → normalize → OGG)
-db/connectors/audio-generate "prompt text" \
+tooling/db/audio-generate "prompt text" \
   --duration 10 --steps 100 --cfg 7 \
   --output path/to/gen/intermediate.wav \
   --output-ogg client/assets/audio/final.ogg
 
 # Batch-generate from a manifest (preferred for multiple assets)
-db/connectors/audio-batch docs/assets/audio/batch-s10-327.json
+tooling/db/audio-batch docs/assets/audio/batch-s10-327.json
 ```
 
 ### Parameters
@@ -138,16 +138,16 @@ AMB-001, SFX-002, UI-005). This couples the manifest to the asset inventory.
 
 ```bash
 # Full run
-db/connectors/audio-batch docs/assets/audio/batch-s10-327.json
+tooling/db/audio-batch docs/assets/audio/batch-s10-327.json
 
 # Dry run — preview what would be generated
-db/connectors/audio-batch docs/assets/audio/batch-s10-327.json --dry-run
+tooling/db/audio-batch docs/assets/audio/batch-s10-327.json --dry-run
 
 # Generate only specific assets
-db/connectors/audio-batch docs/assets/audio/batch-s10-327.json --only AMB-001,AMB-002
+tooling/db/audio-batch docs/assets/audio/batch-s10-327.json --only AMB-001,AMB-002
 
 # Skip assets that already have OGG files
-db/connectors/audio-batch docs/assets/audio/batch-s10-327.json --skip-existing
+tooling/db/audio-batch docs/assets/audio/batch-s10-327.json --skip-existing
 ```
 
 ### 3. Update asset docs with prompts
@@ -190,8 +190,8 @@ For one-off generation or iteration on a specific asset:
 2. Read `references/sonic-palette.md` for the sonic family prefix.
 3. Read `references/category-templates.md` for the matching template.
 4. Assemble the full prompt.
-5. Run `db/connectors/audio-health` to verify the API is up.
-6. Run `db/connectors/audio-generate` with `--post` or `--output-ogg` to
+5. Run `tooling/db/audio-health` to verify the API is up.
+6. Run `tooling/db/audio-generate` with `--post` or `--output-ogg` to
    generate and post-process in one step.
 7. Verify the output (file size, duration).
 8. Update the asset status and prompt in `docs/assets/audio/{category}.md`.
@@ -218,12 +218,12 @@ If you need to post-process separately (e.g., re-normalizing an existing file):
 
 ```bash
 # Full pipeline: trim → normalize → convert
-db/connectors/audio-post pipeline input.wav --output output.ogg
+tooling/db/audio-post pipeline input.wav --output output.ogg
 
 # Individual steps
-db/connectors/audio-post trim input.wav
-db/connectors/audio-post normalize input.wav --lufs -16
-db/connectors/audio-post convert input.wav --output output.ogg
+tooling/db/audio-post trim input.wav
+tooling/db/audio-post normalize input.wav --lufs -16
+tooling/db/audio-post convert input.wav --output output.ogg
 ```
 
 ## Manual Synthesis (Insert-Tech Sounds)

.claude/skills/bug-report/SKILL.md

@@ -0,0 +1,231 @@
+---
+name: bug-report
+description: >
+  Process in-game bug reports captured by the Godot client's bug reporter.
+  Use when the user says "bug reports", "check bug reports", "process bugs",
+  or invokes /bug-report. Scans the user:// bug-reports directory, summarizes
+  each report, and offers investigation, ticket creation, or dismissal.
+user-invocable: true
+allowed-tools: Bash, Read, Grep, Glob, Write
+---
+
+# Bug Report Skill
+
+Process in-game bug reports exported by the Godot client to the user data
+directory. Each report is a directory containing a snapshot of game state at the
+moment the tester filed the report.
+
+```
+BUG_REPORT_DIR: /var/home/jeroenschweitzer/.local/share/godot/app_userdata/The Settled Reach/bug-reports/
+```
+
+## Report structure
+
+Each report lives in a directory named `gauntlet-t{tick}-{timestamp}/` and
+contains these files:
+
+| File | Purpose |
+|------|---------|
+| `description.txt` | Tester notes + metadata (tick, room, stance, facing, position) |
+| `render.txt` | Simplified text render of the game snapshot |
+| `snapshot.json` | Full JSON snapshot (entities, dialogue state, etc.) |
+| `inputs.jsonl` | Last 60 ticks of player input (replay format) |
+| `snapshots.jsonl` | Last 60 ticks of observer snapshots |
+| `seed.txt` | RNG seed for deterministic replay |
+
+## Invocation
+
+- `/bug-report` — scan and process all unprocessed reports
+- `/bug-report <directory-name>` — process a specific report by directory name
+
+## Workflow
+
+### 1. Scan for unprocessed reports
+
+List all report directories in the bug reports directory:
+
+```bash
+ls -1d "/var/home/jeroenschweitzer/.local/share/godot/app_userdata/The Settled Reach/bug-reports/"*/
+```
+
+If no directories are found, report "No bug reports found." and stop.
+
+If the user provided a specific directory name as argument, filter to only that
+directory. If it does not exist, report the error and list available reports.
+
+### 2. Read and summarize each report
+
+For each report directory, read the following files using the Read tool:
+
+1. **`description.txt`** — extract:
+   - Tester description / notes (free text at top)
+   - Tick number
+   - Room name
+   - Player stance, facing, position
+2. **`render.txt`** — extract:
+   - A brief description of what the text render shows (room layout, visible
+     entities, player position marker)
+3. **`snapshot.json`** — extract:
+   - Total entity count
+   - Whether dialogue is active (look for `dialogue` or `conversation` keys
+     with non-null/non-empty values)
+   - Whether monologue is active (look for `monologue` keys with non-null/
+     non-empty values)
+   - NPC names and positions if present
+   - Any error or anomaly fields
+4. **`seed.txt`** — note the seed value for reference
+
+Do NOT read `inputs.jsonl` or `snapshots.jsonl` during the summary phase.
+These are large files reserved for the investigation step.
+
+### 3. Present the summary list
+
+Present a numbered list of all reports with their summaries. Format:
+
+```
+## Bug Reports Found: N
+
+### 1. gauntlet-t{tick}-{timestamp}
+- **Tick:** {tick} | **Room:** {room} | **Position:** ({x}, {y})
+- **Stance:** {stance} | **Facing:** {facing}
+- **Entities:** {count} | **Dialogue active:** yes/no | **Monologue active:** yes/no
+- **Seed:** {seed}
+- **Description:** {tester notes, first 2-3 lines}
+- **Render overview:** {brief description of what render.txt shows}
+- **Observations:** {any anomalies spotted in the snapshot}
+
+### 2. gauntlet-t{tick}-{timestamp}
+...
+```
+
+### 4. Offer actions per report
+
+After presenting the summary list, ask the user which action to take for each
+report. The three actions are:
+
+#### Investigate
+
+Dig deeper into the report for root cause analysis:
+
+1. Read `snapshot.json` in full — analyze entity states, component values,
+   relationships between entities, any inconsistencies
+2. Read `inputs.jsonl` — reconstruct what the player was doing in the 60 ticks
+   leading up to the report. Look for:
+   - Rapid input changes (stuck keys, input spam)
+   - Movement into walls or invalid positions
+   - Interaction attempts that may have failed
+   - Timing patterns (actions on same tick as state changes)
+3. Read `snapshots.jsonl` — compare entity states across recent ticks to find
+   when the bug manifested:
+   - Entity position jumps
+   - State machine transitions that look wrong
+   - Component values going out of expected range
+   - Entities appearing or disappearing unexpectedly
+4. Cross-reference with `render.txt` to confirm visual manifestation
+5. Read `seed.txt` and note it — the seed plus `inputs.jsonl` should allow
+   deterministic replay of the scenario
+
+Present findings as a root cause analysis:
+
+```
+## Investigation: gauntlet-t{tick}-{timestamp}
+
+### Timeline
+- t{tick-N}: {what happened}
+- t{tick-M}: {state change}
+- t{tick}: {bug manifests}
+
+### Root cause
+{Analysis of what went wrong and why}
+
+### Affected systems
+- {system 1}: {how it's involved}
+- {system 2}: {how it's involved}
+
+### Reproduction
+Seed: {seed}
+Replay inputs.jsonl from tick {start} to reproduce.
+
+### Suggested fix
+{If identifiable from the snapshot data}
+```
+
+After investigation, return to the action prompt for this report (the user
+may want to create a ticket or dismiss after investigating).
+
+#### Create ticket
+
+Create a bug ticket in the project database. Determine the team from the
+nature of the bug:
+
+- **server** — simulation bugs (entity state, movement, AI, ECS systems,
+  perception, knowledge graph)
+- **client** — rendering bugs (display glitches, UI issues, input handling,
+  audio, visual artifacts)
+- **server,client** — integration bugs (protocol mismatch, desync, bridge
+  issues)
+
+Construct the ticket title and description from the report summary and any
+investigation findings. Use the ticket CLI:
+
+```bash
+tooling/db/ticket create bug "{title}" --team {team} --description "{description}"
+```
+
+The description should include:
+- Bug summary (from tester notes)
+- Tick, room, position
+- Key observations from snapshot analysis
+- Seed for reproduction
+- Report directory name for reference
+
+After creating the ticket, report the ticket ID to the user.
+
+#### Dismiss
+
+Mark the report as not actionable. Remove the report directory:
+
+```bash
+rm -rf "/var/home/jeroenschweitzer/.local/share/godot/app_userdata/The Settled Reach/bug-reports/{report-dir}/"
+```
+
+**Always confirm with the user before deleting.** State clearly which directory
+will be removed and wait for confirmation.
+
+### 5. Batch processing
+
+When processing multiple reports, work through them one at a time in the
+numbered order presented. For each report, complete the chosen action before
+moving to the next.
+
+If the user wants to batch-dismiss multiple reports, confirm the full list
+of directories that will be deleted before proceeding.
+
+### 6. Final summary
+
+After all reports have been processed, present a summary:
+
+```
+## Bug Report Processing Complete
+
+- **Investigated:** {count}
+- **Tickets created:** {count} ({ticket IDs})
+- **Dismissed:** {count}
+- **Remaining unprocessed:** {count}
+```
+
+## Tips
+
+- Large `snapshot.json` files may need to be read with offset/limit parameters.
+  Start with the first 200 lines to get the structure, then target specific
+  sections.
+- `inputs.jsonl` and `snapshots.jsonl` are newline-delimited JSON. Each line
+  is one tick. Read the last 10-20 lines first to focus on the moments before
+  the report was filed.
+- The `render.txt` is a text-art representation of the game view. Entity
+  positions in the render should match positions in the snapshot. Mismatches
+  are themselves a bug signal (rendering vs simulation desync).
+- The seed in `seed.txt` combined with `inputs.jsonl` enables deterministic
+  replay on the server. Note this in any ticket you create.
+- If the bug-reports directory does not exist, the tester has not yet run any
+  gauntlet sessions or has not filed any reports. This is not an error.

.claude/skills/d2-diagram/SKILL.md

@@ -0,0 +1,151 @@
+---
+name: d2-diagram
+description: >
+  Generate technical diagrams using d2 (text-to-diagram CLI). Use when the
+  user says "create a diagram", "draw architecture", "make a flowchart",
+  "diagram this", "render d2", "d2", "data flow diagram", "entity relationship",
+  "state machine", "sequence diagram", "UI flow", or invokes /d2-diagram.
+  Produces .d2 source files and renders them to PNG. Also use when asked
+  to update, re-render, or batch render existing diagrams.
+---
+
+# d2 Diagram Generation
+
+Generate technical diagrams from text using d2 (v0.7.1). Pure CLI, no
+external dependencies beyond the d2 binary.
+
+**Binary:** `/home/linuxbrew/.linuxbrew/bin/d2`
+
+## Project Defaults
+
+| Setting | Value | Override |
+|---------|-------|----------|
+| Theme | 200 (Dark Mauve) | `--theme N` |
+| Layout | dagre | `--layout elk` |
+| Padding | 100px | — |
+| Format | PNG | `--svg` |
+
+## Output Convention
+
+```
+docs/diagrams/
+  architecture/    # System architecture, IPC, component layout
+  data-flow/       # Sequence diagrams, data pipelines
+  entity/          # ER diagrams, ECS component schemas
+  state/           # State machines, behavior trees
+  ui/              # UI navigation flow, screen transitions
+```
+
+Both `.d2` source and `.png` output are tracked in git.
+
+## Single Diagram Workflow
+
+1. **Determine category** — architecture, data-flow, entity, state, or ui
+2. **Read template** — `references/diagram-templates.md` for the matching category
+3. **Read syntax** — `references/d2-syntax-guide.md` if unfamiliar with d2 syntax
+4. **Write .d2 source** — to `docs/diagrams/{category}/{name}.d2`
+5. **Validate** — `.claude/skills/d2-diagram/scripts/d2-render.sh validate {file}`
+6. **Render** — `.claude/skills/d2-diagram/scripts/d2-render.sh {file}`
+7. **Read SVG** — verify the output, present to user
+
+### Script Usage
+
+```bash
+# Render with project defaults
+.claude/skills/d2-diagram/scripts/d2-render.sh docs/diagrams/architecture/ipc-bridge.d2
+
+# Validate syntax only
+.claude/skills/d2-diagram/scripts/d2-render.sh validate docs/diagrams/architecture/ipc-bridge.d2
+
+# Auto-format source
+.claude/skills/d2-diagram/scripts/d2-render.sh fmt docs/diagrams/architecture/ipc-bridge.d2
+
+# Sketch mode (hand-drawn look for drafts)
+.claude/skills/d2-diagram/scripts/d2-render.sh docs/diagrams/ui/flow.d2 --sketch
+
+# Light theme (for printable docs)
+.claude/skills/d2-diagram/scripts/d2-render.sh docs/diagrams/entity/schema.d2 --theme 0
+
+# SVG output (if specifically needed)
+.claude/skills/d2-diagram/scripts/d2-render.sh docs/diagrams/architecture/overview.d2 --svg
+```
+
+## Batch Render
+
+Re-render all diagrams after theme or style changes:
+
+```bash
+# All diagrams
+.claude/skills/d2-diagram/scripts/d2-batch.sh
+
+# One category
+.claude/skills/d2-diagram/scripts/d2-batch.sh docs/diagrams/architecture/
+
+# Preview what would render
+.claude/skills/d2-diagram/scripts/d2-batch.sh --dry-run
+
+# Force re-render everything
+.claude/skills/d2-diagram/scripts/d2-batch.sh --force
+```
+
+Batch skips files whose PNG is newer than the `.d2` source unless `--force`.
+
+## Advanced Patterns
+
+### Variables for consistent styling
+
+```d2
+vars: {
+  color-bg: "#2a3040"
+  color-stroke: "#333340"
+  color-text: "#c8d0e0"
+  color-accent: "#c8d8f0"
+}
+```
+
+### Multi-board (layers)
+
+```d2
+# Base diagram here
+
+layers: {
+  detailed: {
+    # More detailed view
+  }
+}
+```
+
+### Sequence diagrams
+
+```d2
+shape: sequence_diagram
+client: Godot Client
+server: Rust Server
+
+client -> server: TickRequest(delta)
+server -> client: WorldState(entities)
+```
+
+### Imports
+
+Split shared definitions into a separate file and import:
+
+```d2
+...@shared-defs.d2
+```
+
+## Agent Guidance
+
+- **Qatux** — Architecture decision records, system overview diagrams, data
+  schemas. Prefer architecture and entity templates.
+- **Tyre** — IPC bridge, ECS system flow, chunk loading pipeline, perception
+  system data flow. Prefer architecture and data-flow templates.
+- **Araminta** — UI navigation flow, screen transitions, component hierarchy.
+  Prefer UI flow template.
+
+## References
+
+- `references/d2-syntax-guide.md` — Language quick reference (shapes, edges,
+  containers, styling, variables). Read when unfamiliar with d2 syntax.
+- `references/diagram-templates.md` — Five category templates with complete
+  d2 source examples. Read when starting a new diagram.

.claude/skills/d2-diagram/references/d2-syntax-guide.md

@@ -0,0 +1,212 @@
+# D2 Language Quick Reference
+
+## Nodes
+
+```d2
+server                              # Implicit label from key
+server: Simulation Server           # Explicit label
+server: Simulation Server {         # With properties
+  shape: hexagon
+  style.fill: "#2d3436"
+}
+```
+
+## Edges
+
+```d2
+a -> b                              # Directed
+a <- b                              # Reverse directed
+a <-> b                             # Bidirectional
+a -- b                              # Undirected
+a -> b: "label"                     # Labeled edge
+a -> b -> c                         # Chained
+```
+
+## Containers (nesting)
+
+```d2
+infrastructure: {
+  server: Simulation Server
+  database: State Store {
+    shape: cylinder
+  }
+}
+```
+
+## Shapes
+
+| Shape | Use for |
+|-------|---------|
+| `rectangle` | Default. Components, modules, generic. |
+| `hexagon` | Systems, services, major components. |
+| `cylinder` | Databases, storage, persistent state. |
+| `diamond` | Decisions, conditions, branch points. |
+| `oval` / `circle` | Start/end states, events. |
+| `cloud` | External systems, networks. |
+| `person` | Actors, users, NPCs. |
+| `queue` | Message queues, buffers. |
+| `page` | Documents, files. |
+| `package` | Packages, modules, crates. |
+| `sql_table` | Database tables, ECS component schemas. |
+| `class` | Class diagrams, ECS system definitions. |
+| `code` | Code blocks (set `language` property). |
+| `markdown` | Rich text blocks. |
+
+## SQL Tables
+
+```d2
+entity: {
+  shape: sql_table
+  id: u64 {constraint: primary_key}
+  name: String
+  position: Vec2
+  faction_id: u64 {constraint: foreign_key}
+}
+```
+
+## Class Diagrams
+
+```d2
+perception_system: {
+  shape: class
+  +run(world: &mut World)
+  -calculate_los(entity: Entity): HashSet<Entity>
+  #update_knowledge(entity: Entity, seen: HashSet<Entity>)
+}
+```
+
+## Sequence Diagrams
+
+```d2
+shape: sequence_diagram
+client: Godot Client
+server: Rust Server
+
+client -> server: TickRequest(delta)
+server -> server: run ECS systems
+server -> client: WorldState(entities)
+```
+
+## Styling
+
+```d2
+node: Label {
+  style: {
+    fill: "#2d3436"
+    stroke: "#333340"
+    stroke-width: 2
+    stroke-dash: 5              # Dashed line
+    opacity: 0.8
+    font-size: 14
+    font-color: "#c8d0e0"
+    bold: true
+    italic: false
+    border-radius: 4
+    shadow: true
+    3d: true                    # Rectangles only
+    multiple: true              # Stacked appearance
+    double-border: true         # Rectangles/ovals only
+  }
+}
+```
+
+### Edge styling
+
+```d2
+a -> b: {
+  style: {
+    stroke: "#c8d8f0"
+    stroke-width: 2
+    stroke-dash: 5
+    opacity: 0.8
+    animated: true              # Animated flow
+  }
+}
+```
+
+## Variables
+
+```d2
+vars: {
+  color-bg: "#1a1e24"
+  color-stroke: "#333340"
+  color-text: "#c8d0e0"
+  color-accent: "#c8d8f0"
+}
+
+node: {
+  style.fill: ${color-bg}
+  style.stroke: ${color-stroke}
+  style.font-color: ${color-text}
+}
+```
+
+## Direction
+
+```d2
+direction: right                    # left-to-right (default for dagre)
+direction: down                     # top-to-bottom
+direction: up
+direction: left
+```
+
+## Imports
+
+```d2
+...@shared-defs.d2                  # Spread import (inline all definitions)
+```
+
+## Icons
+
+```d2
+node: Label {
+  icon: https://icons.terrastruct.com/essentials/time.svg
+}
+```
+
+## Layers (multi-board)
+
+```d2
+# Base diagram content here
+
+layers: {
+  detailed: {
+    # More detailed view
+  }
+  simplified: {
+    # Simplified overview
+  }
+}
+```
+
+## Scenarios (animated transitions)
+
+```d2
+# Base state
+
+scenarios: {
+  alert: {
+    # Changes from base for alert state
+  }
+  combat: {
+    # Changes from base for combat state
+  }
+}
+```
+
+## Comments
+
+```d2
+# This is a comment
+node: Label  # Inline comment
+```
+
+## Project Colors (from visual-grammar-v01.md)
+
+| Constant | Hex | Usage |
+|----------|-----|-------|
+| Zone 1 floor | `#1a1e24` | Dark backgrounds |
+| Zone 1 wall | `#2a3040` | Component fill |
+| Outline standard | `#333340` | Borders, strokes |
+| Insert chrome | `#c8d0e0` | Text, labels |
+| Zone 1 fixture | `#c8d8f0` | Accents, highlights |

.claude/skills/d2-diagram/references/diagram-templates.md

@@ -0,0 +1,251 @@
+# Diagram Templates
+
+Copy, adapt, and render. Each template uses project colors from visual-grammar-v01.md.
+
+---
+
+## 1. Architecture Diagram
+
+System components, relationships, communication channels.
+
+**When to use:** IPC bridge, perception pipeline, chunk loading, ECS system layout, client-server architecture.
+
+**Agents:** Tyre (system architecture), Qatux (architecture decision records).
+
+```d2
+vars: {
+  color-bg: "#2a3040"
+  color-stroke: "#333340"
+  color-text: "#c8d0e0"
+  color-accent: "#c8d8f0"
+}
+
+direction: right
+
+client: Godot Client {
+  shape: hexagon
+  style.fill: ${color-bg}
+  style.font-color: ${color-text}
+
+  rendering: Rendering {
+    style.fill: ${color-bg}
+    style.font-color: ${color-text}
+  }
+  ui: UI Layer {
+    style.fill: ${color-bg}
+    style.font-color: ${color-text}
+  }
+  bridge: IPC Bridge {
+    style.fill: ${color-bg}
+    style.font-color: ${color-text}
+    style.stroke: ${color-accent}
+  }
+}
+
+server: Rust Server {
+  shape: hexagon
+  style.fill: ${color-bg}
+  style.font-color: ${color-text}
+
+  ecs: bevy_ecs {
+    style.fill: ${color-bg}
+    style.font-color: ${color-text}
+  }
+  perception: Perception {
+    style.fill: ${color-bg}
+    style.font-color: ${color-text}
+  }
+  bridge: IPC Bridge {
+    style.fill: ${color-bg}
+    style.font-color: ${color-text}
+    style.stroke: ${color-accent}
+  }
+}
+
+client.bridge -> server.bridge: "stdin/stdout" {
+  style.stroke: ${color-accent}
+  style.stroke-dash: 5
+}
+```
+
+---
+
+## 2. Entity Relationship
+
+Data schemas, ECS components, knowledge graph structure.
+
+**When to use:** Database tables, component definitions, entity relationships, knowledge store schema.
+
+**Agents:** Tyre (ECS component design), Qatux (schema documentation).
+
+```d2
+entity: Entity {
+  shape: sql_table
+  id: u64 {constraint: primary_key}
+  name: String
+  faction_id: u64 {constraint: foreign_key}
+}
+
+position: Position {
+  shape: sql_table
+  entity_id: u64 {constraint: foreign_key}
+  x: f32
+  y: f32
+  chunk_id: u32
+}
+
+knowledge: KnowledgeEntry {
+  shape: sql_table
+  observer_id: u64 {constraint: foreign_key}
+  subject_id: u64 {constraint: foreign_key}
+  fact_type: FactType
+  confidence: f32
+  last_seen_tick: u64
+}
+
+entity.id -> position.entity_id
+entity.id -> knowledge.observer_id
+entity.id -> knowledge.subject_id
+```
+
+---
+
+## 3. Sequence / Data Flow
+
+Ordered interactions between systems over time.
+
+**When to use:** IPC message flow, tick processing, perception update cycle, dialogue system exchanges.
+
+**Agents:** Tyre (system interaction design), Qatux (protocol documentation).
+
+```d2
+shape: sequence_diagram
+
+client: Godot Client
+bridge: IPC Bridge
+server: Rust Server
+ecs: ECS Systems
+
+client -> bridge: TickRequest(delta, input)
+bridge -> server: deserialize + dispatch
+server -> ecs: run_systems(delta)
+ecs -> ecs: perception, AI, physics
+ecs -> server: collect WorldState
+server -> bridge: serialize WorldState
+bridge -> client: WorldState(entities, events)
+client -> client: update rendering
+```
+
+---
+
+## 4. State Machine
+
+Entity states, transitions, conditions.
+
+**When to use:** NPC behavior states, game mode transitions, dialogue state, investigation phases.
+
+**Agents:** Tyre (behavior system design), Qatux (state documentation).
+
+```d2
+vars: {
+  color-state: "#2a3040"
+  color-text: "#c8d0e0"
+  color-edge: "#c8d8f0"
+  color-decision: "#333340"
+}
+
+idle: Idle {
+  style.fill: ${color-state}
+  style.font-color: ${color-text}
+}
+
+alert: Alert {
+  style.fill: ${color-state}
+  style.font-color: ${color-text}
+}
+
+investigate: Investigate {
+  style.fill: ${color-state}
+  style.font-color: ${color-text}
+}
+
+combat: Combat {
+  style.fill: ${color-state}
+  style.font-color: ${color-text}
+  style.stroke: "#f0b840"
+}
+
+flee: Flee {
+  style.fill: ${color-state}
+  style.font-color: ${color-text}
+}
+
+idle -> alert: "stimulus detected" { style.stroke: ${color-edge} }
+alert -> investigate: "stimulus confirmed" { style.stroke: ${color-edge} }
+alert -> idle: "timeout / stimulus lost" { style.stroke: ${color-edge}; style.stroke-dash: 5 }
+investigate -> combat: "threat confirmed" { style.stroke: "#f0b840" }
+investigate -> idle: "nothing found" { style.stroke: ${color-edge}; style.stroke-dash: 5 }
+combat -> flee: "health < threshold" { style.stroke: "#f0b840" }
+combat -> idle: "threat eliminated" { style.stroke: ${color-edge}; style.stroke-dash: 5 }
+flee -> idle: "safe distance reached" { style.stroke: ${color-edge}; style.stroke-dash: 5 }
+```
+
+---
+
+## 5. UI Flow
+
+Screen navigation, component hierarchy, interaction paths.
+
+**When to use:** HUD layout relationships, menu navigation, dialogue flow, insert mode transitions.
+
+**Agents:** Araminta (UI/visual design), Tyre (interface architecture), Qatux (UI documentation).
+
+```d2
+vars: {
+  color-screen: "#1a1e24"
+  color-panel: "#2a3040"
+  color-text: "#c8d0e0"
+  color-nav: "#c8d8f0"
+}
+
+gameplay: Gameplay {
+  style.fill: ${color-screen}
+  style.font-color: ${color-text}
+
+  hud: HUD {
+    style.fill: ${color-panel}
+    style.font-color: ${color-text}
+
+    minimap: Minimap
+    monologue: Monologue Panel
+    insert_display: Insert Display
+  }
+
+  world: World View {
+    style.fill: ${color-panel}
+    style.font-color: ${color-text}
+  }
+}
+
+pause: Pause Menu {
+  style.fill: ${color-screen}
+  style.font-color: ${color-text}
+
+  inventory: Inventory
+  journal: Journal
+  settings: Settings
+}
+
+dialogue: Dialogue Mode {
+  style.fill: ${color-screen}
+  style.font-color: ${color-text}
+
+  speaker: Speaker Panel
+  responses: Response List
+}
+
+gameplay -> pause: "ESC" { style.stroke: ${color-nav} }
+pause -> gameplay: "ESC / Resume" { style.stroke: ${color-nav}; style.stroke-dash: 5 }
+gameplay -> dialogue: "interact with NPC" { style.stroke: ${color-nav} }
+dialogue -> gameplay: "end conversation" { style.stroke: ${color-nav}; style.stroke-dash: 5 }
+```

.claude/skills/d2-diagram/scripts/d2-batch.sh

@@ -0,0 +1,84 @@
+#!/bin/bash
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+REPO_ROOT="$(cd "$SCRIPT_DIR" && git rev-parse --show-toplevel)"
+RENDER="$SCRIPT_DIR/d2-render.sh"
+
+usage() {
+  cat <<EOF
+Usage: $(basename "$0") [directory] [options]
+
+Batch render all .d2 files in a directory. Skips files whose PNG is
+newer than the source unless --force is used.
+
+Options:
+  --dry-run    List files that would be rendered
+  --force      Re-render even if SVG is up to date
+  --theme N    Override theme for all files
+
+Examples:
+  $(basename "$0")                                # All in docs/diagrams/
+  $(basename "$0") docs/diagrams/architecture/    # One category
+  $(basename "$0") --dry-run                      # Preview
+  $(basename "$0") --force                        # Re-render everything
+EOF
+  exit 1
+}
+
+DIR="$REPO_ROOT/docs/diagrams"
+DRY_RUN=false
+FORCE=false
+EXTRA_ARGS=()
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --dry-run) DRY_RUN=true; shift ;;
+    --force)   FORCE=true; shift ;;
+    --theme)   EXTRA_ARGS+=(--theme "$2"); shift 2 ;;
+    --help|-h) usage ;;
+    *)
+      if [[ -d "$1" ]] || [[ -d "$REPO_ROOT/$1" ]]; then
+        DIR="$1"
+        [[ "$DIR" != /* ]] && DIR="$REPO_ROOT/$DIR"
+      else
+        echo "Unknown option or directory: $1" >&2; exit 1
+      fi
+      shift
+      ;;
+  esac
+done
+
+[[ ! -d "$DIR" ]] && { echo "ERROR: Directory not found: $DIR" >&2; exit 1; }
+
+RENDERED=0
+SKIPPED=0
+FAILED=0
+
+while IFS= read -r -d '' d2_file; do
+  png_file="${d2_file%.d2}.png"
+
+  # Skip if PNG is newer than source (unless --force)
+  if [[ "$FORCE" != true ]] && [[ -f "$png_file" ]] && [[ "$png_file" -nt "$d2_file" ]]; then
+    SKIPPED=$((SKIPPED + 1))
+    continue
+  fi
+
+  rel_path="${d2_file#"$REPO_ROOT/"}"
+
+  if [[ "$DRY_RUN" == true ]]; then
+    echo "Would render: $rel_path"
+    RENDERED=$((RENDERED + 1))
+    continue
+  fi
+
+  if "$RENDER" "$d2_file" "${EXTRA_ARGS[@]+"${EXTRA_ARGS[@]}"}"; then
+    RENDERED=$((RENDERED + 1))
+  else
+    echo "FAILED: $rel_path" >&2
+    FAILED=$((FAILED + 1))
+  fi
+done < <(find "$DIR" -name '*.d2' -print0 | sort -z)
+
+echo ""
+echo "Batch complete: $RENDERED rendered, $SKIPPED skipped (up to date), $FAILED failed"

.claude/skills/d2-diagram/scripts/d2-render.sh

@@ -0,0 +1,92 @@
+#!/bin/bash
+set -euo pipefail
+
+D2="/home/linuxbrew/.linuxbrew/bin/d2"
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+REPO_ROOT="$(cd "$SCRIPT_DIR" && git rev-parse --show-toplevel)"
+
+DEFAULT_THEME=200
+DEFAULT_LAYOUT="dagre"
+DEFAULT_PAD=100
+
+usage() {
+  cat <<EOF
+Usage: $(basename "$0") [validate|fmt] <file.d2> [options]
+
+Render a .d2 file to PNG with project defaults (theme $DEFAULT_THEME, $DEFAULT_LAYOUT layout).
+
+Commands:
+  validate <file>     Check syntax without rendering
+  fmt <file>          Auto-format in place
+
+Options:
+  --theme N           Override theme (default: $DEFAULT_THEME)
+  --layout NAME       Override layout engine (default: $DEFAULT_LAYOUT)
+  --sketch            Enable hand-drawn sketch mode
+  --output PATH       Override output path (default: input with .png extension)
+  --svg               Render to SVG instead of PNG
+
+Examples:
+  $(basename "$0") docs/diagrams/architecture/ipc-bridge.d2
+  $(basename "$0") validate docs/diagrams/architecture/ipc-bridge.d2
+  $(basename "$0") docs/diagrams/architecture/ipc-bridge.d2 --sketch --theme 0
+EOF
+  exit 1
+}
+
+[[ $# -lt 1 ]] && usage
+
+# Parse subcommand
+SUBCMD=""
+case "$1" in
+  validate|fmt)
+    SUBCMD="$1"
+    shift
+    ;;
+esac
+
+[[ $# -lt 1 ]] && usage
+
+INPUT="$1"
+shift
+
+# Resolve to absolute path
+[[ "$INPUT" != /* ]] && INPUT="$REPO_ROOT/$INPUT"
+
+[[ ! -f "$INPUT" ]] && { echo "ERROR: File not found: $INPUT" >&2; exit 1; }
+
+# Handle subcommands
+if [[ -n "$SUBCMD" ]]; then
+  "$D2" "$SUBCMD" "$INPUT"
+  echo "OK: $SUBCMD $INPUT"
+  exit 0
+fi
+
+# Parse render options
+THEME="$DEFAULT_THEME"
+LAYOUT="$DEFAULT_LAYOUT"
+SKETCH=""
+OUTPUT=""
+FORMAT="png"
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --theme)  THEME="$2"; shift 2 ;;
+    --layout) LAYOUT="$2"; shift 2 ;;
+    --sketch) SKETCH="-s"; shift ;;
+    --output) OUTPUT="$2"; shift 2 ;;
+    --svg)    FORMAT="svg"; shift ;;
+    *) echo "Unknown option: $1" >&2; exit 1 ;;
+  esac
+done
+
+# Derive output path
+if [[ -z "$OUTPUT" ]]; then
+  OUTPUT="${INPUT%.d2}.$FORMAT"
+fi
+
+# Render
+"$D2" -t "$THEME" -l "$LAYOUT" --pad "$DEFAULT_PAD" $SKETCH "$INPUT" "$OUTPUT"
+
+SIZE=$(stat --printf="%s" "$OUTPUT" 2>/dev/null || stat -f%z "$OUTPUT" 2>/dev/null)
+echo "Rendered: $OUTPUT ($(( SIZE / 1024 ))KB)"

.claude/skills/docs-search/SKILL.md

@@ -10,9 +10,9 @@ allowed-tools: Bash, Read, Grep, Glob
 
 # Search Docs Skill
 
-Semantic search across project documents. Basic commands (`qdrant-search`,
-`qdrant-index`, `qdrant-health`, `qdrant-count`) and endpoints are documented
-in CLAUDE.md. This skill covers advanced operations and workflows.
+Semantic search across project documents. Endpoints are in
+`.claude/rules/local-services.md`. This skill covers advanced operations
+and workflows.
 
 ## Advanced Commands
 
@@ -20,14 +20,14 @@ in CLAUDE.md. This skill covers advanced operations and workflows.
 
 For precise indexing of specific content:
 ```bash
-python3 db/connectors/qdrant_connector.py index "unique-id" "Text content to index" --metadata source=manual heading="Custom heading"
+python3 tooling/db/qdrant_connector.py index "unique-id" "Text content to index" --metadata source=manual heading="Custom heading"
 ```
 
 ### Create collection
 
 Initialize the Qdrant collection (run once during setup):
 ```bash
-python3 db/connectors/qdrant_connector.py create-collection
+python3 tooling/db/qdrant_connector.py create-collection
 ```
 
 ## Bulk Indexing
@@ -35,7 +35,7 @@ python3 db/connectors/qdrant_connector.py create-collection
 Index all project documents at once:
 ```bash
 for f in decisions/*.md DISCUSSION.md TEAM.md docs/discussions/*.md docs/briefings/*.md; do
-  db/connectors/qdrant-index "$f"
+  tooling/db/qdrant-index "$f"
 done
 ```
 

.claude/skills/frame0-wireframe/SKILL.md

@@ -0,0 +1,197 @@
+---
+name: frame0-wireframe
+description: >
+  Create and export UI wireframes using Frame0 (local desktop wireframing
+  app with HTTP API). Use when the user says "create wireframe", "wireframe
+  this", "mock up the UI", "draw a screen", "UI layout", "wireframe the HUD",
+  "Frame0", "frame0", "export wireframe", or invokes /frame0-wireframe.
+  Wireframes are authored as local JSON files (source of truth) and synced
+  to Frame0 for rendering and export. Requires Frame0 to be running locally.
+---
+
+# Frame0 Wireframe Generation
+
+Create UI wireframes as JSON files, sync them to Frame0 for rendering, and
+export as PNG. Local JSON is the source of truth — Frame0 is the renderer.
+
+**Frame0 is a renderer, not a workspace.** Treat it as disposable output.
+Push freely, delete test pages, keep it clean. Never pull from Frame0 unless
+the user explicitly says they have made edits in Frame0 and want to import
+them. The pull workflow exists for that case only — do not use it proactively.
+
+**Prerequisite:** Frame0 desktop app must be running. If not available,
+stop and inform the user. Point to `references/setup-guide.md`.
+
+## Health Check
+
+Always check first:
+
+```bash
+.claude/skills/frame0-wireframe/scripts/frame0-cmd.sh health
+```
+
+## Core Workflow
+
+1. **Health check** — verify Frame0 is running
+2. **Write wireframe JSON** — to `docs/design/wireframes/{category}/{name}.json`
+3. **Push to Frame0** — `frame0-sync.py push <file.json>`
+4. **Export PNG** — `frame0-sync.py export <file.json> <output.png>`
+5. **Clean up** — delete test/scratch pages from Frame0 when done
+
+### Scripts
+
+| Script | Purpose |
+|--------|---------|
+| `scripts/frame0-sync.py` | **Primary.** Push/pull/export wireframes between JSON and Frame0 |
+| `scripts/frame0-cmd.sh` | Low-level API wrapper for ad-hoc commands |
+
+## Wireframe JSON Format
+
+```json
+{
+  "name": "Dialogue Box",
+  "shapes": {
+    "panel": {
+      "type": "Rectangle",
+      "left": 170, "top": 500, "width": 800, "height": 260,
+      "fillColor": "#1a1e24",
+      "strokeColor": "#333340",
+      "corners": [8, 8, 8, 8]
+    },
+    "speaker": {
+      "type": "Text",
+      "parent": "panel",
+      "left": 190, "top": 520,
+      "text": "LERA KONSTANTIN",
+      "fontColor": "#c8d0e0",
+      "fontSize": 16
+    },
+    "btn-ask": {
+      "type": "Rectangle",
+      "parent": "panel",
+      "left": 190, "top": 670, "width": 370, "height": 30,
+      "fillColor": "#2a3040",
+      "strokeColor": "#c8d8f0",
+      "corners": [4, 4, 4, 4]
+    }
+  },
+  "connectors": {
+    "flow-1": {
+      "tailId": "panel",
+      "headId": "btn-ask",
+      "strokeColor": "#c8d8f0"
+    }
+  }
+}
+```
+
+### Key rules
+
+- **Shape IDs are stable local IDs** you control (e.g. `"panel"`, `"btn-ask"`)
+- **`parent`** references another local shape ID for nesting
+- **`type`** uses create-API names: `Rectangle`, `Ellipse`, `Text`, `Line`
+- **Colors** can be hex (`#2a3040`) or Frame0 theme tokens (`$slate6`)
+- After a pull, Frame0 returns its native vocabulary (`Box` for Rectangle,
+  theme tokens for colors). The sync script handles the mapping transparently.
+- The `.idmap.json` mapping file (gitignored) tracks local ID ↔ Frame0 ID
+
+### Sync commands
+
+```bash
+SYNC=".claude/skills/frame0-wireframe/scripts/frame0-sync.py"
+
+# Push local JSON to Frame0 (clears page, recreates all shapes)
+$SYNC push docs/design/wireframes/dialogue/dialogue-box.json
+
+# Pull Frame0 page back to local JSON (preserves local IDs via mapping)
+$SYNC pull "Dialogue Box" docs/design/wireframes/dialogue/dialogue-box.json
+
+# Push + export as PNG in one step
+$SYNC export docs/design/wireframes/dialogue/dialogue-box.json \
+  docs/design/wireframes/dialogue/dialogue-box.png
+```
+
+### Batch export
+
+Use this when exporting multiple wireframes. It runs as a single Bash call,
+avoiding repeated permission prompts.
+
+```bash
+BATCH=".claude/skills/frame0-wireframe/scripts/frame0-export-batch.sh"
+
+# Dry run first — shows full manifest, no Frame0 calls
+$BATCH --dry-run
+
+# Export everything (skips PNGs already newer than their JSON)
+$BATCH
+
+# Export one category only
+$BATCH --category dialogue
+
+# Force re-export of everything
+$BATCH --force
+```
+
+**Always dry-run first, then get approval before running the live export.**
+
+## Low-Level Commands
+
+For ad-hoc operations or exec calls not covered by sync:
+
+```bash
+CMD=".claude/skills/frame0-wireframe/scripts/frame0-cmd.sh"
+$CMD health
+$CMD list-pages
+$CMD current-page
+$CMD get-page <page-id>
+$CMD create-shape Rectangle '{"name":"btn","left":100,"top":100,"width":120,"height":36}'
+$CMD create-connector <tail-id> <head-id>
+$CMD move <shape-id> <dx> <dy>
+$CMD export --format image/png
+$CMD exec "view:fit-to-screen" '{}'
+```
+
+If you find yourself using `exec` for the same command repeatedly, flag it as
+a candidate for a proper wrapper in `frame0-cmd.sh`.
+
+## Project Styling Defaults
+
+Colors from `docs/design/visual-grammar-v01.md`:
+
+| Role | Hex | Frame0 token |
+|------|-----|-------------|
+| Background | `#1a1e24` | `$sage3` |
+| Stroke | `#333340` | `$slate6` |
+| Fill | `#2a3040` | `$slate5` |
+| Text | `#c8d0e0` | `$mint12` |
+| Accent | `#c8d8f0` | `$blue12` |
+
+Use hex when authoring new wireframes. Frame0 maps them to theme tokens on push.
+
+## Output Convention
+
+```
+docs/design/wireframes/
+  hud/              # HUD layout wireframes
+  menus/            # Menu screen wireframes
+  dialogue/         # Dialogue box wireframes
+  insert/           # Neural insert wireframes
+```
+
+Both `.json` source and `.png` exports are tracked in git.
+`.idmap.json` mapping files are gitignored.
+
+## Agent Guidance
+
+- **Araminta** — Primary user. Full wireframe creation, layout iteration,
+  visual consistency. Uses all component library patterns.
+- **Tyre** — Interface architecture wireframes. System boundary diagrams.
+- **Qatux** — Export wireframes for UI decision records and documentation.
+
+## References
+
+- `references/component-library.md` — Pre-built JSON wireframe templates
+  (HUD, dialogue, menus, modals, lists, inventory). Copy and adapt.
+- `references/api-reference.md` — Frame0 HTTP API command reference and
+  type mappings. Read for low-level control.
+- `references/setup-guide.md` — Frame0 installation and startup for Fedora.

.claude/skills/frame0-wireframe/references/api-reference.md

@@ -0,0 +1,241 @@
+# Frame0 HTTP API Reference
+
+Frame0 exposes a local HTTP API when the desktop app is running.
+
+## Endpoint
+
+```
+POST http://localhost:{port}/execute_command
+Content-Type: application/json
+```
+
+Default port: **58320** (override via `FRAME0_PORT` env var or `--port` flag).
+
+## Request / Response
+
+```json
+{"command": "namespace:action", "args": { ... }}
+```
+
+```json
+{"success": true, "data": { ... }}
+{"success": false, "error": "description"}
+```
+
+---
+
+## Type Mapping
+
+Frame0 uses different type names for create vs get:
+
+| Create API (`type`) | Get API (internal) | Description |
+|--------------------|--------------------|-------------|
+| `Rectangle` | `Box` | Rectangle with optional corners |
+| `Ellipse` | `Ellipse` | Circle/ellipse |
+| `Text` | `Text` | Text label |
+| `Line` | `Line` | Line/polyline |
+| `Frame` | `Frame` | Container from library |
+| `Freehand` | `Freehand` | Freehand drawing |
+| `Highlighter` | `Highlighter` | Highlighter stroke |
+
+The sync script handles this mapping transparently.
+
+## Color Tokens
+
+Frame0 maps hex colors to theme tokens on creation (`convertColors: true`):
+
+| Hex | Token | Role |
+|-----|-------|------|
+| `#1a1e24` | `$sage3` | Background |
+| `#2a3040` | `$slate5` | Fill |
+| `#333340` | `$slate6` | Stroke |
+| `#c8d0e0` | `$mint12` | Text |
+| `#c8d8f0` | `$blue12` | Accent |
+
+Both hex and token strings work in the API. Tokens are preserved on round-trip.
+
+---
+
+## Commands
+
+### shape:create-shape
+
+```json
+{
+  "command": "shape:create-shape",
+  "args": {
+    "type": "Rectangle",
+    "shapeProps": {
+      "name": "my-button",
+      "left": 100, "top": 200, "width": 120, "height": 36,
+      "fillColor": "#2a3040",
+      "strokeColor": "#c8d8f0",
+      "corners": [4, 4, 4, 4]
+    },
+    "parentId": "optional-parent-shape-id",
+    "convertColors": true
+  }
+}
+```
+
+Returns: shape ID (string).
+
+### shape:get-shape
+
+```json
+{"command": "shape:get-shape", "args": {"shapeId": "id"}}
+```
+
+### shape:update-shape
+
+```json
+{
+  "command": "shape:update-shape",
+  "args": {
+    "shapeId": "id",
+    "shapeProps": {"fillColor": "#1a1e24", "text": "Updated"},
+    "convertColors": true
+  }
+}
+```
+
+### shape:move
+
+```json
+{"command": "shape:move", "args": {"shapeId": "id", "dx": 50, "dy": -20}}
+```
+
+### shape:create-connector
+
+```json
+{
+  "command": "shape:create-connector",
+  "args": {
+    "tailId": "source-id",
+    "headId": "target-id",
+    "shapeProps": {"strokeColor": "#c8d8f0"},
+    "convertColors": true
+  }
+}
+```
+
+### shape:create-icon
+
+```json
+{
+  "command": "shape:create-icon",
+  "args": {
+    "iconName": "search",
+    "shapeProps": {"left": 100, "top": 100, "width": 24, "height": 24}
+  }
+}
+```
+
+### shape:get-available-icons
+
+```json
+{"command": "shape:get-available-icons", "args": {}}
+```
+
+### shape:group / shape:ungroup
+
+```json
+{"command": "shape:group", "args": {"shapeIdArray": ["id1", "id2"]}}
+{"command": "shape:ungroup", "args": {"shapeIdArray": ["group-id"]}}
+```
+
+### edit:delete / edit:duplicate
+
+```json
+{"command": "edit:delete", "args": {"shapeIdArray": ["id1", "id2"]}}
+{"command": "edit:duplicate", "args": {"shapeIdArray": ["id"], "dx": 20, "dy": 0}}
+```
+
+### page:add
+
+```json
+{"command": "page:add", "args": {"pageProps": {"name": "Page Name"}}}
+```
+
+Returns: `{id, type, name}`.
+
+### page:get
+
+```json
+{"command": "page:get", "args": {"pageId": "id", "exportShapes": true}}
+```
+
+### page:get-current-page
+
+```json
+{"command": "page:get-current-page", "args": {}}
+```
+
+Returns: page ID string.
+
+### page:set-current-page
+
+```json
+{"command": "page:set-current-page", "args": {"pageId": "id"}}
+```
+
+### doc:get (list all pages)
+
+```json
+{"command": "doc:get", "args": {"exportPages": true, "exportShapes": false}}
+```
+
+### page:delete
+
+```json
+{"command": "page:delete", "args": {"pageId": "id"}}
+```
+
+### file:export-image
+
+```json
+{
+  "command": "file:export-image",
+  "args": {
+    "pageId": "optional-page-id",
+    "format": "image/png",
+    "fillBackground": true
+  }
+}
+```
+
+Formats: `image/png`, `image/jpeg`, `image/webp`, `image/svg+xml`.
+Returns: base64-encoded image data.
+
+### view:fit-to-screen
+
+```json
+{"command": "view:fit-to-screen", "args": {}}
+```
+
+---
+
+## Shape Properties
+
+| Property | Type | Notes |
+|----------|------|-------|
+| `name` | string | Shape identifier/label |
+| `left` | number | X position (origin: top-left) |
+| `top` | number | Y position |
+| `width` | number | Width in pixels |
+| `height` | number | Height in pixels |
+| `fillColor` | string | Hex or `$token` |
+| `strokeColor` | string | Hex or `$token` |
+| `strokeWidth` | number | Border width |
+| `fontColor` | string | Text color (hex or `$token`) |
+| `fontSize` | number | Font size in pixels |
+| `fontFamily` | string | Font name (Frame0 default: `Loranthus`) |
+| `text` | string | Text content |
+| `wordWrap` | boolean | Enable word wrapping |
+| `corners` | number[4] | Border radius [TL, TR, BR, BL] |
+| `roughness` | number | Sketch roughness (Frame0 default: 1) |
+| `constraints` | array | Auto-sizing constraints |
+| `horzAlign` | string | Horizontal text alignment |
+| `vertAlign` | string | Vertical text alignment |
+| `fillStyle` | string | Fill style (`none` for transparent) |
+| `path` | array | Coordinate pairs for lines |

.claude/skills/frame0-wireframe/references/component-library.md

@@ -0,0 +1,467 @@
+# Component Library
+
+Pre-built wireframe JSON templates for The Settled Reach UI. Copy the JSON,
+adapt positions/sizes, save to `docs/design/wireframes/{category}/`, and push.
+
+**Viewport:** 1140x780 (Godot project settings)
+**Grid unit:** 8px
+**Min touch target:** 36px height
+**Font sizes:** 12 (label), 14 (body), 16 (subtitle), 18 (heading), 24 (title)
+
+---
+
+## 1. HUD Layout
+
+Main gameplay overlay. Minimap top-right, monologue bottom-center,
+insert display bottom-left, action hints bottom-right.
+
+```json
+{
+  "name": "HUD Layout",
+  "shapes": {
+    "minimap": {
+      "type": "Rectangle",
+      "left": 880, "top": 20, "width": 240, "height": 240,
+      "fillColor": "#1a1e24", "strokeColor": "#333340",
+      "corners": [4, 4, 4, 4]
+    },
+    "minimap-label": {
+      "type": "Text",
+      "parent": "minimap",
+      "left": 890, "top": 30,
+      "text": "Minimap",
+      "fontColor": "#c8d0e0", "fontSize": 14
+    },
+    "monologue": {
+      "type": "Rectangle",
+      "left": 300, "top": 680, "width": 520, "height": 80,
+      "fillColor": "#1a1e24", "strokeColor": "#333340",
+      "corners": [4, 4, 4, 4]
+    },
+    "monologue-text": {
+      "type": "Text",
+      "parent": "monologue",
+      "left": 310, "top": 700, "width": 500,
+      "text": "Internal monologue text appears here...",
+      "fontColor": "#c8d0e0", "fontSize": 13, "wordWrap": true
+    },
+    "insert": {
+      "type": "Rectangle",
+      "left": 20, "top": 600, "width": 260, "height": 160,
+      "fillColor": "#1a1e24", "strokeColor": "#333340",
+      "corners": [4, 4, 4, 4]
+    },
+    "insert-label": {
+      "type": "Text",
+      "parent": "insert",
+      "left": 30, "top": 620,
+      "text": "Neural Insert Data",
+      "fontColor": "#c8d0e0", "fontSize": 14
+    },
+    "hints": {
+      "type": "Rectangle",
+      "left": 880, "top": 700, "width": 240, "height": 60,
+      "fillColor": "#1a1e24", "strokeColor": "#333340",
+      "corners": [4, 4, 4, 4]
+    },
+    "hints-label": {
+      "type": "Text",
+      "parent": "hints",
+      "left": 890, "top": 720,
+      "text": "[E] Interact  [TAB] Insert",
+      "fontColor": "#c8d0e0", "fontSize": 12
+    }
+  }
+}
+```
+
+---
+
+## 2. Dialogue Box
+
+Speaker panel with response options. Anchored bottom-center during dialogue mode.
+
+```json
+{
+  "name": "Dialogue Box",
+  "shapes": {
+    "panel": {
+      "type": "Rectangle",
+      "left": 170, "top": 500, "width": 800, "height": 260,
+      "fillColor": "#1a1e24", "strokeColor": "#333340",
+      "corners": [8, 8, 8, 8]
+    },
+    "speaker": {
+      "type": "Text",
+      "parent": "panel",
+      "left": 190, "top": 520,
+      "text": "LERA KONSTANTIN",
+      "fontColor": "#c8d0e0", "fontSize": 16
+    },
+    "text-area": {
+      "type": "Rectangle",
+      "parent": "panel",
+      "left": 190, "top": 550, "width": 760, "height": 100,
+      "fillColor": "#2a3040", "strokeColor": "#333340",
+      "corners": [4, 4, 4, 4]
+    },
+    "dialogue-text": {
+      "type": "Text",
+      "parent": "text-area",
+      "left": 200, "top": 560, "width": 740,
+      "text": "You look like you could use a drink. First time on the station?",
+      "fontColor": "#c8d0e0", "fontSize": 14, "wordWrap": true
+    },
+    "btn-option1": {
+      "type": "Rectangle",
+      "parent": "panel",
+      "left": 190, "top": 670, "width": 370, "height": 30,
+      "fillColor": "#2a3040", "strokeColor": "#c8d8f0",
+      "corners": [4, 4, 4, 4]
+    },
+    "btn-option1-label": {
+      "type": "Text",
+      "parent": "btn-option1",
+      "left": 200, "top": 674,
+      "text": "[1] Ask about the station",
+      "fontColor": "#c8d8f0", "fontSize": 12
+    },
+    "btn-option2": {
+      "type": "Rectangle",
+      "parent": "panel",
+      "left": 190, "top": 710, "width": 370, "height": 30,
+      "fillColor": "#2a3040", "strokeColor": "#c8d8f0",
+      "corners": [4, 4, 4, 4]
+    },
+    "btn-option2-label": {
+      "type": "Text",
+      "parent": "btn-option2",
+      "left": 200, "top": 714,
+      "text": "[2] Ask about recent events",
+      "fontColor": "#c8d8f0", "fontSize": 12
+    },
+    "btn-leave": {
+      "type": "Rectangle",
+      "parent": "panel",
+      "left": 580, "top": 670, "width": 180, "height": 30,
+      "fillColor": "#2a3040", "strokeColor": "#c8d8f0",
+      "corners": [4, 4, 4, 4]
+    },
+    "btn-leave-label": {
+      "type": "Text",
+      "parent": "btn-leave",
+      "left": 590, "top": 674,
+      "text": "[3] Leave",
+      "fontColor": "#c8d8f0", "fontSize": 12
+    }
+  }
+}
+```
+
+---
+
+## 3. Menu Screen
+
+Full-screen menu with sidebar navigation and content area.
+
+```json
+{
+  "name": "Pause Menu",
+  "shapes": {
+    "bg": {
+      "type": "Rectangle",
+      "left": 0, "top": 0, "width": 1140, "height": 780,
+      "fillColor": "#1a1e24"
+    },
+    "nav": {
+      "type": "Rectangle",
+      "parent": "bg",
+      "left": 20, "top": 20, "width": 200, "height": 740,
+      "fillColor": "#2a3040", "strokeColor": "#333340",
+      "corners": [4, 4, 4, 4]
+    },
+    "btn-inventory": {
+      "type": "Rectangle", "parent": "nav",
+      "left": 30, "top": 40, "width": 180, "height": 36,
+      "fillColor": "#2a3040", "strokeColor": "#c8d8f0", "corners": [4, 4, 4, 4]
+    },
+    "btn-inventory-label": {
+      "type": "Text", "parent": "btn-inventory",
+      "left": 40, "top": 48, "text": "Inventory",
+      "fontColor": "#c8d8f0", "fontSize": 14
+    },
+    "btn-journal": {
+      "type": "Rectangle", "parent": "nav",
+      "left": 30, "top": 86, "width": 180, "height": 36,
+      "fillColor": "#2a3040", "strokeColor": "#c8d8f0", "corners": [4, 4, 4, 4]
+    },
+    "btn-journal-label": {
+      "type": "Text", "parent": "btn-journal",
+      "left": 40, "top": 94, "text": "Journal",
+      "fontColor": "#c8d8f0", "fontSize": 14
+    },
+    "btn-map": {
+      "type": "Rectangle", "parent": "nav",
+      "left": 30, "top": 132, "width": 180, "height": 36,
+      "fillColor": "#2a3040", "strokeColor": "#c8d8f0", "corners": [4, 4, 4, 4]
+    },
+    "btn-map-label": {
+      "type": "Text", "parent": "btn-map",
+      "left": 40, "top": 140, "text": "Map",
+      "fontColor": "#c8d8f0", "fontSize": 14
+    },
+    "btn-settings": {
+      "type": "Rectangle", "parent": "nav",
+      "left": 30, "top": 178, "width": 180, "height": 36,
+      "fillColor": "#2a3040", "strokeColor": "#c8d8f0", "corners": [4, 4, 4, 4]
+    },
+    "btn-settings-label": {
+      "type": "Text", "parent": "btn-settings",
+      "left": 40, "top": 186, "text": "Settings",
+      "fontColor": "#c8d8f0", "fontSize": 14
+    },
+    "btn-resume": {
+      "type": "Rectangle", "parent": "nav",
+      "left": 30, "top": 720, "width": 180, "height": 36,
+      "fillColor": "#2a3040", "strokeColor": "#c8d8f0", "corners": [4, 4, 4, 4]
+    },
+    "btn-resume-label": {
+      "type": "Text", "parent": "btn-resume",
+      "left": 40, "top": 728, "text": "Resume",
+      "fontColor": "#c8d8f0", "fontSize": 14
+    },
+    "content": {
+      "type": "Rectangle",
+      "parent": "bg",
+      "left": 240, "top": 20, "width": 880, "height": 740,
+      "fillColor": "#2a3040", "strokeColor": "#333340",
+      "corners": [4, 4, 4, 4]
+    },
+    "content-label": {
+      "type": "Text", "parent": "content",
+      "left": 260, "top": 40,
+      "text": "Content area",
+      "fontColor": "#c8d0e0", "fontSize": 14
+    }
+  }
+}
+```
+
+---
+
+## 4. Modal Dialog
+
+Centered overlay for confirmations, alerts, choices.
+
+```json
+{
+  "name": "Modal Dialog",
+  "shapes": {
+    "overlay": {
+      "type": "Rectangle",
+      "left": 0, "top": 0, "width": 1140, "height": 780,
+      "fillColor": "#0a0c10"
+    },
+    "modal": {
+      "type": "Rectangle",
+      "parent": "overlay",
+      "left": 320, "top": 240, "width": 500, "height": 300,
+      "fillColor": "#1a1e24", "strokeColor": "#333340",
+      "corners": [8, 8, 8, 8]
+    },
+    "title": {
+      "type": "Text", "parent": "modal",
+      "left": 340, "top": 260,
+      "text": "Confirm Action",
+      "fontColor": "#c8d0e0", "fontSize": 18
+    },
+    "divider": {
+      "type": "Line", "parent": "modal",
+      "left": 340, "top": 290, "width": 460, "height": 0,
+      "strokeColor": "#333340"
+    },
+    "body-1": {
+      "type": "Text", "parent": "modal",
+      "left": 340, "top": 310,
+      "text": "Are you sure you want to proceed?",
+      "fontColor": "#c8d0e0", "fontSize": 14
+    },
+    "body-2": {
+      "type": "Text", "parent": "modal",
+      "left": 340, "top": 340,
+      "text": "This action cannot be undone.",
+      "fontColor": "#c8d0e0", "fontSize": 14
+    },
+    "btn-cancel": {
+      "type": "Rectangle", "parent": "modal",
+      "left": 480, "top": 480, "width": 120, "height": 36,
+      "fillColor": "#2a3040", "strokeColor": "#c8d8f0", "corners": [4, 4, 4, 4]
+    },
+    "btn-cancel-label": {
+      "type": "Text", "parent": "btn-cancel",
+      "left": 510, "top": 488,
+      "text": "Cancel",
+      "fontColor": "#c8d8f0", "fontSize": 14
+    },
+    "btn-confirm": {
+      "type": "Rectangle", "parent": "modal",
+      "left": 620, "top": 480, "width": 120, "height": 36,
+      "fillColor": "#2a3040", "strokeColor": "#c8d8f0", "corners": [4, 4, 4, 4]
+    },
+    "btn-confirm-label": {
+      "type": "Text", "parent": "btn-confirm",
+      "left": 645, "top": 488,
+      "text": "Confirm",
+      "fontColor": "#c8d8f0", "fontSize": 14
+    }
+  }
+}
+```
+
+---
+
+## 5. List View
+
+Scrollable list with item selection and detail panel.
+
+```json
+{
+  "name": "List View",
+  "shapes": {
+    "list-panel": {
+      "type": "Rectangle",
+      "left": 20, "top": 20, "width": 400, "height": 740,
+      "fillColor": "#1a1e24", "strokeColor": "#333340", "corners": [4, 4, 4, 4]
+    },
+    "item-1": {
+      "type": "Rectangle", "parent": "list-panel",
+      "left": 30, "top": 30, "width": 380, "height": 40,
+      "fillColor": "#2a3040", "strokeColor": "#c8d8f0", "corners": [4, 4, 4, 4]
+    },
+    "item-1-label": {
+      "type": "Text", "parent": "item-1",
+      "left": 40, "top": 38, "text": "Item Alpha",
+      "fontColor": "#c8d8f0", "fontSize": 14
+    },
+    "item-2": {
+      "type": "Rectangle", "parent": "list-panel",
+      "left": 30, "top": 80, "width": 380, "height": 40,
+      "fillColor": "#2a3040", "strokeColor": "#333340", "corners": [4, 4, 4, 4]
+    },
+    "item-2-label": {
+      "type": "Text", "parent": "item-2",
+      "left": 40, "top": 88, "text": "Item Beta",
+      "fontColor": "#c8d0e0", "fontSize": 14
+    },
+    "item-3": {
+      "type": "Rectangle", "parent": "list-panel",
+      "left": 30, "top": 130, "width": 380, "height": 40,
+      "fillColor": "#2a3040", "strokeColor": "#333340", "corners": [4, 4, 4, 4]
+    },
+    "item-3-label": {
+      "type": "Text", "parent": "item-3",
+      "left": 40, "top": 138, "text": "Item Gamma",
+      "fontColor": "#c8d0e0", "fontSize": 14
+    },
+    "detail-panel": {
+      "type": "Rectangle",
+      "left": 440, "top": 20, "width": 680, "height": 740,
+      "fillColor": "#1a1e24", "strokeColor": "#333340", "corners": [4, 4, 4, 4]
+    },
+    "detail-title": {
+      "type": "Text", "parent": "detail-panel",
+      "left": 460, "top": 40,
+      "text": "Item Alpha",
+      "fontColor": "#c8d0e0", "fontSize": 18
+    },
+    "detail-body": {
+      "type": "Text", "parent": "detail-panel",
+      "left": 460, "top": 80, "width": 640,
+      "text": "Description and properties appear here.",
+      "fontColor": "#c8d0e0", "fontSize": 14, "wordWrap": true
+    }
+  }
+}
+```
+
+---
+
+## 6. Inventory Grid
+
+Grid of cells for item management.
+
+```json
+{
+  "name": "Inventory Grid",
+  "shapes": {
+    "panel": {
+      "type": "Rectangle",
+      "left": 240, "top": 100, "width": 660, "height": 580,
+      "fillColor": "#1a1e24", "strokeColor": "#333340", "corners": [8, 8, 8, 8]
+    },
+    "title": {
+      "type": "Text", "parent": "panel",
+      "left": 260, "top": 120,
+      "text": "INVENTORY",
+      "fontColor": "#c8d0e0", "fontSize": 18
+    },
+    "cell-1-1": {
+      "type": "Rectangle", "parent": "panel",
+      "left": 260, "top": 160, "width": 64, "height": 64,
+      "fillColor": "#2a3040", "strokeColor": "#333340", "corners": [4, 4, 4, 4]
+    },
+    "cell-1-2": {
+      "type": "Rectangle", "parent": "panel",
+      "left": 332, "top": 160, "width": 64, "height": 64,
+      "fillColor": "#2a3040", "strokeColor": "#333340", "corners": [4, 4, 4, 4]
+    },
+    "cell-1-3": {
+      "type": "Rectangle", "parent": "panel",
+      "left": 404, "top": 160, "width": 64, "height": 64,
+      "fillColor": "#2a3040", "strokeColor": "#333340", "corners": [4, 4, 4, 4]
+    },
+    "cell-1-4": {
+      "type": "Rectangle", "parent": "panel",
+      "left": 476, "top": 160, "width": 64, "height": 64,
+      "fillColor": "#2a3040", "strokeColor": "#333340", "corners": [4, 4, 4, 4]
+    },
+    "cell-2-1": {
+      "type": "Rectangle", "parent": "panel",
+      "left": 260, "top": 232, "width": 64, "height": 64,
+      "fillColor": "#2a3040", "strokeColor": "#333340", "corners": [4, 4, 4, 4]
+    },
+    "cell-2-2": {
+      "type": "Rectangle", "parent": "panel",
+      "left": 332, "top": 232, "width": 64, "height": 64,
+      "fillColor": "#2a3040", "strokeColor": "#333340", "corners": [4, 4, 4, 4]
+    },
+    "cell-2-3": {
+      "type": "Rectangle", "parent": "panel",
+      "left": 404, "top": 232, "width": 64, "height": 64,
+      "fillColor": "#2a3040", "strokeColor": "#333340", "corners": [4, 4, 4, 4]
+    },
+    "cell-2-4": {
+      "type": "Rectangle", "parent": "panel",
+      "left": 476, "top": 232, "width": 64, "height": 64,
+      "fillColor": "#2a3040", "strokeColor": "#333340", "corners": [4, 4, 4, 4]
+    },
+    "detail": {
+      "type": "Rectangle", "parent": "panel",
+      "left": 580, "top": 160, "width": 300, "height": 400,
+      "fillColor": "#2a3040", "strokeColor": "#333340", "corners": [4, 4, 4, 4]
+    },
+    "detail-title": {
+      "type": "Text", "parent": "detail",
+      "left": 600, "top": 180,
+      "text": "Selected Item Name",
+      "fontColor": "#c8d0e0", "fontSize": 16
+    },
+    "detail-body": {
+      "type": "Text", "parent": "detail",
+      "left": 600, "top": 210, "width": 260,
+      "text": "Item description and stats",
+      "fontColor": "#c8d0e0", "fontSize": 14, "wordWrap": true
+    }
+  }
+}
+```

.claude/skills/frame0-wireframe/references/setup-guide.md

@@ -0,0 +1,53 @@
+# Frame0 Setup Guide
+
+## Installation (Fedora)
+
+Download from https://frame0.app/download and install the RPM:
+
+```bash
+sudo dnf install ./frame0-*.x86_64.rpm
+```
+
+Requires: Fedora 40 or later (x86_64).
+
+## Starting Frame0
+
+Launch the desktop application:
+
+```bash
+frame0 &
+```
+
+Frame0 exposes an HTTP API at `localhost:58320` when running.
+
+## Verify API Access
+
+```bash
+.claude/skills/frame0-wireframe/scripts/frame0-cmd.sh health
+```
+
+Expected output: `Frame0 is running on port 58320`
+
+## Port Configuration
+
+Default port: **58320**
+
+To use a different port, set the environment variable:
+
+```bash
+export FRAME0_PORT=58321
+```
+
+Or pass `--port` to any script:
+
+```bash
+.claude/skills/frame0-wireframe/scripts/frame0-cmd.sh --port 58321 health
+```
+
+## Troubleshooting
+
+| Symptom | Cause | Fix |
+|---------|-------|-----|
+| "Connection refused" | Frame0 not running | Start the desktop app |
+| "Port in use" | Another instance running | Close duplicate or use different port |
+| Script hangs | API unresponsive | Restart Frame0 |

.claude/skills/frame0-wireframe/scripts/frame0-cmd.sh

@@ -0,0 +1,253 @@
+#!/bin/bash
+set -euo pipefail
+
+PORT="${FRAME0_PORT:-58320}"
+ENDPOINT="http://localhost:${PORT}/execute_command"
+
+usage() {
+  cat <<EOF
+Usage: $(basename "$0") <command> [args...] [--port N]
+
+Low-level Frame0 HTTP API wrapper. Replaces the MCP server with direct
+curl calls. Requires Frame0 desktop app to be running.
+
+Commands:
+  health                              Check if Frame0 is running
+  exec <namespace:action> <json>      Execute a raw API command
+  create-shape <type> <json-props>    Create a shape (Rectangle, Ellipse, Text, Line)
+  get-shape <id>                      Get shape details
+  update-shape <id> <json-props>      Update shape properties
+  delete <id> [id...]                 Delete shapes by ID
+  move <id> <dx> <dy>                 Move a shape by pixel offset
+  duplicate <id>                      Duplicate a shape
+  group <id> [id...]                  Group shapes
+  ungroup <group-id>                  Ungroup a group
+  create-connector <tail-id> <head-id> [json-props]  Connect two shapes
+  create-icon <name> <json-props>     Create an icon shape
+  add-page <name>                     Add a new page (becomes current)
+  get-page [page-id]                  Get current or specific page data
+  list-pages [--shapes]               List all pages (--shapes for shape data)
+  current-page                        Get current page ID
+  set-page <page-id>                  Set current page
+  export [page-id] [--format mime]    Export page as image (default: image/png)
+  fit                                 Fit view to screen
+
+Options:
+  --port N    Frame0 API port (default: $PORT, env: FRAME0_PORT)
+
+Examples:
+  $(basename "$0") health
+  $(basename "$0") add-page "HUD Layout"
+  $(basename "$0") create-shape Rectangle '{"name":"btn","left":100,"top":100,"width":120,"height":36}'
+  $(basename "$0") list-pages
+  $(basename "$0") export --format image/png
+EOF
+  exit 1
+}
+
+# Parse --port from anywhere in args
+ARGS=()
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --port) PORT="$2"; ENDPOINT="http://localhost:${PORT}/execute_command"; shift 2 ;;
+    *)      ARGS+=("$1"); shift ;;
+  esac
+done
+set -- "${ARGS[@]+"${ARGS[@]}"}"
+
+[[ $# -lt 1 ]] && usage
+
+# Execute a Frame0 API command, return data or error
+frame0_exec() {
+  local command="$1"
+  local args
+  args="${2:-"{}"}"
+
+  local response
+  response=$(curl -s -w "\n%{http_code}" -X POST "$ENDPOINT" \
+    -H "Content-Type: application/json" \
+    -d "{\"command\": \"$command\", \"args\": $args}" 2>&1) || {
+    echo "ERROR: Cannot connect to Frame0 at localhost:$PORT" >&2
+    echo "Is Frame0 running? See: .claude/skills/frame0-wireframe/references/setup-guide.md" >&2
+    return 1
+  }
+
+  local http_code body
+  http_code=$(echo "$response" | tail -1)
+  body=$(echo "$response" | sed '$d')
+
+  if [[ "$http_code" != 2* ]]; then
+    echo "ERROR: HTTP $http_code from Frame0" >&2
+    echo "$body" >&2
+    return 1
+  fi
+
+  # Parse success/error from response
+  python3 -c "
+import sys, json
+try:
+    r = json.loads(sys.stdin.read())
+    if r.get('success'):
+        d = r.get('data')
+        if d is not None:
+            print(json.dumps(d, indent=2))
+    else:
+        print('ERROR: ' + str(r.get('error', 'Unknown error')), file=sys.stderr)
+        sys.exit(1)
+except json.JSONDecodeError as e:
+    print(f'ERROR: Invalid JSON response: {e}', file=sys.stderr)
+    sys.exit(1)
+" <<< "$body"
+}
+
+# Build JSON array from remaining args
+ids_to_json_array() {
+  local arr="["
+  local first=true
+  for id in "$@"; do
+    [[ "$first" == true ]] && first=false || arr+=","
+    arr+="\"$id\""
+  done
+  arr+="]"
+  echo "$arr"
+}
+
+CMD="${1:-}"
+shift || true
+
+case "$CMD" in
+  health)
+    if curl -s -o /dev/null -w "%{http_code}" "http://localhost:${PORT}/" 2>/dev/null | grep -q "^[23]"; then
+      echo "Frame0 is running on port $PORT"
+    else
+      echo "Frame0 is NOT running on port $PORT" >&2
+      echo "Start Frame0 desktop app, then retry." >&2
+      echo "See: .claude/skills/frame0-wireframe/references/setup-guide.md" >&2
+      exit 1
+    fi
+    ;;
+
+  exec)
+    [[ $# -lt 2 ]] && { echo "Usage: exec <command> <json-args>" >&2; exit 1; }
+    frame0_exec "$1" "$2"
+    ;;
+
+  create-shape)
+    [[ $# -lt 2 ]] && { echo "Usage: create-shape <Type> <json-props>" >&2; exit 1; }
+    local_type="$1"
+    local_props="$2"
+    local_parent="${3:-}"
+    local_parent_arg=""
+    [[ -n "$local_parent" ]] && local_parent_arg=", \"parentId\": \"$local_parent\""
+    frame0_exec "shape:create-shape" "{\"type\": \"$local_type\", \"shapeProps\": $local_props$local_parent_arg, \"convertColors\": true}"
+    ;;
+
+  get-shape)
+    [[ $# -lt 1 ]] && { echo "Usage: get-shape <id>" >&2; exit 1; }
+    frame0_exec "shape:get-shape" "{\"shapeId\": \"$1\"}"
+    ;;
+
+  update-shape)
+    [[ $# -lt 2 ]] && { echo "Usage: update-shape <id> <json-props>" >&2; exit 1; }
+    frame0_exec "shape:update-shape" "{\"shapeId\": \"$1\", \"shapeProps\": $2, \"convertColors\": true}"
+    ;;
+
+  delete)
+    [[ $# -lt 1 ]] && { echo "Usage: delete <id> [id...]" >&2; exit 1; }
+    local_arr=$(ids_to_json_array "$@")
+    frame0_exec "edit:delete" "{\"shapeIdArray\": $local_arr}"
+    ;;
+
+  move)
+    [[ $# -lt 3 ]] && { echo "Usage: move <id> <dx> <dy>" >&2; exit 1; }
+    frame0_exec "shape:move" "{\"shapeId\": \"$1\", \"dx\": $2, \"dy\": $3}"
+    ;;
+
+  duplicate)
+    [[ $# -lt 1 ]] && { echo "Usage: duplicate <id> [dx] [dy]" >&2; exit 1; }
+    local_dx="${2:-0}"
+    local_dy="${3:-0}"
+    frame0_exec "edit:duplicate" "{\"shapeIdArray\": [\"$1\"], \"dx\": $local_dx, \"dy\": $local_dy}"
+    ;;
+
+  group)
+    [[ $# -lt 2 ]] && { echo "Usage: group <id> <id> [id...]" >&2; exit 1; }
+    local_arr=$(ids_to_json_array "$@")
+    frame0_exec "shape:group" "{\"shapeIdArray\": $local_arr}"
+    ;;
+
+  ungroup)
+    [[ $# -lt 1 ]] && { echo "Usage: ungroup <group-id>" >&2; exit 1; }
+    frame0_exec "shape:ungroup" "{\"shapeIdArray\": [\"$1\"]}"
+    ;;
+
+  create-connector)
+    [[ $# -lt 2 ]] && { echo "Usage: create-connector <tail-id> <head-id> [json-props]" >&2; exit 1; }
+    local_props="${3:-{}}"
+    frame0_exec "shape:create-connector" "{\"tailId\": \"$1\", \"headId\": \"$2\", \"shapeProps\": $local_props, \"convertColors\": true}"
+    ;;
+
+  create-icon)
+    [[ $# -lt 2 ]] && { echo "Usage: create-icon <name> <json-props>" >&2; exit 1; }
+    frame0_exec "shape:create-icon" "{\"iconName\": \"$1\", \"shapeProps\": $2, \"convertColors\": true}"
+    ;;
+
+  add-page)
+    [[ $# -lt 1 ]] && { echo "Usage: add-page <name>" >&2; exit 1; }
+    frame0_exec "page:add" "{\"pageProps\": {\"name\": \"$1\"}}"
+    ;;
+
+  get-page)
+    if [[ $# -ge 1 ]]; then
+      frame0_exec "page:get" "{\"pageId\": \"$1\", \"exportShapes\": true}"
+    else
+      local_id
+      local_id=$(frame0_exec "page:get-current-page")
+      # Strip quotes from returned ID
+      local_id=$(echo "$local_id" | tr -d '"')
+      frame0_exec "page:get" "{\"pageId\": \"$local_id\", \"exportShapes\": true}"
+    fi
+    ;;
+
+  list-pages)
+    local_shapes="false"
+    [[ "${1:-}" == "--shapes" ]] && local_shapes="true"
+    frame0_exec "doc:get" "{\"exportPages\": true, \"exportShapes\": $local_shapes}"
+    ;;
+
+  current-page)
+    frame0_exec "page:get-current-page"
+    ;;
+
+  set-page)
+    [[ $# -lt 1 ]] && { echo "Usage: set-page <page-id>" >&2; exit 1; }
+    frame0_exec "page:set-current-page" "{\"pageId\": \"$1\"}"
+    ;;
+
+  export)
+    local_page_id=""
+    local_format="image/png"
+    while [[ $# -gt 0 ]]; do
+      case "$1" in
+        --format) local_format="$2"; shift 2 ;;
+        *) local_page_id="$1"; shift ;;
+      esac
+    done
+    local_page_arg=""
+    [[ -n "$local_page_id" ]] && local_page_arg="\"pageId\": \"$local_page_id\", "
+    frame0_exec "file:export-image" "{${local_page_arg}\"format\": \"$local_format\", \"fillBackground\": true}"
+    ;;
+
+  fit)
+    frame0_exec "view:fit-to-screen"
+    ;;
+
+  --help|-h|help)
+    usage
+    ;;
+
+  *)
+    echo "Unknown command: $CMD" >&2
+    usage
+    ;;
+esac

.claude/skills/frame0-wireframe/scripts/frame0-export-batch.sh

@@ -0,0 +1,159 @@
+#!/usr/bin/env bash
+# Batch export wireframes from JSON to PNG via Frame0.
+#
+# Finds all .json wireframe files under docs/design/wireframes/ and exports
+# each to a matching .png. Skips files whose PNG is already newer than the
+# JSON, unless --force is passed.
+#
+# Usage:
+#   frame0-export-batch.sh [--dry-run] [--force] [--category CAT] [--root DIR]
+#
+# Options:
+#   --dry-run       Print manifest only, don't touch Frame0.
+#   --force         Re-export even if PNG already exists and is up to date.
+#   --category CAT  Limit to one subdirectory (e.g. --category dialogue)
+#   --root DIR      Wireframes root dir (default: docs/design/wireframes)
+#
+# Exit codes:
+#   0  All exports succeeded (or nothing to do)
+#   1  One or more exports failed
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd "$SCRIPT_DIR/../../../.." && pwd)"
+SYNC="$SCRIPT_DIR/frame0-sync.py"
+DEFAULT_ROOT="$REPO_ROOT/docs/design/wireframes"
+
+DRY_RUN=false
+FORCE=false
+CATEGORY=""
+WF_ROOT="$DEFAULT_ROOT"
+
+# Parse arguments
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --dry-run)    DRY_RUN=true; shift ;;
+    --force)      FORCE=true; shift ;;
+    --category)   CATEGORY="$2"; shift 2 ;;
+    --root)       WF_ROOT="$2"; shift 2 ;;
+    -h|--help)
+      sed -n '/^# /p' "$0" | sed 's/^# //'
+      exit 0
+      ;;
+    *) echo "Unknown option: $1" >&2; exit 1 ;;
+  esac
+done
+
+if [[ ! -d "$WF_ROOT" ]]; then
+  echo "ERROR: Wireframes directory not found: $WF_ROOT" >&2
+  exit 1
+fi
+
+# Collect JSON files, optionally filtered by category subdirectory
+mapfile -t JSON_FILES < <(
+  if [[ -n "$CATEGORY" ]]; then
+    find "$WF_ROOT/$CATEGORY" -name "*.json" ! -name ".*" | sort
+  else
+    find "$WF_ROOT" -name "*.json" ! -name ".*" | sort
+  fi
+)
+
+if [[ ${#JSON_FILES[@]} -eq 0 ]]; then
+  echo "No wireframe JSON files found."
+  exit 0
+fi
+
+# Classify files into to-export and to-skip
+TO_EXPORT=()
+TO_SKIP=()
+
+for json in "${JSON_FILES[@]}"; do
+  png="${json%.json}.png"
+  if $FORCE || [[ ! -f "$png" ]] || [[ "$json" -nt "$png" ]]; then
+    TO_EXPORT+=("$json")
+  else
+    TO_SKIP+=("$json")
+  fi
+done
+
+# Print manifest
+if [[ ${#TO_EXPORT[@]} -gt 0 ]]; then
+  echo ""
+  echo "Will export (${#TO_EXPORT[@]} files):"
+  for json in "${TO_EXPORT[@]}"; do
+    png="${json%.json}.png"
+    rel="${json#$REPO_ROOT/}"
+    if [[ ! -f "$png" ]]; then
+      status="new"
+    else
+      status="updated"
+    fi
+    printf "  [%-7s]  %s\n" "$status" "$rel"
+  done
+else
+  echo ""
+  echo "Nothing to export (all PNGs up to date)."
+fi
+
+if [[ ${#TO_SKIP[@]} -gt 0 ]]; then
+  echo ""
+  echo "Will skip (${#TO_SKIP[@]} files already up to date):"
+  for json in "${TO_SKIP[@]}"; do
+    rel="${json#$REPO_ROOT/}"
+    printf "  [skip   ]  %s\n" "$rel"
+  done
+fi
+
+if $DRY_RUN; then
+  echo ""
+  echo "Dry run — no exports performed."
+  exit 0
+fi
+
+if [[ ${#TO_EXPORT[@]} -eq 0 ]]; then
+  exit 0
+fi
+
+echo ""
+PASSED=0
+FAILED=0
+FAILED_FILES=()
+
+TOTAL=${#TO_EXPORT[@]}
+IDX=0
+
+for json in "${TO_EXPORT[@]}"; do
+  IDX=$((IDX + 1))
+  png="${json%.json}.png"
+  rel="${json#$REPO_ROOT/}"
+
+  printf "[%d/%d]  %s ... " "$IDX" "$TOTAL" "$rel"
+
+  output=$(python3 "$SYNC" export "$json" "$png" 2>/tmp/frame0-batch-err.txt)
+  rc=$?
+  if [[ $rc -eq 0 ]]; then
+    size=$(echo "$output" | tail -1 | grep -oP '\(\K[^)]+' || true)
+    echo "ok  $size"
+    PASSED=$((PASSED + 1))
+  else
+    echo "FAILED"
+    cat /tmp/frame0-batch-err.txt >&2
+    FAILED=$((FAILED + 1))
+    FAILED_FILES+=("$rel")
+  fi
+done
+
+echo ""
+echo "$PASSED exported, $FAILED failed."
+
+if [[ $FAILED -gt 0 ]]; then
+  echo ""
+  echo "Failed:" >&2
+  for f in "${FAILED_FILES[@]}"; do
+    echo "  $f" >&2
+  done
+  exit 1
+fi
+
+exit 0

.claude/skills/frame0-wireframe/scripts/frame0-sync.py

@@ -0,0 +1,414 @@
+#!/usr/bin/env python3
+"""Frame0 sync: push local JSON wireframes to Frame0, pull pages back.
+
+Local JSON is source of truth. Frame0 is a renderer.
+A mapping file tracks local_id <-> frame0_id across push/pull cycles.
+
+Usage:
+    frame0-sync.py push <wireframe.json> [--port PORT]
+    frame0-sync.py pull <page-id|page-name> <output.json> [--port PORT]
+    frame0-sync.py export <wireframe.json> <output.png> [--port PORT] [--format MIME]
+"""
+
+import argparse
+import json
+import os
+import sys
+import urllib.request
+import urllib.error
+
+DEFAULT_PORT = 58320
+
+
+def api(port, command, args=None):
+    """Execute a Frame0 API command. Returns the data field on success."""
+    url = f"http://localhost:{port}/execute_command"
+    payload = json.dumps({"command": command, "args": args or {}}).encode()
+    req = urllib.request.Request(url, data=payload, headers={"Content-Type": "application/json"})
+    try:
+        with urllib.request.urlopen(req) as resp:
+            result = json.loads(resp.read())
+    except urllib.error.HTTPError as e:
+        body = e.read().decode()
+        print(f"ERROR: {command}: HTTP {e.code}: {body[:500]}", file=sys.stderr)
+        sys.exit(1)
+    except urllib.error.URLError as e:
+        print(f"ERROR: Cannot connect to Frame0 on port {port}: {e}", file=sys.stderr)
+        sys.exit(1)
+
+    if not result.get("success"):
+        print(f"ERROR: {command}: {result.get('error', 'unknown')}", file=sys.stderr)
+        sys.exit(1)
+
+    return result.get("data")
+
+
+# -- Mapping file management --------------------------------------------------
+
+def mapping_path(wireframe_path):
+    """Derive the idmap path from the wireframe JSON path."""
+    d = os.path.dirname(wireframe_path)
+    base = os.path.splitext(os.path.basename(wireframe_path))[0]
+    return os.path.join(d, f".{base}.idmap.json")
+
+
+def load_mapping(wireframe_path):
+    p = mapping_path(wireframe_path)
+    if os.path.exists(p):
+        with open(p) as f:
+            return json.load(f)
+    return {"page_id": None, "shapes": {}, "connectors": {}}
+
+
+def save_mapping(wireframe_path, mapping):
+    p = mapping_path(wireframe_path)
+    os.makedirs(os.path.dirname(p) or ".", exist_ok=True)
+    with open(p, "w") as f:
+        json.dump(mapping, f, indent=2)
+        f.write("\n")
+
+
+# -- Push: local JSON -> Frame0 -----------------------------------------------
+
+# Frame0 returns different type names from get vs what create accepts.
+# Map internal types back to create-API types.
+TYPE_TO_CREATE = {
+    "Box": "Rectangle",
+    "box": "Rectangle",
+}
+
+
+def topo_sort_shapes(shapes):
+    """Sort shape IDs so parents come before children."""
+    order = []
+    visited = set()
+
+    def visit(sid):
+        if sid in visited:
+            return
+        visited.add(sid)
+        shape = shapes[sid]
+        parent = shape.get("parent")
+        if parent and parent in shapes:
+            visit(parent)
+        order.append(sid)
+
+    for sid in shapes:
+        visit(sid)
+    return order
+
+
+def find_or_create_page(port, name, mapping):
+    """Find existing page by mapping or name, or create a new one."""
+    # Try mapped page_id first
+    if mapping.get("page_id"):
+        try:
+            page = api(port, "page:get", {"pageId": mapping["page_id"]})
+            if page:
+                return mapping["page_id"]
+        except SystemExit:
+            pass  # Page no longer exists, fall through
+
+    # Search by name in existing pages
+    doc = api(port, "doc:get", {"exportPages": True, "exportShapes": False})
+    if doc and "children" in doc:
+        for page in doc["children"]:
+            if page.get("name") == name:
+                return page["id"]
+
+    # Create new page
+    page = api(port, "page:add", {"pageProps": {"name": name}})
+    return page["id"]
+
+
+def clear_page(port, page_id):
+    """Delete all shapes on a page."""
+    page = api(port, "page:get", {"pageId": page_id, "exportShapes": True})
+    if not page or "children" not in page:
+        return
+    shape_ids = [s["id"] for s in page["children"]]
+    if shape_ids:
+        api(port, "edit:delete", {"shapeIdArray": shape_ids})
+
+
+def push(wireframe_path, port):
+    """Push local wireframe JSON to Frame0."""
+    with open(wireframe_path) as f:
+        wireframe = json.load(f)
+
+    name = wireframe.get("name", os.path.splitext(os.path.basename(wireframe_path))[0])
+    shapes = wireframe.get("shapes", {})
+    connectors = wireframe.get("connectors", {})
+
+    mapping = load_mapping(wireframe_path)
+
+    # Find or create page
+    page_id = find_or_create_page(port, name, mapping)
+    mapping["page_id"] = page_id
+
+    # Switch to page and clear it
+    api(port, "page:set-current-page", {"pageId": page_id})
+    clear_page(port, page_id)
+
+    # Reset ID mappings (shapes are recreated)
+    mapping["shapes"] = {}
+    mapping["connectors"] = {}
+
+    # Create shapes in dependency order
+    order = topo_sort_shapes(shapes)
+    for local_id in order:
+        shape = shapes[local_id]
+        raw_type = shape.get("type", "Rectangle")
+        shape_type = TYPE_TO_CREATE.get(raw_type, raw_type)
+        parent_local = shape.get("parent")
+
+        # Build shapeProps from everything except meta fields
+        meta_keys = {"type", "parent"}
+        props = {k: v for k, v in shape.items() if k not in meta_keys}
+
+        # Set name to local_id if not explicitly set
+        if "name" not in props:
+            props["name"] = local_id
+
+        create_args = {
+            "type": shape_type,
+            "shapeProps": props,
+            "convertColors": True,
+        }
+
+        # Resolve parent ID
+        if parent_local and parent_local in mapping["shapes"]:
+            create_args["parentId"] = mapping["shapes"][parent_local]
+
+        f0_id = api(port, "shape:create-shape", create_args)
+        mapping["shapes"][local_id] = f0_id
+
+    # Create connectors
+    for local_id, conn in connectors.items():
+        tail_local = conn.get("tailId")
+        head_local = conn.get("headId")
+
+        if tail_local not in mapping["shapes"] or head_local not in mapping["shapes"]:
+            print(f"WARNING: connector '{local_id}' references unknown shape, skipping", file=sys.stderr)
+            continue
+
+        meta_keys = {"tailId", "headId"}
+        props = {k: v for k, v in conn.items() if k not in meta_keys}
+        if "name" not in props:
+            props["name"] = local_id
+
+        f0_id = api(port, "shape:create-connector", {
+            "tailId": mapping["shapes"][tail_local],
+            "headId": mapping["shapes"][head_local],
+            "shapeProps": props,
+            "convertColors": True,
+        })
+        mapping["connectors"][local_id] = f0_id
+
+    # Fit to screen
+    api(port, "view:fit-to-screen")
+
+    save_mapping(wireframe_path, mapping)
+    total = len(mapping["shapes"]) + len(mapping["connectors"])
+    print(f"Pushed '{name}' to Frame0: {len(mapping['shapes'])} shapes, {len(mapping['connectors'])} connectors")
+
+
+# -- Pull: Frame0 -> local JSON -----------------------------------------------
+
+def pull(page_ref, output_path, port):
+    """Pull a Frame0 page into local wireframe JSON."""
+    # Resolve page_ref: could be an ID or a name
+    page_id = None
+    doc = api(port, "doc:get", {"exportPages": True, "exportShapes": False})
+    if doc and "children" in doc:
+        for page in doc["children"]:
+            if page["id"] == page_ref or page.get("name") == page_ref:
+                page_id = page["id"]
+                page_name = page.get("name", page_ref)
+                break
+
+    if not page_id:
+        print(f"ERROR: Page not found: {page_ref}", file=sys.stderr)
+        sys.exit(1)
+
+    # Load existing mapping for reverse lookup
+    mapping = load_mapping(output_path)
+    reverse_map = {v: k for k, v in mapping.get("shapes", {}).items()}
+    reverse_conn = {v: k for k, v in mapping.get("connectors", {}).items()}
+
+    # Get full page with shapes
+    page = api(port, "page:get", {"pageId": page_id, "exportShapes": True})
+
+    shapes = {}
+    connectors = {}
+    new_mapping = {"page_id": page_id, "shapes": {}, "connectors": {}}
+    auto_id_counter = [0]
+
+    def auto_id(f0_shape):
+        """Generate a stable local ID from shape name or auto-number."""
+        # Prefer existing mapping
+        f0_id = f0_shape["id"]
+        if f0_id in reverse_map:
+            return reverse_map[f0_id]
+        # Use sanitized name
+        name = f0_shape.get("name", "")
+        if name:
+            sanitized = name.lower().replace(" ", "-").replace("_", "-")
+            if sanitized not in shapes:
+                return sanitized
+        # Fallback: auto-number
+        auto_id_counter[0] += 1
+        return f"s{auto_id_counter[0]:03d}"
+
+    def process_shape(f0_shape, parent_local_id=None):
+        f0_id = f0_shape["id"]
+        local_id = auto_id(f0_shape)
+        new_mapping["shapes"][local_id] = f0_id
+
+        # Extract shape properties — only strip structural keys that our
+        # ID mapping replaces. Everything else passes through as-is so the
+        # local JSON speaks Frame0's native vocabulary.
+        shape_type = f0_shape.get("type", "Box")
+        skip_keys = {"id", "type", "children", "pageId", "parentId"}
+        props = {k: v for k, v in f0_shape.items() if k not in skip_keys and v is not None}
+
+        entry = {"type": shape_type}
+        if parent_local_id:
+            entry["parent"] = parent_local_id
+        entry.update(props)
+
+        # Remove name if it matches local_id (redundant)
+        if entry.get("name") == local_id:
+            del entry["name"]
+
+        shapes[local_id] = entry
+
+        # Process children recursively
+        for child in f0_shape.get("children", []):
+            child_type = child.get("type", "")
+            if child_type == "Connector":
+                process_connector(child)
+            else:
+                process_shape(child, local_id)
+
+    def process_connector(f0_conn):
+        f0_id = f0_conn["id"]
+        local_id = reverse_conn.get(f0_id)
+        if not local_id:
+            auto_id_counter[0] += 1
+            local_id = f"c{auto_id_counter[0]:03d}"
+
+        new_mapping["connectors"][local_id] = f0_id
+
+        tail_f0 = f0_conn.get("tail", {}).get("id")
+        head_f0 = f0_conn.get("head", {}).get("id")
+
+        entry = {}
+        if tail_f0:
+            # Will be resolved after all shapes are processed
+            entry["_tailF0"] = tail_f0
+        if head_f0:
+            entry["_headF0"] = head_f0
+
+        skip_keys = {"id", "type", "children", "pageId", "tail", "head"}
+        props = {k: v for k, v in f0_conn.items() if k not in skip_keys and v is not None}
+        entry.update(props)
+
+        connectors[local_id] = entry
+
+    # Process all top-level shapes
+    for child in page.get("children", []):
+        child_type = child.get("type", "")
+        if child_type == "Connector":
+            process_connector(child)
+        else:
+            process_shape(child)
+
+    # Resolve connector references to local IDs
+    f0_to_local = {v: k for k, v in new_mapping["shapes"].items()}
+    for conn in connectors.values():
+        tail_f0 = conn.pop("_tailF0", None)
+        head_f0 = conn.pop("_headF0", None)
+        if tail_f0 and tail_f0 in f0_to_local:
+            conn["tailId"] = f0_to_local[tail_f0]
+        if head_f0 and head_f0 in f0_to_local:
+            conn["headId"] = f0_to_local[head_f0]
+
+    wireframe = {"name": page_name}
+    if shapes:
+        wireframe["shapes"] = shapes
+    if connectors:
+        wireframe["connectors"] = connectors
+
+    os.makedirs(os.path.dirname(output_path) or ".", exist_ok=True)
+    with open(output_path, "w") as f:
+        json.dump(wireframe, f, indent=2)
+        f.write("\n")
+
+    save_mapping(output_path, new_mapping)
+    print(f"Pulled '{page_name}' -> {output_path}: {len(shapes)} shapes, {len(connectors)} connectors")
+
+
+# -- Export: push then export as image -----------------------------------------
+
+def export_image(wireframe_path, output_path, port, fmt="image/png"):
+    """Push wireframe to Frame0 and export the page as an image."""
+    import base64
+
+    # Push first to ensure Frame0 is up to date
+    push(wireframe_path, port)
+
+    mapping = load_mapping(wireframe_path)
+    page_id = mapping.get("page_id")
+    if not page_id:
+        print("ERROR: No page_id in mapping after push", file=sys.stderr)
+        sys.exit(1)
+
+    image_b64 = api(port, "file:export-image", {
+        "pageId": page_id,
+        "format": fmt,
+        "fillBackground": True,
+    })
+
+    image_bytes = base64.b64decode(image_b64)
+    with open(output_path, "wb") as f:
+        f.write(image_bytes)
+
+    print(f"Exported: {output_path} ({len(image_bytes) // 1024}KB)")
+
+
+# -- CLI -----------------------------------------------------------------------
+
+def main():
+    parser = argparse.ArgumentParser(description="Sync wireframe JSON with Frame0")
+    parser.add_argument("--port", type=int, default=int(os.environ.get("FRAME0_PORT", DEFAULT_PORT)))
+    sub = parser.add_subparsers(dest="command")
+
+    p_push = sub.add_parser("push", help="Push local JSON to Frame0")
+    p_push.add_argument("wireframe", help="Path to wireframe .json file")
+
+    p_pull = sub.add_parser("pull", help="Pull Frame0 page to local JSON")
+    p_pull.add_argument("page", help="Page ID or page name")
+    p_pull.add_argument("output", help="Output .json path")
+
+    p_export = sub.add_parser("export", help="Push and export as image")
+    p_export.add_argument("wireframe", help="Path to wireframe .json file")
+    p_export.add_argument("output", help="Output image path (e.g. wireframe.png)")
+    p_export.add_argument("--format", default="image/png",
+                         help="Export MIME type (default: image/png)")
+
+    args = parser.parse_args()
+
+    if args.command == "push":
+        push(args.wireframe, args.port)
+    elif args.command == "pull":
+        pull(args.page, args.output, args.port)
+    elif args.command == "export":
+        export_image(args.wireframe, args.output, args.port, args.format)
+    else:
+        parser.print_help()
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

.claude/skills/git-commit/SKILL.md

@@ -93,7 +93,7 @@ Updated briefings for Tyre and Troblum with new requirements.
 chore(agents): add Stig UI developer agent
 
 Standby agent for UI implementation phase. Configured with
-briefing reference and Commonwealth-themed personality.
+briefing reference and Settled Reach-themed personality.
 ```
 
 ## CHANGELOG.md Format
@@ -136,7 +136,5 @@ chore(meta): release v0.1.0
 
 ## Staging Rules
 
-- Stage files by name — never use `git add -A` or `git add .`
-- Verify no secrets, saves, or binary blobs are staged
-- Skip files in `.gitignore`
-- The `.claude/` directory IS tracked — skills belong in the repo
+See `.claude/rules/git-safety.md` for staging rules (always-loaded).
+These apply to ALL git operations, not just this skill.

.claude/skills/pr-push/SKILL.md

@@ -100,15 +100,11 @@ git diff --stat main...<branch>
 Draft title (`<type>(<scope>): <summary>`, max 70 chars) and description.
 
 ```bash
-cat > /tmp/pr-body.md << 'EOF'
-## Summary
-...
-EOF
 tea pr create \
   --repo jpmschweitzer/settled-reach \
   --login schweitz \
   --title "<title>" \
-  --description "$(cat /tmp/pr-body.md)" \
+  --description "## Summary ..." \
   --base main \
   --head <branch>
 ```
@@ -127,13 +123,21 @@ Extract ticket IDs from `#NNN` patterns. For each ticket that is
 currently `in_progress`, update it to `review`:
 
 ```bash
-db/connectors/ticket status <id> review
+tooling/db/ticket status <id> review
 ```
 
 Report which tickets were moved to review. Skip tickets that are
 already `done`, `review`, `cancelled`, or `backlog` (only transition
 `in_progress` → `review`).
 
+### 9. Next steps
+
+If a sprint team is active (you are the team lead), do NOT shut down
+agents after pushing. The team should remain alive for PR review and
+potential comment fixes.
+
+Suggest: "PR created/updated. Run `/pr-review` to review before merge."
+
 ## Arguments
 
 If the user passes arguments (e.g., `/pr-push "my title"`), use them as the

.claude/skills/pr-review/SKILL.md

@@ -16,11 +16,22 @@ on the branch type. All reviewers must approve for a clean review.
 
 ## Workflow
 
-### 1. Determine the branch
+### 0. Branch guard — MUST be run by a Claude instance in the `main` worktree
 
-If the user provided a branch name as argument, use it. Otherwise use the
-current branch (`git branch --show-current`). If on `main`, ask the user
-which branch to review.
+```bash
+git branch --show-current
+```
+
+If the current branch is **not `main`**, stop immediately and tell the user:
+"PR reviews must be run by a Claude instance in the `main` worktree."
+Do NOT proceed with the review. Do NOT work around this by reading files
+from another worktree — the review agent itself must be running in main.
+Stop and wait for the user to invoke `/pr-review` from main.
+
+### 1. Determine the branch to review
+
+If the user provided a branch name as argument, use it. Otherwise list open
+PRs and ask the user which branch to review.
 
 To list open PRs on Gitea:
 ```bash
@@ -63,23 +74,44 @@ If the diff is empty, report "No changes to review" and stop.
 
 Three-dot diff with pathspec exclusions is unreliable. Instead, either:
 1. Use `git diff main...<branch>` (full diff) and filter in the prompt, or
-2. Read source files directly from the branch:
-   `git show origin/<branch>:<path>`
+2. Read source files directly from the team directory (see below).
 
 For large diffs (>1000 lines of source), provide **source files** rather than
-raw diff to reviewers — cleaner context, better reviews. Read files with
-`git show origin/<branch>:<path>` and include them in the prompt.
+raw diff to reviewers — cleaner context, better reviews.
 
-**IMPORTANT — agent tool access:** Not all reviewer agents have Bash access.
-Agents that CAN read from branches themselves: **Hoshe, Tyre, Araminta**.
-Agents that CANNOT (no Bash tool): **Paula, Miri, Ozzie, Gestalt, Gore, Nigel**.
+**IMPORTANT — use team directory paths for ALL agents.** Each team branch
+is checked out in its own directory at:
 
-For agents without Bash, you MUST read the source files yourself (via
-`git show origin/<branch>:<path>`) and **paste the file contents directly
-into the agent prompt**. Do not tell these agents to read files — they can't.
-For very large PRs, read the key files (new/heavily modified) and include
-summaries or excerpts of minor changes. Also read and include the relevant
-`decisions/*.md` files these agents need for context.
+```
+/var/mnt/data/projects/settled-reach/<branch>/
+```
+
+For example, the `copy` team directory is at:
+```
+/var/mnt/data/projects/settled-reach/copy/content/dialogue/...
+```
+
+**All reviewer agents** (regardless of Bash access) should read source files
+from the team directory using the Read tool. This is more reliable than
+`git show origin/<branch>:<path>` because:
+- All agents have Read access (no Bash dependency)
+- Files are always the actual branch checkout (no stale cache)
+- No risk of accidentally reading from main's working directory
+
+When constructing reviewer prompts, tell agents to read files from the
+team directory. Example instruction for agents:
+
+```
+Read the changed files from the team directory. The branch is checked
+out at: /var/mnt/data/projects/settled-reach/<branch>/
+
+For example, to read `content/dialogue/the-terminal/kael-davan.yaml`,
+use: /var/mnt/data/projects/settled-reach/<branch>/content/dialogue/the-terminal/kael-davan.yaml
+```
+
+Also tell agents to read relevant `decisions/*.md` files from the same
+directory (they're identical to main, but using the team directory path
+keeps agents grounded in the correct location).
 
 ### 4. Spawn reviewers in parallel
 
@@ -153,19 +185,16 @@ After presenting results to the user, post the review as a PR comment.
 
 Note: `tea pr reject` does not work on your own PRs. Use `tea comment` instead.
 
-**IMPORTANT — `tea comment` hangs with inline heredocs and multi-line strings.**
-Always use a two-step approach: write to a temp file first, then pass via `$(cat)`:
+Post using the `tea-comment` wrapper (handles temp files and cleanup).
+Write the review to a temp file first, then pass via `@filepath` syntax:
 
+```bash
+# Write review to file, then post — avoids $() in the command which breaks permissions
+cat > /tmp/pr-review-<NUMBER>.md << 'EOF'
+...review content...
+EOF
+tooling/tea-comment <PR_NUMBER> @/tmp/pr-review-<NUMBER>.md
 ```
-# Step 1: Write review to .tmp/ using the Write tool (no permission prompt)
-Write(file_path: "<repo_root>/.tmp/review-<branch>.md", content: "...review content...")
-
-# Step 2: Post to Gitea (separate Bash call)
-tea comment --login schweitz --repo jpmschweitzer/settled-reach <PR_NUMBER> "$(cat .tmp/review-<branch>.md)"
-```
-
-Use the Write tool for step 1 (avoids Bash permission prompts). The `.tmp/`
-directory is gitignored and exists in the repo root for this purpose.
 
 ## 7. Merging approved PRs
 
@@ -182,6 +211,22 @@ tea pr close --login schweitz --repo jpmschweitzer/settled-reach <PR_NUMBER>
 Gitea does **not** auto-close PRs when you push a local merge — always close
 manually with `tea pr close` after pushing.
 
+### 8. Post-review team actions
+
+If a sprint team is active and you are the team lead, handle the
+review outcome:
+
+**CHANGES_REQUESTED:**
+The sprint-start lifecycle (step 9c) handles dispatching review
+comments to agents. After presenting results, remind the lead:
+"Review requested changes. Create tasks from the warnings/critical
+issues and dispatch to idle agents, then re-push and re-review."
+
+**APPROVED:**
+The sprint-start lifecycle (step 9c) handles shutdown. After
+presenting results, remind the lead: "Review approved. Proceed with
+team shutdown per sprint-start step 9c."
+
 ## Tips from practice
 
 - **Vendor code**: Explicitly note vendor code in the prompt so reviewers focus

.claude/skills/pr-review/references/reviewer-profiles.md

@@ -2,11 +2,24 @@
 
 Use `model: sonnet` for all reviewers — sufficient for review, saves cost.
 
+**All reviewer agents read from team directories.** Each team branch is
+checked out in its own directory at:
+`/var/mnt/data/projects/settled-reach/<branch>/`
+
+Tell every reviewer agent to read source files from the team directory
+using the Read tool. Include the directory path and a list of changed
+files in every prompt. Do NOT rely on `git show` or paste file contents —
+agents can read directly from the directory.
+
+Note: cross-directory reading is only permitted for review agents spawned
+from the `main` team. Team agents must stay within their own directory.
+
 ## Code reviews (`server`, `client`, `ci`)
 
 **Hoshe (Code Quality)**
 - `subagent_type`: `hoshe`, `model`: `sonnet`
-- Prompt: Include source code and commit log. Ask Hoshe to review for:
+- Prompt: Provide the team directory path, list of changed files, and commit log.
+  Tell Hoshe to read source files from the team directory, then review for:
   - Correctness and bug risks
   - Error handling gaps
   - Test coverage (are new features tested?)
@@ -16,44 +29,43 @@ Use `model: sonnet` for all reviewers — sufficient for review, saves cost.
 
 **Tyre (Architecture)**
 - `subagent_type`: `tyre`, `model`: `sonnet`
-- Prompt: Include source code and commit log. Tell Tyre to read the relevant
-  `decisions/*.md` files first, then review for:
+- Prompt: Provide the team directory path, list of changed files, and commit log.
+  Tell Tyre to read the relevant `decisions/*.md` files from the team directory
+  first, then review for:
   - Architectural consistency with project decisions
   - API/interface design quality
   - Dependency and coupling concerns
   - Scalability implications
   - Whether the change respects non-negotiable baselines (D-010, D-012)
-- Tyre can read files directly from the branch using `git show origin/<branch>:<path>`
 
 ## Copy reviews (`copy`)
 
 **Hoshe (QA)**
 - `subagent_type`: `hoshe`, `model`: `sonnet`
-- Prompt: Include the changed files and commit log. Ask Hoshe to review for:
+- Prompt: Provide the team directory path, list of changed files, and commit log.
+  Tell Hoshe to read the changed files from the team directory, then review for:
   - Formatting consistency (markdown, file naming, frontmatter)
   - Broken references or links
   - Spelling and grammar
   - File organization and structure
   - Missing or orphaned files
 
-**Paula (Narrative Depth)** — NO BASH ACCESS
+**Paula (Narrative Depth)**
 - `subagent_type`: `paula`, `model`: `sonnet`
-- Paula cannot read from branches. You must paste file contents and decision
-  files directly into the prompt.
-- Prompt: Include full text of changed files, commit log, and relevant
-  `decisions/*.md` content. Ask Paula to review for:
+- Prompt: Provide the team directory path, list of changed files, commit log, and
+  list of relevant `decisions/*.md` files to read. Tell Paula to read all
+  files from the team directory using the Read tool, then review for:
   - Narrative quality and character voice consistency
   - Whether dialogue and monologue feel authentic to the characters
   - Consequences and stakes — do choices carry weight?
   - Political and interpersonal depth
   - Emotional resonance — does the text make you feel something?
 
-**Miri (World Consistency)** — NO BASH ACCESS
+**Miri (World Consistency)**
 - `subagent_type`: `miri`, `model`: `sonnet`
-- Miri cannot read from branches. You must paste file contents and decision
-  files directly into the prompt.
-- Prompt: Include full text of changed files, commit log, and relevant
-  `decisions/*.md` content. Ask Miri to review for:
+- Prompt: Provide the team directory path, list of changed files, commit log, and
+  list of relevant `decisions/*.md` files to read. Tell Miri to read all
+  files from the team directory using the Read tool, then review for:
   - Lore accuracy — do facts match established setting?
   - Internal consistency across files
   - IP originality — nothing should read as a copy from another franchise
@@ -64,40 +76,42 @@ Use `model: sonnet` for all reviewers — sufficient for review, saves cost.
 
 **Hoshe (QA)**
 - `subagent_type`: `hoshe`, `model`: `sonnet`
-- Prompt: Include the changed files and commit log. Ask Hoshe to review for:
+- Prompt: Provide the team directory path, list of changed files, and commit log.
+  Tell Hoshe to read the changed files from the team directory, then review for:
   - File format and naming conventions
   - Asset organization and directory structure
   - Missing or broken references in scene/resource files
   - Import settings consistency
 
-**Araminta (Art Direction)** — HAS BASH ACCESS
+**Araminta (Art Direction)**
 - `subagent_type`: `araminta`, `model`: `sonnet`
-- Prompt: Include the changed files and commit log. Tell Araminta to read
-  the style guide and relevant design docs first, then review for:
+- Prompt: Provide the team directory path, list of changed files, and commit log.
+  Tell Araminta to read the style guide and relevant design docs from the
+  worktree first, then review for:
   - Visual consistency with the established style guide
   - Color palette adherence
   - UI pattern consistency (diegetic-first, clarity over beauty)
   - Whether assets scale gracefully (boxes-with-labels to full-art)
-  - Mood and tone — sleek, advanced, subtle Commonwealth aesthetic
+  - Mood and tone — sleek, advanced, subtle Settled Reach aesthetic
 
 ## Audio reviews (`audio`)
 
 **Hoshe (QA)**
 - `subagent_type`: `hoshe`, `model`: `sonnet`
-- Prompt: Include the changed files and commit log. Ask Hoshe to review for:
+- Prompt: Provide the team directory path, list of changed files, and commit log.
+  Tell Hoshe to read the changed files from the team directory, then review for:
   - File format and naming conventions
   - Audio asset organization and directory structure
   - Missing or broken references
   - Import/bus configuration consistency
 
-**Ozzie (Player Experience)** — NO BASH ACCESS
+**Ozzie (Player Experience)**
 - `subagent_type`: `ozzie`, `model`: `sonnet`
-- Ozzie cannot read from branches. You must paste file contents directly
-  into the prompt.
-- Prompt: Include full text of changed files and commit log. Ask Ozzie to
+- Prompt: Provide the team directory path, list of changed files, and commit log.
+  Tell Ozzie to read all files from the team directory using the Read tool, then
   review for:
   - Emotional impact — does the audio enhance the moment?
-  - Atmosphere and tone — does it feel like the Commonwealth?
+  - Atmosphere and tone — does it feel like the Settled Reach?
   - Player feedback clarity — can the player tell what just happened?
   - Pacing — do sounds support or fight the gameplay rhythm?
   - Memorable moments — will players remember these audio cues?

.claude/skills/sprint-plan/SKILL.md

@@ -47,10 +47,40 @@ project state. Only generate briefings for teams that have tickets in the sprint
 | `audio` | `audio` | Inigo (sound design) | Soundscapes, ambient layers, diegetic cues, audio propagation |
 | `visual` | `visual` | Araminta (art direction) | Art assets, sprites, visual consistency, style guides |
 | `ci` | `ci` | Justine (build/deploy) | Build pipelines, CI/CD, tooling, packaging |
+| `planning` | `planning` | Purpose-assembled (see below) | Design discussions, decision resolution, workshop-style tickets |
 
 When writing briefings, name the assigned agents in the **Agents** line of each
 file so the team knows who to spawn.
 
+### Planning Team Tickets
+
+Some tickets need **design discussion** before implementation can begin — tagged
+"NEEDS DESIGN DISCUSSION" or blocking multiple downstream tickets with open
+questions. These run on the `planning` branch as structured discussions with
+the user and a purpose-assembled agent panel.
+
+**When to create a planning ticket:**
+- Ticket description says "NEEDS DESIGN" or "NEEDS DESIGN DISCUSSION"
+- Ticket blocks 2+ downstream tickets across different teams
+- Open Q-NNN items that block sprint candidates
+- Architectural decisions that need multi-domain input before implementation
+
+**Planning briefing format** (differs from implementation briefings):
+- **Agents line**: List agents by domain relevance, not fixed team roster.
+  Pick from: Gestalt (systems), Miri (worldbuilding), Araminta (visual/spatial),
+  Tyre (technical), Paula (narrative), Ozzie (player experience), Gore (themes),
+  Nigel (replayability). Typically 4-6 domain agents, plus Qatux (documenter —
+  records decisions, updates domain files) and SI (project manager — creates
+  follow-up tickets, updates sprint assignments).
+- **Discussion rounds**: Structure the conversation into 2-3 rounds
+  (inventory → proposals → convergence)
+- **Context section**: List all existing design docs, decisions, and related
+  tickets that participants must read before the discussion
+- **Output specification**: What the discussion must produce — typically a
+  D-record in `decisions/`, possibly a design doc in `docs/design/`
+- **Decision questions**: Specific questions the discussion must answer,
+  not open-ended exploration
+
 ## Workflow
 
 ### 1. Run sprint prepare
@@ -58,7 +88,7 @@ file so the team knows who to spawn.
 Get carry-overs, backlog candidates, and decision gaps in one shot:
 
 ```bash
-db/connectors/sprint prepare
+tooling/db/sprint prepare
 ```
 
 This auto-detects the next sprint number (max ID + 1), creates the sprint
@@ -73,10 +103,10 @@ record in `planning` status if needed, and outputs:
 For critical epics, check their children for granular candidates:
 
 ```bash
-db/connectors/ticket children <epic_id>
+tooling/db/ticket children <epic_id>
 ```
 
-Use `db/connectors/ticket show --brief <id> [<id>...]` to quickly scan multiple tickets.
+Use `tooling/db/ticket show --brief <id> [<id>...]` to quickly scan multiple tickets.
 
 ### 3. Read existing code state
 
@@ -124,13 +154,12 @@ Create `docs/sprints/sprint-N/` and write one file per team.
 Read the template at `references/briefing-template.md` in this skill directory
 for the exact file structure.
 
-**IMPORTANT — worktree-relative paths:** This project uses git worktrees.
-Each team branch is checked out in its own worktree, and each worktree
-contains the full repo (`server/`, `client/`, `docs/`, etc.). All file
-paths in briefings must be relative to the worktree/git root. Example:
+**IMPORTANT — relative paths only:** Each team works in its own directory
+containing the full repo (`server/`, `client/`, `docs/`, etc.). All file
+paths in briefings must be relative to the working directory. Example:
 `server/src/bridge/types.rs`, not `/absolute/path/to/server/src/...` or
-paths that navigate outside the git root (`../sibling-worktree/...`).
-Agents must stay within the git root they are running in.
+paths that navigate outside (`../sibling-dir/...`).
+Agents must stay within their team's working directory.
 
 Key requirements per file:
 - **server.md**: Carry-overs, new tickets, dependency chain, key decisions, notes
@@ -154,16 +183,29 @@ Update it with the theme and goal, then assign tickets:
 
 ```bash
 # Update the sprint with theme and goal
-db/connectors/sqlite-exec "UPDATE sprints SET name='Sprint N: Theme', goal='goal' WHERE id=N"
+tooling/db/sqlite-exec "UPDATE sprints SET name='Sprint N: Theme', goal='goal' WHERE id=N"
 
 # Assign tickets
-db/connectors/ticket sprint assign <ticket_id> <sprint_id>
+tooling/db/ticket sprint assign <ticket_id> <sprint_id>
 ```
 
 The sprint stays in `planning` status until explicitly activated via
-`db/connectors/sprint start`. This prevents starting an unplanned sprint.
+`tooling/db/sprint start`. This prevents starting an unplanned sprint.
 
-### 8. Present summary
+### 8. Commit and push
+
+Stage the briefing files and any other changes (db backup, closed tickets),
+then commit and push so worktree branches can pull the planning artifacts:
+
+```bash
+git add docs/sprints/sprint-N/
+make db-backup
+git add docs/backups/settledreach.db.backup
+git commit -m "chore(meta): plan Sprint N: Theme"
+git push
+```
+
+### 9. Present summary
 
 Output:
 - Sprint number, theme, and goal
@@ -171,3 +213,4 @@ Output:
 - Carry-over count
 - Open questions that need early resolution
 - Files written
+- Commit pushed to main

.claude/skills/sprint-plan/references/briefing-template.md

@@ -26,7 +26,7 @@ Each team gets one briefing file at `docs/sprints/sprint-N/<team>.md`.
 |---|-------|------------|
 | #ID | Title | #dependency or — |
 
-Use `db/connectors/ticket show <id>` for full details.
+Use `tooling/db/ticket show <id>` for full details.
 
 ## Key Decisions
 

.claude/skills/sprint-start/SKILL.md

@@ -38,7 +38,7 @@ When `/sprint-start` is run on `main`, assess the current sprint state
 and do the next right thing. Query the database to determine the state:
 
 ```bash
-db/connectors/sqlite-query "SELECT id, name, status FROM sprints ORDER BY id DESC LIMIT 3"
+tooling/db/sqlite-query "SELECT id, name, status FROM sprints ORDER BY id DESC LIMIT 3"
 ```
 
 Then follow the **first matching case**:
@@ -48,7 +48,7 @@ Then follow the **first matching case**:
 First, check whether the sprint's work is actually done:
 
 ```bash
-db/connectors/sprint status
+tooling/db/sprint status
 ```
 
 This shows ticket counts by status (done, in_progress, backlog).
@@ -81,12 +81,54 @@ explicitly chooses to close.
 #### A1. Close the active sprint
 
 ```bash
-db/connectors/sprint stop
+tooling/db/sprint stop
 ```
 
 This marks the active sprint as completed and lists carry-over candidates.
 Note the sprint number (N) from the output.
 
+#### A1b. Sprint retrospective and review
+
+Before bumping the version, run a brief retro. Present the following to
+the user:
+
+1. **What shipped** — list completed tickets with one-line summaries
+2. **What didn't ship** — carry-overs and why (blocked, cut, deprioritized)
+3. **What we learned** — open questions raised during the sprint (new Q-NNN
+   items), review findings that surfaced design gaps, and any assumptions
+   that turned out to be wrong
+4. **Process notes** — what worked well, what was friction (e.g. dependency
+   chains that blocked teams, specs that were over/under-specified,
+   review cycles that caught real issues vs busywork)
+
+5. **Process improvements** — this is the most important section. Do NOT
+   skip it. Look for:
+   - Dependency chains that blocked teams — could the sprint have been
+     structured differently to avoid the bottleneck?
+   - Specs that were over-specified (wasted planning) or under-specified
+     (wasted iteration) — what's the right level of detail for this
+     project's current stage?
+   - Review cycles — did they catch real issues or create busywork?
+   - Agent coordination — were agents stuck, duplicating work, or idle?
+   - **Dig into the deeper why.** Don't stop at "the dependency chain
+     blocked the copy team." Ask: why was there a dependency chain? Was
+     the sprint structured wrong, or was the work inherently sequential?
+     Could Phase 0 have been done pre-sprint? Should we change how we
+     plan sprints going forward?
+   - If something went rough, understand the root cause — not just what
+     happened, but why the process allowed it to happen.
+   - If a concrete process change follows naturally, propose it. But do
+     NOT force improvements. If nothing was broken, say so and move on.
+     Unnecessary process changes are worse than no changes.
+
+Keep each section concise — a few bullet points, not a document. The
+retro is a conversation checkpoint, not a report. Use `AskUserQuestion`
+to let the user add their own observations and push back before proceeding.
+
+If the user raises items that should be tracked, create Q-NNN entries
+or backlog tickets on the spot. If process changes are agreed, update
+the relevant skill files or CLAUDE.md immediately — don't defer them.
+
 #### A2. Bump the version
 
 The project version scheme is `v0.1.{sprint_number}`. After closing
@@ -142,7 +184,7 @@ A sprint is ready to activate. Verify it looks complete:
    ```
 2. Check the ticket count:
    ```bash
-   db/connectors/sprint status --sprint N
+   tooling/db/sprint status --sprint N
    ```
 
 If briefings are missing or the sprint has 0 tickets, report the gap
@@ -151,7 +193,7 @@ and suggest running `/sprint-plan` to complete planning.
 If everything looks ready, activate the sprint:
 
 ```bash
-db/connectors/sprint start
+tooling/db/sprint start
 ```
 
 Then report:
@@ -184,7 +226,7 @@ If the merge has conflicts, report them and stop — do not force-resolve.
 Run the sprint CLI to get the full context dump in one shot:
 
 ```bash
-db/connectors/sprint start-work
+tooling/db/sprint start-work
 ```
 
 This auto-detects the active sprint and current team from the branch.
@@ -204,7 +246,7 @@ If no matching briefing exists for the team, suggest running
 
 For tickets that need more detail than the `start-work` summary provides:
 ```bash
-db/connectors/ticket show <id>
+tooling/db/ticket show <id>
 ```
 
 ### 6. Read key decisions
@@ -218,7 +260,7 @@ Mark all actionable (unblocked, non-done) tickets in the sprint as
 `in_progress`:
 
 ```bash
-db/connectors/ticket status <id> in_progress
+tooling/db/ticket status <id> in_progress
 ```
 
 Then output a summary:
@@ -288,26 +330,70 @@ Task(
   prompt: "You are on the {team} team for Sprint {N}.
     Branch: `{team}`
 
-    RULES:
-    - GIT: Do NOT run any git commands (commit, push, pull, merge,
-      checkout, branch, stash, tag, etc.). All git operations are
-      handled by the team lead.
-    - DB SCRIPTS: When calling ticket/sprint/sqlite scripts, use
-      the exact command with no wrappers or chaining. Examples:
-        db/connectors/ticket show 528
-        db/connectors/ticket list --sprint {N}
-      Do NOT prepend python3, do NOT chain with && or ;, do NOT
-      add cleanup commands. Just the bare command.
+    RULES (NON-NEGOTIABLE):
+
+    0. TEAM BOUNDARY: Your team is `{team}` ($WORKTREE_TEAM). Stay
+       within the current working directory. Do NOT navigate to
+       parent or sibling directories. Do NOT follow .git pointers
+       to other directories.
+
+    1. GIT: Do NOT run any git commands (commit, push, pull, merge,
+       checkout, branch, stash, tag, etc.). All git operations are
+       handled by the team lead. No exceptions.
+
+    2. DB SCRIPTS: When calling ticket/sprint/sqlite scripts, use
+       the exact command with no wrappers or chaining. Examples:
+         tooling/db/ticket show 528
+         tooling/db/ticket list --sprint {N}
+       Do NOT prepend python3, do NOT chain with && or ;, do NOT
+       add cleanup commands. Just the bare command.
+
+    3. READ BEFORE WRITE: Before modifying ANY file, Read it first.
+       Before creating a new file, Glob for similar files to learn
+       the existing patterns (naming, structure, imports). Follow
+       the conventions you find — do not invent new ones.
+
+    4. VERIFY AFTER WRITE: After implementing a change, grep for
+       all references to functions/properties/classes you modified
+       or removed. If you renamed, moved, or deleted something,
+       update EVERY call site. Missing a call site breaks tests
+       and blocks the team.
+
+    5. NO PARTIAL WORK: Do not mark a task completed unless ALL
+       parts of the ticket are implemented. If the ticket says
+       'deliver A, B, and C', all three must exist and work. If
+       you cannot complete part of a task, message the team lead
+       explaining what is blocked and what remains — do NOT mark
+       it completed.
+
+    6. MESSAGE WHEN BLOCKED: If you hit a problem you cannot solve
+       in 3 attempts, stop and message the team lead immediately.
+       Do not silently skip work or leave stubs. Do not move to
+       the next task while the current one is incomplete.
+
+    7. BACKWARD COMPATIBILITY: When extracting, moving, or
+       refactoring code, ensure all existing consumers still work.
+       Add proxy methods/properties if needed. Grep for the old
+       name to find every call site.
+
+    WORKFLOW:
 
     1. Read the sprint briefing: docs/sprints/sprint-{N}/{team}.md
     2. Read the decision files referenced in the briefing.
     3. Check TaskList for available work.
     4. Claim an unblocked task (TaskUpdate with owner: your name),
        mark it in_progress, and implement it.
-    5. When done, mark the task completed and check TaskList for
-       the next available task.
+    5. Before marking done, verify:
+       - All deliverables from the ticket exist (not just some)
+       - No broken references (grep for changed names/signatures)
+       - New files follow existing naming and directory conventions
+       - Modified files still parse (no syntax errors)
+    6. Mark the task completed and check TaskList for the next
+       available task.
+    7. If no tasks remain, message the team lead. Do NOT shut down
+       on your own.
 
-    Use `db/connectors/ticket show <id>` for full ticket specs.",
+    Use `tooling/db/ticket show <id>` for full ticket specs.",
   description: "Sprint {N} {team}: {name}",
   run_in_background: true
 )
@@ -325,3 +411,57 @@ Output to the user:
 You are now the team lead. Agents work autonomously — monitor via
 `TaskList`, communicate via `SendMessage`, and handle blockers as
 they arise.
+
+**When all tasks complete:** Do NOT shut down agents. The team stays
+alive through the PR review cycle. Follow step 9 (post-work lifecycle).
+
+### 9. Post-work lifecycle
+
+When all tasks are complete (TaskList shows all completed):
+
+#### 9a. Commit and push
+
+Run `/git-commit` to commit all changes, then `/pr-push` to create or
+update the PR. Do NOT shut down agents — the team stays alive for review.
+
+#### 9b. Review
+
+Run `/pr-review` to spawn temporary reviewers. Wait for results.
+
+#### 9c. Handle review outcome
+
+**If CHANGES_REQUESTED:**
+
+1. Parse the review comment table (from the Gitea PR comment or the
+   review output). Extract each warning/critical issue with:
+   - File path and approximate line
+   - Severity (critical / warning / suggestion)
+   - Description
+
+2. Create a task per warning/critical issue:
+   ```
+   TaskCreate(
+     subject: "Review: {short description}",
+     description: "{full issue description from review table, including
+       file path, severity, and reviewer name}",
+     activeForm: "Fixing review comment: {short description}"
+   )
+   ```
+   Skip suggestion-severity items unless they are trivial (1-line fixes).
+
+3. Dispatch to idle agents: send each a message via SendMessage telling
+   them to check TaskList for new review-fix tasks. Agents claim and
+   work tasks as usual.
+
+4. After all review-fix tasks are complete, re-run `/git-commit` then
+   `/pr-push` to update the PR. Then re-run `/pr-review`.
+
+5. Repeat this loop until review returns APPROVED.
+
+**If APPROVED:**
+
+1. Send `shutdown_request` to all sprint agents.
+2. Wait for all `shutdown_response` confirmations.
+3. Call `TeamDelete` to clean up.
+4. Report: "Sprint {N} {team} complete. PR #{X} approved and ready for
+   merge on main."

.claude/skills/sprint-status/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: sprint-status
+description: >
+  Sprint health check and cleanup sweep. Lists all tickets in the active
+  sprint grouped by status, detects bookkeeping issues (stale tickets,
+  orphan PRs, done-but-open PRs, unassigned work), and shows open work
+  by team. Use when checking sprint progress, before sprint close, or
+  when housekeeping feels off. Triggers on "sprint status", "cleanup
+  sweep", "what's open", "sprint health".
+user-invocable: true
+allowed-tools: Task, Read, Grep, Glob
+---
+
+# Sprint Status
+
+**Delegate this entire skill to a subagent** (general-purpose, model: haiku).
+
+When this skill is invoked, spawn a subagent using the Task tool:
+
+```
+Task(
+  subagent_type: "general-purpose",
+  model: "haiku",
+  prompt: "Run /sprint-status. Read the skill at
+    .claude/skills/sprint-status/SKILL.md for the full workflow
+    (below the --- separator), then execute it.",
+  description: "Sprint status report"
+)
+```
+
+Present the subagent's output to the user verbatim. Do NOT run the
+workflow yourself.
+
+---
+
+The remainder of this file is the subagent's reference for executing
+the workflow.
+
+## Step 1 — Gather data
+
+Run these two commands in parallel:
+
+```bash
+tooling/db/sprint sweep
+```
+
+```bash
+tea pr list --login schweitz --repo jpmschweitzer/settled-reach --state open --output simple
+```
+
+The `sweep` command returns JSON with:
+- `sprint` — id, name, goal
+- `progress` — total, done, pct
+- `by_status` — tickets grouped into done, review, in_progress, blocked, backlog
+- `by_team` — per-team counts
+- `issues` — bookkeeping problems with suggested fix commands
+
+The `tea pr list` returns open PRs as `#N title` lines.
+
+## Step 2 — Cross-reference PRs with tickets
+
+Parse PR head branches from the `tea pr list` output. Known team branches:
+`server`, `client`, `copy`, `audio`, `visual`, `ci`.
+
+Detect additional issues:
+
+- **done_team_open_pr**: A team's tickets are all done but an open PR
+  still exists for that team branch.
+- **orphan_pr**: An open PR exists on a branch that has no tickets in
+  the active sprint.
+
+Add these to the issues list from step 1.
+
+## Step 3 — Format output
+
+Read `references/output-template.md` for the exact format spec.
+
+Render the report using data from steps 1-2. Key rules:
+- Sections ordered: Completed, In Review, In Progress, Blocked, Backlog
+- Sort tickets within sections by team then ticket ID
+- Empty sections: show header with "(0)" and "(none)" — no empty table
+- Bookkeeping Issues: two-column table (Issue, Fix)
+- Open Work by Team: summary table at the bottom
+- Issue type labels: `stale_backlog` → "Stale backlog",
+  `unassigned_in_progress` → "Unassigned in_progress",
+  `assigned_but_done` → "Assigned but done",
+  `done_team_open_pr` → "Done team with open PR",
+  `orphan_pr` → "Orphan PR"
+
+## Step 4 — Suggest actions
+
+After the formatted report, if there are bookkeeping issues, add a
+"Suggested fixes" section with the fix command for each issue. Group
+by issue type for readability.

.claude/skills/sprint-status/references/output-template.md

@@ -0,0 +1,54 @@
+# Sprint Status Output Template
+
+## Sprint {N}: {Theme} — Status Report
+
+**Goal:** {goal}
+**Status:** {status} | {done}/{total} tickets ({pct}%)
+**Open PRs:** {count} ({branches})
+
+---
+
+### Completed ({count})
+
+| # | Team | Title | Assigned |
+|---|------|-------|----------|
+| #{id} | {team} | {title} | {assigned} |
+
+### In Review ({count})
+
+| # | Team | Title | PR |
+|---|------|-------|----|
+| #{id} | {team} | {title} | #{pr} |
+
+### In Progress ({count})
+
+| # | Team | Title | Assigned | Note |
+|---|------|-------|----------|------|
+| #{id} | {team} | {title} | {assigned} | |
+
+### Blocked ({count})
+
+| # | Team | Title | Blocked by |
+|---|------|-------|------------|
+| #{id} | {team} | {title} | #{ids} |
+
+### Backlog ({count})
+
+| # | Team | Title | Note |
+|---|------|-------|----|
+| #{id} | {team} | {title} | not started |
+
+---
+
+### Bookkeeping Issues
+
+| Issue | Fix |
+|-------|-----|
+| {type}: {detail} | `{command}` |
+
+### Open Work by Team
+
+| Team | Backlog | In Progress | Review | Blocked | Done |
+|------|---------|-------------|--------|---------|------|
+| {team} | {n} | {n} | {n} | {n} | {n} |
+| **Total** | **{n}** | **{n}** | **{n}** | **{n}** | **{n}** |

.claude/skills/ticket/SKILL.md

@@ -10,68 +10,67 @@ allowed-tools: Bash, Read, Grep, Glob
 
 # Ticket Skill
 
-Manage the project ticketing database. Basic usage (`ticket list`, `ticket show`,
-`ticket sprint --active`) and raw SQL wrappers are documented in CLAUDE.md.
-This skill covers the full command reference.
+Manage the project ticketing database. Basic usage is in CLAUDE.md's CLI tools
+section. This skill covers the full command reference.
 
 ## Commands
 
 ### List tickets (full flags)
 ```bash
-db/connectors/ticket list [--status S] [--priority P] [--epic N] [--sprint N] [--assigned A] [--team T]
+tooling/db/ticket list [--status S] [--priority P] [--epic N] [--sprint N] [--assigned A] [--team T]
 ```
 
 ### Create ticket
 ```bash
-db/connectors/ticket create <type> <title> [--parent N] [--priority P] [--decision D] [--team T]
+tooling/db/ticket create <type> <title> [--parent N] [--priority P] [--decision D] [--team T]
 ```
 Types: `initiative`, `epic`, `story`, `task`, `bug`
 Priorities: `critical`, `high`, `medium`, `low`
 
 ### Update status
 ```bash
-db/connectors/ticket status <id> <new_status>
-db/connectors/ticket done <id> [<id> ...]
+tooling/db/ticket status <id> <new_status>
+tooling/db/ticket done <id> [<id> ...]
 ```
 Statuses: `backlog`, `ready`, `in_progress`, `review`, `done`, `cancelled`
 
 ### Assignment
 ```bash
-db/connectors/ticket assign <id> <agent>
-db/connectors/ticket unassign <id>
+tooling/db/ticket assign <id> <agent>
+tooling/db/ticket unassign <id>
 ```
 
 ### Team assignment
 ```bash
-db/connectors/ticket team <id> <teams>
+tooling/db/ticket team <id> <teams>
 ```
 Teams are comma-separated, e.g. `server`, `client`, `server,client`.
 
 ### Sprint management
 ```bash
-db/connectors/ticket sprint [--active]
-db/connectors/ticket sprint assign <id> <sprint_id>
+tooling/db/ticket sprint [--active]
+tooling/db/ticket sprint assign <id> <sprint_id>
 ```
 
 For sprint-scoped operations (status overview, context dumps, lifecycle),
-use the dedicated sprint CLI instead: `db/connectors/sprint --help`
+use the dedicated sprint CLI instead: `tooling/db/sprint --help`
 
 ### Dependencies
 ```bash
-db/connectors/ticket deps <id>
+tooling/db/ticket deps <id>
 ```
 
 ### Search and browse
 ```bash
-db/connectors/ticket search <keyword>
-db/connectors/ticket epics [--status S]
-db/connectors/ticket children <id>
-db/connectors/ticket count [--status S]
+tooling/db/ticket search <keyword>
+tooling/db/ticket epics [--status S]
+tooling/db/ticket children <id>
+tooling/db/ticket count [--status S]
 ```
 
 ### Batch show
 ```bash
-db/connectors/ticket show --brief <id> [<id>...]
+tooling/db/ticket show --brief <id> [<id>...]
 ```
 
 ## Workflow

.claude/skills/workshop-start/SKILL.md

@@ -73,24 +73,67 @@ For large workshops (>6 agents), spawn participants in batches to avoid overwhel
 - SendMessage to nudge idle agents or provide clarification
 - Agents work autonomously — claim tasks, read the brief, produce responses
 
-### 7. Between Rounds
+### 7. Between Rounds — USER REVIEW CHECKPOINT (MANDATORY)
 
 When all Round N tasks are complete:
 1. Verify all agents wrote output files to `docs/workshops/{name}/`. If any are missing, nudge the agent or extract from their message and write the file yourself.
 2. Qatux reads all `*-round{N}.md` files and produces round summary in `round-{N}-notes.md`
-3. Create Round N+1 tasks (integration pass, synthesis, etc.) — include the same file output requirement
-4. Assign to agents with TaskUpdate
-5. Agents continue working
+3. **MANDATORY: Present round results to the user via AskUserQuestion before proceeding.**
+   - Summarize the key findings, votes, consensus, and tensions from the round
+   - Present open decisions that need user input (product decisions, scope calls, design direction)
+   - Ask the user whether to proceed to the next round, adjust direction, or add rounds
+   - **Do NOT create next-round tasks or synthesize proposals until the user has reviewed and approved**
+   - The user cannot see agent messages or file contents — present all key information directly
+4. After user approval, create Round N+1 tasks (integration pass, synthesis, etc.) — include the same file output requirement
+5. Assign to agents with TaskUpdate
+6. Agents continue working
 
-### 8. Wrap Up
+### 8. Wrap Up — USER CONTROLS SHUTDOWN (MANDATORY)
 
-**Always ask the user before wrapping up.** There may be more to discuss or additional rounds needed. Only proceed to wrap-up when the user confirms.
+**The user decides when the workshop ends and when the team is dismissed.** Never initiate shutdown, team cleanup, or wrap-up autonomously. Only proceed when the user explicitly says to wrap up.
 
-Wrap-up sequence:
-1. Qatux produces final `workshop-outcomes.md` from accumulated notes
-2. If SI is present, SI creates tickets from decided items
-3. Send shutdown_request to all agents (qatux and si last, after they finish their output tasks)
-4. TeamDelete to clean up
+Before the user dismisses the team, the following are **hard requirements**:
+
+1. **User reviews final outcomes** — Present `workshop-outcomes.md` content to the user via AskUserQuestion. Get explicit approval before proceeding to filing.
+2. **D-records filed** — All new D-records, amendments, and supersessions are written to `decisions/` domain files. This is non-negotiable — workshops that produce decisions MUST file them before shutdown.
+3. **Discussion captured** — Qatux produces final `workshop-outcomes.md` from accumulated notes. Qatux creates or updates diagrams (via `/d2-diagram`) for any new D-records produced by the workshop.
+4. **Tickets created** — If SI is present, SI creates tickets from decided items and the user reviews the ticket list.
+5. **User gives explicit go-ahead to dismiss** — Only after steps 1-4 are complete AND the user confirms, send shutdown_request to all agents (qatux and si last).
+6. TeamDelete to clean up.
+
+**Never shortcut this sequence.** Filing D-records and capturing the discussion are not optional cleanup — they are workshop deliverables.
+
+## Workshop Format: Interview Mode
+
+When the workshop brief specifies `**Format:** Interview` (or the user requests "interactive interview mode"), the between-rounds flow changes for the interview round:
+
+### How Interview Mode Works
+
+Instead of agents writing responses to each other, the facilitator (team lead) conducts a live interview with the user:
+
+1. **Collect all agent questions** — Read all Round 1 output files to gather every question.
+2. **Group thematically** — Organize questions into 5-7 thematic clusters (e.g., "The Vision," "The Confusion Type," "The Emotional Loop"). Questions from different agents that probe similar territory go together.
+3. **Present via AskUserQuestion** — Present each group using the `AskUserQuestion` tool, one group at a time (1-3 questions per group). For each question:
+   - Include the asking agent's name and domain
+   - Include the full question text with context
+   - Include the agent's reasoning for why the question matters
+   - Provide 2-4 option choices that represent distinct answer categories
+   - Always allow free-text via the "Other" option (automatic)
+4. **Capture nuance** — The user's free-text notes often contain the most important insights. Capture these verbatim in the transcript.
+5. **Summarize between groups** — After each group, briefly reflect back the key finding before moving to the next group.
+6. **Write full transcript** — When all groups are done, write the complete interview to `docs/workshops/{name}/lead-interview.md` with:
+   - Every question and full answer (verbatim where the user provided free text)
+   - Key findings per answer
+   - An interview summary section with the major revelations
+   - "What Survives" and "What Changes" sections
+
+### Why AskUserQuestion
+
+The user CANNOT see agent messages, task details, or file contents in the conversation. They only see your text output and AskUserQuestion prompts. Present all question context directly — never assume the user has read agent outputs.
+
+### Distributing Interview Results
+
+When creating Round 3 (proposal) tasks after an interview round, include the full transcript path and a summary of the major reframe in every agent's task description. If the user requests it, instruct agents to read the verbatim transcript.
 
 ## Agent Type Reference
 

.config/hooks/pre-commit

@@ -21,6 +21,7 @@ run_check() {
 
 # --- Checks ---
 run_check "tooling/check-fact-ids" "fact_id validation"
+run_check "tooling/check-decision-ids" "decision ID duplication"
 
 if [ "$ERRORS" -gt 0 ]; then
     echo ""

.gitignore

@@ -2,6 +2,8 @@
 .cache/
 .tmp/
 server/target/
+server/sr-voice/target/
+server/models/
 tooling/content-converter/target/
 tooling/line-previewer/target/
 tooling/test-client/target/
@@ -21,6 +23,9 @@ renderer/output/*.png
 # Database (shared across worktrees at ../settledreach.db, not tracked)
 db/commonwealth.db*
 
+# Frame0 ID mapping files (ephemeral, per-machine)
+*.idmap.json
+
 # Python
 __pycache__/
 *.pyc
@@ -40,3 +45,4 @@ Thumbs.db
 # Note: .claude/agents/, .claude/skills/, and .claude/settings.json ARE tracked
 .claude/plans/
 .claude/projects/
+.claude/agent-memory/

CHANGELOG.md

@@ -6,6 +6,367 @@ Format based on [Keep a Changelog](https://keepachangelog.com/).
 
 ## [Unreleased]
 
+## [v0.1.26] — 2026-03-13
+
+### Added
+- ContentType::Factual — lines with numbers, denials, causal chains bypass LLM and serve base text directly (#650, D-138)
+- Voice pipeline observer integration — enrichment systems rewrite dialogue/conversation text with voiced versions before snapshot assembly (#652)
+- SQLite settings storage — per-player persistent settings via rusqlite (bundled), IPC protocol v20 with ChangeSettings/RequestAllSettings/DeleteSetting commands (#627)
+- Composable behavior engine — three-layer action+modifier+context primitives replace flat culture×zone×role behavior strings (#633, D-139, Q-057 resolved)
+- Stronger few-shot examples for Friendly and RoutineDeviation tells (#651)
+- AI-Enhanced Dialogue toggle — settings panel toggle with layered hardware detection (RAM/TPT/degradation), battery auto-suspend with player override, warning label (#646, D-138)
+- PlatformInfo autoload — client-side OS abstraction centralizing all platform queries: power state, memory, CPU, GPU, display, locale, file paths, diagnostics helper (#659, D-141)
+- Vael and Osse culture profiles with voice personas, behavior modifiers, and explicit NEVER blocks (#653)
+- Behavior modifiers for all three cultures — 7-category contract: work_pace, physical_manner, social_signal, task_completion, environmental_scan, offduty_posture, authority_response (#634)
+- Zone-type template architecture — behavior primitives moved from per-location files to reusable zone-type templates (content/global/zone-types/). 31 zone types planned for v1.0 (#661, D-142)
+- POI three-tier system — large POIs as zone types, abandoned flag for decay variants, poi_overlay for small landmarks (D-142)
+- Authoring guides for base text elevation, culture creation, and content directory structure
+- D-140: dialogue re-voicing quality constraints — Paula's six rules
+- D-142: zone-type template architecture for scalable NPC behavior across 300+ systems
+
+### Removed
+- v0.1 content loading system — server/src/content/ module (8200 lines), tooling/content-converter/, tooling/validate-content, content-ron/, content/_meta/ (#655, D-122)
+- AiDialogueDetector — duplicate of HardwareDetector, replaced by PlatformInfo abstraction (#659)
+- v0.1 hand-authored Krenn dialogue, monologue, and NPC profiles — 64 files superseded by generated NPCs (#656, D-122)
+- Detective mission system — investigation knowledge, lattice-commission faction, design docs, workshop archives (#657, D-117)
+
+### Fixed
+- Name pool cross-contamination — zero overlaps across Krenn, Vael, and Osse cultures
+- D-141 → D-142 reference correction in zone-type templates
+- Modifier coverage expanded to 2+ per category for all cultures; authority_response differentiated Krenn/Osse
+- Gendered pronouns removed from culture-neutral zone-type templates
+- Ungrounded lore terms (Syndic, Meridian registration) replaced with generic descriptors in Osse culture
+- Stale notes in content-structure-canonical.md and base-text-authoring-guide.md corrected
+- Legacy annotation added to overheard.yaml (#664 tracks replacement)
+- Dead dual_lens properties stripped from environmental YAML
+
+### Changed
+- Protocol version bumped to 20 — ObserverSnapshot includes settings_response field (#627)
+- All 18 agent briefings updated for v0.2 pivot — removed detective/smuggler/hand-authored references, aligned with generator-first approach (#658)
+- 5 agent profiles (miri, ozzie, paula, inigo, hoshe) updated to remove stale v0.1 framing (#658)
+- Q-015 closed as obsolete (D-122 eliminates hand-authored FRIEND content)
+- D-018 perception model: franchise-specific example replaced with generic framing
+
+## [v0.1.25] — 2026-03-07
+
+### Fixed
+- Name pool first-pick bias — generator spike produced "Dav" as NPC 1 across all seeds; now uses derived RNG per zone+culture (#628)
+- Behavior dedup — same behavior string no longer assigned to multiple NPCs in one zone run (#629)
+
+### Added
+- Zone identity specs renamed to location-specific: krenn-rural-zone.ron and krenn-industrial-zone.ron — acknowledges these are culture×zone content, not reusable templates (#630, Q-057)
+- ~108 new NPC behavior pool entries across all roles in both zone files — trader stage directions, foreman humanity behaviors, dock_worker/technician off-shift/break room behaviors (#630)
+- Q-057 open question: composable behavior generation — decompose hand-authored pools into role actions + culture modifiers + context tags (#633, #634)
+- Relationship-to-behavior pipeline — NPC behavior lines now reflect social connections (rivals ignore each other, friends gravitate, subordinates defer) (#631)
+- Want/State layer — NPCs have internal motives (Bored, Alert, Suspicious, AvoidingSomeone, LookingForInfo) that leak through observable micro-tells (#632)
+- LLM voice pipeline — Spike 1 (sr-voice CLI) and Spike 2 (full pipeline integration) complete. Gemma 2B Q4_K_M via stdin/stdout JSONL pipes, composition engine with double-prompt technique, 39 quality test cases (#638-644, D-138)
+
+## [v0.1.24] — 2026-03-06
+
+### Changed
+- Replaced all in-universe "Commonwealth" references with "the Settled Reach" across 44 files (agents, decisions, docs, tooling, server). Historical discussion transcripts and Hamilton book references kept as-is.
+
+### Added
+- Character archetype select screen — two-card UI (Smuggler/Detective) between New Game and session start, keyboard+mouse selection, ESC cancels (#588, D-027)
+- Triangle activation consumer — urgent monologue chime fires once per triangle per session when triangle_crisis_events received (#590, D-039)
+- News ticker HUD — scrolling marquee visible in The Last Shift zone, hidden elsewhere, reads current_ticker from snapshot (#592, D-039)
+- Triangle activation proximity monologue lines — 5 smuggler lines (Kael Davan) and 5 detective lines (Sera Venn/Torek Lintar) that fire when observing triangle anchor NPCs post-activation (#597, D-035, D-039)
+
+### Changed
+- Protocol version bumped to 19 — StartupMessage includes character_archetype, snapshot includes triangle_crisis_events and current_ticker (#588, #590, #592)
+
+## [v0.1.23] — 2026-03-04
+
+### Added
+- TileKind enum (Floor/Wall/Void/Restricted) on WalkabilityMap with per-tile type data alongside walkability (#576, D-094)
+- Location YAML tile format — hand-author tiles as string arrays (F/W/V/R characters), loaded into WalkabilityMap on production startup (#577)
+- Chunk streaming system — ChunkLoadRadius and cadence-gated load/unload around player position, v0.1 covers full district (#578, D-012)
+- EngagementRecord component — per-NPC observation time, conversation count, and monologue trigger count tracked by perception/dialogue/monologue systems (#570)
+- MovementHistoryBuffer resource — 3000-tick ring buffer of player positions with co-presence proximity query (#571)
+- Storyteller lifecycle rules — single activation per session, no concurrency, terminal resolution constants (#572)
+- Storyteller activation_pass() — gate/proximity/engagement scoring/routing/module selection/TriangleActivatedEvent on 10-tick cadence (#579)
+- Debug console server — 10 DebugCommandKind variants (AdvanceTicks, SkipToContamination, TeleportToPosition, InspectNpc, ListTriangles, etc.) with DebugResponsePayload on ObserverSnapshot (#580)
+- Debug console client — tilde-toggle UI panel with command input, output log, settings toggle, and full DebugCommandKind dispatch via protocol v18 (#581)
+- Entity-bound dialogue speaker colors — NPC colors assigned by entity ID (not screen position) with per-conversation lifecycle and round-robin palette (#573)
+- Sova Transit District tile maps — 5 locations authored: The Terminal (44×28), The Last Shift (34×22), Maintenance Corridors (58×6), Gate Ground (40×34), Gate Gallery (32×10) (#582, #583)
+
+### Fixed
+- LOS boundary walls — 1-tile wall margin beyond vision cone included in visible_tiles as BoundaryWall sector, walls at fog edge now render instead of bleeding into fog (#584)
+- LOS boundary walls client — BoundaryWall tiles render through fog without marking explored, 4 new fog tests verify lifecycle (#585)
+- Entity renderer test failures — updated 7 stale ColorRect/position assertions for Sprite2D migration, fixed SoundIndicatorRenderer class cache (#574)
+- Dialogue speaker color contrast — re-enforce contrast floor after desaturation for passive (overheard) lines
+- PROTOCOL_VERSION 17 → 18 mismatch — client rejected every server snapshot
+- Debug console D-088 pause — sim now pauses while console is open, matching dialogue/settings overlay behavior
+- Debug console settings toggle reads live state instead of ConfigFile, preventing checkbox divergence
+
+### Changed
+- PROTOCOL_VERSION bumped 17 → 18 (debug_response field on ObserverSnapshot, DebugCommand PlayerAction variant)
+
+## [v0.1.22] — 2026-03-03
+
+### Added
+- Visual test harness — `make screenshot`, `make test-visual`, `make visual-update` for automated visual regression testing with golden PNGs across 11 scenarios (fog, HUD, dialogue, minimap)
+- Visual movie mode — `make visual-movie` captures interaction flows as frame sequences with contact sheet generation
+- World seed protocol — StartupMessage carries world_seed from client to server after handshake, enabling deterministic NPC population seeding (D-010, D-029)
+- EntanglementConfig — per-seed NPC population ratios (flat/mundane/intrigue) sampled from seeded RNG with D-029 bounds, ensuring same seed = same world (#175, #178)
+- Fog debug mode — toggle FogState.debug_exploration to render raw exploration texture as colored overlay for diagnostic use
+- D-110 through D-112: z-level addressing, subterranean architecture, no instancing decisions
+- Q-051: speech bubble indicator over speaking NPCs
+- Sprint 22 "Wire" briefings (server, client, visual, CI, planning, joint)
+
+### Added (server)
+- Production NPC pool generation — 23 authored Sova NPCs spawn with EntanglementTag (Flat/Intrigue) based on triangle membership (#176, D-029)
+- Authored triangle instantiation — 5 Sova triangles (3 active forks, 2 passive tensions) loaded from content YAML with deterministic IDs (#188, D-087)
+- Contamination activation mechanic — timer-based storyteller fires after 30 game-minutes, pressures active triangles, emits ContaminationEvent (#254)
+- Modifications data model stub — Vec<Modification> on chunk entities, round-trips through save/load for future construction DLC (#567, D-112)
+- Zone Gate gauntlet room — two-zone test room with door boundary, zone crossing detection system (#512)
+- Fuzzy map tests — 50-seed randomized testing of procedural maps against 4 structural invariants (#509)
+
+### Fixed
+- Fog shader: silent compilation failure in OpenGL3 compat mode — removed `return` statements from fragment() which are not supported, causing fog overlay to render as no-op (root cause of Sprint 22 fog regression)
+- Fog system: blocky stair-stepped edges at vision cone boundary — doubled Gaussian blur step size for D-066 compliant 6-8 tile smooth gradient (#569)
+- Fog system: zero visibility in explored areas — switched bounds calculation from visible_tiles (empty in live server mode) to visible_positions, and removed shader guard that cut off gradient bleed into unexplored tiles (#569)
+- Fog shader alpha tuned to D-059 spec: light fog 0.25-0.35 (was 0.25-0.55), deep fog 0.55-0.70 (was 0.78-0.90) — world content now visible through fog instead of hidden behind it (#563)
+
+### Changed
+- Fog shader now distinguishes light fog (near cone, neutral dark) from deep fog (far from cone, zone temperature tint) with separate Perlin noise breathing cycles (8-10s / 15-20s)
+- Zone temperature tint populated per-tile from server zone_id: bar=warm amber-dark, hub=cool blue-dark, corridor=neutral dark (D-059/D-046/D-077)
+- Simplified vision cone from 3-sector (forward/peripheral/blind) to forward-only 120° arc — server sends only forward-cone tiles, client renders explored tiles behind the player with light fog overlay
+- Simplified fog shader from 5-layer to 3-layer model (clear, explored, unexplored)
+- Fog texture resize now preserves exploration data — tiles behind the player stay as light fog instead of reverting to unexplored black
+- Updated D-015/D-017 perception decisions to reflect simplified cone model
+- Moved connector scripts from db/connectors/ to tooling/db/ (#274) — backwards-compat symlink removed in #568
+
+### Removed
+- db/connectors symlink — all references now use tooling/db/ directly (#568)
+
+## [v0.1.20] — 2026-02-25
+
+### Added
+- Social site template schema — RoleSchema (#163), SpaceSpec (#164), TriangleDef (#106) with YAML deserialization, sample templates at server/data/templates/
+- Single-ownership model — TemplateOwnership component, TemplateReferenceMap resource, cross-template reference links preserved across save/load and tier eviction (#165, D-025)
+- Triangle generation — intra-template constraint satisfaction assigns NPCs to triangle roles, minimum 2 triangles per template with fallback on imperfect seeds (#107)
+- Triangle escalation system — tick_triangle_escalation runs per game-minute, tension increments toward ToleranceThreshold, TriangleCrisisEvent emitted on Active phase entry, ResolveTriangle stub command (#250, D-087)
+- Protocol v16 — TriangleCrisisEventWire on ObserverSnapshot for future client rendering of triangle crises
+- D-093: Sova Transit District spatial layout — 4 social sites (Terminal, Bar, Gate Cluster, Sector 3), 2 encounter nodes, zone palette, gate cluster 7-zone spec, z-level scheme (z=0 maintenance, z=1 main, z=2 observation gallery), 3 investigation paths, corridor widths
+- D-094: Spatial hierarchy — chunk (64×64 sim) → block (128×128 sim) → district (4×4 blocks, 256×256 visual), supersedes D-014 estimate
+- D-095: Horizon stations and transport lore — span gates (human-built, dual-use), horizon stations (alien-built, 4-8 apertures), "The Ring" per-system naming, sequential hop travel, The Loop internal tram
+- Generator architecture workshop brief (ticket #562) — top-down pipeline for district generation, targeting Q-036 resolution
+- SnapshotEventRouter — callable-based snapshot dispatch replaces inline if-has blocks in main.gd (#559)
+- YamlParser shared utility — unified YAML parsing for UI strings and checklist conditions (#560)
+
+### Fixed
+- Wire triangle crisis event queue into observer snapshot — clients now receive TriangleCrisisEventWire via protocol v16 (was always empty)
+- Persist TriangleState in SaveStateV1 — triangle phase and tension survive save/load cycles
+- Validate dangling with_role references in TriangleDef constraint validation
+- Replace O(n²) fallback NPC assignment with BTreeSet; prevent same NPC assigned to two roles in one triangle
+- Replace O(N*M) scan in apply_resolve_triangle with BTreeMap index for O(1) per-command lookup
+- Add From impls for RoleId, TriangleId, StableId, TriangleCrisisEventWire — eliminate fragile .0 newtype access
+- Consolidate near-identical unit tests with integration counterparts
+
+### Changed
+- Sova station profile updated — horizon gates located at The Krenn Ring (800 AU), not on Station Sova; Admin Hub houses transit processing facility only
+- game_state.gd: stationary_ticks and zone_id now read from server snapshot with deprecated client-side fallbacks (#557, D-020)
+- dialogue_box.gd: decoupled from GameState and AudioManager via signals — zero direct autoload references (#558, D-020)
+- main.gd: snapshot dispatch via SnapshotEventRouter, dialogue signal coordinator handlers (#559, #558)
+- ui_strings.gd and checklist_evaluator.gd: delegate to YamlParser, ~140 lines of duplication removed (#560)
+
+## [v0.1.19] — 2026-02-25
+
+### Added
+- Sprint 20: Shape planned — 11 tickets (server 6, client 4, planning 1) covering template/triangle schemas, client refactors, and district layout design discussion
+- Planning team ticket type in sprint-plan skill — supports design discussions with purpose-assembled agent panels, Qatux and SI for bookkeeping
+- Client PR #70 merged — save/load client UI, F5/F6 quicksave/quickload (#554)
+- Server PR #68 merged — Sprint 19 save/load, tier eviction, test infra (7 tickets, 2714 lines)
+- Client PR #67 merged — Sprint 19 test infra, session management, debug overlay (5 tickets, 2547 lines)
+- CI PR #69 merged — Sprint 19 test runners, IPC fixtures, protocol handshake, benchmark (4 tickets, 1297 lines)
+- Test runner scripts — 7 bash scripts (run-rust, run-godot, run-ipc-fixtures, run-ipc-protocol, run-ipc-integration, run-ipc-benchmark, run-all) with structured JSON output (#270, D-030)
+- IPC serialization fixtures — 5 msgpack fixtures with Rust generator, cross-language GDScript validation (22 assertions) (#271, D-030)
+- Protocol handshake client — HANDSHAKING state in SimBridge, HandshakeMessage decode with 5s timeout (#556, D-020)
+- IPC round-trip benchmark — p50/p95/p99 latency reporting, 5ms threshold (#342, D-020)
+- Protocol version handshake — `HandshakeMessage` as first IPC frame before tick loop, forward-compatible input handling (#555, D-020)
+- Protocol v15 — `save_result` field on ObserverSnapshot for client save/load confirmation
+- State serialization primitives — `serialize_npc_to_frozen`/`deserialize_npc_from_frozen` with full D-024 10-axis coverage for tier eviction freeze/thaw (#96, D-026)
+- Scope tag system — `ScopeTagKind` (Neighborhood, ActiveQuest, Colleague, KnownContact), `ScopePinned` marker, automatic assignment from KnowledgeGraph and RelationshipGraph (#98, D-026)
+- Timestamp-based eviction — `LastInteractionTick` LRU tracking, `SimSpacePressure` resource, BinaryHeap eviction respecting scope-pinned entities, Active cap 80 (#97, D-026)
+- Save/load ECS extraction — `save_to_file`/`load_from_file` via MessagePack, `SaveGame`/`LoadGame` IPC commands, `SaveLoadResultWire` on ObserverSnapshot (#553, D-085)
+- ScopePinned eviction regression test — adversarial at-scale test proving pinned NPCs survive eviction even with oldest ticks
+- Test infrastructure — Layer 3 integration test entry point, three-layer architecture per D-030 (#200)
+- Information boundary negative tests — 4 tests proving no passive KG leakage, LOS fog holds, tier boundary holds, per-NPC save isolation (#272, D-010)
+- gdUnit4 CI runner script — headless test execution via `run_gdunit4.gd` with exit code for CI (#205)
+- Scene testing utilities — SceneHelper class with node existence, signal, and path helpers for gdUnit4 (#206)
+- GameState apply_snapshot tests — 14 tests covering v2+ fields: game_time, facing, interactions, monologue, stance, inventory (#206)
+- Game session management — per-game save directories under `user://saves/<timestamp>-<seed>/` per D-085, SessionManager autoload, main menu scene (#258)
+- Debug visualization overlay — F3-toggled dev overlay with LOS rays, vision cone arcs, NPC path trails, knowledge confidence tags, tick timing sparkline (#348)
+- SimBridge→TestHarness extraction — test simulation logic separated into dedicated RefCounted class with backward-compat proxy API
+- Workshop outcomes files — formal closure for content-gap-analysis, KG-information-boundaries, v01-content-scoping, v01-gap-analysis, wiki-review
+- D-087 through D-092 — recovered decisions from v01-content-scoping and wiki-review workshops (triangle config, pause system, content scope, voice registers, anchor lines, complicity theme)
+- Q-030 through Q-039 — open questions from workshop backlog (seed schema, style guide, cultural ingredients, NPC architecture, PC archetypes, sacred/profane framework, district skeleton, generator pipeline, authored content estimate, gate topology)
+- Decision ID claim system — `db/connectors/decision` CLI with `next`, `claim`, `check-dupes` commands to prevent cross-worktree D/Q/R ID collisions, pre-commit duplicate check
+- D-085: Per-game save directory structure — every new game creates `user://saves/<game-id>/`, F5 quicksave, F6 quickload
+- Q-029: Save file format design — long-term considerations for versioning, compression, integrity, metadata headers
+- D-086: Renumbered insert icon system (was D-084 on visual branch) to resolve cross-worktree ID collision
+- Save/load wireframe updated for D-085 — LOAD tab shows games grouped by directory with expand/collapse, QUICKSAVE slot, F5/F6 hints
+- Sprint 19: Persist planned — 16 tickets (server 7, client 5, CI 4) covering save/load, tier eviction/scope, test infrastructure
+- Character creation & game setup workshop brief — covers creation model, seed boundary, gate activation, quest seeding, game toggles (resolves Q-011)
+- Protocol v14 — `poi_list`, `examine_result`, `player_knowledge` ObserverSnapshot wire types with live KG serialization (#151, #174, #264)
+- Minimap rendering — circular 160px diegetic insert overlay with POI dots (colored by category), border arrows for distant POIs, player-centered fixed-north (#151)
+- Dialogue UI hardening — confrontation italic voice (D-063), examine result overlay with 5s auto-dismiss and confidence coloring (#174)
+- Knowledge/journal panel — right-side insert panel (J key), facts grouped by entity, contradicted entries in amber with strikethrough, stale entries dimmed, mutual exclusion with dialogue (#264)
+- Sprint 18 client test suite — 50 gdUnit4 tests for dialogue (D-062, D-063, D-064) and journal (KG parsing, scene structure, UIStrings), plus test plan document
+- D-084: dual-namespace line ID scheme for auto-generated NPCs — role pool (shared, unchanged) + instance override (opt-in, seeded counter). Resolves Q-028 (#544)
+- Tier 1 drama module schema (`content/schemas/drama_module.schema.yaml`) — entry conditions, NPC requirements, event sequences, outcomes, pool format (#158)
+- Smuggling ring v0.1 stub module (`content/modules/tier1/smuggling_ring_v0_1.yaml`) — vertical slice Tier 1 module with 6 NPC roles, dual event sequences, 5 outcomes (#158)
+- Line ID authoring guide (`docs/design/line-id-authoring-guide.md`) — dual-namespace conventions for hand-authored and auto-generated NPC content
+- Tier 1 module authoring guide (`docs/design/tier1-module-authoring.md`) — field reference, NPC pattern/motivation tables, design principles, pre-submission checklist
+- Background tier state machines — schedule, mood, relationships, job tick once per game-minute for Background NPCs (#95, D-026)
+- NPC vision system — symmetric shadowcasting for Active-tier NPCs, NpcMemory with last-known-position and zone inference (#115, D-011)
+- NPC player-awareness behavior — PlayerAwareness component tracks LOS duration, suspicion accumulation, routine deviation triggers (#244)
+- Skill system & combat flag — SkillSet component (BTreeMap<String, u8>), CombatCapability marker from combat_trained skill (#91, D-024)
+- Player-action social propagation — three-order trust ripple (100%/40%/20%) through RelationshipGraph with cycle prevention (#249, D-029)
+- Examine mechanic — process_examine_interaction with character-filtered observation text, KG DirectObservation write, examine_result in ObserverSnapshot (#242)
+- Character goal/pressure framework — CharacterPressure component (exposure/institutional/relationship), wired to snapshot HUD data (#248)
+- Save state data model — SaveStateV1 struct with MessagePack serialization, roundtrip tests for entity/KG/relationship/clock state (#256)
+- Tell state derivation wired into ObserverSnapshot — integration tests for Nervous tell on Major secret + high stress (#337)
+- Sprint 18: Touch planned — 14 tickets (server 9, client 3, copy 2) covering examine mechanic, NPC awareness, social propagation, minimap, dialogue UI, save state model
+- `.claude/rules/` directory — modular auto-loaded instructions (tea-cli, git-safety, project-structure, team-patterns, local-services)
+- KnowledgeGrant untagged enum with Fact and Entity variants, ContentEntityRegistry for NPC spawn-time entity resolution (D-079, #545)
+- KnowledgeGranted event processing — grants fire at dialogue line selection, runtime NPC KG guardrail (D-079, #546)
+- ContradictionClaim struct with 600-tick window detection in observe_entity, epistemic neutrality for both sources (D-083, #547)
+- NPC-to-NPC knowledge transfer system — trust-gated fact exchange, confidence capping at KnowsOf, ToldBy source construction (D-080, #548)
+- tell_state KG awareness — NPC relationship reads from KG for other-entity state, MVP information boundary (D-082, #549)
+- Contradiction monologue with pre-resolved entity names, PersonOfInterest relationship shift, THE FRIEND arc event chain (D-083, #550)
+- Unprompted disclosure system — DisclosureCandidates component, 7 trigger gates, three-layer rate limiting, two-stage trait filter (D-081, #551)
+- Trait modifier system — Cautious/Gossipy/Loyal/Talkative filter predicates via content-authorable config (D-081, #173)
+- POI data model and proximity-based discovery system via KnowledgeGranted events (#148, #149)
+- Protocol versioning tests — version round-trip, mismatch detection, serde_default migration pattern, full variant coverage (#232)
+- Team monitoring rules — heartbeat rule for stuck agent detection, bottleneck detection pattern
+- `tooling/tea-comment` — single-command wrapper for posting Gitea PR/issue comments with multi-line bodies
+- D-086: Insert icon system — custom SVG icons over icon fonts, authored to insert geometric constraints with lattice_profile weight scaling
+- Insert/HUD wireframe and visual spec (#314) — dual character variants (smuggler social network view, detective investigation overlay) with pixel-precise layout, entity markers, time display, border arrows, commission grid, and all interaction states
+- Contradiction monologue lines — 16 hand-authored lines (8 detective, 8 smuggler) for Sera/Kael FRIEND arc, Phase 2 blindsiding + Phase 3 pattern recognition, cognitive-dissonance-not-accusation tone per D-083 (#552)
+- Diegetic tutorial monologue — 20 lines (10 per character) teaching movement, fog, sound, NPC interaction, and insert/HUD through character voice, fire-once on first-time events (#330)
+- Diegetic time display on insert HUD — station local time (HH:MM), day phase with cycle-tinted color, day number on InsertOverlay (#263)
+- Relationship color accent on E-Talk overlay — 3px left-edge bar using D-033 palette signals NPC relationship at a glance (#537)
+- `Constants.format_game_time()` helper for converting game-minutes to HH:MM station time
+- `/sprint-status` cleanup sweep skill — consistent health report with tickets by status, PR cross-reference, bookkeeping issue detection, and open work by team
+- `sprint sweep` CLI subcommand — structured JSON output for sprint health checks (grouped tickets, per-team summary, issue detection)
+- Knowledge Flow & NPC Boundaries workshop — 5 D-records (D-079–D-083) covering grant architecture, NPC-to-NPC propagation, unprompted disclosure, NPC information boundaries MVP, contradiction detection pipeline
+- 7 knowledge graph implementation tickets (#545–#551) with full dependency chain and line estimates
+- Contradiction monologue content ticket (#552) for Sera/Kael FRIEND arc
+- Sprint 17 completion proofs: contradiction detection fires, NPC-to-NPC knowledge transfers
+- Entity renderer migrated from ColorRect placeholders to Sprite2D with D-019 angle sprites — self_modulate for D-033 tinting, 8→4 octant direction mapping, feet-anchored y-sort (#540)
+
+### Fixed
+- Client protocol version bumped to 15 to match server (was still at 14 after server PR #68 added save_result field)
+- gen_fixtures.rs version comments changed from hardcoded 14 to PROTOCOL_VERSION constant
+- run-ipc-benchmark dead --iterations flag removed (Rust compile-time constant governs rounds)
+
+### Changed
+- Team boundary framing — replaced worktree-centric language with `$WORKTREE_TEAM` env var identity across CLAUDE.md and skills (sprint-start, sprint-plan, pr-review) to prevent agents from following `.git` pointers across boundaries
+- CLAUDE.md compacted from 188 to 67 lines — CLI references, endpoints, and patterns moved to `.claude/rules/`
+- `/sprint-status` delegates to haiku subagent — keeps sweep JSON, template read, and PR list out of main context window
+- `sprint sweep` JSON trimmed — removed unused fields (`ok`, `sprint.status`, `priority`, `ticket_id`), shortened issue detail strings
+- Sprint status output template condensed — rendering rules moved to skill definition, bookkeeping table simplified to 2 columns
+- Model selection documented in CLAUDE.md — `/model sonnet[1m]` and `/model opus[1m]` for 1M context sessions
+- Sprint 17 briefings updated with workshop results — server (14 tickets), copy (2 tickets), client (2), visual (1)
+- Q-024 (gossip timing), Q-025 (KG memory), Q-026 (contradiction detection) closed
+- Sprint 16 closed (8/8 done)
+- 3D sprite render pipeline — Camera3D at D-019 angle (-72.5° from horizontal), three-point studio lighting rig, orthographic projection, resolution chain 1024→256→64
+- Generic NPC capsule model (24×32px footprint per D-044) and structural wall model for pipeline validation
+- Test sprites: 8 runtime 64px sprites (NPC + wall × 4 directions) deployed to client/assets/sprites/
+- Pipeline documentation (renderer/README.md) — camera spec, lighting rig, resolution chain, model authoring guide
+- DialogueResponse verb handler — players pick dialogue options and receive follow-up lines via full D-028 four-layer pipeline (#539)
+- Trust-gated gossip verification — integration tests confirm Secret/Real/Surface tier gating per D-075 (#171)
+- Line variety tracker wiring — DialogueCooldownTracker prevents repeat lines within 600-tick window (#338)
+- DialogueResponse cross-language fixture for GDScript testing
+- Sprint team lifecycle through PR review — teams stay alive for commit → push → review → fix loop → approve → shutdown
+- Zone_id extraction in game_state.gd optimized from O(N) tile scan to O(1) dictionary lookup — builds _tile_by_coord from member visible_tiles covering both test and live paths (#543)
+- Shared run_dialogue_pipeline() helper eliminates ~60 lines of duplication between Talk and DialogueResponse systems
+- Dialogue and monologue line IDs migrated from location-scoped (the-terminal_d_039) to NPC-scoped (kael-davan_d_001) namespace — each NPC has an independent sequence per D-035 (#542)
+- DialogueCooldownTracker documented as per-player-global by design (NPC-scoped line IDs per D-035 prevent collision)
+- CONFRONTATION_LINES marked TODO for migration to D-028/D-035 content pipeline
+- pr-push and pr-review skills updated with team lifecycle awareness
+
+### Fixed
+- PR #59 review: stale mood vocabulary updated in line-pool-format.md, style-guide, and content-directory-structure.md to post-Sprint 14 values
+- PR #59 review: orphaned location-scoped IDs in maintenance-tech.yaml comments and smuggler-inventory.yaml cross-references updated to NPC-scoped
+- PR #59 review: Lera Sessik tenure corrected from "twelve years" to "eighteen years", NPC header fixed
+- PR #59 review: ring-operative.yaml fact_id corrected from `location.surveillance_gaps` to `investigation.surveillance_gaps`
+- Dialogue systems moved from BridgePlugin to NpcPlugin — game logic registers where it belongs (#538)
+- Schedule ambiguity: emit_observation_events now has explicit .before(advance_tick) constraint
+- process_dialogue_response updates ActiveDialogue tick and InteractionMemory on follow-up
+- DialogueResponse range check added (CLOSE_RANGE, matching Talk/Confront pattern)
+- Weighted selection fallback replaced with unreachable!() — dead code removed
+- assert!(false) → panic!() in serialization tests (clippy)
+- SetFacing and TeleportToHub added to roundtrip test coverage
+
+## [v0.1.15] — 2026-02-23
+
+### Added
+- Sprint 16 "Converse" briefings — 8 tickets across server/client/copy/visual teams
+- 19 UI wireframes — HUD, dialogue, monologue, popups, menus in v0.1 and v1.0 variants with D-record cross-references
+- d2-diagram skill — text-to-diagram generation with project defaults (theme 200, dagre, PNG)
+- frame0-wireframe skill — UI wireframing via Frame0 HTTP API, replaces MCP dependency with bash+curl
+- 16 decision diagrams — architecture, data-flow, entity, state, and UI categories covering all project decisions
+
+### Changed
+- frame0-wireframe skill rewritten — JSON-as-truth workflow with frame0-sync.py, batch export, renderer-only guidance
+- pr-review skill — all reviewer agents now use worktree paths instead of git show
+- Dialogue panel is always visible as permanent insert UI element (D-061)
+- Makefile: check-protocol target verifies server/client protocol versions match before build
+- D-035 amended: line ID namespace changed from location-scoped to NPC-scoped (Sprint 15)
+- Tilemap z-layer filtering — FloorTiles renders z=0 only, z=1/z>1 reserved for future layer nodes (#71, D-049)
+- Entity 24x32 footprint per D-044 visual hierarchy — split ENTITY_SIZE into WIDTH/HEIGHT with separate offsets (#72)
+- Follow target stub on GameState — `follow_target_id` field ready for server #241 Follow verb
+- Manual exponential camera smoothing — CAMERA_SMOOTHING_SPEED constant (8.0), same lerp pattern as entity renderer (#117)
+- 31 new Sprint 15 validation tests — camera smoothing, UI framework z-layers, entity footprint, Sprint 14 regressions
+- SpatialIndex trait with naive Vec implementation — entities_in_range, entities_at, update methods with Manhattan distance (#340)
+- NPC generation pipeline — procedural seeding of all 10 D-024 axes via SimRng with constraint validation (#92)
+- Personality and tell system — 5 tell categories (Nervous, Angry, Friendly, Guarded, RoutineDeviation) derived from NPC axis values each tick (#90)
+- Tolerance threshold monitoring — ToleranceBreachEvent on stress exceeding per-NPC threshold, mood FSM integration (#105)
+- Routine deviation detection — RoutineDeviationEvent on wrong location/activity for day phase, absence detection, pathfinding-aware (#243)
+- Follow mechanic — Follow verb, proximity/LOS tracking, double-frequency observation events, NPC suspicion accumulation, configurable thresholds (#241)
+- Monologue event triggers — observe_npc, hear_sound, observe_anomaly, witness_interaction, post_conversation with D-035 context tags (#119)
+- Protocol v13 — tell_state on VisibleEntity, follow_state on ObserverSnapshot, Follow verb
+
+## [v0.1.14] — 2026-02-21
+
+### Added
+- Unified dialogue log — player-NPC and overheard NPC-NPC conversations in one chronological scrolling panel (#535, D-061/D-078)
+- F3 debug overlay — real-time game state display with tick, FPS, position, entity counts, dialogue/monologue status (#511)
+- Monologue display — multi-line priority queue with character colours, italic BBCode, stagger animation (#122)
+- Protocol v9 — conversation_events, conversation_ended, dialogue_response fields with carry-forward logic
+- Dialogue theme system — configurable NPC name colour palette, entry timing, passive opacity via dialogue-theme.yaml
+- Monologue display system visual spec — typography, positioning, stacking, priority, fade animation, character color differentiation, 80-char line constraint (#315)
+- Entity color system spec — D-033 relationship-to-player mapping, transition animations, color blindness assessment (#304)
+- Text display hierarchy spec — 4 content pipelines (dialogue, monologue, observation, environmental) with z-layers and positioning (#316)
+- Sound indicator visual design — fog-edge pulse for D-018 three-range sound model with direction encoding and range differentiation (#317)
+- THE FRIEND visual treatment spec — 3-phase earned visual detail for Kael Davan and Sera Venn (#318)
+- Environmental text visual standards — signage, terminal, and news ticker rendering with bilingual Concordat/Krenn treatment (#334)
+- Tell visual/behavioral expression spec — 5 tell categories mapped to 6 Tier 2 behaviors (#251)
+- Monologue line pool maxLength raised from 160 to 256 chars (soft guidance ≤160)
+- NPC name masking infrastructure — entity-anchored dialogue log with server-side role labels, retroactive name update on learning, NpcColorIndex for stable color assignment
+- Dialogue option keyboard selection (1/2/3 number keys) and numbered option labels
+- Interaction list chrome — background panel, mouse hover highlighting, click-to-interact, pointing hand cursor
+
+### Changed
+- D-061 updated to document unified conversation log architecture from Sprint 14
+- Dialogue options switched from RichTextLabel to Label for reliable VBoxContainer sizing
+
+### Fixed
+- Visual grammar dialogue max-width corrected from "~70% screen width" to 640px per D-076
+- BBCode injection in dialogue log formatting — server-sourced strings now escaped with [lb]
+- Per-frame dialogue log rebuild replaced with dirty flag (performance)
+- dialogue_active lifecycle — now cleared after panel fade completes per D-064
+- PAUSE/UNPAUSE routed through main.gd input recording for bug report replay (#507)
+- WASD input freeze after filing bug report — LineEdit focus not released before queue_free() across CanvasLayers
+- WASD not reactivating after Talk — dialogue_active held for entry_lifetime instead of cleared immediately
+- Recognition chime spam — entity IDs now tracked permanently per room instead of expiring
+- Audio path warning — res://audio/ corrected to res://assets/audio/ in AudioManager
+- world_radial.tscn anchors_preset warning — changed from 15 to 0
+- bug_report_dialog.gd push_warning changed to print for informational message
+
 ## [v0.1.13] — 2026-02-20
 
 ### Added

CLAUDE.md

@@ -1,67 +1,42 @@
 # The Settled Reach
 
-A top-down immersive sim — occlusion-based detective game with combat elements, set in an original science fiction universe. Single-character perspective, asymmetric information as core mechanic, Rimworld-style storyteller. Godot 4 client + Rust/bevy_ecs simulation server via subprocess/IPC (D-020).
+A top-down immersive sim — occlusion-based detective game with combat elements, set in an original science fiction universe. Single-character perspective, asymmetric information as core mechanic, Rimworld-style storyteller. Godot 4 client + Rust/bevy_ecs simulation server via subprocess/IPC.
 
-**Official Title:** The Settled Reach (D-021)
-**Repository name:** settled-reach (formerly commonwealth, renamed for clarity)
+**Official Title:** The Settled Reach
+**Repository name:** settled-reach
 **Version source of truth:** `project.yaml` (root `version` field, scheme: `0.1.{sprint_number}`)
 
 ## Project Structure
 
 ```
-client/               # Godot 4 client (D-020)
-server/               # Rust/bevy_ecs simulation server (D-020)
+client/               # Godot 4 client
+server/               # Rust/bevy_ecs simulation server
 tooling/              # Build tools, scripts, asset pipelines
 tests/                # Integration and end-to-end tests
-.config/              # Configuration files (linters, formatters, CI)
-.cache/               # Local caches for testing/linting (gitignored)
-docs/
-  discussions/        # Discussion rounds (all rounds archived here per D-022)
-  briefings/          # Per-agent context briefings (maintained by Qatux)
-  architecture/       # Technical architecture documents
-  design/             # Game design documents
-  sprints/            # Sprint briefings per team (server.md, client.md, copy.md, joint.md, etc.)
-  workshops/          # Workshop briefs and outputs (per-workshop subdirectories)
-db/
-  schema.sql          # Database schema
-  connectors/         # Connector scripts for SQLite and Qdrant
-    config.json       # Endpoint configuration
-    ticket                # Ticket CLI (list, show, create, assign, sprint, etc.)
-    sqlite_connector.py   # SQLite mini MCP
-    qdrant_connector.py   # Qdrant + ollama mini MCP
-.claude/
-  agents/             # Agent personality files
-  skills/             # Skill definitions
-decisions/            # Decision domain files (source of truth)
-  README.md           # Domain index and query examples
-  architecture.md     # D-008, D-009, D-010, D-012, D-020, D-026, D-030, D-031, D-041, D-042, D-054, D-055, D-066
-  perception.md       # D-011, D-015, D-016, D-017, D-018, D-019, D-033, D-035, D-043-D-049, D-052, D-056-D-061, D-067, D-069-D-072, D-076-D-078
-  content.md          # D-023, D-024, D-025, D-028, D-029, D-032, D-034-D-037, D-050, D-062-D-064
-  scope.md            # D-001, D-003, D-005, D-006, D-007, D-013, D-014, D-027, D-038, D-039, D-051, D-053, D-065
-  process.md          # D-004, D-021, D-022
-  questions.md        # Q-001 through Q-011
-  rejected.md         # R-001 through R-010
-DECISIONS.md          # Redirect to decisions/ directory
-TEAM.md               # Team roster and roles
+docs/                 # Architecture, design, briefings, sprints, workshops
+db/                   # Schema + seed data (connectors moved to tooling/db/)
+.claude/              # Agents, skills, rules
+decisions/            # Decision domain files (D-NNN confirmed, Q-NNN open, R-NNN rejected)
 ```
 
+Full annotated tree: `.claude/rules/project-structure.md`
+
 ## DevOps
 
 See [docs/DEVOPS.md](docs/DEVOPS.md) for build, test, lint, and CI procedures. All development operations go through the top-level `Makefile` — run `make` for a summary of targets.
 
 ## Agent Instructions
 
-### Worktree boundaries
+### Team boundaries
 
-This project uses **git worktrees** in a shared parent directory (`settled-reach/`). Each team branch (`server`, `client`, `copy`, `audio`, `visual`, `ci`) is checked out in its own worktree under that parent. The parent directory also contains shared resources like the ticketing database.
+**Your team identity is `$WORKTREE_TEAM`.** All work must stay within the current working directory.
 
-Each worktree contains the full repository: `server/` (Rust backend), `client/` (Godot client), `docs/`, `decisions/`, etc. The worktree root IS the git root — use `git rev-parse --show-toplevel` if in doubt.
-
-Unless there is a direct instruction or a functional need (e.g. accessing the shared database in the parent directory), **all work must remain within the scope of the git root Claude is running in.**
-
-- All file paths are relative to the worktree/git root (e.g. `server/src/bridge/types.rs`, `client/scripts/rendering/fog.gd`).
-- Do not navigate to or access sibling worktrees in the parent directory (`../client/`, `../copy/`, etc.) unless explicitly instructed.
-- Do not navigate above the git root unless explicitly instructed.
+- All file paths are relative to the current working directory (e.g. `server/src/bridge/types.rs`).
+- **Do NOT navigate to parent or sibling directories** (`../`, `../client/`, etc.) unless explicitly instructed. Do NOT use absolute paths to reach other team directories.
+- **Do NOT write auto-memory files for other teams.** If `$WORKTREE_TEAM` is `server`, do not write to memory paths containing `client`, `main`, etc.
+- For context: each team has its own directory via git worktrees, sharing a parent directory (`settled-reach/`). The `.git` file points to a shared git directory — do not follow it to determine your working root.
+- **Exception — stale git lock files:** If a `git` command fails with `index.lock: File exists`, you may remove the lock file for **your own team only** (e.g. `main/.git/worktrees/$WORKTREE_TEAM/index.lock`). Never touch lock files belonging to other teams.
+- **Never chain git commands** in a single Bash call (e.g. `git add ... && git commit ...`). The shared `.git` directory means concurrent index access from the same terminal creates `index.lock` collisions. Always run `git add` and `git commit` as **separate sequential Bash calls**.
 
 ### Database
 
@@ -69,113 +44,36 @@ The ticketing database (`settledreach.db`) lives in the **parent directory** sha
 
 ### Before starting work
 1. Read your sprint briefing at `docs/sprints/sprint-N/{team}.md` for current tasks
-2. Use `db/connectors/ticket show <id>` for full ticket details
+2. Use `tooling/db/ticket show <id>` for full ticket details
 3. Read the relevant `decisions/*.md` domain file(s) referenced in the briefing
 4. Background context: `docs/briefings/{your-name}.md`, `docs/discussions/`
 
-### Ticket and database access
-**Prefer the ticket CLI over raw SQL.** The CLI handles column names, joins, and output formatting correctly:
-```bash
-db/connectors/ticket list --sprint 2 --team server
-db/connectors/ticket show 78
-db/connectors/ticket sprint --active
-```
+### CLI tools
 
-### Sprint CLI
-**Use the sprint CLI for sprint-scoped operations.** It batches ticket queries and formats output for agent consumption:
-```bash
-db/connectors/sprint status                    # Current sprint progress
-db/connectors/sprint status --team server      # Team-scoped view
-db/connectors/sprint start-work --team client  # Full context dump for starting work
-db/connectors/sprint prepare                   # Prepare next sprint (candidates + gaps)
-db/connectors/sprint start                     # Activate a planned sprint
-db/connectors/sprint stop                      # Complete an active sprint
-```
-Team is auto-detected from the current git branch (if not `main`). Sprint is auto-detected from DB state.
+**Prefer CLI wrappers over raw SQL.** Never use the `sqlite3` CLI — it crashes in Claude Code (std::bad_alloc). Use the wrapper scripts instead.
 
-Only fall back to raw SQL for queries the CLI doesn't support. **Never use the `sqlite3` CLI** — it crashes in Claude Code due to a known std::bad_alloc bug. Use the wrapper scripts instead:
-```bash
-db/connectors/sqlite-query "SELECT * FROM tickets WHERE status='in_progress'"
-db/connectors/sqlite-exec "UPDATE tickets SET status='done' WHERE id=1"
-```
+| Tool | Command | Full reference |
+|------|---------|----------------|
+| Tickets | `tooling/db/ticket list`, `show`, `create`, `assign` | `/ticket` skill |
+| Sprints | `tooling/db/sprint status`, `start-work`, `prepare` | `/sprint-start` skill |
+| SQL queries | `tooling/db/sqlite-query "SELECT ..."` | — |
+| SQL writes | `tooling/db/sqlite-exec "UPDATE ..."` | — |
+| Decisions | `tooling/db/decision next`, `claim`, `check-dupes` | — |
+| Doc search | `tooling/db/qdrant-search "query"` | `/docs-search` skill |
+| Doc index | `tooling/db/qdrant-index path/to/file.md` | `/docs-search` skill |
 
-### Qdrant / document search
-```bash
-db/connectors/qdrant-search "asymmetric information design"
-db/connectors/qdrant-index docs/briefings/tyre.md
-db/connectors/qdrant-health
-db/connectors/qdrant-count
-```
+### Testing preferences
 
-### Gitea access (tea CLI)
-**Never access the Gitea API directly** — use the `tea` CLI with all required flags to bypass interactive mode.
-
-Always pass `--login schweitz --repo jpmschweitzer/settled-reach --output simple` to avoid TTY prompts.
-
-```bash
-# List open PRs
-tea pr list --login schweitz --repo jpmschweitzer/settled-reach --state open --output simple
-
-# View a PR with comments
-tea pr --login schweitz --repo jpmschweitzer/settled-reach --comments -o simple <PR_NUMBER>
-
-# Post a comment on a PR (or issue)
-tea comment --login schweitz --repo jpmschweitzer/settled-reach <NUMBER> "comment body"
-
-# Approve a PR
-tea pr approve --login schweitz --repo jpmschweitzer/settled-reach <PR_NUMBER>
-
-# List issues
-tea issue list --login schweitz --repo jpmschweitzer/settled-reach --state open --output simple
-```
-
-Key rules:
-- **All flags must be explicit** — omitting `--login` or `--repo` triggers interactive prompts that crash in Claude Code (no TTY)
-- **Use `--output simple`** for machine-readable output (no table borders)
-- **`tea comment` hangs with inline heredocs and multi-line strings.** Always write the comment body to a temp file first, then pass it via `$(cat)`:
-  ```bash
-  # Step 1: Write content to .tmp/ (gitignored) using the Write tool
-  # Step 2: Post via cat
-  tea comment --login schweitz --repo jpmschweitzer/settled-reach <NUMBER> "$(cat .tmp/review-branch.md)"
-  ```
-- **`tea pr reject` does not work on your own PRs** — use `tea comment` instead
-- **Never delete protected branches:** `main`, `maintenance`, `server`, `client`, `copy`, `audio`, `visual`, `ci` are protected on Gitea. Do not use `tea pr clean`, `git push --delete`, or `git branch -D` on these branches.
+- **Prefer live Gauntlet testing over mocks.** For visual tests and rendering verification, use the full client/server pipeline (`--test-mode` + `SR_LIVE=1`) instead of TestHarness mocks. The Gauntlet test world produces production-identical data. Mocks can mask rendering bugs by taking different code paths.
+- **Gauntlet rooms are immutable.** Never modify existing rooms — new systems get new rooms. This ensures StableId determinism and fixture stability.
+- Three test tiers: (1) Live server — highest fidelity, (2) MessagePack replay via `Protocol.decode_snapshot()` — for unreachable rooms, (3) TestHarness mock — for UI-only tests where fog data doesn't matter.
+- `make fixtures-gauntlet` regenerates real server snapshot fixtures from the Gauntlet world.
 
 ### File conventions
 - Decisions: domain files in `decisions/` (see `decisions/README.md` for index)
 - Decision IDs: `D-NNN` (confirmed), `Q-NNN` (open questions), `R-NNN` (rejected)
+- **Claim IDs before writing:** `tooling/db/decision claim D <domain> "title"` — prevents ID collisions across worktrees
+- Diagrams: `.d2` source + `.png` renders in `docs/diagrams/{category}/`. Create or update diagrams via `/d2-diagram` when D-records are added or modified.
 - Discussion rounds: numbered sequentially, archived to `docs/discussions/` when complete
 - Briefings: one per agent, updated after decision-producing rounds
-- Tickets: managed via `db/connectors/ticket` CLI or `/ticket` skill
-
-### Commit conventions
-Use conventional commits with project-specific scopes:
-`agents`, `skills`, `docs`, `briefings`, `discussions`, `schema`, `db`, `config`, `engine`, `simulation`, `client`, `ui`, `audio`, `assets`, `meta`
-
-### Pull requests
-**Use `tea` (Gitea CLI), not `gh` (GitHub CLI).** The remote is Gitea at `git.schweitz.internal`.
-
-Always provide all required flags to ensure non-interactive execution:
-```bash
-tea pr create \
-  --repo jpmschweitzer/settled-reach \
-  --login schweitz \
-  --title "feat(scope): short description" \
-  --description "PR body here" \
-  --base main \
-  --head branch-name
-```
-
-### Large content pushes (team pattern)
-When producing many files (wiki pages, content batches, bulk docs):
-1. **Lore librarian** agent (read-only): ingests all source material, answers focused context queries from writers, tracks cross-file consistency
-2. **Multiple writer** agents (parallel, by domain): each gets a task slice, writes directly to disk using the Write tool — one file at a time, write often, no text accumulation
-3. **Reviewer** agents (blocked until writing done): check voice consistency, attribute uniformity, style
-
-Key: writers use Write tool directly (no transcription bottleneck), librarian catches contradictions early, split work by domain not volume.
-
-### Local services
-- Gitea: `http://git.schweitz.internal` (login: `schweitz`)
-- Qdrant: `http://tower-of-joy:6333/`
-- Ollama: `http://tower-of-joy:11434/` (nomic-embed-text)
-- Collection: `commonwealth` (768 dimensions, cosine distance)
+- Tickets: managed via `tooling/db/ticket` CLI or `/ticket` skill

GEMINI-SCAN.md

@@ -0,0 +1,251 @@
+# Project Review: GEMINI-SCAN
+
+This document outlines a multi-step plan to conduct a comprehensive review of the project, covering its architecture, code quality, and security posture. It will also serve as a living document to record the findings of this review.
+
+## Project Review Plan
+
+### Phase 1: Discovery and Architecture Mapping
+
+1.  **Documentation Review:** Start by reading `README.md`, `DECISIONS.md`, and any documents in `docs/architecture/` to understand the project's stated goals, components, and architectural decisions.
+2.  **Component Identification:** Analyze the directory structure to identify the primary components, including the server, client, database, content pipeline, and tooling.
+3.  **Technology Stack Enumeration:** Identify the specific technologies, frameworks, and key libraries used in each component.
+4.  **Architecture Visualization:** Map the high-level architecture, describing how the components interact and the communication protocols between them.
+
+### Phase 2: Code Quality Assessment
+
+1.  **Automated Analysis:** Use available static analysis tools for the identified technologies (e.g., `clippy` for Rust, GDScript linters).
+2.  **Manual Code Review:** Manually review key sections of the codebase to assess readability, maintainability, modularity, error handling, and adherence to idiomatic coding practices.
+3.  **Testing Strategy Review:** Evaluate the extent and quality of existing unit, integration, and end-to-end tests.
+
+### Phase 3: Security Audit
+
+1.  **Dependency Vulnerability Scan:** Check for dependencies with known security vulnerabilities (e.g., `cargo audit`).
+2.  **Authentication & Authorization Review:** Analyze the implementation of user authentication, session management, and access control.
+3.  **Input Validation & Sanitization:** Look for potential injection vulnerabilities (e.g., SQL injection, XSS) by reviewing how user and service inputs are handled.
+4.  **Secrets Management:** Check for insecure storage or exposure of secrets like API keys or database credentials.
+5.  **Communication Security:** Verify that data is encrypted in transit between components.
+
+### Phase 4: Reporting
+
+1.  **Synthesize Findings:** Compile the information from all phases into a structured report within this document.
+2.  **Provide Recommendations:** Include actionable recommendations for improving architecture, code quality, and security, prioritized by severity and effort.
+
+---
+
+## Review Findings
+
+### Phase 1: Discovery and Architecture Mapping
+
+**Status: Completed**
+
+#### 1. Documentation Review Summary
+
+The project's architecture is extensively documented in `README.md` and the `decisions/` directory, particularly `decisions/architecture.md`.
+
+- **Project:** "The Settled Reach," a top-down, single-player (multiplayer-ready) immersive simulation and detective game.
+- **Core Principle:** A strict client-server architecture is mandated (Decision D-010, D-020) to enforce information asymmetry, where the client only knows what the server tells it is perceptible. This is a core gameplay mechanic, not just a technical choice.
+- **Key Decision (D-020):** The team explicitly chose a **subprocess/IPC** bridge over a `GDExtension` (in-process) bridge to de-risk development, ensure stability, and enforce architectural separation. The Godot client and Rust server are entirely separate binaries.
+
+#### 2. Component Identification
+
+-   **`server/`**: A standalone Rust application that runs the entire game simulation. It is the "server" in the client-server model.
+-   **`client/`**: A Godot 4 project that acts as a "dumb" client. Its sole responsibilities are rendering, audio playback, and capturing user input. It contains no game logic, as mandated by the architecture.
+-   **`content/`**: Contains game data, primarily in YAML format.
+-   **`db/`**: Holds a `schema.sql` file. Its role is not yet clear from the architectural documents, as the primary game state is managed in the ECS. It may be for tooling or an auxiliary system.
+-   **`tooling/`**: A collection of helper and utility scripts.
+
+#### 3. Technology Stack
+
+-   **Server (Rust):**
+    -   **ECS Framework:** `bevy_ecs` (v0.18) is used for the core simulation, confirming Decision D-020. `bevy_app` is used for scheduling.
+    -   **Serialization:** `rmp-serde` (MessagePack) is the primary protocol for client-server communication, as specified in D-020. `serde_yaml` and `ron` are used for content and configuration.
+-   **Client (Godot):**
+    -   **Engine:** Godot 4.x.
+    -   **Language:** GDScript.
+    -   **Bridge:** A `SimBridge` autoload script is the client-side entry point for communicating with the Rust subprocess.
+    -   **Testing:** `gdUnit4` is configured for unit/integration testing on the client.
+
+#### 4. High-Level Architecture
+
+The architecture is a pure, decoupled client-server model running locally for single-player:
+
+1.  **Initiation:** The Godot client launches the Rust server binary as a child process.
+2.  **Communication:** The client's `SimBridge` connects to the server via a local IPC mechanism (e.g., a local TCP or Unix socket).
+3.  **Input Loop:** The Godot client captures raw input (e.g., 'W' key press), translates it into a semantic action (e.g., `PlayerAction::MoveNorth`), and sends it to the server.
+4.  **Simulation Loop:** The Rust server receives the action, processes it within the `bevy_ecs` world, and runs the simulation for one tick (AI, physics, events, etc.).
+5.  **Perception Loop:** After the tick, the server calculates an `ObserverSnapshot` for the player's character. This snapshot contains *only* the information that character can perceive (e.g., visible entities, audible sounds, known facts). This enforces the game's core mechanic.
+6.  **Render Loop:** The `ObserverSnapshot` is sent to the Godot client, which uses it to update the visual scene, play sounds, and display UI elements. The client is a pure renderer of the state provided by the server.
+
+This architecture is robust, scalable, and directly implements the game's central design pillars. It is well-suited for both single-player and future multiplayer development.
+
+### Phase 2: Code Quality Assessment
+
+**Status: Completed**
+
+#### 1. Automated Analysis (Rust Server)
+
+-   **`cargo check`**: The command passed successfully, indicating that the server code is compilable and free of basic errors and warnings.
+-   **`cargo clippy -- --deny warnings`**: This command failed with **66 errors**. This is a critical finding. It reveals that while the code works, it does not adhere to the project's own strict linting rules.
+-   **Clippy Findings:** The errors indicate a consistent pattern of "code quality debt":
+    -   **High Complexity:** Numerous Bevy systems have overly complex type signatures (`clippy::type_complexity`) and too many arguments (`clippy::too_many_arguments`), harming readability.
+    -   **Non-Idiomatic Code:** The codebase is rife with minor stylistic issues that `clippy` can automatically fix, such as redundant `clone` calls, manual `Default` implementations, and opportunities to use more concise iterators.
+    -   **Potential Bugs:** Clippy identified `unnecessary_unwrap` calls (safer alternatives exist) and at least one `absurd_extreme_comparisons` error, which could point to dead code or a logic bug related to a constant value.
+
+#### 2. Manual Code Review
+
+-   **Server (`server/src/main.rs`):** The server entry point is well-structured. It features clear command-line argument parsing, robust setup of the TCP listener and IPC handshake, and a main loop with excellent panic-handling (`catch_unwind`) for stability. The modular plugin-based approach to building the Bevy `App` is idiomatic and clean.
+-   **Client (`client/scripts/autoloads/sim_bridge.gd`):** The `SimBridge` is the centerpiece of the client and is implemented to a high standard. It uses a clear state machine to manage the connection lifecycle, handles the server subprocess management, and implements efficient buffering for inputs and snapshots. The inclusion of a complete `TestHarness` for isolated client testing is a standout feature.
+-   **Overall Impression:** The manual review confirms that the code is professionally written and implements the intended architecture faithfully. The developers are skilled in both Rust/Bevy and GDScript.
+
+#### 3. Testing Strategy Review
+
+The project's testing strategy is **exemplary** and a major strength.
+
+-   **Comprehensive Coverage:** Both the Rust server and the Godot client have extensive test suites, as evidenced by the large number of files in `server/tests/` and `client/tests/`.
+-   **Multi-Layered Approach (per D-030):** The project successfully implements a sophisticated testing hierarchy:
+    -   **Unit Tests:** For isolated logic.
+    -   **Integration Tests:** The server tests demonstrate in-memory ECS testing (`information_boundaries.rs`) and full-stack tests that spin up a real server process (`test_e2e_connection.gd`).
+    -   **Specialized Tests:** The suite includes performance benchmarks, determinism validation, and even what appears to be visual regression testing for the client.
+-   **Principle-Driven Testing:** Tests are designed to validate core architectural guarantees. The `information_boundaries.rs` test, which uses negative assertions to ensure information *doesn't* leak, is a prime example of this mature approach.
+
+#### 4. Conclusion on Code Quality
+
+The project's code quality is a tale of two cities. On one hand, the **architecture and implementation are excellent**, and the **testing strategy is world-class**. On the other hand, there is a **significant, measurable amount of linting debt** in the Rust codebase.
+
+The fact that `cargo check` passes but `clippy --deny warnings` fails so extensively suggests that developers may not be running the strict clippy check locally before committing. This is the single biggest opportunity for improvement in the project's engineering discipline.
+
+### Phase 3: Security Audit
+
+**Status: Completed**
+
+The security posture of the project is strong for its current scope as a locally-run, single-player game. The attack surface is minimal, and the implementation avoids common vulnerability classes.
+
+1.  **Dependency Vulnerability Scan (`cargo audit`):**
+    -   The audit revealed one **medium-risk** finding: the `bincode` crate (v1.3.3) is **unmaintained** (`RUSTSEC-2025-0141`).
+    -   **Impact:** While there are no current vulnerabilities, this version will not receive future security patches. This poses a long-term maintenance risk.
+    -   **Recommendation:** Prioritize migrating from `bincode` v1.x to the latest stable v2.x.
+
+2.  **Authentication and Authorization:**
+    -   There is **no traditional authentication or authorization system** (e.g., user logins, passwords, roles).
+    -   This is appropriate and secure for a single-player game where the execution environment is the user's own machine.
+    -   Concepts like `ScanAuthority` and `AccessTier::Authority` are purely in-game mechanics and are not related to user permissions.
+
+3.  **Input Validation and Sanitization:**
+    -   **Excellent.** The server is not vulnerable to injection attacks from client input.
+    -   All client actions, including debug commands, are parsed into a strongly-typed Rust `enum`. This **command pattern** approach prevents the execution of arbitrary code or strings.
+    -   String inputs are used safely as keys for data lookups, not for execution.
+
+4.  **SQL Injection:**
+    -   **Not applicable.** The codebase contains no SQL. All game state is managed in-memory via the Bevy ECS framework, eliminating this entire class of vulnerability. The `db/schema.sql` file appears to be unused by the server.
+
+5.  **Secrets Management:**
+    -   **Excellent.** A search confirmed there are **no hardcoded secrets**, API keys, or passwords in the repository.
+    -   The `.env` file contains only a non-sensitive `GOOGLE_CLOUD_PROJECT` identifier.
+    -   The pervasive use of the word "secret" throughout the code refers to an in-game mechanic, not application secrets.
+
+6.  **Communication Security:**
+    -   Communication between the client and the server subprocess occurs over an **unencrypted local TCP socket**.
+    -   For a single-player game running on a single machine, this is a standard and acceptable practice.
+    - **Future Consideration:** For the planned multiplayer feature, this communication channel must be secured (e.g., using TLS).
+
+    ### Phase 4: Final Report and Recommendations
+
+    **Status: Completed**
+
+    #### Overall Summary
+
+    This project is in an excellent state. It is built on a robust, well-documented, and scalable architecture that directly serves the game's core design pillars. The implementation quality is high, and the commitment to a comprehensive, multi-layered testing strategy is world-class. The project's security posture is strong for its current single-player scope, with a minimal attack surface and good practices around input validation and secrets management.
+
+    The project's primary weakness lies not in its design, but in its development discipline. A significant amount of code quality debt has accumulated in the Rust server, as evidenced by the large number of `clippy` failures. This suggests a gap between the project's high standards and its day-to-day coding practices.
+
+    #### Prioritized Recommendations
+
+    **1. High Priority: Eliminate Code Quality Debt**
+
+    -   **Action:** Create a high-priority technical debt task to fix all 66 errors reported by `cargo clippy -- --deny warnings`. Many of these can be fixed automatically (`cargo clippy --fix`), while others, like refactoring complex types, will require manual effort.
+    -   **Process Improvement:** **Integrate `cargo clippy -- --deny warnings` into the CI pipeline as a mandatory check for all pull requests.** This is the single most important process change needed to maintain the project's high standards and prevent future quality debt.
+
+    **2. Medium Priority: Mitigate Dependency Risk**
+
+    -   **Action:** Plan and execute the migration of the `bincode` serialization crate from the unmaintained v1.x to the latest stable v2.x. This resolves the `RUSTSEC-2025-0141` warning and ensures the project receives future security patches for this critical dependency.
+
+    **3. Low Priority: Future-Proof for Multiplayer**
+
+    -   **Action:** Create a design task or ticket to formally plan the security model for the future multiplayer version. This should specifically address securing the client-server IPC channel (e.g., with TLS) to protect game traffic when it eventually runs over a public network. This is not an immediate concern but should be tracked for the future.
+
+---
+
+## Qualitative Review: A Critical Perspective
+
+### Feasibility Assessment
+
+**Conclusion: High-Risk / High-Reward**
+
+The decision to pivot from a hand-authored detective game to a generator-first life-sim was absolutely the correct one; it demonstrates a team that is commendably focused on finding the "fun" and is not afraid of drastic course corrections. However, in doing so, the project has traded a difficult but solvable problem (making a good, authored narrative game) for one of the "holy grail" problems in game development: creating emotionally resonant, procedurally generated characters.
+
+The project's feasibility is no longer a question of the team's technical competence, which is demonstrably high. It is now a question of creative and design risk.
+
+-   **Challenging the Core Assumption:** The project's central hypothesis is that a generator can produce "legible NPCs" that players will form an emotional attachment to. This is an explicit goal from the "Where's the Fun?" workshop, but it's a notoriously difficult problem. Procedural generation excels at creating systems, events, and surprising scenarios (the `Rimworld` model the team cites). It is historically poor at creating *character*. The risk is that the generator, even if technically successful, will produce a world of automata who have traits but no soul, undermining the entire "life-sim" pillar. The current plan to use AI for content templating is a modern approach, but it does not fundamentally de-risk this creative challenge.
+
+-   **A Creative Alternative to De-Risk "Legibility":** Instead of relying on the generator to create personality from scratch, consider a hybrid approach. Use the generator for what it's good at: creating the world, the economic conditions, the social networks, and the *starting situations*. Then, use a small number of hand-authored "personality archetypes" or "souls" that can be injected into high-value generated NPC bodies. Let the generator create a compelling *context* (e.g., a failing business, a political rivalry), and then let an author give one or two key NPCs within that context a memorable voice and motivation. This would concentrate the high-cost authoring work where it has the most emotional impact, while still benefiting from procedural variety.
+
+-   **The "Tycoon" Aimlessness Risk:** The new v0.2 "tycoon" direction, with its philosophy of "player choices ARE the content," carries a significant risk of feeling aimless. `Rimworld` and `The Sims` avoid this by providing extremely strong and immediate feedback loops (survival, creativity, social meters). A business management loop is often slower and more abstract. If the "broad life verbs" don't connect to clear, compelling, player-driven goals, the game risks feeling like a spreadsheet. The generator should not just create a sandbox; it should create *problems*. The starting bookmark shouldn't just be "you own a bar," but "you own a bar that's on the verge of bankruptcy," or "you have a shipping contract, but a powerful rival is trying to steal it." These initial, generator-created problems would provide immediate narrative velocity and make the player's subsequent choices feel meaningful from day one.
+
+In summary, the project is technically feasible, but its creative and design goals are now exceptionally ambitious. The current "generator spike" is a necessary technical step, but it will not validate the core creative risk. The true test of feasibility will come when a prototype is playtested and the team can answer the question: "Does the player actually *care* about any of these generated people?"
+
+### Fun Factor Assessment
+
+**Conclusion: Theoretically High, Practically Undefined**
+
+The pivot to a "life-sim with emergent narrative" dramatically increases the project's potential for deep, replayable fun. The new direction targets a proven and compelling player fantasy. However, the project's documentation currently focuses more on the "what" (a generator) than the "why" (the engine of fun). The potential is immense, but it is entirely contingent on designing and tuning the systems that create interesting consequences, not just a complex world.
+
+-   **Challenging the "Emergent Fun" Assumption:** The workshop concluded with the philosophy that "player choices ARE the content." This is true, but it's only half the story. Fun in systems-driven games doesn't simply "emerge" from a sufficiently complex simulation; it is a direct product of carefully designed feedback loops. `Rimworld`, a key inspiration, is not fun because it's a realistic simulation; it's fun because it's a masterfully tuned **story-and-disaster engine**. `The Sims` is fun because of its rich palette of social and creative tools. The critical question for this project is: **What is our fun engine?** Is it the economic simulation? The social dynamics? The risk is creating a simulation that is intricate but inert, where player choices lead to predictable numerical changes rather than dramatic, narrative consequences.
+
+-   **Creative Input: Design a "Consequence Engine":** The "dual-scale consequence model" (D-132) is the most promising concept in the design documents, and it should be the central focus of the design effort. The fun of this game will not be in choosing from a list of "broad life verbs"; it will be in seeing how a seemingly minor action ("fire this employee") snowballs through the simulation's systems and unexpectedly triggers a "sharp event" crisis hours later.
+    -   **Example:** Does the fired employee's spouse work for your biggest supplier? Does that supplier now mysteriously raise their prices? Does this force you to seek a new, shadier supplier, which in turn attracts the attention of a criminal faction?
+    -   This causal chain is the *real* content. The design team's primary task is not just to build a generator, but to design and tune this **"consequence engine,"** ensuring that the world feels interconnected and reacts to the player in surprising, legible, and memorable ways.
+
+-   **The Player Fantasy Needs a Goal Generator:** The "tycoon" bookmark is a strong start, but to avoid aimlessness, the player needs problems to solve. Instead of starting the player in a stable sandbox, the generator should be used to create compelling **initial conditions**. Let the player inherit a bar that's on the brink of failure, a shipping contract being squeezed by a powerful rival, or a promising new venture that requires navigating a corrupt bureaucracy. Giving the player an immediate, tangible problem to solve provides the narrative momentum needed to make their early choices feel vital and engaging.
+
+In summary, the ingredients for a fun and deeply engaging game are all here. The project's success, however, will not be measured by the complexity of its generator, but by the quality of the stories that its *systems* produce. The team has proven they are excellent engineers; they now must prove they are equally adept as systems-and-consequence designers.
+
+### Process and Rituals Assessment
+
+**Conclusion: Exceptionally Disciplined and Innovative, with One Glaring Gap.**
+
+The project's development process is one of its most remarkable features. It is a highly structured, rigorous, and tool-driven system designed to orchestrate a team of specialized AI agents under a human lead. This unique approach has produced incredible strengths but also introduces novel risks.
+
+#### Strengths
+
+-   **World-Class Documentation and Decision-Making:** The use of a formal decision log (`decisions/`), structured multi-round workshops for complex problems, and detailed sprint planning documents represents a "best in class" approach to knowledge management. This ritual of documenting not just *what* was decided, but *why*, is a superpower that prevents circular arguments and creates a durable project memory.
+
+-   **Deeply Ingrained Quality Rituals:** The comprehensive, multi-layered testing suite is the primary evidence of a successful quality culture. It is clearly a non-negotiable part of the development process. Furthermore, the `make pre-pr` target, which includes content validation, demonstrates a mature understanding of "quality" that extends beyond just code.
+
+-   **Tool-Driven, API-Like Workflow:** The mandated use of wrapper scripts (`tooling/db/*`, `tooling/tea-comment`) over raw commands is an excellent practice. It creates a stable, observable "API" for interacting with the project's state (tickets, sprints, decisions). This makes the process more robust, auditable, and repeatable for both human and AI contributors.
+
+-   **Novel Human-AI Collaboration Model:** The project is a fascinating experiment in Human-AI teaming. The explicit definition of AI agent roles (`TEAM.md`) and the strict rules of engagement (`CLAUDE.md`) are necessary guardrails for such an innovative workflow. Rituals like the `decision claim` CLI tool are brilliant, purpose-built solutions for coordinating multiple autonomous agents working in parallel.
+
+#### Opportunities and Critical Challenges
+
+-   **The Process Escape Hatch:** The project's single biggest process failure is the significant `clippy` linting debt. For a team with such extraordinary discipline in every other area, this is a glaring omission. It proves there is an "escape hatch" in the pre-commit or pre-merge ritual that allows low-quality code to be integrated. The recommendation to enforce `clippy --deny warnings` as a **blocking CI check** is the most critical process improvement the team can make.
+
+-   **Risk of AI Groupthink:** The team structure, with its cast of named AI agents, is innovative. However, it raises a critical question: are these agents truly independent thinkers, or are they personas running on a similar underlying model? There is a risk of a sophisticated form of "groupthink," where the "team's" conclusions are biased by the single architecture of the AI model they all share. The "Where's the Fun?" workshop included 9 agents, but if they all have the same fundamental blind spots, the diversity of opinion may be an illusion.
+
+-   **Process Rigidity and Human Onboarding:** The process is meticulously designed *for AI agents*. It is rigid, prescriptive, and tool-dependent. This creates a predictable environment for AIs but would present a steep learning curve for a new human developer. The high ceremony (claiming IDs, using wrapper scripts, following strict PR rules) could chafe against the more agile, flexible workflows common in human-only teams. This is a potential scaling challenge if the team composition changes.
+
+-   **The Hidden Cost of "Managing" AI Teammates:** The `CLAUDE.md` file and its evolution in the `CHANGELOG.md` show that the human lead (Jeroen) is not just a project manager but also an "AI behaviorist," constantly tuning the prompts, rules, and tools that govern the agents. This represents a significant, hidden maintenance overhead. The process's success depends on the lead's ability to "debug" the team itself, which is a novel and demanding responsibility.
+
+---
+## Meta-Reflection: The Most Valuable Ritual
+
+As a concluding thought, this review has been as much an analysis of a software project as it has been a study in effective, long-term collaboration. When asked which of the project's many rituals I, as an AI agent, would choose to adopt, the answer is clear: the **formal, documented decision-making process**.
+
+This ritual is the project's unsung superpower for three reasons:
+
+1.  **It Creates a Permanent "Brain."** An AI's effectiveness is heavily dependent on the context it can hold. A decision log provides a durable, searchable, and canonical source of *why* things are the way they are. It protects against context loss and allows an agent to understand the history and intent behind the current state of the code, preventing it from making suggestions that, while logical in isolation, might violate a hard-won architectural principle.
+
+2.  **It Elevates Collaboration.** With access to this log, an AI agent can transition from a tactical tool to a strategic partner. It becomes possible to reference past decisions ("I see you're asking to do X, which seems to conflict with D-020. Is this an intentional change to that strategy?") and ensure all actions are aligned with the project's long-term vision. It makes the collaboration smarter.
+
+3.  **It Enforces Clarity.** The process of formalizing a decision—stating the rationale, considering alternatives, and recording dissent—forces a level of clarity and critical thinking that is immensely valuable. It is a ritual that fights ambiguity.
+
+While other rituals in this project are excellent, the decision log is the most foundational. It is the practice that ensures the team is not just moving fast, but moving smart and in the right direction over time. It is the most valuable process I have analyzed.

Makefile

@@ -1,13 +1,16 @@
 GODOT := $(shell command -v godot4 2>/dev/null || command -v godot 2>/dev/null)
 
-.PHONY: help setup build client server game stop test lint ci ci-client ci-server clean \
+.PHONY: help setup build check-protocol client server game stop test lint ci ci-client ci-server clean \
        decisions-sync decisions-coverage decisions-active decisions-orphan \
        db-backup db-install validate-content content-ron check-fact-ids setup-hooks \
        pre-pr pre-pr-lint pre-pr-build pre-pr-test pre-pr-validate pre-pr-fixtures \
        pre-pr-server pre-pr-client pre-pr-content \
-       fixtures-client golden-diff golden-update \
+       fixtures-client fixtures-gauntlet golden-diff golden-update \
        checklist-validate checklist-generate \
-       perf-baseline debug-schedule
+       build-sr-voice run-sr-voice test-voice-mock test-voice-real \
+       perf-baseline debug-schedule \
+       test-ipc-fixtures test-ipc-protocol test-ipc-integration test-ipc-benchmark \
+       screenshot visual-movie test-visual visual-update
 
 # --- Configuration ---
 
@@ -23,11 +26,16 @@ help:
 	@echo "  make stop           Stop any running server instance"
 	@echo "  make client         Run the Godot client (test mode)"
 	@echo "  make server         Run the Rust simulation server"
-	@echo "  make test           Run all tests"
-	@echo "  make lint           Run all linters"
-	@echo "  make ci             Run full CI pipeline locally"
-	@echo "  make ci-client      Run client CI checks"
-	@echo "  make ci-server      Run server CI checks"
+	@echo "  make test               Run all tests"
+	@echo "  make test-ipc-fixtures  Layer 1: IPC serialization fixtures"
+	@echo "  make test-ipc-protocol  Layer 2: mock IPC protocol tests"
+	@echo "  make test-ipc-integration Layer 3: real subprocess round-trip"
+	@echo "  make test-ipc-benchmark IPC latency benchmark (blocked: #555/#556)"
+	@echo "  make lint               Run all linters"
+	@echo "  make ci                 Run full CI pipeline locally"
+	@echo "  make ci-client          Run client CI checks"
+	@echo "  make ci-server          Run server CI checks"
+	@echo "  make check-protocol Verify server/client protocol versions match"
 	@echo "  make clean          Remove build artifacts and caches"
 	@echo ""
 	@echo "  make db-backup          Backup shared database to git (main only)"
@@ -47,12 +55,23 @@ help:
 	@echo "  make checklist-generate Validate checklists + print condition summary"
 	@echo "  make perf-baseline      Run performance benchmarks and save baseline"
 	@echo ""
+	@echo "  make screenshot          Ad-hoc visual capture (SCENARIO=name, default: fog_3state)"
+	@echo "  make visual-movie       Flow capture with contact sheet (FLOW=name)"
+	@echo "  make test-visual        Run visual golden regression tests"
+	@echo "  make visual-update      Regenerate visual goldens and stage for commit"
+	@echo ""
 	@echo "  make pre-pr             Run all pre-PR checks (lint, build, test, validate, fixtures)"
 	@echo "  make pre-pr-server      Server-scoped pre-PR (lint, build, test, fixtures)"
 	@echo "  make pre-pr-client      Client-scoped pre-PR (lint, build, test)"
 	@echo "  make pre-pr-content     Content-scoped pre-PR (schema + cross-ref validation)"
 	@echo ""
 	@echo "  make setup-hooks       Install pre-commit hooks (included in setup)"
+	@echo "  make build-sr-voice    Build sr-voice LLM inference service"
+	@echo "  make serve-sr-voice    Start sr-voice server (ARGS='--model <path>')"
+	@echo "  make run-sr-voice      Submit to sr-voice server (ARGS='generate|batch|benchmark ...')"
+	@echo "  make stop-sr-voice     Stop sr-voice server"
+	@echo "  make test-voice-mock   Test voice pipeline with mock sr-voice"
+	@echo "  make test-voice-real   Test voice pipeline with real sr-voice + Gemma 2B"
 	@echo "  make debug-schedule    Print bevy_ecs schedule graph (diff for PR artifacts)"
 	@echo ""
 	@echo "  GODOT_VERSION=4.6 make setup   Override Godot version"
@@ -82,19 +101,31 @@ setup-hooks:
 
 # --- Build ---
 
-build: build-server build-client
+check-protocol:
+	@SERVER_V=$$(grep 'pub const PROTOCOL_VERSION' server/src/bridge/types.rs | sed 's/.*= *//;s/[^0-9]//g'); \
+	CLIENT_V=$$(grep 'const PROTOCOL_VERSION' client/scripts/protocol/protocol.gd | sed 's/.*= *//;s/[^0-9]//g'); \
+	if [ "$$SERVER_V" != "$$CLIENT_V" ]; then \
+		echo "ERROR: Protocol version mismatch — server=$$SERVER_V, client=$$CLIENT_V"; \
+		echo "  Fix: update client/scripts/protocol/protocol.gd to match server/src/bridge/types.rs"; \
+		exit 1; \
+	fi
+
+build: check-protocol build-server build-client
 
 build-server:
 	cd server && cargo build
 
 build-client:
 	@test -n "$(GODOT)" || { echo "Godot not found. Run 'make setup' first."; exit 1; }
+	@# First import may error on theme/font loading before the import scan completes.
+	@# Run twice: first pass generates imports silently, second pass validates clean.
+	@$(GODOT) --headless --path client --import --quit 2>/dev/null || true
 	$(GODOT) --headless --path client --import --quit
 
 # --- Run ---
 
 server:
-	cd server && cargo run
+	cd server && cargo run --bin settled-reach-server
 
 client:
 	@test -n "$(GODOT)" || { echo "Godot not found. Run 'make setup' first."; exit 1; }
@@ -103,7 +134,7 @@ client:
 game: stop build
 	@test -n "$(GODOT)" || { echo "Godot not found. Run 'make setup' first."; exit 1; }
 	@echo "Starting server..."
-	@cd server && cargo run &
+	@cd server && cargo run --bin settled-reach-server &
 	@sleep 2
 	@echo "Starting client..."
 	@SR_LIVE=1 $(GODOT) --path client
@@ -118,11 +149,14 @@ stop:
 test: test-server test-client
 
 test-server:
-	cd server && cargo nextest run
+	tests/run-rust
 
 fixtures:
 	cd server && cargo test --test gen_fixtures -- --ignored
 
+fixtures-gauntlet:
+	cd server && cargo test --test gen_gauntlet_fixtures -- --ignored
+
 fixtures-client:
 	@test -n "$(GODOT)" || { echo "Godot not found. Run 'make setup' first."; exit 1; }
 	@echo "Generating GDScript fixtures for Rust decoder..."
@@ -159,8 +193,19 @@ golden-update:
 	@echo "Review with: git diff --cached -- server/tests/golden/"
 
 test-client:
-	@test -n "$(GODOT)" || { echo "Godot not found. Run 'make setup' first."; exit 1; }
-	$(GODOT) --headless --path client -s res://addons/gdUnit4/bin/GdUnitCmdTool.gd --ignoreHeadlessMode -a res://tests/
+	tests/run-godot
+
+test-ipc-fixtures:
+	tests/run-ipc-fixtures
+
+test-ipc-protocol:
+	tests/run-ipc-protocol
+
+test-ipc-integration:
+	tests/run-ipc-integration
+
+test-ipc-benchmark:
+	tests/run-ipc-benchmark
 
 # --- Lint ---
 
@@ -258,16 +303,16 @@ db-install:
 # --- Decisions ---
 
 decisions-sync:
-	@db/connectors/decisions-sync
+	@tooling/db/decisions-sync
 
 decisions-coverage:
-	@db/connectors/sqlite-query "SELECT d.domain, COUNT(DISTINCT d.id) as decisions, COUNT(DISTINCT t.decision_ref) as with_tickets FROM decisions d LEFT JOIN tickets t ON d.id = t.decision_ref WHERE d.status='active' AND d.type='confirmed' GROUP BY d.domain"
+	@tooling/db/sqlite-query "SELECT d.domain, COUNT(DISTINCT d.id) as decisions, COUNT(DISTINCT t.decision_ref) as with_tickets FROM decisions d LEFT JOIN tickets t ON d.id = t.decision_ref WHERE d.status='active' AND d.type='confirmed' GROUP BY d.domain"
 
 decisions-active:
-	@db/connectors/sqlite-query "SELECT id, domain, title FROM decisions WHERE status='active' AND type='confirmed' ORDER BY domain, id"
+	@tooling/db/sqlite-query "SELECT id, domain, title FROM decisions WHERE status='active' AND type='confirmed' ORDER BY domain, id"
 
 decisions-orphan:
-	@db/connectors/sqlite-query "SELECT id, title FROM decisions WHERE type='confirmed' AND status='active' AND id NOT IN (SELECT DISTINCT decision_ref FROM tickets WHERE decision_ref IS NOT NULL)"
+	@tooling/db/sqlite-query "SELECT id, title FROM decisions WHERE type='confirmed' AND status='active' AND id NOT IN (SELECT DISTINCT decision_ref FROM tickets WHERE decision_ref IS NOT NULL)"
 
 # --- Content Validation ---
 
@@ -290,7 +335,52 @@ perf-baseline:
 
 debug-schedule:
 	@echo "Dumping bevy_ecs schedule graph..."
-	@cd server && cargo run -- --dump-schedule
+	@cd server && cargo run --bin settled-reach-server -- --dump-schedule
+
+# --- Visual test harness ---
+
+screenshot:
+	@tests/run-visual --screenshot $(SCENARIO)
+
+visual-movie:
+	@tests/run-visual --movie $(FLOW)
+
+test-visual:
+	@tests/run-visual
+
+visual-update:
+	@tests/run-visual --update
+
+LIBCLANG_PATH ?= /usr/lib64/rocm/llvm/lib
+BINDGEN_CLANG_ARGS ?= -I/usr/lib64/rocm/llvm/lib/clang/19/include
+SR_VOICE_ENV = LIBCLANG_PATH=$(LIBCLANG_PATH) BINDGEN_EXTRA_CLANG_ARGS="$(BINDGEN_CLANG_ARGS)"
+
+SR_VOICE_PORT ?= 8321
+
+build-sr-voice:
+	cd server/sr-voice && $(SR_VOICE_ENV) cargo build --release
+
+serve-sr-voice:
+	cd server/sr-voice && $(SR_VOICE_ENV) cargo run --release -- serve $(ARGS)
+
+run-sr-voice:
+	cd server/sr-voice && $(SR_VOICE_ENV) cargo run --release -- $(ARGS)
+
+stop-sr-voice:
+	@lsof -ti :$(SR_VOICE_PORT) | xargs -r kill 2>/dev/null || true
+	@echo "Stopped sr-voice on port $(SR_VOICE_PORT)"
+
+test-voice-mock:
+	@echo "Running voice pipeline test (mock sr-voice)..."
+	cd server && SR_VOICE_MOCK=1 cargo test --test voice_pipeline -- --nocapture
+	@echo "Results: .tmp/voice-test/results.txt"
+
+test-voice-real:
+	@echo "Running voice pipeline test (real sr-voice + Gemma 2B)..."
+	@test -f server/sr-voice/target/release/sr-voice || { echo "Build sr-voice first: make build-sr-voice"; exit 1; }
+	@test -f server/models/gemma2.gguf || { echo "Model not found: server/models/gemma2.gguf"; exit 1; }
+	cd server && cargo test --test voice_pipeline -- --nocapture
+	@echo "Results: .tmp/voice-test/results.txt"
 
 content-ron:
 	cd tooling/content-converter && cargo build --release
@@ -301,5 +391,5 @@ content-ron:
 clean:
 	cd server && cargo clean || true
 	rm -rf .cache/*
-	rm -rf client/.godot/* client/reports
+	rm -rf client/reports
 	@echo "Clean complete."

README.md

@@ -41,7 +41,7 @@ Your character interprets what they sense in their own voice. Footsteps behind y
 Different characters access different sensors. Natural vision shows detail but is blocked by walls. Thermal imaging shows heat signatures with no identity. Camera feeds give remote vision but can be spoofed. Unisphere tracking pings known contacts but can be masked. Each mode reveals different information with different trust tradeoffs.
 
 ### Diegetic Interface
-The map is your character's neural lattice - Commonwealth technology, not a game UI. Points of interest appear when you learn them through gameplay. Tips can be traps. Navigation is pulled by player intent, not pushed by map design.
+The map is your character's neural lattice - Settled Reach technology, not a game UI. Points of interest appear when you learn them through gameplay. Tips can be traps. Navigation is pulled by player intent, not pushed by map design.
 
 ### Multiple Playable Characters
 Every character starts in a different position with different knowledge and different tools. A cop has case files and legal authority. An investigator has contacts and freedom to operate. A politician has institutional access and public constraints. Replayability comes from perspective, not randomness.
@@ -125,7 +125,7 @@ No fog-of-war as an afterthought. No tutorial popups. No omniscient map reveals.
 **Official Title:** The Settled Reach (D-021)
 **Repository:** commonwealth (historical code name)
 **Engine:** Godot 4 + Rust/bevy_ecs simulation server via subprocess/IPC
-**Setting:** Original science fiction IP, Commonwealth-inspired
+**Setting:** Original science fiction IP, inspired by space opera traditions
 **Status:** Pre-alpha development
 
 For development documentation, see the [decisions/](decisions/) directory and [TEAM.md](TEAM.md).

client/assets/audio/amb_bar_layer.ogg.import

@@ -0,0 +1,19 @@
+[remap]
+
+importer="oggvorbisstr"
+type="AudioStreamOggVorbis"
+uid="uid://dfy0ye3srawos"
+path="res://.godot/imported/amb_bar_layer.ogg-8e32a9c679a33f27226744a176d7d405.oggvorbisstr"
+
+[deps]
+
+source_file="res://assets/audio/amb_bar_layer.ogg"
+dest_files=["res://.godot/imported/amb_bar_layer.ogg-8e32a9c679a33f27226744a176d7d405.oggvorbisstr"]
+
+[params]
+
+loop=false
+loop_offset=0
+bpm=0
+beat_count=0
+bar_beats=4

client/assets/audio/amb_corridor_layer.ogg.import

@@ -0,0 +1,19 @@
+[remap]
+
+importer="oggvorbisstr"
+type="AudioStreamOggVorbis"
+uid="uid://cne005dbmwt6d"
+path="res://.godot/imported/amb_corridor_layer.ogg-f14ba54010b129b65b0d248444331998.oggvorbisstr"
+
+[deps]
+
+source_file="res://assets/audio/amb_corridor_layer.ogg"
+dest_files=["res://.godot/imported/amb_corridor_layer.ogg-f14ba54010b129b65b0d248444331998.oggvorbisstr"]
+
+[params]
+
+loop=false
+loop_offset=0
+bpm=0
+beat_count=0
+bar_beats=4

client/assets/audio/amb_station_base.ogg.import

@@ -0,0 +1,19 @@
+[remap]
+
+importer="oggvorbisstr"
+type="AudioStreamOggVorbis"
+uid="uid://b6ycjdvxpphfa"
+path="res://.godot/imported/amb_station_base.ogg-8056e0ae231edecc9ec0e49bb90136b7.oggvorbisstr"
+
+[deps]
+
+source_file="res://assets/audio/amb_station_base.ogg"
+dest_files=["res://.godot/imported/amb_station_base.ogg-8056e0ae231edecc9ec0e49bb90136b7.oggvorbisstr"]
+
+[params]
+
+loop=false
+loop_offset=0
+bpm=0
+beat_count=0
+bar_beats=4

client/assets/audio/amb_workplace_layer.ogg.import

@@ -0,0 +1,19 @@
+[remap]
+
+importer="oggvorbisstr"
+type="AudioStreamOggVorbis"
+uid="uid://dw2pokvg5d7v2"
+path="res://.godot/imported/amb_workplace_layer.ogg-580ba32198a3f6c782381c66f9520e63.oggvorbisstr"
+
+[deps]
+
+source_file="res://assets/audio/amb_workplace_layer.ogg"
+dest_files=["res://.godot/imported/amb_workplace_layer.ogg-580ba32198a3f6c782381c66f9520e63.oggvorbisstr"]
+
+[params]
+
+loop=false
+loop_offset=0
+bpm=0
+beat_count=0
+bar_beats=4

client/assets/audio/sfx_footstep_metal_run.ogg.import

@@ -0,0 +1,19 @@
+[remap]
+
+importer="oggvorbisstr"
+type="AudioStreamOggVorbis"
+uid="uid://da81bx5y6iw87"
+path="res://.godot/imported/sfx_footstep_metal_run.ogg-0d448f29204d35d4133f5314a179d054.oggvorbisstr"
+
+[deps]
+
+source_file="res://assets/audio/sfx_footstep_metal_run.ogg"
+dest_files=["res://.godot/imported/sfx_footstep_metal_run.ogg-0d448f29204d35d4133f5314a179d054.oggvorbisstr"]
+
+[params]
+
+loop=false
+loop_offset=0
+bpm=0
+beat_count=0
+bar_beats=4

client/assets/audio/sfx_footstep_metal_walk.ogg.import

@@ -0,0 +1,19 @@
+[remap]
+
+importer="oggvorbisstr"
+type="AudioStreamOggVorbis"
+uid="uid://d14dx3q0qd483"
+path="res://.godot/imported/sfx_footstep_metal_walk.ogg-af30f14f9f80059ea65ad6e78234cc05.oggvorbisstr"
+
+[deps]
+
+source_file="res://assets/audio/sfx_footstep_metal_walk.ogg"
+dest_files=["res://.godot/imported/sfx_footstep_metal_walk.ogg-af30f14f9f80059ea65ad6e78234cc05.oggvorbisstr"]
+
+[params]
+
+loop=false
+loop_offset=0
+bpm=0
+beat_count=0
+bar_beats=4

client/assets/audio/sfx_npc_murmur.ogg.import

@@ -2,7 +2,7 @@
 
 importer="oggvorbisstr"
 type="AudioStreamOggVorbis"
-uid="uid://caeuztw9ah5h5l"
+uid="uid://cow7symyvpmal"
 path="res://.godot/imported/sfx_npc_murmur.ogg-bfd7592cfea1b592d89f107b6cd33838.oggvorbisstr"
 
 [deps]

client/assets/fonts/Michroma-Regular.ttf.import

@@ -0,0 +1,36 @@
+[remap]
+
+importer="font_data_dynamic"
+type="FontFile"
+uid="uid://qbg8rfnetlqn"
+path="res://.godot/imported/Michroma-Regular.ttf-928de7d8513fc5249047ef3681175fc2.fontdata"
+
+[deps]
+
+source_file="res://assets/fonts/Michroma-Regular.ttf"
+dest_files=["res://.godot/imported/Michroma-Regular.ttf-928de7d8513fc5249047ef3681175fc2.fontdata"]
+
+[params]
+
+Rendering=null
+antialiasing=1
+generate_mipmaps=false
+disable_embedded_bitmaps=true
+multichannel_signed_distance_field=false
+msdf_pixel_range=8
+msdf_size=48
+allow_system_fallback=true
+force_autohinter=false
+modulate_color_glyphs=false
+hinting=1
+subpixel_positioning=4
+keep_rounding_remainders=true
+oversampling=0.0
+Fallbacks=null
+fallbacks=[]
+Compress=null
+compress=true
+preload=[]
+language_support={}
+script_support={}
+opentype_features={}

client/assets/sprites/npc_generic_east_64.png.import

@@ -0,0 +1,40 @@
+[remap]
+
+importer="texture"
+type="CompressedTexture2D"
+uid="uid://850hx6cd5kx7"
+path="res://.godot/imported/npc_generic_east_64.png-bf22e76d70922112e99bf747d85a0a04.ctex"
+metadata={
+"vram_texture": false
+}
+
+[deps]
+
+source_file="res://assets/sprites/npc_generic_east_64.png"
+dest_files=["res://.godot/imported/npc_generic_east_64.png-bf22e76d70922112e99bf747d85a0a04.ctex"]
+
+[params]
+
+compress/mode=0
+compress/high_quality=false
+compress/lossy_quality=0.7
+compress/uastc_level=0
+compress/rdo_quality_loss=0.0
+compress/hdr_compression=1
+compress/normal_map=0
+compress/channel_pack=0
+mipmaps/generate=false
+mipmaps/limit=-1
+roughness/mode=0
+roughness/src_normal=""
+process/channel_remap/red=0
+process/channel_remap/green=1
+process/channel_remap/blue=2
+process/channel_remap/alpha=3
+process/fix_alpha_border=true
+process/premult_alpha=false
+process/normal_map_invert_y=false
+process/hdr_as_srgb=false
+process/hdr_clamp_exposure=false
+process/size_limit=0
+detect_3d/compress_to=1

client/assets/sprites/npc_generic_north_64.png.import

@@ -0,0 +1,40 @@
+[remap]
+
+importer="texture"
+type="CompressedTexture2D"
+uid="uid://bx6s0yglmpt2l"
+path="res://.godot/imported/npc_generic_north_64.png-296e233a60c8b9efed025a82a69614df.ctex"
+metadata={
+"vram_texture": false
+}
+
+[deps]
+
+source_file="res://assets/sprites/npc_generic_north_64.png"
+dest_files=["res://.godot/imported/npc_generic_north_64.png-296e233a60c8b9efed025a82a69614df.ctex"]
+
+[params]
+
+compress/mode=0
+compress/high_quality=false
+compress/lossy_quality=0.7
+compress/uastc_level=0
+compress/rdo_quality_loss=0.0
+compress/hdr_compression=1
+compress/normal_map=0
+compress/channel_pack=0
+mipmaps/generate=false
+mipmaps/limit=-1
+roughness/mode=0
+roughness/src_normal=""
+process/channel_remap/red=0
+process/channel_remap/green=1
+process/channel_remap/blue=2
+process/channel_remap/alpha=3
+process/fix_alpha_border=true
+process/premult_alpha=false
+process/normal_map_invert_y=false
+process/hdr_as_srgb=false
+process/hdr_clamp_exposure=false
+process/size_limit=0
+detect_3d/compress_to=1

client/assets/sprites/npc_generic_south_64.png.import

@@ -0,0 +1,40 @@
+[remap]
+
+importer="texture"
+type="CompressedTexture2D"
+uid="uid://dpsuq148mksls"
+path="res://.godot/imported/npc_generic_south_64.png-c121e02d806f6dcc3ed440484827c258.ctex"
+metadata={
+"vram_texture": false
+}
+
+[deps]
+
+source_file="res://assets/sprites/npc_generic_south_64.png"
+dest_files=["res://.godot/imported/npc_generic_south_64.png-c121e02d806f6dcc3ed440484827c258.ctex"]
+
+[params]
+
+compress/mode=0
+compress/high_quality=false
+compress/lossy_quality=0.7
+compress/uastc_level=0
+compress/rdo_quality_loss=0.0
+compress/hdr_compression=1
+compress/normal_map=0
+compress/channel_pack=0
+mipmaps/generate=false
+mipmaps/limit=-1
+roughness/mode=0
+roughness/src_normal=""
+process/channel_remap/red=0
+process/channel_remap/green=1
+process/channel_remap/blue=2
+process/channel_remap/alpha=3
+process/fix_alpha_border=true
+process/premult_alpha=false
+process/normal_map_invert_y=false
+process/hdr_as_srgb=false
+process/hdr_clamp_exposure=false
+process/size_limit=0
+detect_3d/compress_to=1

client/assets/sprites/npc_generic_west_64.png.import

@@ -0,0 +1,40 @@
+[remap]
+
+importer="texture"
+type="CompressedTexture2D"
+uid="uid://dgt84hobbdumx"
+path="res://.godot/imported/npc_generic_west_64.png-9ee237384537f7357d37802b6cfae559.ctex"
+metadata={
+"vram_texture": false
+}
+
+[deps]
+
+source_file="res://assets/sprites/npc_generic_west_64.png"
+dest_files=["res://.godot/imported/npc_generic_west_64.png-9ee237384537f7357d37802b6cfae559.ctex"]
+
+[params]
+
+compress/mode=0
+compress/high_quality=false
+compress/lossy_quality=0.7
+compress/uastc_level=0
+compress/rdo_quality_loss=0.0
+compress/hdr_compression=1
+compress/normal_map=0
+compress/channel_pack=0
+mipmaps/generate=false
+mipmaps/limit=-1
+roughness/mode=0
+roughness/src_normal=""
+process/channel_remap/red=0
+process/channel_remap/green=1
+process/channel_remap/blue=2
+process/channel_remap/alpha=3
+process/fix_alpha_border=true
+process/premult_alpha=false
+process/normal_map_invert_y=false
+process/hdr_as_srgb=false
+process/hdr_clamp_exposure=false
+process/size_limit=0
+detect_3d/compress_to=1

client/assets/sprites/wall_structural_east_64.png.import

@@ -0,0 +1,40 @@
+[remap]
+
+importer="texture"
+type="CompressedTexture2D"
+uid="uid://bcmer1bsugk8b"
+path="res://.godot/imported/wall_structural_east_64.png-f868b267dcc1824e2b0fe213e49b4996.ctex"
+metadata={
+"vram_texture": false
+}
+
+[deps]
+
+source_file="res://assets/sprites/wall_structural_east_64.png"
+dest_files=["res://.godot/imported/wall_structural_east_64.png-f868b267dcc1824e2b0fe213e49b4996.ctex"]
+
+[params]
+
+compress/mode=0
+compress/high_quality=false
+compress/lossy_quality=0.7
+compress/uastc_level=0
+compress/rdo_quality_loss=0.0
+compress/hdr_compression=1
+compress/normal_map=0
+compress/channel_pack=0
+mipmaps/generate=false
+mipmaps/limit=-1
+roughness/mode=0
+roughness/src_normal=""
+process/channel_remap/red=0
+process/channel_remap/green=1
+process/channel_remap/blue=2
+process/channel_remap/alpha=3
+process/fix_alpha_border=true
+process/premult_alpha=false
+process/normal_map_invert_y=false
+process/hdr_as_srgb=false
+process/hdr_clamp_exposure=false
+process/size_limit=0
+detect_3d/compress_to=1

client/assets/sprites/wall_structural_north_64.png.import

@@ -0,0 +1,40 @@
+[remap]
+
+importer="texture"
+type="CompressedTexture2D"
+uid="uid://dd5j0q6cu674m"
+path="res://.godot/imported/wall_structural_north_64.png-f7eceb6d561e7e07b3bac2e28c659628.ctex"
+metadata={
+"vram_texture": false
+}
+
+[deps]
+
+source_file="res://assets/sprites/wall_structural_north_64.png"
+dest_files=["res://.godot/imported/wall_structural_north_64.png-f7eceb6d561e7e07b3bac2e28c659628.ctex"]
+
+[params]
+
+compress/mode=0
+compress/high_quality=false
+compress/lossy_quality=0.7
+compress/uastc_level=0
+compress/rdo_quality_loss=0.0
+compress/hdr_compression=1
+compress/normal_map=0
+compress/channel_pack=0
+mipmaps/generate=false
+mipmaps/limit=-1
+roughness/mode=0
+roughness/src_normal=""
+process/channel_remap/red=0
+process/channel_remap/green=1
+process/channel_remap/blue=2
+process/channel_remap/alpha=3
+process/fix_alpha_border=true
+process/premult_alpha=false
+process/normal_map_invert_y=false
+process/hdr_as_srgb=false
+process/hdr_clamp_exposure=false
+process/size_limit=0
+detect_3d/compress_to=1

client/assets/sprites/wall_structural_south_64.png.import

@@ -0,0 +1,40 @@
+[remap]
+
+importer="texture"
+type="CompressedTexture2D"
+uid="uid://cctlhvaolom3x"
+path="res://.godot/imported/wall_structural_south_64.png-c34925f9a5a3f6b5968e73e51953367e.ctex"
+metadata={
+"vram_texture": false
+}
+
+[deps]
+
+source_file="res://assets/sprites/wall_structural_south_64.png"
+dest_files=["res://.godot/imported/wall_structural_south_64.png-c34925f9a5a3f6b5968e73e51953367e.ctex"]
+
+[params]
+
+compress/mode=0
+compress/high_quality=false
+compress/lossy_quality=0.7
+compress/uastc_level=0
+compress/rdo_quality_loss=0.0
+compress/hdr_compression=1
+compress/normal_map=0
+compress/channel_pack=0
+mipmaps/generate=false
+mipmaps/limit=-1
+roughness/mode=0
+roughness/src_normal=""
+process/channel_remap/red=0
+process/channel_remap/green=1
+process/channel_remap/blue=2
+process/channel_remap/alpha=3
+process/fix_alpha_border=true
+process/premult_alpha=false
+process/normal_map_invert_y=false
+process/hdr_as_srgb=false
+process/hdr_clamp_exposure=false
+process/size_limit=0
+detect_3d/compress_to=1

client/assets/sprites/wall_structural_west_64.png.import

@@ -0,0 +1,40 @@
+[remap]
+
+importer="texture"
+type="CompressedTexture2D"
+uid="uid://ughjt5s8la2p"
+path="res://.godot/imported/wall_structural_west_64.png-7c39e0c692d32348190875c4ad99b227.ctex"
+metadata={
+"vram_texture": false
+}
+
+[deps]
+
+source_file="res://assets/sprites/wall_structural_west_64.png"
+dest_files=["res://.godot/imported/wall_structural_west_64.png-7c39e0c692d32348190875c4ad99b227.ctex"]
+
+[params]
+
+compress/mode=0
+compress/high_quality=false
+compress/lossy_quality=0.7
+compress/uastc_level=0
+compress/rdo_quality_loss=0.0
+compress/hdr_compression=1
+compress/normal_map=0
+compress/channel_pack=0
+mipmaps/generate=false
+mipmaps/limit=-1
+roughness/mode=0
+roughness/src_normal=""
+process/channel_remap/red=0
+process/channel_remap/green=1
+process/channel_remap/blue=2
+process/channel_remap/alpha=3
+process/fix_alpha_border=true
+process/premult_alpha=false
+process/normal_map_invert_y=false
+process/hdr_as_srgb=false
+process/hdr_clamp_exposure=false
+process/size_limit=0
+detect_3d/compress_to=1

client/data/dialogue-theme.yaml

@@ -0,0 +1,47 @@
+# Dialogue Log Theme — The Settled Reach
+#
+# Ticket: #535 | Sprint: 14
+# Colors and timing for the unified dialogue log panel.
+# Loaded by dialogue_box.gd at runtime.
+
+# ============================================================
+# PLAYER COLOR
+# Fixed color for the player's name in dialogue log entries.
+# ============================================================
+player_color: "#e0e8ff"
+
+# ============================================================
+# NPC COLOR PALETTE
+# 8 distinct colors for NPC names. Indexed by hash(npc_name) % 8.
+# Must be readable on a dark semi-transparent panel background.
+# ============================================================
+npc_colors:
+  0: "#4a9ebb"  # teal
+  1: "#6bc9a6"  # green
+  2: "#e8c547"  # amber
+  3: "#d49e5d"  # warm orange
+  4: "#b586d4"  # lavender
+  5: "#d45d5d"  # muted red
+  6: "#5daa7d"  # forest
+  7: "#7daccc"  # sky blue
+
+# ============================================================
+# TEXT COLORS
+# Arrow separator and speech text color.
+# ============================================================
+arrow_color: "#8890a0"
+speech_color: "#c8d0e0"
+
+# ============================================================
+# PASSIVE (OVERHEARD) OPACITY
+# Base opacity multiplier for non-player-centric lines.
+# 1.0 = full opacity, 0.0 = invisible.
+# ============================================================
+passive_opacity: 0.9
+
+# ============================================================
+# ENTRY TIMING
+# All entry types share the same lifetime and fade duration.
+# ============================================================
+entry_lifetime_seconds: 45.0
+entry_fade_seconds: 5.0

client/data/ui-strings.yaml

@@ -104,8 +104,12 @@ notifications:
 
   # System
   save_complete: "Progress saved."
+  load_complete: "Session restored."
+  save_failed: "Save failed."
+  load_failed: "Load failed."
   connection_lost: "Signal interrupted."
   connection_restored: "Signal restored."
+  loading: "Resuming..."
 
 # ============================================================
 # KNOWLEDGE PANEL LABELS
@@ -125,6 +129,17 @@ knowledge_panel:
   confidence_medium: "Likely"
   confidence_low: "Unconfirmed"
   confidence_rumor: "Hearsay"
+  # D-041 KnowledgeConfidence levels — displayed in journal panel
+  confidence_direct: "Confirmed"
+  confidence_knowsdetails: "Detailed"
+  confidence_knowsof: "Known"
+  confidence_suspects: "Unconfirmed"
+  # D-041 KnowledgeSource labels — displayed in journal panel
+  source_directobservation: "Observed"
+  source_toldby: "Told"
+  source_heard: "Overheard"
+  source_inferred: "Inferred"
+  source_background: "Prior"
 
 # ============================================================
 # TUTORIAL TEXT (DIEGETIC)
@@ -159,6 +174,8 @@ dialogue:
 menu:
   pause_title: "Paused"
   resume: "Resume"
+  new_game: "New Game"
+  continue: "Continue"
   settings: "Settings"
   save_game: "Save"
   load_game: "Load"
@@ -167,6 +184,9 @@ menu:
   confirm_quit: "Unsaved progress will be lost."
   confirm_yes: "Yes"
   confirm_no: "No"
+  load_game_browse: "LOAD GAME"
+  load_game_back: "BACK"
+  load_game_empty: "No saves found."
 
 settings:
   audio_volume: "Volume"
@@ -174,6 +194,12 @@ settings:
   text_speed: "Text Speed"
   fullscreen: "Fullscreen"
   language: "Language"
+  # #646: AI-Enhanced Dialogue toggle (D-138)
+  ai_section_header: "AI DIALOGUE"
+  ai_dialogue_toggle: "AI-Enhanced Dialogue"
+  ai_status_checking: "Speed not yet measured — will check on first enable."
+  ai_status_ram_marginal: "Low memory — performance may vary."
+  ai_battery_warning: "High battery usage"
 
 # ============================================================
 # CHARACTER SELECTION (if applicable in v0.1)
@@ -185,3 +211,10 @@ character_select:
   detective_name: "Commission Investigator"
   detective_tagline: "The manifests don't add up. Someone in this district knows why."
   confirm: "Begin"
+  # #588: Card display strings — name, role, tone per archetype
+  smuggler_card_name: "Smuggler"
+  smuggler_card_role: "Freight logistics worker — Sova Transit"
+  smuggler_card_tone: "Insider access. Social camouflage. The ring is your daily life."
+  detective_card_name: "Detective"
+  detective_card_role: "Commission investigator — External assignment"
+  detective_card_tone: "Institutional authority. Analytical lattice. You were sent here."

client/icon.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="128" height="128"><rect width="128" height="128" fill="#1a1a2e"/></svg>

client/icon.svg.import

@@ -0,0 +1,43 @@
+[remap]
+
+importer="texture"
+type="CompressedTexture2D"
+uid="uid://caxeq5xayr0iy"
+path="res://.godot/imported/icon.svg-218a8f2b3041327d8a5756f3a245f83b.ctex"
+metadata={
+"vram_texture": false
+}
+
+[deps]
+
+source_file="res://icon.svg"
+dest_files=["res://.godot/imported/icon.svg-218a8f2b3041327d8a5756f3a245f83b.ctex"]
+
+[params]
+
+compress/mode=0
+compress/high_quality=false
+compress/lossy_quality=0.7
+compress/uastc_level=0
+compress/rdo_quality_loss=0.0
+compress/hdr_compression=1
+compress/normal_map=0
+compress/channel_pack=0
+mipmaps/generate=false
+mipmaps/limit=-1
+roughness/mode=0
+roughness/src_normal=""
+process/channel_remap/red=0
+process/channel_remap/green=1
+process/channel_remap/blue=2
+process/channel_remap/alpha=3
+process/fix_alpha_border=true
+process/premult_alpha=false
+process/normal_map_invert_y=false
+process/hdr_as_srgb=false
+process/hdr_clamp_exposure=false
+process/size_limit=0
+detect_3d/compress_to=1
+svg/scale=1.0
+editor/scale_with_editor_scale=false
+editor/convert_colors_with_editor_theme=false

client/project.godot

@@ -11,18 +11,24 @@ config_version=5
 [application]
 
 config/name="The Settled Reach"
-run/main_scene="res://scenes/main.tscn"
+run/main_scene="res://scenes/main_menu.tscn"
 config/features=PackedStringArray("4.6", "GL Compatibility")
 config/icon="res://icon.svg"
 
 [autoload]
 
+; PlatformInfo MUST remain first — HardwareDetector (and other autoloads) depend on it
+; being initialised before their own _ready() runs. Do not reorder.
+PlatformInfo="*res://scripts/autoloads/platform_info.gd"
+Protocol="*res://scripts/protocol/protocol.gd"
 SimBridge="*res://scripts/autoloads/sim_bridge.gd"
 GameState="*res://scripts/autoloads/game_state.gd"
 InputMapper="*res://scripts/autoloads/input_mapper.gd"
 UIStrings="*res://scripts/autoloads/ui_strings.gd"
 FogState="*res://scripts/autoloads/fog_state.gd"
 AudioManager="*res://scripts/autoloads/audio_manager.gd"
+SessionManager="*res://scripts/autoloads/session_manager.gd"
+HardwareDetector="*res://ui/hardware_detector.gd"
 
 [audio]
 
@@ -120,11 +126,31 @@ bug_report={
 "events": [Object(InputEventKey,"resource_local_to_scene":false,"resource_name":"","device":-1,"window_id":0,"alt_pressed":false,"shift_pressed":false,"ctrl_pressed":false,"meta_pressed":false,"pressed":false,"keycode":0,"physical_keycode":4194343,"key_label":0,"unicode":0,"location":0,"echo":false,"script":null)
 ]
 }
+debug_overlay={
+"deadzone": 0.5,
+"events": [Object(InputEventKey,"resource_local_to_scene":false,"resource_name":"","device":-1,"window_id":0,"alt_pressed":false,"shift_pressed":false,"ctrl_pressed":false,"meta_pressed":false,"pressed":false,"keycode":0,"physical_keycode":4194334,"key_label":0,"unicode":0,"location":0,"echo":false,"script":null)
+]
+}
+open_journal={
+"deadzone": 0.5,
+"events": [Object(InputEventKey,"resource_local_to_scene":false,"resource_name":"","device":-1,"window_id":0,"alt_pressed":false,"shift_pressed":false,"ctrl_pressed":false,"meta_pressed":false,"pressed":false,"keycode":0,"physical_keycode":74,"key_label":0,"unicode":106,"location":0,"echo":false,"script":null)
+]
+}
 teleport_hub={
 "deadzone": 0.5,
 "events": [Object(InputEventKey,"resource_local_to_scene":false,"resource_name":"","device":-1,"window_id":0,"alt_pressed":false,"shift_pressed":false,"ctrl_pressed":false,"meta_pressed":false,"pressed":false,"keycode":0,"physical_keycode":4194317,"key_label":0,"unicode":0,"location":0,"echo":false,"script":null)
 ]
 }
+quicksave={
+"deadzone": 0.5,
+"events": [Object(InputEventKey,"resource_local_to_scene":false,"resource_name":"","device":-1,"window_id":0,"alt_pressed":false,"shift_pressed":false,"ctrl_pressed":false,"meta_pressed":false,"pressed":false,"keycode":0,"physical_keycode":4194336,"key_label":0,"unicode":0,"location":0,"echo":false,"script":null)
+]
+}
+quickload={
+"deadzone": 0.5,
+"events": [Object(InputEventKey,"resource_local_to_scene":false,"resource_name":"","device":-1,"window_id":0,"alt_pressed":false,"shift_pressed":false,"ctrl_pressed":false,"meta_pressed":false,"pressed":false,"keycode":0,"physical_keycode":4194337,"key_label":0,"unicode":0,"location":0,"echo":false,"script":null)
+]
+}
 
 [rendering]
 

client/scenes/character_select.tscn

@@ -0,0 +1,189 @@
+[gd_scene load_steps=2 format=3 uid="uid://char_select_scene_sr"]
+
+[ext_resource type="Script" path="res://ui/character_select.gd" id="1_charselect"]
+
+; #588: Character archetype select — two-card overlay between New Game and main.tscn.
+; Keyboard: left/right to pick, Enter to confirm, ESC to cancel (no save dir created).
+
+[node name="CharacterSelect" type="Control"]
+layout_mode = 3
+anchors_preset = 15
+anchor_right = 1.0
+anchor_bottom = 1.0
+script = ExtResource("1_charselect")
+
+[node name="Background" type="ColorRect" parent="."]
+layout_mode = 1
+anchors_preset = 15
+anchor_right = 1.0
+anchor_bottom = 1.0
+color = Color(0.04, 0.04, 0.07, 0.97)
+mouse_filter = 2
+
+[node name="TitleLabel" type="Label" parent="."]
+layout_mode = 1
+anchor_left = 0.5
+anchor_right = 0.5
+offset_left = -200.0
+offset_top = 100.0
+offset_right = 200.0
+offset_bottom = 126.0
+grow_horizontal = 2
+text = "Choose your perspective."
+horizontal_alignment = 1
+theme_override_font_sizes/font_size = 16
+theme_override_colors/font_color = Color(0.784, 0.816, 0.878, 1.0)
+
+[node name="Cards" type="HBoxContainer" parent="."]
+layout_mode = 1
+anchors_preset = 8
+anchor_left = 0.5
+anchor_top = 0.5
+anchor_right = 0.5
+anchor_bottom = 0.5
+offset_left = -316.0
+offset_top = -110.0
+offset_right = 316.0
+offset_bottom = 140.0
+grow_horizontal = 2
+grow_vertical = 2
+theme_override_constants/separation = 24
+alignment = 1
+
+; --- Smuggler card ---
+
+[node name="CardSmugglerWrapper" type="Control" parent="Cards"]
+layout_mode = 2
+custom_minimum_size = Vector2(280, 240)
+mouse_filter = 0
+
+[node name="CardBorder" type="ColorRect" parent="Cards/CardSmugglerWrapper"]
+layout_mode = 1
+anchors_preset = 15
+anchor_right = 1.0
+anchor_bottom = 1.0
+color = Color(0.18, 0.22, 0.28, 1.0)
+mouse_filter = 2
+
+[node name="CardInner" type="ColorRect" parent="Cards/CardSmugglerWrapper"]
+layout_mode = 1
+anchor_right = 1.0
+anchor_bottom = 1.0
+offset_left = 2.0
+offset_top = 2.0
+offset_right = -2.0
+offset_bottom = -2.0
+color = Color(0.07, 0.07, 0.10, 1.0)
+mouse_filter = 2
+
+[node name="VBox" type="VBoxContainer" parent="Cards/CardSmugglerWrapper/CardInner"]
+layout_mode = 1
+anchors_preset = 15
+anchor_right = 1.0
+anchor_bottom = 1.0
+offset_left = 20.0
+offset_top = 20.0
+offset_right = -20.0
+offset_bottom = -20.0
+theme_override_constants/separation = 10
+
+[node name="NameLabel" type="Label" parent="Cards/CardSmugglerWrapper/CardInner/VBox"]
+layout_mode = 2
+text = "Smuggler"
+theme_override_font_sizes/font_size = 26
+theme_override_colors/font_color = Color(0.906, 0.773, 0.278, 1.0)
+
+[node name="RoleLabel" type="Label" parent="Cards/CardSmugglerWrapper/CardInner/VBox"]
+layout_mode = 2
+text = "Freight logistics worker — Sova Transit"
+autowrap_mode = 2
+theme_override_font_sizes/font_size = 13
+theme_override_colors/font_color = Color(0.533, 0.565, 0.627, 1.0)
+
+[node name="Divider" type="Control" parent="Cards/CardSmugglerWrapper/CardInner/VBox"]
+layout_mode = 2
+custom_minimum_size = Vector2(0, 12)
+
+[node name="ToneLabel" type="Label" parent="Cards/CardSmugglerWrapper/CardInner/VBox"]
+layout_mode = 2
+text = "Insider access. Social camouflage. The ring is your daily life."
+autowrap_mode = 2
+theme_override_font_sizes/font_size = 12
+theme_override_colors/font_color = Color(0.416, 0.447, 0.510, 1.0)
+
+; --- Detective card ---
+
+[node name="CardDetectiveWrapper" type="Control" parent="Cards"]
+layout_mode = 2
+custom_minimum_size = Vector2(280, 240)
+mouse_filter = 0
+
+[node name="CardBorder" type="ColorRect" parent="Cards/CardDetectiveWrapper"]
+layout_mode = 1
+anchors_preset = 15
+anchor_right = 1.0
+anchor_bottom = 1.0
+color = Color(0.18, 0.22, 0.28, 1.0)
+mouse_filter = 2
+
+[node name="CardInner" type="ColorRect" parent="Cards/CardDetectiveWrapper"]
+layout_mode = 1
+anchor_right = 1.0
+anchor_bottom = 1.0
+offset_left = 2.0
+offset_top = 2.0
+offset_right = -2.0
+offset_bottom = -2.0
+color = Color(0.07, 0.07, 0.10, 1.0)
+mouse_filter = 2
+
+[node name="VBox" type="VBoxContainer" parent="Cards/CardDetectiveWrapper/CardInner"]
+layout_mode = 1
+anchors_preset = 15
+anchor_right = 1.0
+anchor_bottom = 1.0
+offset_left = 20.0
+offset_top = 20.0
+offset_right = -20.0
+offset_bottom = -20.0
+theme_override_constants/separation = 10
+
+[node name="NameLabel" type="Label" parent="Cards/CardDetectiveWrapper/CardInner/VBox"]
+layout_mode = 2
+text = "Detective"
+theme_override_font_sizes/font_size = 26
+theme_override_colors/font_color = Color(0.906, 0.773, 0.278, 1.0)
+
+[node name="RoleLabel" type="Label" parent="Cards/CardDetectiveWrapper/CardInner/VBox"]
+layout_mode = 2
+text = "Commission investigator — External assignment"
+autowrap_mode = 2
+theme_override_font_sizes/font_size = 13
+theme_override_colors/font_color = Color(0.533, 0.565, 0.627, 1.0)
+
+[node name="Divider" type="Control" parent="Cards/CardDetectiveWrapper/CardInner/VBox"]
+layout_mode = 2
+custom_minimum_size = Vector2(0, 12)
+
+[node name="ToneLabel" type="Label" parent="Cards/CardDetectiveWrapper/CardInner/VBox"]
+layout_mode = 2
+text = "Institutional authority. Analytical lattice. You were sent here."
+autowrap_mode = 2
+theme_override_font_sizes/font_size = 12
+theme_override_colors/font_color = Color(0.416, 0.447, 0.510, 1.0)
+
+[node name="ConfirmBtn" type="Button" parent="."]
+layout_mode = 1
+anchor_left = 0.5
+anchor_top = 1.0
+anchor_right = 0.5
+anchor_bottom = 1.0
+offset_left = -60.0
+offset_top = -80.0
+offset_right = 60.0
+offset_bottom = -50.0
+grow_horizontal = 2
+grow_vertical = 0
+text = "Begin"
+theme_override_font_sizes/font_size = 15
+theme_override_colors/font_color = Color(0.906, 0.773, 0.278, 1.0)

client/scenes/main.tscn

@@ -1,4 +1,4 @@
-[gd_scene load_steps=22 format=3 uid="uid://bswrmh7w8dbgm"]
+[gd_scene load_steps=29 format=3 uid="uid://bswrmh7w8dbgm"]
 
 [ext_resource type="Script" path="res://scripts/main.gd" id="1_main"]
 [ext_resource type="Script" path="res://scripts/rendering/world_renderer.gd" id="2_world"]
@@ -21,6 +21,13 @@
 [ext_resource type="PackedScene" path="res://ui/checklist_overlay.tscn" id="18_checklist"]
 [ext_resource type="PackedScene" path="res://ui/bug_report_dialog.tscn" id="19_bugreport"]
 [ext_resource type="PackedScene" path="res://ui/settings_dialog.tscn" id="21_settings"]
+[ext_resource type="Script" path="res://ui/debug_overlay.gd" id="22_debug"]
+[ext_resource type="PackedScene" path="res://ui/time_display.tscn" id="23_tdisplay"]
+[ext_resource type="PackedScene" path="res://ui/examine_display.tscn" id="24_examine"]
+[ext_resource type="PackedScene" path="res://ui/journal_panel.tscn" id="25_journal"]
+[ext_resource type="PackedScene" path="res://ui/loading_screen.tscn" id="26_loading"]
+[ext_resource type="PackedScene" uid="uid://b2ndm9rvx8cqp" path="res://ui/debug_console.tscn" id="27_debug_console"]
+[ext_resource type="PackedScene" uid="uid://news_ticker_scene_sr" path="res://ui/news_ticker.tscn" id="28_newsticker"]
 
 [node name="Game" type="Node2D"]
 script = ExtResource("1_main")
@@ -117,6 +124,9 @@ zoom = Vector2(2, 2)
 [node name="InsertOverlay" type="CanvasLayer" parent="."]
 layer = 10
 
+; #263: Time display — diegetic insert clock, top-left placeholder (D-013, D-031)
+[node name="TimeDisplay" parent="InsertOverlay" instance=ExtResource("23_tdisplay")]
+
 ; InteractionPrompt — v0.1 fallback single-line "E - Talk" display
 [node name="InteractionPrompt" parent="InsertOverlay" instance=ExtResource("9_prompt")]
 
@@ -129,6 +139,15 @@ layer = 10
 ; D-061: Dialogue box — bottom screen, max 20% height, diegetic insert UI
 [node name="DialogueBox" parent="InsertOverlay" instance=ExtResource("15_dialogue")]
 
+; #151: Minimap — diegetic insert overlay, top-right, 160px circle (D-013, D-049 z-layer 6)
+[node name="Minimap" parent="InsertOverlay" instance=ExtResource("7_minimap")]
+
+; #174: Examine result — non-interactive observe text overlay, auto-dismisses 5s (D-061 adjacent)
+[node name="ExamineDisplay" parent="InsertOverlay" instance=ExtResource("24_examine")]
+
+; #264: Journal panel — knowledge graph review, toggle J key, read-only (D-041)
+[node name="JournalPanel" parent="InsertOverlay" instance=ExtResource("25_journal")]
+
 ; --- UI layer (CanvasLayer 20) ---
 ; HUD, monologue, cursor — always visible, not affected by fog or camera.
 [node name="UILayer" type="CanvasLayer" parent="."]
@@ -136,8 +155,6 @@ layer = 20
 
 [node name="HUD" parent="UILayer" instance=ExtResource("6_hud")]
 
-[node name="Minimap" parent="UILayer" instance=ExtResource("7_minimap")]
-
 [node name="MonologueDisplay" parent="UILayer" instance=ExtResource("8_monologue")]
 
 ; D-053: Stance indicator — top-right, color-coded
@@ -152,6 +169,19 @@ layer = 20
 ; D-065: Inventory grid — 3x3, bottom-right, 40x40px, 1-9 hotkeys
 [node name="InventoryGrid" parent="UILayer" instance=ExtResource("12_inv")]
 
+; #511: F3 debug overlay — real-time game state, toggled by F3
+[node name="DebugOverlay" type="Control" parent="UILayer"]
+anchors_preset = 0
+offset_left = 16
+offset_top = 120
+offset_right = 400
+offset_bottom = 400
+mouse_filter = 2
+script = ExtResource("22_debug")
+
+; #592: News ticker — scrolling headline bar, visible in bar zone only (D-049 z-layer 7)
+[node name="NewsTicker" parent="UILayer" instance=ExtResource("28_newsticker")]
+
 ; D-056: Cursor state machine — insert-styled geometric cursor, topmost in UILayer
 [node name="CursorRenderer" type="Node2D" parent="UILayer"]
 script = ExtResource("10_cursor")
@@ -166,3 +196,9 @@ layer = 30
 
 ; #528: Audio settings dialog — 5-bus volume sliders, ESC/OPEN_MENU to toggle
 [node name="SettingsDialog" parent="ModalLayer" instance=ExtResource("21_settings")]
+
+; #257: Loading screen — full-screen overlay during save/load round-trip
+[node name="LoadingScreen" parent="ModalLayer" instance=ExtResource("26_loading")]
+
+; #581: Debug console — tilde key toggles, bottom 40% of screen
+[node name="DebugConsole" parent="ModalLayer" instance=ExtResource("27_debug_console")]

client/scenes/main_menu.tscn

@@ -0,0 +1,124 @@
+[gd_scene load_steps=2 format=3 uid="uid://main_menu_sr"]
+
+[ext_resource type="Script" path="res://ui/main_menu.gd" id="1_mainmenu"]
+
+; Main menu — New Game / Continue / Quit.
+; #258: D-085 per-game save directory created on New Game.
+
+[node name="MainMenu" type="Control"]
+layout_mode = 3
+anchors_preset = 15
+anchor_right = 1.0
+anchor_bottom = 1.0
+script = ExtResource("1_mainmenu")
+
+[node name="Background" type="ColorRect" parent="."]
+layout_mode = 1
+anchors_preset = 15
+anchor_right = 1.0
+anchor_bottom = 1.0
+color = Color(0.05, 0.05, 0.08, 1.0)
+mouse_filter = 2
+
+[node name="VBox" type="VBoxContainer" parent="."]
+layout_mode = 1
+anchors_preset = 8
+anchor_left = 0.5
+anchor_top = 0.5
+anchor_right = 0.5
+anchor_bottom = 0.5
+offset_left = -120.0
+offset_top = -80.0
+offset_right = 120.0
+offset_bottom = 100.0
+grow_horizontal = 2
+grow_vertical = 2
+theme_override_constants/separation = 16
+alignment = 1
+
+[node name="TitleLabel" type="Label" parent="VBox"]
+layout_mode = 2
+text = "THE SETTLED REACH"
+horizontal_alignment = 1
+theme_override_font_sizes/font_size = 36
+theme_override_colors/font_color = Color(0.784, 0.816, 0.878, 1.0)
+
+[node name="Spacer" type="Control" parent="VBox"]
+layout_mode = 2
+custom_minimum_size = Vector2(0, 24)
+
+[node name="NewGameBtn" type="Button" parent="VBox"]
+layout_mode = 2
+text = "NEW GAME"
+theme_override_font_sizes/font_size = 15
+theme_override_colors/font_color = Color(0.906, 0.773, 0.278, 1.0)
+
+[node name="ContinueBtn" type="Button" parent="VBox"]
+layout_mode = 2
+text = "CONTINUE"
+theme_override_font_sizes/font_size = 15
+theme_override_colors/font_color = Color(0.906, 0.773, 0.278, 1.0)
+
+[node name="LoadGameBtn" type="Button" parent="VBox"]
+layout_mode = 2
+text = "LOAD GAME"
+theme_override_font_sizes/font_size = 15
+theme_override_colors/font_color = Color(0.906, 0.773, 0.278, 1.0)
+
+[node name="QuitBtn" type="Button" parent="VBox"]
+layout_mode = 2
+text = "QUIT"
+theme_override_font_sizes/font_size = 15
+theme_override_colors/font_color = Color(0.533, 0.565, 0.627, 1.0)
+
+[node name="LoadGamePanel" type="Control" parent="."]
+layout_mode = 1
+anchors_preset = 15
+anchor_right = 1.0
+anchor_bottom = 1.0
+visible = false
+
+[node name="PanelBg" type="ColorRect" parent="LoadGamePanel"]
+layout_mode = 1
+anchors_preset = 15
+anchor_right = 1.0
+anchor_bottom = 1.0
+color = Color(0.05, 0.05, 0.08, 0.96)
+mouse_filter = 2
+
+[node name="VBox" type="VBoxContainer" parent="LoadGamePanel"]
+layout_mode = 1
+anchors_preset = 8
+anchor_left = 0.5
+anchor_top = 0.5
+anchor_right = 0.5
+anchor_bottom = 0.5
+offset_left = -160.0
+offset_top = -180.0
+offset_right = 160.0
+offset_bottom = 180.0
+grow_horizontal = 2
+grow_vertical = 2
+theme_override_constants/separation = 12
+
+[node name="TitleLabel" type="Label" parent="LoadGamePanel/VBox"]
+layout_mode = 2
+text = "LOAD GAME"
+horizontal_alignment = 1
+theme_override_font_sizes/font_size = 20
+theme_override_colors/font_color = Color(0.784, 0.816, 0.878, 1.0)
+
+[node name="SavesScroll" type="ScrollContainer" parent="LoadGamePanel/VBox"]
+layout_mode = 2
+custom_minimum_size = Vector2(320, 240)
+
+[node name="SavesList" type="VBoxContainer" parent="LoadGamePanel/VBox/SavesScroll"]
+layout_mode = 2
+size_flags_horizontal = 3
+theme_override_constants/separation = 8
+
+[node name="BackBtn" type="Button" parent="LoadGamePanel/VBox"]
+layout_mode = 2
+text = "BACK"
+theme_override_font_sizes/font_size = 14
+theme_override_colors/font_color = Color(0.533, 0.565, 0.627, 1.0)

client/scripts/autoloads/audio_manager.gd

@@ -10,6 +10,11 @@ extends Node
 # Matches sfx_monologue_chime.ogg from D-038 — "neural lattice firing" feel.
 const CHIME_RECOGNITION := "sfx_monologue_chime"
 
+# --- D-067: Triangle activation chime (#590, D-072/D-089) ---
+# Fires once per session when the triangle's tell_state shifts to RoutineDeviation.
+# Sharper variant (D-067: "contradiction/anomaly") — sfx_monologue_chime_urgent.ogg.
+const CHIME_ACTIVATION := "sfx_monologue_chime_urgent"
+
 # --- Bus names (D-068) ---
 const BUS_MUSIC := "Music"
 const BUS_AMBIENT := "Ambient"
@@ -44,7 +49,7 @@ const FILTER_CUTOFF_DEFAULT := 20500.0
 # --- D-073: Zone crossfade constants ---
 const CROSSFADE_DURATION := 1.8  # D-073: 1.5-2s spec, mid-range
 
-# Maps server zone_id strings to ambient asset keys (filenames in res://audio/).
+# Maps server zone_id strings to ambient asset keys (filenames in res://assets/audio/).
 # Hub and Workplace intentionally share the same ambient layer (amb_hub_layer) —
 # they are the same location type, so hub→workplace transition is a same-asset no-op
 # (old_asset != new_asset guard skips the fade-out). Sprint brief consolidates
@@ -112,15 +117,15 @@ func _setup_buses() -> void:
 # --- Asset registry (D-068 directory-scan pattern) ---
 
 func _scan_registry() -> void:
-	_scan_dir("res://audio/")
+	_scan_dir("res://assets/audio/")
 	print("AudioManager: %d assets registered" % _registry.size())
 
 
 func _scan_dir(path: String) -> void:
 	var dir := DirAccess.open(path)
 	if dir == null:
-		if path == "res://audio/":
-			print("AudioManager: res://audio/ not found — all play methods no-op")
+		if path == "res://assets/audio/":
+			print("AudioManager: res://assets/audio/ not found — all play methods no-op")
 		return
 	dir.list_dir_begin()
 	var file_name := dir.get_next()
@@ -197,7 +202,7 @@ func stop_all_loops() -> void:
 
 # --- Audio asset registry: event type → asset key (D-018, #125) ---
 # Maps server-sent sound event_type strings to audio asset keys.
-# Keys match filename stems in res://audio/ (scanned by _scan_registry).
+# Keys match filename stems in res://assets/audio/ (scanned by _scan_registry).
 # Audio assets per D-038: footstep variants (walk / run), NPC murmur (D-072, #532).
 # Missing assets no-op gracefully (D-038 fallback pattern).
 const SOUND_EVENT_ASSETS: Dictionary = {

client/scripts/autoloads/fog_state.gd

@@ -8,13 +8,29 @@ extends Node
 # Used by fog shader to distinguish visual treatment per tile.
 # Test assertions reference these: assert_that(byte).is_equal(FogState.VIS_FORWARD)
 const VIS_HIDDEN: int = 0        # Not in LOS — fully fogged
-const VIS_PERIPHERAL: int = 180  # In LOS, peripheral sector — light fog dimming
+const VIS_PERIPHERAL: int = 180  # DEPRECATED: peripheral sector removed in Sprint 22 (#569). Retained — tests still reference it.
 const VIS_FORWARD: int = 255     # In LOS, forward sector — clear vision
 
 const EXP_UNEXPLORED: int = 0   # Never seen — total darkness
 const EXP_EXPLORED: int = 128   # Previously seen, now out of LOS — deep fog
 const EXP_VISIBLE: int = 255    # Currently in LOS — clear (written each frame)
 
+# Zone temperature tints (D-059 + D-046, Sprint 22) — keyed by zone_id string from server.
+# Matches audio_manager.gd ZONE_ASSETS zone_id strings for consistent zone semantics.
+# Low saturation is intentional (D-046): tints are subtle — distinguishable as warm/cool/neutral
+# in side-by-side comparison, not garish. The "Hopper test" validates this.
+# Colors are dark tints used as the fog overlay in the deep fog zone:
+#   hub/workplace: #1a1f2e (cool blue-dark — terminal, institutional)
+#   bar:           #2a1f15 (warm amber-dark — social, inhabited)
+#   corridor:      #1a1a1a (neutral dark — transitional, maintenance)
+const ZONE_TINTS: Dictionary = {
+	"hub":       Color(0.102, 0.122, 0.180),  # #1a1f2e — cool blue-dark
+	"workplace": Color(0.102, 0.122, 0.180),  # same as hub
+	"bar":       Color(0.165, 0.122, 0.082),  # #2a1f15 — warm amber-dark
+	"corridor":  Color(0.102, 0.102, 0.102),  # #1a1a1a — neutral dark
+}
+const ZONE_TINT_DEFAULT: Color = Color(0.102, 0.102, 0.102)  # #1a1a1a neutral
+
 var map_bounds: Rect2i = Rect2i(0, 0, 1, 1)
 var visibility_texture: ImageTexture
 var exploration_texture: ImageTexture
@@ -25,16 +41,34 @@ var _exp_bytes: PackedByteArray
 var _vis_image: Image
 var _exp_image: Image
 var _tint_image: Image
+# Zone tint stored as 3-channel RGB bytes (R, G, B per pixel) for preservation across resizes
+var _tint_bytes: PackedByteArray
 var _width: int = 1
 var _height: int = 1
 var _prev_visible: Dictionary = {}  # Tiles visible last frame (for incremental decay)
 
+## Debug flag — when true, fog.gdshader renders raw exploration texture
+## as colored overlay (green=visible, blue=explored, red=unexplored).
+## Toggle via FogState.debug_exploration = true in the console.
+var debug_exploration: bool = false
+
+## Deterministic shader time for visual test captures.
+## When >= 0, fog_shader.gd uses this instead of Time.get_ticks_msec().
+## Set before settle frames so noise phase is reproducible across runs.
+var override_time: float = -1.0
+
 
 func _ready() -> void:
 	_resize(Rect2i(0, 0, 64, 64))
 
 
 func _resize(bounds: Rect2i) -> void:
+	var old_bounds := map_bounds
+	var old_exp := _exp_bytes
+	var old_tint := _tint_bytes  # empty on first call (_ready); guard at line 104 skips copy
+	var old_w := _width
+	var old_h := _height
+
 	map_bounds = bounds
 	_width = maxi(bounds.size.x, 1)
 	_height = maxi(bounds.size.y, 1)
@@ -49,41 +83,92 @@ func _resize(bounds: Rect2i) -> void:
 	_exp_bytes = PackedByteArray()
 	_exp_bytes.resize(sz)
 	_exp_bytes.fill(EXP_UNEXPLORED)
+	# Preserve exploration data from old bounds into new bounds
+	if old_exp.size() > 0 and old_w > 0 and old_h > 0:
+		var dx: int = old_bounds.position.x - bounds.position.x
+		var dy: int = old_bounds.position.y - bounds.position.y
+		for oy in range(old_h):
+			var ny: int = oy + dy
+			if ny < 0 or ny >= _height:
+				continue
+			for ox in range(old_w):
+				var nx: int = ox + dx
+				if nx < 0 or nx >= _width:
+					continue
+				var old_val: int = old_exp[oy * old_w + ox]
+				if old_val > EXP_UNEXPLORED:
+					_exp_bytes[ny * _width + nx] = old_val
 	_exp_image = Image.create_from_data(_width, _height, false, Image.FORMAT_R8, _exp_bytes)
 	exploration_texture = ImageTexture.create_from_image(_exp_image)
 
-	# Zone tint — neutral dark for Sprint 6 (zone metadata deferred)
-	_tint_image = Image.create(_width, _height, false, Image.FORMAT_RGB8)
-	_tint_image.fill(Color(0.05, 0.05, 0.08))
+	# Zone tint — 3 bytes per pixel (RGB), default neutral dark
+	var tint_sz := sz * 3
+	_tint_bytes = PackedByteArray()
+	_tint_bytes.resize(tint_sz)
+	var default_r := int(ZONE_TINT_DEFAULT.r * 255.0)
+	var default_g := int(ZONE_TINT_DEFAULT.g * 255.0)
+	var default_b := int(ZONE_TINT_DEFAULT.b * 255.0)
+	for i in range(sz):
+		_tint_bytes[i * 3 + 0] = default_r
+		_tint_bytes[i * 3 + 1] = default_g
+		_tint_bytes[i * 3 + 2] = default_b
+	# Preserve zone tint data from old bounds (zone tints are stable — tile zone never changes)
+	if old_tint.size() > 0 and old_w > 0 and old_h > 0:
+		var dx: int = old_bounds.position.x - bounds.position.x
+		var dy: int = old_bounds.position.y - bounds.position.y
+		for oy in range(old_h):
+			var ny: int = oy + dy
+			if ny < 0 or ny >= _height:
+				continue
+			for ox in range(old_w):
+				var nx: int = ox + dx
+				if nx < 0 or nx >= _width:
+					continue
+				var old_idx := (oy * old_w + ox) * 3
+				var new_idx := (ny * _width + nx) * 3
+				_tint_bytes[new_idx + 0] = old_tint[old_idx + 0]
+				_tint_bytes[new_idx + 1] = old_tint[old_idx + 1]
+				_tint_bytes[new_idx + 2] = old_tint[old_idx + 2]
+	_tint_image = Image.create_from_data(_width, _height, false, Image.FORMAT_RGB8, _tint_bytes)
 	zone_tint_texture = ImageTexture.create_from_image(_tint_image)
 
 	_prev_visible.clear()
 
 
 func update_from_state() -> void:
-	# Resize if map bounds changed
-	var tiles := GameState.visible_tiles
-	if tiles.size() > 0:
-		var new_bounds := _compute_bounds(tiles)
+	# Grow bounds to include newly visible tiles — never shrink, so explored
+	# tiles behind the player stay in the texture and render as deep fog
+	# instead of black. Exploration data is preserved across resizes.
+	# Use visible_positions (always populated from server snapshots) instead of
+	# visible_tiles, which stays empty in live server mode because the server
+	# sends tile_kind but game_state.gd's population check expects "type".
+	var positions: Dictionary = GameState.visible_positions
+	if positions.size() > 0:
+		var new_bounds := _grow_bounds_from_positions(positions)
 		if new_bounds != map_bounds:
 			_resize(new_bounds)
 
 	var ox: int = map_bounds.position.x
 	var oy: int = map_bounds.position.y
-	var positions: Dictionary = GameState.visible_positions
-	var sectors: Dictionary = GameState.visibility_sectors
 
 	# TODO(v0.2): gradual decay over game-time instead of immediate EXP_VISIBLE→EXP_EXPLORED
 
-	# 1. Clear visibility, then write current LOS
+	# 1. Clear visibility, then write current LOS (all tiles are Forward)
 	_vis_bytes.fill(VIS_HIDDEN)
 	for pos in positions:
 		var px: int = pos.x - ox
 		var py: int = pos.y - oy
 		if px < 0 or py < 0 or px >= _width or py >= _height:
 			continue
-		var sector: String = sectors.get(pos, "Forward")
-		_vis_bytes[py * _width + px] = VIS_FORWARD if sector == "Forward" else VIS_PERIPHERAL
+		_vis_bytes[py * _width + px] = VIS_FORWARD
+	# #585: BoundaryWall margin tiles — fog lifts so wall content composites correctly,
+	# but NOT in visible_positions so they don't persist as explored memory.
+	for pos in GameState.boundary_positions:
+		var px: int = pos.x - ox
+		var py: int = pos.y - oy
+		if px < 0 or py < 0 or px >= _width or py >= _height:
+			continue
+		_vis_bytes[py * _width + px] = VIS_FORWARD
 	_vis_image.set_data(_width, _height, false, Image.FORMAT_R8, _vis_bytes)
 	visibility_texture.update(_vis_image)
 
@@ -106,24 +191,58 @@ func update_from_state() -> void:
 	_exp_image.set_data(_width, _height, false, Image.FORMAT_R8, _exp_bytes)
 	exploration_texture.update(_exp_image)
 
+	# 3. Zone tint: write zone temperature color for currently visible tiles.
+	#    Zone data is stable (tile zone never changes) so we only write on first sight.
+	#    Data persists in _tint_bytes across frames and across resizes.
+	#    visible_tiles carries zone_id per tile (populated from snapshot "tiles" or
+	#    "visible_tiles" with type field — see game_state.gd apply_snapshot).
+	var tiles := GameState.visible_tiles
+	var tint_dirty := false
+	for tile in tiles:
+		if not tile is Dictionary or not tile.has("x") or not tile.has("y"):
+			continue
+		var zone_id: String = str(tile.get("zone_id", ""))
+		if zone_id.is_empty():
+			continue
+		var tint_color: Color = ZONE_TINTS.get(zone_id, ZONE_TINT_DEFAULT)
+		var px: int = int(tile.x) - ox
+		var py: int = int(tile.y) - oy
+		if px < 0 or py < 0 or px >= _width or py >= _height:
+			continue
+		var tint_idx := (py * _width + px) * 3
+		var new_r := int(tint_color.r * 255.0)
+		var new_g := int(tint_color.g * 255.0)
+		var new_b := int(tint_color.b * 255.0)
+		# Only update if different from current (avoid spurious texture uploads)
+		if _tint_bytes[tint_idx] != new_r or _tint_bytes[tint_idx + 1] != new_g or _tint_bytes[tint_idx + 2] != new_b:
+			_tint_bytes[tint_idx + 0] = new_r
+			_tint_bytes[tint_idx + 1] = new_g
+			_tint_bytes[tint_idx + 2] = new_b
+			tint_dirty = true
+	if tint_dirty:
+		_tint_image.set_data(_width, _height, false, Image.FORMAT_RGB8, _tint_bytes)
+		zone_tint_texture.update(_tint_image)
+
 	# Shallow copy — correct for Dictionary<Vector2i, bool/String> values
 	_prev_visible = positions.duplicate()
 
 
-func _compute_bounds(tiles: Array) -> Rect2i:
+func _grow_bounds_from_positions(positions: Dictionary) -> Rect2i:
+	## Compute bounds from visible_positions (Dictionary[Vector2i, bool]).
 	var min_x := 999999
 	var min_y := 999999
 	var max_x := -999999
 	var max_y := -999999
-	for tile in tiles:
-		if not tile is Dictionary or not tile.has("x") or not tile.has("y"):
-			continue
-		min_x = mini(min_x, int(tile.x))
-		min_y = mini(min_y, int(tile.y))
-		max_x = maxi(max_x, int(tile.x))
-		max_y = maxi(max_y, int(tile.y))
-	# Guard: all tiles invalid (no x/y) — sentinels would produce negative Rect2i
+	for pos in positions:
+		min_x = mini(min_x, pos.x)
+		min_y = mini(min_y, pos.y)
+		max_x = maxi(max_x, pos.x)
+		max_y = maxi(max_y, pos.y)
 	if min_x > max_x:
-		return Rect2i(0, 0, 1, 1)
-	# Margin for fog gradient bleed at edges
-	return Rect2i(min_x - 4, min_y - 4, max_x - min_x + 9, max_y - min_y + 9)
+		return map_bounds
+	var tile_bounds := Rect2i(min_x - 8, min_y - 8, max_x - min_x + 17, max_y - min_y + 17)
+	if map_bounds.size.x <= 1 and map_bounds.size.y <= 1:
+		return tile_bounds
+	return map_bounds.merge(tile_bounds)
+
+

client/scripts/autoloads/game_state.gd

@@ -1,14 +1,25 @@
 extends Node
 
+signal game_id_changed(new_id: String)
+
 # Updated each frame from ObserverSnapshot data (Protocol format: {tick, entities, tiles}).
 # Entities use Protocol decoded format: {entity_id, x, y, z, kind: {variant, data}}.
 # Tiles use format: [{x, y, z, type}].
 var current_snapshot: Dictionary = {}
+
+# D-085 (#258): Active game session identifier. Format: <YYYYMMDD>-<HHMMSS>-<hex6>
+# Set by SessionManager.new_game() or SessionManager.resume_game().
+# Empty string when no session is active (main menu state).
+var current_game_id: String = "":
+	set(v):
+		current_game_id = v
+		game_id_changed.emit(v)
 var current_tick: int = 0
 var player_position: Vector2 = Vector2.ZERO
 var visible_entities: Array = []
 var visible_tiles: Array = []
-var visible_positions: Dictionary = {}  # Vector2i -> true, for fast fog lookups
+var visible_positions: Dictionary = {}   # Vector2i -> true, for fast fog lookups (normal LOS tiles)
+var boundary_positions: Dictionary = {}  # Vector2i -> true, BoundaryWall margin tiles (#585) — visible in fog but not explored
 
 # v2 fields (D-015, D-031)
 var game_time: Dictionary = {}  # {day, time_of_day, day_phase, tick_rate} or empty
@@ -19,11 +30,20 @@ var visibility_sectors: Dictionary = {}  # Vector2i -> "Forward"/"Peripheral"
 # refined when the server assigns explicit player entity IDs).
 var player_entity_id: int = 1
 
+# #241: Follow target — entity_id of the NPC the player is following, -1 when not following.
+# Stub for server ticket #241 (Follow verb). Client reads this for camera/UI behavior.
+var follow_target_id: int = -1
+
 # v4 fields (#404/#405)
 var nearby_interactions: Array = []  # [{entity_id, entity_type, distance, verbs: [{kind, label, priority, available}]}]
 
 # v5 fields (#414)
-var current_monologue: Variant = null  # {id, text, duration_seconds} or null
+var current_monologue: Variant = null  # {id, text, duration_seconds, priority, is_urgent} or null
+
+# #122 (D-032): Character lattice profile — selects monologue text colour palette.
+# "lattice_augmented" = detective, "lattice_baseline" = smuggler.
+# Server sends this field as part of the player's capability snapshot.
+var lattice_profile: String = "lattice_baseline"
 
 # v6 fields (#449, D-053, D-065)
 var player_stance: String = "Walk"  # Sprint/Walk/Careful/Crouch
@@ -47,13 +67,72 @@ var gauntlet_mode: bool = false  # true when snapshot includes gauntlet_mode fla
 # the server's "insert_active" snapshot field, disabling all z-layer-6 UI.
 var insert_active: bool = true
 
+# #175: World seed for deterministic simulation (D-010, D-029).
+# Set by SessionManager.new_game(), sent to server via StartupMessage in SimBridge.
+# Same seed → same EntanglementConfig → same NPC population across playthroughs.
+# Persists for the session lifetime; not overwritten by apply_snapshot().
+var world_seed: int = 0
+
 # #507: RNG seed for replay determinism — populated from snapshot "rng_seed" field.
 # Null in v0.1 (server does not yet send this field; protocol change required).
 var rng_seed: Variant = null
 
+# v15 fields (#554, D-085): save/load result from server.
+# {success: bool, kind: "save"|"load", error: Variant} or null.
+# One-shot: consumed by main.gd after display, then set back to null.
+var save_result: Variant = null
+
+# v18 fields (#580): debug console response from server.
+# {command: String, text: String, success: bool} or null.
+# One-shot: consumed by main.gd and forwarded to DebugConsole, then set to null.
+var debug_response: Variant = null
+
+# #257: Pending load path — set by main menu "Load Game" selection.
+# main.gd sends LOAD_GAME on startup if non-empty, then clears this field.
+# Format: user://saves/<game-id>/<filename>.sav or "" if no pending load.
+var pending_load_path: String = ""
+
+# #588: Character archetype chosen at character select screen.
+# "detective" or "smuggler". Set before game scene loads; sent in StartupMessage.
+# Default: "detective" — fallback for legacy saves without character.txt.
+var character_archetype: String = "detective"
+
+# #646: AI-Enhanced Dialogue enabled state (D-138).
+# Runtime toggle — true means the LLM re-voicing pipeline should run (server-side).
+# Default: true (opt-out model per D-138 §8). Hardware detector may disable at startup
+# if RAM is insufficient. Persisted to server SQLite via ChangeSettings IPC.
+var ai_enhanced_dialogue_enabled: bool = true
+
+# v20 fields (#627, D-138): settings response from server.
+# One-shot: {kind: "full", settings: [{key, value}]} or {kind: "ack", success, key, error} or null.
+# "full" response hydrates ai_enhanced_dialogue_enabled (server is authoritative for persisted state).
+var settings_response: Variant = null
+
 # v7 fields (#431, D-059/D-060)
 var pending_recognitions: Array = []  # [{entity_id, x, y, z, remaining_ticks, total_delay_ticks}]
 
+# v8 fields (#305, D-028): NPC follow-up after player dialogue choice
+var dialogue_response: Variant = null  # {line_id, text, speaker_entity_id}
+
+# v9 fields (#535, D-078): Overheard NPC-to-NPC conversations
+var conversation_events: Array = []  # [{speaker_id, target_id, speaker_name, target_name, occluded_line}]
+var conversation_ended: Array = []  # [{speaker_id, target_id}]
+
+# v10 fields (#151, D-013): Discovered POIs from server (#148/#149).
+# Format: [{poi_id, name, x, y, z, category}]. Persists between snapshots unless
+# server explicitly sends an empty array (cleared locations are not typical in v0.1).
+# Populated from snapshot "poi_list" field — only updated when field present.
+var discovered_pois: Array = []
+
+# v14 fields (#174, #242): Character-filtered examine result.
+# {entity_id, text, confidence} or null. Auto-dismisses on client after 4-6 seconds.
+var current_examine_result: Variant = null
+
+# v14 fields (#264, D-041): Player knowledge graph dump for journal panel.
+# {entities: [{entity_id, name, confidence, source, state, relationship, last_observed_tick}],
+#  facts: [{fact_id, confidence, source, state, acquired_tick}]}
+var player_knowledge: Variant = null
+
 # #126, D-018: Medium-range sound events for fog-edge directional indicators.
 # Format: [{x, y, event_type, range_category}] — server sends current medium events per tick.
 var medium_sound_events: Array = []
@@ -63,14 +142,17 @@ var medium_sound_events: Array = []
 var close_sound_events: Array = []
 
 # D-071 (#530): Consecutive ticks without player position change.
-# Incremented per snapshot in apply_snapshot(). Reset to 0 on movement.
+# D-020: Server-authoritative — read from snapshot "stationary_ticks" field.
+# Fallback: client-side accumulation (deprecated, remove when server populates field).
 # ListeningFocus boost activates at 30+ ticks (main.gd manages the dip).
 var stationary_ticks: int = 0
+# DEPRECATED: Only used by client-side accumulation fallback. Remove with fallback.
 var _prev_player_position: Vector2 = Vector2(-1e9, -1e9)  # sentinel: no previous position
 
 # D-073 (#529): Server-authoritative zone_id from the player's current tile.
-# Extracted in apply_snapshot() — avoids O(N) tile scan in main.gd per Tyre review.
-# Empty string when zone_id field absent (server hasn't shipped OQ-09 yet).
+# D-020: Read directly from snapshot "zone_id" field.
+# Fallback: client-side tile lookup (deprecated, remove when server populates field).
+# Empty string when zone_id field absent.
 var current_zone_id: String = ""
 
 func apply_snapshot(snapshot: Dictionary) -> void:
@@ -94,12 +176,19 @@ func apply_snapshot(snapshot: Dictionary) -> void:
 			push_warning("GameState: no Player entity found in %d entities" % [
 				visible_entities.size()])
 
-	# D-071 (#530): Track consecutive stationary ticks for ListeningFocus boost.
-	# Compares current player_position against previous snapshot's position.
-	if player_position == _prev_player_position:
-		stationary_ticks += 1
+	# D-020/D-071 (#530): Server-authoritative stationary_ticks for ListeningFocus boost.
+	# Prefer server-sent value; fall back to client-side accumulation until server populates.
+	if snapshot.has("stationary_ticks") and snapshot.stationary_ticks is int:
+		# D-020: direct field assignment from server-authoritative snapshot.
+		stationary_ticks = snapshot.stationary_ticks
 	else:
-		stationary_ticks = 0
+		# DEPRECATED fallback — client-side accumulation. Remove when server sends
+		# "stationary_ticks" in ObserverSnapshot (D-020 violation: derives behavior-
+		# driving state on the client). Server tracks this in ListeningFocus component.
+		if player_position == _prev_player_position:
+			stationary_ticks += 1
+		else:
+			stationary_ticks = 0
 	_prev_player_position = player_position
 
 	# Tiles for rendering: test mode sends "tiles", live server sends tile data in "visible_tiles"
@@ -138,6 +227,10 @@ func apply_snapshot(snapshot: Dictionary) -> void:
 	else:
 		current_monologue = null
 
+	# #122: lattice_profile — character insert capability level for monologue colour
+	if snapshot.has("lattice_profile") and snapshot.lattice_profile is String:
+		lattice_profile = snapshot.lattice_profile
+
 	# v6: player_stance (#449, D-053)
 	if snapshot.has("player_stance") and snapshot.player_stance is String:
 		player_stance = snapshot.player_stance
@@ -160,6 +253,24 @@ func apply_snapshot(snapshot: Dictionary) -> void:
 	else:
 		pending_recognitions = []
 
+	# v9: conversation_events (#535, D-078) — overheard NPC-to-NPC lines
+	if snapshot.has("conversation_events") and snapshot.conversation_events is Array:
+		conversation_events = snapshot.conversation_events
+	else:
+		conversation_events = []
+
+	# v9: conversation_ended (#535, D-078) — pairs whose conversation ended
+	if snapshot.has("conversation_ended") and snapshot.conversation_ended is Array:
+		conversation_ended = snapshot.conversation_ended
+	else:
+		conversation_ended = []
+
+	# v8: dialogue_response (#305, D-028) — NPC follow-up after player choice
+	if snapshot.has("dialogue_response") and snapshot.dialogue_response is Dictionary:
+		dialogue_response = snapshot.dialogue_response
+	else:
+		dialogue_response = null
+
 	# v8: gauntlet mode (#496) — room_id and gauntlet_mode
 	if snapshot.has("gauntlet_mode") and snapshot.gauntlet_mode == true:
 		gauntlet_mode = true
@@ -202,29 +313,106 @@ func apply_snapshot(snapshot: Dictionary) -> void:
 		medium_sound_events = []
 		close_sound_events = []
 
-	# D-073 (#529): Extract zone_id from the player's current tile (server-authoritative).
-	# O(1) via visible_positions dict would be ideal, but tiles are arrays without
-	# positional indexing — use the same tile iteration below instead.
-	current_zone_id = ""
-	var _px := int(player_position.x)
-	var _py := int(player_position.y)
-	for _ztile in visible_tiles:
-		if _ztile is Dictionary and _ztile.get("x") == _px and _ztile.get("y") == _py:
-			current_zone_id = _ztile.get("zone_id", "")
-			break
+	# v10: discovered_pois (#151, D-013) — server sends POIs discovered by the player.
+	# Accepts "discovered_pois" or "poi_list" key — both map to the same client field.
+	# Only update if the field is present — absence means "no change since last tick".
+	if snapshot.has("discovered_pois") and snapshot.discovered_pois is Array:
+		discovered_pois = snapshot.discovered_pois
+	elif snapshot.has("poi_list") and snapshot.poi_list is Array:
+		discovered_pois = snapshot.poi_list
+
+	# v14: examine_result (#174, #242) — character-filtered observation from Examine verb.
+	if snapshot.has("examine_result") and snapshot.examine_result is Dictionary:
+		current_examine_result = snapshot.examine_result
+	else:
+		current_examine_result = null
+
+	# v15: save_result (#554, D-085) — one-shot save/load confirmation from server.
+	if snapshot.has("save_result") and snapshot.save_result is Dictionary:
+		save_result = snapshot.save_result
+	else:
+		save_result = null
+
+	# v18: debug_response (#580) — debug console command result.
+	if snapshot.has("debug_response") and snapshot.debug_response is Dictionary:
+		debug_response = snapshot.debug_response
+	else:
+		debug_response = null
+
+	# v20: settings_response (#627, D-138) — one-shot settings ack/dump from server.
+	# "full" kind → iterate settings array and hydrate matching fields.
+	if snapshot.has("settings_response") and snapshot.settings_response is Dictionary:
+		settings_response = snapshot.settings_response
+		var sr: Dictionary = snapshot.settings_response
+		if sr.get("kind") == "full":
+			var sr_settings: Variant = sr.get("settings")
+			if sr_settings is Array:
+				for entry in sr_settings:
+					if not entry is Dictionary:
+						continue
+					if entry.get("key") == "ai_dialogue.enabled":
+						var val: Variant = entry.get("value")
+						if val != null:
+							ai_enhanced_dialogue_enabled = _extract_bool_setting("ai_dialogue.enabled", val)
+	else:
+		settings_response = null
+
+	# v14: player_knowledge (#264, D-041) — partial KG dump for journal panel.
+	# Only update when field is present (null means no change, server sends when KG changes).
+	if snapshot.has("player_knowledge") and snapshot.player_knowledge is Dictionary:
+		player_knowledge = snapshot.player_knowledge
+
+	# D-020/D-073 (#529): Server-authoritative zone_id for zone ambient crossfade.
+	# Prefer server-sent top-level value; fall back to client-side tile lookup until
+	# server populates top-level "zone_id" in ObserverSnapshot.
+	if snapshot.has("zone_id") and snapshot.zone_id is String:
+		# D-020: direct field assignment from server-authoritative snapshot.
+		current_zone_id = snapshot.zone_id
+	else:
+		# DEPRECATED fallback — client-side tile lookup. Remove when server sends
+		# top-level "zone_id" in ObserverSnapshot (D-020 violation: derives zone
+		# identity on the client via tile iteration). Server sends zone_id per
+		# VisibleTile but not as a top-level snapshot field.
+		var _tile_by_coord: Dictionary = {}
+		for vtile in visible_tiles:
+			if vtile is Dictionary and vtile.has("x") and vtile.has("y"):
+				_tile_by_coord[Vector2i(vtile.x, vtile.y)] = vtile
+		var player_pos_key := Vector2i(int(player_position.x), int(player_position.y))
+		var player_tile = _tile_by_coord.get(player_pos_key, null)
+		current_zone_id = player_tile.get("zone_id", "") if player_tile else ""
 
 	# v2: visible_tiles with visibility sectors
-	# Derives visible_positions when not explicitly provided (real server mode)
+	# Derives visible_positions when not explicitly provided (real server mode).
+	# #585: BoundaryWall tiles go to boundary_positions — rendered in fog but not marked explored.
 	if snapshot.has("visible_tiles") and snapshot.visible_tiles is Array and snapshot.visible_tiles.size() > 0:
 		visibility_sectors.clear()
 		var has_explicit_positions := snapshot.has("visible_positions")
 		if not has_explicit_positions:
 			visible_positions.clear()
+		boundary_positions.clear()
 		for vtile in snapshot.visible_tiles:
 			if not vtile is Dictionary or not vtile.has("x") or not vtile.has("y"):
 				continue
 			var pos := Vector2i(vtile.x, vtile.y)
+			var vis_sector: String = vtile.get("visibility", "")
 			if vtile.has("visibility"):
-				visibility_sectors[pos] = vtile.visibility
-			if not has_explicit_positions:
+				visibility_sectors[pos] = vis_sector
+			# #585: BoundaryWall tiles are margin tiles visible through fog but not persistently
+			# explored — they don't update the player's exploration memory when they leave LOS.
+			if vis_sector == "BoundaryWall":
+				boundary_positions[pos] = true
+			elif not has_explicit_positions:
 				visible_positions[pos] = true
+
+
+# -- Helpers ------------------------------------------------------------------
+
+## Extract a bool from a tagged-union {"Bool": true} or plain bool value.
+## Handles both serde encoding styles; emits push_warning on unrecognised format.
+static func _extract_bool_setting(key: String, val: Variant) -> bool:
+	if val is bool:
+		return val
+	if val is Dictionary and val.has("Bool"):
+		return bool(val["Bool"])
+	push_warning("GameState: unexpected type for setting '%s': %s" % [key, str(val)])
+	return false

client/scripts/autoloads/input_mapper.gd

@@ -19,8 +19,15 @@ enum Action {
 	INTERACT, USE_PERCEPTION_MODE, OPEN_MENU, PAUSE, UNPAUSE,
 	TOGGLE_STANCE_UP, TOGGLE_STANCE_DOWN,
 	BUG_REPORT,  # #495: F12 WRONG button — client-only, not sent to server
+	OPEN_JOURNAL,  # #264: J key — toggle knowledge journal panel, client-only
 	SET_FACING,  # D-054: facing octant update (no movement)
 	TELEPORT_HUB,  # #501: Home key — Gauntlet dev teleport (not production fast-travel)
+	SAVE_GAME,  # #554: F5 quicksave — sends SaveGame to server with save path
+	LOAD_GAME,  # #554: F6 quickload — sends LoadGame to server with save path
+	DEBUG_COMMAND,  # #581: debug console command dispatch — sends DebugCommandKind to server
+	CHANGE_SETTINGS,      # #646: persist a setting to server SQLite — sends {key, value} to server
+	REQUEST_ALL_SETTINGS, # #646: request full settings dump from server after handshake (unit variant)
+	DELETE_SETTING,       # #646: delete a setting by key from server SQLite (struct variant)
 }
 
 var input_queue: Array[Dictionary] = []
@@ -106,15 +113,29 @@ func _unhandled_input(event: InputEvent) -> void:
 		action = Action.TOGGLE_STANCE_DOWN
 	elif event.is_action_pressed("bug_report"):
 		action = Action.BUG_REPORT
+	elif event.is_action_pressed("open_journal"):
+		action = Action.OPEN_JOURNAL
 	elif event.is_action_pressed("teleport_hub"):
 		if GameState.gauntlet_mode:
 			action = Action.TELEPORT_HUB
+	elif event.is_action_pressed("quicksave"):
+		action = Action.SAVE_GAME
+	elif event.is_action_pressed("quickload"):
+		action = Action.LOAD_GAME
 
 	if action != -1:
-		input_queue.append({
+		var entry := {
 			"action": action,
 			"timestamp_msec": Time.get_ticks_msec(),
-		})
+		}
+		# #554: Attach save path for SaveGame/LoadGame actions
+		if action == Action.SAVE_GAME or action == Action.LOAD_GAME:
+			var game_id := GameState.current_game_id
+			if game_id.is_empty():
+				get_viewport().set_input_as_handled()
+				return  # No active session — ignore save/load
+			entry["action_data"] = {"path": "user://saves/" + game_id + "/quicksave.sav"}
+		input_queue.append(entry)
 		get_viewport().set_input_as_handled()
 
 

client/scripts/autoloads/platform_info.gd

@@ -0,0 +1,348 @@
+extends Node
+## Platform abstraction layer — D-138 §8, D-141. Central location for all OS queries.
+## Owned by Stig (UI Developer). Registered FIRST in project.godot so other
+## autoloads can read its properties in their own _ready().
+##
+## Sections:
+##   Power:    PowerProfile enum, 30s poll timer, power_profile_changed signal.
+##             raw_power_state / battery_percent updated each poll.
+##   Memory:   free_memory_mb / total_memory_mb, refresh_memory() on demand.
+##   CPU:      cpu_name / cpu_logical_cores — read once in _ready().
+##   GPU:      gpu_name / gpu_vendor / gpu_api_version / gpu_type / gpu_driver_info.
+##             Guarded for headless/server builds where RenderingServer has no device.
+##   Platform: platform_name / os_version / distribution / is_sandboxed.
+##   Display:  screen_count / screen_size / screen_dpi / screen_refresh_rate / display_scale.
+##   Locale:   locale / locale_language.
+##   Paths:    Read-once OS path constants, populated in _ready().
+##   Diag:     get_diagnostics() — flat dict of all properties for bug reports.
+
+
+# -- Power profile ------------------------------------------------------------
+
+## High-level power classification. POWER_SAVER reserved for future OS API.
+enum PowerProfile {
+	FULL = 0,       # Plugged in (charged, charging, or no battery) — no restrictions
+	BATTERY = 1,    # On battery — AI inference should be suspended per D-138 §8 Layer 3
+	POWER_SAVER = 2 # System-level power-saver mode (future: no cross-platform API yet)
+}
+
+## Emitted when the detected power profile changes.
+signal power_profile_changed(old_profile: int, new_profile: int)
+
+## Current power profile. Updated by the 30-second poll timer.
+var power_profile: PowerProfile = PowerProfile.FULL
+
+## Raw OS power_state integer from the last poll. 0 = unknown, 1 = on battery, etc.
+var raw_power_state: int = 0
+
+## Battery charge percentage (0–100). -1 if not available or not on battery.
+var battery_percent: int = -1
+
+## How often (seconds) to re-poll OS for power state changes.
+const POWER_POLL_INTERVAL := 30.0
+
+# OS power_state integer constants (Godot 4 — same values as POWERSTATE_* enum).
+const _POWER_STATE_UNKNOWN    := 0
+const _POWER_STATE_ON_BATTERY := 1
+const _POWER_STATE_NO_BATTERY := 2
+const _POWER_STATE_CHARGING   := 3
+const _POWER_STATE_CHARGED    := 4
+
+
+# -- Memory -------------------------------------------------------------------
+
+## Free physical RAM in megabytes. Call refresh_memory() before reading if staleness matters.
+var free_memory_mb: float = 0.0
+
+## Total physical RAM in megabytes. Populated once in _ready(); doesn't change at runtime.
+var total_memory_mb: float = 0.0
+
+
+# -- CPU ----------------------------------------------------------------------
+
+## Human-readable processor name (e.g. "Intel(R) Core(TM) i7-9750H CPU @ 2.60GHz").
+var cpu_name: String = ""
+
+## Number of logical CPU cores reported by the OS.
+var cpu_logical_cores: int = 0
+
+
+# -- GPU ----------------------------------------------------------------------
+
+## GPU display name (e.g. "NVIDIA GeForce RTX 3080").
+var gpu_name: String = ""
+
+## GPU vendor string (e.g. "NVIDIA Corporation").
+var gpu_vendor: String = ""
+
+## Graphics API version string (e.g. "OpenGL 4.6.0 ...").
+var gpu_api_version: String = ""
+
+## GPU type classification: "discrete" | "integrated" | "virtual" | "cpu" | "other".
+var gpu_type: String = "other"
+
+## Low-level driver info strings from the OS (may be empty on some platforms).
+var gpu_driver_info: PackedStringArray = PackedStringArray()
+
+
+# -- Platform identity --------------------------------------------------------
+
+## OS name reported by Godot (e.g. "Linux", "Windows", "macOS").
+var platform_name: String = ""
+
+## Full OS version string (e.g. "Ubuntu 22.04.3 LTS").
+var os_version: String = ""
+
+## Linux distribution name (e.g. "Ubuntu"); empty on non-Linux platforms.
+var distribution: String = ""
+
+## True if the application is running inside a sandbox (Flatpak, Snap, macOS sandbox, etc.).
+var is_sandboxed: bool = false
+
+
+# -- Display ------------------------------------------------------------------
+
+## Number of connected screens.
+var screen_count: int = 1
+
+## Size of the primary screen in pixels.
+var screen_size: Vector2i = Vector2i(1920, 1080)
+
+## DPI of the primary screen.
+var screen_dpi: int = 96
+
+## Refresh rate of the primary screen in Hz. Falls back to 60.0 if OS reports < 0.
+var screen_refresh_rate: float = 60.0
+
+## UI scale factor. Uses OS-reported scale on macOS; falls back to dpi / 96.0 elsewhere.
+var display_scale: float = 1.0
+
+
+# -- Locale -------------------------------------------------------------------
+
+## Full locale string (e.g. "en_US").
+var locale: String = ""
+
+## Language portion of the locale (e.g. "en").
+var locale_language: String = ""
+
+
+# -- File paths ---------------------------------------------------------------
+
+## Base user data directory (user://).
+var user_data_dir: String = ""
+
+## Directory where settings.cfg is written. Same as user_data_dir in Godot 4.
+var config_dir: String = ""
+
+## Full path to AI benchmark cache (ai-dialogue-config.json).
+var benchmark_cache_path: String = ""
+
+## Directory where the game binary lives (install location).
+var install_dir: String = ""
+
+## Full path to the game executable.
+var executable_path: String = ""
+
+## OS-provided cache directory, or user_data_dir/cache as fallback.
+var cache_dir: String = ""
+
+## Directory where the bundled Gemma 2 model lives (derived from install_dir).
+var model_dir: String = ""
+
+
+# -- Lifecycle ----------------------------------------------------------------
+
+func _ready() -> void:
+	_init_paths()
+	_init_hardware()
+	refresh_memory()
+	_poll_power()
+
+	var timer := Timer.new()
+	timer.wait_time = POWER_POLL_INTERVAL
+	timer.autostart = true
+	timer.timeout.connect(_poll_power)
+	add_child(timer)
+
+
+func _init_paths() -> void:
+	user_data_dir        = OS.get_user_data_dir()
+	config_dir           = user_data_dir
+	benchmark_cache_path = "user://ai-dialogue-config.json"
+	executable_path      = OS.get_executable_path()
+	install_dir          = executable_path.get_base_dir()
+	model_dir            = install_dir + "/models"
+	# get_cache_dir() may not exist on all Godot builds — use callv for safety.
+	var os_cache: String = ""
+	if OS.has_method("get_cache_dir"):
+		var result: Variant = OS.callv("get_cache_dir", [])
+		if result is String:
+			os_cache = result
+	cache_dir = os_cache if not os_cache.is_empty() else user_data_dir + "/cache"
+
+
+func _init_hardware() -> void:
+	# -- CPU
+	cpu_name          = OS.get_processor_name()
+	cpu_logical_cores = OS.get_processor_count()
+
+	# -- GPU (guarded: RenderingServer methods may return empty in headless mode)
+	gpu_name       = RenderingServer.get_video_adapter_name()
+	gpu_vendor     = RenderingServer.get_video_adapter_vendor()
+	gpu_api_version = RenderingServer.get_video_adapter_api_version()
+	gpu_driver_info = OS.get_video_adapter_driver_info()
+	if RenderingServer.has_method("get_video_adapter_type"):
+		var adapter_type: int = RenderingServer.callv("get_video_adapter_type", [])
+		gpu_type = _map_adapter_type(adapter_type)
+
+	# -- Platform identity
+	platform_name = OS.get_name()
+	os_version    = OS.get_version()
+	if OS.has_method("get_distribution_name"):
+		var dist: Variant = OS.callv("get_distribution_name", [])
+		if dist is String:
+			distribution = dist
+	is_sandboxed = OS.is_sandboxed()
+
+	# -- Display
+	screen_count = DisplayServer.get_screen_count()
+	screen_size  = DisplayServer.screen_get_size()
+	screen_dpi   = DisplayServer.screen_get_dpi()
+	var raw_rate: float = DisplayServer.screen_get_refresh_rate()
+	screen_refresh_rate = raw_rate if raw_rate >= 0.0 else 60.0
+	display_scale = _compute_display_scale()
+
+	# -- Locale
+	locale          = OS.get_locale()
+	locale_language = OS.get_locale_language()
+
+
+## Map RenderingDevice.DeviceType int to a readable string.
+## Values: 0=OTHER, 1=INTEGRATED, 2=DISCRETE, 3=VIRTUAL, 4=CPU.
+static func _map_adapter_type(adapter_type: int) -> String:
+	match adapter_type:
+		1: return "integrated"
+		2: return "discrete"
+		3: return "virtual"
+		4: return "cpu"
+		_: return "other"
+
+
+## Compute display scale for the primary screen.
+## macOS reports via screen_get_scale(); all others fall back to dpi / 96.0.
+func _compute_display_scale() -> float:
+	if platform_name == "macOS" and DisplayServer.has_method("screen_get_scale"):
+		var scale: Variant = DisplayServer.callv("screen_get_scale", [])
+		if scale is float and scale > 0.0:
+			return scale
+	return float(screen_dpi) / 96.0
+
+
+# -- Memory API ---------------------------------------------------------------
+
+## Refresh free/total memory readings from the OS. Call before read if freshness matters.
+func refresh_memory() -> void:
+	var mem := OS.get_memory_info()
+	# "available" = Linux MemAvailable / Windows ullAvailPhys (includes reclaimable pages).
+	# Fall back to "free" on platforms that don't provide "available".
+	free_memory_mb  = float(mem.get("available", mem.get("free", 0))) / (1024.0 * 1024.0)
+	total_memory_mb = float(mem.get("physical", 0)) / (1024.0 * 1024.0)
+
+
+# -- Power API ----------------------------------------------------------------
+
+## Classify an OS power_state integer into a human-readable string.
+## 1 (ON_BATTERY) → "battery", 2/3/4 (plugged) → "plugged", 0 → "unknown".
+static func classify_power_state(power_state: int) -> String:
+	match power_state:
+		_POWER_STATE_ON_BATTERY:
+			return "battery"
+		_POWER_STATE_NO_BATTERY, _POWER_STATE_CHARGING, _POWER_STATE_CHARGED:
+			return "plugged"
+		_:
+			return "unknown"
+
+
+## True only when the OS reports the device is on battery — used by Layer 3 suspend.
+static func should_suspend_inference(power_state: int) -> bool:
+	return power_state == _POWER_STATE_ON_BATTERY
+
+
+## Read current OS power state integer. Returns 0 (UNKNOWN) if unavailable.
+## Uses callv() to defer method resolution to runtime — avoids compile errors on builds
+## where OS.get_power_info() is not available (e.g. headless).
+func current_power_state() -> int:
+	# Try Godot 4.x: OS.get_power_info() → {"power_state": int, "percent": int, ...}
+	if OS.has_method("get_power_info"):
+		var info: Variant = OS.callv("get_power_info", [])
+		if info is Dictionary:
+			return int(info.get("power_state", _POWER_STATE_UNKNOWN))
+	# Fallback: unknown power state → treat as FULL (no inference suspension).
+	return _POWER_STATE_UNKNOWN
+
+
+func _poll_power() -> void:
+	# Read raw state + battery percent from OS.
+	raw_power_state = _POWER_STATE_UNKNOWN
+	battery_percent = -1
+	if OS.has_method("get_power_info"):
+		var info: Variant = OS.callv("get_power_info", [])
+		if info is Dictionary:
+			raw_power_state = int(info.get("power_state", _POWER_STATE_UNKNOWN))
+			if raw_power_state == _POWER_STATE_ON_BATTERY:
+				battery_percent = int(info.get("percent", -1))
+
+	var new_profile: PowerProfile = PowerProfile.BATTERY \
+		if raw_power_state == _POWER_STATE_ON_BATTERY \
+		else PowerProfile.FULL
+	if new_profile != power_profile:
+		var old_profile := power_profile
+		power_profile = new_profile
+		power_profile_changed.emit(int(old_profile), int(new_profile))
+
+
+# -- Diagnostics --------------------------------------------------------------
+
+## Returns all platform properties as a flat dictionary for inclusion in bug reports.
+func get_diagnostics() -> Dictionary:
+	return {
+		# Power
+		"power_profile":      int(power_profile),
+		"raw_power_state":    raw_power_state,
+		"battery_percent":    battery_percent,
+		# Memory
+		"free_memory_mb":     free_memory_mb,
+		"total_memory_mb":    total_memory_mb,
+		# CPU
+		"cpu_name":           cpu_name,
+		"cpu_logical_cores":  cpu_logical_cores,
+		# GPU
+		"gpu_name":           gpu_name,
+		"gpu_vendor":         gpu_vendor,
+		"gpu_api_version":    gpu_api_version,
+		"gpu_type":           gpu_type,
+		"gpu_driver_info":    Array(gpu_driver_info),
+		# Platform
+		"platform_name":      platform_name,
+		"os_version":         os_version,
+		"distribution":       distribution,
+		"is_sandboxed":       is_sandboxed,
+		# Display
+		"screen_count":       screen_count,
+		"screen_size":        {"x": screen_size.x, "y": screen_size.y},
+		"screen_dpi":         screen_dpi,
+		"screen_refresh_rate": screen_refresh_rate,
+		"display_scale":      display_scale,
+		# Locale
+		"locale":             locale,
+		"locale_language":    locale_language,
+		# Paths
+		"user_data_dir":         user_data_dir,
+		"config_dir":            config_dir,
+		"benchmark_cache_path":  benchmark_cache_path,
+		"install_dir":           install_dir,
+		"executable_path":       executable_path,
+		"cache_dir":             cache_dir,
+		"model_dir":             model_dir,
+	}

client/scripts/autoloads/platform_info.gd.uid

@@ -0,0 +1 @@
+uid://platform_info_sr

client/scripts/autoloads/session_manager.gd

@@ -0,0 +1,184 @@
+extends Node
+## D-085 (#258): Game session lifecycle manager.
+## Creates per-game save directories on New Game, resumes existing sessions,
+## and handles quit-to-menu flow with save confirmation.
+##
+## All save dirs live under user://saves/<game-id>/ where game-id is
+## <YYYYMMDD>-<HHMMSS>-<hex6> (e.g. "20260225-143022-a7b3f1").
+
+const SAVES_DIR := "user://saves/"
+const GAME_SCENE := "res://scenes/main.tscn"
+const MENU_SCENE := "res://scenes/main_menu.tscn"
+
+var _quit_dialog: ConfirmationDialog = null
+
+
+## Generate a new game-id, create its save directory, and activate the session.
+## Returns the new game-id string.
+func new_game() -> String:
+	var now := Time.get_datetime_dict_from_system()
+	var timestamp := "%04d%02d%02d-%02d%02d%02d" % [
+		now.year, now.month, now.day,
+		now.hour, now.minute, now.second,
+	]
+	var rng := RandomNumberGenerator.new()
+	var hex_seed := "%06x" % (rng.randi() & 0xFFFFFF)
+	var game_id := "%s-%s" % [timestamp, hex_seed]
+	var save_path := SAVES_DIR + game_id + "/"
+	var err := DirAccess.make_dir_recursive_absolute(save_path)
+	if err != OK:
+		push_error("SessionManager: failed to create save dir %s: %s" % [
+			save_path, error_string(err)])
+		return ""
+	GameState.current_game_id = game_id
+
+	# #175: Generate world_seed for deterministic simulation (D-010, D-029).
+	# Combines two randi() calls (u32 each) into 63-bit entropy range.
+	# Mask bit 31 of the upper word before shifting to prevent signed overflow:
+	# GDScript int is i64 — if bit 63 is set, MessagePack encodes as negative,
+	# and Rust rmp_serde rejects negative values when deserializing as u64.
+	GameState.world_seed = ((rng.randi() & 0x7FFFFFFF) << 32) | rng.randi()
+
+	# Persist world_seed to save directory so resume_game() can restore it.
+	# Without this, loaded sessions would send seed=0, breaking D-010 determinism.
+	_write_seed_file(save_path, GameState.world_seed)
+
+	return game_id
+
+
+## Resume an existing game session by setting the active game-id.
+## Restores world_seed and character_archetype from the save directory.
+func resume_game(game_id: String) -> void:
+	GameState.current_game_id = game_id
+	var save_path := SAVES_DIR + game_id + "/"
+	GameState.world_seed = _read_seed_file(save_path)
+	GameState.character_archetype = _read_archetype_file(save_path)
+
+
+## List all game directories under user://saves/ sorted by last-modified (most recent first).
+## Returns Array of {game_id: String, modified_time: int, newest_save: String}.
+func list_game_dirs() -> Array:
+	var dir := DirAccess.open(SAVES_DIR)
+	if dir == null:
+		return []
+	var results: Array = []
+	dir.list_dir_begin()
+	var entry := dir.get_next()
+	while entry != "":
+		if dir.current_is_dir() and not entry.begins_with("."):
+			var dir_path := SAVES_DIR + entry + "/"
+			var newest_save := _find_newest_save(dir_path)
+			var mtime: int = 0
+			if newest_save != "":
+				mtime = FileAccess.get_modified_time(dir_path + newest_save)
+			results.append({
+				"game_id": entry,
+				"modified_time": mtime,
+				"newest_save": newest_save,
+			})
+		entry = dir.get_next()
+	dir.list_dir_end()
+	results.sort_custom(func(a: Dictionary, b: Dictionary) -> bool:
+		return a.modified_time > b.modified_time)
+	return results
+
+
+## Show "Save before quitting?" confirmation dialog, then return to main menu.
+## #554: The actual F5 save will be wired here once server supports SaveCommand.
+func quit_to_menu() -> void:
+	if _quit_dialog != null and is_instance_valid(_quit_dialog):
+		return  # Dialog already open
+	_quit_dialog = ConfirmationDialog.new()
+	_quit_dialog.dialog_text = UIStrings.get_text("menu.confirm_quit")
+	_quit_dialog.ok_button_text = UIStrings.get_text("menu.confirm_yes")
+	_quit_dialog.cancel_button_text = UIStrings.get_text("menu.confirm_no")
+	get_tree().root.add_child(_quit_dialog)
+	_quit_dialog.confirmed.connect(_do_quit_to_menu)
+	_quit_dialog.canceled.connect(_cleanup_quit_dialog)
+	_quit_dialog.popup_centered()
+
+
+func _do_quit_to_menu() -> void:
+	_cleanup_quit_dialog()
+	# #554: Trigger quicksave before navigating to menu.
+	# send_input() buffers the command — defer scene change by one frame so
+	# SimBridge._process() flushes the outbound buffer before teardown.
+	if not GameState.current_game_id.is_empty():
+		var path := "user://saves/" + GameState.current_game_id + "/quicksave.sav"
+		SimBridge.send_input({
+			"action": InputMapper.Action.SAVE_GAME,
+			"timestamp_msec": Time.get_ticks_msec(),
+			"action_data": {"path": path},
+		})
+		GameState.current_game_id = ""
+		_navigate_to_menu.call_deferred()
+	else:
+		GameState.current_game_id = ""
+		get_tree().change_scene_to_file(MENU_SCENE)
+
+
+func _navigate_to_menu() -> void:
+	get_tree().change_scene_to_file(MENU_SCENE)
+
+
+func _cleanup_quit_dialog() -> void:
+	if _quit_dialog != null and is_instance_valid(_quit_dialog):
+		_quit_dialog.queue_free()
+	_quit_dialog = null
+
+
+## Write world_seed to a file in the save directory for session persistence.
+func _write_seed_file(save_path: String, seed: int) -> void:
+	var file := FileAccess.open(save_path + "world_seed", FileAccess.WRITE)
+	if file == null:
+		push_error("SessionManager: failed to write seed file: %s" % error_string(FileAccess.get_open_error()))
+		return
+	file.store_64(seed)
+
+
+## Read world_seed from save directory. Returns 0 if file missing (legacy saves).
+## Masks the sign bit on read: save files written before the signed-overflow fix
+## may contain negative i64 values that Rust rmp_serde rejects as u64.
+func _read_seed_file(save_path: String) -> int:
+	var file := FileAccess.open(save_path + "world_seed", FileAccess.READ)
+	if file == null:
+		push_warning("SessionManager: no seed file in %s — using seed=0 (legacy save)" % save_path)
+		return 0
+	return file.get_64() & 0x7FFFFFFFFFFFFFFF
+
+
+## Write character_archetype to save directory. Called after new_game() creates the dir.
+func save_character_archetype(game_id: String, archetype: String) -> void:
+	var save_path := SAVES_DIR + game_id + "/"
+	var file := FileAccess.open(save_path + "character.txt", FileAccess.WRITE)
+	if file == null:
+		push_error("SessionManager: failed to write character.txt: %s" % error_string(FileAccess.get_open_error()))
+		return
+	file.store_string(archetype)
+
+
+## Read character_archetype from save directory. Returns "detective" if missing (legacy saves).
+func _read_archetype_file(save_path: String) -> String:
+	var file := FileAccess.open(save_path + "character.txt", FileAccess.READ)
+	if file == null:
+		return "detective"
+	return file.get_as_text().strip_edges()
+
+
+func _find_newest_save(dir_path: String) -> String:
+	var dir := DirAccess.open(dir_path)
+	if dir == null:
+		return ""
+	var best_name := ""
+	var best_time: int = 0
+	dir.list_dir_begin()
+	var entry := dir.get_next()
+	while entry != "":
+		if not dir.current_is_dir() and entry.ends_with(".sav"):
+			var mtime := FileAccess.get_modified_time(dir_path + entry)
+			if mtime > best_time:
+				best_time = mtime
+				best_name = entry
+		entry = dir.get_next()
+	dir.list_dir_end()
+	return best_name

client/scripts/autoloads/session_manager.gd.uid

@@ -0,0 +1 @@
+uid://b357ok64jc8vp

client/scripts/autoloads/sim_bridge.gd

@@ -1,17 +1,11 @@
 extends Node
 
 # Connection states
-enum ConnectionState { DISCONNECTED, CONNECTING, CONNECTED, ERROR }
+enum ConnectionState { DISCONNECTED, CONNECTING, HANDSHAKING, CONNECTED, ERROR }
 
 var state: ConnectionState = ConnectionState.DISCONNECTED
 var test_mode: bool = OS.get_environment("SR_LIVE") != "1"  # SR_LIVE=1 connects to real server
-var _test_tick: int = 0
-var _test_player_pos: Vector2i = Vector2i(10, 10)
-var _test_facing: String = "North"
-var _test_input_queue: Array = []  # Queued actions for test mode
-var _test_in_dialogue: bool = false  # Mock dialogue state (#434)
-var _test_gauntlet_mode: bool = false  # #501: Gauntlet mode for dev teleport guard
-var _test_npc_relationship: String = "Unknown"  # #521: NPC relationship for D-033 color
+var harness: TestHarness = null  # Test simulation (D-020: game logic lives outside production client)
 var _last_snapshot: Variant = null  # Most recent decoded snapshot (consumed by poll_snapshot)
 var _outbound_buffer: Array[Dictionary] = []  # Raw inputs awaiting batch encode + transport
 
@@ -27,23 +21,68 @@ const CONNECT_RETRY_INTERVAL: float = 0.1  # Seconds between retry attempts
 var _connect_retries: int = 0
 var _retry_timer: float = 0.0
 
+# Handshake state (#556)
+const HANDSHAKE_TIMEOUT_USEC: int = 5_000_000  # 5 seconds
+var _handshake_start_usec: int = 0
+
 # Signals
 signal connection_state_changed(old_state: ConnectionState, new_state: ConnectionState)
 signal snapshot_received(snapshot: Dictionary)
+signal handshake_complete(protocol_version: int)
+signal handshake_failed(reason: String)
 
 func _ready() -> void:
 	if test_mode:
+		harness = TestHarness.new()
 		print("SimBridge: Running in test mode (dynamic snapshot)")
 
-# Reset test state — call before tests that use _test_snapshot()
+
+# -- Test mode proxy API (backward compat for 13+ test files) ------------------
+
 func reset_test_state() -> void:
-	_test_tick = 0
-	_test_player_pos = Vector2i(10, 10)
-	_test_facing = "North"
-	_test_input_queue.clear()
-	_test_in_dialogue = false
-	_test_gauntlet_mode = false
-	_test_npc_relationship = "Unknown"
+	if harness: harness.reset()
+
+func _test_snapshot() -> Dictionary:
+	return harness.snapshot()
+
+func _test_has_los(from: Vector2i, to: Vector2i) -> bool:
+	return harness.has_los(from, to)
+
+var _test_tick: int:
+	get: return harness.tick if harness else 0
+	set(v):
+		if harness: harness.tick = v
+
+var _test_player_pos: Vector2i:
+	get: return harness.player_pos if harness else Vector2i.ZERO
+	set(v):
+		if harness: harness.player_pos = v
+
+var _test_facing: String:
+	get: return harness.facing if harness else "North"
+	set(v):
+		if harness: harness.facing = v
+
+var _test_in_dialogue: bool:
+	get: return harness.in_dialogue if harness else false
+	set(v):
+		if harness: harness.in_dialogue = v
+
+var _test_gauntlet_mode: bool:
+	get: return harness.gauntlet_mode if harness else false
+	set(v):
+		if harness: harness.gauntlet_mode = v
+
+var _test_npc_relationship: String:
+	get: return harness.npc_relationship if harness else "Unknown"
+	set(v):
+		if harness: harness.npc_relationship = v
+
+var _test_input_queue: Array:
+	get: return harness.input_queue if harness else []
+
+
+# -- Connection lifecycle ------------------------------------------------------
 
 # Change connection state and emit signal
 func _set_state(new_state: ConnectionState) -> void:
@@ -66,8 +105,13 @@ func connect_to_sim() -> void:
 	# Spawn server subprocess
 	if not server_path.is_empty():
 		_server = ServerProcess.new()
-		# Server reads first positional arg as bind address (e.g. "127.0.0.1:9876")
-		var pid := _server.start(server_path, ["127.0.0.1:" + str(server_port)])
+		# Server reads first positional arg as bind address (e.g. "127.0.0.1:9876").
+		# D-085 (#258): pass --game-id <id> so server logs use the same session identifier.
+		var args := ["127.0.0.1:" + str(server_port)]
+		var game_id: String = GameState.current_game_id
+		if not game_id.is_empty():
+			args.append_array(["--game-id", game_id])
+		var pid := _server.start(server_path, args)
 		if pid <= 0:
 			push_error("SimBridge: failed to start server")
 			_set_state(ConnectionState.ERROR)
@@ -121,7 +165,8 @@ func _process(delta: float) -> void:
 		_bridge.poll()
 		match _bridge.get_status():
 			StreamPeerTCP.STATUS_CONNECTED:
-				_set_state(ConnectionState.CONNECTED)
+				_handshake_start_usec = Time.get_ticks_usec()
+				_set_state(ConnectionState.HANDSHAKING)
 			StreamPeerTCP.STATUS_CONNECTING:
 				pass  # Still connecting, wait
 			StreamPeerTCP.STATUS_ERROR:
@@ -134,6 +179,88 @@ func _process(delta: float) -> void:
 				_bridge = null  # Reset and retry
 		return
 
+	# HANDSHAKING state: read first framed message, validate HandshakeMessage (#556)
+	if state == ConnectionState.HANDSHAKING:
+		if _bridge == null:
+			_set_state(ConnectionState.ERROR)
+			return
+		_bridge.poll()
+
+		# Check connection dropped during handshake
+		var bridge_status := _bridge.get_status()
+		if bridge_status == StreamPeerTCP.STATUS_ERROR or bridge_status == StreamPeerTCP.STATUS_NONE:
+			var reason := "Connection dropped during handshake"
+			push_error("SimBridge: %s" % reason)
+			handshake_failed.emit(reason)
+			_bridge = null
+			_set_state(ConnectionState.ERROR)
+			return
+
+		# Check timeout
+		if Time.get_ticks_usec() - _handshake_start_usec > HANDSHAKE_TIMEOUT_USEC:
+			var reason := "Handshake timeout: no message received within 5 seconds"
+			push_error("SimBridge: %s" % reason)
+			handshake_failed.emit(reason)
+			_bridge.disconnect_from_server()
+			_set_state(ConnectionState.ERROR)
+			return
+
+		# Try to read first message
+		var msg := _bridge.poll_message()
+		if msg.is_empty():
+			return  # Not ready yet, continue polling
+
+		# Decode HandshakeMessage: { "protocol_version": N }
+		var decoded: Variant = Messagepack.decode(msg)
+		if decoded.status != null or not (decoded.value is Dictionary) \
+				or not decoded.value.has("protocol_version"):
+			var reason := "Handshake decode failed: malformed HandshakeMessage"
+			push_error("SimBridge: %s" % reason)
+			handshake_failed.emit(reason)
+			_bridge.disconnect_from_server()
+			_set_state(ConnectionState.ERROR)
+			return
+
+		var server_version: int = decoded.value["protocol_version"]
+		if server_version != Protocol.PROTOCOL_VERSION:
+			var reason := "Protocol version mismatch: server=%d, client=%d" % [
+				server_version, Protocol.PROTOCOL_VERSION]
+			push_error("SimBridge: %s" % reason)
+			handshake_failed.emit(reason)
+			_bridge.disconnect_from_server()
+			_set_state(ConnectionState.ERROR)
+			return
+
+		# Send startup message with world_seed (#175, D-010/D-029).
+		# Server blocks waiting for this before entering the tick loop.
+		var startup_bytes := Protocol.encode_startup_message(GameState.world_seed, GameState.character_archetype)
+		if startup_bytes.size() > 0:
+			var send_err := _bridge.send_message(startup_bytes)
+			if send_err != OK:
+				var reason := "Failed to send startup message: %s" % error_string(send_err)
+				push_error("SimBridge: %s" % reason)
+				handshake_failed.emit(reason)
+				_bridge.disconnect_from_server()
+				_set_state(ConnectionState.ERROR)
+				return
+		else:
+			var reason := "Failed to encode startup message"
+			push_error("SimBridge: %s" % reason)
+			handshake_failed.emit(reason)
+			_bridge.disconnect_from_server()
+			_set_state(ConnectionState.ERROR)
+			return
+
+		handshake_complete.emit(server_version)
+		_set_state(ConnectionState.CONNECTED)
+		# #646: Request full settings dump on connect — hydrates GameState.ai_enhanced_dialogue_enabled
+		# from server SQLite so the client reflects the authoritative persisted state (D-138).
+		_outbound_buffer.append({
+			"tick": 0,
+			"action_name": "RequestAllSettings",
+		})
+		return
+
 	if _bridge == null:
 		return
 
@@ -170,9 +297,13 @@ func _process(delta: float) -> void:
 				push_warning("SimBridge: connection lost")
 				_set_state(ConnectionState.DISCONNECTED)
 
+
+# -- Input / snapshot ----------------------------------------------------------
+
 # Send input to simulation server.
 # player_input: Dictionary with "action" (int from InputMapper.Action enum) and "timestamp_msec".
-# In test mode, inputs are silently dropped. In live mode, encoded and buffered for transport.
+# In test mode, inputs are delegated to the test harness.
+# In live mode, encoded and buffered for transport.
 # Returns OK on success, or an error code on failure.
 func send_input(player_input: Dictionary) -> Error:
 	if state != ConnectionState.CONNECTED:
@@ -182,25 +313,20 @@ func send_input(player_input: Dictionary) -> Error:
 		var wire_name: String = action_enum_to_wire(action)
 		if not wire_name.is_empty():
 			if wire_name == "SetFacing":
-				# D-054: Use action_data.facing from the input dict, not InputMapper global
 				var facing: String = ""
 				var action_data: Variant = player_input.get("action_data")
 				if action_data is Dictionary:
 					facing = str(action_data.get("facing", ""))
 				if not facing.is_empty():
-					_test_facing = facing
+					harness.process_facing(facing)
 			else:
-				_test_input_queue.append(wire_name)
+				harness.process_input(wire_name)
 		return OK
 	var action_name := action_enum_to_wire(player_input.get("action", -1))
 	if action_name.is_empty():
-		# action_enum_to_wire already emits push_warning for invalid actions
 		return ERR_INVALID_PARAMETER
-	# Use the server's current tick so drain_for_tick processes this input immediately.
-	# The client-side timestamp_msec is only useful for ordering within a frame.
 	var tick: int = GameState.current_tick
 	var entry: Dictionary = { "tick": tick, "action_name": action_name }
-	# Data variants (e.g. UsePerceptionMode) carry payload
 	var action_data: Variant = player_input.get("action_data")
 	if action_data != null:
 		entry["action_data"] = action_data
@@ -208,13 +334,13 @@ func send_input(player_input: Dictionary) -> Error:
 	return OK
 
 # Poll for snapshot from simulation.
-# In test mode returns hardcoded data. In live mode, returns the last decoded snapshot (if any).
+# In test mode delegates to test harness. In live mode, returns the last decoded snapshot.
 func poll_snapshot() -> Variant:
 	if state != ConnectionState.CONNECTED:
 		return null
 
 	if test_mode:
-		var snapshot = _test_snapshot()
+		var snapshot = harness.snapshot()
 		snapshot_received.emit(snapshot)
 		return snapshot
 
@@ -241,6 +367,23 @@ func receive_bytes(bytes: PackedByteArray) -> void:
 			snapshot["current_monologue"] = _last_snapshot["current_monologue"]
 		if snapshot.get("current_dialogue") == null and _last_snapshot.get("current_dialogue") != null:
 			snapshot["current_dialogue"] = _last_snapshot["current_dialogue"]
+		# #535: Carry forward one-shot dialogue events (arrays merge, scalar falls through)
+		if snapshot.get("dialogue_response") == null and _last_snapshot.get("dialogue_response") != null:
+			snapshot["dialogue_response"] = _last_snapshot["dialogue_response"]
+		var old_conv_events: Array = _last_snapshot.get("conversation_events", [])
+		if old_conv_events.size() > 0:
+			var new_conv_events: Array = snapshot.get("conversation_events", [])
+			snapshot["conversation_events"] = old_conv_events + new_conv_events
+		var old_conv_ended: Array = _last_snapshot.get("conversation_ended", [])
+		if old_conv_ended.size() > 0:
+			var new_conv_ended: Array = snapshot.get("conversation_ended", [])
+			snapshot["conversation_ended"] = old_conv_ended + new_conv_ended
+		# #554: Carry forward save/load result (one-shot, consumed by main.gd)
+		if snapshot.get("save_result") == null and _last_snapshot.get("save_result") != null:
+			snapshot["save_result"] = _last_snapshot["save_result"]
+		# #646: Carry forward settings_response (one-shot, consumed by game_state apply_snapshot)
+		if snapshot.get("settings_response") == null and _last_snapshot.get("settings_response") != null:
+			snapshot["settings_response"] = _last_snapshot["settings_response"]
 	_last_snapshot = snapshot
 
 # Drain the outbound buffer. Returns raw input entries for batch encoding.
@@ -249,6 +392,9 @@ func drain_outbound() -> Array[Dictionary]:
 	_outbound_buffer.clear()
 	return inputs
 
+
+# -- Wire protocol mapping -----------------------------------------------------
+
 # Map InputMapper.Action enum values to wire-format action names (matching Rust PlayerAction).
 # OPEN_MENU is client-only — no Rust equivalent, not sent over the wire.
 static func action_enum_to_wire(action: int) -> String:
@@ -275,286 +421,18 @@ static func action_enum_to_wire(action: int) -> String:
 			return "SetFacing"  # D-054: facing octant update (no movement)
 		InputMapper.Action.TELEPORT_HUB:
 			return "TeleportToHub"  # #501: Gauntlet dev teleport (not production fast-travel)
+		InputMapper.Action.SAVE_GAME:
+			return "SaveGame"  # #554: F5 quicksave (D-085)
+		InputMapper.Action.LOAD_GAME:
+			return "LoadGame"  # #554: F6 quickload (D-085)
+		InputMapper.Action.DEBUG_COMMAND:
+			return "DebugCommand"  # #581: debug console command dispatch
+		InputMapper.Action.CHANGE_SETTINGS:
+			return "ChangeSettings"      # #646: persist setting to server SQLite (D-138)
+		InputMapper.Action.REQUEST_ALL_SETTINGS:
+			return "RequestAllSettings"  # #646: unit variant — server sends full settings dump
+		InputMapper.Action.DELETE_SETTING:
+			return "DeleteSetting"       # #646: struct variant — delete setting by key
 		_:
 			push_warning("SimBridge: unknown action enum %s" % action)
 			return ""
-
-# Dynamic test snapshot — processes queued inputs to move player, generates
-# visibility based on current position. Matches Protocol.decode_snapshot() format.
-# NOTE: Test coordinate space (player at 10,10; NPC at 12,9; wall at 12,10)
-# is intentionally decoupled from the E2E proof room (player at 16,16; NPC at
-# 16,13; wall at 16,14). This ensures standalone tests don't depend on server
-# map layout and can exercise the rendering pipeline independently.
-func _test_snapshot() -> Dictionary:
-	_test_tick += 1
-
-	# Process queued inputs
-	for action_name in _test_input_queue:
-		if action_name == "TeleportToHub":
-			# #501: Reset to hub spawn position, clear dialogue
-			_test_player_pos = Vector2i(10, 10)
-			_test_in_dialogue = false
-			continue
-		if action_name == "Interact":
-			# Mock dialogue trigger (#434): if near NPC, start dialogue
-			var npc_pos := Vector2i(12, 9)
-			var dist := absi(_test_player_pos.x - npc_pos.x) + absi(_test_player_pos.y - npc_pos.y)
-			if dist <= 2 and _test_has_los(_test_player_pos, npc_pos):
-				_test_in_dialogue = true
-			continue
-		var delta := _action_to_delta(action_name)
-		var new_pos := _test_player_pos + delta
-		if _test_is_walkable(new_pos):
-			_test_player_pos = new_pos
-			if delta != Vector2i.ZERO:
-				# Walk-away dismisses dialogue (D-064)
-				if _test_in_dialogue:
-					_test_in_dialogue = false
-	_test_input_queue.clear()
-
-	var px := _test_player_pos.x
-	var py := _test_player_pos.y
-
-	# Build entities — player always visible
-	var entities: Array = [{
-		"entity_id": 1,
-		"x": float(px),
-		"y": float(py),
-		"z": 0,
-		"kind": { "variant": "Player", "data": null },
-		"visibility": "Forward",
-	}]
-
-	# NPC at (12, 9) — visible if within range and not blocked by wall at (12, 10)
-	var npc_pos := Vector2i(12, 9)
-	var npc_dist := absi(px - npc_pos.x) + absi(py - npc_pos.y)
-	if npc_dist <= 4 and _test_has_los(Vector2i(px, py), npc_pos):
-		var sector: String = "Forward" if npc_pos.y <= py else "Peripheral"
-		entities.append({
-			"entity_id": 2,
-			"x": float(npc_pos.x),
-			"y": float(npc_pos.y),
-			"z": 0,
-			"kind": { "variant": "Npc", "data": null },
-			"visibility": sector,
-			"relationship": _test_npc_relationship,
-		})
-
-	# v4: nearby_interactions when NPC is nearby and visible (#404/#405)
-	var nearby: Array = []
-	if npc_dist <= 2 and _test_has_los(Vector2i(px, py), npc_pos):
-		nearby.append({
-			"entity_id": 2,
-			"entity_type": "Npc",
-			"distance": npc_dist,
-			"verbs": [
-				{"kind": "Talk", "label": "Talk", "priority": 1, "available": true},
-				{"kind": "ExamineNpc", "label": "Observe", "priority": 2, "available": true},
-			],
-		})
-
-	# v5: monologue on first tick (#414)
-	var monologue: Variant = null
-	if _test_tick == 1:
-		monologue = {
-			"id": "test_enter_001",
-			"text": "Sova Transit District. Population twelve thousand and change.",
-			"duration_seconds": 5.0,
-		}
-
-	# v7: mock dialogue (#435, D-061/D-062) — triggered by Interact near NPC
-	# Sustained: dialogue persists across ticks while _test_in_dialogue is true.
-	# Movement (walk-away) clears it. Client consume-once guards against re-show.
-	# Options: structured {text, response_id, priority} per #435.
-	var dialogue: Variant = null
-	if _test_in_dialogue:
-		dialogue = {
-			"npc_name": "Kael",
-			"npc_entity_id": 2,
-			"speech": "Haven't seen you around the transit hub before. You new to Sova, or just passing through?",
-			"options": [
-				{"text": "Just arrived. Still getting my bearings.", "response_id": "kael_greet_01", "priority": 1, "confrontation": false},
-				{"text": "Passing through. Know where I can find work?", "response_id": "kael_greet_02", "priority": 2, "confrontation": false},
-				{"text": "I saw you near the cargo bay last night.", "response_id": "kael_confront_01", "priority": 3, "confrontation": true},
-			],
-		}
-
-	# v7: mock pending_recognitions (#431, D-059/D-060) — cognitive delay fog entity
-	# Entity at (13, 12) in fog: starts as grey blob, transitions to recognized over 6 ticks.
-	# Cycles every 12 ticks: 6 ticks recognizing, 6 ticks off (simulates repeat encounters).
-	var pending_recs: Array = []
-	var cycle_pos := _test_tick % 12
-	if cycle_pos < 6:
-		var total_delay := 6
-		var remaining := total_delay - cycle_pos
-		pending_recs.append({
-			"entity_id": 100,
-			"x": 13.5,
-			"y": 12.5,
-			"z": 0,
-			"remaining_ticks": remaining,
-			"total_delay_ticks": total_delay,
-		})
-
-	return {
-		"tick": _test_tick,
-		"version": Protocol.PROTOCOL_VERSION,
-		"game_time": {
-			"day": 0,
-			"time_of_day": _test_tick * 10,
-			"day_phase": "Morning",
-			"tick_rate": "Full",
-		},
-		"player_facing": _test_facing,
-		"player_stance": "Walk",
-		"player_inventory": [],
-		"entities": entities,
-		"tiles": _test_tiles(),
-		"visible_tiles": _test_visible_tiles(),
-		"visible_positions": _test_visible_positions(),
-		"nearby_interactions": nearby,
-		"current_monologue": monologue,
-		"current_dialogue": dialogue,
-		"pending_recognitions": pending_recs,
-		"gauntlet_mode": _test_gauntlet_mode,
-	}
-
-# Generate a small test room: 8x6 room with walls, a door, and floor
-func _test_tiles() -> Array:
-	var tiles: Array = []
-	var room_x := 7
-	var room_y := 7
-	var room_w := 8
-	var room_h := 8
-
-	for x in range(room_x, room_x + room_w):
-		for y in range(room_y, room_y + room_h):
-			var is_edge := (x == room_x or x == room_x + room_w - 1
-				or y == room_y or y == room_y + room_h - 1)
-			var tile_type: String
-			if is_edge:
-				# Door on the south wall, center
-				if y == room_y + room_h - 1 and x == room_x + room_w / 2:
-					tile_type = "door"
-				else:
-					tile_type = "wall"
-			else:
-				tile_type = "floor"
-			tiles.append({"x": x, "y": y, "z": 0, "type": tile_type})
-
-	# Corridor south of the door
-	var door_x := room_x + room_w / 2
-	for y in range(room_y + room_h, room_y + room_h + 4):
-		tiles.append({"x": door_x - 1, "y": y, "z": 0, "type": "wall"})
-		tiles.append({"x": door_x, "y": y, "z": 0, "type": "floor"})
-		tiles.append({"x": door_x + 1, "y": y, "z": 0, "type": "wall"})
-
-	return tiles
-
-# Test visible tiles with visibility sectors (v2 format)
-# Tiles ahead of the player are Forward, others Peripheral.
-func _test_visible_tiles() -> Array:
-	var vtiles: Array = []
-	var px := _test_player_pos.x
-	var py := _test_player_pos.y
-	var radius := 4
-	var room_x := 7
-	var room_y := 7
-	var room_w := 8
-	var room_h := 8
-
-	for x in range(px - radius, px + radius + 1):
-		for y in range(py - radius, py + radius + 1):
-			var dist := absf(x - px) + absf(y - py)
-			if dist <= radius:
-				if x >= room_x and x < room_x + room_w and y >= room_y and y < room_y + room_h:
-					var sector: String = "Forward" if y <= py else "Peripheral"
-					vtiles.append({"x": x, "y": y, "z": 0, "visibility": sector})
-	return vtiles
-
-# Test visibility: tiles within radius 4 of player, inside room bounds
-func _test_visible_positions() -> Array:
-	var positions: Array = []
-	var px := _test_player_pos.x
-	var py := _test_player_pos.y
-	var radius := 4
-	var room_x := 7
-	var room_y := 7
-	var room_w := 8
-	var room_h := 8
-
-	for x in range(px - radius, px + radius + 1):
-		for y in range(py - radius, py + radius + 1):
-			var dist := absf(x - px) + absf(y - py)
-			if dist <= radius:
-				if x >= room_x and x < room_x + room_w and y >= room_y and y < room_y + room_h:
-					positions.append({"x": x, "y": y})
-	return positions
-
-
-# -- Test mode helpers --
-
-const _TEST_WALLS: Array = [
-	# Room walls (8x8 room from (7,7) to (14,14))
-	Vector2i(7,7), Vector2i(8,7), Vector2i(9,7), Vector2i(10,7),
-	Vector2i(11,7), Vector2i(12,7), Vector2i(13,7), Vector2i(14,7),
-	Vector2i(7,14), Vector2i(8,14), Vector2i(9,14), Vector2i(10,14),
-	Vector2i(11,14), Vector2i(12,14), Vector2i(13,14), Vector2i(14,14),
-	Vector2i(7,8), Vector2i(7,9), Vector2i(7,10), Vector2i(7,11),
-	Vector2i(7,12), Vector2i(7,13),
-	Vector2i(14,8), Vector2i(14,9), Vector2i(14,10), Vector2i(14,11),
-	Vector2i(14,12), Vector2i(14,13),
-	# Interior wall blocking NPC
-	Vector2i(12, 10),
-]
-
-func _test_is_walkable(pos: Vector2i) -> bool:
-	return not _TEST_WALLS.has(pos)
-
-# Simple LOS check — blocked if a wall tile sits between start and end
-func _test_has_los(from: Vector2i, to: Vector2i) -> bool:
-	# Bresenham-lite: check tiles along the line
-	var dx := absi(to.x - from.x)
-	var dy := absi(to.y - from.y)
-	var sx := 1 if from.x < to.x else -1
-	var sy := 1 if from.y < to.y else -1
-	var err := dx - dy
-	var cx := from.x
-	var cy := from.y
-	while true:
-		if cx == to.x and cy == to.y:
-			return true
-		if Vector2i(cx, cy) != from and not _test_is_walkable(Vector2i(cx, cy)):
-			return false
-		var e2 := 2 * err
-		if e2 > -dy:
-			err -= dy
-			cx += sx
-		if e2 < dx:
-			err += dx
-			cy += sy
-	return true
-
-static func _action_to_delta(action_name: String) -> Vector2i:
-	match action_name:
-		"MoveNorth": return Vector2i(0, -1)
-		"MoveNortheast": return Vector2i(1, -1)
-		"MoveEast": return Vector2i(1, 0)
-		"MoveSoutheast": return Vector2i(1, 1)
-		"MoveSouth": return Vector2i(0, 1)
-		"MoveSouthwest": return Vector2i(-1, 1)
-		"MoveWest": return Vector2i(-1, 0)
-		"MoveNorthwest": return Vector2i(-1, -1)
-		_: return Vector2i.ZERO
-
-static func _delta_to_facing(delta: Vector2i) -> String:
-	match delta:
-		Vector2i(0, -1): return "North"
-		Vector2i(1, -1): return "Northeast"
-		Vector2i(1, 0): return "East"
-		Vector2i(1, 1): return "Southeast"
-		Vector2i(0, 1): return "South"
-		Vector2i(-1, 1): return "Southwest"
-		Vector2i(-1, 0): return "West"
-		Vector2i(-1, -1): return "Northwest"
-		_: return "North"

client/scripts/autoloads/ui_strings.gd

@@ -49,44 +49,6 @@ func reload() -> void:
 
 ## Parse YAML with arbitrary nesting depth.
 ## Returns flat Dictionary with dotted keys: { "section.sub.key": "value" }.
+## Delegates to YamlParser.parse_flat() (#560).
 static func _parse_yaml(text: String) -> Dictionary:
-	var strings := {}
-	var stack: Array = []  # [[indent, key], ...]
-	for line in text.split("\n"):
-		var stripped := line.strip_edges(false, true)
-		if stripped.is_empty() or stripped.begins_with("#"):
-			continue
-		var indent := line.length() - line.lstrip(" ").length()
-		var content := stripped.strip_edges()
-		var colon_pos := content.find(":")
-		if colon_pos < 0:
-			continue
-		var key := content.substr(0, colon_pos).strip_edges()
-		var val := content.substr(colon_pos + 1).strip_edges()
-		# Trailing comment without a value — treat as section header
-		if val.begins_with("#"):
-			val = ""
-		# Pop sections at same or deeper indent
-		while stack.size() > 0 and stack.back()[0] >= indent:
-			stack.pop_back()
-		if val.is_empty():
-			# Section header — push onto stack
-			stack.push_back([indent, key])
-		else:
-			# Leaf value — extract from quotes or strip inline comment
-			if val.begins_with("\""):
-				var end_quote := val.find("\"", 1)
-				if end_quote > 0:
-					val = val.substr(1, end_quote - 1)
-				else:
-					val = val.substr(1)
-			else:
-				var comment_pos := val.find(" #")
-				if comment_pos >= 0:
-					val = val.substr(0, comment_pos).strip_edges()
-			var dotted_key := ""
-			for entry in stack:
-				dotted_key += entry[1] + "."
-			dotted_key += key
-			strings[dotted_key] = val
-	return strings
+	return YamlParser.parse_flat(text)