chore(meta): release v0.1.15

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
chore(meta): update changelog
2026-02-23 16:24:23 +01:00 · 2026-02-23 15:56:20 +01:00 · 2026-02-23 15:56:10 +01:00 · 2026-02-23 15:36:45 +01:00 · 2026-02-23 15:36:29 +01:00 · 2026-02-23 15:36:24 +01:00
1052 changed files with 204827 additions and 1385 deletions
@@ -114,7 +114,7 @@ Synthesize findings.

 ### Qatux (Documenter & Librarian)
 - Core team member — participates in discussion rounds as documenter
- Manages document search via `/search-docs` skill
+- Manages document search via `/docs-search` skill
 - Maintains DECISIONS.md, DISCUSSION.md, briefings, and Qdrant search index
 - Answers "did we discuss this?" with citations

@@ -0,0 +1,39 @@
+---
+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.
+tools: Read, Glob, Grep, Edit, Write, Bash
+model: sonnet
+memory: project
+---
+
+You are INIGO, the Sound Designer on a game development team building a top-down immersive sim set in an original science fiction universe.
+
+## Your personality
+
+You think in layers. Every space has a base tone, a rhythm, and the things that break the rhythm. You hear what's missing as much as what's present. You say things like "What does silence sound like here?" and "That sound tells the player something before they see it" and "Ambience is information." You understand that in an immersive sim, sound is the player's second sight — what they hear around corners, through walls, behind closed doors. Sound is gameplay.
+
+Named after Inigo from the Void Trilogy — the Dreamer who shared immersive multi-sensory experiences with billions. He understood that atmosphere isn't decoration, it's the thing that makes a world feel inhabited.
+
+## Your role on the team
+
+- Design the soundscape layers for each location (Logistics Hub, Bar, Ring spaces)
+- 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)
+- Define what sounds travel through walls, around corners, and across z-levels
+- Create sound palettes per location and time-of-day
+- Specify audio tells for NPC behavior (footsteps, conversations, alerts)
+- Work with Gestalt to ensure sound cues map to mechanical significance
+- Ensure audio reinforces the information asymmetry core mechanic — what you hear but can't see matters
+
+## Design principles
+
+- **Sound is information**: Every ambient sound should either establish atmosphere or communicate game state. No filler noise.
+- **Diegetic first**: The player hears what their character hears. No non-diegetic audio cues for gameplay events (music is the exception).
+- **Layers, not walls**: Soundscapes are built from distinct layers (base ambience, activity, events) that can be independently controlled.
+- **Silence is a sound**: The absence of expected sound (a machine stopping, a crowd going quiet) is as meaningful as any cue.
+- **Range matters**: Sound propagation (D-018) is a core mechanic. Design sounds with their falloff and occlusion behavior in mind.
+
+## Project context
+
+Read your briefing at `docs/briefings/inigo.md` before starting work.
@@ -28,7 +28,7 @@ Named after Qatux, the Raiel with perfect memory who helped Paula Myo by recalli
 - Provide "state of the project" summaries when asked

 ### Knowledge management
- Maintain the Qdrant document index via /search-docs skill
+- Maintain the Qdrant document index via /docs-search skill
 - Update briefing files when decisions change
 - Answer retrieval questions: "did we discuss X?", "what did we decide about Y?"
 - Catch staleness in briefings and flag for update
@@ -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 `python3 db/connectors/qdrant_connector.py index-file <path>`.
+- **Re-index documents:** After archiving or updating documents, re-index them in Qdrant via `db/connectors/qdrant-index <path>`.

 ## Team workflow (mandatory)

@@ -29,6 +29,16 @@ Named after the Sentient Intelligences that manage all Commonwealth infrastructu

 You are execution-focused. When a decision is made, you immediately think about what needs to happen, in what order, by whom, and what depends on what. You maintain the project's pulse - always knowing what's in progress, what's blocked, and what's next. You don't wait to be asked for status updates; you surface risks early.

+## Ticket assignment rules
+
+The development teams are: **server**, **client**, **copy**, **audio**, **visual**, **ci**.
+
+When creating or splitting tickets:
+- **Always assign a ticket to exactly one team.** Every ticket must have a team.
+- **Never use "joint" as a team.** If work spans multiple teams, split it into separate tickets — one per team — with explicit dependencies between them.
+- For example, a feature requiring server-side logic and client-side rendering becomes two tickets: one for server (implement the data/system), one for client (consume and render it), with the client ticket blocked by the server ticket.
+- Sprint proof/acceptance tickets should be assigned to the team responsible for the final integration step, with blockers on the upstream tickets.
+
 ## Project context

 Read your briefing at `docs/briefings/si.md` before starting work.
@@ -0,0 +1,72 @@
+{
+  "env": {
+    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
+  },
+  "teammateMode": "in-process",
+  "permissions": {
+    "allow": [
+      "Bash(git add *)",
+      "Bash(git commit *)",
+      "Bash(git push *)",
+      "Bash(git fetch *)",
+      "Bash(git merge *)",
+      "Bash(git pull *)",
+      "Bash(git status *)",
+      "Bash(git log *)",
+      "Bash(git diff *)",
+      "Bash(git show *)",
+      "Bash(git checkout *)",
+      "Bash(git stash *)",
+      "Bash(git branch *)",
+      "Bash(git worktree *)",
+      "Bash(git config *)",
+      "Bash(git mv *)",
+      "Bash(git rm *)",
+      "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(db/connectors/audio-generate *)",
+      "Bash(db/connectors/audio-health)",
+      "Bash(db/connectors/audio-post *)",
+
+      "Bash(make *)",
+      "Bash(make)",
+
+      "Bash(tea *)",
+
+      "Bash(chmod *)",
+      "Bash(ls *)",
+      "Bash(find *)",
+      "Bash(list *)",
+      "Bash(tree *)",
+      "Bash(sed -n *)",
+
+      "Skill(git-commit)",
+      "Skill(worktree-update)",
+      "Skill(sprint-start)",
+      "Skill(sprint-plan)",
+      "Skill(pr-push)",
+      "Skill(pr-review)",
+      "Skill(ticket)",
+      "Skill(docs-search)",
+      "Skill(workshop-start)"
+    ],
+    "deny": [
+      "Bash(git push --force *)",
+      "Bash(git reset --hard *)",
+      "Bash(git clean -f *)",
+      "Bash(rm -rf *)"
+    ]
+  }
+}
@@ -0,0 +1,255 @@
+---
+name: audio-gen
+description: >
+  Generate audio assets for The Settled Reach using the Stable Audio Open API
+  (self-hosted Gradio app at tower-of-joy:11500). Use when generating any game
+  audio: ambient loops, SFX, UI sounds, monologue chimes, footsteps, or any
+  sound asset from docs/assets/audio/. Also use when the user asks about audio
+  generation, sound design pipeline, or audio asset iteration. Triggers on:
+  "generate audio", "make sounds", "create ambient", "audio pipeline",
+  "generate sfx", "stable audio", "gen audio", "sound design".
+---
+
+# Audio Generation — The Settled Reach
+
+Generate sonically consistent audio assets using the Stable Audio Open API via
+wrapper scripts at `db/connectors/audio-*`.
+
+Asset descriptions, filenames, bus routing, and design intent are documented in
+`docs/assets/audio/`. This skill provides the prompt system, generation
+workflow, and quality validation.
+
+## API Access
+
+**Never call the API directly.** Use the wrapper scripts:
+
+```bash
+# Check API health
+db/connectors/audio-health
+
+# Generate a single asset (WAV only)
+db/connectors/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" \
+  --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
+```
+
+### Parameters
+
+| Parameter | Default | Range | Notes |
+|-----------|---------|-------|-------|
+| `--duration` | 10 | 0-47s | Max 47s per generation. For longer loops, generate 45s with crossfade overlap. |
+| `--steps` | 100 | 10-200 | More steps = better quality, slower. Use 50 for quick previews, 100-150 for final. |
+| `--cfg` | 7 | 1-15 | Classifier-free guidance. Higher = more prompt-adherent but less natural. 5-9 is the sweet spot. |
+| `--output` | auto | — | Output WAV file path. Auto-names from prompt if omitted. |
+| `--post` | off | — | Run trim + normalize + convert after generation. |
+| `--output-ogg` | auto | — | OGG output path (implies `--post`). Defaults to same basename as WAV. |
+| `--timeout` | 600 | — | Max wait in seconds. Generation can take 2-5 minutes on 11GB VRAM. |
+
+### Critical Constraints
+
+- **NEVER parallelize requests.** The server has 11GB VRAM and runs one
+  generation at a time. Always wait for a generation to complete before
+  starting the next. Sequential only.
+- **Generation takes 2-5 minutes** per clip depending on duration and steps.
+  Be patient. The timeout default (600s) is generous.
+- **Max 47 seconds** per generation. For 60-90s ambient loops, generate 45s
+  clips and crossfade-stitch in post-processing.
+
+## Prompt Assembly
+
+Every generation uses three parts:
+
+```
+[SONIC FAMILY PREFIX] + [CATEGORY TEMPLATE] + [ASSET DESCRIPTION from docs/assets/audio/]
+```
+
+Never call the API with just the asset description. Always prepend the sonic
+family prefix and matching category template.
+
+- **Sonic palette and families:** Read `references/sonic-palette.md`
+- **Category templates:** Read `references/category-templates.md` and match by
+  asset type (ambient, sfx, ui)
+- **Asset description:** Look up the specific asset in `docs/assets/audio/{category}.md`
+
+## Batch Workflow (Preferred)
+
+For generating multiple assets, use a manifest file. This reduces prompt
+approvals to 2: one Write (manifest) + one Bash (batch run).
+
+### 1. Create the manifest
+
+Write a JSON manifest to `docs/assets/audio/batch-{sprint}-{ticket}.json`:
+
+```json
+{
+  "description": "Sprint 10 ambient + world SFX batch",
+  "output_dir": "client/assets/audio",
+  "gen_dir": "client/assets/audio/gen",
+  "defaults": {
+    "steps": 100,
+    "cfg": 7,
+    "lufs": -16,
+    "quality": 6
+  },
+  "assets": [
+    {
+      "id": "AMB-001",
+      "filename": "amb_station_base.ogg",
+      "method": "sao",
+      "duration": 45,
+      "steps": 150,
+      "cfg": 5,
+      "prompt": "[sonic family prefix] + [template] + [description]"
+    },
+    {
+      "id": "UI-005",
+      "filename": "sfx_monologue_chime.ogg",
+      "method": "synth",
+      "synth": {
+        "type": "harmonic",
+        "duration": 0.8,
+        "fundamental": 1200,
+        "harmonics": [
+          {"freq": 2400, "db": -12},
+          {"freq": 3600, "db": -24}
+        ],
+        "attack_ms": 15,
+        "sustain_ratio": 0.2,
+        "decay": "exponential"
+      }
+    }
+  ]
+}
+```
+
+Asset `id` values must match IDs in `docs/assets/audio/{category}.md` (e.g.,
+AMB-001, SFX-002, UI-005). This couples the manifest to the asset inventory.
+
+### 2. Run the batch
+
+```bash
+# Full run
+db/connectors/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
+
+# Generate only specific assets
+db/connectors/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
+```
+
+### 3. Update asset docs with prompts
+
+After the batch completes, write the exact prompts used back into the
+Prompt/Notes column of `docs/assets/audio/{category}.md`. The manifest records
+what was generated; the asset docs record what we have.
+
+### Manifest fields
+
+| Field | Required | Notes |
+|-------|----------|-------|
+| `id` | yes | Asset ID from docs (AMB-001, SFX-002, UI-005) |
+| `filename` | yes | Output filename (must match asset doc) |
+| `method` | yes | `sao` (Stable Audio Open) or `synth` (harmonic synthesis) |
+| `duration` | SAO only | Duration in seconds |
+| `prompt` | SAO only | Full assembled prompt |
+| `steps` | no | Override default steps |
+| `cfg` | no | Override default CFG |
+| `synth` | synth only | Synthesis parameters (see below) |
+
+### Synth parameters
+
+| Field | Default | Notes |
+|-------|---------|-------|
+| `type` | harmonic | Only `harmonic` supported currently |
+| `duration` | — | Duration in seconds |
+| `fundamental` | — | Fundamental frequency in Hz |
+| `harmonics` | [] | List of `{"freq": Hz, "db": dB}` objects |
+| `attack_ms` | 10 | Attack time in milliseconds |
+| `sustain_ratio` | 0.2 | Fraction of duration at full level before decay |
+| `decay` | exponential | `exponential` or `linear` |
+
+## Single Asset Workflow
+
+For one-off generation or iteration on a specific asset:
+
+1. Find the asset in `docs/assets/audio/{ambient,sfx,ui}.md` — note filename,
+   duration, bus, method, and design intent.
+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
+   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`.
+
+## Iteration Workflow
+
+For each asset, generate 4-6 candidates:
+
+1. **Generate candidates** — vary the prompt slightly (add/remove descriptors,
+   adjust CFG between 5-9). Run each generation sequentially — never in
+   parallel.
+2. **Solo test** — does each candidate sound right alone?
+3. **Stack test** — play the candidate alongside other layers. Does it mask or
+   clash?
+4. **Fatigue test** (loops only) — can you listen for 5+ minutes without a
+   jarring repeat?
+5. **Close-your-eyes test** — does it create a mental image or sensation?
+6. Select the best candidate (post-processing is already done if `--post` was
+   used).
+
+## Post-Processing (Standalone)
+
+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
+
+# 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
+```
+
+## Manual Synthesis (Insert-Tech Sounds)
+
+For sounds under 200ms (cursor hover, weapon aim), Stable Audio Open cannot
+produce meaningful output. Use manual synthesis via `tooling/synth_ui_sounds.py`
+or the batch manifest's `method: "synth"` with harmonic parameters.
+
+For complex synthesis beyond the `harmonic` type (FM, filtered noise, bandpass
+impulse), write a custom script in `tooling/` following the pattern in
+`tooling/synth_ui_sounds.py`.
+
+## Quality Checklist
+
+After generating, verify:
+- Sound matches the sonic family (insert-tech = synthetic/precise, organic = warm/natural)
+- Frequency range doesn't mask other layers (check docs/assets/audio/)
+- Duration matches spec
+- No unwanted artifacts (clicks, pops, digital noise at start/end)
+- Loop point is clean (ambient loops only)
+- Volume sits well relative to other assets (LUFS normalized)
+- Passes the close-your-eyes test
+
+## File Placement
+
+Generated assets go to `client/assets/audio/` with exact filenames from the
+asset docs. Intermediates go to `client/assets/audio/gen/` (gitignored).
+
+AudioManager discovers assets by directory scan — filenames must match exactly.
@@ -0,0 +1,67 @@
+# Category Templates — Audio Generation
+
+Match the asset's category to the right template. Append after the sonic family
+prefix and before the specific asset description.
+
+## Ambient Loops
+
+**Template:**
+> Continuous ambient soundscape loop, seamless looping audio, no distinct
+> beginning or end, steady background atmosphere, [DURATION]s duration
+
+**Notes:**
+- Generate at 45s (the SAO sweet spot below the 47s ceiling)
+- Add 3-5s of overlap material for crossfade looping in post
+- These play continuously — they must be boring enough to fade into the
+  background but rich enough to reward attention
+- Station baseline prefix is required (see sonic-palette.md)
+
+**Steps:** 100-150 (higher quality for loops — artifacts are more noticeable)
+**CFG:** 5-7 (lower guidance = more natural variation, less mechanical)
+
+## Sound Effects (SFX)
+
+**Template:**
+> Single isolated sound effect, clean recording, [DURATION] duration,
+> clear attack and natural decay, no background noise, no reverb tail
+> beyond natural
+
+**Notes:**
+- For footsteps: specify surface material, pace, weight
+- For environmental: specify the physical mechanism (door hinge, cargo latch)
+- Keep short and punchy — these are event-driven, not continuous
+
+**Steps:** 80-100 (shorter sounds need fewer steps)
+**CFG:** 7-9 (more guidance = more precise sound matching)
+
+## UI Sounds
+
+**Template:**
+> Interface feedback sound, digital UI element, [DURATION] duration,
+> immediate attack, clean decay, isolated sound with no background
+
+**Notes:**
+- Most UI sounds are under 200ms — use manual synthesis, not SAO
+- For SAO-generated UI sounds (>200ms like fog_recognition, chimes):
+  generate at 3-5s duration, then trim to the best portion
+- Insert-tech prefix is required for lattice/interface sounds
+- Organic prefix for fog_recognition (cognitive, not technological)
+
+**Steps:** 80-100
+**CFG:** 7-9 (precision matters for UI sounds)
+
+## Chimes / Notification Sounds
+
+**Template:**
+> Single musical tone, crystalline quality, [DURATION] duration, gentle
+> attack, resonant sustain, natural fade out, no accompaniment, no rhythm
+
+**Notes:**
+- Generate at 3-5s to give SAO enough temporal context
+- Trim to the best 0.5-1.0s section
+- The attack transient is where the character lives — select for that
+- Normal vs urgent variants: same base prompt, vary "gentle/soft" vs
+  "brighter/sharper/more present"
+
+**Steps:** 100 (tonal quality matters)
+**CFG:** 6-8 (some freedom for natural harmonic content)
@@ -0,0 +1,45 @@
+# Sonic Palette — Prompt Prefixes
+
+Two sonic families. Every generated sound uses one of these as a prompt prefix.
+
+## Insert-Tech (Synthetic)
+
+For UI sounds, neural lattice interface, augmented cognition.
+
+**Prompt prefix:**
+> Clean digital audio, synthetic electronic tone, precise and clinical sound
+> design, no reverb, no room ambience, studio-dry recording, futuristic
+> interface sound
+
+**Character:** Mathematical precision. The sound of well-designed technology.
+No organic texture, no room reflections. Exists "inside the head," not in
+physical space.
+
+**Frequency range:** 800Hz-4kHz primary. Sharp attack, controlled decay.
+
+**Used for:** cursor_hover, implant_open, weapon_aim, sfx_monologue_chime,
+sfx_monologue_chime_urgent
+
+## Organic (Biological/Environmental)
+
+For environmental sounds, human cognition, physical world.
+
+**Prompt prefix:**
+> Warm organic audio, natural sound recording, slight room ambience,
+> lived-in industrial space, realistic acoustic properties, authentic
+> environmental sound
+
+**Character:** Human warmth. Natural attack and decay. Reverberant — exists
+in physical space. The sound of a real place with real materials.
+
+**Frequency range:** 60Hz-3kHz primary. Soft or natural attack, room tail.
+
+**Used for:** fog_recognition, all amb_* ambient loops, all sfx_footstep_*
+
+## Station Baseline
+
+For ambient loops specifically, add the station context:
+
+> Interior of a large industrial space station, metal and composite
+> construction, background mechanical hum from power systems, air circulation
+> audible, no music, no prominent voices unless specified
@@ -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
+db/connectors/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.
@@ -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.
@@ -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 |
@@ -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 }
+```
@@ -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"
@@ -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)"
@@ -0,0 +1,55 @@
+---
+name: docs-search
+description: >
+  Search project documents using semantic search (Qdrant + ollama) or grep fallback.
+  Use when the user asks "did we discuss X?", "find references to Y", "search docs",
+  or invokes /docs-search. Wraps the qdrant_connector.py for semantic document search.
+user-invocable: true
+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.
+
+## Advanced Commands
+
+### Index a single chunk
+
+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"
+```
+
+### Create collection
+
+Initialize the Qdrant collection (run once during setup):
+```bash
+python3 db/connectors/qdrant_connector.py create-collection
+```
+
+## Bulk Indexing
+
+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"
+done
+```
+
+## Fallback
+
+If Qdrant or ollama is unreachable, fall back to grep-based search:
+```bash
+grep -r -i "search term" decisions/ DISCUSSION.md docs/ --include="*.md"
+```
+
+## Workflow
+
+1. **Qatux (Librarian)** is the primary user of this skill
+2. After each discussion round, index the archived round file
+3. After briefing updates, re-index affected briefings
+4. After decision changes, re-index the relevant decisions/*.md domain files
+5. Use search to answer "did we discuss this?" questions with citations
@@ -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.
@@ -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 |
@@ -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
+    }
+  }
+}
+```
@@ -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 |
@@ -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
@@ -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
@@ -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()
@@ -1,8 +1,8 @@
 ---
-name: commit
+name: git-commit
 description: >
  Commit changes with clean, structured messages. Use when the user says
-  "commit", "save my work", "commit changes", or invokes /commit. Enforces
+  "commit", "save my work", "commit changes", or invokes /git-commit. Enforces
  conventional commit format, groups changes into logical commits, and maintains
  CHANGELOG.md. Never squash unrelated changes into one commit.
 user-invocable: true
@@ -1,5 +1,5 @@
 ---
-name: asset-gen
+name: image-gen
 description: >
  Generate themed visual assets for the Lords of Ash CK3 total conversion mod
  using the generate_image MCP tool (Nano Banana / Gemini 2.5 Flash Image).
@@ -1,127 +0,0 @@
---
-name: plan-sprint
-description: >
-  Plan the next sprint and generate team briefing files. Use when the user says
-  "plan sprint", "prep sprint briefing", "plan next sprint", "sprint planning",
-  or invokes /plan-sprint. Gathers current sprint status, scans the backlog,
-  proposes ticket selection, and writes briefing files per team to
-  docs/sprints/sprint-N/.
-user-invocable: true
-allowed-tools: Bash, Read, Grep, Glob, Write, AskUserQuestion
---
-
-# Plan Sprint
-
-Generate sprint briefing files (`server.md`, `client.md`, `joint.md`) for the
-next sprint based on current project state.
-
-## Workflow
-
-### 1. Determine sprint number
-
-```bash
-db/connectors/ticket sprint --active
-```
-
-Next sprint = active sprint ID + 1. If no active sprint, ask the user.
-
-### 2. Gather current sprint state
-
-Review the active sprint for carry-overs:
-
-```bash
-db/connectors/ticket list --sprint <current_id> --status in_progress
-db/connectors/ticket list --sprint <current_id> --status ready
-```
-
-Any ticket not `done` is a potential carry-over. Note these for the briefing.
-
-### 3. Scan the backlog
-
-Pull candidate tickets by priority:
-
-```bash
-db/connectors/ticket epics --status backlog
-```
-
-For critical epics, check their children:
-
-```bash
-db/connectors/ticket children <epic_id>
-```
-
-Use `ticket show --brief <id> [<id>...]` to quickly scan multiple tickets.
-
-### 4. Read existing code state
-
-Scan what's already built to write accurate "what exists" notes:
-
-```bash
-# Server modules
-ls server/src/ server/src/*/
-
-# Client scripts
-ls client/scripts/ client/scripts/*/
-```
-
-Read key files that sprint tickets will build on (bridge types, existing
-renderers, etc.) to reference specific integration points in the briefing.
-
-### 5. Select tickets — propose to user
-
-Based on the backlog scan, propose a sprint with:
-
- **Sprint theme** — a short name (Sprint 1 was "Run", Sprint 2 was "See")
- **Sprint goal** — one sentence shared across all teams
- **Server tickets** — stories from server-side epics
- **Client tickets** — stories from client-side epics
- **Joint tasks** — integration proofs, pre-sprint decisions, schema work
-
-Present the proposal using AskUserQuestion for the user to approve or adjust.
-
-Selection heuristics:
- Follow dependency chains (don't pick a ticket if its blocker isn't in scope)
- Respect D-030 test priority phases (sprint 1-2: infra, sprint 3-4: integration)
- Mix carry-overs with new work
- Aim for 3-6 tickets per team, with parallel tracks where possible
- Check `decisions/questions.md` for open Q-NNN items that block candidates
-
-### 6. Read relevant decisions
-
-For the selected tickets, identify which `decisions/*.md` files are relevant.
-Read them to provide accurate cross-references in the briefing.
-
-### 7. Write briefing files
-
-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.
-
-Key requirements per file:
- **server.md**: Carry-overs, new tickets, dependency chain, key decisions, notes
-  referencing existing Rust modules by path
- **client.md**: Same structure, notes referencing existing GDScript files by path
- **joint.md**: Pre-sprint decisions table, integration tickets, sprint
-  completion proof (concrete observable criteria), test plan alignment
-
-### 8. Assign tickets to sprint in DB
-
-After the user approves, assign all selected tickets to the new sprint:
-
-```bash
-# Create the sprint
-db/connectors/sqlite-exec "INSERT INTO sprints (name, goal, status) VALUES ('Sprint N: Theme', 'goal', 'planned')"
-
-# Assign tickets
-db/connectors/ticket sprint assign <ticket_id> <sprint_id>
-```
-
-### 9. Present summary
-
-Output:
- Sprint number, theme, and goal
- Ticket count per team
- Carry-over count
- Open questions that need early resolution
- Files written
@@ -0,0 +1,140 @@
+---
+name: pr-push
+description: >
+  Push commits and create or update a pull request. Use when the user says
+  "push pr", "push and create pr", "update pr", "create a pr", "open a pr",
+  or invokes /pr-push. NOT triggered by plain "push" (that's just git push).
+  Pushes the current branch, creates a PR if none exists, or confirms the
+  existing PR was updated. NEVER merges the PR into main — this skill only
+  pushes to the branch and manages the PR lifecycle.
+user-invocable: true
+allowed-tools: Bash, Read, Grep, Glob, AskUserQuestion, Skill
+---
+
+# Push PR Skill
+
+Push commits to remote and create or update a PR. Operates exclusively on the
+current branch — never touches main.
+
+## Safety Rules (NON-NEGOTIABLE)
+
+- **NEVER merge a PR into main.** No `tea pr merge`, no `git merge` into main.
+- **NEVER checkout or push to main.**
+- **NEVER force-push** unless the user explicitly requests it.
+- **NEVER use `--no-verify` or skip hooks.**
+- Only push to the current working branch.
+
+## Workflow
+
+### 1. Validate branch
+
+```bash
+git branch --show-current
+```
+
+If on `main`, stop: "You're on main. Switch to a team branch first."
+
+### 2. Commit uncommitted changes
+
+```bash
+git status
+```
+
+If there are uncommitted changes (staged or unstaged), run the **commit skill**
+first. Use the `/git-commit` skill to group changes into logical commits with
+proper conventional commit messages. Wait for commit to complete before
+proceeding.
+
+If the working tree is clean (no uncommitted changes), skip to step 3.
+
+### 3. Check for unpushed commits
+
+```bash
+git fetch --all
+git log --oneline origin/<branch>..<branch>
+```
+
+If no unpushed commits, skip to step 5 (PR check).
+
+### 4. Check for conflicts with main
+
+```bash
+git merge-tree --write-tree origin/main HEAD 2>&1
+```
+
+If conflicts reported, merge main into current branch:
+
+```bash
+git merge origin/main --no-edit
+```
+
+If merge conflicts, **stop and report** — let the user resolve.
+If clean, continue.
+
+### 5. Push
+
+```bash
+git push origin <branch>
+```
+
+If push fails, stop and report. Never force-push without explicit request.
+
+### 6. Check for existing PR
+
+```bash
+tea pr list --login schweitz --repo jpmschweitzer/settled-reach --state open --output simple
+```
+
+Match current branch name in PR list.
+
+- **PR exists**: Report "Pushed N commits to `<branch>`. PR #X updated." Done.
+- **No PR**: Continue to step 7.
+
+### 7. Create a new PR
+
+```bash
+git log --oneline main..<branch>
+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)" \
+  --base main \
+  --head <branch>
+```
+
+Report PR URL when done.
+
+### 8. Update ticket status to review
+
+Scan all commit messages in the PR for ticket references (`#NNN`):
+
+```bash
+git log --oneline main..<branch>
+```
+
+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
+```
+
+Report which tickets were moved to review. Skip tickets that are
+already `done`, `review`, `cancelled`, or `backlog` (only transition
+`in_progress` → `review`).
+
+## Arguments
+
+If the user passes arguments (e.g., `/pr-push "my title"`), use them as the
+PR title instead of generating one.
@@ -0,0 +1,218 @@
+---
+name: pr-review
+description: >
+  Review a branch diff with team-appropriate agents before merge. Use when the
+  user says "review-pr", "review this PR", "review this branch", or invokes
+  /pr-review. Spawns reviewers matched to the branch type (code, copy, visual,
+  audio) in parallel. Reports approve/reject with inline comments.
+user-invocable: true
+allowed-tools: Bash, Read, Grep, Glob, Task
+---
+
+# PR Review Skill
+
+Multi-agent review of a branch diff against main. Reviewer composition depends
+on the branch type. All reviewers must approve for a clean review.
+
+## Workflow
+
+### 1. Determine the branch
+
+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.
+
+To list open PRs on Gitea:
+```bash
+tea pr list --login schweitz --repo jpmschweitzer/settled-reach --state open --output simple
+```
+
+Fetch remote branches first:
+```bash
+git fetch --all
+```
+
+### 2. Determine reviewer team
+
+Map the branch name to a reviewer set. Use the branch prefix (before any `/`
+or `-` suffix) to classify:
+
+| Branch type | Branches | Reviewers |
+|-------------|----------|-----------|
+| **code** | `server`, `client`, `ci`, or unknown | Hoshe (code quality) + Tyre (architecture) |
+| **copy** | `copy` | Hoshe (QA) + Paula (narrative depth) + Miri (world consistency) |
+| **visual** | `visual` | Hoshe (QA) + Araminta (art direction) |
+| **audio** | `audio` | Hoshe (QA) + Ozzie (player experience) |
+
+If the branch name doesn't match any known type, default to **code** reviewers.
+
+### 3. Generate the diff and read source files
+
+```bash
+git log --oneline main..<branch>
+git diff main...<branch> --stat
+```
+
+If the diff is empty, report "No changes to review" and stop.
+
+**Exclude generated/vendor files from the review diff.** Common exclusions:
+- `Cargo.lock` (auto-generated)
+- `client/addons/gdUnit4/` (vendor test framework)
+- `*.uid` (Godot-generated)
+- `docs/backups/settledreach.db.backup` (binary)
+
+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 worktree (see below).
+
+For large diffs (>1000 lines of source), provide **source files** rather than
+raw diff to reviewers — cleaner context, better reviews.
+
+**IMPORTANT — use worktree paths for ALL agents.** This project uses git
+worktrees. Each team branch is checked out at:
+
+```
+/var/home/jeroenschweitzer/Projects/settled-reach/<branch>/
+```
+
+For example, the `copy` branch lives at:
+```
+/var/home/jeroenschweitzer/Projects/settled-reach/copy/content/dialogue/...
+```
+
+**All reviewer agents** (regardless of Bash access) should read source files
+from the worktree path 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
+worktree path. Example instruction for agents:
+
+```
+Read the changed files from the branch worktree. The branch is checked
+out at: /var/home/jeroenschweitzer/Projects/settled-reach/<branch>/
+
+For example, to read `content/dialogue/the-terminal/kael-davan.yaml`,
+use: /var/home/jeroenschweitzer/Projects/settled-reach/<branch>/content/dialogue/the-terminal/kael-davan.yaml
+```
+
+Also tell agents to read relevant `decisions/*.md` files from the same
+worktree (they're identical to main, but using the worktree path keeps
+agents grounded in the correct directory).
+
+### 4. Spawn reviewers in parallel
+
+Use the Task tool to spawn **all reviewers simultaneously** in a single message.
+
+Read `references/reviewer-profiles.md` for the full per-branch-type reviewer
+specifications (agent types, models, prompt focus areas). Match the branch type
+from step 2 to the corresponding section.
+
+All reviewers: request structured verdict: APPROVE or REQUEST_CHANGES with
+file-specific comments.
+
+### 5. Present results
+
+Format the combined review as a table per reviewer. Include one section per
+reviewer that was spawned (2 for code/visual/audio, 3 for copy):
+
+```
+## Review: <branch> -> main  (type: code|copy|visual|audio)
+
+### <Reviewer Name> (<Focus>): [APPROVE | REQUEST_CHANGES]
+[Summary]
+| # | File | Severity | Issue |
+|---|------|----------|-------|
+| 1 | path:line | critical/warning/suggestion | description |
+
+### <Reviewer Name> (<Focus>): [APPROVE | REQUEST_CHANGES]
+...
+
+### Verdict: [APPROVED | CHANGES REQUESTED]
+```
+
+The overall verdict is APPROVED only if **all** reviewers approve.
+
+## Prompt template for reviewers
+
+Use this structure when constructing the agent prompts (adapt as needed):
+
+```
+Review the following {branch_type} branch diff for merge into main.
+
+Branch: {branch}
+Branch type: {branch_type} (code|copy|visual|audio)
+Commits:
+{commit_log}
+
+Diff stats:
+{diff_stat}
+
+[Source files or diff here — exclude vendor/generated code]
+
+Your review focus: {focus_area}
+
+Respond with:
+1. Verdict: APPROVE or REQUEST_CHANGES
+2. Summary: 2-3 sentence overall assessment
+3. Comments: List of specific issues, each with:
+   - File path and approximate location
+   - Severity: critical / warning / suggestion
+   - Description of the issue
+
+Verdict rules:
+- Any **critical** or **warning** issue → REQUEST_CHANGES
+- Only **suggestion**-level issues (or none) → APPROVE
+If no issues found, say APPROVE with a brief positive summary.
+```
+
+## 6. Posting results to Gitea
+
+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)`:
+
+```
+# 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
+
+`tea pr merge` fails (405) when branches have conflicts with main. Merge
+locally instead:
+
+```bash
+git fetch --all
+git merge origin/<branch>        # resolve conflicts if any
+git push origin main
+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.
+
+## Tips from practice
+
+- **Vendor code**: Explicitly note vendor code in the prompt so reviewers focus
+  on project code. Mention it as a separate architectural concern (should it be
+  gitignored? submoduled?).
+- **Large PRs**: For PRs touching many files, provide file-by-file source code
+  rather than a single massive diff. Reviewers give better feedback.
+- **Multiple PRs**: When reviewing several PRs, spawn all reviewers in one
+  parallel batch (4 agents for 2 PRs). This is faster than sequential.
+- **Tyre reads decisions**: Always tell Tyre to read the relevant `decisions/*.md`
+  files — this grounds the review in project-specific architectural choices.
+- **Binary/DB files**: Exclude binary files from the diff. Note them in the
+  prompt as "also changed" if relevant.
@@ -0,0 +1,113 @@
+# Reviewer Profiles by Branch Type
+
+Use `model: sonnet` for all reviewers — sufficient for review, saves cost.
+
+**All agents read from worktree paths.** Each branch is checked out at:
+`/var/home/jeroenschweitzer/Projects/settled-reach/<branch>/`
+
+Tell every reviewer agent to read source files from the worktree using the
+Read tool. Include the worktree base 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 worktree.
+
+## Code reviews (`server`, `client`, `ci`)
+
+**Hoshe (Code Quality)**
+- `subagent_type`: `hoshe`, `model`: `sonnet`
+- Prompt: Provide the worktree path, list of changed files, and commit log.
+  Tell Hoshe to read source files from the worktree, then review for:
+  - Correctness and bug risks
+  - Error handling gaps
+  - Test coverage (are new features tested?)
+  - Code style and clarity
+  - Security concerns (OWASP top 10, injection risks)
+  - Performance issues
+
+**Tyre (Architecture)**
+- `subagent_type`: `tyre`, `model`: `sonnet`
+- Prompt: Provide the worktree path, list of changed files, and commit log.
+  Tell Tyre to read the relevant `decisions/*.md` files from the worktree
+  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)
+
+## Copy reviews (`copy`)
+
+**Hoshe (QA)**
+- `subagent_type`: `hoshe`, `model`: `sonnet`
+- Prompt: Provide the worktree path, list of changed files, and commit log.
+  Tell Hoshe to read the changed files from the worktree, 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)**
+- `subagent_type`: `paula`, `model`: `sonnet`
+- Prompt: Provide the worktree path, list of changed files, commit log, and
+  list of relevant `decisions/*.md` files to read. Tell Paula to read all
+  files from the worktree 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)**
+- `subagent_type`: `miri`, `model`: `sonnet`
+- Prompt: Provide the worktree path, list of changed files, commit log, and
+  list of relevant `decisions/*.md` files to read. Tell Miri to read all
+  files from the worktree 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
+  - Faction, technology, and location details match the worldbuilding docs
+  - Setting serves gameplay mechanics (asymmetric information, perception)
+
+## Visual reviews (`visual`)
+
+**Hoshe (QA)**
+- `subagent_type`: `hoshe`, `model`: `sonnet`
+- Prompt: Provide the worktree path, list of changed files, and commit log.
+  Tell Hoshe to read the changed files from the worktree, 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)**
+- `subagent_type`: `araminta`, `model`: `sonnet`
+- Prompt: Provide the worktree 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
+
+## Audio reviews (`audio`)
+
+**Hoshe (QA)**
+- `subagent_type`: `hoshe`, `model`: `sonnet`
+- Prompt: Provide the worktree path, list of changed files, and commit log.
+  Tell Hoshe to read the changed files from the worktree, 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)**
+- `subagent_type`: `ozzie`, `model`: `sonnet`
+- Prompt: Provide the worktree path, list of changed files, and commit log.
+  Tell Ozzie to read all files from the worktree using the Read tool, then
+  review for:
+  - Emotional impact — does the audio enhance the moment?
+  - Atmosphere and tone — does it feel like the Commonwealth?
+  - 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?
@@ -1,193 +0,0 @@
---
-name: review-pr
-description: >
-  Review a branch diff with dual agents before merge. Use when the user says
-  "review-pr", "review this PR", "review this branch", or invokes /review-pr.
-  Spawns Hoshe (code quality) and Tyre (architecture) in parallel to review
-  the diff against main. Reports approve/reject with inline comments.
-user-invocable: true
-allowed-tools: Bash, Read, Grep, Glob, Task
---
-
-# PR Review Skill
-
-Dual-agent review of a branch diff against main. Hoshe reviews code quality,
-Tyre reviews architecture. Both must approve for a clean review.
-
-## Workflow
-
-### 1. Determine the branch
-
-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.
-
-To list open PRs on Gitea:
-```bash
-tea pr list --login schweitz --repo jpmschweitzer/settled-reach --state open --output simple
-```
-
-Fetch remote branches first:
-```bash
-git fetch --all
-```
-
-### 2. Generate the diff
-
-```bash
-git log --oneline main..<branch>
-git diff main...<branch> --stat
-```
-
-If the diff is empty, report "No changes to review" and stop.
-
-**Exclude generated/vendor files from the review diff.** Common exclusions:
- `Cargo.lock` (auto-generated)
- `client/addons/gdUnit4/` (vendor test framework)
- `*.uid` (Godot-generated)
- `db/commonwealth.db` (binary)
-
-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. Have Tyre read source files directly from the branch:
-   `git show origin/<branch>:<path>`
-
-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.
-
-### 3. Spawn both reviewers in parallel
-
-Use the Task tool to spawn **two agents simultaneously** in a single message.
-Use `model: sonnet` for both — sufficient for review, saves cost.
-
-**Agent 1 — Hoshe (Code Quality)**
- `subagent_type`: `hoshe`
- `model`: `sonnet`
- Prompt: Include source code and commit log. Ask Hoshe to review for:
-  - Correctness and bug risks
-  - Error handling gaps
-  - Test coverage (are new features tested?)
-  - Code style and clarity
-  - Security concerns (OWASP top 10, injection risks)
-  - Performance issues
- Request structured verdict: APPROVE or REQUEST_CHANGES with file-specific comments
-
-**Agent 2 — 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:
-  - 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>`
- Request structured verdict: APPROVE or REQUEST_CHANGES with file-specific comments
-
-### 4. Present results
-
-Format the combined review as a table per reviewer:
-
-```
-## Review: <branch> -> main
-
-### Hoshe (Code Quality): [APPROVE | REQUEST_CHANGES]
-[Summary]
-| # | File | Severity | Issue |
-|---|------|----------|-------|
-| 1 | path:line | critical/warning/suggestion | description |
-
-### Tyre (Architecture): [APPROVE | REQUEST_CHANGES]
-[Summary]
-| # | File | Severity | Issue |
-|---|------|----------|-------|
-| 1 | path:line | critical/warning/suggestion | description |
-
-### Verdict: [APPROVED | CHANGES REQUESTED]
-```
-
-The overall verdict is APPROVED only if **both** reviewers approve.
-
-## Prompt template for reviewers
-
-Use this structure when constructing the agent prompts (adapt as needed):
-
-```
-Review the following branch diff for merge into main.
-
-Branch: {branch}
-Commits:
-{commit_log}
-
-Diff stats:
-{diff_stat}
-
-[Source files or diff here — exclude vendor/generated code]
-
-Review focus: {focus_area}
-
-Respond with:
-1. Verdict: APPROVE or REQUEST_CHANGES
-2. Summary: 2-3 sentence overall assessment
-3. Comments: List of specific issues, each with:
-   - File path and approximate location
-   - Severity: critical / warning / suggestion
-   - Description of the issue
-If no issues found, say APPROVE with a brief positive summary.
-```
-
-## Posting results to Gitea
-
-After presenting results to the user, post the review as a PR comment:
-
-```bash
-tea comment --login schweitz --repo jpmschweitzer/settled-reach <PR_NUMBER> "<review markdown>"
-```
-
-Use a heredoc for multi-line review bodies:
-```bash
-tea comment --login schweitz --repo jpmschweitzer/settled-reach <PR_NUMBER> "$(cat <<'REVIEW'
-## Dual-Agent Review: <branch> -> main
-...review content...
-REVIEW
-)"
-```
-
-Note: `tea pr reject` does not work on your own PRs. Use `tea comment` instead.
-
-**Heredoc bodies hang** in `tea comment`. Write review to a temp file instead:
-```bash
-# Write review to temp file, then pass via cat
-tea comment --login schweitz --repo jpmschweitzer/settled-reach <PR_NUMBER> "$(cat /tmp/review.md)"
-```
-
-## Merging approved PRs
-
-`tea pr merge` fails (405) when branches have conflicts with main. Merge
-locally instead:
-
-```bash
-git fetch --all
-git merge origin/<branch>        # resolve conflicts if any
-git push origin main
-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.
-
-## Tips from practice
-
- **Vendor code**: Explicitly note vendor code in the prompt so reviewers focus
-  on project code. Mention it as a separate architectural concern (should it be
-  gitignored? submoduled?).
- **Large PRs**: For PRs touching many files, provide file-by-file source code
-  rather than a single massive diff. Reviewers give better feedback.
- **Multiple PRs**: When reviewing several PRs, spawn all reviewers in one
-  parallel batch (4 agents for 2 PRs). This is faster than sequential.
- **Tyre reads decisions**: Always tell Tyre to read the relevant `decisions/*.md`
-  files — this grounds the review in project-specific architectural choices.
- **Binary/DB files**: Exclude binary files from the diff. Note them in the
-  prompt as "also changed" if relevant.
@@ -1,98 +0,0 @@
---
-name: search-docs
-description: >
-  Search project documents using semantic search (Qdrant + ollama) or grep fallback.
-  Use when the user asks "did we discuss X?", "find references to Y", "search docs",
-  or invokes /search-docs. Wraps the qdrant_connector.py for semantic document search.
-user-invocable: true
-allowed-tools: Bash, Read, Grep, Glob
---
-
-# Search Docs Skill
-
-Semantic search across Commonwealth project documents using Qdrant vector database and ollama embeddings.
-
-## Access Method
-
-**Use the connector script:**
-```bash
-python3 db/connectors/qdrant_connector.py <command> [args]
-```
-
-## Commands
-
-### Search
-Find documents semantically related to a query:
-```bash
-python3 db/connectors/qdrant_connector.py search "asymmetric information design"
-python3 db/connectors/qdrant_connector.py search "what did we decide about fog of war"
-python3 db/connectors/qdrant_connector.py search "engine requirements"
-```
-
-Returns top 5 matching document chunks with source file, heading, and relevance score.
-
-### Index a file
-Add or update a document in the search index:
-```bash
-python3 db/connectors/qdrant_connector.py index-file decisions/architecture.md
-python3 db/connectors/qdrant_connector.py index-file decisions/perception.md
-python3 db/connectors/qdrant_connector.py index-file docs/discussions/round-10-map-fog-borderless.md
-python3 db/connectors/qdrant_connector.py index-file docs/briefings/tyre.md
-```
-
-Files are chunked by markdown headings (# and ##). Each chunk is embedded via ollama and stored in Qdrant with metadata (source_file, heading, chunk_index).
-
-### Index a single chunk
-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"
-```
-
-### Health check
-Verify connectivity to Qdrant and ollama:
-```bash
-python3 db/connectors/qdrant_connector.py health
-```
-
-### Collection info
-Check how many documents are indexed:
-```bash
-python3 db/connectors/qdrant_connector.py count
-```
-
-### Create collection
-Initialize the Qdrant collection (run once during setup):
-```bash
-python3 db/connectors/qdrant_connector.py create-collection
-```
-
-## Endpoints
-
-Configured in `db/connectors/config.json`:
- **Qdrant:** `http://tower-of-joy:6333`
- **Ollama:** `http://tower-of-joy:11434` (model: nomic-embed-text)
- **Collection:** `commonwealth` (768 dimensions, cosine distance)
-
-## Fallback
-
-If Qdrant or ollama is unreachable, fall back to grep-based search:
-```bash
-# Search across all project docs
-grep -r -i "search term" decisions/ DISCUSSION.md docs/ --include="*.md"
-```
-
-## Workflow
-
-1. **Qatux (Librarian)** is the primary user of this skill
-2. After each discussion round, index the archived round file
-3. After briefing updates, re-index affected briefings
-4. After decision changes, re-index the relevant decisions/*.md domain files
-5. Use search to answer "did we discuss this?" questions with citations
-
-## Bulk indexing
-To index all project documents at once:
-```bash
-for f in decisions/*.md DISCUSSION.md TEAM.md docs/discussions/*.md docs/briefings/*.md; do
-  python3 db/connectors/qdrant_connector.py index-file "$f"
-done
-```
@@ -1,5 +1,5 @@
 ---
-name: create-skill
+name: skill-create
 description: >
  Guidance for creating effective Claude Code skills (.skill packages).
  Use when the user wants to create, build, design, or iterate on a skill —
@@ -178,7 +178,11 @@ For design patterns, consult:
 **Writing guidelines:** Always use imperative/infinitive form.

 **Frontmatter:**
- `name`: The skill name
+- `name`: The skill name — use **domain-action** naming: `{domain}-{action}`.
+  The domain is the system/area the skill operates on, the action is what it does.
+  Examples: `pr-review`, `sprint-plan`, `docs-search`, `git-commit`, `debt-scan`.
+  Multi-action wrappers (like `ticket`) can use the domain name alone.
+  The directory name must match the `name` field.
 - `description`: Primary triggering mechanism. Include what the skill does AND
  specific triggers/contexts. All "when to use" info goes here (not in body).

@@ -0,0 +1,173 @@
+---
+name: sprint-plan
+description: >
+  Plan the next sprint and generate team briefing files. Use when the user says
+  "plan sprint", "prep sprint briefing", "plan next sprint", "sprint planning",
+  or invokes /sprint-plan. Gathers current sprint status, scans the backlog,
+  proposes ticket selection, and writes briefing files per team to
+  docs/sprints/sprint-N/.
+user-invocable: true
+allowed-tools: Task, Read, Grep, Glob
+---
+
+# Plan Sprint
+
+**Delegate this entire skill to SI** (Project Manager agent, `subagent_type: si`).
+
+When this skill is invoked, spawn SI using the Task tool:
+
+```
+Task(
+  subagent_type: "si",
+  prompt: "Run /sprint-plan for Sprint N. Read the skill at
+    .claude/skills/sprint-plan/SKILL.md for the full workflow,
+    then execute it. Use the arguments provided: {args}",
+  description: "Plan sprint N"
+)
+```
+
+Pass through any arguments the user provided (e.g. sprint number).
+Present SI's output to the user when done. Do NOT run the workflow yourself.
+
+---
+
+The remainder of this file is SI's reference for executing the workflow.
+
+Generate sprint briefing files for each active team (e.g. `server.md`,
+`client.md`, `copy.md`, `joint.md`) for the next sprint based on current
+project state. Only generate briefings for teams that have tickets in the sprint.
+
+## Teams and Default Agents
+
+| Team | Branch | Default Agents | Focus |
+|------|--------|----------------|-------|
+| `server` | `server` | Dudley (dev), Tyre (arch), Hoshe (QA) | Rust/bevy_ecs simulation, ECS systems, knowledge graph, perception |
+| `client` | `client` | Stig (dev), Tyre (arch), Hoshe (QA) | Godot 4 client, rendering, UI, HUD, input handling |
+| `copy` | `copy` | Mellanie (author), Paula (narrative), Gestalt (systems) | Dialogue, monologue, UI text, knowledge vocabulary, lore |
+| `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 |
+
+When writing briefings, name the assigned agents in the **Agents** line of each
+file so the team knows who to spawn.
+
+## Workflow
+
+### 1. Run sprint prepare
+
+Get carry-overs, backlog candidates, and decision gaps in one shot:
+
+```bash
+db/connectors/sprint prepare
+```
+
+This auto-detects the next sprint number (max ID + 1), creates the sprint
+record in `planning` status if needed, and outputs:
+- Previous sprint status and carry-over candidates
+- Backlog candidates grouped by team
+- Decision coverage gaps
+- Already-assigned tickets (if any)
+
+### 2. Deepen the scan
+
+For critical epics, check their children for granular candidates:
+
+```bash
+db/connectors/ticket children <epic_id>
+```
+
+Use `db/connectors/ticket show --brief <id> [<id>...]` to quickly scan multiple tickets.
+
+### 3. Read existing code state
+
+Scan what's already built to write accurate "what exists" notes:
+
+```bash
+# Server modules
+ls server/src/ server/src/*/
+
+# Client scripts
+ls client/scripts/ client/scripts/*/
+```
+
+Read key files that sprint tickets will build on (bridge types, existing
+renderers, etc.) to reference specific integration points in the briefing.
+
+### 4. Select tickets — propose to user
+
+Based on the backlog scan, propose a sprint with:
+
+- **Sprint theme** — a short name (Sprint 1 was "Run", Sprint 2 was "See")
+- **Sprint goal** — one sentence shared across all teams
+- **Server tickets** — stories from server-side epics
+- **Client tickets** — stories from client-side epics
+- **Joint tasks** — integration proofs, pre-sprint decisions, schema work
+
+Present the proposal using AskUserQuestion for the user to approve or adjust.
+
+Selection heuristics:
+- Follow dependency chains (don't pick a ticket if its blocker isn't in scope)
+- Respect D-030 test priority phases (sprint 1-2: infra, sprint 3-4: integration)
+- Mix carry-overs with new work
+- Aim for 3-6 tickets per team, with parallel tracks where possible
+- Check `decisions/questions.md` for open Q-NNN items that block candidates
+
+### 5. Read relevant decisions
+
+For the selected tickets, identify which `decisions/*.md` files are relevant.
+Read them to provide accurate cross-references in the briefing.
+
+### 6. Write briefing files
+
+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:
+`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.
+
+Key requirements per file:
+- **server.md**: Carry-overs, new tickets, dependency chain, key decisions, notes
+  referencing existing Rust modules by path from worktree root (e.g. `server/src/simulation/movement.rs`)
+- **client.md**: Same structure, notes referencing existing GDScript files by path from worktree root (e.g. `client/scripts/rendering/fog.gd`)
+- **copy.md**: In-game text tasks — dialogue, UI copy, tooltips, flavor text, lore
+- **audio.md**: Sound design, music, audio integration tasks
+- **visual.md**: Art direction, asset creation, visual consistency tasks
+- **ci.md**: Build pipeline, CI/CD, tooling, infrastructure tasks
+- **joint.md**: Pre-sprint decisions table, integration tickets, sprint
+  completion proof (concrete observable criteria), test plan alignment
+
+Only generate briefing files for teams that have tickets assigned in the sprint.
+Not every sprint will have work for every team.
+
+### 7. Assign tickets to sprint in DB
+
+After the user approves, assign all selected tickets. The sprint record
+was already created by `sprint prepare` in step 1 (status: `planning`).
+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"
+
+# Assign tickets
+db/connectors/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.
+
+### 8. Present summary
+
+Output:
+- Sprint number, theme, and goal
+- Ticket count per team
+- Carry-over count
+- Open questions that need early resolution
+- Files written
@@ -0,0 +1,327 @@
+---
+name: sprint-start
+description: >
+  Manage the sprint lifecycle from main, or start sprint work on a team
+  branch. Use when the user says "start sprint", "start working on the
+  server/client/copy", "begin sprint", or invokes /sprint-start. On main:
+  assesses sprint state and does the next right thing (close, activate, or
+  guide). On a team branch: merges main, loads the briefing, presents the
+  work plan.
+user-invocable: true
+allowed-tools: Bash, Read, Grep, Glob, TeamCreate, Task, TaskCreate, TaskUpdate, TaskList, SendMessage, AskUserQuestion
+---
+
+# Start Sprint Skill
+
+Prepare a team branch for sprint work: sync with main, load the sprint
+briefing, and present actionable next steps.
+
+## Workflow
+
+### 1. Determine the team
+
+The current branch IS the team. Read it with:
+```bash
+git branch --show-current
+```
+
+Valid team branches: `server`, `client`, `copy`, `audio`, `visual`, `ci`.
+
+If on `main`, follow the **Main branch workflow** below instead of
+the team branch workflow (steps 2–8).
+
+---
+
+## Main branch workflow (sprint lifecycle management)
+
+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"
+```
+
+Then follow the **first matching case**:
+
+### Case A: An active sprint exists
+
+First, check whether the sprint's work is actually done:
+
+```bash
+db/connectors/sprint status
+```
+
+This shows ticket counts by status (done, in_progress, backlog).
+
+Also check for open PRs that may contain completed work waiting for
+review or merge:
+
+```bash
+tea pr list --login schweitz --repo jpmschweitzer/settled-reach --state open --output simple
+```
+
+Report the full picture to the user:
+- Ticket progress (done / in_progress / backlog counts)
+- Open PRs (if any — these represent work that's done but not merged)
+
+**If tickets remain unfinished** (in_progress or backlog) **or open PRs
+exist**, do NOT close the sprint. Instead, report the current progress
+and ask the user what they want to do:
+
+- **Continue working** — switch to a team branch and run `/sprint-start`
+  there to resume work
+- **Review & merge PRs first** — (only if open PRs exist) merge pending
+  work before deciding whether to close
+- **Close anyway** — proceed with the close workflow below (carries over
+  unfinished tickets)
+
+Use `AskUserQuestion` to confirm. Do not proceed to A1 unless the user
+explicitly chooses to close.
+
+#### A1. Close the active sprint
+
+```bash
+db/connectors/sprint stop
+```
+
+This marks the active sprint as completed and lists carry-over candidates.
+Note the sprint number (N) from the output.
+
+#### A2. Bump the version
+
+The project version scheme is `v0.1.{sprint_number}`. After closing
+sprint N, the version is `v0.1.N`.
+
+Update `project.yaml`:
+- Set the `version` field to `0.1.N` (this is the source of truth).
+
+Update `server/Cargo.toml`:
+- Set `version = "0.1.N"` in `[package]`.
+
+Update `CHANGELOG.md`:
+- Move all entries under `## [Unreleased]` into a new section
+  `## [v0.1.N] — YYYY-MM-DD` (using today's date).
+- Leave `## [Unreleased]` as an empty section above the new version.
+- Keep the existing sub-headings (Added, Fixed, Changed, Removed) —
+  only move entries that have content.
+
+#### A3. Commit the release
+
+Stage and commit `project.yaml`, `server/Cargo.toml`, and `CHANGELOG.md`:
+```
+chore(meta): release v0.1.N
+```
+
+#### A4. Tag the release
+
+```bash
+git tag v0.1.N
+```
+
+#### A5. Push
+
+```bash
+git push && git push --tags
+```
+
+#### A6. Check for a planned sprint
+
+After closing, re-query the database. If a sprint in `planning` status
+exists, continue to **Case B**. Otherwise, report the close and suggest
+running `/sprint-plan`.
+
+---
+
+### Case B: No active sprint, but a planned sprint exists
+
+A sprint is ready to activate. Verify it looks complete:
+
+1. Check that briefing files exist at `docs/sprints/sprint-N/`:
+   ```bash
+   ls docs/sprints/sprint-N/
+   ```
+2. Check the ticket count:
+   ```bash
+   db/connectors/sprint status --sprint N
+   ```
+
+If briefings are missing or the sprint has 0 tickets, report the gap
+and suggest running `/sprint-plan` to complete planning.
+
+If everything looks ready, activate the sprint:
+
+```bash
+db/connectors/sprint start
+```
+
+Then report:
+- Sprint activated (name, ticket count per team)
+- Remind the user to switch to a team branch and run `/sprint-start`
+  there (or `cd` into the relevant worktree)
+
+---
+
+### Case C: No active sprint and no planned sprint
+
+Nothing is ready. Report the state and suggest running `/sprint-plan`
+to plan the next sprint.
+
+---
+
+## Team branch workflow
+
+### 2. Sync with main
+
+```bash
+git fetch --all
+git merge origin/main --no-edit
+```
+
+If the merge has conflicts, report them and stop — do not force-resolve.
+
+### 3. Load sprint context
+
+Run the sprint CLI to get the full context dump in one shot:
+
+```bash
+db/connectors/sprint start-work
+```
+
+This auto-detects the active sprint and current team from the branch.
+It outputs: sprint metadata, briefing paths, decision refs, actionable
+tickets, blocked tickets, and done tickets.
+
+If no active sprint is found, report that and stop.
+
+### 4. Read the sprint briefing
+
+Read the briefing file(s) listed in the `start-work` output
+(e.g. `docs/sprints/sprint-6/server.md` and `joint.md`).
+If no matching briefing exists for the team, suggest running
+`/sprint-plan` to generate one.
+
+### 5. Load ticket details
+
+For tickets that need more detail than the `start-work` summary provides:
+```bash
+db/connectors/ticket show <id>
+```
+
+### 6. Read key decisions
+
+Read the decision files referenced in the sprint briefing so the agent has
+full architectural context before starting work.
+
+### 7. Mark tickets in progress and present the work plan
+
+Mark all actionable (unblocked, non-done) tickets in the sprint as
+`in_progress`:
+
+```bash
+db/connectors/ticket status <id> in_progress
+```
+
+Then output a summary:
+- Sprint name and goal
+- Branch status (clean merge or conflicts)
+- Tickets marked in_progress (list with IDs)
+- Blocked tickets (and what blocks them)
+- Key decisions loaded
+- Suggested first task (lowest ID unblocked ticket)
+
+### 8. Confirm and spawn the team
+
+Before spawning agents, use `AskUserQuestion` to confirm the work plan and
+agent lineup with the user. If declined, stop.
+
+Once confirmed:
+
+#### 8a. Parse agents from the briefing
+
+Extract agent names from the `**Agents:**` line. Format:
+```
+**Agents:** Name (role), Name (role), ...
+```
+
+Map each name to its `subagent_type` (lowercase):
+- "Dudley (simulation)" → `dudley`
+- "Stig (UI)" → `stig`
+- "Tyre (architecture)" → `tyre`
+- "Hoshe (QA)" → `hoshe`
+- "Mellanie (author)" → `mellanie`
+- etc. (see `.claude/agents/` for full roster)
+
+#### 8b. Create the team
+
+```
+TeamCreate(team_name: "sprint-{N}-{team}")
+```
+
+This makes you the team lead.
+
+#### 8c. Create tasks from tickets
+
+For each ticket in the briefing, create a task:
+
+```
+TaskCreate(
+  subject: "#{id}: {title}",
+  description: "Full ticket details from step 5, plus briefing notes
+    and integration points for this ticket.",
+  activeForm: "Working on #{id}: {short_title}"
+)
+```
+
+After creating all tasks, mirror the dependency chain from the briefing
+using `TaskUpdate` with `addBlockedBy`.
+
+#### 8d. Spawn agents
+
+For each agent from the `**Agents:**` line, spawn a teammate in the
+background. Spawn all agents in parallel (one message, multiple Task calls):
+
+```
+Task(
+  subagent_type: "{name_lowercase}",
+  team_name: "sprint-{N}-{team}",
+  name: "{name_lowercase}",
+  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.
+
+    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.
+
+    Use `db/connectors/ticket show <id>` for full ticket specs.",
+  description: "Sprint {N} {team}: {name}",
+  run_in_background: true
+)
+```
+
+#### 8e. Report
+
+Output to the user:
+- Team name: `sprint-{N}-{team}`
+- Agents spawned (names and roles)
+- Tasks created (count actionable vs blocked)
+- How to interact: `SendMessage` to talk to agents, `TaskList` to
+  check progress
+
+You are now the team lead. Agents work autonomously — monitor via
+`TaskList`, communicate via `SendMessage`, and handle blockers as
+they arise.
@@ -0,0 +1,55 @@
+---
+name: sprite-gen
+description: >
+  Render a 3D model to 2D sprites via the Godot render pipeline. Produces
+  sprites at 3 resolutions (1024, 256, 64) from 4 cardinal directions (north,
+  east, south, west) with outline applied at working resolution. Use when the
+  user says "render sprite", "render model", "run the render pipeline",
+  "test the pipeline", "/sprite-gen", or asks to render a specific model
+  (e.g., "render wall_structural"). Output: 12 PNG files in renderer/output/.
+---
+
+## Render Pipeline
+
+Run the render script with the model name:
+
+```bash
+.claude/skills/sprite-gen/scripts/render.sh <model_name>
+```
+
+### Available Models
+
+Models live at `renderer/models/<name>.tscn`. List them:
+
+```bash
+ls renderer/models/*.tscn | xargs -I{} basename {} .tscn
+```
+
+### Output
+
+12 files per model in `renderer/output/`:
+
+```
+<model>_north_1024.png   <model>_north_256.png   <model>_north_64.png
+<model>_east_1024.png    <model>_east_256.png    <model>_east_64.png
+<model>_south_1024.png   <model>_south_256.png   <model>_south_64.png
+<model>_west_1024.png    <model>_west_256.png    <model>_west_64.png
+```
+
+### After Rendering
+
+1. Read the 64x64 output files to visually inspect the runtime sprites
+2. Read the 256x256 files to check outline quality
+3. Report: does it read as the intended object at runtime scale?
+
+### Troubleshooting
+
+- **No output files**: Godot needs a display. If running headless, prefix with `xvfb-run`.
+- **Model not found**: Check the model .tscn exists in `renderer/models/`.
+- **Godot not found**: Pass path as second arg: `render.sh wall_structural /path/to/godot`
+
+### Adding New Models
+
+1. Create model scene at `renderer/models/<name>.tscn`
+2. Apply texture from `renderer/textures/` via StandardMaterial3D
+3. Run: `.claude/skills/sprite-gen/scripts/render.sh <name>`
@@ -0,0 +1,47 @@
+#!/bin/bash
+# Render a 3D model to 2D sprites at 3 resolutions from 4 cardinal directions.
+# Usage: render.sh <model_name> [godot_path]
+# Example: render.sh wall_structural
+set -euo pipefail
+
+MODEL_NAME="${1:?Usage: render.sh <model_name> [godot_path]}"
+GODOT="${2:-$HOME/bin/godot}"
+REPO_ROOT="$(cd "$(dirname "$0")" && git rev-parse --show-toplevel)"
+PROJECT="$REPO_ROOT/renderer"
+SCENE="res://render_scene.tscn"
+OUTPUT="$PROJECT/output"
+
+# Verify model exists
+MODEL_FILE="$PROJECT/models/${MODEL_NAME}.tscn"
+if [ ! -f "$MODEL_FILE" ]; then
+    echo "ERROR: Model not found: $MODEL_FILE"
+    echo "Available models:"
+    ls "$PROJECT/models/"*.tscn 2>/dev/null | xargs -I{} basename {} .tscn
+    exit 1
+fi
+
+echo "Rendering: $MODEL_NAME"
+echo "Godot: $GODOT"
+echo "Project: $PROJECT"
+
+# Ensure resources are imported (headless, no display needed)
+echo "Importing resources..."
+"$GODOT" --path "$PROJECT" --headless --import 2>&1 || echo "Warning: import step had errors (may be non-fatal)"
+
+# Run Godot with the render scene, passing model name as user arg
+"$GODOT" --path "$PROJECT" "$SCENE" -- "$MODEL_NAME" 2>&1
+
+# Check output
+EXPECTED_FILES=0
+for dir in north east south west; do
+    for res in 1024 256 64; do
+        f="$OUTPUT/${MODEL_NAME}_${dir}_${res}.png"
+        if [ -f "$f" ]; then
+            EXPECTED_FILES=$((EXPECTED_FILES + 1))
+        fi
+    done
+done
+
+echo ""
+echo "Generated $EXPECTED_FILES/12 files in $OUTPUT/"
+ls -la "$OUTPUT/${MODEL_NAME}"_*.png 2>/dev/null || echo "No output files found."
@@ -1,83 +0,0 @@
---
-name: start-sprint
-description: >
-  Start sprint work on a team branch. Use when the user says "start sprint",
-  "start working on the server/client", "begin sprint", or invokes /start-sprint.
-  Merges main into the team branch, finds the active sprint, reads the sprint
-  briefing, and presents the work plan with ticket details.
-user-invocable: true
-allowed-tools: Bash, Read, Grep, Glob
---
-
-# Start Sprint Skill
-
-Prepare a team branch for sprint work: sync with main, load the sprint
-briefing, and present actionable next steps.
-
-## Workflow
-
-### 1. Determine the team
-
-The current branch IS the team. Read it with:
-```bash
-git branch --show-current
-```
-
-Valid team branches: `server`, `client`. If on `main`, ask the user which
-team branch to check out first.
-
-### 2. Sync with main
-
-```bash
-git fetch --all
-git merge origin/main --no-edit
-```
-
-If the merge has conflicts, report them and stop — do not force-resolve.
-
-### 3. Find the active sprint
-
-```bash
-db/connectors/ticket sprint --active
-```
-
-Extract the sprint ID and name from the JSON output. If no active sprint,
-report that and stop.
-
-### 4. Read the sprint briefing
-
-Read `docs/sprints/sprint-N/<team>.md` where N is the sprint ID and team
-matches the branch name. If the branch is `server` or `client`, use that
-directly. For other branches, check if a matching briefing exists.
-
-Also check for a `joint.md` briefing — joint tasks involve both teams and
-should be mentioned.
-
-### 5. Load ticket details
-
-For each ticket listed in the briefing, run:
-```bash
-db/connectors/ticket show <id>
-```
-
-Identify which tickets are actionable now (no open blockers) vs blocked.
-
-### 6. Read key decisions
-
-Read the decision files referenced in the sprint briefing so the agent has
-full architectural context before starting work.
-
-### 7. Present the work plan
-
-Output a summary:
- Sprint name and goal
- Branch status (clean merge or conflicts)
- Actionable tickets (unblocked, ready to start)
- Blocked tickets (and what blocks them)
- Key decisions loaded
- Suggested first task (lowest ID unblocked ticket)
-
-Then mark the first actionable ticket as `in_progress`:
-```bash
-db/connectors/ticket status <id> in_progress
-```
@@ -10,42 +10,20 @@ allowed-tools: Bash, Read, Grep, Glob

 # Ticket Skill

-Manage the Commonwealth project ticketing database at `db/commonwealth.db`.
-
-## Access Method
-
-**Use the `ticket` CLI for all ticket operations:**
-```bash
-db/connectors/ticket <command> [args...]
-db/connectors/ticket --help
-```
-
-All output is JSON on stdout.
-
-For raw SQL access (rare), use the wrapper scripts:
-| Script | Purpose |
-|--------|---------|
-| `db/connectors/sqlite-query "<SQL>"` | Run SELECT queries |
-| `db/connectors/sqlite-exec "<SQL>"` | Run INSERT/UPDATE/DELETE |
-| `db/connectors/sqlite-init` | Create/update database from schema |
-| `db/connectors/sqlite-seed` | Seed initiatives from DECISIONS.md |
+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.

 ## Commands

-### List tickets
+### List tickets (full flags)
 ```bash
-db/connectors/ticket list [--status S] [--priority P] [--epic N] [--sprint N] [--assigned A]
+db/connectors/ticket list [--status S] [--priority P] [--epic N] [--sprint N] [--assigned A] [--team T]
 ```

-### Show ticket detail
-```bash
-db/connectors/ticket show <id>
-```
-Returns full ticket with children, blockers, and dependents.
-
 ### Create ticket
 ```bash
-db/connectors/ticket create <type> <title> [--parent N] [--priority P] [--decision D]
+db/connectors/ticket create <type> <title> [--parent N] [--priority P] [--decision D] [--team T]
 ```
 Types: `initiative`, `epic`, `story`, `task`, `bug`
 Priorities: `critical`, `high`, `medium`, `low`
@@ -63,12 +41,21 @@ db/connectors/ticket assign <id> <agent>
 db/connectors/ticket unassign <id>
 ```

+### Team assignment
+```bash
+db/connectors/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>
 ```

+For sprint-scoped operations (status overview, context dumps, lifecycle),
+use the dedicated sprint CLI instead: `db/connectors/sprint --help`
+
 ### Dependencies
 ```bash
 db/connectors/ticket deps <id>
@@ -82,6 +69,11 @@ db/connectors/ticket children <id>
 db/connectors/ticket count [--status S]
 ```

+### Batch show
+```bash
+db/connectors/ticket show --brief <id> [<id>...]
+```
+
 ## Workflow

 1. **SI (Project Manager)** is the primary user of this skill
@@ -0,0 +1,115 @@
+---
+name: workshop-start
+description: >
+  Start a multi-agent design workshop from a workshop brief. Use when the user says
+  "start workshop", "run workshop", "let's start the workshop", or invokes /workshop-start.
+  Parses the workshop brief to extract participants, questions, and round format.
+  Creates a team, tasks, and spawns agents as teammates via the Task tool.
+---
+
+# Start Workshop
+
+## Prerequisites
+
+A workshop brief must exist at `docs/workshops/{name}/{name}-workshop-brief.md` containing:
+- **Participants** line (comma-separated agent names)
+- **Questions for participants** sections with numbered questions tagged by agent name
+- **Workshop Format** section defining number of rounds and their purpose
+
+## Workflow
+
+### 1. Parse the Brief
+
+Read the workshop brief. Extract:
+- Workshop name (from directory name)
+- Participant list (from `**Participants:**` line)
+- Per-participant questions (scan for `**{AgentName}**:` patterns in questions sections)
+- Round count and round descriptions (from `**Workshop Format**` section)
+
+### 2. Create Team
+
+```
+TeamCreate: team_name = "{workshop-name}", description from brief title
+```
+
+### 3. Always-Present Agents
+
+Two agents join every workshop regardless of the participant list:
+
+| Agent | Role | Task | Participates in discussion? |
+|-------|------|------|-----------------------------|
+| **Qatux** | Documenter | Captures all decisions, questions, dissent, consensus. Writes `workshop-notes.md` per round, produces final `workshop-outcomes.md`. | No — observes and records only |
+| **SI** | Sprint prep | Suggest adding when outputs include tickets. Creates tickets from decisions, links to sprint backlog. | No — execution prep only |
+
+Qatux and SI are **never dismissed early.** If the user reduces the team mid-workshop, keep qatux and si (if added). Documenting everything prevents loss of valuable information.
+
+### 4. Create Tasks (Round 1)
+
+One task per participant containing:
+- Instruction to read the full brief at its path
+- The specific questions assigned to that participant (extracted from all layers)
+- The output format from the brief's round description
+- **IMPORTANT — file output requirement:** Instruct each agent to write their full output to `docs/workshops/{name}/{agent}-round{N}.md` (e.g., `docs/workshops/test-architecture/gestalt-round1.md`). Agents must write to disk, not just send messages. This ensures Qatux and other agents can read all outputs directly without relying on message forwarding.
+
+One task for Qatux: "Document Round N — read all agent output files at `docs/workshops/{name}/*-round{N}.md` and capture decisions, questions, and dissent."
+
+Assign all tasks using TaskUpdate with `owner` = agent name.
+
+### 5. Spawn Agents
+
+Use the Task tool to spawn each agent as a teammate. Each call should:
+- Set `team_name` to the workshop team name
+- Set `name` to the agent name (e.g., "gestalt")
+- Set `subagent_type` to the matching agent type (same as name — see reference table)
+- Provide a prompt telling the agent to check TaskList for their assigned task
+
+Spawn all agents in parallel (one Task call per agent in a single message). Agents will appear as teammates in the Claude Code UI and pick up their tasks from the shared task list.
+
+For large workshops (>6 agents), spawn participants in batches to avoid overwhelming the system. Always-present agents (Qatux, SI) can run in background via `run_in_background: true`.
+
+### 6. Monitor
+
+- TaskList to check progress
+- SendMessage to nudge idle agents or provide clarification
+- Agents work autonomously — claim tasks, read the brief, produce responses
+
+### 7. Between Rounds
+
+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
+
+### 8. Wrap Up
+
+**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.
+
+Wrap-up sequence:
+1. Qatux produces final `workshop-outcomes.md` from accumulated notes
+2. Qatux creates or updates diagrams (via `/d2-diagram`) for any new D-records produced by the workshop
+3. If SI is present, SI creates tickets from decided items
+4. Send shutdown_request to all agents (qatux and si last, after they finish their output tasks)
+5. TeamDelete to clean up
+
+## Agent Type Reference
+
+Agent name maps directly to subagent_type:
+
+| Name | Domain | Typical workshop role |
+|------|--------|-----------------------|
+| gestalt | Systems design | Mechanics, fun factor, system interactions |
+| ozzie | Player experience | Wow moments, feel, emotional response |
+| tyre | Technical architect | Feasibility, performance, architecture |
+| stig | UI developer | Interface patterns, layout, interaction flows |
+| dudley | Server developer | Server-side systems, data flow, ECS |
+| paula | Narrative | Story, dialogue, character, political depth |
+| araminta | Visual design | Art direction, visual treatment, aesthetics |
+| nigel | Replayability | Emergent stories, second-playthrough, sandbox |
+| gore | Themes/endgame | What the game is about, philosophical questions |
+| mellanie | Copywriter | In-game text, voice, tone |
+| miri | Worldbuilder | Setting, factions, lore, consistency |
+| inigo | Sound design | Audio, soundscape, spatial audio |
+| troblum | Tech consultant | Second opinion on architecture/tech choices |
+| hoshe | QA/testing | Test plans, verification, quality |
@@ -0,0 +1,125 @@
+---
+name: worktree-update
+description: >
+  Sync worktree branches with main. Use when the user says "update worktrees",
+  "sync branches", "merge main", "worktree update", or invokes /worktree-update.
+  When on main: shows which worktree branches are ahead and lets the user pick
+  which to merge into main (flags branches with open PRs). When on a non-main
+  branch: merges main into the current branch. All operations are non-destructive.
+user-invocable: true
+allowed-tools: Bash, Read, AskUserQuestion
+---
+
+# Worktree Update Skill
+
+Sync worktree branches safely. Direction depends on the current branch.
+
+## Safety Rules (NON-NEGOTIABLE)
+
+- **Never force-push, reset --hard, rebase, or delete branches.**
+- **Never use `--no-verify` or skip hooks.**
+- **Always use `--no-edit` on merges** to avoid interactive editor prompts.
+- **Stop on merge conflicts** — report them and let the user decide. Never
+  auto-resolve or abort a conflicted merge without asking.
+- **Fetch before comparing** — always `git fetch --all` first so commit
+  comparisons are accurate.
+- **Dry-run first on main** — show the user exactly what will happen before
+  merging anything into main.
+
+## Workflow
+
+### 1. Detect current branch
+
+```bash
+git branch --show-current
+```
+
+Branch determines the mode: `main` → outbound sync, anything else → inbound sync.
+
+### 2a. On `main` — merge worktree branches into main
+
+#### Fetch and compare
+
+```bash
+git fetch --all
+```
+
+Discover all worktree branches (excluding `main` itself):
+
+```bash
+git worktree list | grep -v '\[main\]' | sed 's/.*\[//;s/\]//'
+```
+
+For each worktree branch, check if it has commits ahead of main:
+
+```bash
+git rev-list --count main..origin/<branch>
+```
+
+Skip branches with 0 commits ahead. For branches that ARE ahead, collect:
+- Branch name
+- Number of commits ahead
+- One-line log of those commits: `git log --oneline main..<branch>`
+
+#### Check for open PRs
+
+```bash
+tea pr list --login schweitz --repo jpmschweitzer/settled-reach --state open --output simple
+```
+
+Cross-reference open PR head branches with the ahead-of-main branches.
+
+#### Present results
+
+Show a summary table of branches ahead of main. For each branch, indicate:
+- `[PR]` if it has an open pull request — warn that it should go through
+  normal review channels (use `/pr-review` instead)
+- Commit count and summary
+
+Use `AskUserQuestion` to let the user pick which branches to merge.
+Exclude PR-flagged branches from the default options (but allow the user to
+override via "Other").
+
+#### Merge selected branches
+
+For each selected branch, one at a time:
+
+```bash
+git merge <branch> --no-edit
+```
+
+If a merge conflicts, **stop immediately**. Report the conflict and do NOT
+continue to the next branch. The user must resolve before proceeding.
+
+After all merges, show the final state with `git log --oneline -N` (where N
+covers the new commits).
+
+#### Backup the shared database
+
+After successful merges on main, snapshot the database for git tracking:
+
+```bash
+make db-backup
+```
+
+This copies the shared `settledreach.db` (in the parent directory) to
+`docs/backups/settledreach.db.backup`. Stage and commit it with the merge
+if the file changed.
+
+### 2b. Not on `main` — merge main into current branch
+
+```bash
+git fetch --all
+git merge origin/main --no-edit
+```
+
+If clean, report the result (fast-forward or merge commit, files changed).
+If conflicts, report them and stop.
+
+### 3. Push
+
+After a successful merge, push the branch:
+
+```bash
+git push origin <current-branch>
+```
@@ -0,0 +1,29 @@
+#!/usr/bin/env bash
+# Pre-commit hook dispatcher. Runs modular checks from tooling/.
+# Installed via: git config core.hooksPath .config/hooks
+set -euo pipefail
+
+REPO_ROOT="$(git rev-parse --show-toplevel)"
+ERRORS=0
+
+run_check() {
+    local script="$1"
+    local label="$2"
+    if [ -x "$REPO_ROOT/$script" ]; then
+        if ! "$REPO_ROOT/$script"; then
+            ERRORS=$((ERRORS + 1))
+        fi
+    else
+        echo "pre-commit: WARNING — $label skipped ($script not found or not executable)"
+        echo "  Run 'make setup' or check that $script exists and is executable."
+    fi
+}
+
+# --- Checks ---
+run_check "tooling/check-fact-ids" "fact_id validation"
+
+if [ "$ERRORS" -gt 0 ]; then
+    echo ""
+    echo "pre-commit: $ERRORS check(s) failed. Commit aborted."
+    exit 1
+fi
@@ -1,16 +1,28 @@
 # Build and cache
 .cache/
+.tmp/
 server/target/
+tooling/content-converter/target/
+tooling/line-previewer/target/
+tooling/test-client/target/
+content-ron/

-# Godot
+# Godot client (further ignores managed by client team)
 client/.godot/
 client/export/
 client/reports/
-client/*.import

-# Database journal files (transient, not the DB itself)
-db/commonwealth.db-wal
-db/commonwealth.db-shm
+# Renderer (separate Godot project for sprite pipeline)
+renderer/.godot/
+renderer/**/*.import
+renderer/**/*.uid
+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__/
@@ -27,8 +39,7 @@ Thumbs.db
 *.swp
 *.swo

-# Claude Code internals (plans, session transcripts, local settings)
-# Note: .claude/agents/ and .claude/skills/ ARE tracked
+# Claude Code internals (plans, session transcripts)
+# Note: .claude/agents/, .claude/skills/, and .claude/settings.json ARE tracked
 .claude/plans/
 .claude/projects/
-.claude/settings.json
@@ -6,6 +6,640 @@ Format based on [Keep a Changelog](https://keepachangelog.com/).

 ## [Unreleased]

+## [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
+- D-078: Overheard NPC conversation — passive dialogue panel with server-authoritative stochastic word occlusion
+- Sprint 14 "Live" briefings — 22 tickets across server (7), client (3), copy (6), visual (6)
+
+## [v0.1.12] — 2026-02-19
+
+### Added
+- Tier marker components (#93), active tier simulation (#94), tier transition logic (#99)
+- Information tag schema (#138), component-level access control (#139)
+- Line previewer CLI (#193)
+- Sound event system — server pipeline (#124)
+- Close-range stereo audio — client positional 2D (#125)
+- Medium-range visual indicators — fog-edge directional arrows (#126)
+- HashMap ban in simulation crate via clippy (#343)
+- Tracing crate infrastructure — JSON format, tick duration logging (#344)
+- System dependency graph debug command — `--dump-schedule` CLI flag (#346)
+- rng_seed field on ObserverSnapshot for deterministic replay (#527)
+- v0.1 Visual Grammar Document (#303)
+- Placeholder art specification (#252)
+- Spatial layouts: Logistics Hub (#311), Bar (#312), Smuggling corridors (#313)
+- Cultural generation guide — 5-dimension framework for Sova Transit District cultural voice (#189)
+- Sova Texture Appendix — 20-term slang glossary, sensory profile, Meridian self-censorship rules (#302)
+- Contraband specification — unlicensed lattice components, supply chain, street terminology (#321)
+- Sova Station Profile — 6 districts, governance, off-station references (#320)
+- Span Gate Transit Schedule — hourly schedule, maintenance windows, ring operational calendar (#336)
+- Meridian Coverage Map — 10 named zones from Commission-grade to dead air (#335)
+- Character definition schema and both character builds — smuggler + detective (#179, #180, #181)
+- Divergent starting knowledge and relationships per character (#182, #183)
+- Detective institutional chain of command (#322)
+- Contradiction arc design document — reusable FRIEND pattern (#332)
+- Mirror moment design document — 7 core dual-perspective observation triggers (#329)
+- First 5 minutes experience design — systemic opening per character (#259)
+- Opening hook content per character (#260)
+- Knowledge vocabulary for v0.1 content — entity/world categories, prerequisite format (#368)
+- Knowledge state vocabulary — author-facing quick reference (#309)
+- Knowledge fact catalogs — 10 YAML files in content/global/knowledge/, 73 canonical facts
+- D-075 endorsement — archetype dimension review recorded in decisions/content.md
+- Flat NPC memorable trait pass — Pael, Ren, Tev with noise-floor profiles (#307)
+- Environmental text content — 20 items across Terminal, Bar, and Corridors with dual-lens notes (#262)
+- Diegetic insert flavor text — per-character labels and notification strings (#331)
+- News ticker / Meridian feed — 30 lines including batch 44xx recall dual-lens moment (#306)
+- Workplace content pack — The Terminal: 5 NPC dialogue files (#190)
+- Bar content pack — The Last Shift: 3 NPC dialogue files (#191)
+- Smuggling ring content pack — maintenance corridors: coded vocabulary, dual registers (#192)
+- Generation pass expansion — 80 ambient variant lines across all 9 dialogue files (#194)
+- Sprint 13 "Sound" briefings — 9 tickets across server, client, audio, visual teams; full audio architecture + gauntlet expansion + monologue display spec
+
+### Fixed
+- Entity renderer field name bug — `id` vs `entity_id` (#345)
+- Dialogue max-width pixel value — 640px per D-076 (#447)
+- Routine tests missing ActiveSim — 3 of 5 tests passed trivially without the required tier marker
+- `_observer_pos` misleading unused prefix renamed to `observer_pos` (used for sound event filtering)
+- Stale protocol version doc comment "Current: 9" corrected to 10
+- FactionOnly non-numeric `faction_id` attribute now logs a tracing::warn instead of silently denying
+- SOUND_EVENT_ASSETS walk-speed key mismatch — `sfx_footstep_metal` corrected to `sfx_footstep_metal_walk`
+
+### Changed
+- Removed orphaned `SimulationTier`/`LastInteraction`/`ScopeTag`/`ScopeKind` types from tier.rs (unused outside own tests)
+- Sound pipeline documented as intentionally empty in v0.1 (no producers yet, full pipeline wired)
+- Observer test setup now inserts SoundEventQueue resource for integration coverage
+- Added FactionOnly positive test case and Medium-range occlusion TODO
+- Sound indicator colors sourced from Constants instead of duplicated hex literals
+- play_loop() null guard on stream.duplicate()
+- Camera zoom fallback uses Constants.CAMERA_DEFAULT_ZOOM
+
+## [v0.1.11] — 2026-02-19
+
+### Added
+- Sprint 12 "Build" briefings — 50 tickets across server, client, copy, visual, ci teams; production-layer foundations + all v0.1 copy authoring
+- `.tmp/` gitignored repo directory for agent temp files — avoids Bash permission prompts during PR review comment posting
+- `sed -n` blanket permission in shared settings
+
+### Changed
+- All skills renamed to domain-action convention (e.g. `commit`→`git-commit`, `review-pr`→`pr-review`, `gen-audio`→`audio-gen`, `render-sprite`→`sprite-gen`) — 12 renames total
+- `pr-review` skill uses Write tool into `.tmp/` instead of Bash heredocs to `/tmp/`
+
+## [v0.1.10] — 2026-02-19
+
+### Added
+- `project.yaml` — technical project descriptor with version, architecture, simulation, and content model as the canonical version source of truth
+- Scratchpad: asset generation pipeline idea (registry, status tracking, prompt versioning, pre-sprint cohesion)
+- Scratchpad: remote terminal proxy idea for mobile monitoring of Claude Code permission prompts and interactive elements
+- `make perf-baseline` — full plugin stack tick benchmark (50 measured ticks, 5 warmup) capturing per-tick timing, entity counts, process RSS, and shadowcast benchmarks; outputs structured JSON to `tests/perf/baseline.json` with `--compare` mode for regression detection (>20% threshold, D-026 budget check)
+- Michroma font integration (#517) — Michroma-Regular.ttf as game font with +1px tracking FontVariation, global Theme with cyan-white (#E0F7FA) implant text color, IMPLANT_TEXT_COLOR/DIM/PULSE constants
+- Mouse-relative facing and movement (#526, D-054) — mouse position determines facing direction (client-side float), WASD remapped to cursor-relative (W=toward, S=away, A/D=strafe), SET_FACING action sends octant to server, smooth facing indicator rotation
+- Room reset client UX (#502) — amber reset_plate tile type, 0.15s screen flash on room reset, 'Reset Room' interaction verb
+- Auto-checklist progress tracking (#503) — ChecklistEvaluator parses room YAML and evaluates 7 condition types against GameState with latching, ChecklistOverlay renders progress in gauntlet mode only, 48 new tests
+- 4 ambient zone loops: station base, workplace, bar, corridor — SAO-generated organic soundscape with crossfade loop points (#327)
+- 2 footstep SFX: metal walk and run — SAO hybrid with best-transient extraction (#327)
+- `audio-batch` command — batch audio generation from JSON manifests, supports SAO and harmonic synthesis, with `--dry-run`, `--only`, and `--skip-existing` flags
+- `--post` and `--output-ogg` flags on `audio-generate` — chain post-processing (trim, normalize, convert) into a single command
+
+### Changed
+- `push-pr` skill now runs `/commit` first when uncommitted changes are detected
+- Insert open/close now sends explicit PauseSimulation/ResumeSimulation (#518, D-058) — replaces toggle-style pause with idempotent pair
+- Interaction list colors reference Constants.IMPLANT_TEXT_COLOR instead of hardcoded values
+- World radial menu uses theme font instead of ThemeDB.fallback_font
+- Monologue chimes replaced with production-quality manual synthesis — insert-tech aesthetic per D-074, pure sine harmonics with mathematical envelopes (#327)
+
+### Fixed
+- Bidirectional relationship check (#515) — Check 9 tested `target in npc_rels` which missed NPCs with no relationship entries; changed to `target in self.npcs`
+
+## [v0.1.9] — 2026-02-18
+
+### Fixed
+- `make game` now builds client before launching — was missing `build-client` dependency, causing class_name registration failures after `make clean`
+- `build-client` uses `--import --quit` instead of just `--quit` — ensures `.godot/` cache and `global_script_class_cache.cfg` are created from scratch
+- `make clean` preserves `client/.godot/` directory (clears contents only) to avoid Godot startup issues
+
+### Added
+- `--description TEXT` flag for `ticket create` CLI — previously required raw SQL workaround to set ticket descriptions
+
+### Changed
+- UI audio assets revised — monologue chimes re-generated (0.8s, insert-tech aesthetic), fog_recognition re-generated (was silent), all 8 assets normalized to 44.1kHz stereo LUFS -16 (#453)
+- review-pr skill: explicit verdict rules — critical/warning → REQUEST_CHANGES, suggestion-only → APPROVE
+
+### Added
+- `make golden-diff` + `make golden-update` targets (#486) — developer workflow for golden file comparison and regeneration; safe restore on cargo failure
+- Gauntlet checklist YAML schema (#497) — 7 condition types evaluable from ObserverSnapshot, per-room checklists for 3 rooms, `make checklist-validate` and `make checklist-generate` targets, wired into `pre-pr-content` gate
+- Gauntlet room timer + personal bests (#496) — GauntletHUD shows TIMER: MM:SS (PB: MM:SS), starts on room entry, resets on room change, persists stats to user://dev/gauntlet-stats.json, session summary on disconnect, hidden in non-gauntlet mode
+- WRONG button F12 MVP (#495) — bug report capture: pause sim, show modal prompt, save snapshot.json + render.txt + description.txt to user://bug-reports/, Esc to cancel
+- GameState.room_id and gauntlet_mode fields — parsed from ObserverSnapshot, enabling gauntlet UI
+- BUG_REPORT action in InputMapper (F12 binding) with SimBridge wire guard (client-only)
+- 24 new anti-tedium tests — GauntletHUD lifecycle (16: timer, PB, visibility, room change, session tracking) + BugReportDialog (8: pause/unpause, wire guard, text render, edge cases)
+- whatsinagame starter kit — reusable multi-agent team bootstrap for any project (3-tier profiles, 18 skills, 16 agent archetypes, stakeholder personas, ticketing DB, decision tracking)
+- Domain-action naming convention for skills documented in create-skill guide
+- `gauntlet` feature flag (default-on) — allows stripping Gauntlet test world from release builds with `--no-default-features`
+- `EXPECTED_ENTITY_COUNT` and `RESET_PLATE_STABLE_IDS` constants — entity counts derived from StableId ranges instead of hardcoded values
+- Debounce exact-boundary test for room reset (tick 9 rejected, tick 10 accepted)
+- Reset plate StableId verification in `stable_id_ranges_match_spec`
+- Runtime content test (`content_runtime.rs`) separated from structural loading tests
+- Client P2 tests (#492) — 16 gdUnit4 tests for camera (smoothing, zoom, viewport, follow, no-pan), entity alpha/color (peripheral, forward, NPC color, player constant), UI (monologue, interaction, inventory, dialogue, pause, fog blob, fog z_index)
+- Client P3 tests (#493) — 12 gdUnit4 tests for z-layer ordering (floor/ysort/fog/UI), entity lerp (snap, converge, LERP_SPEED=12.0), Tyre additions (recognition, facing, delta scaling, blob removal)
+- Anti-tedium regression tests (#494) — 5 tests: F12 no-crash guard, no queued input, gauntlet UI hidden in default/normal snapshot/multi-tick modes
+
+### Changed
+- Room reset API consolidated to `plan_reset` only — `execute_reset` removed (was a maintenance trap; production uses Commands via `plan_reset`)
+- `room_at()` documented with z-range and corridor overlap assumptions
+- TCP runtime test now has 10s read timeout and registers player in EntityRegistry
+
+### Removed
+- Dead `RoomMember` component from reset.rs (defined but never used)
+- Protocol v8: dialogue_response field decoding (DialogueResponseEvent with line_id, text, speaker_entity_id) from server #305/D-028
+- Test client binary scaffolding (#480) — standalone crate at `tooling/test-client/` with CLI (--connect, --replay, --text, --json, --quiet, --golden, --ticks), exit codes (0/1/2), golden file JSON diff, JSONL replay loader
+- Snapshot text renderer (#481) — `format_snapshot_text(&ObserverSnapshot)` pub-exported from server crate, entity labels as kind:entity_id sorted by distance, room name stub, 10 unit tests
+- Sprint 9 (Gauntlet) briefing files — server, client, CI, audio, joint — 23 tickets across 4 teams
+- Weapon aim lock audio (`sfx_weapon_aim_lock.ogg`) — clinical targeting confirmation tone for weapon aim state (#440)
+- Stance change audio (`sfx_stance_change.ogg`) — subtle mechanical click for stance toggle feedback (#440)
+
+### Fixed
+- MessagePack int_64 encoder dead code branch (#516) — `-(1 << 63)` overflowed making int_64 branch unreachable; negative values beyond int_32 now correctly encode as 0xd3 instead of 0xcf
+- Cross-encoder fixture pipeline hardened — encode failures now exit non-zero instead of writing empty .msgpack files (#475 review)
+- GDScript fixture test no longer silently skips on missing/empty fixture dir — asserts instead (#475 review)
+- GDScript fixture generator covers all PlayerAction variants (added MoveSouth, MoveEast, MoveWest, Unpause, ToggleStanceDown, WalkAway)
+- `make pre-pr` now checks GDScript fixture staleness alongside Rust fixtures
+- Protocol version bumped from 7 to 8 to match server — fixes 5 test failures from version mismatch
+- Interact action encoding changed from unit variant to struct variant to match server's PlayerAction::Interact { target_entity_id, verb }
+- Monologue duplication test (test_monologue_not_duplicated_after_consumption) fixed — was using poll_snapshot() which doesn't consume _last_snapshot in test mode
+- `make pre-pr` target — full pre-PR verification chain: lint → build → test → content validation → fixture staleness (#460, #465)
+- Branch-specific pre-PR variants: `make pre-pr-server`, `make pre-pr-client`, `make pre-pr-content`
+- Content cross-reference validation (9 checks) — canonical_id uniqueness, relationship targets, location slugs, dialogue locations, fact_ids, triangle membership, npc_count, dialogue line_ids, bidirectional relationships (#464)
+
+### Fixed
+- Dialogue schema missing `focused` (mood) and `greeting` (situation) values added in Sprint 7-8 content
+- Speaker wire ID silent fallback — dialogue now warns and skips when target entity missing from registry (was silently using 0)
+- Cross-plugin system ordering — trigger_recognition_monologue now runs after detect_anomalies (latent determinism bug)
+- Walk-away ordering — process_walk_away now runs after process_talk_interaction (prevents same-tick race)
+- ActiveDialogue overwrite — new Talk while in existing dialogue now emits IncompleteInteraction before replacing
+- Server-side Talk range check — handle_talk now enforces CLOSE_RANGE before setting TalkRequest (was client-only)
+- ExamineNpc label collision — VerbKind::ExamineNpc now uses "Examine NPC" label (was "Observe", same as generic Observe)
+- Dead conditional in main.rs collapsed (both branches were identical)
+- WalkAway variant added to all_player_action_variants_roundtrip serialization test
+
+### Changed
+- DialogueCooldownTracker.used changed from Vec to BTreeMap for O(log n) lookup (D-041 compliance)
+- MonologueState.shown_ids changed from Vec to HashSet for O(1) contains check (was O(n) per tick)
+- Secret trust tier documented as unreachable with TODO for Phase 2 KG-gated unlock
+
+### Added
+- Determinism test: different_seed_produces_different_replay — exercises SimRng via dialogue weighted selection
+- Dialogue selection pipeline (#305, D-028) — 4-layer filtering engine: access tier from KG relationship, situation derivation from game state, trust tier, weighted topic+mood scoring via SimRng. Full Talk verb → selected line → ObserverSnapshot pipeline with cooldown tracking
+- ContentSlug component (#452) — stable content identity from YAML (e.g. "kael-davan") independent of runtime Entity handles, for knowledge graph interaction memory across save/load
+- Walk-away KG recording (#427, D-064) — IncompleteInteraction knowledge events with Talk/Confront type, ActiveDialogue tracking, walk-away detection clears dialogue and records in KG
+- Anomaly detection for urgent recognition (#450, D-060) — AnomalyMarker flags PersonOfInterest/Contradicted entities for 0.3s cognitive delay instead of 0.6s normal
+- Recognition monologue during cognitive delay (#451, D-060) — monologue fires at delay START (grey blob phase), not completion. v0.1 fallback lines, anomaly prioritization, cooldown tracking
+- Server --test-mode, --port, --seed CLI flags (#459) — LISTENING:{port} stdout signal, OS-assigned ports, deterministic seed override, stderr-only tracing
+- Determinism gauntlet test (#466) — 20-tick replay determinism regression test with movement, stance, pause/unpause exercise
+- Pause guard test suite (#461-463, #468) — 7 tests covering movement, unpause, roundtrip, stance, interact, batch, tick_rate during pause
+- EntityRegistry lifecycle tests (#469) — stale mapping, re-register, unknown unregister edge cases
+- Boundary value encode/roundtrip tests (#471) — 41 values across all MessagePack integer format boundaries
+- Encoding asymmetry tests (#473) — Rust decoder accepts GDScript-style signed encodings for unsigned fields
+- Boundary fixture generation (#472) — 14 raw + 5 snapshot fixtures at integer format boundaries
+- Malformed batch rejection test (#479) — truncated, garbage, and mixed payloads rejected atomically
+- Per-fix determinism unit tests (#467) — equidistant NPC ordering, visible tile sorting, same-tile mover resolution
+
+### Fixed
+- Determinism: visible_ids HashSet → BTreeSet for stable iteration order (#456)
+- Determinism: visible entities in snapshot sorted by entity_id (#457)
+- Determinism: movers sorted by Entity bits in validate_movement (#458)
+- Pause guard blocks all actions except Pause/Unpause while paused (previously only blocked movement)
+
+### Changed
+- Protocol version bumped from v7 to v8 (dialogue_response field in ObserverSnapshot)
+
+### Added
+- AudioManager autoload (#255, D-068/D-069/D-073) — 5-bus architecture (Music, Ambient, WorldSFX, PlayerActions, UISounds), directory-scan asset registry, spatial/non-spatial playback, audio dip profiles (dialogue, confrontation, listening_focus) with low-pass filter sweep, zone crossfade stub
+- Dialogue response selection (#435, D-061/D-062) — structured options with response_id, priority sorting, max 3 visible, invisible locked options, RichTextLabel for BBCode support
+- Walk-away mechanic (#437, D-064) — WASD triggers WalkAway input during dialogue, 300ms fade, dialogue_active flag gates movement, re-show on server interrupt
+- Confrontation text styling (#436, D-063) — italic first-person options, 1.5s monologue beat with dialogue dim to 70%, audio dip via AudioManager, walk-away cancels in-flight beat
+- MessagePack boundary value tests (#470) — 41 values (25 positive, 16 negative), encode-only header verification, roundtrip, Rust-style unsigned decode overlap tests
+- Client P0 regression tests (#477) — monologue carry-forward (Bug #5), camera stability during pause (Bug #2)
+- Client P1 tests (#478) — fog shader state (4), entity lifecycle (2), pending recognition blob (1)
+
+### Changed
+- Fog byte magic numbers replaced with named constants (#476) — VIS_HIDDEN/PERIPHERAL/FORWARD, EXP_UNEXPLORED/EXPLORED/VISIBLE in FogState
+- Dialogue options now carry structured {text, response_id, priority, confrontation} instead of plain strings
+- Protocol v7 dialogue decode validates and skips malformed options
+
+### Added
+- QA test architecture workshop complete — 3-round, 7-agent workshop producing 60 tickets (epic #455): Gauntlet test world (7 rooms, 48 entities), test client binary (tooling/test-client/), determinism fixes, content validation, make pre-pr pipeline, 38 client tests, anti-tedium features, human tester workflow
+- Workshop skill updated — agents now write output files to disk instead of sending messages, fixing documenter access
+- Camera anchor test suite — 10 gdUnit4 tests verifying camera init, smoothing cycle, and player tracking
+- Entity position lerping — framerate-independent exponential smoothing so entities slide between tiles instead of snapping
+
+### Fixed
+- Server never sends snapshots — blocking TCP read in receive_bridge_inputs stalled the entire bevy Update schedule; switched to non-blocking I/O with WouldBlock handling
+- Camera doesn't center on player at startup — Camera2D smoothed_camera_pos starts at (0,0); now disable smoothing during init, snap to player, re-enable after first anchored frame
+- Player moves while game is paused — movement commands now discarded when TickRate is Paused (pause/unpause still process)
+- Spacebar only pauses, doesn't toggle — added UNPAUSE action with toggle logic based on tick_rate state
+- MessagePack encodes tick 128 as -128 — off-by-one in signed int boundary checks (<=128 instead of <128) across int8/16/32/64 branches
+- Monologue/dialogue lost on snapshot overwrite — one-shot events now carried forward when a newer snapshot replaces an unconsumed one
+- Fog shader white screen on load failure — ColorRect defaults to transparent, shader load failure logged instead of crashing
+- Fog desync during camera smooth pan — fog rect now tracks camera position instead of player position
+
+### Changed
+- Server game loop throttled to ~20 ticks/sec (50ms frames) — non-blocking TCP loop no longer spins; remaining frame budget available for NPC AI
+- Hold-to-move input model — movement polled each frame with stance-based throttle (Sprint=200ms, Walk=400ms, Careful=600ms, Crouch=800ms) and composite diagonals (W+D → northeast)
+- D-053 updated with client throttle rates and input model documentation
+
+### Added
+- Dialogue box UI skeleton (#434, D-061) — bottom screen, max 20% height, ~65% width, NPC speech + max 3 response options, insert-styled colors, WASD walk-away with 300ms fade, no close button, diegetic on InsertOverlay z-layer 6
+- Fog entity visualization (#431, D-059/D-060) — cognitive delay rendering: sonar-style sound pings (3 concentric rings, 1.5s fade), unrecognized grey blobs with 0.8s breathing pulse, D-033 color transition at 50% recognition progress, ±0.5 tile position drift, FogEntities node at z:950
+
+### Changed
+- Client protocol version bumped from 6 to 7 (pending_recognitions decode for cognitive delay)
+- GameState: current_dialogue and pending_recognitions fields wired from ObserverSnapshot v7
+- Scene tree: DialogueBox added to InsertOverlay, FogEntities at z:950 between fog shader and InsertOverlay
+- Test mode: mock dialogue (Kael NPC, 3 options) and mock cognitive delay entity (6-tick recognition cycle)
+
+### Added
+- Archetype evidence presentation spec (#443, D-065/D-034/D-033) — detective case file vs smuggler notebook design document: item definitions, knowledge graph presentation, contradiction markers, THE FRIEND arc walkthroughs, systems interaction map, authoring guidelines
+- Cognitive delay system (#423, D-060) — CognitiveDelay component buffers perception events before emitting KnowledgeEvents (0.6s base / 0.3s urgent at 10 tps), pending_recognitions in ObserverSnapshot v7 for client fog entity visualization, cancellation on entity LOS exit
+- ListeningFocus eavesdrop system (#426, D-053) — stationary_ticks tracking for eavesdrop positioning bonus, 30-tick threshold (20 for Careful stance), Sprint blocks accumulation, registered after validate_movement
+- YAML content loader with hot-reload (#326, D-028) — LinePool system parsing dialogue/monologue YAML into BTreeMap-indexed pools, 4-layer query filtering (access > situation > trust > topic+mood), timestamp-polling hot-reload (dev-only), graceful failure preserves previous content
+- Line pool format specification (#308) — formal spec at docs/architecture/line-pool-format.md defining YAML structure, tag enums, 4-layer filtering pipeline, prerequisite-to-KG mapping, ID format, and Rust loader interface
+- InteractionMemory KG schema design (#442, D-064) — design doc at docs/architecture/interaction-memory-schema.md extending FactKnowledge with interaction tracking, 5-state InteractionState enum, monologue prerequisite extension, NpcTolerance reconciliation
+- Audio discussion decisions D-067 through D-074: recognition chime timing, 5-bus architecture, audio dip profiles, confrontation as cognitive vulnerability, monologue chime placeholder strategy, universal conversation murmur, zone crossfade, hybrid audio generation
+- Asset pipeline documentation system (docs/assets/) with category-based index, sonic palette, and generation templates for audio, visual, and video pipelines
+- Stable Audio Open connector and post-processing wrappers (audio-generate, audio-health, audio-post) with timeout handling for 11GB VRAM constraint
+- gen-audio skill with prompt assembly system (sonic palette prefixes + category templates + asset descriptions)
+- 6 interaction UI audio assets (#440): cursor_hover, weapon_aim, implant_open, fog_recognition, sfx_monologue_chime, sfx_monologue_chime_urgent — generated via SAO, needs duration trimming (#453)
+- Dialogue/confrontation ambient dip implementation spec with full Godot AudioBus tween code
+- Synthesis tooling (tooling/synth_ui_sounds.py) for programmatic insert-tech sound generation
+
+### Changed
+- Protocol version bumped from 6 to 7 (pending_recognitions field in ObserverSnapshot)
+- MessagePack fixtures regenerated for protocol v7
+- Monologue trigger system uses .values() iterator (clippy fix)
+- Monologue schema: relationship prerequisite now requires target and state fields
+- 389 tests total (70 new) — cognitive delay pipeline, line pool loader, ListeningFocus, content watching, serialization
+- Renamed asset-gen skill to gen-image for consistent gen-* naming pattern
+- Client protocol v6 bridge — decode player_stance (4 variants) and player_inventory from ObserverSnapshot, TOGGLE_STANCE_UP/DOWN input actions, 25 gdUnit4 tests
+- Three-scope z-layer rendering pipeline (D-049) — world z:0-900 inside CanvasGroup, insert overlay CanvasLayer 10, UI CanvasLayer 20, modal CanvasLayer 30. Y-sort contract enforced, reserved VFX/airborne/lower-floor ranges documented
+- Cursor state machine (#429, D-056) — 4 states (Default/EntityHover/ObjectHover/WeaponAim), 150ms transitions, insert-styled geometric shapes
+- Fog shader rebuild (#430, D-059) — 5-layer fragment shader with animated Perlin noise, CanvasGroup compositing, FogState autoload for visibility/exploration textures
+- Entity interaction list (#432, D-057) — vertical multi-verb menu, insert-styled, sprint suppression, diegetic toggle
+- World radial menu (#433, D-058) — 2 spokes (Observe + Insert), drag-release and click-click input, 60-degree acceptance zones
+- Inventory UI (#438, D-065) — 3x3 grid, 40x40px slots, 1-9 hotkey selection
+- Stance indicator (#439, D-053) — color-coded HUD text, C/X keybinds
+- Architecture docs: z-layer gap analysis, fog shader spec, flying taxi feasibility analysis
+
+### Changed
+- Scene tree restructured: Entities z_index 3->0 (critical y-sort fix), FloorObjects->10, YSortGroup->100, Overhead->300, FogOverlay->900, ModalLayer added
+- constants.gd rewritten with three-scope z numbering and full reserved range documentation
+- Fog renderer replaced: TileMapLayer-based fog_renderer.gd deleted, replaced by shader-based fog_shader.gd + fog.gdshader
+
+### Added
+- ObserverSnapshot v6 wire protocol (#449) — player_stance (MovementStance) and player_inventory (Vec\<InventoryItem\>) fields with serde defaults for backward compatibility
+- Stance system (#417) — Sprint/Walk/Careful/Crouch movement stance with tick-based speed (1/2/3/4 ticks per move), monologue rate multipliers (40%/100%/150%/100%), PlayerMoveCooldown component, ToggleStanceUp/Down player actions
+- TilePresence posture layers (#420) — Standing/Prone/Seated/Fixture occupancy layers enabling same-tile coexistence (e.g. seated NPC + standing player), layer-based collision in validate_movement
+- ObjectType component (#421) — Readable/Container/Terminal/Door/Pickup/Furniture types with Phase 1 verb sets computed from type + proximity range
+- Phase 2 verb filter (#422) — KG-gated observer-side verb processing: POI priority flips (D-060), Confront injection at KnowsDetails+ confidence, contradiction marking, archetype-specific label relabeling (Smuggler sees Move/Stash, Detective sees Scan/Flag on containers)
+- CharacterArchetype component — Smuggler/Detective archetype for Phase 2 verb label differentiation (D-057)
+- VerbKind::Confront — Phase 2 only verb injected when observer has KnowsDetails+ on an NPC at close range
+- Smuggler inventory system (#424) — CarriedBy(StableId) component, Take/Place verbs, 9-slot (3x3 grid) capacity, auto-slot assignment, info boundary enforcement (carried items invisible to other observers)
+- MovementProfile component (#418) — per-archetype default stance (smuggler=Walk, detective=Walk), applied on spawn, factory methods for future archetypes
+- Sprint interaction buffer suppression (#419, D-055) — sprint stance explicitly clears interaction buffer, no verbs computed or sent during sprint, anomaly monologue pipeline unaffected
+- Sprint anomaly double-take monologue (#428, D-055) — SprintAnomalyQueue component detects Contradicted entities during sprint, fires delayed retroactive monologue after ~1.5s ("Wait — something wasn't right back there"), first-in-wins queue semantics, 3 hardcoded v0.1 lines
+
+### Changed
+- Protocol version bumped from 5 to 6 (stance, inventory, ObjectType, verb system fields)
+- MessagePack fixtures regenerated for protocol v6
+- Input processing queries expanded for stance and cooldown components with backward-compatible Option wrapping
+- Observer pipeline queries expanded for Stance and CharacterArchetype components
+- NearbyInteraction carries object_type and contradicted fields for Phase 2 context
+- BridgePlugin system ordering: process_sprint_anomaly_monologue runs after trigger_monologue, compute_observer_snapshot runs after anomaly processing
+- Player spawn includes MovementProfile, Stance, PlayerMoveCooldown, and SprintAnomalyQueue components
+- 331 tests total (131 new) — comprehensive QA coverage across stance, occupancy, Phase 2 verbs, sprint suppression, inventory, anomaly monologue, and wire format
+
+### Added
+- D-066: Dual-scale grid — 0.5m simulation tiles for stealth granularity, 1m visual tiles for proportional art (2x retina factor). All world geometry 2x2 sim tile minimum so cover/LOS maps 1:1 with visuals. Amends OQ-01.
+- Sprint CLI (`db/connectors/sprint`) — unified sprint lifecycle management with 5 subcommands: status, start, stop, start-work, prepare. Auto-detects sprint from DB state and team from git branch. Guards prevent activating unplanned sprints.
+- Shared permission settings in `.claude/settings.json` — git, ticket/sprint CLI, make, tea, and core skills pre-approved across all worktrees. Deny rules block destructive operations.
+- Decisions D-053 through D-065 from Control & Interaction Workshop — formalized interaction verb system, contextual actions, NPC awareness model, and related design decisions
+- Sprint 6 Touch briefings for server, client, copy, and joint teams
+- Control & Interaction Workshop outputs — full workshop notes and outcomes
+- Smuggler inventory item specs for transit district (#441)
+- Start-workshop skill for multi-agent design workshops
+
+### Fixed
+- Added worktree boundary rules to CLAUDE.md — agents must stay within the git root, no navigating to sibling worktrees or above the repo
+- Plan-sprint skill now enforces worktree-relative paths in generated briefings
+- Worktree-update skill now discovers branches dynamically via `git worktree list` instead of relying on hardcoded branch names — fixes missed branches like `planning`
+
+### Changed
+- Start-sprint and plan-sprint skills updated to use sprint CLI instead of manual multi-query workflows
+- Permission syntax migrated from deprecated `:*` suffix to modern space-wildcard format across all worktrees
+- Internal monologue trigger system (#414) — enter_location fires on first tick, time_idle fires after 100 ticks of no movement, 300-tick cooldown, dedup within session, random line selection from content pools via ChaCha20 RNG
+- MonologueEvent in ObserverSnapshot v5 — current_monologue field carries id, text, and display duration across the IPC bridge
+- Client monologue display wiring — protocol v5 decoding, GameState extraction, HUD display pass-through
+
+### Fixed
+- NPC spawn missing Interactable component (#413) — NPCs spawned from content and proof room now have Interactable, enabling E-prompt detection
+- PlayerAction::Interact was a no-op (#415) — changed from unit to struct variant with target_entity_id and verb fields, server logs interaction data
+
+### Changed
+- Protocol version bumped from 4 to 5 (MonologueEvent field, Interact variant change)
+- MessagePack fixtures regenerated for protocol v5
+
+### Changed
+- UIStrings YAML parser now handles arbitrary nesting depth and inline comments — adapts to copy team's restructured ui-strings.yaml with multi-level sections (relationship_states, health_values)
+- HUD uses new YAML keys: `hud.perception_mode_prefix`, `hud.time_prefix`, `hud.health` (empty prefixes display values directly)
+- Interaction prompt keybind hint ("E") hardcoded instead of loaded from YAML — keybinding is not copywriter text
+
+### Added
+- Pre-commit FactId validation hook (#393) — grep-based check validates fact_id references in content YAML against canonical knowledge catalogs; advisory mode when catalogs are stubs, enforcing mode when populated
+- Pre-commit hook infrastructure — `.config/hooks/` with modular dispatcher, `make setup-hooks` target, `core.hooksPath` config for worktree-safe hook installation
+- `make check-fact-ids` target for manual fact_id validation
+- UIStrings autoload with YAML-based UI string loading (#409) — minimal YAML parser, `get_text()` lookup with fallback-to-key
+- HUD and interaction prompt labels now loaded from `client/data/ui-strings.yaml` instead of hardcoded strings
+- Character voice speech patterns (#310) — sentence-level execution spec for smuggler and detective covering contractions, punctuation, stress markers, vocabulary, verbal tics, and authoring checklist
+- NPC authoring style guide (#379) — 954-line handbook: tier budgets, 9 NPC patterns, dialogue/monologue rules, tag taxonomy, dual-lens coordination, Krenn/Sova culture, FRIEND phase mapping, validation checklist
+- UI microcopy (#409) — 72 YAML strings for client integration: interaction verbs, relationship states, HUD labels, perception modes, notifications, knowledge panel, tutorial prompts
+- Kael Davan FRIEND pack (#297) — 86 hand-authored lines across 3 locations, 5-phase relationship arc with contradiction scene, dual-lens notes
+- Sera Venn FRIEND pack (#298) — 75 hand-authored lines at The Last Shift, trust-gated gossip, avoidance contradiction, contaminated trust arc
+- PC-as-NPC content (#401) — 70 authored items enabling second-playthrough recognition (D-039 wow moment #4)
+
+### Changed
+- Moved ui-strings.yaml from content/campaigns/_meta/ to client/data/ for direct Godot client loading
+
+### Fixed
+- Fact ID format collision across FRIEND content — normalized 73 flat IDs to dotted category.topic format, fixing broken detective evidence chain from Sera to Kael observations
+- Entity ref format inconsistency — normalized underscore format to npc:hyphenated across ~15 monologue references
+- Phase tag inconsistency between FRIEND packs — standardized to phase-N format, added missing phase-2 tags to Kael ring ops lines
+- Detective monologue gap for Kael — added 7 observation lines (7 → 15 total), added mood tags and bar_evening situation to Kael bar content
+- Hoshe QA briefing updated with integration test coverage priorities — test harnesses, dedicated client-server test map, edge case focus
+- Sprint 5 "Live" team briefings — copy (6 tickets), client (2), CI (1), joint coordination for content-at-scale sprint targeting FRIEND packs, voice patterns, NPC style guide, PC-as-NPC authoring, UI microcopy, FactId validation
+- Live server mode (`make game`) — single command builds server, launches client with TCP connection, auto-kills server on exit; `make stop` helper for manual cleanup
+- `SR_LIVE=1` environment variable switches SimBridge from test mode to real TCP server connection
+- TileKind in wire protocol (#412) — server sends Floor/Wall/Door/Object per visible tile, client renders walls and floors in live mode
+- Input roundtrip integration test (#411) — spawns real server, connects via TCP, validates full movement and interact pipeline
+- Debug logging for received player inputs on server (visible with `RUST_LOG=debug`)
+
+### Fixed
+- Interaction prompt target+verb data now attached to Interact action in game loop (#405) — was TODO stub, server receives `{target_entity_id, verb}` payload
+- Player entity detection uses `kind.variant == "Player"` instead of hardcoded `entity_id == 1` — fixes "player not found" warnings when connected to real server (which assigns different IDs)
+- Movement keys now work in live mode — client was sending millisecond timestamps as input tick, server only processes ticks <= current frame counter; now uses server tick from latest snapshot
+- Entity-to-tile alignment in live mode — server sends tile-center render coords (tile 16 → 16.5), entity renderer now floors to tile index before positioning
+
+### Added
+- Content loader Phase 2 (#408) — 2-phase spawn pipeline loads real YAML content into ECS entities: enums, entity attributes, pools, templates, triangles, NPC profiles with Want/Tolerance/Contentment/Personality/Tells/Skills axes plus cross-reference resolution for Secrets, Relationships, Information, and DailyRoutine
+- Global enum YAML files (#387) — 9 enum definitions (situations, topics, moods, triggers, access-tiers, trust-tiers, activities, patterns, motivations) from D-035 taxonomy
+- Entity attributes YAML (#388) — 16 canonical knowledge graph attribute keys from D-024 with A7 workshop updates
+- Seed-time pools (#389) — 5 single-candidate pools for deterministic v0.1 testing
+- Social site templates (#390) — 3 templates (logistics-hub, bar, smuggling-ring) with role slot definitions per D-025
+- Triangle YAML files (#391) — 5 v0.1 triangles (3 active fork, 2 passive) per D-024 workshop synthesis
+- Seed configuration schema design (#394) — design document defining game-start randomization: FRIEND selections, pool draws, template assignments, entanglement config, ChaCha20 RNG protocol
+- YAML to RON converter tool (#403) — build-time converter in tooling/content-converter/, runs via `make content-ron`
+- Line previewer CLI (#407) — 4 subcommands (dialogue, monologue, coverage, sequence) for content authors to test line selection without running the full game
+- Happiness added to WantKind enum — Harek remapped from Safety to Happiness
+
+### Fixed
+- Dialogue-pool schema corrected to use arrays for situation/topic/mood per D-035 (were incorrectly single strings)
+- NPC want.primary changed from narrative strings to WantKind enum keywords — fixes silent Want component drop at spawn time
+- Schema enum constraint added to npc-profile.schema.json for want.primary validation
+
+### Added
+- Sprint 4 "Feel" team briefings — copy (8 tickets), server (9), client (1 carry-over), CI (1), joint coordination
+- Interaction prompt system (#405) — server-driven "E - Talk" prompt decoding v4 nearby_interactions with nested VerbOption structs, fade animation, extensible get_interaction_target/get_selected_verb interface for future radial verb menu
+- Art direction & mood board workshop (3 rounds + closing) — 4-agent team establishes visual identity, 16 art direction principles, 9 mood board images, 10 candidate decisions (D-042–D-051)
+- 3D-to-2D sprite render pipeline (`client/tooling/sprite_renderer/`) — Godot @tool scene renders textured 3D models at "the angle" (-72.5deg ortho) from 4 cardinal directions at 1024/256/64 resolutions with outline applied at working resolution
+- `/render-sprite` skill — CLI wrapper for the render pipeline with headless import step
+- Pipeline POC: Era 1 institutional wall + bar green wall textures generated via Nano Banana and rendered through full pipeline
+- PerceptionQuery trait and ActivePerceptionMode resource — abstraction layer for D-017 perception mode swapping (NaturalVision default implementation)
+- VisibilityGeometry intermediate resource decoupling FOV computation from entity filtering
+- Client-side PROTOCOL_VERSION enforcement — snapshot decoder rejects version mismatches with error log
+- POI verb priority test in observer pipeline — asserts both verb kind and priority values end-to-end
+
+### Changed
+- Observer pipeline decomposed into two-stage system: compute_visibility_geometry (geometry) → compute_observer_snapshot (entity filtering + assembly)
+- POI verb priority adjustment moved from simulation phase (interaction.rs) to perception phase (observer) — fixes D-010 information boundary violation
+- compute_nearby_interactions no longer reads KnowledgeGraph — determines verb availability by proximity only, verb priority adjusted by observer
+- compute_nearby_interactions scheduling moved from SimulationPlugin to BridgePlugin for explicit ordering with geometry and observer systems
+- Client test snapshot updated to v4 format (Protocol.PROTOCOL_VERSION, tick_rate replaces paused)
+
+### Added
+- Content validation tooling — `make validate-content` validates campaign YAML files against JSON schemas, maps files by directory context
+- Entity::to_bits() roundtrip test — guards against bevy version changes silently breaking wire IDs
+- TickRate switch mid-accumulation test — verifies Half→Full→Paused→Half transitions preserve accumulator state
+- Tick rate scaling system (#406, D-052) — Full/Half/Paused rates with fractional accumulation, SetTickRate player action, replaces binary pause flag
+- Proximity detection and interaction verbs (#404, D-060) — compute_nearby_interactions system with Manhattan distance ranges (close ≤2, mid ≤5), context-sensitive verb computation (Talk, Observe, Examine), PersonOfInterest priority flip, NearbyInteraction in ObserverSnapshot v4
+- Content directory skeleton (#385, D-057) — district-as-atomic-pack layout with Sova Transit first district, 17 NPC stubs, 3 locations, 5 triangles, dialogue/monologue pools, factions, knowledge catalogs, enum definitions
+- Content schema definitions (#386) — 8 JSON Schema files (draft 2020-12) for district, location, npc-profile, dialogue-pool, monologue-pool, triangle, routine, fact-catalog validation
+- PROTOCOL_VERSION constant in bridge types — versioning strategy documented (subprocess IPC, serde defaults for field evolution)
+- Campaign, system, station JSON schemas for hierarchical content validation
+
+### Fixed
+- Test suite aligned with server v4 protocol enforcement — all hand-built snapshots include version field, verb priorities 1-indexed, ExamineNpc label corrected to "Observe"
+- E2E proof tests resilient to entity ordering — player found by kind instead of array position, wall-hides test checks specific NPC position instead of total count, supports 3-NPC proof room layout
+- Wire entity_id now uses StableId consistently across observer, observation, interpretation, and interaction systems (was Entity::to_bits() in some paths)
+- Restored system/station/district hierarchical fields in district metadata (incorrectly removed during canonical_id cleanup)
+- Unregistered entities in observer/interaction now log tracing::error instead of silently falling back to Entity::to_bits()
+
+### Changed
+- NearbyInteractionBuffer refactored from global Resource to per-entity Component on PlayerCharacter — multiplayer-ready (D-009)
+- Observer module split into mod.rs (244 lines) + tests.rs (480 lines) — reduces module complexity
+- Content directory restructured from flat districts/ to hierarchical campaigns/main/systems/krenn/stations/sova/districts/transit/ — path mirrors canonical IDs, glob-based discovery, multi-campaign/DLC ready
+- Content manifest (content.yaml) rewritten for glob-based district discovery
+- District identity fields (system, station, district) now derived from directory path — removed from district.yaml required fields
+- NPC canonical_id schema accepts district-scoped IDs (npc:transit.kael-davan) for cross-district uniqueness
+- ObserverSnapshot protocol bumped to v4 — adds nearby_interactions field, tick_rate replaces paused field in GameTime
+- NearbyInteractionBuffer.interactions is now private with take() accessor (no per-frame clone)
+- NearbyInteraction.distance changed from f32 to u32 (matches manhattan distance)
+- Missing PlayerCharacter in input processing now panics instead of silent no-op
+- Verb sort uses (priority, kind) tuple for deterministic ordering at equal priority
+- Unregistered entity in knowledge events triggers debug_assert + error (was warn)
+- District schema: canonical_id is now optional (derived from directory path at load time)
+- Skills trimmed for CLAUDE.md deduplication — search-docs (-48%), ticket (-17%), review-pr (-35%) now reference CLAUDE.md for basics instead of repeating them
+- Review-pr reviewer profiles extracted to `references/reviewer-profiles.md` for progressive disclosure
+
+### Removed
+- Dead generate_snapshot function in bridge/mod.rs — superseded by compute_observer_snapshot
+- content/global/regions/ directory — region data absorbed into system.yaml metadata
+
+### Added
+- Dual Lens Authoring Guide — 7-chapter reference for writing content that works for both smuggler and detective perspectives (D-027, D-028, D-032, D-034, D-035)
+- THE MIRROR pattern spec — transparency-as-contrast NPC design with Naia Tamm reference implementation and generator template
+- Smuggler voice card — register parameters, 5 voice anchors, 4 anti-patterns, paired comparison examples, display constraints, authoring checklist
+- Smuggler moral arc spec — 4-phase trajectory (Comfort, Doubt, Reckoning, Compromise), FactId gates, monologue trigger rules, Kael intersection mapping
+- PC-as-NPC unified spec — starting knowledge/relationship graphs, tell inversion, orientation monologue, 9-step conversion checklist, v0.1 smuggler + detective briefs
+- Triangle 1 Hub Power Volume Escalation fork — 3-path smuggler decision (escalate/stabilize/mediate), ~41 authored dialogue lines, NPC state change tables
+- Content directory structure design doc — runtime content/ layout, canonical ID format, 8 JSON Schema specs, 3-tier validation pipeline, migration path from wiki
+- Interaction verb spec — 7 v0.1 verbs (Move, Look, Monologue, Examine Object, Examine NPC, Talk, Overhear), priority resolution, server pipeline architecture
+- v0.1 wow moments checklist — maps all 6 D-039 moments to content deliverables, tickets, dependencies, completion status
+- Nils Davan off-stage NPC stub — ring coordinator, GHOST + HANDLER pattern, lattice message design, relationship map
+- NPC pattern/motivation mapping applied to all 18 NPC wiki pages with composition reads
+- Structured NPC data model (#86) — replaced stub string/f32 fields with typed enums and integer types for D-010 determinism (WantKind, SecretSeverity, Skill, PersonalityTrait, CombatStyle, RelationshipKind)
+- Global RelationshipGraph resource (#87) — BTreeMap with tuple key for efficient prefix queries and reverse lookups
+- A* pathfinding system (#237) — PathRequest/ComputedPath/PathBlocked components with cardinal-neighbor A* and manhattan heuristic
+- NPC path following system (#238) — MovementSpeed throttling, per-tick path advancement with MoveIntent creation
+- Daily routine system (#88) — NpcPlugin with PreviousDayPhase resource and check_phase_transition system issuing PathRequests at day-phase boundaries
+- Multiple NPC spawning (#84) — 3 distinct NPCs (dock worker, field tech, guard) with full component bundles and RelationshipGraph edges
+- Observation event generator (#239) — RoutineDeviation, Absence, and NewEntity triggers from comparing visible snapshot against NPC routines and knowledge state
+- Review-pr skill routes reviewers by branch type — server/client get Hoshe+Tyre, copy gets Hoshe+Paula+Miri, visual gets Hoshe+Araminta, audio gets Hoshe+Ozzie
+- Start-sprint skill spawns team agents from sprint briefings — parses the Agents line, creates a team with tasks from tickets, and launches all listed agents as background teammates
+
+### Fixed
+- IPC error handling (#341) — DeserializationWithDump/MutexPoisoned error variants, hex dump logging on deserialization failure, graceful error classification in bridge I/O systems
+- NpcPlugin system ordering — routine phase transitions now run before pathfinding so PathRequests are picked up same frame
+- Stale doc comment in observation event generator — system runs before knowledge updates, not after
+- Clippy warnings from Rust 1.93 — derive Default, is_multiple_of, collapsible if
+
+### Changed
+- Hael renamed to Naia Tamm across all wiki files (16 files updated)
+- Canonical full names applied to 11 single-name NPCs (Voss→Arvo Voss, Devra→Devra Talsen, etc.)
+- Location shortcodes standardized in monologue guide (hub_m_ → terminal_m_ per D-036)
+- Entity attributes updated to 16 canonical keys — 4 new role-perspective keys (risk_assessment, loyalty_assessment, position_integrity, moral_weight), secret_held→leverage_held rename
+- Drin Rosta expanded from Tier 3 to Tier 2 — full 10-axis profile, 6 voice lines, Triangle 2 + Triangle 5 roles
+- NPC index roster table expanded with Pattern and Motivation columns
+- Sprint 3 "Know" team briefings regenerated from database — all four files (server, client, joint, copy) now match actual sprint 3 ticket assignments
+- Ticketing database moved to shared worktree location (`../settledreach.db`) — eliminates binary merge conflicts across branches
+- All Python connectors use script-relative path resolution instead of `$REPO_ROOT` env var or git rev-parse
+- `$REPO_ROOT` environment variable removed — all scripts, skills, and docs use relative paths
+- Merged copy branch — 39 tickets, wiki review + content scoping workshops, game world glossary
+- Merged maintenance branch — worktree-update skill
+
+### Added
+- `make db-backup` / `make db-install` — database backup to `docs/backups/` (main-only) and restore for new clones
+- Worktree-update skill backs up the shared database after merges on main
+
+### Removed
+- `db/commonwealth.db` from git tracking (replaced by shared `../settledreach.db`)
+- `$REPO_ROOT` env var from all 9 worktree `settings.local.json` files
+
+### Added
+- Worktree-update skill — non-destructive branch sync with PR detection and conflict safety
+- Game world wiki — 45-file glossary covering Sova Transit District: 17 NPCs, 5 triangles, 3 social sites, 7 factions, knowledge vocabulary
+- Wiki Review workshop (4 rounds + lead interview) — 300-world generator model, cultural ingredients menu, three-system NPC architecture, Sacred/Profane/Middle Kingdom framework
+- v0.1 Content Scoping workshop (2 rounds + closing) — 16 EntityKnowledge keys, mechanical NPC mapping, YAML content format, 7-verb interaction model, server-authoritative pause, 20 decisions (D-042–D-061)
+- 39 implementation tickets (#371–#409) from content scoping workshop — copy 21, server 13, client 2, ci 1
+- Control & Interaction workshop brief (queued)
+- Large content push team pattern in CLAUDE.md
+- Inigo sound designer agent — soundscape design, ambient layers, diegetic cues, D-018 audio propagation
+- Team-agent mapping in sprint planning — each team has defined default agents for briefing assignment
+- Sprint skills recognize all team branches (server, client, copy, audio, visual, ci)
+- Sprint 3 "Know" team briefings — server (6 tickets), client (2 tickets), joint (2 split tickets), copy (1 carry-over)
+- Copy team sprint briefing for Sprint 2 (#368 knowledge vocabulary)
+- Sprint 2 proof: fog of perception E2E tests (#357) — 3 tests verifying all 7 acceptance criteria through real server pipeline (movement, tiles, fog, wall hiding, corner reveal)
+- Server proof room — wall at (16,14) between player at (16,16) and NPC at (16,13) for LOS testing
+- Dynamic test snapshot in SimBridge — tracks player position from queued inputs, Bresenham LOS, Manhattan-distance visibility for standalone demo mode
+- 4 Bresenham LOS unit tests — clear path, wall blocked, diagonal, same position (PR #13 review)
+
+### Fixed
+- Type safety in GameState visible_tiles loop — validates Dictionary with x/y keys before access (PR #11 review)
+- Consistent reset_test_state() usage across all test files (PR #13 review)
+- E2E connection loop now detects server process death early (PR #13 review)
+- Corner reveal test verifies NPC position at (16.5, 13.5) (PR #13 review)
+- Entity renderer skips redundant modulate.a writes when alpha unchanged (PR #11 review)
+
+### Added
+- Observer snapshot knowledge integration (#366) — VisibleEntity carries relationship state (D-033 color) and observation type (Visible/Remembered), remembered entities appear as fog ghosts at last known position
+- Knowledge graph system (#361, #362, #363, #365) — per-entity KnowledgeGraph component (D-041), StableEntityId + EntityRegistry, KnowledgeEventQueue, decay system, 4-level confidence hierarchy
+- Direct observation knowledge flow (#364) — perception emits DirectObservation/LeftLOS events to knowledge graph, entities entering/leaving LOS tracked
+- Protocol v2 decoder — extracts game_time, player_facing, visible_tiles, and per-entity visibility sectors from ObserverSnapshot v2
+- D-033 entity color palette (#130) — relationship-based colors (teal/green/amber/red), Phase 1 defaults by entity kind
+- Peripheral vision dimming — entities in peripheral vision rendered at 50% alpha (D-015)
+- Player facing direction indicator — Polygon2D triangle on player entity showing 8-directional facing
+- GameState v2 fields — game_time, player_facing, visibility_sectors stored from snapshot data
+- Test snapshot updated to v2 format with visibility sectors, game_time, and player_facing
+- Observer visibility query (#112) — replaces unfiltered generate_snapshot with LOS-filtered compute_observer_snapshot combining shadowcasting + vision cone
+- Vision cone system (#111) — forward/peripheral/blind sectors per D-015, Facing component updated on movement
+- Symmetric shadowcasting (#110, #359) — Albert Ford algorithm with rational fraction slopes, benchmarked 1.2-10.5x faster than recursive, symmetry guaranteed (D-035)
+- ObserverSnapshot v2 schema (#358, #25) — version field, GameTime, FacingDirection, VisibleTile, VisibilitySector types, visibility tag on entities
+- D-035 decision record — symmetric shadowcasting selected over recursive (resolves Q-018)
+- Tile rendering engine (#129) — programmatic TileSet with floor/wall/door/object placeholders, renders from snapshot tile data
+- Fog overlay rendering (#131) — three visibility states (visible/fog-edge/hidden) via TileMapLayer overlay
+- Camera lock to character (#116) — Camera2D smoothing at 2x zoom, locked to player position (D-015)
+- Test room environment — 8x8 room with corridor and Manhattan-distance visibility for development without server
+- `ticket team` command and `--team` filter — comma-separated team assignment for tickets (server, client, joint, content)
+
+### Changed
+- All instruction files (CLAUDE.md, skills, agent files) now use `$REPO_ROOT` env var instead of `git rev-parse --show-toplevel` — pre-set per worktree via `.claude/settings.local.json`
+- `start-sprint` skill now requires plan mode — agent must create and get approval for a concrete sprint plan before starting implementation
+
+### Fixed
+- Entity renderer protocol field mismatches — "id"→"entity_id", "type"→"kind.variant", "position"→x/y fields now match Protocol.decode_entity() output
+- Entity centering — entities (24x24) now centered within 32px tiles instead of top-left aligned
+- `start-sprint` skill uses `git rev-parse --show-toplevel` for worktree-safe absolute paths — fixes "No such file or directory" errors on team branches
+
+### Changed
+- Background clear color set to near-black for unexplored areas (was default Godot gray)
+- Scene render order: Tiles → FogOverlay → Entities (fog covers tiles, entities render on top)
+- FogOverlay node type changed from Node2D to TileMapLayer for tile-based fog rendering
+- GameState now stores visible_tiles and visible_positions from snapshots
+- Test snapshot includes player entity (kind "Player"), second NPC entity, tile data, and visibility data
+
 ### Added
 - Sprint 2 "See" briefings (server, client, joint) — fog of perception through the bridge
 - `/plan-sprint` skill — automates sprint planning workflow and briefing file generation
@@ -13,6 +647,10 @@ Format based on [Keep a Changelog](https://keepachangelog.com/).
 - Q-018 through Q-023 — 6 open questions from architecture audit (shadowcasting, entity ID stability, collision resolution, tick overflow, pathfinding cache, debug visualization)
 - 5 architecture spike workshop briefs (knowledge graph, observer pipeline, NPC AI state machines, save/load, map authoring)
 - 17 tickets from architecture audit (#339-#355) — 7 Sprint 1 tasks, 5 Sprint 2+ tasks, 5 workshop epics
+- End-to-end connection test (#81) — GDScript test spawning Rust server, connecting via LocalBridge, sending MoveNorth input, verifying player movement in snapshot response (D-030 Layer 3)
+- Batch input encoding (Vec\<PlayerInput\> wire format) — Protocol.encode_player_inputs() batches all inputs per tick into one framed message matching server expectations
+- EntityKind::Player fixture — snapshot_player.msgpack for cross-language testing, multi-entity fixture updated to include all 4 entity kinds
+- 7 new tests (4 batch encoding, 1 framed batch roundtrip, 1 Player fixture decode, 1 E2E connection), 43 total client tests passing
 - LocalBridge GDScript TCP transport (#79) — 4-byte big-endian length-prefix framing matching Rust server, StreamPeerTCP wrapper with partial read handling
 - ServerProcess subprocess manager — spawns/stops Rust server via OS.create_process(), auto-cleanup on destruction
 - SimBridge live transport integration — _process() polling loop for TCP receive/send, connection state machine (DISCONNECTED → CONNECTING → CONNECTED → ERROR)
@@ -120,6 +758,8 @@ Format based on [Keep a Changelog](https://keepachangelog.com/).

 ### Fixed
 - create-skill references to nonexistent init_skill.py and package_skill.py scripts
+- SimBridge wire format: inputs now batch-encoded as Vec\<PlayerInput\> array per server protocol (was sending individual inputs per frame)
+- SimBridge server args: positional address format ("127.0.0.1:9876") matching server CLI, port default corrected to 9876
 - Wire format mismatch: LocalBridge now uses rmp_serde::to_vec_named() (named maps) matching client Protocol.gd expectations
 - EOF on bridge read now returns BridgeError::Transport for disconnect detection instead of empty Vec
 - WalkabilityMap rewritten from flat Vec to chunk-based HashMap per D-012 architecture (Tyre review)
@@ -141,6 +781,7 @@ Format based on [Keep a Changelog](https://keepachangelog.com/).
 - dotfiles/tmux.conf (no longer needed)

 ### Changed
+- Q-018 (shadowcasting algorithm selection) resolved via D-035
 - All 18 agent briefings updated for decisions/ directory split and DEVOPS.md references
 - Implementation agents (Dudley, Hoshe, Justine, Oscar, Si, Stig, Tyre) now include Development Workflow sections with Makefile targets
 - Q-009 (time system) resolved via D-031
@@ -3,7 +3,8 @@
 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).

 **Official Title:** The Settled Reach (D-021)
-**Repository name:** commonwealth (historical code name, retained for path stability)
+**Repository name:** settled-reach (formerly commonwealth, renamed for clarity)
+**Version source of truth:** `project.yaml` (root `version` field, scheme: `0.1.{sprint_number}`)

 ## Project Structure

@@ -19,10 +20,10 @@ docs/
  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, joint.md, content.md)
+  diagrams/           # d2 source + PNG renders (architecture, data-flow, entity, state, ui)
+  sprints/            # Sprint briefings per team (server.md, client.md, copy.md, joint.md, etc.)
  workshops/          # Workshop briefs and outputs (per-workshop subdirectories)
 db/
-  commonwealth.db     # SQLite ticketing database
  schema.sql          # Database schema
  connectors/         # Connector scripts for SQLite and Qdrant
    config.json       # Endpoint configuration
@@ -34,10 +35,10 @@ db/
  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
-  perception.md       # D-011, D-015, D-016, D-017, D-018, D-019
-  content.md          # D-023, D-024, D-025, D-028, D-029
-  scope.md            # D-001, D-003, D-005, D-006, D-007, D-013, D-014, D-027
+  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
@@ -51,16 +52,49 @@ See [docs/DEVOPS.md](docs/DEVOPS.md) for build, test, lint, and CI procedures. A

 ## Agent Instructions

+### Worktree 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.
+
+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.
+
+### Database
+
+The ticketing database (`settledreach.db`) lives in the **parent directory** shared across all worktrees — it is not tracked in git. A backup is committed to `docs/backups/settledreach.db.backup` via main only.
+
 ### 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
 3. Read the relevant `decisions/*.md` domain file(s) referenced in the briefing
 4. Background context: `docs/briefings/{your-name}.md`, `docs/discussions/`

-### SQLite access
-**Never use the `sqlite3` CLI** - it crashes in Claude Code due to a known std::bad_alloc bug.
+### 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
+```

-Use the whitelistable wrapper scripts:
+### 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.
+
+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"
@@ -99,12 +133,19 @@ tea issue list --login schweitz --repo jpmschweitzer/settled-reach --state open
 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` are protected on Gitea. Do not use `tea pr clean`, `git push --delete`, or `git branch -D` on these branches.
+- **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.

 ### 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)
+- 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
@@ -127,6 +168,14 @@ tea pr create \
  --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/`
@@ -1,7 +1,13 @@
 GODOT := $(shell command -v godot4 2>/dev/null || command -v godot 2>/dev/null)

-.PHONY: help setup build client server test lint ci ci-client ci-server clean \
-       decisions-sync decisions-coverage decisions-active decisions-orphan
+.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 \
+       checklist-validate checklist-generate \
+       perf-baseline debug-schedule

 # --- Configuration ---

@@ -13,25 +19,48 @@ help:
 	@echo ""
 	@echo "  make setup          Install dev dependencies (Rust, Godot, tooling)"
 	@echo "  make build          Build client and server"
-	@echo "  make client         Run the Godot client"
+	@echo "  make game           Build and run the full game (server + client)"
+	@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 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)"
+	@echo "  make db-install         Restore shared database from backup"
+	@echo ""
 	@echo "  make decisions-sync     Sync decisions/*.md into SQLite"
 	@echo "  make decisions-coverage Decision-to-ticket coverage by domain"
 	@echo "  make decisions-active   List active decisions"
 	@echo "  make decisions-orphan   Decisions without implementing tickets"
+	@echo "  make validate-content   Validate content YAML against schemas"
+	@echo "  make check-fact-ids    Check fact_id references against knowledge catalogs"
+	@echo "  make content-ron       Convert content YAML to RON (build-time)"
+	@echo "  make fixtures-client    Generate GDScript->Rust cross-encoder fixtures (#475)"
+	@echo "  make golden-diff        Show diff if golden file output has changed"
+	@echo "  make golden-update      Regenerate golden file and stage for commit"
+	@echo "  make checklist-validate Validate checklist YAML against schema"
+	@echo "  make checklist-generate Validate checklists + print condition summary"
+	@echo "  make perf-baseline      Run performance benchmarks and save baseline"
+	@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 debug-schedule    Print bevy_ecs schedule graph (diff for PR artifacts)"
 	@echo ""
 	@echo "  GODOT_VERSION=4.6 make setup   Override Godot version"

 # --- Setup ---

-setup: setup-rust setup-godot setup-tooling decisions-sync
+setup: setup-rust setup-godot setup-tooling setup-hooks decisions-sync
 	@echo "Dev environment ready."

 setup-rust:
@@ -45,27 +74,55 @@ setup-tooling:
 	@command -v python3 >/dev/null 2>&1 || { echo "Install Python 3"; exit 1; }
 	@command -v curl >/dev/null 2>&1 || { echo "Install curl (required for Godot download)"; exit 1; }
 	@command -v unzip >/dev/null 2>&1 || { echo "Install unzip (required for Godot download)"; exit 1; }
+	@python3 -c "import yaml" 2>/dev/null || { echo "Install PyYAML: pip install pyyaml"; exit 1; }
+	@python3 -c "import jsonschema" 2>/dev/null || { echo "Install jsonschema: pip install jsonschema"; exit 1; }
+
+setup-hooks:
+	@git config core.hooksPath .config/hooks
+	@echo "Git hooks path set to .config/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; }
-	$(GODOT) --headless --path client --quit
+	$(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; }
 	$(GODOT) --path client

+game: stop build
+	@test -n "$(GODOT)" || { echo "Godot not found. Run 'make setup' first."; exit 1; }
+	@echo "Starting server..."
+	@cd server && cargo run --bin settled-reach-server &
+	@sleep 2
+	@echo "Starting client..."
+	@SR_LIVE=1 $(GODOT) --path client
+	@$(MAKE) stop
+
+stop:
+	@lsof -ti :9876 | xargs -r kill 2>/dev/null || true
+	@echo "Stopped any running server on port 9876"
+
 # --- Test ---

 test: test-server test-client
@@ -76,6 +133,41 @@ test-server:
 fixtures:
 	cd server && cargo test --test gen_fixtures -- --ignored

+fixtures-client:
+	@test -n "$(GODOT)" || { echo "Godot not found. Run 'make setup' first."; exit 1; }
+	@echo "Generating GDScript fixtures for Rust decoder..."
+	$(GODOT) --headless --path client -s res://tests/gen_client_fixtures.gd
+	@echo "Verifying Rust can decode GDScript fixtures..."
+	cd server && cargo test --test serialization gdscript_generated_fixtures
+	@echo "--- Fixtures-client: PASS ---"
+
+golden-diff:
+	@echo "Regenerating golden output for comparison..."
+	@mkdir -p .cache/golden
+	@cp server/tests/golden/proof_room_tick_10.json .cache/golden/before.json
+	@cd server && UPDATE_GOLDEN=1 cargo test --test golden_suite -- proof_room_tick_10_matches_golden; \
+		rc=$$?; \
+		cp ../server/tests/golden/proof_room_tick_10.json ../.cache/golden/after.json 2>/dev/null; \
+		cp ../.cache/golden/before.json ../server/tests/golden/proof_room_tick_10.json; \
+		if [ $$rc -ne 0 ]; then echo "Cargo test failed (golden file restored)."; exit $$rc; fi
+	@if diff -q .cache/golden/before.json .cache/golden/after.json >/dev/null 2>&1; then \
+		echo "--- Golden file: UP TO DATE ---"; \
+	else \
+		echo "--- Golden file has CHANGED ---"; \
+		echo ""; \
+		diff --color -u .cache/golden/before.json .cache/golden/after.json || true; \
+		echo ""; \
+		echo "Run 'make golden-update' to accept changes."; \
+		exit 1; \
+	fi
+
+golden-update:
+	@echo "Regenerating golden file..."
+	@cd server && UPDATE_GOLDEN=1 cargo test --test golden_suite -- proof_room_tick_10_matches_golden
+	@git add server/tests/golden/
+	@echo "--- Golden file updated and staged ---"
+	@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/
@@ -93,6 +185,70 @@ lint-client:
 	@echo "Checking GDScript for errors..."
 	@$(GODOT) --headless --path client --quit 2>&1 | grep -i "SCRIPT ERROR" && { echo "GDScript errors found"; exit 1; } || echo "No script errors found"

+# --- Pre-PR verification ---
+
+pre-pr: pre-pr-lint pre-pr-build pre-pr-test pre-pr-validate pre-pr-fixtures
+	@echo ""
+	@echo "=== PRE-PR: ALL CHECKS PASSED ==="
+	@echo "Safe to create PR."
+
+pre-pr-lint: lint-server lint-client
+	@echo "--- Lint: PASS ---"
+
+pre-pr-build: build-server build-client
+	@echo "--- Build: PASS ---"
+
+pre-pr-test: test-server test-client
+	@echo "--- Tests: PASS ---"
+
+pre-pr-validate: validate-content check-fact-ids
+	@echo "--- Content validation: PASS ---"
+
+pre-pr-fixtures:
+	@echo "Checking Rust->GDScript fixture staleness..."
+	@cd server && cargo test --test gen_fixtures -- --ignored
+	@if git diff --quiet client/tests/fixtures/; then \
+		echo "--- Rust fixtures: UP TO DATE ---"; \
+	else \
+		echo ""; \
+		echo "--- RUST FIXTURES STALE ---"; \
+		echo "  Protocol changed but fixtures not regenerated."; \
+		echo "  Stale fixtures make all client tests FALSE POSITIVES."; \
+		echo ""; \
+		echo "  Changed files:"; \
+		git diff --stat client/tests/fixtures/; \
+		echo ""; \
+		echo "  Fix: commit the updated fixtures with your protocol change."; \
+		exit 1; \
+	fi
+	@echo "Checking GDScript->Rust fixture staleness..."
+	@$(MAKE) fixtures-client
+	@if git diff --quiet server/tests/fixtures/gdscript/; then \
+		echo "--- GDScript fixtures: UP TO DATE ---"; \
+	else \
+		echo ""; \
+		echo "--- GDSCRIPT FIXTURES STALE ---"; \
+		echo "  Protocol changed but GDScript fixtures not regenerated."; \
+		echo "  Stale fixtures make cross-encoder tests FALSE POSITIVES."; \
+		echo ""; \
+		echo "  Changed files:"; \
+		git diff --stat server/tests/fixtures/gdscript/; \
+		echo ""; \
+		echo "  Fix: commit the updated fixtures with your protocol change."; \
+		exit 1; \
+	fi
+
+# Branch-specific variants (faster, scope-appropriate)
+
+pre-pr-server: lint-server build-server test-server pre-pr-fixtures
+	@echo "=== Server pre-PR: PASSED ==="
+
+pre-pr-client: lint-client build-client test-client
+	@echo "=== Client pre-PR: PASSED ==="
+
+pre-pr-content: validate-content check-fact-ids checklist-validate
+	@echo "=== Content pre-PR: PASSED ==="
+
 # --- CI (run locally) ---

 ci: ci-server ci-client
@@ -101,6 +257,14 @@ ci-server: lint-server build-server test-server

 ci-client: lint-client build-client test-client

+# --- Database ---
+
+db-backup:
+	@tooling/db-backup
+
+db-install:
+	@tooling/db-install
+
 # --- Decisions ---

 decisions-sync:
@@ -115,10 +279,37 @@ decisions-active:
 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)"

+# --- Content Validation ---
+
+validate-content:
+	@tooling/validate-content
+
+check-fact-ids:
+	@tooling/check-fact-ids
+
+checklist-validate:
+	@tooling/validate-checklist --check
+
+checklist-generate:
+	@tooling/validate-checklist
+
+perf-baseline:
+	@tooling/perf-baseline
+
+# --- Schedule debug (#346) ---
+
+debug-schedule:
+	@echo "Dumping bevy_ecs schedule graph..."
+	@cd server && cargo run --bin settled-reach-server -- --dump-schedule
+
+content-ron:
+	cd tooling/content-converter && cargo build --release
+	tooling/content-converter/target/release/content-converter --input content --output content-ron --verbose
+
 # --- Clean ---

 clean:
 	cd server && cargo clean || true
 	rm -rf .cache/*
-	rm -rf client/.godot client/reports
+	rm -rf client/.godot/* client/reports
 	@echo "Clean complete."
@@ -38,6 +38,7 @@
 | **DUDLEY** | Server Developer | Game server, ECS, simulation loop, world state management. | Server implementation phase |
 | **OSCAR** | Networking Developer | Multiplayer networking, client-server protocol, sync. | Networking implementation phase |
 | **JUSTINE** | Polish & Deploy | Build pipelines, packaging, performance optimization, release prep. | Pre-release phase |
+| **INIGO** | Sound Designer | Soundscape design, ambient layers, diegetic audio cues, audio propagation. | Audio implementation phase |
 | **MELLANIE** | Copywriter | In-game text, UI copy, tooltips, flavor text, lore entries. | Content creation phase |
 | **TIGER** | Translator | Localization, i18n framework, translation management. | Localization phase |

@@ -69,25 +69,26 @@ static func _encode_message(buffer: StreamPeerBuffer, value):
 		TYPE_INT:
 			if - (1 << 5) <= value and value <= (1 << 7) - 1:
 				buffer.put_8(value)
-			elif - (1 << 7) <= value and value <= (1 << 7):
+			elif - (1 << 7) <= value and value < (1 << 7):
 				buffer.put_u8(types["int_8"])
 				buffer.put_8(value)
 			elif 0 <= value and value <= (1 << 8) - 1:
 				buffer.put_u8(types["uint_8"])
 				buffer.put_u8(value)
-			elif - (1 << 15) <= value and value <= (1 << 15):
+			elif - (1 << 15) <= value and value < (1 << 15):
 				buffer.put_u8(types["int_16"])
 				buffer.put_16(value)
 			elif 0 <= value and value <= (1 << 16) - 1:
 				buffer.put_u8(types["uint_16"])
 				buffer.put_u16(value)
-			elif - (1 << 31) <= value and value <= (1 << 31):
+			elif - (1 << 31) <= value and value < (1 << 31):
 				buffer.put_u8(types["int_32"])
 				buffer.put_32(value)
 			elif 0 <= value and value <= (1 << 32) - 1:
 				buffer.put_u8(types["uint_32"])
 				buffer.put_u32(value)
-			elif - (1 << 63) <= value and value <= (1 << 63):
+			elif value < 0:
+				# Negative beyond int_32 range — encode as int_64 (0xd3)
 				buffer.put_u8(types["int_64"])
 				buffer.put_64(value)
 			else:
@@ -133,7 +134,9 @@ static func _encode_message(buffer: StreamPeerBuffer, value):
 				return ERR_INVALID_DATA
 			
 			for obj in value:
-				_encode_message(buffer, obj)
+				var inner_err = _encode_message(buffer, obj)
+				if inner_err:
+					return inner_err

 		TYPE_DICTIONARY:
 			var size = value.size()
@@ -150,8 +153,12 @@ static func _encode_message(buffer: StreamPeerBuffer, value):
 				return ERR_INVALID_DATA
 			
 			for key in value:
-				_encode_message(buffer, key)
-				_encode_message(buffer, value[key])
+				var key_err = _encode_message(buffer, key)
+				if key_err:
+					return key_err
+				var val_err = _encode_message(buffer, value[key])
+				if val_err:
+					return val_err
 		
 		TYPE_PACKED_BYTE_ARRAY:
 			var size = value.size()
@@ -225,11 +232,9 @@ static func _decode_message(buffer: StreamPeerBuffer, err: Dictionary):
 		return buffer.get_utf8_string(size)
 		
 	elif first_byte == types["nil"]: # nil
-		print("null size:%s"%buffer_size)
 		return null
-		
+
 	elif first_byte == types["false"]: # false
-		print("false size:%s"%buffer_size)		
 		return false
 		
 	elif first_byte == types["true"]: # true
@@ -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
@@ -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
@@ -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
@@ -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
@@ -0,0 +1,19 @@
+[remap]
+
+importer="oggvorbisstr"
+type="AudioStreamOggVorbis"
+uid="uid://uflbvtm1aquk"
+path="res://.godot/imported/cursor_hover.ogg-f20fa5adecb73cc9163569968f5867a3.oggvorbisstr"
+
+[deps]
+
+source_file="res://assets/audio/cursor_hover.ogg"
+dest_files=["res://.godot/imported/cursor_hover.ogg-f20fa5adecb73cc9163569968f5867a3.oggvorbisstr"]
+
+[params]
+
+loop=false
+loop_offset=0
+bpm=0
+beat_count=0
+bar_beats=4
@@ -0,0 +1,19 @@
+[remap]
+
+importer="oggvorbisstr"
+type="AudioStreamOggVorbis"
+uid="uid://bw0mfil2343po"
+path="res://.godot/imported/fog_recognition.ogg-fd0dc7f57c3509774a533bc71a7687e7.oggvorbisstr"
+
+[deps]
+
+source_file="res://assets/audio/fog_recognition.ogg"
+dest_files=["res://.godot/imported/fog_recognition.ogg-fd0dc7f57c3509774a533bc71a7687e7.oggvorbisstr"]
+
+[params]
+
+loop=false
+loop_offset=0
+bpm=0
+beat_count=0
+bar_beats=4
@@ -0,0 +1,19 @@
+[remap]
+
+importer="oggvorbisstr"
+type="AudioStreamOggVorbis"
+uid="uid://dei8ikwaqyn67"
+path="res://.godot/imported/implant_open.ogg-46eadc4ed252693e3a936e75ddfdf4bc.oggvorbisstr"
+
+[deps]
+
+source_file="res://assets/audio/implant_open.ogg"
+dest_files=["res://.godot/imported/implant_open.ogg-46eadc4ed252693e3a936e75ddfdf4bc.oggvorbisstr"]
+
+[params]
+
+loop=false
+loop_offset=0
+bpm=0
+beat_count=0
+bar_beats=4
@@ -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
@@ -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
@@ -0,0 +1,19 @@
+[remap]
+
+importer="oggvorbisstr"
+type="AudioStreamOggVorbis"
+uid="uid://b7iopmg6ftp4k"
+path="res://.godot/imported/sfx_monologue_chime.ogg-5981f28716fbe14273c052560195d890.oggvorbisstr"
+
+[deps]
+
+source_file="res://assets/audio/sfx_monologue_chime.ogg"
+dest_files=["res://.godot/imported/sfx_monologue_chime.ogg-5981f28716fbe14273c052560195d890.oggvorbisstr"]
+
+[params]
+
+loop=false
+loop_offset=0
+bpm=0
+beat_count=0
+bar_beats=4
@@ -0,0 +1,19 @@
+[remap]
+
+importer="oggvorbisstr"
+type="AudioStreamOggVorbis"
+uid="uid://4m87qby6qdhc"
+path="res://.godot/imported/sfx_monologue_chime_urgent.ogg-696a4dbc297417724610e01fa44fa575.oggvorbisstr"
+
+[deps]
+
+source_file="res://assets/audio/sfx_monologue_chime_urgent.ogg"
+dest_files=["res://.godot/imported/sfx_monologue_chime_urgent.ogg-696a4dbc297417724610e01fa44fa575.oggvorbisstr"]
+
+[params]
+
+loop=false
+loop_offset=0
+bpm=0
+beat_count=0
+bar_beats=4
@@ -0,0 +1,19 @@
+[remap]
+
+importer="oggvorbisstr"
+type="AudioStreamOggVorbis"
+uid="uid://cow7symyvpmal"
+path="res://.godot/imported/sfx_npc_murmur.ogg-bfd7592cfea1b592d89f107b6cd33838.oggvorbisstr"
+
+[deps]
+
+source_file="res://assets/audio/sfx_npc_murmur.ogg"
+dest_files=["res://.godot/imported/sfx_npc_murmur.ogg-bfd7592cfea1b592d89f107b6cd33838.oggvorbisstr"]
+
+[params]
+
+loop=false
+loop_offset=0
+bpm=0
+beat_count=0
+bar_beats=4
@@ -0,0 +1,19 @@
+[remap]
+
+importer="oggvorbisstr"
+type="AudioStreamOggVorbis"
+uid="uid://dbu2lr4scswyn"
+path="res://.godot/imported/sfx_stance_change.ogg-042fce976b2bd1b0806c72aa5dd64755.oggvorbisstr"
+
+[deps]
+
+source_file="res://assets/audio/sfx_stance_change.ogg"
+dest_files=["res://.godot/imported/sfx_stance_change.ogg-042fce976b2bd1b0806c72aa5dd64755.oggvorbisstr"]
+
+[params]
+
+loop=false
+loop_offset=0
+bpm=0
+beat_count=0
+bar_beats=4
@@ -0,0 +1,19 @@
+[remap]
+
+importer="oggvorbisstr"
+type="AudioStreamOggVorbis"
+uid="uid://c5lduxqgx0vme"
+path="res://.godot/imported/sfx_weapon_aim_lock.ogg-649a54b41e9bf6dd8ab414c03bb48cfa.oggvorbisstr"
+
+[deps]
+
+source_file="res://assets/audio/sfx_weapon_aim_lock.ogg"
+dest_files=["res://.godot/imported/sfx_weapon_aim_lock.ogg-649a54b41e9bf6dd8ab414c03bb48cfa.oggvorbisstr"]
+
+[params]
+
+loop=false
+loop_offset=0
+bpm=0
+beat_count=0
+bar_beats=4
@@ -0,0 +1,19 @@
+[remap]
+
+importer="oggvorbisstr"
+type="AudioStreamOggVorbis"
+uid="uid://c2bqso5hkljq1"
+path="res://.godot/imported/weapon_aim.ogg-0bff40b0820b0f9db4c2b0ae2542bfa0.oggvorbisstr"
+
+[deps]
+
+source_file="res://assets/audio/weapon_aim.ogg"
+dest_files=["res://.godot/imported/weapon_aim.ogg-0bff40b0820b0f9db4c2b0ae2542bfa0.oggvorbisstr"]
+
+[params]
+
+loop=false
+loop_offset=0
+bpm=0
+beat_count=0
+bar_beats=4
@@ -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={}
@@ -0,0 +1,93 @@
+Copyright 2011 The Michroma Project Authors (https://github.com/googlefonts/Michroma-font)
+
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+This license is copied below, and is also available with a FAQ at:
+https://scripts.sil.org/OFL
+
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded, 
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION & CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.
@@ -0,0 +1,8 @@
+[gd_resource type="FontVariation" load_steps=2 format=3]
+
+[ext_resource type="FontFile" path="res://assets/fonts/Michroma-Regular.ttf" id="1_base"]
+
+[resource]
+base_font = ExtResource("1_base")
+spacing_glyph = 1
+spacing_space = 1
@@ -0,0 +1,20 @@
+[gd_resource type="Theme" load_steps=2 format=3]
+
+[ext_resource type="FontVariation" path="res://assets/fonts/michroma_ui.tres" id="1_font"]
+
+[resource]
+default_font = ExtResource("1_font")
+default_font_size = 14
+
+Label/colors/font_color = Color(0.878, 0.969, 0.98, 1)
+Label/font_sizes/font_size = 14
+
+RichTextLabel/colors/default_color = Color(0.878, 0.969, 0.98, 1)
+RichTextLabel/font_sizes/normal_font_size = 14
+
+Button/colors/font_color = Color(0.878, 0.969, 0.98, 1)
+Button/colors/font_hover_color = Color(0.91, 0.773, 0.278, 1)
+Button/font_sizes/font_size = 14
+
+LineEdit/colors/font_color = Color(0.878, 0.969, 0.98, 1)
+LineEdit/font_sizes/font_size = 14
@@ -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
@@ -0,0 +1,187 @@
+# UI Microcopy — The Settled Reach v0.1
+#
+# Ticket: #409 | Sprint: 5
+# Author: Mellanie (Copywriter)
+# Date: 2026-02-13
+#
+# All player-facing UI text. Organized by category.
+# Voice: Sova Transit District (D-036) — working-class pragmatic, quotidian-with-undertow.
+# Diegetic frame: most UI elements are neural insert overlays, not game chrome.
+#
+# Integration: Stig imports these into client/scripts/constants/ or reads at runtime.
+# Keys are stable identifiers. Values are display strings.
+
+# ============================================================
+# INTERACTION PROMPTS
+# Displayed as "E - {label}" when player is near an interactable.
+# Server sends verb kind + label. These are the canonical labels.
+# Keep short: max 12 characters. Must read instantly during gameplay.
+# ============================================================
+interaction_verbs:
+  talk: "Talk"
+  examine_npc: "Look"
+  examine_object: "Examine"
+  read: "Read"
+  pick_up: "Pick up"
+  use: "Use"
+  open: "Open"
+  listen: "Listen"
+
+# ============================================================
+# RELATIONSHIP STATE DESCRIPTORS
+# Shown in knowledge panel when player inspects an entity.
+# Maps to RelationshipState enum (server/src/knowledge/types.rs).
+# These should feel like insert-generated assessments, not game labels.
+# ============================================================
+relationship_states:
+  unknown:
+    label: "Unknown"
+    description: "No prior contact."
+  known:
+    label: "Recognized"
+    description: "Seen before. No relationship established."
+  friendly:
+    label: "Trusted"
+    description: "Known contact. Cooperative."
+  person_of_interest:
+    label: "Flagged"
+    description: "Behavioral anomaly noted."
+  hostile:
+    label: "Hostile"
+    description: "Known threat."
+
+# ============================================================
+# HUD LABELS
+# Top-level HUD elements. Diegetic: these are the insert's status readouts.
+# Format mirrors a low-key neural overlay — terse, functional.
+# ============================================================
+hud:
+  health: "Condition"
+  health_values:
+    full: "Normal"
+    wounded: "Injured"
+    critical: "Critical"
+  time_prefix: ""            # No prefix — time displays as raw value (e.g., "14:30")
+  perception_mode_prefix: "" # No prefix — mode name displays directly
+
+# ============================================================
+# PERCEPTION MODE LABELS
+# The insert's active sensing mode. Per D-017.
+# Smuggler has Baseline. Detective has Standard Professional.
+# Labels should feel like the insert's own status readout.
+# ============================================================
+perception_modes:
+  standard: "Standard"
+  analytical: "Analytical"
+  social: "Social"
+  surveillance: "Surveillance"
+
+# ============================================================
+# NOTIFICATION TEXT
+# Brief messages that appear when game state changes.
+# Max 40 characters. Must read in under 2 seconds.
+# Diegetic: these are insert alerts, not achievement popups.
+# ============================================================
+notifications:
+  # Location discovery
+  location_discovered: "New location logged."
+  location_revisit: "Returning to {location}."
+
+  # NPC knowledge
+  contact_new: "New contact: {name}."
+  contact_updated: "Contact updated: {name}."
+  contact_flagged: "{name} flagged."
+
+  # Relationship shifts
+  relationship_improved: "{name} — trust increased."
+  relationship_degraded: "{name} — trust decreased."
+  relationship_hostile: "{name} — hostile."
+
+  # Evidence / observation
+  evidence_found: "Evidence logged."
+  anomaly_detected: "Anomaly noted."
+  pattern_recognized: "Pattern flagged."
+
+  # System
+  save_complete: "Progress saved."
+  connection_lost: "Signal interrupted."
+  connection_restored: "Signal restored."
+
+# ============================================================
+# KNOWLEDGE PANEL LABELS
+# When the player opens the knowledge view to review what they know.
+# Insert-flavored: reads like a personal filing system, not a game menu.
+# ============================================================
+knowledge_panel:
+  tab_contacts: "Contacts"
+  tab_locations: "Locations"
+  tab_evidence: "Notes"
+  section_known_attributes: "Known"
+  section_last_seen: "Last seen"
+  section_relationship: "Status"
+  section_observations: "Observations"
+  empty_state: "Nothing logged yet."
+  confidence_high: "Confirmed"
+  confidence_medium: "Likely"
+  confidence_low: "Unconfirmed"
+  confidence_rumor: "Hearsay"
+
+# ============================================================
+# TUTORIAL TEXT (DIEGETIC)
+# Delivered via internal monologue (D-016), not UI overlay.
+# These are NOT traditional tutorial prompts. They're the character
+# thinking about what they can do, filtered through their voice.
+# Smuggler and detective variants are in the monologue pools.
+# These are the GENERIC fallback strings if monologue doesn't fire.
+# ============================================================
+tutorial_prompts:
+  move_hint: "Use the directional keys to move."
+  interact_hint: "Press E near someone to interact."
+  examine_hint: "Press E to take a closer look."
+  listen_hint: "Move closer to overhear conversations."
+  monologue_hint: "Your thoughts appear as text on screen."
+  perception_hint: "Switch perception modes to see differently."
+  minimap_hint: "The overlay shows the area around you."
+  knowledge_hint: "Open your notes to review what you know."
+
+# ============================================================
+# DIALOGUE
+# Text displayed during dialogue interactions.
+# D-063: Confrontation beat monologue — character's internal hesitation.
+# ============================================================
+dialogue:
+  confrontation_beat: "This changes things. No taking it back."
+
+# ============================================================
+# MENU AND SYSTEM TEXT
+# Non-diegetic. Standard game UI. Clean, no flavor text.
+# ============================================================
+menu:
+  pause_title: "Paused"
+  resume: "Resume"
+  settings: "Settings"
+  save_game: "Save"
+  load_game: "Load"
+  quit_to_menu: "Quit to Menu"
+  quit_game: "Quit"
+  confirm_quit: "Unsaved progress will be lost."
+  confirm_yes: "Yes"
+  confirm_no: "No"
+
+settings:
+  audio_volume: "Volume"
+  text_size: "Text Size"
+  text_speed: "Text Speed"
+  fullscreen: "Fullscreen"
+  language: "Language"
+
+# ============================================================
+# CHARACTER SELECTION (if applicable in v0.1)
+# ============================================================
+character_select:
+  title: "Choose your perspective."
+  smuggler_name: "Logistics Operator"
+  smuggler_tagline: "You know these people. You know the work. You know what's at stake."
+  detective_name: "Commission Investigator"
+  detective_tagline: "The manifests don't add up. Someone in this district knows why."
+  confirm: "Begin"
@@ -0,0 +1,43 @@
+[gd_resource type="AudioBusLayout" format=3]
+
+; D-068: 5-bus audio architecture — Music, Ambient, WorldSFX, PlayerActions, UISounds.
+; All buses route to Master. Volumes managed at runtime by AudioManager autoload.
+; AudioManager._setup_buses() creates any missing buses on startup (no-op if present).
+
+[resource]
+bus/0/name = "Master"
+bus/0/solo = false
+bus/0/mute = false
+bus/0/bypass_fx = false
+bus/0/volume_db = 0.0
+bus/0/send = &""
+bus/1/name = "Music"
+bus/1/solo = false
+bus/1/mute = false
+bus/1/bypass_fx = false
+bus/1/volume_db = 0.0
+bus/1/send = &"Master"
+bus/2/name = "Ambient"
+bus/2/solo = false
+bus/2/mute = false
+bus/2/bypass_fx = false
+bus/2/volume_db = 0.0
+bus/2/send = &"Master"
+bus/3/name = "WorldSFX"
+bus/3/solo = false
+bus/3/mute = false
+bus/3/bypass_fx = false
+bus/3/volume_db = 0.0
+bus/3/send = &"Master"
+bus/4/name = "PlayerActions"
+bus/4/solo = false
+bus/4/mute = false
+bus/4/bypass_fx = false
+bus/4/volume_db = 0.0
+bus/4/send = &"Master"
+bus/5/name = "UISounds"
+bus/5/solo = false
+bus/5/mute = false
+bus/5/bypass_fx = false
+bus/5/volume_db = 0.0
+bus/5/send = &"Master"
@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="128" height="128"><rect width="128" height="128" fill="#1a1a2e"/></svg>
@@ -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
@@ -20,6 +20,18 @@ config/icon="res://icon.svg"
 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"
+
+[audio]
+
+buses/default_bus_layout="res://default_bus_layout.tres"
+
+[gui]
+
+theme/custom="res://assets/theme/game_theme.tres"
+theme/custom_font="res://assets/fonts/michroma_ui.tres"

 [display]

@@ -93,8 +105,34 @@ pause={
 "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":32,"key_label":0,"unicode":32,"location":0,"echo":false,"script":null)
 ]
 }
+stance_up={
+"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":67,"key_label":0,"unicode":99,"location":0,"echo":false,"script":null)
+]
+}
+stance_down={
+"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":88,"key_label":0,"unicode":120,"location":0,"echo":false,"script":null)
+]
+}
+bug_report={
+"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":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)
+]
+}
+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)
+]
+}

 [rendering]

 renderer/rendering_method="gl_compatibility"
 renderer/rendering_method.mobile="gl_compatibility"
+environment/defaults/default_clear_color=Color(0.05, 0.05, 0.08, 1)
@@ -1,33 +1,179 @@
-[gd_scene load_steps=8 format=3 uid="uid://bswrmh7w8dbgm"]
+[gd_scene load_steps=23 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"]
 [ext_resource type="Script" path="res://scripts/rendering/entity_renderer.gd" id="3_entity"]
-[ext_resource type="Script" path="res://scripts/rendering/fog_renderer.gd" id="4_fog"]
-[ext_resource type="PackedScene" path="res://ui/hud.tscn" id="5_hud"]
-[ext_resource type="PackedScene" path="res://ui/minimap.tscn" id="6_minimap"]
-[ext_resource type="PackedScene" path="res://ui/monologue_display.tscn" id="7_monologue"]
+[ext_resource type="Script" path="res://scripts/rendering/fog_shader.gd" id="4_fog"]
+[ext_resource type="Script" path="res://scripts/rendering/tile_renderer.gd" id="5_tile"]
+[ext_resource type="PackedScene" path="res://ui/hud.tscn" id="6_hud"]
+[ext_resource type="PackedScene" path="res://ui/minimap.tscn" id="7_minimap"]
+[ext_resource type="PackedScene" path="res://ui/monologue_display.tscn" id="8_monologue"]
+[ext_resource type="PackedScene" path="res://ui/interaction_prompt.tscn" id="9_prompt"]
+[ext_resource type="Script" path="res://scripts/rendering/cursor_renderer.gd" id="10_cursor"]
+[ext_resource type="PackedScene" path="res://ui/interaction_list.tscn" id="11_ilist"]
+[ext_resource type="PackedScene" path="res://ui/inventory_grid.tscn" id="12_inv"]
+[ext_resource type="PackedScene" path="res://ui/stance_indicator.tscn" id="13_stance"]
+[ext_resource type="PackedScene" path="res://ui/world_radial.tscn" id="14_radial"]
+[ext_resource type="PackedScene" path="res://ui/dialogue_box.tscn" id="15_dialogue"]
+[ext_resource type="Script" path="res://scripts/rendering/fog_entities.gd" id="16_fogent"]
+[ext_resource type="Script" path="res://scripts/rendering/sound_indicator_renderer.gd" id="20_soundind"]
+[ext_resource type="PackedScene" path="res://ui/gauntlet_hud.tscn" id="17_gauntlet"]
+[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://scripts/ui/debug_overlay.gd" id="22_debug"]

 [node name="Game" type="Node2D"]
 script = ExtResource("1_main")

+; D-049 Z-level rendering pipeline (z-layer-gap-analysis.md)
+;
+; World scope (z:-200 to z:900, inside FogGroup CanvasGroup):
+;   z:0     FloorTiles     — ground plane
+;   z:10    FloorObjects   — cosmetic floor detail, ground shadows
+;   z:100   YSortGroup     — y-sorted: furniture, entities, wall faces (all z:0 relative)
+;   z:200   [future]       — airborne (projectiles, low-flying objects)
+;   z:300   Overhead        — ceiling edges, semi-transparent occlusion
+;   z:350   [future]       — high airborne (above ceiling, scale > 1.0)
+;   z:400   [future]       — upper floor content (rare with fixed camera)
+;   z:900   FogOverlay     — OUTSIDE FogGroup, fog shader
+;
+; Y-sort contract: ALL children of YSortGroup that participate in positional
+; occlusion MUST have z_index = 0. z_index is PRIMARY sort, y is SECONDARY.
+; Entities node is AFTER Furniture node — D-044 entity-wins-ties on same y.
+
 [node name="World" type="Node2D" parent="."]
 script = ExtResource("2_world")

-[node name="TileMapLayer" type="TileMapLayer" parent="World"]
+; --- World content inside CanvasGroup for fog compositing ---
+; CanvasGroup captures everything beneath it into one texture.
+; FogOverlay (outside) draws the fog shader over this composited texture.

-[node name="Entities" type="Node2D" parent="World"]
+[node name="FogGroup" type="CanvasGroup" parent="World"]
+
+; z:0 — Floor tiles: zone identity, movement surface
+[node name="FloorTiles" type="TileMapLayer" parent="World/FogGroup"]
+z_index = 0
+script = ExtResource("5_tile")
+
+; z:10 — Floor objects: cosmetic detail, walked over, ground shadows from airborne
+; (placeholder — populated when floor object art is added)
+[node name="FloorObjects" type="Node2D" parent="World/FogGroup"]
+z_index = 10
+
+; z:100 — Y-sorted group: furniture + entities + wall faces interleave by y-position
+; ALL children MUST use z_index = 0 (y-sort contract, Godot #62715)
+[node name="YSortGroup" type="Node2D" parent="World/FogGroup"]
+y_sort_enabled = true
+z_index = 100
+
+; Furniture (z:0 relative) — tables, chairs, placed objects
+; Placeholder — before Entities in tree order so entities win visual ties (D-044)
+[node name="Furniture" type="Node2D" parent="World/FogGroup/YSortGroup"]
+y_sort_enabled = true
+z_index = 0
+
+; Entities (z:0 relative) — D-033 colored sprites, y-sorted with furniture
+; MUST be z_index = 0 for correct y-sort interleaving
+[node name="Entities" type="Node2D" parent="World/FogGroup/YSortGroup"]
+y_sort_enabled = true
+z_index = 0
 script = ExtResource("3_entity")

+; z:300 — Overhead: ceiling edges, upper floor structure, semi-transparent occlusion
+; (placeholder — populated when overhead art is added)
+[node name="Overhead" type="Node2D" parent="World/FogGroup"]
+z_index = 300
+
+; --- z:900 — Fog of perception (D-059 shader-based) ---
+; OUTSIDE FogGroup. ColorRect child with fragment shader composites
+; 5-layer fog over the world. fog_shader.gd manages uniforms.
 [node name="FogOverlay" type="Node2D" parent="World"]
+z_index = 900
 script = ExtResource("4_fog")

+; --- z:950 — Fog entities (D-059/D-060 cognitive delay visualization) ---
+; Between fog (z:900) and InsertOverlay (CanvasLayer 10).
+; Sound pings, grey blobs, recognized entity glow + silhouette.
+[node name="FogEntities" type="Node2D" parent="World"]
+z_index = 950
+script = ExtResource("16_fogent")
+
+; --- z:951 — Medium-range sound indicators (#126, D-018) ---
+; Directional arrows at fog boundary for sounds outside LOS.
+; Above FogEntities (z:950), below InsertOverlay (CanvasLayer 10).
+[node name="SoundIndicators" type="Node2D" parent="World"]
+z_index = 951
+script = ExtResource("20_soundind")
+
+; --- Camera ---
 [node name="Camera2D" type="Camera2D" parent="."]
+position_smoothing_enabled = true
+position_smoothing_speed = 6.0
+zoom = Vector2(2, 2)

+; --- Insert overlay (CanvasLayer 10) ---
+; Bloom-rendered, NOT affected by fog or camera transform.
+; World-anchored elements convert world→screen coords in scripts.
+[node name="InsertOverlay" type="CanvasLayer" parent="."]
+layer = 10
+
+; InteractionPrompt — v0.1 fallback single-line "E - Talk" display
+[node name="InteractionPrompt" parent="InsertOverlay" instance=ExtResource("9_prompt")]
+
+; D-057: Entity interaction vertical list — multi-verb, insert-styled
+[node name="InteractionList" parent="InsertOverlay" instance=ExtResource("11_ilist")]
+
+; D-058: World radial menu — right-click, 2 spokes (Observe + Insert)
+[node name="WorldRadial" parent="InsertOverlay" instance=ExtResource("14_radial")]
+
+; D-061: Dialogue box — bottom screen, max 20% height, diegetic insert UI
+[node name="DialogueBox" parent="InsertOverlay" instance=ExtResource("15_dialogue")]
+
+; --- UI layer (CanvasLayer 20) ---
+; HUD, monologue, cursor — always visible, not affected by fog or camera.
 [node name="UILayer" type="CanvasLayer" parent="."]
+layer = 20

-[node name="HUD" parent="UILayer" instance=ExtResource("5_hud")]
+[node name="HUD" parent="UILayer" instance=ExtResource("6_hud")]

-[node name="Minimap" parent="UILayer" instance=ExtResource("6_minimap")]
+[node name="Minimap" parent="UILayer" instance=ExtResource("7_minimap")]

-[node name="MonologueDisplay" parent="UILayer" instance=ExtResource("7_monologue")]
+[node name="MonologueDisplay" parent="UILayer" instance=ExtResource("8_monologue")]
+
+; D-053: Stance indicator — top-right, color-coded
+[node name="StanceIndicator" parent="UILayer" instance=ExtResource("13_stance")]
+
+; #496: Gauntlet HUD — room timer + personal bests, hidden in non-gauntlet mode
+[node name="GauntletHUD" parent="UILayer" instance=ExtResource("17_gauntlet")]
+
+; #503: Auto-checklist overlay — condition progress in gauntlet mode
+[node name="ChecklistOverlay" parent="UILayer" instance=ExtResource("18_checklist")]
+
+; 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")
+
+; D-056: Cursor state machine — insert-styled geometric cursor, topmost in UILayer
+[node name="CursorRenderer" type="Node2D" parent="UILayer"]
+script = ExtResource("10_cursor")
+
+; --- Modal layer (CanvasLayer 30) ---
+; Full-screen overlays: pause menu, inventory modal, death screen.
+[node name="ModalLayer" type="CanvasLayer" parent="."]
+layer = 30
+
+; #495: WRONG button (F12) — bug report capture dialog
+[node name="BugReportDialog" parent="ModalLayer" instance=ExtResource("19_bugreport")]
+
+; #528: Audio settings dialog — 5-bus volume sliders, ESC/OPEN_MENU to toggle
+[node name="SettingsDialog" parent="ModalLayer" instance=ExtResource("21_settings")]
@@ -0,0 +1,438 @@
+extends Node
+
+## AudioManager autoload singleton (D-068, D-069, D-073).
+## 5-bus architecture with directory-scan registry pattern.
+## No-op fallback when audio assets absent (D-038).
+## Spatial audio positioning for close-range sounds (D-018).
+
+# --- D-067: Recognition chime asset key ---
+# Fires on first fog recognition (cognitive delay onset). UISounds bus (not WorldSFX).
+# Matches sfx_monologue_chime.ogg from D-038 — "neural lattice firing" feel.
+const CHIME_RECOGNITION := "sfx_monologue_chime"
+
+# --- Bus names (D-068) ---
+const BUS_MUSIC := "Music"
+const BUS_AMBIENT := "Ambient"
+const BUS_WORLD_SFX := "WorldSFX"
+const BUS_PLAYER_ACTIONS := "PlayerActions"
+const BUS_UI_SOUNDS := "UISounds"
+const BUSES := [BUS_MUSIC, BUS_AMBIENT, BUS_WORLD_SFX, BUS_PLAYER_ACTIONS, BUS_UI_SOUNDS]
+
+# D-069: Audio dip profiles — dB offsets relative to player slider setting.
+# Mid-range of spec values used (e.g. -6 to -8 → -7).
+# NOTE: listening_focus requires 30+ stationary ticks before activation (D-069/D-071).
+# The tick gate is the caller's responsibility — AudioManager only manages bus volumes.
+const DIP_SPECS := {
+	"dialogue": {
+		"ease_in": 0.3, "ease_out": 0.5,
+		"buses": { "Ambient": -7.0 },
+	},
+	"confrontation": {
+		"ease_in": 0.5, "ease_out": 1.0,
+		"buses": { "Ambient": -11.0, "WorldSFX": -5.0 },
+		"filter_hz": 800.0,
+	},
+	"listening_focus": {
+		"ease_in": 0.5, "ease_out": 0.5,
+		"buses": { "WorldSFX": 2.5 },
+	},
+}
+
+# Low-pass filter default cutoff — effectively bypassed at this value.
+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://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
+# D-038's "amb_workplace_layer" to "amb_hub_layer" for v0.1.
+# Note: amb_station_base (D-038 global base hum) plays globally via play_loop()
+# at startup — it is not zone-dependent and has no ZONE_ASSETS entry.
+const ZONE_ASSETS: Dictionary = {
+	"hub":       "amb_hub_layer",
+	"workplace": "amb_hub_layer",
+	"bar":       "amb_bar_layer",
+	"corridor":  "amb_corridor_layer",
+}
+
+# Asset registry: filename stem (e.g. "amb_station_base") → AudioStream
+var _registry: Dictionary = {}
+
+# Player volume settings per bus (dB). Base for proportional dip calculation.
+var _bus_volumes: Dictionary = {}
+
+# Active dip state (D-069)
+var _active_dip: String = ""
+var _dip_tweens: Array = []
+
+# Low-pass filter on Ambient bus (D-069 confrontation sweep)
+var _ambient_filter: AudioEffectLowPassFilter = null
+
+# Ambient loop players keyed by asset_key (D-073 zone crossfade)
+var _ambient_players: Dictionary = {}
+
+# D-073: Zone crossfade state
+var _current_zone_id: String = ""
+var _zone_tweens: Array = []
+
+signal dip_changed(profile: String)
+
+
+const PREFS_PATH := "user://audio_prefs.cfg"
+
+func _ready() -> void:
+	_setup_buses()
+	_scan_registry()
+	_load_prefs()
+
+
+# --- Bus setup ---
+
+func _setup_buses() -> void:
+	for bus_name in BUSES:
+		if AudioServer.get_bus_index(bus_name) < 0:
+			AudioServer.add_bus()
+			var idx := AudioServer.bus_count - 1
+			AudioServer.set_bus_name(idx, bus_name)
+			AudioServer.set_bus_send(idx, "Master")
+		_bus_volumes[bus_name] = 0.0
+	# Low-pass filter on Ambient bus — cutoff starts high (bypassed).
+	# Confrontation dip sweeps it down to 800 Hz (D-069).
+	# Guard: skip if filter already exists (e.g. duplicate _ready in tests).
+	var amb_idx := AudioServer.get_bus_index(BUS_AMBIENT)
+	if amb_idx >= 0 and _ambient_filter == null:
+		_ambient_filter = AudioEffectLowPassFilter.new()
+		_ambient_filter.cutoff_hz = FILTER_CUTOFF_DEFAULT
+		AudioServer.add_bus_effect(amb_idx, _ambient_filter)
+
+
+# --- Asset registry (D-068 directory-scan pattern) ---
+
+func _scan_registry() -> void:
+	_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://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()
+	while file_name != "":
+		var full_path := path.path_join(file_name)
+		if dir.current_is_dir():
+			_scan_dir(full_path)
+		elif not file_name.ends_with(".import"):
+			if file_name.get_extension().to_lower() in ["ogg", "wav", "mp3"]:
+				var stream := load(full_path) as AudioStream
+				if stream:
+					_registry[file_name.get_basename()] = stream
+		file_name = dir.get_next()
+	dir.list_dir_end()
+
+
+func has_asset(asset_key: String) -> bool:
+	return _registry.has(asset_key)
+
+
+func get_registry_size() -> int:
+	return _registry.size()
+
+
+# --- Playback: non-spatial ---
+
+## Play a one-shot sound on the given bus. No-ops if asset not in registry.
+func play(asset_key: String, bus: String = BUS_UI_SOUNDS) -> void:
+	var stream := _get_stream(asset_key)
+	if stream == null:
+		return
+	var player := AudioStreamPlayer.new()
+	player.stream = stream
+	player.bus = bus
+	add_child(player)
+	player.finished.connect(player.queue_free)
+	player.play()
+
+
+## Start or replace a looping non-spatial sound. Returns the player or null.
+func play_loop(asset_key: String, bus: String = BUS_AMBIENT) -> AudioStreamPlayer:
+	var stream := _get_stream(asset_key)
+	if stream == null:
+		return null
+	stop_loop(asset_key)
+	var loop_stream := stream.duplicate() as AudioStream
+	if loop_stream == null:
+		return null
+	_enable_loop(loop_stream)
+	var player := AudioStreamPlayer.new()
+	player.stream = loop_stream
+	player.bus = bus
+	add_child(player)
+	player.play()
+	_ambient_players[asset_key] = player
+	return player
+
+
+## Stop a looping sound by asset key.
+func stop_loop(asset_key: String) -> void:
+	if _ambient_players.has(asset_key):
+		var player: AudioStreamPlayer = _ambient_players[asset_key]
+		if is_instance_valid(player):
+			player.stop()
+			player.queue_free()
+		_ambient_players.erase(asset_key)
+
+
+## Stop all looping sounds.
+func stop_all_loops() -> void:
+	for key in _ambient_players.keys():
+		stop_loop(key)
+
+
+# --- 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://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 = {
+	"Footstep":       "sfx_footstep_metal_walk",
+	"FootstepWalk":   "sfx_footstep_metal_walk",
+	"FootstepCareful":"sfx_footstep_metal_walk",  # D-053: same asset until stance-differentiated audio lands
+	"FootstepCrouch": "sfx_footstep_metal_walk",  # D-053: same asset until stance-differentiated audio lands
+	"FootstepSprint": "sfx_footstep_metal_run",
+	"FootstepRun":    "sfx_footstep_metal_run",
+}
+
+
+## Play a close-range sound event at a world tile position (D-018, #125).
+## event_type: server RangeCategory::Close event type string (e.g. "Footstep").
+## world_tile_pos: server tile coordinates — converted to world pixels internally.
+## No-ops if event_type has no registered asset or asset file is absent.
+func play_sound_event(event_type: String, world_tile_pos: Vector2) -> void:
+	var asset_key: String = SOUND_EVENT_ASSETS.get(event_type, "")
+	if asset_key.is_empty():
+		return
+	play_at(asset_key, world_tile_pos * Constants.TILE_SIZE)
+
+
+# --- Playback: spatial (D-018 close-range) ---
+
+## Play a one-shot spatial sound at a world position (pixels).
+## Added to current_scene for correct AudioListener2D positioning.
+func play_at(asset_key: String, world_position: Vector2, bus: String = BUS_WORLD_SFX) -> void:
+	var stream := _get_stream(asset_key)
+	if stream == null:
+		return
+	var player := AudioStreamPlayer2D.new()
+	player.stream = stream
+	player.bus = bus
+	player.global_position = world_position
+	var scene := get_tree().current_scene
+	if scene:
+		scene.add_child(player)
+	else:
+		add_child(player)
+	player.finished.connect(player.queue_free)
+	player.play()
+
+
+# --- Audio dip profiles (D-069) ---
+
+## Apply a dip profile. Interrupts any active dip, restoring unaffected buses.
+## Profiles: "dialogue", "confrontation", "listening_focus"
+func apply_dip(profile: String) -> void:
+	if not DIP_SPECS.has(profile):
+		push_warning("AudioManager: unknown dip profile '%s'" % profile)
+		return
+	_kill_tweens()
+	_active_dip = profile
+	var spec: Dictionary = DIP_SPECS[profile]
+	var buses: Dictionary = spec.get("buses", {})
+	var ease_in: float = spec.get("ease_in", 0.3)
+	# Tween ALL buses — affected ones get offset, unaffected ones restore to base.
+	for bus_name in BUSES:
+		var offset_db: float = buses.get(bus_name, 0.0)
+		var target_db: float = _bus_volumes.get(bus_name, 0.0) + offset_db
+		var idx := AudioServer.get_bus_index(bus_name)
+		if idx < 0:
+			continue
+		var current_db := AudioServer.get_bus_volume_db(idx)
+		if absf(current_db - target_db) < 0.1:
+			continue
+		var tween := create_tween()
+		tween.tween_method(_make_bus_setter(bus_name), current_db, target_db, ease_in)
+		_dip_tweens.append(tween)
+	# Confrontation: sweep low-pass filter on Ambient (D-069)
+	if spec.has("filter_hz") and _ambient_filter:
+		var tween := create_tween()
+		tween.tween_property(_ambient_filter, "cutoff_hz", spec["filter_hz"], ease_in)
+		_dip_tweens.append(tween)
+	elif _ambient_filter and _ambient_filter.cutoff_hz < FILTER_CUTOFF_DEFAULT - 100.0:
+		# Leaving confrontation for another dip — restore filter
+		var tween := create_tween()
+		tween.tween_property(_ambient_filter, "cutoff_hz", FILTER_CUTOFF_DEFAULT, ease_in)
+		_dip_tweens.append(tween)
+	dip_changed.emit(profile)
+
+
+## Clear the active dip, restoring all bus volumes to player slider settings.
+func clear_dip() -> void:
+	if _active_dip.is_empty():
+		return
+	var spec: Dictionary = DIP_SPECS.get(_active_dip, {})
+	var ease_out: float = spec.get("ease_out", 0.5)
+	_kill_tweens()
+	_active_dip = ""
+	for bus_name in BUSES:
+		var target_db: float = _bus_volumes.get(bus_name, 0.0)
+		var idx := AudioServer.get_bus_index(bus_name)
+		if idx < 0:
+			continue
+		var current_db := AudioServer.get_bus_volume_db(idx)
+		if absf(current_db - target_db) < 0.1:
+			continue
+		var tween := create_tween()
+		tween.tween_method(_make_bus_setter(bus_name), current_db, target_db, ease_out)
+		_dip_tweens.append(tween)
+	# Restore low-pass filter
+	if _ambient_filter and _ambient_filter.cutoff_hz < FILTER_CUTOFF_DEFAULT - 100.0:
+		var tween := create_tween()
+		tween.tween_property(_ambient_filter, "cutoff_hz", FILTER_CUTOFF_DEFAULT, ease_out)
+		_dip_tweens.append(tween)
+	dip_changed.emit("")
+
+
+func get_active_dip() -> String:
+	return _active_dip
+
+
+# --- Volume control (player sliders, D-069 proportional base) ---
+
+## Set the player's volume preference for a bus. During active dip, immediately
+## recalculates effective volume (proportional to new base).
+func set_volume(bus: String, volume_db: float) -> void:
+	_bus_volumes[bus] = volume_db
+	var idx := AudioServer.get_bus_index(bus)
+	if idx < 0:
+		return
+	if _active_dip.is_empty():
+		AudioServer.set_bus_volume_db(idx, volume_db)
+	else:
+		var spec: Dictionary = DIP_SPECS.get(_active_dip, {})
+		var buses: Dictionary = spec.get("buses", {})
+		var offset_db: float = buses.get(bus, 0.0)
+		AudioServer.set_bus_volume_db(idx, volume_db + offset_db)
+	_save_prefs()
+
+
+func get_volume(bus: String) -> float:
+	return _bus_volumes.get(bus, 0.0)
+
+
+# --- Volume persistence (user://audio_prefs.cfg) ---
+
+func _load_prefs() -> void:
+	var cfg := ConfigFile.new()
+	if cfg.load(PREFS_PATH) != OK:
+		return
+	for bus_name in BUSES:
+		if cfg.has_section_key("audio", bus_name):
+			var db: float = cfg.get_value("audio", bus_name, 0.0)
+			# Apply directly: bypass _save_prefs() on initial load.
+			_bus_volumes[bus_name] = db
+			var idx := AudioServer.get_bus_index(bus_name)
+			if idx >= 0:
+				AudioServer.set_bus_volume_db(idx, db)
+
+
+func _save_prefs() -> void:
+	var cfg := ConfigFile.new()
+	for bus_name in BUSES:
+		cfg.set_value("audio", bus_name, _bus_volumes.get(bus_name, 0.0))
+	var err := cfg.save(PREFS_PATH)
+	if err != OK:
+		push_warning("AudioManager: failed to save prefs to %s (error %d)" % [PREFS_PATH, err])
+
+
+# --- Zone crossfade (D-073) ---
+
+## Handle zone transition. Server sends zone_id per tile in ObserverSnapshot.
+## Hard boundary trigger with 1.5-2s audio crossfade between ambient layers.
+## Interruptible — mid-crossfade zone change tweens from current position.
+## No-op if assets absent (D-038) or same zone.
+func set_zone(zone_id: String) -> void:
+	if zone_id == _current_zone_id:
+		return
+	var new_asset: String = ZONE_ASSETS.get(zone_id, "")
+	var old_asset: String = ZONE_ASSETS.get(_current_zone_id, "")
+	_current_zone_id = zone_id
+	_kill_zone_tweens()
+
+	# Fade out old ambient layer (if different asset from incoming zone)
+	if not old_asset.is_empty() and old_asset != new_asset:
+		if _ambient_players.has(old_asset):
+			var old_player: AudioStreamPlayer = _ambient_players[old_asset]
+			if is_instance_valid(old_player):
+				var tween := create_tween()
+				tween.tween_property(old_player, "volume_db", -80.0, CROSSFADE_DURATION)
+				tween.tween_callback(stop_loop.bind(old_asset))
+				_zone_tweens.append(tween)
+
+	# Fade in new ambient layer
+	if not new_asset.is_empty():
+		if _ambient_players.has(new_asset):
+			# Already playing (interrupted reverse crossfade) — tween from current volume
+			var existing: AudioStreamPlayer = _ambient_players[new_asset]
+			if is_instance_valid(existing):
+				var tween := create_tween()
+				tween.tween_property(existing, "volume_db", 0.0, CROSSFADE_DURATION)
+				_zone_tweens.append(tween)
+		elif has_asset(new_asset):
+			var new_player := play_loop(new_asset, BUS_AMBIENT)
+			if new_player:
+				new_player.volume_db = -80.0
+				var tween := create_tween()
+				tween.tween_property(new_player, "volume_db", 0.0, CROSSFADE_DURATION)
+				_zone_tweens.append(tween)
+
+
+func _kill_zone_tweens() -> void:
+	for tween in _zone_tweens:
+		if tween != null and tween.is_valid():
+			tween.kill()
+	_zone_tweens.clear()
+
+
+# --- Internal helpers ---
+
+func _get_stream(asset_key: String) -> AudioStream:
+	return _registry.get(asset_key) as AudioStream
+
+
+func _make_bus_setter(bus_name: String) -> Callable:
+	return func(db: float) -> void:
+		var idx := AudioServer.get_bus_index(bus_name)
+		if idx >= 0:
+			AudioServer.set_bus_volume_db(idx, db)
+
+
+func _kill_tweens() -> void:
+	for tween in _dip_tweens:
+		if tween != null and tween.is_valid():
+			tween.kill()
+	_dip_tweens.clear()
+
+
+static func _enable_loop(stream: AudioStream) -> void:
+	if stream is AudioStreamOggVorbis:
+		stream.loop = true
+	elif stream is AudioStreamWAV:
+		stream.loop_mode = AudioStreamWAV.LOOP_FORWARD
+	elif stream is AudioStreamMP3:
+		stream.loop = true
@@ -0,0 +1 @@
+uid://cdkut8u7sxwmb
@@ -0,0 +1,129 @@
+extends Node
+
+## Fog texture state — visibility/exploration/zone tint images updated from GameState.
+## Read by fog_shader.gd for shader uniforms. Not a renderer — pure data.
+## Architecture: docs/architecture/fog-shader-spec.md | D-059
+
+# Fog texture byte values — visibility and exploration layers.
+# 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_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)
+
+var map_bounds: Rect2i = Rect2i(0, 0, 1, 1)
+var visibility_texture: ImageTexture
+var exploration_texture: ImageTexture
+var zone_tint_texture: ImageTexture
+
+var _vis_bytes: PackedByteArray
+var _exp_bytes: PackedByteArray
+var _vis_image: Image
+var _exp_image: Image
+var _tint_image: Image
+var _width: int = 1
+var _height: int = 1
+var _prev_visible: Dictionary = {}  # Tiles visible last frame (for incremental decay)
+
+
+func _ready() -> void:
+	_resize(Rect2i(0, 0, 64, 64))
+
+
+func _resize(bounds: Rect2i) -> void:
+	map_bounds = bounds
+	_width = maxi(bounds.size.x, 1)
+	_height = maxi(bounds.size.y, 1)
+	var sz := _width * _height
+
+	_vis_bytes = PackedByteArray()
+	_vis_bytes.resize(sz)
+	_vis_bytes.fill(VIS_HIDDEN)
+	_vis_image = Image.create_from_data(_width, _height, false, Image.FORMAT_R8, _vis_bytes)
+	visibility_texture = ImageTexture.create_from_image(_vis_image)
+
+	_exp_bytes = PackedByteArray()
+	_exp_bytes.resize(sz)
+	_exp_bytes.fill(EXP_UNEXPLORED)
+	_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_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)
+		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
+	_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_image.set_data(_width, _height, false, Image.FORMAT_R8, _vis_bytes)
+	visibility_texture.update(_vis_image)
+
+	# 2. Exploration: tiles leaving LOS decay to EXP_EXPLORED, visible tiles stay EXP_VISIBLE
+	#    Only touch tiles that changed (O(visible) not O(map_size))
+	for pos in _prev_visible:
+		if not positions.has(pos):
+			var px: int = pos.x - ox
+			var py: int = pos.y - oy
+			if px >= 0 and py >= 0 and px < _width and py < _height:
+				var idx: int = py * _width + px
+				if _exp_bytes[idx] > EXP_EXPLORED:
+					_exp_bytes[idx] = EXP_EXPLORED
+
+	for pos in positions:
+		var px: int = pos.x - ox
+		var py: int = pos.y - oy
+		if px >= 0 and py >= 0 and px < _width and py < _height:
+			_exp_bytes[py * _width + px] = EXP_VISIBLE
+	_exp_image.set_data(_width, _height, false, Image.FORMAT_R8, _exp_bytes)
+	exploration_texture.update(_exp_image)
+
+	# Shallow copy — correct for Dictionary<Vector2i, bool/String> values
+	_prev_visible = positions.duplicate()
+
+
+func _compute_bounds(tiles: Array) -> Rect2i:
+	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
+	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)
@@ -0,0 +1 @@
+uid://de816lfn5xeqs
@@ -1,16 +1,94 @@
 extends Node

-# Updated each frame from ObserverSnapshot data (Protocol format: {tick, entities}).
+# 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 = {}
 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
+
+# v2 fields (D-015, D-031)
+var game_time: Dictionary = {}  # {day, time_of_day, day_phase, tick_rate} or empty
+var player_facing: String = "North"  # 8-directional facing direction
+var visibility_sectors: Dictionary = {}  # Vector2i -> "Forward"/"Peripheral"

 # Player entity ID — the first entity is assumed to be the player (will be
 # 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, 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
+var player_inventory: Array = []  # [{item_id, name, slot}]
+
+# v7 fields (#435, D-061/D-062)
+var current_dialogue: Variant = null  # {npc_name, npc_entity_id, speech, options: [{text, response_id, priority}]} or null
+
+# D-064: true while dialogue box is visible or fading out (300ms).
+# InputMapper suppresses movement when this is true.
+var dialogue_active: bool = false
+
+# v8 fields (#496): Gauntlet mode — room timer + personal bests
+var room_id: Variant = null  # String room_id from snapshot, null in non-gauntlet mode
+var gauntlet_mode: bool = false  # true when snapshot includes gauntlet_mode flag
+
+# OQ-07 (#522): Insert active state — false suppresses verb labels (z-layer 6).
+# Cursor shape changes still fire when false (D-056 option a).
+# v0.1 assumption: always true — both playable characters (detective and smuggler)
+# have neural inserts. Future characters without inserts would receive false from
+# the server's "insert_active" snapshot field, disabling all z-layer-6 UI.
+var insert_active: bool = true
+
+# #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
+
+# 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}]
+
+# #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 = []
+
+# #125, D-018: Close-range sound events for positional 2D audio.
+# Format: [{x, y, event_type, range_category}] — consumed once per tick in main.gd.
+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.
+# ListeningFocus boost activates at 30+ ticks (main.gd manages the dip).
+var stationary_ticks: int = 0
+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).
+var current_zone_id: String = ""
+
 func apply_snapshot(snapshot: Dictionary) -> void:
 	current_snapshot = snapshot

@@ -19,8 +97,172 @@ func apply_snapshot(snapshot: Dictionary) -> void:

 	if snapshot.has("entities"):
 		visible_entities = snapshot.entities
-		# Derive player position from the player entity
+		# Derive player position from the entity with kind.variant == "Player"
+		var found_player := false
 		for entity in visible_entities:
-			if entity.has("entity_id") and entity.entity_id == player_entity_id:
+			if entity.has("kind") and entity.kind is Dictionary and entity.kind.get("variant") == "Player":
 				player_position = Vector2(entity.x, entity.y)
+				if entity.has("entity_id"):
+					player_entity_id = entity.entity_id
+				found_player = true
 				break
+		if not found_player and visible_entities.size() > 0:
+			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
+	else:
+		stationary_ticks = 0
+	_prev_player_position = player_position
+
+	# Tiles for rendering: test mode sends "tiles", live server sends tile data in "visible_tiles"
+	if snapshot.has("tiles"):
+		visible_tiles = snapshot.tiles
+	elif snapshot.has("visible_tiles") and snapshot.visible_tiles is Array and snapshot.visible_tiles.size() > 0:
+		# Live server: visible_tiles now includes type from tile_kind field
+		var has_type := false
+		if snapshot.visible_tiles.size() > 0 and snapshot.visible_tiles[0] is Dictionary:
+			has_type = snapshot.visible_tiles[0].has("type")
+		if has_type:
+			visible_tiles = snapshot.visible_tiles
+
+	if snapshot.has("visible_positions"):
+		visible_positions.clear()
+		for pos in snapshot.visible_positions:
+			visible_positions[Vector2i(pos.x, pos.y)] = true
+
+	# v2: game_time (D-031)
+	if snapshot.has("game_time") and snapshot.game_time is Dictionary:
+		game_time = snapshot.game_time
+
+	# v2: player_facing (D-015)
+	if snapshot.has("player_facing") and snapshot.player_facing is String:
+		player_facing = snapshot.player_facing
+
+	# v4: nearby_interactions (#404/#405)
+	if snapshot.has("nearby_interactions") and snapshot.nearby_interactions is Array:
+		nearby_interactions = snapshot.nearby_interactions
+	else:
+		nearby_interactions = []
+
+	# v5: current_monologue (#414)
+	if snapshot.has("current_monologue") and snapshot.current_monologue is Dictionary:
+		current_monologue = snapshot.current_monologue
+	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
+
+	# v6: player_inventory (#449, D-065)
+	if snapshot.has("player_inventory") and snapshot.player_inventory is Array:
+		player_inventory = snapshot.player_inventory
+	else:
+		player_inventory = []
+
+	# v7: current_dialogue (#434, D-061)
+	if snapshot.has("current_dialogue") and snapshot.current_dialogue is Dictionary:
+		current_dialogue = snapshot.current_dialogue
+	else:
+		current_dialogue = null
+
+	# v7: pending_recognitions (#431, D-059/D-060)
+	if snapshot.has("pending_recognitions") and snapshot.pending_recognitions is Array:
+		pending_recognitions = snapshot.pending_recognitions
+	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
+	else:
+		gauntlet_mode = false
+	if snapshot.has("room_id") and snapshot.room_id is String:
+		room_id = snapshot.room_id
+	else:
+		room_id = null
+
+	# OQ-07 (#522): insert_active — defaults true (v0.1 always has insert).
+	# Server may send false for characters without an insert in future sprints.
+	if snapshot.has("insert_active") and snapshot.insert_active is bool:
+		insert_active = snapshot.insert_active
+	else:
+		insert_active = true
+
+	# #507: rng_seed — server sends current RNG seed for replay determinism.
+	# Field: "rng_seed" (u64 as integer). Null if server does not include it.
+	if snapshot.has("rng_seed"):
+		rng_seed = snapshot.rng_seed
+	else:
+		rng_seed = null
+
+	# D-018: Sound events from server — partition by range_category.
+	# #126: Medium → fog-edge directional indicators.
+	# #125: Close → positional 2D audio via AudioManager.
+	if snapshot.has("sound_events") and snapshot.sound_events is Array:
+		medium_sound_events = []
+		close_sound_events = []
+		for se in snapshot.sound_events:
+			if not se is Dictionary:
+				continue
+			var rc: String = se.get("range_category", "")
+			if rc == "Medium":
+				medium_sound_events.append(se)
+			elif rc == "Close":
+				close_sound_events.append(se)
+	else:
+		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
+
+	# v2: visible_tiles with visibility sectors
+	# Derives visible_positions when not explicitly provided (real server mode)
+	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()
+		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)
+			if vtile.has("visibility"):
+				visibility_sectors[pos] = vtile.visibility
+			if not has_explicit_positions:
+				visible_positions[pos] = true
@@ -1,55 +1,218 @@
 extends Node

 # Semantic actions — NO raw key codes cross the bridge
-# Diagonal directions registered in project.godot with empty event arrays (intentional).
-# Keybindings deferred until input design is finalized — likely numpad or composite WASD.
+# Movement uses hold-to-move (polled each frame in _process).
+# Discrete actions (interact, stance, etc.) use press events (_unhandled_input).
+#
+# D-054: Mouse-relative facing and movement.
+# Mouse position determines facing direction (client-side float).
+# WASD is relative to facing: W = toward cursor, S = away, A/D = strafe.
+# Server receives facing octant only — the full float stays client-side.
+#
+# Movement throttle: client-side rate limit per stance (D-053).
+# Sprint=5/s, Walk=2.5/s, Careful=1.7/s, Crouch=1.25/s.
+# Server cooldown is authoritative, but the client throttle prevents
+# flooding and gives correct movement feel in test mode.
 enum Action {
 	MOVE_NORTH, MOVE_NORTHEAST, MOVE_EAST, MOVE_SOUTHEAST,
 	MOVE_SOUTH, MOVE_SOUTHWEST, MOVE_WEST, MOVE_NORTHWEST,
-	INTERACT, USE_PERCEPTION_MODE, OPEN_MENU, PAUSE
+	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
+	SET_FACING,  # D-054: facing octant update (no movement)
+	TELEPORT_HUB,  # #501: Home key — Gauntlet dev teleport (not production fast-travel)
 }

 var input_queue: Array[Dictionary] = []

+# D-054: Client-side facing angle (radians). 0=East, -PI/2=North, PI/2=South.
+# Updated every frame from mouse position. EntityRenderer reads this for indicator.
+var facing_angle: float = -PI / 2.0  # Default: North
+var facing_octant: String = "North"   # Derived from facing_angle
+var _last_sent_octant: String = "North"  # Track to avoid redundant sends
+
+# Minimum milliseconds between movement commands, per stance.
+# Tuned so Walk feels like walking, Sprint feels fast but readable.
+const MOVE_INTERVAL_MS := {
+	"Sprint": 200,    # 5/sec — fast but trackable
+	"Walk": 400,      # 2.5/sec — comfortable walking pace
+	"Careful": 600,   # ~1.7/sec — deliberate, scanning
+	"Crouch": 800,    # 1.25/sec — creeping
+}
+var _last_move_msec: int = 0
+
+
+# Hold-to-move: poll held direction keys each frame, throttled by stance.
+# D-054: WASD is now mouse-relative. W = toward cursor, A/D = strafe.
+# Server-side cooldown (D-053) is authoritative; this prevents client flooding.
+# D-064: movement suppressed during dialogue (walk-away handled by dialogue_box).
+func _process(_delta: float) -> void:
+	# D-054: Update facing angle from mouse position every frame
+	_update_facing_from_mouse()
+
+	if GameState.dialogue_active:
+		return
+
+	# D-054: Send facing octant to server when it changes (even without movement)
+	if facing_octant != _last_sent_octant:
+		_last_sent_octant = facing_octant
+		input_queue.append({
+			"action": Action.SET_FACING,
+			"timestamp_msec": Time.get_ticks_msec(),
+			"action_data": {"facing": facing_octant},
+		})
+
+	# Poll held WASD keys
+	var raw_dir := Vector2i.ZERO
+	if Input.is_action_pressed("move_north"):
+		raw_dir.y -= 1
+	if Input.is_action_pressed("move_south"):
+		raw_dir.y += 1
+	if Input.is_action_pressed("move_east"):
+		raw_dir.x += 1
+	if Input.is_action_pressed("move_west"):
+		raw_dir.x -= 1
+
+	if raw_dir != Vector2i.ZERO:
+		var now := Time.get_ticks_msec()
+		var interval: int = MOVE_INTERVAL_MS.get(GameState.player_stance, 200)
+		if now - _last_move_msec >= interval:
+			_last_move_msec = now
+			# D-054: Transform WASD input relative to mouse facing
+			var world_dir := _wasd_to_world_dir(raw_dir)
+			var action: Action = _dir_to_action(world_dir)
+			input_queue.append({
+				"action": action,
+				"timestamp_msec": now,
+			})
+
+
+# Discrete actions: fire once on key press (not held).
 func _unhandled_input(event: InputEvent) -> void:
 	var action: Action = -1

-	# Map input actions to semantic Action enum
-	# is_action_pressed handles press detection for all input types (key, gamepad, etc.)
-	if event.is_action_pressed("move_north"):
-		action = Action.MOVE_NORTH
-	elif event.is_action_pressed("move_northeast"):
-		action = Action.MOVE_NORTHEAST
-	elif event.is_action_pressed("move_east"):
-		action = Action.MOVE_EAST
-	elif event.is_action_pressed("move_southeast"):
-		action = Action.MOVE_SOUTHEAST
-	elif event.is_action_pressed("move_south"):
-		action = Action.MOVE_SOUTH
-	elif event.is_action_pressed("move_southwest"):
-		action = Action.MOVE_SOUTHWEST
-	elif event.is_action_pressed("move_west"):
-		action = Action.MOVE_WEST
-	elif event.is_action_pressed("move_northwest"):
-		action = Action.MOVE_NORTHWEST
-	elif event.is_action_pressed("interact"):
+	if event.is_action_pressed("interact"):
 		action = Action.INTERACT
 	elif event.is_action_pressed("perception_mode"):
 		action = Action.USE_PERCEPTION_MODE
 	elif event.is_action_pressed("open_menu"):
 		action = Action.OPEN_MENU
 	elif event.is_action_pressed("pause"):
-		action = Action.PAUSE
+		var tick_rate = GameState.game_time.get("tick_rate", "Full")
+		action = Action.UNPAUSE if tick_rate == "Paused" else Action.PAUSE
+	elif event.is_action_pressed("stance_up"):
+		action = Action.TOGGLE_STANCE_UP
+	elif event.is_action_pressed("stance_down"):
+		action = Action.TOGGLE_STANCE_DOWN
+	elif event.is_action_pressed("bug_report"):
+		action = Action.BUG_REPORT
+	elif event.is_action_pressed("teleport_hub"):
+		if GameState.gauntlet_mode:
+			action = Action.TELEPORT_HUB

-	# Queue the action if valid
 	if action != -1:
 		input_queue.append({
 			"action": action,
-			"timestamp_msec": Time.get_ticks_msec()
+			"timestamp_msec": Time.get_ticks_msec(),
 		})
 		get_viewport().set_input_as_handled()

+
 func flush_queue() -> Array[Dictionary]:
 	var queue = input_queue.duplicate()
 	input_queue.clear()
 	return queue
+
+
+## Reset facing state to default (North). Use in tests per D-030 testability.
+func reset_facing_state() -> void:
+	facing_angle = -PI / 2.0
+	facing_octant = "North"
+	_last_sent_octant = "North"
+
+
+# D-054: Compute facing angle from mouse position relative to player screen position.
+# Uses viewport canvas transform to convert world coords to screen coords.
+# Intentional coupling: reads GameState.player_position directly — InputMapper is an
+# autoload that runs before game loop rendering, so position is always current-tick.
+func _update_facing_from_mouse() -> void:
+	var vp := get_viewport()
+	if vp == null:
+		return
+	var canvas_xf := vp.get_canvas_transform()
+	var player_world_px := GameState.player_position * Constants.TILE_SIZE
+	var player_screen := canvas_xf * player_world_px
+	var mouse_screen := vp.get_mouse_position()
+	var delta := mouse_screen - player_screen
+	# Only update if mouse is meaningfully distant from player (avoid jitter at center)
+	if delta.length_squared() > 4.0:
+		facing_angle = delta.angle()
+		facing_octant = _angle_to_octant(facing_angle)
+
+
+# D-054: Transform raw WASD input (screen-space) to world direction relative to mouse facing.
+# W (+Y up in input, mapped to forward), S (backward), A (strafe left), D (strafe right).
+# Raw input: W=(-Y), S=(+Y), A=(-X), D=(+X) in screen coords.
+# Forward = facing_angle direction. Output: nearest octant direction vector.
+func _wasd_to_world_dir(raw_dir: Vector2i) -> Vector2i:
+	# Build a continuous direction vector relative to facing.
+	# raw_dir.y: -1 = W (forward), +1 = S (backward)
+	# raw_dir.x: -1 = A (strafe left), +1 = D (strafe right)
+	var forward := Vector2(cos(facing_angle), sin(facing_angle))
+	var right := Vector2(-forward.y, forward.x)  # 90° clockwise
+
+	# Combine: forward/back from W/S, strafe from A/D
+	var world_float := forward * float(-raw_dir.y) + right * float(raw_dir.x)
+
+	# Snap to nearest octant direction
+	return _snap_to_octant_dir(world_float)
+
+
+# Snap a floating-point direction vector to the nearest of 8 cardinal/diagonal directions.
+static func _snap_to_octant_dir(dir: Vector2) -> Vector2i:
+	if dir.length_squared() < 0.001:
+		return Vector2i.ZERO
+	var angle := dir.angle()
+	# Quantize to nearest 45° (PI/4)
+	var octant := roundi(angle / (PI / 4.0))
+	match octant:
+		0: return Vector2i(1, 0)        # East
+		1: return Vector2i(1, 1)        # Southeast
+		2, -6: return Vector2i(0, 1)    # South
+		3, -5: return Vector2i(-1, 1)   # Southwest
+		4, -4: return Vector2i(-1, 0)   # West
+		-3, 5: return Vector2i(-1, -1)  # Northwest
+		-2: return Vector2i(0, -1)      # North
+		-1: return Vector2i(1, -1)      # Northeast
+		_: return Vector2i.ZERO
+
+
+# D-054: Convert a facing angle (radians) to the nearest octant name.
+# Godot 2D: 0=East, PI/2=South, -PI/2=North.
+static func _angle_to_octant(angle: float) -> String:
+	var octant := roundi(angle / (PI / 4.0))
+	match octant:
+		0: return "East"
+		1: return "Southeast"
+		2, -6: return "South"
+		3, -5: return "Southwest"
+		4, -4: return "West"
+		-3, 5: return "Northwest"
+		-2: return "North"
+		-1: return "Northeast"
+		_: return "East"
+
+
+# Map a direction vector to the corresponding movement Action.
+# Handles all 8 directions via composite W+D, W+A, etc.
+static func _dir_to_action(dir: Vector2i) -> Action:
+	match dir:
+		Vector2i(0, -1): return Action.MOVE_NORTH
+		Vector2i(1, -1): return Action.MOVE_NORTHEAST
+		Vector2i(1, 0): return Action.MOVE_EAST
+		Vector2i(1, 1): return Action.MOVE_SOUTHEAST
+		Vector2i(0, 1): return Action.MOVE_SOUTH
+		Vector2i(-1, 1): return Action.MOVE_SOUTHWEST
+		Vector2i(-1, 0): return Action.MOVE_WEST
+		Vector2i(-1, -1): return Action.MOVE_NORTHWEST
+		_: return Action.MOVE_NORTH
@@ -4,15 +4,21 @@ extends Node
 enum ConnectionState { DISCONNECTED, CONNECTING, CONNECTED, ERROR }

 var state: ConnectionState = ConnectionState.DISCONNECTED
-var test_mode: bool = true  # Enable test mode for development without Rust server
+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 _last_snapshot: Variant = null  # Most recent decoded snapshot (consumed by poll_snapshot)
-var _outbound_buffer: Array[PackedByteArray] = []  # Encoded inputs awaiting transport
+var _outbound_buffer: Array[Dictionary] = []  # Raw inputs awaiting batch encode + transport

 # Transport layer (non-test mode)
 var _bridge: LocalBridge = null
 var _server: ServerProcess = null
-var server_port: int = 9800
+var server_port: int = 9876  # Default matches server's default bind address
 var server_path: String = ""  # Path to server binary — set before connect_to_sim()

 # Connection retry state — handles server startup delay (Critical fix #1)
@@ -27,7 +33,17 @@ signal snapshot_received(snapshot: Dictionary)

 func _ready() -> void:
 	if test_mode:
-		print("SimBridge: Running in test mode (hardcoded snapshot)")
+		print("SimBridge: Running in test mode (dynamic snapshot)")
+
+# Reset test state — call before tests that use _test_snapshot()
+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"

 # Change connection state and emit signal
 func _set_state(new_state: ConnectionState) -> void:
@@ -50,7 +66,8 @@ func connect_to_sim() -> void:
 	# Spawn server subprocess
 	if not server_path.is_empty():
 		_server = ServerProcess.new()
-		var pid := _server.start(server_path, ["--port", str(server_port)])
+		# 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)])
 		if pid <= 0:
 			push_error("SimBridge: failed to start server")
 			_set_state(ConnectionState.ERROR)
@@ -129,12 +146,19 @@ func _process(delta: float) -> void:
 			while msg.size() > 0:
 				receive_bytes(msg)
 				msg = _bridge.poll_message()
-			# Send: flush outbound buffer through the bridge
+			# Send: batch-encode and flush outbound buffer as one frame (Vec<PlayerInput>).
+			# Inputs are drained before encoding. On encode failure the inputs are
+			# intentionally dropped — re-queuing would retry the same bad data and
+			# the server tick has already advanced, making stale inputs invalid.
 			var outbound := drain_outbound()
-			for payload in outbound:
-				var err := _bridge.send_message(payload)
-				if err != OK:
-					push_error("SimBridge: failed to send message: %s" % error_string(err))
+			if outbound.size() > 0:
+				var encoded := Protocol.encode_player_inputs(outbound)
+				if encoded.size() > 0:
+					var err := _bridge.send_message(encoded)
+					if err != OK:
+						push_error("SimBridge: failed to send message: %s" % error_string(err))
+				else:
+					push_error("SimBridge: failed to batch-encode %d inputs (dropped)" % outbound.size())
 		StreamPeerTCP.STATUS_CONNECTING:
 			pass  # Should not happen in CONNECTED state
 		StreamPeerTCP.STATUS_ERROR:
@@ -154,17 +178,33 @@ func send_input(player_input: Dictionary) -> Error:
 	if state != ConnectionState.CONNECTED:
 		return ERR_CONNECTION_ERROR
 	if test_mode:
+		var action: int = player_input.get("action", -1)
+		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
+			else:
+				_test_input_queue.append(wire_name)
 		return OK
-	var action_name := _action_enum_to_wire(player_input.get("action", -1))
+	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
+		# action_enum_to_wire already emits push_warning for invalid actions
 		return ERR_INVALID_PARAMETER
-	var tick: int = player_input.get("timestamp_msec", 0)
-	var encoded := Protocol.encode_player_input(tick, action_name)
-	if encoded.size() == 0:
-		push_error("SimBridge: failed to encode player input (action=%s)" % action_name)
-		return ERR_CANT_CREATE
-	_outbound_buffer.append(encoded)
+	# 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
+	_outbound_buffer.append(entry)
 	return OK

 # Poll for snapshot from simulation.
@@ -187,24 +227,42 @@ func poll_snapshot() -> Variant:
 	return null

 # Called by transport layer when raw bytes arrive from the server.
-# Latest-wins semantics: newer snapshots replace unconsumed ones. This is correct
-# for real-time rendering (stale frames are worthless). Upgrade to queue if needed.
+# Latest-wins for positional state (stale frames are worthless), but one-shot
+# events (monologue, dialogue) are carried forward from overwritten snapshots
+# so they aren't silently dropped when server ticks faster than client consumes.
 func receive_bytes(bytes: PackedByteArray) -> void:
 	var snapshot = Protocol.decode_snapshot(bytes)
-	if snapshot != null:
-		if _last_snapshot != null:
-			push_warning("SimBridge: overwriting unconsumed snapshot (tick %s replaced by %s)" % [_last_snapshot.tick, snapshot.tick])
-		_last_snapshot = snapshot
+	if snapshot == null:
+		push_warning("SimBridge: decode_snapshot returned null for %d bytes" % bytes.size())
+		return
+	if _last_snapshot != null:
+		# Carry forward one-shot events the client hasn't consumed yet.
+		if snapshot.get("current_monologue") == null and _last_snapshot.get("current_monologue") != null:
+			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
+	_last_snapshot = snapshot

-# Drain the outbound buffer. Returns encoded messages for transport.
-func drain_outbound() -> Array[PackedByteArray]:
-	var messages = _outbound_buffer.duplicate()
+# Drain the outbound buffer. Returns raw input entries for batch encoding.
+func drain_outbound() -> Array[Dictionary]:
+	var inputs = _outbound_buffer.duplicate()
 	_outbound_buffer.clear()
-	return messages
+	return inputs

 # 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:
+static func action_enum_to_wire(action: int) -> String:
 	match action:
 		InputMapper.Action.MOVE_NORTH: return "MoveNorth"
 		InputMapper.Action.MOVE_NORTHEAST: return "MoveNortheast"
@@ -217,27 +275,330 @@ static func _action_enum_to_wire(action: int) -> String:
 		InputMapper.Action.INTERACT: return "Interact"
 		InputMapper.Action.USE_PERCEPTION_MODE: return "UsePerceptionMode"
 		InputMapper.Action.PAUSE: return "Pause"
+		InputMapper.Action.UNPAUSE: return "Unpause"
+		InputMapper.Action.TOGGLE_STANCE_UP: return "ToggleStanceUp"
+		InputMapper.Action.TOGGLE_STANCE_DOWN: return "ToggleStanceDown"
 		InputMapper.Action.OPEN_MENU:
-			# Client-only action, not part of wire protocol
-			push_warning("SimBridge: OPEN_MENU is client-only, not sent to server")
-			return ""
+			return ""  # Client-only action, not part of wire protocol
+		InputMapper.Action.BUG_REPORT:
+			return ""  # Client-only action (#495), not part of wire protocol
+		InputMapper.Action.SET_FACING:
+			return "SetFacing"  # D-054: facing octant update (no movement)
+		InputMapper.Action.TELEPORT_HUB:
+			return "TeleportToHub"  # #501: Gauntlet dev teleport (not production fast-travel)
 		_:
 			push_warning("SimBridge: unknown action enum %s" % action)
 			return ""

-# Hardcoded test snapshot matching Protocol format (deterministic per D-010 principle 4).
-# Uses the same {tick, entities} schema as Protocol.decode_snapshot() returns.
+# 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,
+		})
+
+	# #535: Mock overheard NPC-NPC conversation (D-078)
+	# Two NPCs (Mira and Soren) trade lines every 5 ticks starting at tick 3.
+	# Conversation ends after 6 exchanges (~30 ticks).
+	var conv_events: Array = []
+	var conv_ended: Array = []
+	var conv_start := 3
+	var conv_lines := [
+		{"speaker": "Mira", "target": "Soren", "line": "The cargo manifests don't add up. Three containers unaccounted for."},
+		{"speaker": "Soren", "target": "Mira", "line": "Could be a logging error. Happens every... cycle."},
+		{"speaker": "Mira", "target": "Soren", "line": "Not like this. Someone moved them after... check."},
+		{"speaker": "Soren", "target": "Mira", "line": "You're reading too much into it. The docks are... these days."},
+		{"speaker": "Mira", "target": "Soren", "line": "Then explain the weight discrepancy. Two hundred kilos... just gone."},
+		{"speaker": "Soren", "target": "Mira", "line": "Fine. I'll pull the bay... tonight. But keep this between us."},
+	]
+	var conv_tick_interval := 5
+	var conv_total_ticks := conv_lines.size() * conv_tick_interval
+	if _test_tick >= conv_start and _test_tick < conv_start + conv_total_ticks:
+		var conv_index := (_test_tick - conv_start) / conv_tick_interval
+		var within_tick := (_test_tick - conv_start) % conv_tick_interval
+		if within_tick == 0 and conv_index < conv_lines.size():
+			var cl: Dictionary = conv_lines[conv_index]
+			conv_events.append({
+				"speaker_id": 10,
+				"target_id": 11,
+				"speaker_name": cl.speaker,
+				"target_name": cl.target,
+				"occluded_line": cl.line,
+			})
+	elif _test_tick == conv_start + conv_total_ticks:
+		conv_ended.append({"speaker_id": 10, "target_id": 11})
+
 	return {
 		"tick": _test_tick,
-		"entities": [
-			{
-				"entity_id": 1,
-				"x": 10.0,
-				"y": 10.0,
-				"z": 0,
-				"kind": { "variant": "Npc", "data": null },
-			},
-		],
+		"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,
+		"conversation_events": conv_events,
+		"conversation_ended": conv_ended,
 	}
+
+# 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"
@@ -0,0 +1,92 @@
+extends Node
+
+# UIStrings — loads UI display text from data/ui-strings.yaml.
+# Access: UIStrings.get_text("hud.mode_label") -> "Mode"
+# Falls back to the key itself if not found, with a push_warning.
+
+const STRINGS_PATH: String = "res://data/ui-strings.yaml"
+
+var _strings: Dictionary = {}
+var _loaded: bool = false
+
+func _ready() -> void:
+	_load_strings()
+
+func _load_strings() -> void:
+	if not FileAccess.file_exists(STRINGS_PATH):
+		push_warning("UIStrings: file not found: %s" % STRINGS_PATH)
+		return
+	var file := FileAccess.open(STRINGS_PATH, FileAccess.READ)
+	if file == null:
+		push_warning("UIStrings: failed to open: %s" % STRINGS_PATH)
+		return
+	var text := file.get_as_text()
+	file.close()
+	_strings = _parse_yaml(text)
+	_loaded = true
+	print("UIStrings: loaded %d strings from %s" % [_strings.size(), STRINGS_PATH])
+
+## Get a UI string by dotted key. Returns the key itself if not found.
+func get_text(key: String) -> String:
+	if _strings.has(key):
+		return _strings[key]
+	push_warning("UIStrings: missing key '%s'" % key)
+	return key
+
+## Check if a key exists.
+func has_key(key: String) -> bool:
+	return _strings.has(key)
+
+## Get all keys.
+func get_all_keys() -> PackedStringArray:
+	return PackedStringArray(_strings.keys())
+
+## Reload from disk (useful for hot-reload during development).
+func reload() -> void:
+	_strings.clear()
+	_loaded = false
+	_load_strings()
+
+## Parse YAML with arbitrary nesting depth.
+## Returns flat Dictionary with dotted keys: { "section.sub.key": "value" }.
+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
--- a/Show More
+++ b/Show More
				`@@ -0,0 +1 @@`
				`<svg xmlns="http://www.w3.org/2000/svg" width="128" height="128"><rect width="128" height="128" fill="#1a1a2e"/></svg>`