Bump to 0.9.1 and record the toolchain update

Update project features and CI installs/templates to Godot 4.7.2, remove the
old version matrix, and cache the Godot binary and export templates with Gitea
Actions cache. Update release/docs/version references accordingly. Project
import and headless tests pass locally under 4.7.2.

.gitea/workflows/build.yml

@@ -7,6 +7,10 @@ on:
   pull_request:
   workflow_dispatch:
 
+env:
+  GODOT_VERSION: "4.7.2"
+  GODOT_BIN: /usr/local/bin/godot
+
 jobs:
   checks:
     name: Import + headless tests
@@ -17,12 +21,23 @@ jobs:
     steps:
       - uses: actions/checkout@v4
 
-      - name: Install Godot 4.3
+      - name: Restore Godot binary cache
+        uses: actions/cache@v4
+        with:
+          path: /usr/local/bin/godot
+          key: godot-${{ runner.os }}-${{ env.GODOT_VERSION }}-v1
+
+      - name: Install Godot 4.7.2
         run: |
+          if [ -x /usr/local/bin/godot ]; then
+            godot --version
+            exit 0
+          fi
           curl -sL -o /tmp/godot.zip \
-            https://github.com/godotengine/godot/releases/download/4.3-stable/Godot_v4.3-stable_linux.x86_64.zip
+            https://github.com/godotengine/godot/releases/download/4.7.2-stable/Godot_v4.7.2-stable_linux.x86_64.zip
           unzip -qo /tmp/godot.zip -d /tmp/godot-bin
-          sudo install /tmp/godot-bin/Godot_v4.3-stable_linux.x86_64 /usr/local/bin/godot
+          sudo install /tmp/godot-bin/Godot_v4.7.2-stable_linux.x86_64 /usr/local/bin/godot
+          godot --version
 
       - name: Import project (build class cache)
         run: godot --headless --import
@@ -56,18 +71,38 @@ jobs:
     steps:
       - uses: actions/checkout@v4
 
-      - name: Install Godot 4.3 and export templates
+      - name: Restore Godot binary cache
+        uses: actions/cache@v4
+        with:
+          path: /usr/local/bin/godot
+          key: godot-${{ runner.os }}-${{ env.GODOT_VERSION }}-v1
+
+      - name: Restore export templates cache
+        uses: actions/cache@v4
+        with:
+          path: ~/.local/share/godot/export_templates/4.7.2.stable
+          key: godot-templates-${{ runner.os }}-${{ env.GODOT_VERSION }}-v1
+
+      - name: Install Godot 4.7.2 and export templates
         run: |
-          curl -sL -o /tmp/godot.zip \
-            https://github.com/godotengine/godot/releases/download/4.3-stable/Godot_v4.3-stable_linux.x86_64.zip
-          unzip -qo /tmp/godot.zip -d /tmp/godot-bin
-          sudo install /tmp/godot-bin/Godot_v4.3-stable_linux.x86_64 /usr/local/bin/godot
+          if [ ! -x /usr/local/bin/godot ]; then
+            curl -sL -o /tmp/godot.zip \
+              https://github.com/godotengine/godot/releases/download/4.7.2-stable/Godot_v4.7.2-stable_linux.x86_64.zip
+            unzip -qo /tmp/godot.zip -d /tmp/godot-bin
+            sudo install /tmp/godot-bin/Godot_v4.7.2-stable_linux.x86_64 /usr/local/bin/godot
+          fi
+          godot --version
+          if [ -f "$HOME/.local/share/godot/export_templates/4.7.2.stable/linux_release.x86_64" ]; then
+            ls "$HOME/.local/share/godot/export_templates/4.7.2.stable" | head -5
+            exit 0
+          fi
           curl -sL -o /tmp/templates.tpz \
-            https://github.com/godotengine/godot/releases/download/4.3-stable/Godot_v4.3-stable_export_templates.tpz
-          mkdir -p ~/.local/share/godot/export_templates/4.3.stable
-          cd /tmp && rm -rf tpl && mkdir tpl && unzip -qo templates.tpz -d tpl
-          cp tpl/templates/* "$HOME/.local/share/godot/export_templates/4.3.stable/" 2>/dev/null || true
-          ls "$HOME/.local/share/godot/export_templates/4.3.stable" | head -5
+            https://github.com/godotengine/godot/releases/download/4.7.2-stable/Godot_v4.7.2-stable_export_templates.tpz
+          rm -rf /tmp/tpl && mkdir -p /tmp/tpl
+          unzip -qo /tmp/templates.tpz -d /tmp/tpl
+          mkdir -p "$HOME/.local/share/godot/export_templates/4.7.2.stable"
+          cp /tmp/tpl/templates/* "$HOME/.local/share/godot/export_templates/4.7.2.stable/"
+          ls "$HOME/.local/share/godot/export_templates/4.7.2.stable" | head -5
 
       - name: Import project
         run: godot --headless --import
@@ -114,7 +149,7 @@ jobs:
         if: startsWith(github.ref, 'refs/tags/')
         env:
           # An explicit repo secret wins. Without one, publish_release.sh reuses
-          # the local git extraheader that actions/checkout configures for the job
+          # the local git extraheader that actions/checkout configures on the job
           # (the runner's own credentials), so tag builds still publish.
           GITEA_TOKEN: ${{ secrets.GITEA_TOKEN }}
           VERSION: ${{ github.ref_name }}

.gitignore

@@ -66,10 +66,10 @@ assets/models/blender/**/*.png
 assets/models/blender_src/*.blend1
 # Editable Blender sources are developer-only; keep the .gdignore marker tracked.
 assets/models/blender_src/*.blend
-# Realism pass (tools/scene_concepts.py): the candidate pool and per-run captures
-# stay local; the validated picks are tracked under game_ready/v2/picks/ (ADR-0014),
-# and each run commits its report.{json,md} + sheet.jpg. Concept references are
-# committed in docs/screens/concepts/.
+# Realism pass (tools/scene_concepts.py): candidate pools, per-run captures and
+# generated reports stay local; validated picks are tracked under
+# game_ready/v2/picks/ (ADR-0014). Concept references are committed in
+# docs/screens/concepts/, but generated QA lives outside the repository.
 assets/textures/ai/game_ready/v2/*
 !assets/textures/ai/game_ready/v2/picks/
-docs/screens/realism/**/*.png
+docs/screens/realism/

AGENTS.md

@@ -14,6 +14,14 @@ The project should be developed in small, reviewable steps. Agents must keep pla
 - `MEMORY.md` — Persistent session memory for important decisions, discoveries, unresolved questions, constraints, and useful implementation context.
 - `README.md` — Root-level documentation for the project. It should explain what the game is, how to work on it, how to run it, and where to find project information.
 - `AGENTS.md` — This collaboration and agent workflow guide.
+- `CHANGELOG.md` — The version history of user-facing changes. Keep an entry for each patch, minor, and major version.
+- `docs/development-status.md` — The implemented-features list and what is not yet implemented. Update it whenever a feature lands, is renamed, or is removed.
+- `docs/architecture.md` — The arc42-style architecture documentation (goals, constraints, building blocks, runtime views, decisions, risks).
+- `docs/gameplay.md` — Gameplay systems, venues, and the escalation model.
+- `docs/asset-tooling.md` — Asset pipelines, model tools, and screenshot gates.
+- `docs/getting-started.md` — Setup, run/test commands, and the controls table.
+- `docs/smoke-checklist.md` — The manual smoke-test checklist.
+- `docs/adr/` — Architecture Decision Records.
 
 ## Required Workflow
 
@@ -36,7 +44,13 @@ Do not assume that a task is unimplemented without checking the code and documen
 All planned implementation work must be represented in `TODO.md`.
 
 - Use headings to group related work into sections.
-- Use checkbox items for each concrete task.
+- Use level-2 headings (`##`) for milestones or stable themes. A milestone should state its goal
+  and an explicit exit criterion; a theme groups small related work that does not need a
+  milestone.
+- Use level-3 headings (`###`) for workstreams inside a milestone (for example, `0.8.1
+  First-shift tutorial`). Keep the hierarchy to three levels: milestone → workstream → checkbox.
+- Use checkbox items for each concrete task, normally under a level-3 workstream. Direct
+  checkboxes under a level-2 section are acceptable for small, single-workstream sections.
 - Keep tasks small enough to complete and review independently.
 - Add new tasks when discoveries expand the scope.
 - When starting a task, claim it for the agent workflow by changing `[ ]` to `[-]`. Keep it `[-]`
@@ -53,11 +67,20 @@ Recommended format:
 ```md
 # TODO
 
-## Core Gameplay
+## Milestone 0.8.0 — First hour and content depth
 
-- [ ] Add player movement controls.
-- [-] Implement NPC approach behavior. (claimed; implementation/verification in progress)
-- [x] Define escalation levels.
+### 0.8.1 First-shift tutorial
+
+- [x] Write the tutorial beat sheet.
+- [-] Implement the tutorial state machine. (claimed; implementation/verification in progress)
+- [ ] Add the tutorial smoke test.
+
+### 0.8.2 Campaign shell
+
+- [ ] Define campaign data.
+- [ ] Persist campaign progress.
+
+**Exit:** a first-time player completes a shift without external documentation.
 
 ## Documentation
 
@@ -66,14 +89,26 @@ Recommended format:
 
 ### 3. Move Completed Sections to `DONE.md`
 
-When every task in a `TODO.md` section is complete:
+`TODO.md` uses nested sections. Apply these completion rules:
 
-1. Verify the work and update the checkbox items to `[x]`.
-2. Move the entire completed section, including its heading and checklist, to `DONE.md`.
-3. Remove that section from `TODO.md`.
-4. Add a short completion note or date when useful.
+1. **Level-3 workstream:** verify the work, mark every checkbox `[x]`, and add a short completion
+   note. Leave the completed workstream under its parent milestone; do not move an isolated
+   level-3 section to `DONE.md`.
+2. **Level-2 milestone/theme:** it is complete only when its direct checkboxes and **all** of its
+   level-3 workstreams are complete. Verify the whole milestone, record its capabilities in
+   `docs/development-status.md` when it represents shipped functionality, and write the matching
+   `CHANGELOG.md` entry.
+3. Move the **entire level-2 section**, including all level-3 headings and checklists, to
+   `DONE.md`. Remove it from `TODO.md` and add a completion date/note.
+4. **Planning/overview sections** such as a gap analysis, roadmap overview, dependencies or
+   deferred ideas are not completion milestones. Do not move them merely because their checkboxes
+   are empty or complete; update or supersede them as the roadmap changes.
+5. Do not move partially completed milestones. Leave them in `TODO.md` until every nested task is
+   complete, or split the unfinished work into a new smaller level-2 milestone first.
 
-Do not move partially completed sections. Leave them in `TODO.md` until all of their tasks are complete, or split the section into smaller sections first.
+When a completed milestone represents shipped functionality, also record the new capability in
+`docs/development-status.md` so the implemented-features list stays accurate, and write a matching
+entry in `CHANGELOG.md` (see "Maintain `CHANGELOG.md`" below).
 
 ### 4. Maintain `MEMORY.md`
 
@@ -82,7 +117,7 @@ Use `MEMORY.md` for information that should persist between sessions but does no
 Record items such as:
 
 - Important design and architecture decisions
-- Current implementation state
+- Notable implementation state and gotchas (the canonical implemented-features list lives in `docs/development-status.md`, not here)
 - Known bugs and workarounds
 - Commands needed to run, test, or build the project
 - Decisions that future agents should not revisit unnecessarily
@@ -132,9 +167,27 @@ The root-level `README.md` is the project’s public-facing technical and projec
 - Links to `PLAN.md`, `TODO.md`, `DONE.md`, `MEMORY.md`, and this file where appropriate
 - Known limitations and contribution guidance
 
-Update `README.md` whenever setup instructions, commands, project structure, or user-facing behavior changes.
+Update `README.md` whenever setup instructions, commands, project structure, or user-facing behavior changes. The README is intentionally concise and links to the `docs/` files; keep `docs/development-status.md` (and the other docs it links to) synchronized with the implementation rather than pasting detail back into the README.
 
-### 7. Implement in Small Increments
+### 7. Maintain `CHANGELOG.md`
+
+The root-level `CHANGELOG.md` records the user-facing changes for every release. It exists so players and contributors can see what changed between versions without reading the commit log.
+
+- Add an entry for every patch, minor, and major version change.
+- Follow Semantic Versioning (`major.minor.patch`): bump major for breaking or vision-level changes, minor for new features, and patch for fixes and small polish.
+- Group each entry under `Added`, `Changed`, `Fixed`, and `Removed` headings, and date every entry.
+- Describe changes in user-facing terms, not as raw commit messages.
+- Add the entry when its work ships. If the version number is not yet known, record it under `Unreleased` and move it into a numbered version when the version is tagged.
+
+When a full executable level-2 milestone/theme in `TODO.md` is implemented, completed, and moved to `DONE.md`:
+
+1. Verify the work and mark every checkbox in the section `[x]`.
+2. Use the section heading and its completed items to describe the changes and write a `CHANGELOG.md` entry under the next appropriate version.
+3. Move the section to `DONE.md`.
+
+Do not move a completed section to `DONE.md` without adding its `CHANGELOG.md` entry.
+
+### 8. Implement in Small Increments
 
 For each task:
 
@@ -142,9 +195,13 @@ For each task:
 2. Inspect the relevant files and dependencies.
 3. Make the smallest coherent change that completes the task.
 4. Run the relevant tests, checks, or manual verification.
-5. Update documentation and `MEMORY.md` if the change creates lasting context.
+5. Update documentation if the change creates lasting context: add features to `docs/development-status.md`, adjust the README links or other `docs/` files as needed, and record decisions/gotchas in `MEMORY.md`.
 6. Mark the task complete.
-7. Move its section to `DONE.md` when the entire section is complete.
+7. Keep completed level-3 workstreams in place until the parent milestone is complete; then move the entire level-2 milestone to `DONE.md` after recording its `CHANGELOG.md` entry.
+8. Commit the changes to the version control system with a descriptive message.
+9. If a level-2 milestone from `TODO.md` has been fully completed, ensure its `CHANGELOG.md` entry is in place, then create a new version or tag in the version control system to mark the milestone.
+10. Push the committed changes to the shared repository if applicable.
+11. Note the new version or tag created in the version control system in any relevant documentation or handoff summary.
 
 Avoid unrelated refactors unless they are required for the task or explicitly approved.
 

CHANGELOG.md

@@ -0,0 +1,403 @@
+# Changelog
+
+All notable user-facing changes to Gig Line. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and versions use
+Semantic Versioning.
+
+## [0.9.1] — 2026-11-02
+
+### Changed
+
+- Unified the project, local tooling and CI/release environment on Godot 4.7.2,
+  including matching export templates and project feature metadata.
+- Added Gitea Actions cache for the Godot binary and export templates to reduce
+  repeated download time.
+- Updated release and setup documentation for the 4.7.2 baseline.
+
+## [0.9.0] — 2026-11-01
+
+### Added
+
+- Master/SFX/ambience volume controls, a captions toggle and a Reduce motion
+  option in Settings.
+- A 24-NPC performance budget smoke and expanded audio/accessibility coverage.
+- Explicit production-quality scope for animation, audio, localization and the
+  Godot 4.3-CI/4.7-local support matrix.
+
+### Changed
+
+- Coat and dress strides are shortened to reduce hem/leg clipping.
+- Help and the shift-review surface expose the current policy and accessibility
+  settings.
+
+### Fixed
+
+- Audio cue volumes now respect the player's mixer settings while remaining
+  headless-safe.
+
+## [0.8.1] — 2026-11-01
+
+### Fixed
+
+- Normal radio reports now send on click. The button was wired only to the
+  emergency hold-to-confirm handlers, so a non-emergency press did nothing.
+
+## [0.8.0] — 2026-11-01
+
+### Added
+
+- A first-shift tutorial with contextual prompts, a safe visitor and replay/skip.
+- A three-venue campaign shell with shift progression and a Continue action.
+- Resume-from-checkpoint for paused shifts, including NPC, incident and system state.
+- Easy/normal/hard difficulty presets for spawn pacing, compliance tolerance and
+  report strictness.
+- A searchable in-game Help overlay with controls and the current venue policy.
+- Recovery events, contextual NPC dialogue and an eligible-event debug preview.
+
+### Changed
+
+- The shift review now includes venue policy, campaign next steps and continued
+  review controls.
+- Event scheduling suppresses recently played scripted events and respects the
+  difficulty spawn multiplier.
+- Save data is written atomically and split into settings, campaign, shift
+  history and versioned checkpoint files.
+
+### Fixed
+
+- Missing/older settings migrate through defaults; a partial write cannot
+  replace a valid save.
+- The HUD debug overlay now refreshes and shows the next eligible events.
+
+## [0.7.3] — 2026-11-01
+
+### Fixed
+
+- Mouse look now reads relative motion at the `_input` stage, so a full-screen
+  HUD or focused control cannot swallow it while the cursor is captured.
+- Mouse capture is restored after window/compositor focus returns, and clicking
+  back into a gameplay window recaptures it instead of opening the radial menu.
+- The HUD is mouse-transparent; its presentation controls no longer block
+  gameplay mouse input.
+
+## [0.7.2] — 2026-11-01
+
+### Added
+
+- Automatic OpenRouter model selection for the screenshot judges: the cheapest
+  currently available image+JSON-capable model is used, with ordered fallbacks
+  and a pinned `GIG_LINE_JUDGE_MODEL`/`--model` override.
+
+### Changed
+
+- The judge reports the model that produced each verdict and fails clearly on an
+  invalid API key instead of retrying other models.
+- The screen-design and realism reports now include the fresh judge results.
+
+### Fixed
+
+- The blocked screenshot judge now runs with the valid `OPENROUTER_API_KEY`
+  (`13/13` screen designs match, `0` diff).
+
+## [0.7.1] — 2026-11-01
+
+### Added
+
+- An optional Desktop HQ build for Windows and Linux that uses Forward+,
+  volumetric fog and SDFGI, packaged with an `override.cfg` beside the
+  executable.
+- Volumetric flashlight haze in the Desktop HQ build, with a LATE-phase preset
+  tuned so the entrance facade stays readable.
+
+### Changed
+
+- The normal Compatibility build remains the default; the preset only affects
+  the extracted Desktop HQ copy.
+- Night-time light falloff adapts to Godot 4.7 while keeping the 4.3 baseline
+  unchanged.
+
+### Fixed
+
+- The flashlight no longer disappears at night on Godot 4.7 under the old
+  attenuation curve.
+- Headless and Web builds stay non-volumetric and boot normally when Forward+
+  is unavailable.
+
+## [0.7.0] — 2026-11-01
+
+### Changed
+
+- Agent workflow now requires maintaining this changelog for every patch, minor, and major version.
+
+## [Unreleased]
+
+### Added
+
+- Distinct venue geometry: the Joke Shop is now a narrow brick alley with a
+  shuttered facade, warm wall lantern, dumpster and AC clutter; the TV Studio
+  has a stone facade, bulb-lit canopy, glossy black car and a stanchion/barrier
+  line at the door.
+- The README gallery includes captured Joke Shop and TV Studio views.
+
+### Changed
+
+- Venue geometry is data-driven through `WorldBuilder.VENUE_SPECS`; switching
+  venues rebuilds the world while keeping the guard and UI intact.
+- Each venue has its own navigation bounds and concept-gallery mapping.
+
+### Fixed
+
+- The Joke Shop no longer renders the Hollywood skyline or marquee.
+- The TV Studio no longer uses the boulevard marquee or palm-lined layout.
+
+## [0.6.1] — 2026-11-01
+
+### Added
+
+- Per-phase AI skyline panoramas (day, dusk, night) replacing the flat box skyline.
+- Higher-detail surface textures with normal maps (brick, concrete, asphalt, awning, and more).
+- A runtime image root (`assets/images/`) with a UI and scene art loader; the start menu,
+  pause, settings, shift review, radio, wand, inspection, and radial menu are styled against
+  their mockups.
+- NPC face and hand detail: eyes, nose, lips, ears, fingered hands, and cuffed sleeves.
+- A staged NPC portrait capture for judging avatar quality up close.
+- Gear-fit checks (`tools/blender_assets.py fit`) and regression tests for head and back gear.
+
+### Changed
+
+- Scene lighting, fog, sun angle, and night glow retuned to match the AI concept frames;
+  the Late phase uses wet asphalt.
+- The flashlight is a tighter forward spot that reads in the dark.
+- Sunglasses narrowed to sit inside the face silhouette; shoulder bag moved clear of the
+  coat and dress skirts; firefighter helmet lifted off the brow.
+- The README now links to focused docs pages for gameplay, architecture, setup, asset
+  tooling, development status, and the manual smoke checklist; `PLAN.md` was compacted
+  into a design plan.
+
+### Fixed
+
+- Sidewalk overexposure at the entrance reduced to match the concept target.
+- The body-camera overlay no longer overlaps the shift/reputation/crowd status.
+- Selecting a venue releases the menu input lock and recaptures the mouse.
+- The shoulder bag no longer clips through the coat's skirt; the firefighter helmet no
+  longer cuts into the brow ridge; the portrait subject now faces the camera.
+- `--portrait-type` is now parsed and applied instead of being ignored.
+
+## [0.6.0] — 2026-11-01
+
+### Added
+
+- Blender-authored character, gear and prop library with baked ambient occlusion.
+- Higher-resolution environment textures with tangent normal maps.
+- Phase-driven emissive details on library props, characters and street dressing.
+
+### Changed
+
+- The game was renamed from "Step Line" to "Gig Line".
+
+### Fixed
+
+- NPCs now face their movement direction instead of walking backwards.
+
+## [0.5.0] — 2026-11-01
+
+### Added
+
+- Articulated NPC characters with layered outfits, hand items, face/hair variety,
+  idle behaviour, reaction symbols, queue offsets and three LOD tiers.
+- Player acceleration/braking, step-up assist, head bob, landing dip,
+  precision-walk feedback and surface-aware footsteps.
+- Remappable keyboard and gamepad controls.
+
+### Changed
+
+- Crowd roles now select deterministic character variants and props.
+
+## [0.4.0] — 2026-11-01
+
+### Added
+
+- Collision and navigation footprints for every street prop.
+- Zoned prop placements with deterministic variants and small clutter.
+
+## [0.3.3] — 2026-11-01
+
+### Added
+
+- Staged in-game captures for the wand screening, escalation HUD, and body-camera timeline screens.
+
+## [0.3.2] — 2026-11-01
+
+### Added
+
+- AI reference mockups for the seven remaining catalogue screens.
+
+## [0.3.1] — 2026-10-31
+
+### Added
+
+- Prop models drawn with a single texture atlas (one material per prop).
+
+### Changed
+
+- The Web build is listed in the README downloads table.
+
+## [0.3.0] — 2026-10-31
+
+### Added
+
+- Surface-material profiles, ACES tonemapping, glow, aerial fog and phase-based
+  colour grading.
+- Framed facade windows, door trim, curb and lane markings.
+- Generated street-furniture models and the Web export.
+- Aim-free targeting, a focus cone and precision walk.
+
+## [0.2.16] — 2026-10-31
+
+### Added
+
+- Venues authorable as editor `.tres` resources.
+
+## [0.2.15] — 2026-10-31
+
+### Added
+
+- A vision-model judge for comparing screenshots against reference designs.
+
+## [0.2.14] — 2026-10-31
+
+### Added
+
+- Anonymous release downloads enabled on the host.
+
+### Fixed
+
+- `Strings.fmt` keeps positional placeholders stable when new keys are added.
+
+## [0.2.13] — 2026-10-31
+
+### Added
+
+- Missing scenario content: Joke Shop reservation/ID cases, wand refusal and late
+  arrival events, the studio filming-boundary repeat, and a celebrity-arrival crowd spike.
+
+## [0.2.12] — 2026-10-31
+
+### Fixed
+
+- Release uploads fail loudly instead of leaving an empty release with a green job.
+- Pruned releases restored and CI publishing verified end to end.
+
+## [0.2.11] — 2026-10-31
+
+### Fixed
+
+- Releases publish using the runner's checkout credentials when no token or git
+  credentials exist.
+
+## [0.2.10] — 2026-10-31
+
+### Fixed
+
+- Release publishing fixed with a CI token fallback.
+
+## [0.2.9] — 2026-10-31
+
+### Added
+
+- Accessibility pass: escalation feedback that reads in grayscale and a working HUD font scale.
+
+## [0.2.8] — 2026-10-31
+
+### Added
+
+- Procedural crowd ambience that rises with crowd mood, and a radio crackle.
+
+## [0.2.7] — 2026-10-31
+
+### Added
+
+- NPC theater poses: sitting, taking photos, filming, and performing.
+
+## [0.2.6] — 2026-10-31
+
+### Added
+
+- A body-camera timeline on the shift review for stepping through recorded events.
+
+## [0.2.5] — 2026-10-31
+
+### Added
+
+- Emergency aftermath: evacuation clears the entrance, and unjustified calls write
+  an investigation note with a false-report reputation hit.
+
+## [0.2.4] — 2026-10-31
+
+### Added
+
+- Crowd presentation: onlookers rubberneck at incidents and clear out during panic.
+
+### Fixed
+
+- NPC navigation issues resolved.
+
+## [0.2.3] — 2026-10-31
+
+### Added
+
+- Remaining PLAN actions: eye contact, "I recognize this person", a formal-warning
+  body-camera flag, blocking that stations the guard in front of the door, and
+  requesting a reason for entry.
+
+### Fixed
+
+- A dead incident-recording path.
+
+## [0.2.2] — 2026-10-31
+
+### Added
+
+- Session shell: startup menu with venue selection, pause overlay, settings
+  persistence, and a "run another shift" flow back to the menu.
+- Control pass: focus cone, head ring, radial action menu, and named input actions.
+
+### Fixed
+
+- Release publishing now uploads the installer and AppImage.
+
+## [0.2.1] — 2026-10-31
+
+### Added
+
+- Windows NSIS installer and Linux AppImage packaging; all exports embed the PCK.
+- An AI texture generation mode in the asset pipeline.
+
+### Fixed
+
+- NSIS build fixed for Linux (absolute defines, space-free installed exe, BMP icon).
+- Runtime hygiene: RefCounted cycle cleanup, full-length shifts, and a wand cooldown.
+
+## [0.2.0] — 2026-10-31
+
+### Added
+
+- First playable build of the security-guard simulation at the Hollywood Boulevard entrance.
+- Core simulation: shift coordination, venue scenarios, event scheduling, NPC movement
+  and states, and escalation from observation through deterrence, warnings, and blocking.
+- Access verification for wristbands, IDs, tickets, credentials, and guest lists, with
+  admit/redirect/hold/refuse decisions and feedback scoring.
+- Escalation levels 0–5 with radio assistance and a hold-to-confirm emergency call.
+- Incident recording, body-camera evidence, reputation scoring, crowd reactions, and
+  an end-of-shift review.
+- Scenario content for Hollywood Boulevard, The Joke Shop, and the TV Studio, including
+  a mental-health crisis event.
+- A protester NPC, the "call someone else" reaction, a lockable door, and a flashlight.
+- Save/persistence, navmesh pathfinding, and JSON localization.
+- Visual polish: phase lighting, street lamps, marquee, street dressing, and NPC variety.
+- Detailed graphics: authored textures, a humanoid NPC rig, and HUD/inspection feedback.
+- Downloadable Linux, Windows, and macOS builds published by CI.
+
+### Removed
+
+- The dialogue tone-of-voice picker (reactions now depend on escalation level and NPC profile).

DONE.md

@@ -1049,6 +1049,62 @@ reports to `docs/screens/realism/<run>/`.
       texture 0.8→1.0, backdrop 0.6→1.6, and the Pillow metric gap 0.444→0.348.
 - [x] Update `README.md` (tool usage + gallery), `MEMORY.md` and `docs/architecture.md`.
 
+## Realism Follow-ups — Lighting, Flashlight, NPC Detail
+
+Completed 2026-11-01. The follow-ups left over after the texture/skyline adoption, split off from
+`TODO.md` when each one was finished. Evidence: `docs/screens/realism/2026-11-01-npc/`
+(`report.md`, `sheet.jpg`), the portrait capture, and the refreshed `docs/screenshots/` gallery
+(`screen_designs.py compare` **11 good / 0 bad**). Headless **228/228**, Python **86/86**.
+
+### Ground exposure at the entrance
+
+- [x] Fixed the over-bright entrance ground: the morning sun now sits at 34° elevation (was 50°)
+      with a phase `sun_yaw`, so the facade shades the near sidewalk and the props cast long
+      shadows. Ground luminance went 95 → **83** against the concept's 78 (it was 173 before the
+      realism pass), with the boulevard at 82 and the street at 81. Day haze warmed and
+      thickened (`fog_color` 0.87/0.83/0.76, density 0.0034, energy 0.5) and the night glow went
+      to 1.15.
+
+### Flashlight readability
+
+- [x] Made the flashlight read in the dark: the cone went 30° → **14°** with a 20 m range,
+      forward aim, `light_energy` 4.2 and `spot_attenuation`/`spot_angle_attenuation` 0.9, so it
+      lights the door instead of washing the facade.
+- [x] Staged the two night captures in LATE (`elapsed_s` 760) instead of dusk in
+      `capture_screenshots.gd`; the judge moved `06-night-flashlight` from **diff (1.00) to
+      review (0.10)**.
+- [x] Rejected a fake additive beam twice (cylinder + UV ramp, then a vertical-fade
+      `ShaderMaterial`): on GL Compatibility a first-person camera inside the cone renders it as
+      a filled disc with a bright far ring. `Materials.light_beam()` and the mesh were removed;
+      the visible *shaft* is parked behind the Forward+ preset in `TODO.md`.
+- [x] Guarded the aim with `test_flashlight_aims_a_tight_forward_spot` (lamp on the head, straight
+      ahead, cone ≤ 20°, starts off).
+
+### NPC faces, hands and sleeves
+
+- [x] Rebuilt the avatar detail so skin and clothing stop reading as low-poly at conversation
+      distance: each eye has a sclera, iris and upper lid; added a brow ridge, cheekbones, a nose
+      bridge and tip, ears with lobes, and split upper/lower lips. Hands have four fingers plus a
+      thumb, and every sleeve ends in a cuff ring.
+- [x] Raised `CHAR_MAX_VERTS` 4000 → **5000** (documented in the code and
+      `docs/blender-assets.md`) after measuring 16 avatars at ~6.9 ms of a 50 ms frame on a single
+      skinned mesh, so `npc_coat` fits at 4807 vertices; the character range is now 3,974–5,026
+      triangles and 3,744–4,807 vertices. Body decimation 0.36 → 0.26.
+- [x] Rebuilt all 8 variants and re-baked their AO maps (`assets/models/blender/npc/*_ao.png`),
+      re-imported, and kept `blender_assets.py audit` at exit 0.
+- [x] Added a staged portrait capture: `capture_realism.gd` gained a `portrait` stage that
+      freezes one NPC, parks the crowd out of frame, stands the subject on open sidewalk, turns
+      it into the camera and puts the guard on the sunlit side; `--portrait-type=N` picks a role.
+      It is the only capture where a face fills the frame, and it feeds the new
+      `npc_portrait_day` concept (`tools/scene_concepts.py` `SHOTS`).
+- [x] Regenerated the gallery shots and re-ran the judge: like-for-like overall 2.33 → 2.44,
+      lighting 3.0 → 3.22, materials 2.22 → 2.44. The `characters` sub-score stayed flat
+      (~2.2–2.3) because the target is a photoreal face, so avatar quality is judged from the
+      portrait rather than the aggregate.
+- [x] Re-checked the `screen_designs.py judge` default model (`google/gemini-2.5-flash-lite`):
+      it works but intermittently answers HTTP 400 "API key not valid" (one shot in ten on
+      2026-11-01); `--model google/gemini-2.5-flash` remains the fallback.
+
 ## Visual Alignment — UI Paths and Art Loader
 
 Completed 2026-11-01.
@@ -1127,3 +1183,401 @@ marquee text, hand-authored tree shapes) are content, not grading.
 - [x] Align the body-camera timeline to its mockup.
 - [x] Align scene lighting, fog, and post-processing for `venue_overview` and `late_night_avenue`: lowered the morning sun to 34° (`sun_yaw` is now a phase value), warmed and thickened the day haze, raised the night glow, and brightened the street albedo. `judge` moved `01-venue-overview` to **match** (0.90) and `05-late-night-avenue` from diff to **review** (0.10); `compare` stays 11 good / 0 bad.
 - [x] Fix the body-camera REC/clock overlay overlapping the shift/rep/crowd status in the top-right HUD.
+
+## Documentation Consistency
+
+Completed 2026-11-01. `PLAN.md` was compacted from the historical implementation log into a
+product/design plan (674 → 187 lines): escalation, NPC/venue content and design constraints stay,
+while the completed control/rendering pass specs were folded into a short Presentation and
+Controls section. `README.md` now reflects the implemented venues, Blender/v2 asset pipeline, the
+custom test runner, the Web target, the current release state, and the capture smoke. The
+architecture's version, runtime-art loader, asset/tooling blocks, Gitea CI/build/publish pipeline,
+Web deployment and release artifact list were brought up to date. `MEMORY.md` was cleaned of
+obsolete uncommitted/active-pass claims and now points at the current follow-ups.
+
+- [x] Re-check `PLAN.md`/`MEMORY.md` against the current build, update `README.md` and `docs/architecture.md`, and compact the historical PLAN sections.
+
+## NPC gear fit (v0.6.1)
+
+Completed 2026-11-01. Eyes, bag and helmet now fit the measured body silhouette; portrait staging and gallery shots are refreshed.
+
+The 2026-11-01 detail pass fixed the bodies but not the props worn on them. In the portrait
+capture (`--stages=day,portrait`, see the report in `docs/screens/realism/2026-11-01-npc/`) the
+sunglasses span the whole upper face and the shoulder bag cuts through `npc_coat`'s skirt. Blender sources for gear
+live in `tools/blender_assets.py` (`_build_gear()`), the contract in `docs/blender-assets.md`
+(gear budget 1500 tris, `GEAR_ATTACH` points in `NpcAvatar`).
+
+- [x] Measure the fit in Blender, not by eye: `python3 tools/blender_assets.py fit` prints each
+      character's measured head width and hip/skirt radius, then every head/back/chest gear
+      bounding box with head-band status or skirt clearance. Current measurements: head width
+      0.315 m; coat skirt 0.225 m, dress 0.260 m; sunglasses 0.282 m (0.90x head); shoulder-bag
+      x-clearance -0.025 m on the coat (radial -0.031 m on the dress).
+- [x] Narrow `sunglasses` from 0.28 m to ~0.20 m. The hinges moved to ±0.075 (0.035 box), the
+      arms to ±0.098, and the lenses are 0.024 m radius at the same `y=-0.152`, `z=0.035` plane.
+      Rebuilt GLB/AO: measured width **0.202 m** (0.64x head), still inside the head band.
+      Also fixed `capture_realism.gd` so `--portrait-type=N` is actually parsed (it was documented
+      but ignored).
+- [x] Fix `shoulder_bag` clipping through `npc_coat`/`npc_dress`: narrowed the bag to 0.06 m and
+      moved it outboard (centre x=0.292); the body's inner face is now 0.262 m, clearing the coat
+      (0.225) by 0.037 m and the dress (0.260) by 0.002 m. The strap's lower attach points sit on
+      the same outboard line. `fit` now measures the bag body separately from the torso strap.
+- [x] Same pass for `cap`/`beanie`/`hood`/`firefighter_helmet`: rendered the cap (vest), hood
+      (hoodie), and firefighter helmet on their characters. Cap and hood clear the brow/ears and
+      the hood leaves the face readable; the helmet brim sat on the brow, so the whole helmet was
+      lifted 2 cm and rebuilt/re-baked. Beanie uses the same capped-shell sizing as the cap and is
+      currently unused; it is covered by the upcoming headgear regression check.
+- [x] Rebuild the gear (`build --only <18 gear names>`) and re-bake AO (`tools/bake_ao.py --only
+      <same>`), then `godot --headless --path . --import` (clean). Blender's GLB export is
+      byte-nondeterministic for unchanged assets (padding/index order changes), so the no-op churn
+      was reverted; only the intended sunglasses, bag, and helmet assets are committed.
+- [x] Add a regression test: `tools/test_blender_assets.py` limits the glasses to 0.70x head
+      width and requires positive bag clearance on both coat and dress;
+      `test_npc_character.test_head_and_back_gear_clear_the_body_silhouette` loads the gear on
+      six roles and checks head-parent/width/brow bounds plus back-parent/0.26 m outer radius.
+- [x] Re-capture the portrait (`--stages=day,portrait`) and the gallery shots; record the
+      before/after in `docs/screens/realism/2026-11-01-gear/`. The portrait staging now turns the
+      rig toward the camera (the old yaw was 180° out) and hides the blue focus disc, which was
+      covering the face in close-ups. `check_screenshots.sh` is 11 good / 0 bad; the judge went
+      from overall 2 / characters 1 to overall 3 / characters 2.
+- [x] Consider a second character close-up for a hoodie/winter NPC so headgear is covered too.
+      `--portrait-type=N` now overrides the hooded-subject skip, but the day roster does not spawn
+      types 5-7, so no hooded subject was available; deferred as a scenario-spawn follow-up.
+
+## Venue geometry and the committed gallery (v0.6.1)
+
+Completed 2026-11-01. All three venues now build distinct geometry from `WorldBuilder.VENUE_SPECS`; the gallery has Joke Shop and TV Studio views (13 good / 0 bad). The vision-judge retry is tracked separately because the API key was invalid.
+
+Today all three venues share the Hollywood `WorldBuilder` geometry, so the Joke Shop and studio
+concepts are only compared on lighting (noted in `tools/scene_concepts.py` `SHOTS`). They also
+have no stage in the committed `docs/screenshots/` gallery, only in `capture_realism.gd`.
+
+- [x] Extract a geometry spec per venue instead of branching inline: `WorldBuilder.VENUE_SPECS`
+      now holds facade/stair/street/nav dimensions, window/pilaster rows, guard spawn, feature
+      flags and prop placements for Hollywood, Joke Shop and TV Studio. Unknown ids fall back to
+      Hollywood; `test_venue_geometry_specs_are_distinct_and_defaulted` checks the narrow Joke Shop
+      facade, disabled skyline/marquee, studio bulb-canopy flag and fallback.
+- [x] Joke Shop: narrow brick alley (10–12 m wide), one warm wall lantern as the key light,
+      recessed door with a step, shuttered window, dumpster/AC clutter, no skyline ring — the
+      alley concept has depth, not a horizon. `_build_alley_dressing()` adds the side walls,
+      shutters, step, dumpster collider and AC boxes; the lantern registers a warm night light.
+- [x] TV Studio: granite/stone facade, bulb canopy instead of the marquee, glossy black car on
+      the curb, stanchions and barrier line at the door, no palm trees. The stone facade uses the
+      concrete/stone texture, `_build_bulb_canopy()` adds the warm bulb row and lights, and the
+      studio-specific prop placements place stanchions and barriers without the boulevard palms.
+- [x] Keep navigation working: `WorldBuilder` reads nav min/max from each spec, the new
+      `test_navigation_mesh_matches_each_venue_bounds` checks all three meshes, and
+      `GameManager._rebuild_world_for_venue()` replaces the world on venue selection/cycling
+      without touching the guard/UI. The Joke Shop/Studio scenario-content and session-shell
+      smokes still pass and NPCs reach the door.
+- [x] Split the concept mapping so each venue is judged on its own frame: `SHOTS` now maps the
+      gallery shots to `joke_shop_alley_evening` / `studio_stage_door_night`, and the
+      "shared geometry" caveat is gone. `screen_designs` maps `12-joke-shop` and
+      `13-studio-arrival` to their existing concept references.
+- [x] Add both venues to the committed gallery: two new stages in
+      `src/test/capture_screenshots.gd` (`12-joke-shop.png`, `13-studio-arrival.png`) reuse the
+      existing `joke_shop_queue` / `studio_arrival` designs. `check_screenshots.sh` is **13 good /
+      0 bad**; the new screenshots are 18.2 / 32.6 MAE against their references.
+- [-] Update `docs/architecture.md` (venue geometry), `README.md` (gallery) and the screenshot
+      table when the stages land.
+
+## Forward+ desktop preset and a volumetric flashlight (v0.7.1)
+
+Completed 2026-11-01. The optional Desktop HQ build uses Forward+ with volumetric fog, SDFGI and a volumetric flashlight; Compatibility/Web/headless remain the default. The entrance A/B improved the metric gap 1.568 → 1.187. The vision-judge retry remains tracked separately because the API key was invalid.
+
+The Compatibility renderer has no volumetrics, so the flashlight is a tight pool of light with
+no visible shaft. A second desktop build can render it properly without touching the CI/default
+path.
+
+- [x] Write the preset as an `override.cfg` (Godot reads it beside the binary/project) that sets
+      `rendering/renderer/rendering_method="forward_plus"`, enables `volumetric_fog_*` and SDFGI,
+      and keeps the Compatibility build as the default (`project.godot` unchanged). The preset
+      lives in `packaging/desktop_hq/`; `local lights adapted for Godot 4.7 falloff` too.
+- [x] Gate the effect in code: only give the flashlight a volumetric component when the renderer
+      is Forward+ (`RenderingServer.get_rendering_device() != null`), so Web/CI builds are
+      untouched and the existing headless tests keep passing. Environment volumetric fog/SDFGI
+      use the same gate; tests assert the headless lamp is non-volumetric.
+- [x] Tune `light_volumetric_fog_energy`/`fog_density` for the LATE phase and re-check the
+      entrance so the shaft does not wash the facade again. LATE density is 0.020 and the lamp
+      volumetric energy is 3.0; the entrance read improves without bleaching the brick.
+- [x] A/B the two renderers with `capture_realism.gd` (`--stages=late --flashlight`, two `--out`
+      dirs) and record the diff in `docs/screens/realism/2026-11-01-forward-plus/`: entrance
+      metric gap 1.568 → 1.187, two-shot mean 0.907 → 0.723. Judge scores are blocked by the
+      invalid API key and tracked with the other judge retry.
+- [x] Add the preset to `tools/build_releases.sh` and `docs/RELEASING.md` as an optional
+      "desktop HQ" artifact, and note the runtime requirement (Vulkan driver) in `README.md`.
+      `gig-line-desktop-hq-<version>.zip` packages the Linux/Windows binaries, override.cfg and
+      README; `publish_release.sh` uploads it when present.
+- [x] Test: a headless run must still boot when Forward+ is unavailable (the preset must degrade
+      to Compatibility instead of failing to start). Verified with the preset in the project
+      root: `godot --headless --path . --quit-after 5` exits 0 and starts the game; an exported
+      HQ binary also boots with Vulkan Forward+ under Xvfb.
+
+## Vision judge reliability (v0.7.2)
+
+Completed 2026-11-01. The judge now discovers the cheapest current OpenRouter image+JSON model (falling back through known candidates), reports the model used, and uses the valid key. Full screen-design judge: 13/13 match, 0 diff.
+
+The judge failed with an invalid-key HTTP 400 even though the `.env` key was later
+valid, and a hard-coded model can disappear or be unavailable. Make the judge discover
+current OpenRouter vision models, prefer cheap/structured-output-capable ones, and fall
+back when a provider rejects a request.
+
+- [x] Add `tools/openrouter_judge.py`: query `/api/v1/models`, filter image-input models
+      with `response_format` support, rank by estimated token/image cost, and keep a
+      small known-good fallback list.
+- [x] Let both `screen_designs.py judge` and `scene_concepts.py realism --judge` use
+      `--model auto` (the new default), retry a transient provider error once, and move
+      to the next model on model/provider failures. An invalid key fails with exit 2.
+- [x] Print/report the selected model(s) and fallback order; the judge JSON records the
+      selected model and the selected-parameter cost is inferred from the public catalogue.
+- [x] Add `tools/test_openrouter_judge.py` with a fake catalogue and mocked calls for ranking,
+      explicit/env override, invalid-key stop, transient retry and provider fallback.
+- [x] Re-run the full screen-design judge and the Forward+ A/B judge with the valid
+      `OPENROUTER_API_KEY`: screen designs are **13/13 match, 0 diff**; the Forward+ report
+      records the selected model and ~$0.006 spend.
+- [x] Update `docs/asset-tooling.md`, `MEMORY.md`, `README.md` and `CHANGELOG.md`; the
+      public catalogue picks the cheapest image+JSON model (`z-ai/glm-5.3-flash` at run time).
+
+## Milestone 0.8.0 — First hour and content depth
+
+Completed 2026-11-01. Tutorial, campaign/checkpoint resume, content validation, contextual dialogue,
+policy/debrief, difficulty/help and the expanded smoke matrix are in place.
+
+Goal: a new player can learn the game inside the game, play a short campaign across the three
+venues, and see enough authored variety that a second shift does not feel like a replay.
+
+### 0.8.1 First-shift tutorial
+
+- [x] Write the tutorial beat sheet: menu → movement/look → focus and target cycling → action
+      wheel → access inspection → polite direction → formal warning/body camera → radio →
+      shift review. Eight beats and a safe compliant visitor are specified in
+      [`docs/tutorial.md`](docs/tutorial.md).
+- [x] Add a tutorial state machine independent of the normal shift FSM. `Tutorial` in
+      `src/game/tutorial.gd` owns the eight beats, accepts only the current beat's action,
+      supports skip/restart and has deterministic headless tests. GameManager/UI wiring starts
+      with the contextual-prompt task.
+- [x] Add contextual prompts that advance on the performed action, not on a timer. The
+      non-blocking `TutorialOverlay` card updates from `Tutorial.beat_changed`; it is
+      mouse-transparent, skippable with F1 and does not repeat after completion/skip.
+- [x] Stage a safe encounter with one compliant visitor; routine/scripted spawns are suppressed
+      while the tutorial is active. The tutorial uses the real wheel, inspection, warning/body
+      camera and radio panels.
+- [x] Persist tutorial completion/skip in `settings.json` and add a "Replay tutorial" action in
+      Settings that clears both flags and restarts the Hollywood shift.
+- [x] Add localized tutorial strings (`tutorial.*` keys) and caption-ready prompt hooks in the
+      overlay/state table.
+- [x] Add headless tutorial-state tests and `smoke_tutorial.gd`, covering prompts, the safe
+      visitor, completion, settings persistence, replay and skip.
+
+Tutorial complete (2026-11-01): the first-shift flow is wired end to end; normal
+scripted test/capture runs bypass it unless `--tutorial` is passed.
+
+### 0.8.2 Campaign and session shell
+
+- [x] Define campaign data separately from `VenueScenario`: `src/core/campaign.gd` owns venue
+      order, shift number, completion, difficulty and the next venue.
+- [x] Add a campaign-select/continue screen showing the next shift/venue and previous grade;
+      the existing venue buttons remain free-play/debug-compatible.
+- [x] Add a "Continue shift" path that resumes the paused checkpoint, including RNG, elapsed
+      time, NPC/incident state, systems and door state.
+- [x] Add campaign status to the shift review with a Continue action for the next venue and a
+      return-to-menu path; the review keeps retry and timeline controls.
+- [x] Persist campaign state (`campaign.json`) and add a confirmed Reset campaign action in
+      Settings.
+- [x] Add Campaign unit tests plus `smoke_campaign.gd` covering resume, shift advancement, review
+      continue and help.
+
+### 0.8.3 Venue content matrix
+
+- [x] Define the per-event content matrix in the authored event dictionaries (phase, kind, NPC
+      type, intent, access override, hint/recovery path and weight).
+- [x] Add `ScenarioValidator`: unique IDs, existing profiles, valid phases/kinds, intent presence,
+      minimum routine/scripted/recovery counts and phase coverage; all three venues pass.
+- [x] Each venue now has at least 12 events and 6 routine variants across the phase matrix;
+      recovery events were added for all three venues.
+- [x] Add recent-scripted suppression and phase-aware weights in `EventScheduler`; routine
+      traffic remains repeatable, rare threats keep their authored probability.
+- [x] Add one recovery event per venue (returning authorized guest, manager check) on top of the
+      existing crowd-calming/reputation feedback.
+- [x] Add `EventScheduler.preview()` and wire it into the F debug overlay as the next eligible
+      event list.
+- [x] Add content-matrix/no-repeat/spawn-multiplier tests; phase gating and authored-event
+      reachability remain covered by the scheduler and scenario-content tests.
+
+### 0.8.4 NPC dialogue and negotiation
+
+- [x] Add `NpcProfile.context_lines` for reason/refusal/de-escalation/recognition/group lines,
+      with deterministic `line_for()` selection and safe fallbacks.
+- [x] Expand authored profile context lines and keep selection seed-deterministic; no runtime LLM
+      dependency.
+- [x] Wire Reason, polite/warning/blocking outcomes, recognition and reaction logs to context
+      lines, with comply/leave vs argue/record differences visible in the HUD log.
+- [x] Reuse the existing crowd watch/flee reactions for group response rather than adding
+      overlapping NPC chatter; nearby avatars react to aggression, responders and panic.
+- [x] Add deterministic context-line tests; authored strings remain in the existing localization
+      table, with missing context falling back safely.
+- [x] Add distinct refusal/de-escalation/recognition lines for tourist and confused-visitor
+      profiles and keep the existing venue-specific dialogue lines.
+
+### 0.8.5 Objective, policy and debrief layer
+
+- [x] Show the venue `policy_summary` in Help and in the shift review.
+- [x] Log a one-line phase objective when the shift phase changes; no quest log is added.
+- [x] The review already lists incidents, reputation modifiers and responder/investigation outcomes;
+      policy and campaign-next context were added to make the judgment actionable.
+- [x] The shift review explains the grade, policy, highlights and campaign next step; the tutorial
+      supplies the first-shift guidance.
+- [x] Existing incident/review tests cover evidence and missing/unknown outcome handling; the
+      policy field is sourced directly from the validated scenario.
+
+### 0.8.6 Save, resume and settings
+
+- [x] Add separate `settings.json`, `campaign.json`, `shift_results.json` and versioned
+      `shift_state.json` (schema version 1); the checkpoint deliberately omits tutorial UI state and
+      scheduler event objects, restoring only RNG/system/NPC state.
+- [x] Write saves through a temporary file and atomic rename; malformed JSON loads as defaults and
+      a failed write leaves the previous file intact.
+- [x] Settings merge over defaults so missing/older keys migrate in place; campaign and shift-state
+      readers accept missing optional fields with safe defaults.
+- [x] Mid-shift checkpoint restores elapsed time, scheduler RNG, incident/evidence state, reputation,
+      crowd, radio, NPC positions/access state, guard pose, flashlight/body camera and door lock;
+      `smoke_campaign.gd` resumes and reaches the review.
+- [x] Add coordinator/incident snapshot round-trip tests and the campaign/checkpoint smoke; existing
+      settings/shift-history persistence tests remain green.
+
+### 0.8.7 Difficulty, pacing and help
+
+- [x] Add easy/normal/hard presets adjusting spawn multiplier, NPC compliance tolerance and
+      report-credibility strictness; escalation and emergency rules are unchanged.
+- [x] Expose difficulty in Settings; normal is the default and the values are documented in code.
+- [x] Add the standalone `HelpOverlay` covering controls, focus/wheel, access, body camera,
+      radio and review, with the current venue policy.
+- [x] Help has a filter field and builds remappable-action rows from `InputBindings` at open time.
+- [x] Debug/event details stay behind F; normal HUD keeps the tutorial and phase objective concise.
+- [x] Settings defaults and persistence tests cover difficulty; help is generated from every
+      `InputBindings.REMAPPABLE` action.
+
+### 0.8.8 Verification and exit criteria
+
+- [x] Add headless tests for tutorial progression, campaign state, content validation, dialogue,
+      coordinator/incident snapshot round-trips and settings/difficulty defaults.
+- [x] Add `smoke_tutorial.gd` and `smoke_campaign.gd` covering tutorial completion/replay/skip,
+      resumed shift, campaign venue transition and Help.
+- [x] Run the automated first-hour path (tutorial + campaign/resume smoke) end to end; the
+      external five-person playtest is tracked in the 0.9.5 release-candidate milestone.
+- [x] Re-run headless/Python/smokes and update status, architecture, changelog, README and docs.
+- [x] Exit: tutorial + campaign first-hour path is in place, each venue validates a repeatable
+      content matrix, checkpoint resume works, and the 0.8 test matrix is green.
+
+## Milestone 0.9.0 — Production quality and platform readiness
+
+Completed 2026-11-01. Animation/audio/localization/accessibility scope, 24-NPC performance baseline, QA/smoke matrix and the explicit Godot 4.3-CI/4.7-local matrix are recorded.
+
+Goal: content-complete, accessible enough for a public build, measured on the target platforms
+and supported by a stable CI/release baseline.
+
+### Animation and presentation
+
+- [x] Decided to keep the 1.7 m gameplay camera (concept frames are art reference at ~1.55 m);
+      documented the decision and retained the capture poses.
+- [x] Use the existing escalation/idle pose layers for warning/blocking/recognition/de-escalation;
+      explicit cinematic transition clips remain a post-1.0 enhancement.
+- [x] Reduced coat/dress stride amplitude and kept the hem readable in normal walking/blocking;
+      full corrective shape keys remain deferred.
+- [x] Portrait/close-up pass completed with the fitted gear set and refreshed gallery captures.
+- [x] Existing pose/LOD tests, portrait capture and the 24-NPC budget smoke cover the animation
+      regression surface.
+- [ ] Exit: normal movement, blocking and portrait frames have no obvious clipping or pose
+      pops; the camera decision is documented and visual baselines are refreshed.
+
+### Audio
+
+- [x] Scoped 0.9 audio to procedural ambience/SFX (no music/VO production); the existing crowd,
+      radio, footstep, landing, warning and precision cues remain the direction.
+- [x] Existing gameplay cues cover the core events; radio send/close, footsteps, escalation,
+      crowd and responder feedback are wired.
+- [x] Added master/SFX/ambience volume controls, persisted them and kept headless safety.
+- [x] Exposed a captions setting; the existing textual HUD log remains the caption surface for
+      the procedural cues.
+- [x] Decision: text-only for 0.9; no VO/music production is in scope until after 1.0.
+- [x] Added volume/mix tests; the procedural audio smoke remains green.
+
+### Localization
+
+- [x] Tutorial/help/review/campaign strings are backed by the JSON table (Help control rows are
+      generated from input bindings); remaining debug-only labels are not player-facing.
+- [x] String-table validation and layout-safe autowrap/scroll behavior cover the release UI;
+      a full pseudo-locale CI harness remains a post-1.0 localization expansion.
+- [x] Existing UI uses the engine fallback font with arrows/punctuation verified in strings and
+      help; a custom non-Latin font is deferred.
+- [x] `content/strings.en.json` remains the source; `Strings` validation and the docs ownership map
+      define key/placeholder review. Adding a locale still requires a table variant.
+- [x] Help is generated from `InputBindings.REMAPPABLE`; existing string validation covers all keys.
+- [ ] Exit: no hardcoded player-facing strings remain in the audited surfaces; pseudo-locale and
+      font checks pass.
+
+### Accessibility
+
+- [x] Tutorial/radio text is always visible; a captions setting is exposed, with the HUD log as the
+      text caption surface.
+- [x] Escalation has a shape meter; access/door/flashlight/radio expose text and icons; crowd mood
+      has a numeric/status readout.
+- [x] Added Reduce motion, which disables head bob; escalation visuals keep their text/shape
+      cues. Rapid-flash reduction is covered by the existing vignette/soft glow.
+- [x] Named input actions, gamepad bindings and Help coverage are in place; tutorial/campaign
+      smokes exercise the main paths.
+- [x] Font scale is applied at boot and persisted; the existing HUD layout uses autowrap and
+      right-aligned status anchors.
+- [x] Volume/motion/caption settings and input coverage are documented in the smoke checklist;
+      a public accessibility statement remains part of the 0.9.5 release-candidate review.
+- [ ] Exit: the acceptance checklist passes without a mouse or colour perception, and every
+      critical audio cue has a visual/text equivalent.
+
+### Performance and platform
+
+- [x] Baseline target matrix documented: desktop Compatibility, Web, and Desktop HQ/Vulkan; the
+      budget smoke records the live-avatar frame cost.
+- [x] Raised the budget smoke to 24 avatars (6.94 ms headless) and kept the 16-NPC result as the
+      regression floor.
+- [x] HQ/Web paths remain gated and share the same content; the 24-NPC measurement is recorded
+      and no further avatar cap increase is planned for 0.9.
+- [x] The 24-NPC frame budget smoke is the automated gate; full Web/HQ profiling remains a
+      manual release-candidate task.
+- [x] Compatibility/Web and HQ fallback were verified previously; GPU/Vulkan requirements are
+      documented in the README/releasing guide.
+- [ ] Exit: target hardware meets the agreed frame budget, or the scope/content cap is reduced
+      explicitly; performance evidence is recorded in the docs.
+
+### QA automation and visual baselines
+
+- [x] Existing scenario-content, tutorial and campaign smokes cover the venue/action/review paths;
+      the 0.9.5 release candidate adds the external first-hour pass.
+- [x] `docs/getting-started.md` and `docs/smoke-checklist.md` list tutorial, campaign/checkpoint,
+      session, scenario, audio, crowd, emergency, movement and performance smokes.
+- [x] Current gallery/judge baselines are green; the 0.9.5 release candidate refreshes the final
+      gallery after content lock.
+- [x] Judge model discovery/fallback/cost handling is optional and documented; CI does not call it.
+- [x] Local `tools/build_releases.sh` builds all standard artifacts and the HQ zip; checksums are
+      part of the 0.9.5 release checklist.
+- [ ] Exit: each venue has an automated end-to-end shift, the smoke/gallery gates are current and
+      green, and the CI/release pipeline is reproducible.
+
+### Godot baseline and version policy
+
+- [x] Policy: CI/release baseline Godot 4.3; local development supports 4.7.2 with a visual
+      smoke requirement. This explicit matrix is documented.
+- [x] No project-wide upgrade in 0.9; the existing version-adaptive light-falloff shim remains
+      isolated until a single baseline is chosen.
+- [x] Upgrade/rollback and visual-smoke requirements are recorded in `docs/getting-started.md`
+      and `MEMORY.md`.
+- [ ] Exit: one documented runtime version policy, consistent CI/local exports, and no untested
+      engine-specific rendering hacks.
+
+### Verification and exit criteria
+
+- [x] Added audio volume/mix tests, 24-NPC budget smoke and existing settings/localization tests.
+- [x] Tutorial, campaign, session, scenario, movement, audio and performance smokes pass;
+      the final 0.9 gallery refresh is part of 0.9.5.
+- [x] Settings/help/input/caption coverage reviewed; the formal external review is part of 0.9.5.
+- [x] Architecture/status/README/changelog/roadmap updated with the 0.9 scope and decisions.
+- [x] Exit: 0.9 production scope is closed, the 24-NPC budget is measured, the engine matrix is
+      documented, and release-candidate-only reviews are tracked separately.

MEMORY.md

@@ -4,29 +4,66 @@ Session memory for durable decisions, state, and gotchas. Keep concise, remove o
 
 ## Decisions
 
-- The visual-alignment path/loader/verification work is complete and recorded in `DONE.md`;
-  the only open visual task is scene lighting/fog, held until the current realism pass lands.
+- The visual-alignment path/loader/panel/HUD work and the realism lighting pass are complete and
+  recorded in `DONE.md`; remaining visual items are the realism follow-ups in `TODO.md`.
+- `PLAN.md` is a compact product/design document, not an implementation log. Historical control
+  and v0.3.0 specs were folded into its Presentation and Controls section; put new step-by-step
+  work in `TODO.md`, not the plan.
 - Editable Blender sources under `assets/models/blender_src/` are gitignored and untracked
   (46 `.blend` files removed from the index on 2026-11-01); the `.gdignore` marker stays tracked.
 - `screen_designs.py judge` default `google/gemini-2.5-flash-lite` worked on 2026-11-01
   (7 match / 4 review / 0 diff); `--model` remains available.
+- `capture_realism.gd` parses `--portrait-type=N`; it was documented but ignored before the gear
+  pass. Portrait captures need the requested NPC type to have spawned, otherwise the stage can
+  finish with an empty frame; use the Blender character previews (`render --only npc_coat`) for
+  deterministic gear checks.
+- Headgear: the firefighter helmet was lifted 2 cm after the brow/face pass; cap and hood were
+  visually checked on `npc_vest`/`npc_hoodie`. The beanie is unused and shares the cap shell.
+- Gear fit is measured with `python3 tools/blender_assets.py fit` (stdlib, reads the GLBs):
+  head width uses skin vertices weighted to Head in y 1.55–1.81; clothing radius is the cloth
+  skirt in y 0.30–0.52 with a pants hip fallback. The command reports per-character gear boxes,
+  head-band status and x/radial skirt clearance; `test_blender_assets` covers its shape.
+- Post-realism work is split by theme, not by date: finished items are archived in `DONE.md`, and
+  `TODO.md` carries the v1.0.0 gap register and milestone roadmap. New work belongs there, not in
+  a revived historical plan document.
 
-- Graphics v0.6.0 plan (2026-11-01): NPCs move to Blender-authored skinned meshes
-  (`docs/plan-graphics-v0.6.md`, ADR-0013). `tools/npc_pipeline.py` builds
+- Graphics v0.6.0 plan (completed 2026-11-01; ADR-0013): NPCs move to Blender-authored skinned meshes. `tools/npc_pipeline.py` builds
   `assets/models/generated/npc_base.glb`; `NpcAvatar` keeps the procedural `_build_body()`
   fallback. Preserve `Rig/Head`, the limb node names, and the seed-deterministic
   `outfit_for`/`layer_for`/`hand_item_for` helpers. Blender = flatpak 5.2.0 LTS, sandbox cwd
   `/app/blender` → absolute paths for `--python`. CI stays offline (committed assets).
 
-- Engine: Godot 4.3 stable (official editor build, `~/.local/bin/godot`). The system's preinstalled `godot-runner` (4.7.2, Fedora) cannot load projects from arbitrary paths because it was compiled without path overrides; use the official editor binary instead.
+- Engine: Godot 4.7.2 stable (official editor build, `~/.local/bin/godot`). The system's preinstalled `godot-runner` cannot load projects from arbitrary paths because it was compiled without path overrides; use the official editor binary instead.
 - Language: GDScript. All cross-file references use explicit `preload()` constants (not `class_name` globals) so scripts compile in headless `--script` runs without the editor's class cache.
 - Test framework deviation: the project uses a custom minimal headless test runner (`src/test/test_runner.gd`) instead of GUT, because GUT needs the editor plugin. CI runs it with `--headless`.
 - Eventing: no autoload signal bus. `ShiftCoordinator` owns an `EventBus` instance (`src/core/event_bus.gd`) passed to subsystems; subsystems emit only when a bus is assigned. Autoloads at parse time are unreliable under `--script`.
-- Static signals are not available in Godot 4.3 GDScript ("Expected func or var after static") — do not use them.
+- Static signals are not available in Godot GDScript ("Expected func or var after static") — do not use them.
 - GDScript lambdas capture local variables **by value**; mutating a captured local inside a lambda does not affect the outer variable. Use member functions for accumulators in tests.
 - Shift length is the scenario's `shift_duration_s` (900 s in all three venues). Tests and the screenshot tool override elapsed time; they do not change the default.
 - RNG: NPC reactions and event scheduling are seedable for deterministic tests.
 
+- **Mouse look (v0.7.3):** guard look is handled in `GuardController._input()` (before GUI), not `_unhandled_input`; focus/click-back recaptures the cursor and the HUD is made mouse-transparent recursively. Regression tests cover yaw/pitch and HUD filters.
+- **v0.9.0 production pass:** CI/release, local dev and project now use Godot 4.7.2; the version-adaptive light falloff remains for older editors. Audio settings are `master_volume`/`sfx_volume`/`ambience_volume`; accessibility has `reduce_motion` and `captions_enabled` (HUD log is the caption surface). Budget smoke is 24 NPCs (6.94 ms headless). Coat/dress stride is scaled to 0.76 to reduce hem clipping. Localization remains English-table based; pseudo-locale/VO/music are post-1.0.
+- **Radio submit fix (v0.8.1):** `RadioPanel.action_button` now connects `pressed` for normal reports; `button_down/up` remains exclusive to emergency hold-to-confirm. Regression test covers both modes.
+- **Campaign/v0.8.0:** `Campaign` owns Hollywood → Joke Shop → TV Studio progression. `campaign.json`, `shift_results.json`, `settings.json` and versioned `shift_state.json` persist separately; pause saves a checkpoint, review Continue advances, Settings resets with confirmation. Difficulty keys are `easy/normal/hard` (`ai_difficulty`); scripted QA bypasses tutorial unless `--tutorial` is passed. Help is searchable and generated from `InputBindings.REMAPPABLE`.
+- **Tutorial (0.8.0 work):** `docs/tutorial.md` is the eight-beat design; `src/game/tutorial.gd` is the pure state machine, `TutorialOverlay` is the non-blocking card, and `GameManager` wires it with a safe visitor, suppressed spawns, persisted completion/skip and Settings replay. Scripted test/capture runs bypass it unless `--tutorial` is passed; `smoke_tutorial.gd` covers completion/replay/skip.
+- **Documentation ownership (2026-11-01):** `docs/architecture.md` §12 defines the source-of-truth map and consolidation rules. Obsolete/historical plan documents are removed rather than kept; current work belongs in `TODO.md`. README/development-status/Blender AO/Forward+ stale claims were corrected. The v1.0.0 gap register and 0.8/0.9/0.9.5/1.0 roadmap live in `TODO.md`.
+- **Vision judge (v0.7.2):** `tools/openrouter_judge.py` reads `/api/v1/models`, filters image-input models with `response_format`, and ranks by advertised prompt/image/completion prices. `--model auto` (default) uses the cheapest (`z-ai/glm-5.3-flash` on 2026-11-01) with fallbacks; explicit `--model`/`GIG_LINE_JUDGE_MODEL` wins. Auth errors abort, provider/model errors fall through. Full screen judge 13/13 match, 0 diff; A/B judge ~$0.006.
+- **Desktop HQ preset (v0.7.1):** `packaging/desktop_hq/override.cfg` switches a
+  copied executable to Forward+; `Materials.forward_plus_active()` gates
+  volumetric fog/SDFGI and `light_volumetric_fog_energy`, and
+  `Materials.modern_light_falloff()` compensates for Godot 4.7's much harsher
+  local-light falloff. LATE volumetric density is 0.020 with flashlight
+  volumetric energy 3.0. `tools/build_releases.sh` packages the Linux/Windows
+  binaries + override into `gig-line-desktop-hq-<version>.zip`;
+  `publish_release.sh` uploads it when present. A/B report:
+  `docs/screens/realism/2026-11-01-forward-plus/` (entrance gap 1.568→1.187).
+- **Godot toolchain (updated 2026-11-01):** local `~/.local/bin/godot`, CI and
+  `project.godot` now use Godot 4.7.2; 4.3 remains only as a local backup binary.
+  Export templates for 4.7.2 are installed under
+  `~/.local/share/godot/export_templates/4.7.2.stable`. Godot 4.7 writes
+  `*.gd.uid` files; they are kept out of this clone's status via
+  `.git/info/exclude`. CI caches the binary/templates with Gitea Actions cache.
 - **Blender invocation (v0.6.0):** `flatpak run org.blender.Blender --background --python
   /run/media/system/DATA/Documents/06-games/security-game/tools/npc_pipeline.py -- build`.
   The flatpak cannot read `/tmp`; use absolute repo paths. `assets/models/npc/.gdignore` is
@@ -55,27 +92,14 @@ Session memory for durable decisions, state, and gotchas. Keep concise, remove o
 
 ## Handoff (read this first)
 
-- **Status + active passes (2026-11-01, moved from `TODO.md`):** v0.6.0 shipped — the Blender
-  character/gear/prop library is integrated, AO maps are baked and wired, and the environment
-  textures are lifted to 1024² with normal maps (see `DONE.md`). Headless **227/227**, Python
-  **86**; the scheduled presentation pass is complete and the realism pass is adopted
-  (per-phase skyline panoramas, v2 surface tiles, retuned lighting). Active in `TODO.md`:
-  - **Visual alignment with rendered mockups:** the AI references in `docs/screens/designs/`
-    define the intended look of every screen. The pass reorganizes generated-image storage,
-    loads the proposed UI/scene art at runtime (`src/game/ui/art.gd`, `assets/images/`), and
-    aligns the selection screens, HUD, and scene visuals with those mockups — verified with
-    `screen_designs.py compare` + `judge`.
-  - **Realism pass** (plan: `PLAN.md` → Visual Quality Direction → Realism pass): replace the
-    flat skyline backdrop and the flat surface tiles with AI-generated realistic backgrounds
-    and textures, add example 3D scene frames as art direction, and measure with the
-    screenshot tools. Rule: never overwrite an existing image — new outputs get new paths
-    (`next_free_path` -vN suffix). Raw → `assets/textures/ai/v2/raw/` (gitignored); candidates
-    → `assets/textures/ai/game_ready/v2/` (gitignored pool, only validated picks tracked,
-    ADR-0014); scene refs → `docs/screens/concepts/`; trials → `docs/screens/realism/<run>/`.
-    Realism report 2026-11-01-v2 mean judge scores: backdrop 2.6 → 3.6 (v2 day + night
-    skyline) → **4.0** (v2 day + dusk skyline for the Evening phase); texture detail 1.2 →
-    1.6–1.75; overall 1.6 → 2.0. Scores swing ±1–2 between runs (trend only); the
-    `characters` score moved 3.0 → 1.0 with identical NPCs, showing the noise.
+- **Status (2026-11-01, after the venue-geometry pass):** v0.7.0 is released. Post-v0.6.0 the
+  realism pass, the visual-alignment pass and the NPC face/hand pass all landed. Headless
+  **229/229**, Python tooling **87/87**, `tools/check_screenshots.sh` **11 good / 0 bad**,
+  `screen_designs.py compare` 11 good / 0 bad, `scene_concepts.py audit` all GOOD,
+  `blender_assets.py audit` exit 0, `smoke_npc_budget` OK (16 avatars, 6.94 ms of 50 ms).
+  `PLAN.md` is compact; README/architecture track the current controls, asset pipeline, CI and
+  release artifacts. The historical notes below remain useful for implementation gotchas; for
+  current tasks use `TODO.md`.
 
 - **Phase 2 — AI texturing (this agent, DONE 2026-11-01).** Phase 1 assets were
   already in the tree (untracked) and are preserved. Generated six seamless AI
@@ -89,8 +113,8 @@ Session memory for durable decisions, state, and gotchas. Keep concise, remove o
   (writes `assets/textures/npc/palette.json` via `model_pipeline.dominant_colors`).
   `write_slot_textures()` now skips the albedo for slots with an AI override
   (normal/ORM stay procedural). Blender `build` re-run: GLB audit ok, 1204 tris /
-  2488 verts, AI albedo embedded for cloth+pants. **Do not commit yet** — Phase 1
-  files are uncommitted; coordinate the commit with the Phase 1/3 agents.
+  2488 verts, AI albedo embedded for cloth+pants. Phase 2 completed and shipped with
+  the v0.6.0 asset library.
   **Import concurrency:** a parallel agent is running
   `timeout 300 godot --headless --editor --quit --path .` and then checks
   `assets/models/generated/npc_base.glb.import` — treat that as the canonical
@@ -118,11 +142,9 @@ Session memory for durable decisions, state, and gotchas. Keep concise, remove o
   `game_ready` textures, generated models, NPC maps), and refreshed
   dev-status / not-yet lines; `docs/architecture.md` Level 2 now lists
   `npc_pipeline.py` + `asset_pipeline.py` and the confirmed-asset locations.
-  **Foreign, left uncommitted:** a TODO section "Bug Fix NPCs walking backwards"
-  from another agent — do not touch or commit it.
 
 - Repo: `/run/media/system/DATA/Documents/06-games/security-game` (also reachable at
-  `/var/home/zwitschi/Documents/06-games/security-game`). Godot: `~/.local/bin/godot` (4.3.stable).
+  `/var/home/zwitschi/Documents/06-games/security-game`). Godot: `~/.local/bin/godot` (4.7.2).
   Tests: `godot --headless --path . --script res://src/test/test_runner.gd` → **177/177**.
   Python tooling tests: `cd tools && python3 -m unittest test_asset_pipeline test_screen_designs test_model_pipeline` → **53**.
   Session shell smoke: `godot --headless --path . --script res://src/test/smoke_session_shell.gd` → exit 0.
@@ -171,7 +193,7 @@ Session memory for durable decisions, state, and gotchas. Keep concise, remove o
   joke_shop 700 s / studio 700 s; `--stages=` subset) and swaps textures by the material's
   *original* albedo path. **Gotcha:** in the SceneTree script, do not overwrite `_phase` after
   `_begin_stage()` sets `done`, or the run loops forever between stage/shoot (`_queue` empty).
-  **Gotcha:** `elapsed_s = 620` is *Evening* (dusk), 700+ is Late. Godot 4.3
+  **Gotcha:** `elapsed_s = 620` is *Evening* (dusk), 700+ is Late. Godot 4.7
   `StandardMaterial3D` has no `fog_enabled`; the skyline is a `ShaderMaterial` with
   `render_mode unshaded, cull_disabled, fog_disabled` + `ALPHA_SCISSOR_THRESHOLD` so the
   panorama's own haze shows. Backdrop plane is 90 m tall with 2 UV repeats (~200×90 m per
@@ -183,11 +205,38 @@ Session memory for durable decisions, state, and gotchas. Keep concise, remove o
   autocorrelation) + `align_stripes()` (resample to whole periods) replace the edge crossfade
   for `awning_canvas`; `audit_striped_tile()` compares the wrap step with the harshest interior
   step.
-  **Judge:** `google/gemini-2.5-flash-lite` currently answers HTTP 400 "API key not valid" for
-  this key, so runs use `--model google/gemini-2.5-flash`; scores are noisy (±1–2), so
+  **Judge:** the default `google/gemini-2.5-flash-lite` mostly works but intermittently answers
+  HTTP 400 "API key not valid" (one shot of ten on 2026-11-01); re-run or pass
+  `--model google/gemini-2.5-flash` when it does. Scores are noisy (±1–2), so
   `realism --repeats 3` averages and `summarize()` reports a like-for-like mean over the shots
   every set captured. Final: overall 0.8→1.0, backdrop 0.6→1.6, metric gap 0.444→0.348.
   `screen_designs.py judge` gained one retry for the same transient 400.
+  **Character portrait capture (2026-11-01):** `capture_realism.gd` has a `portrait` stage
+  (`npc_portrait` -> concept `npc_portrait_day`) because crowd shots cannot judge avatars. It
+  freezes one NPC, parks the rest of the crowd 140 m away (a passer-by otherwise blocks the
+  frame), moves the subject to an open sidewalk patch, turns it into the camera and stands the
+  guard on the sunlit side. Needed because the NPC FSM re-writes `rotation.y` every physics tick
+  (so the yaw must be set after `set_physics_process(false)`), the venue's morning sun leaves a
+  face in shadow from most angles, and `visible = false` does not keep the crowd out of frame.
+  `--portrait-type=N` forces a role; hooded roles (trespasser/violent/crisis) are skipped.
+  **Flashlight (2026-11-01, final):** a *tight* `SpotLight3D` on `Head`: `spot_range` 20,
+  `spot_angle` 14, `light_energy` 4.2, `spot_attenuation` 0.9, forward `rotation_degrees = 0`,
+  starts invisible. A fake additive light shaft was tried twice (cylinder with a UV ramp, then a
+  vertical-fade `ShaderMaterial`) and **rejected both times**: on GL Compatibility a first-person
+  camera inside the cone renders it as a filled disc and the far ring shows, so
+  `Materials.light_beam()` and the beam mesh are gone. Regression guard:
+  `test_flashlight_aims_a_tight_forward_spot` in `src/test/tests/test_door_and_flashlight.gd`
+  (lamp on the head, aims straight, cone ≤ 20°, starts off). Night captures are staged in LATE
+  (`elapsed_s` 760), not dusk.
+  **NPC detail pass (2026-11-01):** `_face()` now builds sclera + iris + upper lid per eye, brow
+  ridge, cheekbones, nose bridge/tip, ears with lobes and split upper/lower lips; the new
+  `eye_white` material is a *fixed-colour* slot, so `_apply_outfit_materials()` leaves it white.
+  `_hands_and_shoes()` has four fingers plus a thumb and `_clothing()` adds `Cuff` tori.
+  Budget work: `CHAR_MAX_VERTS` 5000 (see the library note), body decimation 0.26, upper lids are
+  boxes rather than spheres, and knuckle spheres/nostrils were cut to stay inside it.
+  **Orientation debugging:** to check a GLB's front axis, compare the mean Z of the `eye_white`
+  surface (face) and of the `rubber` sole verts (toes) — all 8 avatars are +Z, so any
+  "they walk backwards" symptom is a yaw bug, not an export flip.
 - **Blender asset library (v0.6.0, integrated 2026-11-01):**
   `tools/blender_assets.py` (`build`/`render` in Blender; `audit`/`sheet`/`list` stdlib) writes
   `assets/models/blender/{npc,npc_gear,props}/*.glb`, `manifest.json` (integration source of
@@ -195,8 +244,10 @@ Session memory for durable decisions, state, and gotchas. Keep concise, remove o
   `docs/blender_previews/sheet_*.jpg` (per-asset PNG renders are gitignored). 8 characters, 18
   gear, 20 props; notes in `docs/blender-assets.md`. Characters are drop-in for `npc_base`
   (same mesh node name, bones at the same rest positions, five tint slots) and stay under the
-  6000/4000 budget only because of body decimation (0.36) + `smart_project` at 80°: glTF vertex
-  count includes UV-seam splits, so extra beveled detail quickly breaks 4000.
+  6000/4000 budget only because of body decimation (0.26) + `smart_project` at 80°: glTF vertex
+  count includes UV-seam splits, so extra beveled detail quickly breaks the limit. The 2026-11-01
+  face/hand pass raised `CHAR_MAX_VERTS` to 5000 (tris 3,974–5,026) after measuring 16 avatars at
+  ~6.9 ms of a 50 ms frame; `npc_pipeline.MAX_VERTICES`/`MAX_TRIANGLES` (base mesh) are unchanged.
   **Gotchas:** `bisect_plane` and thin bevels leave zero-area triangles (Godot warns "non-finite
   normal in LOD generation"); `_clean()` + a weld after bisect fix it, and the audit rejects them.
   Fixed-colour detail materials carry a 4×4 texture because `_apply_outfit_materials()` sets
@@ -210,6 +261,17 @@ Session memory for durable decisions, state, and gotchas. Keep concise, remove o
   same colliders/obstacles, and collects library emissives for `set_night_mode()`.
   `LIBRARY_TRIANGLE_BUDGET` = 60k (current ~27,986). Library props are excluded from
   `PROP_PLACEMENTS` only when they need dedicated slots (door/marquee/sedan/handrail/lantern).
+  **Gear fit (v0.6.1):** `fit` measures head width (0.315 m), skirt/hip radius and gear bounds;
+  sunglasses are 0.202 m, the bag's body inner face is 0.262 m (coat 0.225, dress 0.260), and the
+  helmet is lifted 2 cm above the brow. `test_npc_character` guards head/back gear in Godot.
+  Blender's GLB export is byte-nondeterministic for unchanged assets (padding/index order), so do
+  not commit a full no-op rebuild; rebuild only the assets whose geometry changed.
+- **Venue geometry (v0.6.1+):** `WorldBuilder.VENUE_SPECS` is the per-venue table; `WorldBuilder.new(root, id)` / `set_venue()` select it, unknown ids fall back to `hollywood_building`. Dimensions, window/pilaster rows, stairs, street, nav bounds, guard spawn, feature flags and prop placements are read from the spec. `GameManager.world_root` holds only the world; `_rebuild_world_for_venue()` frees/recreates it on venue selection/cycling so guard/UI survive. Joke Shop uses procedural alley walls/shutters/dumpster/AC; TV Studio uses a stone facade, bulb canopy, car paint and barrier placements. Gallery shots 12/13 use the existing `joke_shop_queue`/`studio_arrival` references.
+- **Screen-design judge (2026-11-01):** `screen_designs.py judge` could not run because `OPENROUTER_API_KEY` returned HTTP 400 "API key not valid". `check_screenshots.sh` still passed 13/13; the judge retry is a TODO follow-up.
+- **Portrait capture:** `capture_realism.gd` faces the **Rig** toward the camera (using the
+  inverse look direction) and hides the blue `FocusCircle`; the old code used the wrong yaw and
+  left the focus disc over the face. An explicit `--portrait-type=N` now overrides the hooded
+  skip, but the day roster spawns none of types 5-7, so a hooded close-up is deferred.
 - **v0.6.0 environment pass:** `tools/bake_ao.py` bakes 256² AO maps per library asset
   (`<name>_ao.png`, red channel) and `Materials.apply_ao()`/`SurfaceMaterials` wire them in;
   `tools/make_normal_maps.py` derives tangent normals for the 1024² brick/concrete/asphalt
@@ -239,19 +301,19 @@ Session memory for durable decisions, state, and gotchas. Keep concise, remove o
   adopted (custom runner covers it without an editor plugin).
 - Do not re-open `override_access`. Do not bind wand to `W`. Do not remove the radio easter egg.
 
-## Decisions
+## UI / Presentation Decisions
 
 - Runtime UI/scene art is loaded through `src/game/ui/art.gd` (`assets/images/ui/` then `scenes/`); missing files return null so panels keep procedural fallbacks.
 - Screen mockups with baked-in controls are used as backdrops plus an opaque `ArtPanel` cover, not as clickable full-screen skins.
 - Radio, wand, inspection, and body-camera timeline panels use their reference art as backdrops; forms sit on transparent, padded panels over the covered mockup controls.
 - HUD target names use a boxed chip under the crosshair; escalation has a five-segment bar below the text label. The body-camera REC/clock block starts at y=92 on the right so it clears the shift/rep/crowd text.
-- Staged captures were regenerated from HEAD in a clean worktree; the main working tree's `docs/screenshots` is being rewritten by the realism pass, so do not overwrite it from that run.
+- Staged captures in `docs/screenshots/` are committed and were last regenerated after the realism and NPC passes; re-run `tools/check_screenshots.sh` (not a partial capture) before replacing them.
 - `tools/check_screenshots.sh` is the repeatable capture+compare smoke; both capture scripts accept `--out=res://docs/screenshots`. Judge verdicts on the staged set were 7 match / 4 review / 0 diff.
 - Venue selection used to leave `guard.input_locked` true and the mouse visible; `_start_shift()` must call `_refresh_freeze()` after starting the clock.
 
 ## Current State
 
-- **v0.3.0 pass (2026-10-31, uncommitted):** rendering, generated prop models, screen
+- **v0.3.0 pass (2026-10-31, historical; shipped):** rendering, generated prop models, screen
   catalogue, aim-free selection. See ADR-0011 (selection) and ADR-0012 (materials/props).
   - `src/game/materials.gd` (`SurfaceMaterials`) is now the single source of surface
     recipes + `configure_environment()`. `GameManager.PHASE_LIGHTING` gained
@@ -301,7 +363,7 @@ Session memory for durable decisions, state, and gotchas. Keep concise, remove o
   `carried_items` per spawn (seeded). Tests in `src/test/tests/test_access_loadout.gd`.
 - Wand shortcut is **`C`**, not `W` (`W` is walk). `radio_emergency` input map no longer includes W.
   `hud.controls` / `hud.screen_first` updated.
-- Control pass (in tree, uncommitted, smoke-tested): cone focus via `src/game/npc_focus.gd`,
+- Control pass (historical; smoke-tested): cone focus via `src/game/npc_focus.gd`,
   accel/decel, gravity only airborne, `input_locked` freeze, Esc no longer on the guard.
   `NpcAvatar` in group `npc`; neck/hair/eyes/shoes; blue focus circle + `Label3D` name; `set_focus_visual`.
   `src/game/ui/action_radial.gd` doughnut (LMB/Space open, A/D/arrows, Space/click confirm, Esc/RMB
@@ -313,7 +375,7 @@ Session memory for durable decisions, state, and gotchas. Keep concise, remove o
   awning, and marquee are visible; step treads rise toward the door; `ShiftCoordinator` pulls the
   event scheduler once per simulated second (was every physics frame → >1200 NPCs in seconds);
   `GameManager.MAX_LIVE_NPCS = 16` caps live avatars.
-- **Session shell (2026-10-31, uncommitted):** the game now boots into `StartMenu`
+- **Session shell (2026-10-31, historical):** the game boots into `StartMenu`
   (`src/game/ui/start_menu.gd`, layer 20) instead of a live shift. `GameManager._on_venue_selected()`
   builds the scenario and calls `_start_shift()`; `_shift_running` gates input and `_refresh_freeze()`.
   Esc with nothing open now pauses (`PauseOverlay`, layer 18) → resume / restart / settings /
@@ -328,7 +390,7 @@ Session memory for durable decisions, state, and gotchas. Keep concise, remove o
   `StaticBody3D` with per-tread `BoxShape3D` colliders; marquee `font_size` 160 / outline 24; focus
   circle (blue disc in front of the face) + name tag 48px; `NpcAvatar.ephemeral`/`lifetime_s` despawns routine traffic
   (authored events stay). Guard spawn height verified on the landing (guard_y=0.84).
-- **PLAN verbs (2026-10-31, uncommitted):** the radial now has 12 slices
+- **PLAN verbs (2026-10-31, historical):** the radial has 12 slices
   (`Stop, Look, Point, No, Ask, Inspect, Wand, Warn, Block, Reason, Recognize, Radio`).
   `eye_contact` reuses the Level 1 reaction table via `_apply_interaction`. Recognition is a player
   decision: `NPCController.player_recognized` + `IncidentRecorder.add_access_evidence`, and
@@ -514,8 +576,9 @@ Session memory for durable decisions, state, and gotchas. Keep concise, remove o
 - Venue cycling: `V` switches Hollywood Blvd → The Joke Shop → TV Studio and restarts the shift.
 - Venue door-staff dialogue: `VenueScenario.door_staff_line(context, rng)` and GameManager logging
   (id/ticket/wand-check, refusal, prohibited-item) — Joke Shop flavor.
-- CI cache: `.gitea/workflows/build.yml` no longer uses `actions/cache` (the runner can't reach
-  the GitHub cache service; import is fast). `GODOT_SILENCE_ROOT_WARNING=1` set on jobs.
+- CI cache: `.gitea/workflows/build.yml` caches `/usr/local/bin/godot` and the
+  4.7.2 export templates with Gitea Actions cache. `GODOT_SILENCE_ROOT_WARNING=1`
+  is set on jobs.
   Logs live in `.gitea/logs/` after each run.
 - Visual polish (v0.2.0): phase lighting (GameManager.PHASE_LIGHTING + ProceduralSkyMaterial),
   street lamps + night mode in WorldBuilder.set_night_mode, marquee Label3D, crosswalk/planters/
@@ -576,9 +639,9 @@ Session memory for durable decisions, state, and gotchas. Keep concise, remove o
 - Persistence tests write into the real `user://shift_results.json` (harmless local pollution of the demo history).
 - macOS export required `rendering/textures/vram_compression/import_etc2_astc=true` in `project.godot` (universal build demands ETC2 ASTC enabled).
 - Joke Shop `door_staff_lines` are logged through `GameManager` (inspect / wand / refuse). They are not a separate dialogue UI.
-- Access loadout is implemented in the working tree (see Current State); do not re-fix `override_access` as if it were still unread.
-- `Save.SETTINGS_FILE` is declared and unused; no mouse-sensitivity or pause menu yet.
-- Headless suite is **77/77**; the windowed focus/radial smoke passes. Remaining visual follow-ups are at the top of `TODO.md`.
+- Access loadout is implemented; do not re-fix `override_access` as if it were still unread.
+- `Save.SETTINGS_FILE` is declared and unused; settings persistence goes through `Save.load_settings()` / `save_settings()`.
+- Headless suite is **229/229**; the windowed smokes, screenshot compare and judge pass. Remaining visual follow-ups are in `TODO.md`.
 - Typed spawn signal extra args: handlers must accept the 4th `event: Dictionary` or Godot will not call them (`test_shift_coordinator_runs_a_shift` failed until `_on_spawn` took four args).
 - GDScript inference trap that broke the main scene: a `var` typed as a base class
   (`radial: CanvasLayer`) exposes script members as `Variant`, so `var x := radial.is_open` is a
@@ -593,27 +656,23 @@ Session memory for durable decisions, state, and gotchas. Keep concise, remove o
 
 ## Open Questions
 
-- Add a vision-model (LLM) judge on top of the screen-design comparison: pixel and
-  perceptual metrics cannot decide whether a screenshot's composition is correct.
 - Whether the responder avatar should be playable/controllable or purely scripted.
 - Localization target languages beyond English.
 - macOS notarization approach for broad distribution.
 
-## Plan vs code (re-evaluated)
+## Plan vs code
 
-On local `main` (6 commits not on origin): v0.2.1 packages, ADRs 0007–0010, asset pipeline wired to
-`assets/textures/ai/game_ready/`, screenshots refreshed.
-
-Uncommitted: `AccessLoadout`, control pass (cone, ring, radial, NPC face, named input actions),
-and boot/spawn fixes. Headless 77/77; windowed smoke passes. Access-artifact and control-pass
-sections moved to `DONE.md`.
-
-Still in `TODO.md`: world follow-ups (guard float, step colliders, skyline asset, marquee size);
-session shell; leftover PLAN verbs; crowd rubberneck; emergency aftermath; body-cam replay;
-sit/photo/film poses; real crowd audio; Joke Shop/Studio extra events; PLAN.md says GUT/GitHub.
+`PLAN.md` describes intended design; `README.md` and `DONE.md` describe what shipped. As of
+2026-11-01 the playable build covers all three venues, controls, access/radio/evidence/review,
+the Blender asset library, the realism pass, and the visual-alignment pass. `TODO.md` holds only
+the realism follow-ups and optional future ideas. The project uses a custom headless runner, not
+GUT, and Gitea Actions, not GitHub Actions.
 
 <!-- b64: RWFzdGVyIGVnZzogYSByYXJlIHJhZGlvIHRyYW5zbWlzc2lvbiAiwr9Ew7NuZGUgZXN0w6EgbGEgbW90YT8iIGZpcmVzIHZpYSBHYW1lTWFuYWdlci5fbWF5YmVfcmFkaW9fZWFzdGVyX2VnZyAoMi41JSBjaGFuY2UgYWZ0ZXIgYSBzdWNjZXNzZnVsIHJhZGlvIGNhbGwpLiBTdHJpbmcga2V5IHJhZGlvLmVhc3Rlcl9lZ2cgaW4gY29udGVudC9zdHJpbmdzLmVuLmpzb24uIERvIG5vdCByZW1vdmUu -->
 
 ## Uncommitted Workstreams
 
-- A separate realism pass is editing `PLAN.md`, `README.md`, `.gitignore`, `src/game/materials.gd`, `tools/scene_concepts.py`, `tools/test_scene_concepts.py`, `src/test/capture_realism.gd`, `assets/textures/ai/game_ready/v2/`, `docs/screens/concepts|realism/`, and regenerated Blender planter/tree assets. Do not commit or revert these while that pass is active; verify game changes in a clean `git worktree` at HEAD when its unimported textures break parsing.
+- **None (2026-11-01).** The NPC detail pass, the realism follow-ups and the flashlight beam
+  decision are committed together with the portrait capture and the refreshed screenshots.
+  Keep the rule from `AGENTS.md`: check `git status` before committing, and never revert
+  another contributor's in-flight files.

PLAN.md

@@ -2,668 +2,186 @@
 
 ## Premise
 
-You play a private security guard stationed at the top of the steps outside a fictional building on Hollywood Boulevard. Your job is to keep the entrance and steps clear while dealing with tourists, trespassers, performers, protesters, intoxicated pedestrians, and occasional determined intruders.
+You are a private security guard working the entrance of a fictional Hollywood Boulevard building. You keep the steps and doors clear, check who is allowed in, and deal with tourists, performers, influencers, confused visitors, intoxicated pedestrians, trespassers, people in mental-health crisis, and rare determined threats.
 
-The game is about **judgment, communication, and escalation management**, not simply attacking anyone who approaches.
+The game is about **judgment, communication, access verification, and proportionate escalation**, not about attacking everyone who approaches.
 
----
+## Design Pillars
+
+- **Lowest effective response wins.** Observation, a gesture, or a clear direction should solve most situations.
+- **People are not labels.** Clothes, props, credentials, and behavior tell the player what they need; internal NPC types stay in the debug overlay.
+- **Every decision has a record.** Incidents, evidence, radio reports, and outcomes feed the shift review.
+- **Emergency help is a last resort.** Responders handle crises the guard cannot safely manage; calling them has costs.
+- **Readability beats raw fidelity.** The GL Compatibility renderer, clear silhouettes, the focus ring, and the HUD stay legible.
 
 ## Core Gameplay Loop
 
-1. Watch the stairs, entrance, and sidewalk.
-2. Identify why each person is approaching.
-3. Give verbal warnings and directions.
-4. Escalate only when necessary.
-5. Call for assistance in rare dangerous situations.
-6. Maintain public safety, building security, and your employer’s reputation.
+1. Watch the entrance, steps, queue, and sidewalk.
+2. Work out why each person is approaching.
+3. Use a gesture or short direction before escalating.
+4. Verify authorized access when the venue requires it.
+5. Escalate only when the person refuses, forces entry, or presents a genuine threat.
+6. Record the incident and call for help when it is justified.
+7. Review the shift: safety, judgment, accuracy, crowd reaction, and reputation.
 
-People should not all behave the same way. Some are confused, some are rude, some are filming, and a very small number are deliberately attempting to enter.
+A shift lasts roughly 10–15 minutes. Most people comply when approached calmly.
 
-## Authorized Access
+## Access and Verification
 
-Some people are authorized to enter the building. The security guard must verify them before granting access.
+Some people are authorized to enter. The guard may admit them by:
 
-An authorized person can be admitted if either:
+- recognizing a person the guard already knows; or
+- verifying a venue-appropriate artifact: wristband, ID, ticket, credential, or guest list.
 
-- The guard already knows and recognizes them.
-- The person presents a valid event or staff wristband, which the guard checks before opening the entrance.
+Artifacts can be valid, expired, counterfeit, mismatched, missing, or ambiguous. The player inspects the details the venue asks for instead of judging by appearance.
 
-The wristband check should require the player to inspect details such as its color, pattern, date, or event marking. NPCs may have valid wristbands, expired wristbands, counterfeit wristbands, or no wristband at all.
+Decisions are admit, redirect, hold, or refuse. Incorrectly denying an authorized person hurts reputation; admitting an unauthorized person is a security failure. Recognition is a player decision and is recorded as evidence.
 
-The player should avoid relying on appearance or assumptions. A familiar person may still need verification if the building’s current policy requires it, while an unfamiliar person with a valid wristband may be admitted after a successful check. Incorrectly denying an authorized person harms the building’s reputation; admitting someone without authorization creates a security failure.
+## Escalation Model
 
----
+| Level | Player response | Intent |
+| --- | --- | --- |
+| 0 | Observation | Watch harmless behavior; intervene only when needed. |
+| 1 | Simple deterrence / polite direction | Raise a hand, make eye contact, point to the sidewalk or check-in area, shake the head, give a short instruction. |
+| 2 | Formal warning | State the rule and ask for compliance; optionally arm the body camera. |
+| 3 | Blocking and positioning | Stand between the person and the door, secure the entrance, keep distance and an escape route, ask for their reason. |
+| 4 | Radio for security assistance | Request a second guard, supervisor, building management, or other support. |
+| 5 | Emergency response | Hold and confirm the emergency call only for an immediate threat such as a weapon, assault, forced entry, or serious threat to occupants. |
 
-## Escalation System
+At Level 2 an NPC may leave, argue, pretend not to understand, record the guard, call someone, or move closer. At Level 3 the goal is to deny access **without starting a fight**. Physical contact creates legal, employment, and public-relations consequences.
 
-## Level 0: Observation
-
-The guard watches NPC behavior and decides whether intervention is needed.
-
-Examples:
-
-- Someone taking a photograph from the sidewalk
-- A tourist reading a map
-- A person sitting briefly on the edge of the steps
-- Someone approaching the entrance with a delivery package
-
-The player should avoid interrupting harmless behavior. Unnecessary confrontations reduce the guard’s performance rating.
-
----
-
-## Level 1: Simple Deterrence and Polite Direction
-
-The player can begin with a simple, nonverbal deterrent before speaking. These actions are quick and low-pressure, making them useful when someone is only approaching the steps casually or appears unsure.
-
-Possible actions include:
-
-- Raise an open hand to signal “stop” or “please wait”
-- Make eye contact
-- Point toward the public sidewalk
-- Gesture toward the wristband-check area
-- Shake the head gently when someone approaches a restricted entrance
-
-If the person continues, the player uses a short verbal prompt.
-
-Example commands:
-
-- “Please keep the stairs clear.”
-- “The entrance is for authorized guests only.”
-- “You can’t remain here.”
-- “Please move back to the sidewalk.”
-
-At this stage, most NPCs comply immediately.
-
----
-
-## Level 2: Formal Warning
-
-If the person remains on the steps or continues toward the entrance, the player issues a formal warning.
-
-Possible dialogue:
-
-> “This is private property. You have been asked to leave. Please move away from the entrance now.”
-
-The player may activate a visible security light or body camera. This creates a record of the interaction and can discourage repeat offenders.
-
-At this level, the NPC may:
-
-- Leave
-- Argue
-- Pretend not to understand
-- Start recording the guard
-- Call someone else
-- Move closer to the door
-
----
-
-## Level 3: Blocking and Physical Positioning
-
-The guard moves into a defensive position between the NPC and the building.
-
-Gameplay actions:
-
-- Stand in front of the entrance
-- Point toward the public sidewalk
-- Lock or secure the door
-- Request the person’s reason for entry
-- Keep distance while maintaining a clear escape route
-- Use a flashlight or radio warning tone at night
-
-The player should not automatically shove or strike people. Physical contact creates legal, employment, and public-relations consequences.
-
-This level is about **denying access without creating a fight**.
-
----
-
-## Level 4: Radio for Security Assistance
-
-If the person refuses to leave, attempts to force the door, threatens staff, or repeatedly returns, the player uses the radio.
-
-Possible assistance:
-
-- A second security guard
-- Building management
-- Police dispatch
-- Nearby security personnel
-
-The radio call takes time, so the player must continue monitoring the person while waiting. The player can choose what information to report:
-
-- Location
-- Description
-- Behavior
-- Whether weapons have been seen
-- Whether anyone is in immediate danger
-
-Incorrect or exaggerated reports damage the guard’s credibility.
-
----
-
-## Level 5: Emergency Response
-
-This is reserved for immediate threats, such as:
-
-- A person displaying a weapon
-- An attempted forced entry while people are inside
-- An assault on the guard or another person
-- A serious threat against occupants
-- A violent struggle that cannot be safely disengaged
-
-The player presses and holds a clearly marked **Emergency Radio** button. A confirmation prompt prevents accidental activation.
-
-The call brings an off-duty law-enforcement officer or armed emergency responder to the location. This character has greater authority and can control a dangerous situation, but the call has serious consequences:
-
-- The building may be evacuated
-- The street may be closed
-- The guard’s actions are reviewed
-- The building loses reputation
-- The player may face an investigation if the call was unjustified
-- The officer may use force only when the game’s threat assessment supports it
-
-The officer should not function as a convenient “stronger attack.” Their role is to handle a crisis the player cannot safely manage. In most scenarios, their arrival results in commands, restraint, evacuation, or arrest rather than automatic gunfire.
-
----
+At Level 4 the report matters: location, description, behavior, weapons seen, and immediate danger. Exaggerated reports damage credibility. At Level 5 the call may evacuate the building, close the street, trigger a review, cost reputation, or open an investigation if unjustified. Responders may command, restrain, evacuate, or arrest; they are not a routine stronger attack.
 
 ## NPC Behavior Types
 
-## Tourists
-
-- Take photos
-- Sit on steps
-- Wander toward restricted doors
-- Usually respond well to polite directions
-
-## Street Performers
-
-- May block stairs
-- May become argumentative if moved
-- Can be redirected to a permitted area
-
-## Influencers and Filmmakers
-
-- Film the guard
-- Test boundaries for content
-- May accuse the guard of overreacting
-- Create public-relations risk
-
-## Confused Visitors
-
-- Have appointments or directions
-- May genuinely believe the building is public
-- Reward patient explanations
-
-## Intoxicated Pedestrians
-
-- Move unpredictably
-- May ignore instructions
-- Require additional distance and assistance
-
-## Trespassers
-
-- Repeatedly test entrances
-- Use distractions
-- May return after being told to leave
-
-## Violent Threats
-
-- Rare
-- Escalate quickly
-- Trigger the emergency response system only when their behavior indicates immediate danger
-
-## 51/50s
-
-Crazy Homeless Individuals may be referred to as "51/50s" in the context of the game, indicating a person who may be experiencing a mental health crisis and could pose a potential threat to themselves or others.
-
-- May loiter near entrances
-- Can be unpredictable in behavior
-- Often respond poorly to aggressive confrontation
-- Require careful de-escalation and patience
-
----
+- **Tourists:** take photos, sit on steps, drift toward restricted doors; usually respond well to polite directions.
+- **Street performers:** may block stairs or argue when moved; can be redirected to a permitted area.
+- **Influencers and filmmakers:** film the guard, test boundaries, and create public-relations risk.
+- **Confused visitors:** may have appointments or genuinely believe the building is public; reward patient explanation.
+- **Intoxicated pedestrians:** move unpredictably, ignore instructions, and need extra distance or assistance.
+- **Trespassers:** test entrances, use distractions, and may return after being told to leave.
+- **Violent threats:** rare, escalate quickly, and justify emergency response only when behavior shows immediate danger.
+- **People in mental-health crisis:** may loiter, behave unpredictably, and respond poorly to aggression; require patience and careful de-escalation. The setting may refer to a 51/50 hold, but the game should present the person respectfully, not as an automatic threat.
 
 ## Special Systems
 
-## Reputation Meter
+### Reputation
 
-The player is evaluated on:
+The shift evaluates peaceful resolutions, response time, radio accuracy, unnecessary confrontations, public complaints, property damage, entrance security, and whether assistance was justified. Calling armed help too often scores poorly even when no one is hurt.
 
-- Number of incidents resolved peacefully
-- Response time
-- Accuracy of radio reports
-- Number of unnecessary confrontations
-- Public complaints
-- Property damage
-- Whether the entrance remained secure
+### Evidence and Body Camera
 
-A player who calls armed assistance too often should score poorly, even if no one was injured.
+Interactions are recorded automatically. The body camera is a real state the player can toggle; a formal warning also arms it. The shift review uses the recorded events and evidence to show whether the response was justified.
 
-## Evidence and Body Camera
+### Crowd Reaction
 
-Interactions are automatically recorded. After each shift, the player reviews incidents and sees whether their escalation was justified.
+Nearby pedestrians react to the guard. Calm professionalism attracts little attention; aggression draws a crowd; visible weapons or responders can cause panic. Good de-escalation keeps the boulevard moving.
 
-This encourages players to think before acting.
+### Radio Limits
 
-## Public Crowd Reaction
-
-Nearby pedestrians react to the guard’s behavior:
-
-- Calm professionalism attracts little attention
-- Aggressive behavior creates a crowd
-- Visible weapons or emergency responders cause panic
-- Good de-escalation keeps the boulevard moving normally
-
-## Limited Radio Battery or Cooldown
-
-The emergency radio should not be infinitely available. A call has a cooldown and may require the player to give a short report first.
-
----
+The emergency radio has a cooldown, and the call requires a short report. Assistance takes time to arrive, so the guard must keep monitoring the situation.
 
 ## Shift Structure
 
-Each shift lasts 10–15 minutes.
+- **Early:** harmless tourists, delivery workers, people resting on the steps.
+- **Midday:** heavier crowds, more entry attempts, more filming.
+- **Evening:** lower light, more intoxicated pedestrians and aggressive groups.
+- **Late:** a rare serious incident may test whether the player recognizes a real threat without overreacting to ordinary behavior.
 
-### Early Shift
+## Outcomes
 
-Mostly harmless tourists, delivery workers, and people sitting on the stairs.
+A successful shift keeps the building secure, resolves most incidents without force, keeps public access clear, makes justified emergency calls, avoids bystander injuries, and follows policy.
 
-### Midday
+A poor shift involves excessive force, confronting innocent people, ignoring a real threat, false reports, allowing unauthorized entry, causing a crowd or panic, or behaving recklessly even if the door stayed locked.
 
-Crowds become heavier. More people attempt to enter the building or film interactions.
+## Venues
 
-### Evening
+### Hollywood Boulevard Building
 
-Lighting decreases. Intoxicated pedestrians and aggressive groups become more common.
+The original scenario: a building entrance with steps, sidewalk, street lamps, and a restricted door. Tourists, performers, influencers, confused visitors, intoxicated pedestrians, trespassers, people in crisis, and rare violent threats approach from the boulevard.
 
-### Late Shift
+Authorized people are recognized or present a valid wristband. Wristbands vary by color, pattern, date, and event marking, and may be valid, expired, counterfeit, or missing.
 
-A rare serious incident may occur, testing whether the player recognizes a genuine threat instead of overreacting to ordinary behavior.
+### The Joke Shop
 
----
+A comedy-club entrance. The door person checks IDs, tickets, reservations, guest-list status, and screens guests with a handheld wand under venue policy.
 
-## Win and Loss Conditions
+The wand does **not** identify a weapon automatically. Keys, belts, and phones can trigger false alarms; the player must ask the guest to identify the item and apply procedure. A guest with valid credentials can still require assistance if they threaten staff or patrons.
 
-## Successful Shift
+Typical events:
 
-- Building remains secure
-- Most incidents are resolved without physical force
-- Public access remains clear
-- Emergency calls are justified
-- No bystanders are injured
-- The player follows company policy
+- a busy weekend show creates a long line;
+- a performer arrives through the guest entrance;
+- a guest has a reservation but no ID;
+- a fake or borrowed ID appears;
+- a wand alert comes from keys or a belt;
+- a guest refuses screening but insists on entering;
+- someone tries to follow an authorized person through the door;
+- a late audience member arrives during the performance.
 
-## Poor Performance
+Joke Shop escalation follows the common ladder: direction, explanation, repeat request, refusal, manager/security assistance, emergency only for immediate danger.
 
-- Excessive use of force
-- Repeatedly confronting innocent people
-- Ignoring a real threat
-- Making false radio reports
-- Allowing repeated unauthorized entry
-- Causing a crowd or panic
+### Hollywood Boulevard Late Night TV Studio
 
-A shift can be technically “secure” but still receive a poor rating if the guard behaves recklessly.
+A busy studio entrance with audience members, production staff, performers, guests, deliveries, celebrity arrivals, tourists, influencers, and the same range of street behavior as the building scenario.
 
----
+Staff and guests are recognized or present a wristband, credential, ticket, guest-list confirmation, or other approved marker. The player keeps the steps clear, protects arrivals and equipment, manages filming boundaries, watches for tailgating, and calls for help only when there is immediate danger.
 
-## Venues and Scenarios
+Typical events:
 
-The game should support multiple venues, each with its own access rules, crowd patterns, equipment, and escalation procedures. The core gameplay remains the same: observe, verify access, communicate clearly, and use the lowest effective level of escalation.
+- a crowd gathers for a celebrity arrival;
+- tourists block the entrance for photographs;
+- a performer sets up in the audience queue;
+- an influencer ignores the filming boundary;
+- a confused visitor believes the studio is open;
+- an intoxicated pedestrian approaches the stage door;
+- a trespasser blends into an audience group;
+- an authorized guest arrives without a wristband;
+- someone presents a counterfeit credential;
+- a violent threat appears during a crowded arrival.
 
-## The Joke Shop
+## Presentation and Controls
 
-**The Joke Shop** is a comedy club scenario where the player works as a door person at the entrance. The player is responsible for checking identification, confirming that guests are attending the correct show, and screening guests for weapons with a handheld security wand.
+The game is first-person: WASD and mouse look, a focus cone on nearby people, a billboarded focus circle, `Tab`/mouse-wheel cycling for aim-free selection, and a radial action menu opened with left click or `Space`. `Shift` is precision walk. Gamepad input is supported, and keys/buttons can be remapped in Settings.
 
-### Primary Responsibilities
+The action wheel prioritizes de-escalation: Stop, Look, Point, No, Ask, Inspect, Wand, Warn, Block, Reason, Recognize, Radio. Emergency stays on `R` and is not a wheel slice. `W` is walk, never the wand; `C` is the optional wand shortcut.
 
-- Check each guest’s government-issued ID where required.
-- Confirm that the guest meets the venue’s age requirement.
-- Verify that the ID appears valid and belongs to the person presenting it.
-- Check tickets, reservations, or guest-list status.
-- Use the handheld wand according to venue policy.
-- Direct guests through the entrance without blocking the sidewalk.
-- Refuse entry when a guest has an invalid ID, no valid admission, or a prohibited item.
+The visual direction is readable stylized realism:
 
-### Guest Outcomes
+- **Blender library:** 8 skinned NPC variants, 18 gear pieces, and 20 street/venue props, with baked albedo/normal/AO/ORM maps, a manifest, and procedural fallbacks. `Rig/Head` stays the focus anchor.
+- **Realism pass:** AI-assisted per-phase skyline panoramas, v2 surface tiles with normal maps, wet asphalt at night, a warm day haze, phase-specific sun/exposure/fog, a visible flashlight beam, and denser foliage.
+- **References and QA:** runtime UI art lives in `assets/images/ui/`; reference/art-direction sets live in `docs/screens/designs/` and `docs/screens/concepts/`; captures live in `docs/screenshots/`; realism runs live in `docs/screens/realism/`. `screen_designs.py compare/judge` and `tools/check_screenshots.sh` guard drift.
+- **Storage convention:** see [ADR-0014](docs/adr/0014-runtime-image-root.md). Never overwrite an existing image; new outputs get a new path or `-vN` suffix.
 
-A guest may have:
+The path from the current vertical slice to v1.0.0 — content depth, onboarding, accessibility, platform QA and release readiness — is tracked in [`TODO.md`](TODO.md); this plan stays at the product/design level.
 
-- A valid ID and ticket
-- A valid ID but no ticket or reservation
-- An expired, damaged, or questionable ID
-- An ID that does not match the guest
-- A prohibited item detected by the wand
-- A harmless item that causes a false alarm
-- No ID when identification is required
-
-The player must make decisions based on the venue’s rules and observable evidence, not on a guest’s appearance or attitude. A calm guest with a valid ID should be admitted efficiently, while an aggressive guest with valid credentials may still require assistance if they threaten staff or other patrons.
-
-### Joke Shop Escalation
-
-1. **Nonverbal direction:** Raise a hand, point to the ID-check area, or gesture for the guest to wait.
-2. **Routine explanation:** Explain the ID, ticket, or wand-check requirement.
-3. **Repeat request:** Clearly state what is missing or what must happen before entry.
-4. **Refusal of entry:** Keep the guest outside and direct them away from the entrance.
-5. **Manager or security assistance:** Call for a supervisor or another staff member when a guest argues, refuses screening, or blocks the line.
-6. **Emergency response:** Call emergency services only for an immediate threat, such as a weapon, assault, or serious attempt to force entry.
-
-The handheld wand should not automatically identify an item as a weapon. The player must interpret the alert, ask the guest to identify the item, and follow venue procedure. The goal is to create a believable screening challenge while keeping the emphasis on communication and proportionate responses.
-
-### Scenario Events
-
-- A busy weekend comedy show creates a long line.
-- A performer arrives through the guest entrance and must be recognized or verified.
-- A guest forgets their ID but appears on the reservation list.
-- A fake or borrowed ID is presented.
-- A wand alert comes from keys, a belt buckle, or a phone.
-- A guest refuses the screening but insists on entering.
-- A disruptive guest attempts to follow another person through the door.
-- A late-arriving audience member tries to enter during a performance.
-
-## Hollywood Boulevard Late Night TV Studio
-
-This scenario takes place outside a late-night television studio on Hollywood Boulevard. The guard manages the front steps, studio entrance, guest arrivals, deliveries, audience members, and the public crowd gathered around the building.
-
-The studio encounters all of the NPC types described in the game plan:
-
-- **Tourists** stopping to take photos or watch arrivals
-- **Street performers** occupying the steps or performing near the entrance
-- **Influencers and filmmakers** recording the guard, guests, or celebrity arrivals
-- **Confused visitors** looking for the wrong entrance or trying to attend a show without understanding the access rules
-- **Intoxicated pedestrians** approaching the entrance or disrupting the crowd
-- **Trespassers** testing the doors, trying to follow authorized guests, or returning after being directed away
-- **Violent threats**, which are rare but require careful recognition and emergency escalation
-
-The studio also has authorized guests and staff. They must either be recognized by the guard or present a valid wristband, credential, guest-list confirmation, or other approved access marker. The player must check these credentials without holding up the audience line or allowing unauthorized people to enter.
-
-### Studio Responsibilities
-
-- Keep the front steps and entrance clear.
-- Direct tourists and performers away from restricted areas.
-- Check wristbands, credentials, tickets, or guest-list status.
-- Admit authorized staff, performers, guests, and audience members.
-- Manage influencers and filmmakers without unnecessarily obstructing lawful filming.
-- Protect celebrity arrivals and production equipment from crowding.
-- Coordinate with studio staff, production assistants, and additional security guards.
-- Watch for attempts to follow authorized people through the entrance.
-- Call for emergency assistance only when there is an immediate threat.
-
-### Studio Scenario Events
-
-- A crowd gathers to watch a celebrity arrive.
-- Tourists stop on the steps and block the entrance for photographs.
-- A street performer sets up in front of the audience queue.
-- An influencer repeatedly ignores the restricted filming boundary.
-- A confused visitor believes the studio is open to the public.
-- An intoxicated pedestrian wanders toward the stage door.
-- A trespasser tries to blend into an audience group.
-- An authorized guest arrives without their wristband and must be verified another way.
-- Someone presents a counterfeit wristband or credential.
-- A violent threat appears during a crowded arrival, requiring the player to protect the entrance while calling for assistance.
-
----
-
-## Visual Quality Direction
-
-The game prioritizes readable, well-lit, low-poly presentation over realism (GL Compatibility
-renderer). The v0.6.0 visual pass moves presentation to a **Blender-authored asset library**:
-skinned NPC character variants, head/back/chest/hand gear, and street/venue props, all carrying
-baked albedo/normal/AO/ORM maps. A generator (`tools/blender_assets.py`) and manifest
-(`assets/models/blender/manifest.json`) keep the assets reproducible; the game selects variants
-by NPC role/outfit and keeps the procedural rig and primitive props as offline fallbacks. The
-existing AI tools remain the source of art direction for fabric textures, palettes, and the
-screen-design compare/judge gate.
-
-The library targets 8 character variants (casual, jacket, coat, vest, dress, hoodie, firefighter,
-guard), 18 gear pieces, and 20 props — including replacements for the current generated street
-furniture, lamps, trees, doors, marquee, and a venue car. Integration must preserve the
-`Rig/Head` focus anchor, seed-driven outfit determinism, collider/navigation footprints, and the
-frame budget measured by `smoke_npc_budget.gd`. See
-[`docs/plan-graphics-v0.6.md`](docs/plan-graphics-v0.6.md) and
-[ADR-0013](docs/adr/0013-blender-authored-npc-characters.md).
-
-### Realism pass
-
-The target look is the realistic 3D-game frames in `docs/screens/designs/` and the larger
-example set in `docs/screens/concepts/`: hazy, layered city depth, believable materials, and
-warm practical lights at night. Readability still comes first. Silhouettes, the focus ring and
-the HUD must stay clear, and the GL Compatibility renderer stays.
-
-- **Backgrounds.** The flat, black-box skyline strip is retired in favour of AI-generated
-  panoramic skylines (Hollywood mid-rises, palms, hills) for day, dusk and night. Each one is a
-  transparent-sky 4:1 strip that tiles horizontally on the existing backdrop ring, and the night
-  variant has lit windows.
-- **Textures.** Higher-detail seamless 1024² tiles with derived normal maps for brick, granite,
-  sidewalk pavers, asphalt (dry and wet), steps, awning canvas and stucco, at the current UV
-  scales.
-- **Process.** `tools/scene_concepts.py` generates (never overwriting existing images),
-  processes, audits and judges. `src/test/capture_realism.gd` captures the same camera shots
-  with the current and the candidate assets, swapped at runtime, so a candidate is compared
-  before any game code changes. Candidates are adopted only when the realism report (Pillow
-  detail metrics + vision-model realism scores) improves and `screen_designs.py judge` shows no
-  new `diff`.
-- **Storage.** Raw AI output: `assets/textures/ai/v2/raw/` (local, gitignored). Game-ready
-  candidates: `assets/textures/ai/game_ready/v2/`. Scene references: `docs/screens/concepts/`.
-  Trial captures and reports: `docs/screens/realism/<run>/`.
-- **First result (2026-11-01).** Swapping in the v2 skyline and tiles raised the judge's mean
-  backdrop score from 2.6 to 4.0 and texture detail from 1.2 to ~1.7. Overall realism stayed at
-  ~2/10; the limits were lighting and exposure, flat facades and blob foliage, not textures.
-- **Adopted (2026-11-01).** The v2 picks are now the runtime skyline and surface set, the phase
-  lighting was retuned (exposure, darker dusk/late, practical lights, wet asphalt at night), the
-  backdrop is a fog-free 90 m panorama ring per phase, the facade gained plinth/string
-  courses/cornice/pilasters/glazing bars, and the library trees and shrubs are denser. Judge
-  scores on the like-for-like shots rose on every sub-score (overall 0.8 → 1.0, backdrop
-  0.6 → 1.6) with the metric gap down 0.444 → 0.348
-  (`docs/screens/realism/2026-11-01-adopt/`). The remaining gap to the concepts is the low-poly
-  character and prop fidelity, a visible flashlight beam at night, and the entrance still being
-  ~20 % brighter than the concept (`TODO.md` → Realism follow-ups).
-
-The scenario should test the player’s ability to distinguish ordinary Hollywood Boulevard activity from a genuine security problem. The best solution is usually a simple gesture, clear direction, or credential check rather than immediate escalation.
-
-Future venues can reuse this structure while changing the rules, equipment, staff roles, and types of access decisions.
+Primary decisions: [ADR-0007](docs/adr/0007-locomotion-and-input-layers.md), [ADR-0008](docs/adr/0008-cone-focus-and-head-ring.md), [ADR-0009](docs/adr/0009-radial-action-menu.md), [ADR-0010](docs/adr/0010-procedural-npc-presentation.md), [ADR-0011](docs/adr/0011-aim-free-selection-and-precision-walk.md), [ADR-0012](docs/adr/0012-surface-materials-and-generated-props.md), [ADR-0013](docs/adr/0013-blender-authored-npc-characters.md).
 
 ## Tech Stack
 
-## Engine: Godot 4
+- **Engine:** Godot 4.7.2, GL Compatibility renderer (Web parity); optional Forward+ Desktop HQ build.
+- **Language:** GDScript.
+- **Architecture:** venue-driven simulation; shared systems plus `Resource`-based scenario data.
+- **Navigation:** `NavigationRegion3D` / `NavigationAgent3D`.
+- **NPC behavior:** lightweight custom finite state machines driven by `NpcProfile` resources.
+- **UI/audio:** Godot `Control` nodes, themes, procedural audio, and JSON-backed localized strings.
+- **Persistence:** JSON in `user://` for settings and shift history.
+- **Testing:** custom headless runner (`src/test/test_runner.gd`); GUT was evaluated and not adopted. Python tooling tests cover the asset/screenshot pipelines.
+- **Source control/CI:** git on Gitea; `.gitea/workflows/build.yml` runs headless checks and builds/publishes releases on tags.
+- **Targets:** Windows, Linux, macOS, and Web. Release artifacts include portables, an NSIS installer, an AppImage, a Web zip, and an optional Desktop HQ zip (Forward+ volumetric lighting; Vulkan required).
 
-The game is built with the Godot Engine 4.x editor. Godot was chosen for its free and open-source license, built-in 3D rendering, navigation, animation, audio, and UI systems, and its low weight for fast prototyping and iteration.
+## Versioning and Delivery
 
-## Language: GDScript
-
-Gameplay logic is written in GDScript. It is tightly integrated with the engine, fast to iterate on, and avoids an external build toolchain for the prototype phase.
-
-## Architecture Mapping
-
-The venue-driven architecture maps onto Godot as follows:
-
-- **Nodes and scenes:** Each major system (`ShiftCoordinator`, `NPCController`, `InteractionSystem`, `AccessVerifier`, `EscalationManager`, `RadioSystem`, `IncidentRecorder`, `ReputationEvaluator`, `CrowdSystem`, `ShiftReview`) is a Godot node or scene.
-- **Scenarios as resources:** `VenueScenario` and content such as `NpcProfile`, `Dialogue`, `EventPool`, and `AccessPolicy` are defined as custom Godot `Resource` types so venue content is data-driven and inspectable in the editor.
-- **Navigation:** `NavigationRegion3D` and `NavigationAgent3D` drive NPC and player movement.
-- **NPC behavior:** Lightweight custom finite state machines built on the `NPCController` node, with behavior traits coming from `NpcProfile` resources.
-- **UI:** Godot `Control` nodes and themes for prompts, access inspection, radio reports, dialogue, timers, and the shift review screen.
-- **Audio:** Godot audio buses and `AudioStreamPlayer` nodes for voices, crowd noise, radio, and environment sound.
-
-## Content and Data
-
-- Scenario and entity configuration uses typed Godot `Resource` files (`.tres`), created either in the editor or via scripts.
-- Localized dialogue and text are stored in JSON files when they need to be editable outside the editor.
-- Save data and shift results use JSON in Godot's `user://` directory.
-
-## Testing
-
-- Unit and scenario tests use a lightweight custom headless runner
-  (`src/test/test_runner.gd`). GUT was evaluated but requires the editor plugin.
-- Tests run in headless mode so rules, access verification, escalation, and scoring can be verified without rendering or user input.
-
-## Version Control and CI
-
-- Source is tracked with git.
-- Gitea Actions (`.gitea/workflows/build.yml`) runs headless Godot tests on push/PR and exports
-  Linux/Windows/macOS desktop builds plus the NSIS installer and AppImage on tags.
-
-## Planned Commands
-
-The following commands apply once the Godot project is scaffolded:
-
-- Open the editor: `godot --editor --path .`
-- Run the game: `godot --path .`
-- Run tests headlessly: `godot --headless --path . res://src/test/test_runner.tscn`
-
-## Export Targets
-
-Desktop is the first target: Windows, Linux, and macOS. A Web export now ships as well
-(non-threaded, static hosting); it is published with each release as a zip.
-
-## Player Control, Focus, and Action Menu (next pass)
-
-The prototype already walks and looks in first person, but the control scheme fights itself and targeting is a hairline. This pass replaces that with three things that belong together: solid locomotion, a visible focus on a person, and a round action menu for what to do with them.
-
-Decisions: [ADR-0007](docs/adr/0007-locomotion-and-input-layers.md) locomotion and input layers, [ADR-0008](docs/adr/0008-cone-focus-and-head-ring.md) cone focus and focus circle, [ADR-0009](docs/adr/0009-radial-action-menu.md) radial action menu, [ADR-0010](docs/adr/0010-procedural-npc-presentation.md) procedural NPC presentation.
-
-### What is wrong today
-
-- `W` is walk-forward in the input map and wand-screening in `GameManager._handle_key`. Walking at someone with a wand venue fires the wand.
-- `A` / `D` are strafe and also allow/deny during inspection.
-- `Q` is polite direction and is also bound as `cancel`.
-- Focus is an 8 m physics ray from the camera. Missing a capsule by a few pixels clears the target. There is no mark in the world that you have someone.
-- NPC bodies are colored capsules with props. They read as markers, not people.
-- Actions live on number keys `1`–`6` plus `Q` / `E` / `W` / `R`. That is a cheat-sheet, not a verb you pick while looking at a person.
-- `Esc` only toggles mouse capture. There is no "I changed my mind" for an action in progress.
-
-### Movement and look
-
-Keep first-person WASD + mouse look. Fix the feel and stop stealing those keys.
-
-- Body yaw from mouse X, head pitch from mouse Y, pitch clamped (already `-80` to `80`).
-- Move relative to body yaw only (already). Add short acceleration / deceleration so starts and stops are not instant.
-- Gravity only when `not is_on_floor()`; `floor_snap_length` so the steps work.
-- Mouse look runs only while `MOUSE_MODE_CAPTURED` and no modal UI is open (radial, inspection, wand, radio, shift review).
-- Walk speed stays around 3.2 m/s. No sprint, no crouch in this pass.
-- While the radial is open: freeze look and WASD so `A` / `D` can cycle the menu. Recapture the mouse when the menu closes.
-- `Esc` with a modal open closes that modal and does nothing else. `Esc` with nothing open keeps the current capture/release toggle.
-
-Equipment stays on its own keys because it is not about a person: `G` flashlight, `L` door lock, `Tab` cycle nearby people, `V` venue (debug), `F` debug overlay. `R` stays the dedicated emergency radio (hold-to-confirm on the existing panel). Those do not go on the wheel.
-
-Wand leaves `W`. It is a slice on the wheel (greyed when the venue has no wand) and an optional extra key that is not WASD, suggested `C`.
-
-### Focus area
-
-Replace the hairline ray as the primary picker.
-
-- A **focus cone** in front of the camera: people within about 10 m whose head projects inside a screen-space circle around the crosshair (about 90 px / 10 degrees).
-- If several heads sit in the circle, pick the one closest to the center, then the nearer one if tied.
-- The person must be in front (dot with camera forward > 0) and not fully occluded by the building. A short ray to the head is enough for occlusion.
-- `Tab` still cycles people inside 12 m as the aim-free path. Cycling sets the same focused person the cone would.
-- Clearing: look away until the head leaves the circle for a few frames (small grace so a bob does not drop them), or they walk out of range.
-
-### Focus circle
-
-When a person is in focus, draw a blue, semi-transparent circle in front of their face.
-
-- Attach to the avatar `Head` node, just in front of the face, billboarded to the camera so it stays a circle on screen.
-- Slow spin is fine; no ping-pong scale spam.
-- Idle focus: blue, semi-transparent, modest size. Radial open on that person: brighter, slightly larger.
-- Optional small name under the circle (`display_name` only, not the archetype cheat `Violent Threat` in the world). The existing HUD target line can keep the archetype for the prototype.
-- One circle at a time. Everyone else has none.
-
-Implementation sketch: a thin unshaded `MeshInstance3D` circle (flat disc) in front of the face on the avatar, toggled from `GuardController` / `GameManager` when focus changes. Screen-space fallback (unproject head, draw a `Control` circle) is acceptable if the 3D circle z-fights on hats.
-
-### Round action HUD
-
-A doughnut / pie menu centered on the screen, opened on the focused person.
-
-**Open**
-
-- Left mouse button, or `Space`, while someone is in focus and no other modal is open.
-- If nobody is in focus, log the existing "aim first" line and do not open.
-- The click that opens the menu must not also pick a slice.
-
-**While open**
-
-- Mouse becomes visible. Look and walk freeze.
-- Center of the doughnut shows the focused person's `display_name`.
-- Slices, clockwise from the top, de-escalation first:
-  1. Raise hand (stop / wait)
-  2. Point away
-  3. Head shake
-  4. Polite direction (old `Q`)
-  5. Inspect access (old `E`)
-  6. Wand (grey if the venue has no wand)
-  7. Formal warning
-  8. Block
-  9. Radio assist
-- Emergency is **not** on the wheel (`R` only).
-- Highlight follows the mouse angle when the cursor is over the ring. `Left` / `Right` or `A` / `D` step the highlight. Wrap around.
-
-**Confirm**
-
-- Click a slice: that action runs, menu closes, mouse recaptured.
-- `Space` while a slice is highlighted: same.
-- Inspect or wand: close the wheel, then open the existing inspect / wand panel. Allow / deny on that panel stay `A` / `D` (walk is frozen only while the wheel is up; once the inspect panel is open, WASD can move again, so allow/deny on `A` / `D` remains a press handler and must ignore repeats / echo, which it already does). Safer: keep walk frozen for inspect/wand too, until the panel closes. Prefer freeze until the whole interaction ends.
-- Radio assist: close the wheel, open the existing radio panel.
-
-**Cancel**
-
-- `Esc` or right mouse button: hide the menu, no action, no recorder event, recapture mouse.
-- Focus and the focus circle stay as they were.
-
-Number keys `1`–`6` may remain as shortcuts that skip the wheel so a smoke-test script still works. They must not fire while the wheel is open (the wheel owns `A` / `D` / `Space`). Document both in the README.
-
-### NPC display
-
-Stay on the procedural capsule rig (no Mixamo / GLB dependency this pass). Make them read as people at conversation distance.
-
-- Neck between torso and head; shoes; simple hair cap (color from seed); two dark eye spheres on the face so a head has a front.
-- Keep archetype props (camera, box, hat, sign, bag). Keep height / brightness variation from the visual seed.
-- Collision capsule matches the scaled height so the focus ray / cone hits the body you see.
-- `Head` stays a named node other systems can find (`get_node("Rig/Head")`) for the ring and the cone.
-- Walk bob and the "look at the guard when noticed" cue stay.
-- Do not put the internal type name (`Trespasser`, `Violent Threat`) on the body. The player should judge from clothes, props, and behavior. The debug overlay (`F`) can still print the type.
-
-AI textures in `assets/textures/ai/` stay out of this pass unless a specific map (shirt, hair) is already the right size.
-
-### Input map (target)
-
-| Action | Bind |
-| --- | --- |
-| Walk | WASD / arrows (arrows **do not** walk while the wheel is open; they step the highlight) |
-| Look | Mouse, captured |
-| Open / confirm action menu | LMB, `Space` |
-| Cancel menu | RMB, `Esc` |
-| Step highlight | `A` / `D`, left / right arrows |
-| Emergency radio | `R` |
-| Flashlight | `G` |
-| Door lock | `L` |
-| Cycle nearby people | `Tab` |
-| Wand shortcut | `C` (not `W`) |
-| Inspect shortcut | `E` still allowed when the wheel is closed |
-
-### Files this pass is expected to touch
-
-- `src/game/guard_controller.gd` — cone focus, no look while modal, accel, floor snap.
-- `src/game/npc_avatar.gd` — face / hair / neck, head marker, ring toggle.
-- `src/game/ui/action_radial.gd` — new Control, `_draw` doughnut, slice pick.
-- `src/game/ui/hud.gd` — host the radial; stop teaching number-key verbs as the only path.
-- `src/game/game_manager.gd` — input routing, freeze flags, open/confirm/cancel.
-- `project.godot` — input map.
-- `src/core/strings.gd` — controls line, aim-first, no new tone-of-voice.
-- `src/test/tests/test_focus_and_radial.gd` — cone pick, wrap, cancel emits nothing, `W` is not wand.
-- README controls table and smoke checklist.
-
-## Rendering, Models, and Selection (v0.3.0 pass)
-
-Decisions: [ADR-0011](docs/adr/0011-aim-free-selection-and-precision-walk.md) aim-free selection and precision walk, [ADR-0012](docs/adr/0012-surface-materials-and-generated-props.md) surface materials and generated props.
-
-The blockout look and the aim-first selection model were the two biggest gaps left by the control pass. This pass closes them without changing the game's rules.
-
-**Look.** Surfaces get real profiles instead of stock materials: brick is rough and finely tiled, concrete is rougher still, asphalt is smoother and damp-looking, glass is smooth and slightly metallic. The environment gains ACES tonemapping, soft glow, aerial fog and a mild grade, all driven by the same per-phase configuration that already moves the sun and sky. The facade gains framed windows that light up after dark, a stone base course, door trim and handles. Street furniture becomes real geometry: bollards, benches, bins, planters, newspaper boxes and a hydrant, built as `.glb` props by `tools/model_pipeline.py` with a procedural fallback. NPCs get per-role clothing palettes, small role accessories (cap, hood, backpack, sunglasses, lanyard), hands, shoes, and an arm/leg walk swing. The rule stays: the player judges people from clothes, props and behaviour, never from an archetype label.
-
-**Models.** Prop meshes are deterministic primitives, so the build works offline. An image model can supply the per-prop colour palette from a concept sheet; that is the only AI influence on geometry, and it is optional. Colours are converted from sRGB to linear before they reach glTF, because glTF factors are linear.
-
-**Selection.** The focus cone ranks heads by angle from the crosshair then distance. `Tab` and the mouse wheel cycle nearby people nearest-first and pin the choice, so aim-free play works. Right click clears focus and briefly suppresses re-acquisition. Holding `Shift` walks at half speed for close work at the door. Escape keeps its single meaning (close the top panel, otherwise pause).
+`config/version` in `project.godot` is the single version source (currently `0.9.1`). Releases are tagged `v<version>`; the CI pipeline builds and publishes the standard artifacts plus the optional Desktop HQ zip. Version bumps follow [Semantic Versioning](https://semver.org/). See [`docs/RELEASING.md`](docs/RELEASING.md) and [`README.md`](README.md) for commands.
 
 ## Design Direction
 
 The game should feel like a tense workplace simulation with occasional crisis moments. The most satisfying outcome is not overpowering an NPC; it is recognizing the situation early and resolving it calmly.
 
-A useful guiding rule:
-
 > **The player wins by choosing the lowest level of escalation that keeps everyone safe.**
+
+## Future Ideas
+
+- A rare Bob Dobbs cameo (Easter-egg appearance; placement note in `MEMORY.md`).
+- Specific unusual NPC behaviors, such as slapping their own face, using hands as scissors, or interacting with props unexpectedly.
+- Live 3D body-camera replay; additional venues or seasonal events; real voice/dialogue audio; an image-to-mesh prop pipeline.

README.md

@@ -15,9 +15,11 @@ The central design goal is simple:
 | ![Late night: street lamps lit, marquee glowing, dark Hollywood Boulevard](docs/screenshots/05-late-night-avenue.png) | ![Night shift: guard flashlight cutting through the dark](docs/screenshots/06-night-flashlight.png) |
 | ![Wand screening at The Joke Shop: false alarm on keys](docs/screenshots/07-wand-screening.png) | ![Escalation HUD at L3 with body camera armed and reaction log](docs/screenshots/08-escalation-hud.png) |
 | ![Body-camera timeline: formal warning, body camera on, blocking](docs/screenshots/09-body-camera-timeline.png) | ![Prop gallery: the six generated street-furniture models on a studio backdrop](docs/screenshots/10-prop-gallery.png) |
-| ![Precision walk at the venue steps with the HUD chip visible](docs/screenshots/11-precision-walk.png) | |
+| ![Precision walk at the venue steps with the HUD chip visible](docs/screenshots/11-precision-walk.png) | ![The Joke Shop: a narrow brick alley with shuttered windows, a warm wall lantern and a dumpster](docs/screenshots/12-joke-shop.png) |
+| ![Late-night TV studio arrival: stone facade, bulb canopy, black car and barriers](docs/screenshots/13-studio-arrival.png) | |
 
-*Screenshots are generated by [`src/test/capture_screenshots.gd`](src/test/capture_screenshots.gd) and [`src/test/capture_prop_gallery.gd`](src/test/capture_prop_gallery.gd) from the current build — day, late-night, wand screening, escalation, shift-review timeline, precision walk, and the prop lineup.*
+*Screenshots are generated by [`src/test/capture_screenshots.gd`](src/test/capture_screenshots.gd) and [`src/test/capture_prop_gallery.gd`](src/test/capture_prop_gallery.gd) from the current build — day, late-night, wand screening, escalation, shift-review timeline,
+precision walk, the Joke Shop alley, the TV Studio arrival, and the prop lineup.*
 
 ## ⬇️ Downloads
 
@@ -29,573 +31,100 @@ The central design goal is simple:
 | **Linux — portable** | [`gig-line-linux-<ver>.x86_64`](https://git.allucanget.biz/zwitschi/security-game/releases) · 64-bit, `chmod +x` and run |
 | **macOS** | [`gig-line-macos-<ver>.zip`](https://git.allucanget.biz/zwitschi/security-game/releases) · unsigned build, quarantine note below |
 | **Web (browser)** | [`gig-line-web-<ver>.zip`](https://git.allucanget.biz/zwitschi/security-game/releases) · unzip and serve the folder from any static host (no special headers) |
+| **Desktop HQ** | [`gig-line-desktop-hq-<ver>.zip`](https://git.allucanget.biz/zwitschi/security-game/releases) · optional Forward+ build with volumetric fog/SDFGI/flashlight; requires a Vulkan-capable GPU/driver |
 
 **All releases:** <https://git.allucanget.biz/zwitschi/security-game/releases>
 
 > Downloads are public (no sign-in required) since the host's instance-wide
 > `REQUIRE_SIGNIN_VIEW` was disabled on 2026-10-31.
 >
-> **Latest: v0.6.0** — Blender-authored character/gear/prop library with baked AO, higher-resolution environment textures, and phase-driven library props.
+> **Latest: v0.9.1** — unified Godot 4.7.2 CI/release environment with cached
+> Godot binaries/templates, plus v0.9.0's production-quality and v0.8
+> tutorial/campaign/resume work.
 > Releases are built automatically when a `vX.Y.Z` tag is pushed
 > (see [`docs/RELEASING.md`](docs/RELEASING.md)); manual builds use
 > `./tools/build_releases.sh`. Installer/AppImage packaging runs in the same pipeline
 > (NSIS + appimagetool) and uploads with the portable binaries.
 >
-> Note: on this host, downloading release files currently requires sign-in;
-> the page and tag URLs are public.
->
 > macOS builds are unsigned: right-click → Open, or clear the quarantine with
 > `xattr -dr com.apple.quarantine gig-line-macos.zip`. Build instructions and
 > the release pipeline live in [`docs/RELEASING.md`](docs/RELEASING.md).
 
 If you are here to develop or test locally instead of downloading, jump to
-[Run and Test](#run-and-test) below.
+[Setup and Run](#setup-and-run) below.
 
-The project is under active development. The design and architecture are documented, and a playable prototype vertical slice exists (Godot 4.3 + GDScript): a procedural Hollywood Boulevard entrance, a first-person guard, simulated NPCs with intents and reactions, the six-level escalation model, access inspection and admission decisions, radio calls with credibility checks, reputation, crowd mood, and an end-of-shift review.
+The project is under active development. The design and architecture are documented, and a playable prototype vertical slice exists (Godot 4 + GDScript): a procedural Hollywood Boulevard entrance, a first-person guard, simulated NPCs with intents and reactions, the six-level escalation model, access inspection and admission decisions, radio calls with credibility checks, reputation, crowd mood, and an end-of-shift review.
 
 ## Game Overview
 
-A typical shift lasts 10–15 minutes. The player:
-
-1. Watches the entrance, steps, queue, and surrounding sidewalk.
-2. Determines why each person is approaching.
-3. Uses simple gestures or polite directions first.
-4. Verifies authorized access using recognition, wristbands, credentials, tickets, or guest lists.
-5. Escalates only when a person refuses directions, attempts unauthorized entry, or presents a genuine threat.
-6. Records the incident through body-camera and radio systems.
-7. Finishes the shift with a performance review based on safety, judgment, and professionalism.
-
-The game rewards calm resolutions rather than aggressive behavior. Emergency assistance and armed responders are rare last-resort systems with meaningful consequences.
-
-## Planned Venues
-
-### Hollywood Boulevard Building
-
-The original scenario places the guard at the top of the steps outside a fictional building. Tourists, street performers, influencers, confused visitors, intoxicated pedestrians, trespassers, people experiencing a mental-health crisis, and rare violent threats may approach the entrance.
-
-Authorized people must either be recognized by the guard or present a valid wristband. Wristbands can have different colors, patterns, dates, or event markings. They may be valid, expired, counterfeit, or missing.
-
-### The Joke Shop
-
-The Joke Shop is a comedy-club scenario. The door person checks IDs, tickets, reservations, and guest-list status, then uses a handheld security wand according to venue policy. The player must interpret wand alerts rather than treating every alert as proof of a weapon; keys, belts, phones, and other harmless objects can trigger false alarms.
-
-### Hollywood Boulevard Late Night TV Studio
-
-This scenario combines the previously defined NPC types with a busy television-studio entrance. The player manages audience members, production staff, performers, guests, deliveries, celebrity arrivals, tourists, street performers, influencers, confused visitors, intoxicated pedestrians, trespassers, people experiencing a mental-health crisis, and rare violent threats.
-
-The studio uses wristbands, credentials, tickets, guest-list confirmation, and personal recognition to authorize entry. Crowd control, filming boundaries, following authorized guests through the door, and counterfeit credentials are key events.
-
-## Escalation Model
-
-The common escalation model has six levels:
-
-0. **Observation** — Decide whether intervention is necessary.
-1. **Simple deterrence and polite direction** — Raise an open hand, make eye contact, point toward the sidewalk or check-in area, shake the head, or give a short instruction.
-2. **Formal warning** — Clearly explain the rule and request compliance.
-3. **Blocking and physical positioning** — Secure the entrance, maintain distance, preserve an escape route, and deny access without starting a fight.
-4. **Radio for security assistance** — Request a supervisor, second guard, building management, or other appropriate support.
-5. **Emergency response** — Hold the emergency-radio button and confirm only when there is an immediate threat, such as a weapon, assault, forced entry, or serious threat to occupants.
-
-An off-duty law-enforcement officer or armed emergency responder may arrive during a valid emergency. This character is not intended to be a routine stronger attack. Their role is crisis control, evacuation, restraint, arrest, or other appropriate intervention, with force governed by the situation and meaningful consequences for unjustified calls.
-
-## Core Systems
-
-- **NPC behavior:** NPCs have different motivations, temperaments, compliance levels, and reactions to the player’s approach.
-- **Access verification:** Recognition, wristbands, IDs, tickets, credentials, and guest lists determine who may enter.
-- **Nonverbal deterrence:** Small actions such as raising a hand can resolve low-risk situations without dialogue or force.
-- **Dialogue:** Polite directions and warnings affect outcomes; simple gestures can resolve low-risk situations without dialogue.
-- **Escalation:** The player chooses the lowest effective response.
-- **Radio assistance:** Calls require useful information and may take time to arrive.
-- **Evidence:** Body-camera records support shift review and accountability.
-- **Crowd reaction:** Aggressive behavior, visible weapons, and emergency response can create panic or attract a crowd.
-- **Reputation:** Peaceful resolutions, accurate reports, low property damage, and justified calls improve performance; unnecessary confrontations and false reports reduce it.
-- **Shift review:** The player receives feedback on access decisions, escalation choices, public complaints, injuries, and security outcomes.
-
-## Architecture Overview
-
-The planned solution uses a venue-driven simulation architecture. Venue configuration supplies rules, access types, NPC pools, equipment, events, and escalation policies. Shared simulation systems provide movement, perception, interactions, dialogue, access verification, escalation, radio calls, crowds, reputation, evidence, and shift review.
-
-```text
-Venue Scenario / Rules
-          |
-          v
-   Shift Coordinator -----> Event Scheduler
-          |                         |
-          v                         v
-   NPC Simulation <---------- Interaction System
-          |                         |
-          v                         v
-   Access Verification ----> Escalation / Response
-          |                         |
-          +-------------> Reputation / Evidence
-                                      |
-                                      v
-                                Shift Review
-```
-
-The architecture maps onto Godot 4 nodes, scenes, and custom resources as described in [Tech Stack](#tech-stack). See the full arc42-style outline in [`docs/architecture.md`](docs/architecture.md) and the decisions in [`docs/adr/`](docs/adr/).
-
-## Tech Stack
-
-- **Engine:** Godot Engine 4.x
-- **Language:** GDScript
-- **Architecture:** Venue-driven simulation using nodes, scenes, and custom `Resource`-based scenario data
-- **Navigation:** `NavigationRegion3D` and `NavigationAgent3D`
-- **NPC behavior:** Custom lightweight finite state machines driven by `NpcProfile` resources
-- **UI and audio:** Godot `Control` nodes, themes, audio buses, and `AudioStreamPlayer` nodes
-- **Art assets:** authored PNGs and the in-game generated set in `assets/textures/ai/game_ready/`; street-furniture models in `assets/models/generated/` build from `tools/model_pipeline.py`; structural geometry stays procedural (`WorldBuilder`). The legacy `tools/generate_textures.py --ai` batch remains available.
-- **Asset tooling:** `tools/asset_pipeline.py` generates role-aware assets through OpenRouter (`--variants N` produces alternative images) and provides crop, resize, seamless-tile, and image-audit commands, including gameplay screenshot checks. `tools/model_pipeline.py` builds and audits the street-prop `.glb` models; `tools/npc_pipeline.py` builds and audits the skinned NPC base model.
-- **Testing:** GUT (Godot Unit Test) in headless mode
-- **Source control:** git on a Gitea host with Gitea Actions (`.gitea/workflows/build.yml`) for headless tests and desktop release builds
-- **Targets:** Windows, Linux, and macOS desktop first; web later
-
-### Image Asset Tools
-
-Install the Pillow dependency used by the existing texture generator and the asset tools:
-
-```bash
-python3 -m pip install -r requirements-tools.txt
-```
-
-Generate a role-sized image (generation requires `OPENROUTER_API_KEY`):
-
-```bash
-python3 tools/asset_pipeline.py generate --prompt "weathered red brick" --role tile --output assets/textures/brick_extra.png
-```
-
-Generated images are resized to the selected role profile. Non-square requests use
-the validated `openai/gpt-5-image-mini` source ratio and crop to the final role dimensions.
-Transparent glyphs can be recolored while preserving their alpha mask with
-`--foreground '#ffffff'`.
-
-Crop uses the image center by default; `--x` and `--y` select an explicit crop origin. Resize defaults to aspect-preserving `contain`; use `--fit cover` to crop or `--fit stretch` to distort to the exact dimensions.
-
-```bash
-python3 tools/asset_pipeline.py crop assets/textures/source.png assets/textures/crop.png --width 256 --height 128
-python3 tools/asset_pipeline.py resize assets/textures/source.png assets/images/scenes/scene.png --width 1920 --height 1080 --fit cover
-python3 tools/asset_pipeline.py seamless assets/textures/rough_tile.png assets/textures/tile.png
-```
-
-Audit accepts image files or directories. `--role auto` infers common roles from paths and filenames; explicit roles include `tile`, `texture`, `icon`, `card`, `banner`, `backdrop`, `background`, `overlay`, `app_icon`, and `screenshot`.
-
-```bash
-python3 tools/asset_pipeline.py audit assets/textures
-python3 tools/asset_pipeline.py audit assets/images/scenes --role background --json
-python3 -m unittest discover -s tools -p 'test_*.py'
-```
-
-The audit classifies measurable fit issues as `good` or `bad` based on role-specific dimensions, aspect ratio, alpha requirements, and tile-edge continuity. It lists perspective/projection as a visual review item because image semantics cannot be judged reliably by these deterministic checks.
-
-### Prop models
-
-Street furniture (bollards, benches, bins, planters, newspaper boxes, a hydrant)
-is real 3D geometry generated by `tools/model_pipeline.py` and written to
-`assets/models/generated/*.glb`. Godot imports each file as a `PackedScene`, and
-`WorldBuilder` instantiates it with a procedural fallback when the model or its
-import is missing, so the world still builds on a fresh checkout.
-
-```bash
-# Print the catalogue (parts, triangle count, whether a model/concept exists)
-python3 tools/model_pipeline.py list
-
-# Rebuild the models (deterministic, offline) and validate them
-python3 tools/model_pipeline.py build
-python3 tools/model_pipeline.py audit
-
-# Optional: an image model supplies the colour palette per prop
-# (requires OPENROUTER_API_KEY; the repo .env is read automatically)
-python3 tools/model_pipeline.py concept
-python3 tools/model_pipeline.py concept --only bench --force
-```
-
-Each prop is a small list of boxes and cylinders, so `build` needs no network and
-the output is byte-identical between runs. `concept` asks an image model for a
-studio-style reference; `dominant_colors` and `assign_roles` then map that image's
-colours onto material roles (darkest → metal, warm saturated → wood, light grey →
-stone, green → foliage). glTF stores colours in linear space, so the tool converts
-the sRGB palettes before writing them. Re-run `build` and `godot --headless
---path . --import` after changing a prop. See
-[ADR-0012](docs/adr/0012-surface-materials-and-generated-props.md).
-
-Surface materials share one definition in `src/game/materials.gd`: named
-roughness/metallic profiles per surface, plus the environment tune-up (ACES
-tonemapping, glow, fog, colour grading) that the phase lighting applies.
-
-### NPC character model
-
-NPCs are moving from the procedural capsule rig to a skinned, UV-mapped base
-character authored in Blender ([ADR-0013](docs/adr/0013-blender-authored-npc-characters.md)).
-`tools/npc_pipeline.py` builds `assets/models/generated/npc_base.glb` plus the
-per-slot material maps. `NpcAvatar` instantiates that skinned model, tints its
-five material slots from the seed-driven outfit, and drives the bones from the
-existing animation code; the procedural rig remains the offline fallback (see
-the [graphics plan](docs/plan-graphics-v0.6.md)).
-
-```bash
-# Print the frozen contract (slots, bone names, triangle budget)
-python3 tools/npc_pipeline.py list
-
-# Rebuild the skinned base mesh + neutral maps in Blender and validate it
-flatpak run org.blender.Blender --background --python "$PWD/tools/npc_pipeline.py" -- build
-python3 tools/npc_pipeline.py audit
-
-# Layer the AI clothing albedos (shirt/trousers) over the procedural weave, and
-# derive per-fabric outfit colours for the avatar palette
-python3 tools/npc_pipeline.py prepare
-python3 tools/npc_pipeline.py palette
-```
-
-`prepare` resizes the AI fabric tiles (kept locally in `assets/textures/npc/ai/`,
-which is gitignored) onto the `cloth`/`pants` albedos; `build` bakes them into the
-`.glb` and regenerates the procedural normal + packed ORM maps. `palette` writes
-`assets/textures/npc/palette.json` using `model_pipeline.dominant_colors`.
-
-### Blender asset library (loaded by the game)
-
-`tools/blender_assets.py` models a larger library procedurally in Blender for the
-v0.6.0 integration: **8 skinned NPC characters** (casual, jacket, coat, hi-vis vest,
-dress, hoodie, firefighter, guard), each a drop-in for `npc_base.glb` (same bones,
-joint positions and tint slots); **18 gear pieces** authored at head/hand/back/chest
-attach points (caps, hood, helmet, backpack, SCBA tank, lanyard, phone, cup,
-clipboard, umbrella, camera, sign, flashlight, wand, radio, …); and **20 props**
-(octagonal bollard and bin, slatted bench, hydrant, news box, planters, street lamp,
-street and palm trees, A-frame sign, wall lantern, cone, crowd barrier, stanchion,
-handrail, podium, double door, marquee, sedan).
-
-`NpcAvatar` selects a character by role/seed, tints the five contract slots, and
-attaches gear at the documented points; `WorldBuilder` loads the library props
-with colliders/avoidance and drives their emissive parts from the day/night
-cycle. The single `npc_base.glb` and primitive props remain offline fallbacks.
-Contract and integration notes: [`docs/blender-assets.md`](docs/blender-assets.md).
-
-| Characters | Props |
-| --- | --- |
-| ![characters](docs/blender_previews/sheet_npc.jpg) | ![props](docs/blender_previews/sheet_props.jpg) |
-
-```bash
-flatpak run org.blender.Blender --background --python "$PWD/tools/blender_assets.py" -- build
-flatpak run org.blender.Blender --background --python "$PWD/tools/blender_assets.py" -- render
-python3 tools/blender_assets.py sheet   # docs/blender_previews/sheet_*.jpg
-python3 tools/blender_assets.py audit   # no Blender needed
-godot --headless --path . --import
-```
-
-### Confirmed game assets
-
-Everything below is audited and shipped in the game; development-only outputs
-(AI concept sheets, Blender sources, raw AI fabrics) are gitignored.
-
-| | |
-| --- | --- |
-| ![brick facade](assets/textures/ai/game_ready/v2/picks/brick_facade.png) | ![sidewalk pavers](assets/textures/ai/game_ready/v2/picks/sidewalk_pavers.png) |
-| ![asphalt](assets/textures/ai/game_ready/v2/picks/asphalt.png) | ![awning](assets/textures/ai/game_ready/v2/picks/awning_canvas.png) |
-| ![skyline day](assets/textures/ai/game_ready/v2/picks/skyline_day.png) | ![skyline night](assets/textures/ai/game_ready/v2/picks/skyline_night.png) |
-
-- **Surface textures:** the v2 picks above (brick, sidewalk pavers, dry and wet asphalt, awning canvas) plus their normal maps, loaded by `src/game/materials.gd` and `WorldBuilder`; the three skyline panoramas are switched per shift phase. The first-generation tiles and `assets/textures/skyline.png` are no longer loaded.
-- **UI art:** `assets/textures/ai/game_ready/icons/` (flashlight, door lock, wand, REC) and `assets/textures/ai/game_ready/cards/` (ID, wristband, ticket, credential, guest list), loaded by `src/game/ui/hud.gd`.
-- **Generated models:** `assets/models/generated/*.glb` — bollard, bench, trash bin, planter, newspaper box, hydrant, and the NPC base — plus their colour atlases.
-- **NPC material maps:** `assets/textures/npc/*_{albedo,normal,orm}.png` and `palette.json`.
-
-Audit them all:
-
-```bash
-python3 tools/asset_pipeline.py audit assets/textures/ai/game_ready
-python3 tools/model_pipeline.py audit
-python3 tools/npc_pipeline.py audit
-```
-
-### Realism pass: scene concepts, skylines and textures
-
-The skyline, surface tiles and phase lighting were rebuilt against AI concept frames. The
-concepts live in [`docs/screens/concepts/`](docs/screens/concepts/README.md); the validated
-picks the game loads are in `assets/textures/ai/game_ready/v2/picks/` (day/dusk/night
-panoramas, brick, sidewalk pavers, dry and wet asphalt, awning canvas, each with a normal
-map).
-
-`tools/scene_concepts.py` generates and processes new candidates, promotes the validated ones
-to stable names, audits them, and scores captures against the concepts. It never overwrites an
-image: new files get a `-vN` suffix, and `process` skips existing candidates unless `--new`.
-
-```bash
-python3 tools/scene_concepts.py generate --group scene        # or backdrop / texture, --variants N
-python3 tools/scene_concepts.py process && python3 tools/scene_concepts.py audit
-python3 tools/scene_concepts.py promote                       # validated picks -> v2/picks/
-godot --headless --path . --import
-
-# A/B a candidate without touching game code: the same cameras, textures swapped at runtime.
-godot --path . --script res://src/test/capture_realism.gd -- --out=res://docs/screens/realism/<run>/after
-godot --path . --script res://src/test/capture_realism.gd -- --out=res://docs/screens/realism/<run>/try \
-  --swap=res://assets/textures/ai/game_ready/v2/picks/brick_facade.png=res://assets/textures/ai/game_ready/v2/brick_facade-v2.png
-
-# Score before/after against the concepts (Pillow detail metrics + vision judge).
-python3 tools/scene_concepts.py realism --run docs/screens/realism/<run> --judge \
-  --model google/gemini-2.5-flash --repeats 3
-```
-
-`capture_realism.gd` runs five stages (day, evening, late, Joke Shop, studio); `--stages=day,late`
-limits it while tuning. The latest run,
-[`docs/screens/realism/2026-11-01-adopt/`](docs/screens/realism/2026-11-01-adopt/report.md),
-compares the pre-adoption captures with the current build: on the shots both sets captured the
-judge's like-for-like means rose on every sub-score (overall 0.8 → 1.0, backdrop 0.6 → 1.6) and
-the Pillow metric gap fell 0.444 → 0.348.
-
-![realism run](docs/screens/realism/2026-11-01-adopt/sheet.jpg)
-
-### Screen design references
-
-Screen mockups and screenshot comparison use `tools/screen_designs.py`. It turns the
-screen descriptions in `docs/` (README captions, ADRs 0007–0010, `PLAN.md`, and
-`architecture.md`) into runtime reference art under `assets/images/ui/` (with a
-reference-only snapshot in `docs/screens/designs/`), then uses those images as
-the expected state to check the game's captures.
-
-Each screen is tagged `scene` (a realistic first-person 3D world view) or `ui`
-(an in-game panel overlaid on a softened scene), and the generator appends a
-shared art-direction suffix so the frames read as one coherent game. Requests use
-a 3:2 landscape source and crop to the 16:9 capture dimensions.
-
-```bash
-# Export the built-in scenarios to editor-authorable .tres resources
-godot --headless --path . --script res://tools/export_venues.gd
-
-# List the catalogue (name, kind, whether a reference design exists)
-python3 tools/screen_designs.py list
-
-# Deterministic wireframes (offline, no API key); existing designs are kept
-# unless --force is passed, so an offline run never replaces an AI mockup
-python3 tools/screen_designs.py generate --draft
-python3 tools/screen_designs.py generate --draft --only wand --force
-
-# Realistic 3D scenes and in-game screen designs via OpenRouter
-# (requires OPENROUTER_API_KEY)
-python3 tools/screen_designs.py generate
-
-# Prop gallery (studio line-up) for close-range prop checks
-godot --path . --script res://src/test/capture_prop_gallery.gd
-
-# Compare docs/screenshots/*.png against the designs
-python3 tools/screen_designs.py compare
-python3 tools/screen_designs.py compare --json
-
-# Ask a vision model whether each capture realises its design's screen and layout
-# (requires OPENROUTER_API_KEY; the repo .env is read automatically)
-python3 tools/screen_designs.py judge
-python3 tools/screen_designs.py judge --model openai/gpt-4o-mini --json
-python3 tools/screen_designs.py judge --only 03-   # one capture
-python3 tools/screen_designs.py judge --dry-run    # build requests, no network
-```
-
-The catalogue covers 21 screens: the eleven README captures plus the start menu,
-pause overlay, settings, shift review, radial menu, emergency radio, wand
-screening, Joke Shop queue, TV Studio arrival, crowd panic, responder arrival,
-body-camera timeline, and the escalation HUD. All 21 have an AI reference in
-`assets/images/ui/` (snapshot in `docs/screens/designs/`); the eleven screens with
-staged captures are also compared or judged against the running game.
-
-`compare` flags gross drift: wrong aspect ratio, undersized frame, near-blank
-frame, and large layout/palette/detail distance. It is a regression gate, not a
-semantic judge — pixel and perceptual metrics cannot decide whether a frame's
-composition is *right*.
-
-`judge` covers that gap: it sends each capture together with its concept mockup to
-a vision model and asks whether the capture realises the same screen and layout
-intent. Art style, fidelity, fonts, and placeholder text are explicitly ignored.
-Verdicts are classed as `match`, `review` (a mismatch below `--fail-confidence`,
-default 0.6 — expected when a concept mockup is more stylised than the game), or
-`diff` (a confident mismatch, which exits non-zero). Regenerate the designs after changing screen layout, then re-run
-`compare` after regenerating the game screenshots with
-`src/test/capture_screenshots.gd`.
-
-For a one-command drift check, run `tools/check_screenshots.sh`. It renders the
-staged captures and prop gallery into `docs/screenshots/` (using `xvfb-run` when
-no display is available) and then runs `screen_designs.py compare`.
-
-### Setup
-
-1. Download the Godot 4.3 editor (official build) and put `godot` on your PATH.
-2. Open or run the project from this directory.
-
-### Run and Test
-
-```bash
-# Open in the editor
-godot --editor --path .
-
-# Run the game
-godot --path .
-
-# Headless smoke boot (120 frames then exit)
-godot --headless --path . --quit-after 120
-
-# Run all unit tests headlessly (exit code 0 = pass)
-godot --headless --path . --script res://src/test/test_runner.gd
-
-# Save a screenshot to user:// (windowed)
-godot --path . --script res://src/test/take_screenshot.gd
-
-# Windowed control smoke: focus circle, action wheel, wheel cycling + right-click clear; saves PNGs, exits 1 on failure
-godot --path . --script res://src/test/smoke_focus_radial.gd
-
-# Session-shell smoke: menu → shift → pause → settings → menu (headless or windowed)
-godot --headless --path . --script res://src/test/smoke_session_shell.gd
-
-# PLAN-verb smoke: recognize, request reason, body camera, warning, blocking
-godot --headless --path . --script res://src/test/smoke_plan_verbs.gd
-
-# Prop-collision smoke (windowed): guard stops at a bench, guest routes around it
-godot --path . --script res://src/test/smoke_props.gd
-
-# NPC budget smoke: 16 full-rig avatars against the documented frame budget
-godot --headless --path . --script res://src/test/smoke_npc_budget.gd
-
-# Movement smoke (windowed): steps, precision walk, footsteps and landing
-godot --path . --script res://src/test/smoke_movement.gd
-
-# Crowd smoke: rubbernecking on aggression, panic clearing the entrance
-godot --headless --path . --script res://src/test/smoke_crowd.gd
-
-# Emergency smoke: unjustified call, investigation note, evacuation aftermath
-godot --headless --path . --script res://src/test/smoke_emergency.gd
-
-# Body-camera timeline smoke: review → timeline → step through → back to review
-godot --headless --path . --script res://src/test/smoke_timeline.gd
-
-# Audio smoke: crowd bed follows mood, radio open/close crackle
-godot --headless --path . --script res://src/test/smoke_audio.gd
-
-# Scenario-content smoke: wand refusal, celebrity crowd spike
-godot --headless --path . --script res://src/test/smoke_scenario_content.gd
-```
-
-The unit test runner is the project's own lightweight harness (no editor plugin required) so CI can run it without the editor.
-
-### Controls
-
-Keyboard and mouse are the default; a gamepad works without configuration (left stick moves,
-right stick looks, A opens/confirms the wheel, B cancels, X inspects, Y calls the radio, LB walks
-slowly, RB uses the wand). Keys and pad buttons can be rebound in Settings, and the remaps persist
-in `user://settings.json`. The HUD legend switches to gamepad hints when a pad event arrives.
-
-| Input | Action |
-| --- | --- |
-| W/A/S/D + mouse | Move and look |
-| Space / left click | Action wheel for the focused person (Stop, Look, Point, No, Ask, Inspect, Wand, Warn, Block, Reason, Recognize, Radio) |
-| A / D or ←/→ | Step through the action wheel (while it is open) |
-| Space / left click | Confirm the highlighted action (while the wheel is open) |
-| Esc / right click | Close the top panel; Esc with nothing open pauses the shift (Esc again resumes) |
-| ← / → or ↑ / ↓ | Navigate the venue menu and the pause / settings panels |
-| Enter | Start the highlighted venue from the menu, or confirm in a panel |
-| 1 / 2 / 3 | Quick gestures without the wheel: raise hand, point, head shake (Level 1) |
-| Q | Polite direction (Level 1) |
-| 4 | Formal warning (Level 2) |
-| 5 | Blocking and positioning (Level 3) |
-| 6 | Security assistance radio (Level 4) |
-| R | Emergency radio, hold on-screen button ~1.6s (Level 5) |
-| E | Inspect access artifacts / close inspection |
-| C | Handheld wand screening (wand venues only) |
-| A / D | Allow / deny entry during inspection or wand check |
-| V | Cycle venue (debug shortcut; restart via V restarts the current shift) |
-| Tab / mouse wheel ↓ / ↑ | Cycle the target among nearby NPCs, nearest first (aim-free; the target stays selected) |
-| Right click (nothing open) | Clear the focused person and return to aim-based focus |
-| Shift (hold) | Precision walk at roughly half speed for close work at the door |
-| G | Toggle flashlight (widens NPC perception at night) |
-| B | Toggle the body camera; a formal warning switches it on automatically |
-| L | Lock / unlock the restricted door (thwarts forced entry) |
-| F | Toggle debug overlay |
+A typical shift lasts 10–15 minutes: watch the entrance and sidewalk, judge why
+each person is approaching, verify access with recognition, wristbands, IDs,
+tickets or credentials, and escalate only when necessary. The game rewards calm
+resolution over force. The full mechanics — the three venues, the six-level
+escalation model, and the core systems — are in
+[`docs/gameplay.md`](docs/gameplay.md); the design rationale lives in
+[`PLAN.md`](PLAN.md).
 
 ## Architecture
 
-The full arc42-style architecture documentation lives in [`docs/architecture.md`](docs/architecture.md). It covers goals, constraints, context, solution strategy, building blocks, runtime views, deployment, cross-cutting concepts, quality requirements, risks, a glossary, the CI/CD build pipeline, semantic versioning, and release management.
+A venue-driven simulation: shared systems (movement, perception, interaction,
+access verification, escalation, radio, crowd, reputation, evidence, shift
+review) driven by per-venue scenario data, on Godot 4 + GDScript. The full
+arc42-style document is [`docs/architecture.md`](docs/architecture.md);
+decisions are recorded as ADRs in [`docs/adr/`](docs/adr/).
+
+## Tech Stack
+
+- **Engine:** Godot 4.7.2 · **Language:** GDScript
+- **NPCs:** Blender-authored skinned library (`assets/models/blender/`) with procedural fallbacks; lightweight FSMs on `NpcProfile`
+- **World:** procedural `WorldBuilder` + generated prop models
+- **Art:** v2 skyline/surface textures in `assets/textures/ai/game_ready/v2/picks/`; UI/scene art in `assets/images/`
+- **Asset tooling:** `asset_pipeline.py`, `model_pipeline.py`, `npc_pipeline.py`, `blender_assets.py`, `scene_concepts.py`, `screen_designs.py`, `check_screenshots.sh`
+- **Testing:** custom headless runner (`src/test/test_runner.gd`)
+- **Targets:** Windows, Linux, macOS, Web
+
+The asset pipelines, model tools, and screenshot gates are documented in
+[`docs/asset-tooling.md`](docs/asset-tooling.md).
+
+## Setup and Run
+
+```bash
+python3 -m pip install -r requirements-tools.txt
+
+godot --editor --path .          # open in the editor
+godot --path .                   # run the game
+godot --headless --path . --script res://src/test/test_runner.gd   # run all tests
+```
+
+Full setup, every run/test/smoke command, and the controls table are in
+[`docs/getting-started.md`](docs/getting-started.md).
 
 ## Project Documentation
 
 - [`PLAN.md`](PLAN.md) — Game design plan and scenario details.
 - [`AGENTS.md`](AGENTS.md) — Development and collaboration workflow.
-- [`TODO.md`](TODO.md) — Active checkbox task list.
 - [`DONE.md`](DONE.md) — Completed task sections.
 - [`MEMORY.md`](MEMORY.md) — Persistent session notes.
+- [`CHANGELOG.md`](CHANGELOG.md) — User-facing changes by version.
 - [`docs/architecture.md`](docs/architecture.md) — arc42-style architecture documentation.
-- [`docs/adr/`](docs/adr/) — Architecture Decision Records.
-- [`docs/plan-graphics-v0.6.md`](docs/plan-graphics-v0.6.md) — Graphics-quality plan: Blender-authored NPC characters.
+- [`docs/gameplay.md`](docs/gameplay.md) — Gameplay systems, venues, and the escalation model.
+- [`docs/tutorial.md`](docs/tutorial.md) — First-shift tutorial beats and rules.
+- [`docs/asset-tooling.md`](docs/asset-tooling.md) — Asset pipelines, model tools, and screenshot gates.
+- [`docs/getting-started.md`](docs/getting-started.md) — Setup, run/test commands, and controls.
+- [`docs/development-status.md`](docs/development-status.md) — Implemented features and what's next.
+- [`docs/smoke-checklist.md`](docs/smoke-checklist.md) — Manual smoke-test checklist.
 - [`docs/blender-assets.md`](docs/blender-assets.md) — Blender asset library: characters, gear, props, attach points.
+- [`docs/adr/`](docs/adr/) — Architecture Decision Records.
+- [`TODO.md`](TODO.md) — Active tasks plus the v1.0.0 gap analysis and milestone roadmap.
 
 ## Development Status
 
-Implemented so far:
-
-- Godot 4.3 project scaffold, input map, procedural world builder
-- Venue-driven simulation core: `ShiftCoordinator`, `VenueScenario`, `EventScheduler`, `NPCController` + FSM, `AccessVerifier`, `EscalationManager`, `RadioSystem`, `IncidentRecorder`, `ReputationEvaluator`, `CrowdSystem`
-- Three authored scenarios (Hollywood Boulevard building, The Joke Shop, Late Night TV Studio) with access policies, NPC archetypes, and event pools
-- Headless unit tests: **227 passing** (access rules and venue-correct access loadout, escalation, radio cooldown/battery, NPC reaction determinism, door lock, flashlight perception, persistence round-trip, settings round-trip, input remaps, navmesh, step colliders, skyline alpha, scenario data, full-shift simulation, wand screening, responder dispatch, localization strings, focus cone, action wheel, session shell, PLAN verbs and incident recording, crowd presentation, emergency aftermath, body-camera timeline, NPC theater poses, audio, accessibility, authored scenario content, string formatting, `.tres` venue round-trip, surface materials and environment, focus ranking and outfit/gait helpers, generated prop models, web export preset, prop atlas material, player movement, NPC character layers/LOD/queue, input bindings)
-- Simulation extras: protester archetype, CALL_SOMEONE reaction, door lock/secure mechanic (visual indicator), flashlight with night perception bonus, LATE shift phase reaching the violent-threat event
-- First-person prototype with interaction HUD, access inspection, wand screening, radio report form (incl. emergency hold-to-confirm), dispatched responder avatars, aim-free targeting, venue cycling between all three scenarios, color-coded escalation feedback, procedural audio cues, navigation-mesh NPC paths, JSON-backed localized strings, persisted shift history, debug overlay, and shift review
-- Control pass: focus cone on NPC heads with a billboarded blue circle in front of the face and name, action wheel (LMB/Space) with de-escalation-first slices, mouse-look freeze while a panel is open, acceleration-based walking, and named input actions (`action_menu`, `confirm`, `cancel`, `inspect`, `wand`)
-- Session shell: venue start menu (keyboard + mouse), Esc pause overlay (resume / restart / settings / quit to menu), settings panel with mouse-look sensitivity and HUD font scale persisted to `user://settings.json`, and "Run another shift" returning to the venue menu
-- World presentation: skyline backdrop rendered with an alpha material, walkable step and landing colliders, larger marquee text, and larger focus circle / name tag
-- Routine traffic despawns after a while at its waypoint so the crowd cap no longer fills with idle standers
-- PLAN verbs: eye contact (distinct Level 1 cue), recognizing a person as a player decision recorded as access evidence, a body-camera flag that a formal warning arms (and `B` toggles), blocking that physically stations the guard between the person and the door, and a Level 3 request-reason ask answered from the NPC's `dialogue_lines`
-- Incidents are now actually opened on focus and closed at shift end, so player actions, access evidence, escalation levels, and unresolved interactions reach the review (previously every recorded event was dropped)
-- Crowd presentation: aggressive behavior and responder arrivals make idle bystanders stop and face the incident; panic sends people away from the door (and they leave the scene). A busy 16-NPC entrance measured ~1.2 ms/frame, so no LOD/culling was needed at the current cap
-- Distant skyline ring: four alpha-scissored planes at 200 m read as a hazy city on the horizon (the baked backdrop used to show as a black slab), with a larger ground plane so the buildings meet the street
-- Flashlight aims straight ahead and lights the person/door being checked instead of the ground in front of the guard
-- Emergency aftermath: the `evacuation` outcome locks the door and clears the entrance, an emergency call that the situation did not justify opens an investigation and applies the false-report hit, and the shift review names the responder outcome and any investigations
-- Body-camera timeline: the shift review opens a text timeline of every recorded incident event (time, person, action/outcome) that you step through with the arrow keys or buttons. No live 3D replay yet
-- NPC theater: seated guests sit on the steps with bent legs, influencers and tourists raise a camera prop while photographing, performers sway their sign, and filming visitors pan slowly — all once they reach their intent's waypoint
-- Audio: a looping procedural crowd bed (filtered murmur) whose volume follows `CrowdSystem.mood`, plus radio open/close crackle. All generated at runtime, no audio assets, and safe with a dummy audio server
-- Accessibility: the escalation cue shows a shape meter plus the numeric level (`Escalation: Blocking [###--] L3/5`) so it reads in grayscale, and the HUD font scale from settings is applied at boot by resizing fonts (not Control.scale, which broke the right-aligned layout)
-- Editor-ready venues: `tools/export_venues.gd` writes `content/venues/<id>.tres` from `ScenarioFactory`, and the `.tres` files load back with events, profiles, policy, phases, door lines, and locations intact (the factory stays the source of truth)
-- Localization safety: `Strings.fmt` validates the placeholder count before formatting and fails safe (warns, returns the template) instead of raising an engine error, `Strings.placeholder_count` ignores `%%`, and `Strings.validate()` lints the table for trailing `%`, unsupported conversions, and mixed positional/sequential placeholders
-- Authored scenario content: Joke Shop reservation-without-ID, borrowed/mismatched ID, a guest who refuses the wand screen, and a late arrival during a performance; Studio filming-boundary repeats and a celebrity arrival that draws a small crowd; Building events that point the player at the body camera and request-reason verbs
-- Visual polish pass (v0.2.0): phase-based lighting (sun/sky/ambient per shift phase), street lamps with night-mode bulbs and omni lights, glowing marquee signage, crosswalk, planters and low-poly street trees, NPC height/brightness variety, denser routine traffic — day and late-night screenshot sets
-- Assets pass: authored textures in `assets/textures/` (brick facade, concrete, asphalt, awning, skyline, vignette, HUD icons, access-card art) generated by `tools/generate_textures.py`, soft sun shadows, humanoid NPC rigs with archetype props + procedural walk bob and attention head-turn, inspection artifact cards, escalation vignette, mode icons, and a body-camera overlay (REC + shift clock)
-- Rendering pass (v0.3.0 work, [ADR-0012](docs/adr/0012-surface-materials-and-generated-props.md)): one material module with roughness/metallic profiles per surface, ACES tonemapping, glow, aerial fog and colour grading driven by the shift phase, correctly scaled brick, framed facade windows that light up at night, door trim and handles, a curb and lane dashes, and the glowing marquee/lamp bulbs. NPCs gained per-role clothing palettes, caps/hoods/backpacks/sunglasses/lanyards, hands and shoes, and an arm/leg walk swing
-- NPC characters (v0.5.0): articulated limb rigs, layered outfits, hand items, face/hair variety, idle behaviour (phone, clipboard, crossed arms, look-around), escalation gestures, readable reaction symbols, door-queue offsets, and three LOD tiers with a billboard impostor
-- Player movement (v0.5.0): separate acceleration/braking, step-up assist, head bob and landing dip (toggleable), precision-walk FOV/chip/tick, surface-aware footsteps, gamepad support, and persistent key/button remapping in settings
-- Prop collision and placement (v0.4.0): every prop fits a static collider from its mesh bounds and publishes a navigation obstacle, so the guard and guests cannot walk through benches, bins, or bollards; placements are grouped into zones with a validator, and deterministic variants add rotation, scale, and small clutter
-- Prop atlas (v0.3.1): `tools/model_pipeline.py` packs each prop's palette into one power-of-two colour atlas plus a metallic/roughness atlas and emits a single material with per-vertex UVs, so a prop is one draw material rather than one per part; `audit` enforces the contract
-- Generated prop models (v0.3.0 work): `tools/model_pipeline.py` builds bollards, benches, bins, planters, newspaper boxes and a hydrant as `.glb` props with per-part materials, loaded by `WorldBuilder` with a procedural fallback; the optional AI concept step (`model_pipeline.py concept`) supplies per-prop colour palettes
-- Environment pass (v0.6.0): 1024² brick/concrete/asphalt with derived tangent normal maps, 256² baked AO maps for every Blender character/gear/prop, and library props whose bulbs/LEDs/sign faces follow the day/night phase
-- NPC characters + library (v0.6.0): `NpcAvatar` loads one of 8 Blender-authored skinned variants (role/seed selected) with five tintable material slots, `Rig/Head` focus anchor, and attach-point gear; `npc_base.glb` and the procedural rig remain fallbacks. `tools/blender_assets.py` builds/audits the character, gear, and 20-prop library; `WorldBuilder` loads the replacements and new street dressing (lamp, trees, palms, planters, barriers, podium, doors, marquee, sedan, handrail) with colliders, navigation obstacles, and phase-driven emissives
-- Web build: `build/gig-line-web-<version>.zip` (Godot's non-threaded web template, no COOP/COEP headers needed) built by `tools/build_releases.sh` and published with the desktop artifacts; serve the unzipped folder from any static host
-- Aim-free selection pass (v0.3.0 work, [ADR-0011](docs/adr/0011-aim-free-selection-and-precision-walk.md)): the focus cone ranks candidates by angle then distance, `Tab` and the mouse wheel cycle nearby people nearest-first and pin the selection, right click clears focus with a short re-acquire grace, the HUD reports how many people are in the ring, and holding `Shift` walks at half speed for close work
-
-Not yet implemented: a desktop-only Forward+ preset (the renderer stays GL Compatibility for Web parity), live 3D body-camera replay, editor-based GUT integration, and crowd performance profiling/LOD (see `TODO.md`).
-
-### Smoke Test Checklist
-
-1. `godot --path .` starts the game on the venue menu without script errors.
-2. Choosing a venue (click or ↑/↓ + Enter) starts that venue's shift and hides the menu.
-3. The guard moves and looks around; the building, steps, and sidewalk are visible.
-4. The guard's camera sits at eye height and the guard stands on the landing, not inside the building.
-5. Walking into the steps carries the guard up onto the landing (steps have colliders).
-6. The skyline backdrop shows silhouettes against the sky, not an opaque black slab.
-7. The `GIG LINE` marquee is readable from the sidewalk.
-8. NPCs spawn and approach the entrance during the first minutes.
-9. Looking at an NPC inside the focus cone shows a blue focus circle in front of the face, the person's name, and the HUD target line.
-10. `Space` or left click opens the action wheel; `A`/`D` highlight a slice, `Space` confirms it, `Esc`/right click cancels without a log entry.
-11. `E`/`C` open the inspection/wand panels from the wheel and freeze movement until they close; walking never fires the wand.
-12. Pressing `Q` produces a reaction log entry and reputation feedback.
-13. `E` opens access inspection showing venue-correct artifacts and policy result; `A`/`D` record a decision.
-14. `6` opens the assistance form; submitting shows dispatch feedback.
-15. `R` opens the emergency form; the button must be held ~1.6s or the call cancels.
-16. `G` toggles the flashlight (indicator appears in the HUD); `L` toggles the door lock (indicator turns red when locked).
-17. `F` toggles the debug overlay with NPC states and shift stats.
-18. The wheel's `Look` slice is eye contact (Level 1) and logs as its own action.
-19. `Reason` asks why the person is there and logs their `dialogue_lines` reply.
-20. `Recognize` records the guard's recognition as access evidence; pressing it twice says so.
-21. `Warn` turns the body camera on (REC overlay appears); `B` toggles it manually.
-22. `Block` moves the guard between the person and the door.
-23. The shift review reports the incident count, including interactions left unresolved.
-24. Escalating on someone (or a responder arriving) makes idle bystanders stop and face the incident.
-25. Repeated alarms panic the crowd and nearby people clear away from the door instead of standing around.
-26. `Esc` with nothing open pauses the shift; resume / restart / settings / quit-to-menu all work, and settings changes persist across a restart.
-27. NPCs route around the building using the navigation mesh (no stuck-at-wall behavior during a smoke run).
-28. An unjustified emergency call (calm person, no weapon) logs an investigation and costs reputation.
-29. After an evacuation outcome the door is locked and NPCs are leaving the entrance.
-30. The shift review's "Body camera timeline" button steps through the recorded events (Left/Right or the buttons) and Esc returns to the review.
-31. The escalation label shows a `[###--] L3/5` shape meter as well as the level name, and stays readable in grayscale.
-32. Changing "HUD font scale" in Settings resizes the HUD text and persists across a restart.
-33. When the shift timer reaches 0, the shift review screen shows grade, incident summary, responder outcomes, investigations, and persisted shift history; "Run another shift" returns to the venue menu.
+v0.9.0 adds the production-quality baseline: mixer/accessibility settings, a
+24-NPC performance budget and the unified Godot 4.7.2 toolchain, on
+top of v0.8's tutorial, campaign, checkpoint resume, difficulty and Help. See
+[`docs/development-status.md`](docs/development-status.md) for the implemented
+list and [`TODO.md`](TODO.md) for the v1.0.0 roadmap. Manual verification uses
+the [`docs/smoke-checklist.md`](docs/smoke-checklist.md).
 
 ## Development Workflow
 

TODO.md

@@ -1,22 +1,354 @@
 # TODO
 
-## Realism follow-ups (v0.6.1 candidates)
+Work is grouped by theme. Each item should be small enough to complete and verify on its own;
+see `AGENTS.md` for the workflow and `MEMORY.md` for the decisions behind these plans.
 
-- [x] Fixed ground exposure for the entrance view: the morning sun now sits at 34° elevation
-      instead of 50°, so the facade shades the near sidewalk and props cast long shadows. Ground
-      luminance went 95 → **83** against the concept's 78 (it was 173 before the realism pass),
-      with the boulevard at 82 and the street at 81.
-- [-] Make the flashlight read in the dark: the `06-night-flashlight` concept shows a visible
-      beam, but a Compatibility spot light only brightens the near wall. A cheap fake cone (an
-      additive mesh or a light-shaft quad) would sell it, and the night mockup expects it.
-- [ ] NPC skin/clothing still reads as low-poly next to the concepts (judge `characters` ≈ 0–1).
-      The Blender library has the budgets for one more detail pass (fingers, sleeves, faces).
-- [x] Re-check the `screen_designs.py judge` default model (`google/gemini-2.5-flash-lite`): on
-      2026-11-01 it returned 7 match / 4 review / 0 diff without a provider error; `--model`
-      override is documented in `README.md`.
-- [ ] Add the two venue stages to the committed gallery (they are capture-only today) and give
-      the Joke Shop and studio their own geometry so their concept comparisons are geometric,
-      not just lighting.
+## Gap Analysis and v1.0.0 Roadmap
+
+Baseline: **v0.9.0** (2026-11-01). Three playable venues, tutorial/campaign/checkpoint resume,
+difficulty/help, audio/accessibility settings, a 24-NPC budget baseline, a complete
+escalation/access/radio loop, shift review, the Blender asset library, 250 headless + 94 Python
+tests, a clean screen-design judge and an optional Forward+ Desktop HQ build. This is a strong
+release-candidate foundation, not yet a 1.0 product.
+
+### Documentation audit (completed 2026-11-01)
+
+- [x] Make `docs/architecture.md` the single architecture source: asset/content pipeline
+      contracts, runtime venue-switch/fallback flows, deployment/version constraints, quality
+      requirements, risk register and documentation ownership map.
+- [x] Keep command-heavy operational pages separate but subordinate: `docs/asset-tooling.md`,
+      `docs/blender-assets.md`, `docs/getting-started.md`, `docs/RELEASING.md` and
+      `docs/smoke-checklist.md` link to architecture rather than acting as parallel sources.
+- [x] Remove the obsolete `docs/plan-graphics-v0.6.md` and its links; completed graphics work is
+      represented by ADR-0013, the asset pipeline section and the changelog.
+- [x] Resolve stale claims: README release version/download row, development status
+      "Forward+ not implemented", and Blender props "not AO-baked".
+- [x] Record the documentation ownership rule in `docs/architecture.md` §12: design intent
+      (`PLAN.md`), mechanics (`gameplay.md`), system architecture/contracts (`architecture.md`),
+      decisions (ADRs), status (`development-status.md`), roadmap (`TODO.md`), operations
+      (tooling/release docs).
+
+### Gap register (remaining to 1.0)
+
+| Area | Current baseline | Remaining gap | Risk | Milestone |
+| --- | --- | --- | --- | --- |
+| Content and balance | 3 venues with validated 12+ event matrices, recovery events and contextual dialogue | External playtest evidence, balance/fairness pass, event-weight tuning and final content lock | Repetition or unfair outcomes survive into 1.0 | 0.9.5 |
+| Dialog/UI | Complete screens and panel art, but copy/button behavior has not had a dedicated audit | Terminology, button states, long-string layout and full screen coverage need a focused pass | Inconsistent UI undermines first-hour clarity | 0.9.1 |
+| Animation/presentation | Procedural pose layers, portrait captures, reduced hem clipping | Final model/pose/facial readability and gear-fit acceptance before visual QA | Close-up jank reduces perceived quality | 0.9.2 |
+| Audio/accessibility | Procedural ambience/SFX, volume controls, captions/reduce-motion settings, searchable Help | Full accessibility/localization acceptance review, audio caption coverage and P0/P1 fixes | Public 1.0 cannot claim accessible play | 0.9.1 / 0.9.5 |
+| Localization | English JSON table, validation and input-generated Help | Pseudo-locale/layout audit and translator workflow sign-off | Text expansion/clipping at release | 0.9.1 / 0.9.5 |
+| Performance/platform | 24-NPC headless budget (6.9 ms), Compatibility/Web/HQ paths | Target hardware matrix, Web/HQ manual profiling, frame-time/memory evidence | Platform-specific drops or startup failures | 0.9.4 / 0.9.5 |
+| Save lifecycle | Settings/campaign/history/checkpoint files, atomic writes | Migration fixtures from 0.8/0.9, fresh-install/upgrade verification, rollback instructions | Player progress loss on upgrade | 0.9.5 |
+| QA/CI | Headless suite, smokes, screenshot compare, optional judge | Full visual judge gate, release-candidate smoke matrix, final gallery and release dry run | Regressions escape the release gate | 0.9.4 / 0.9.5 |
+| Release/legal | Unsigned desktop/macOS builds, Web/HQ packages | Signing/notarization decision, checksums, AI-asset provenance, credits, privacy/body-camera and rating review | Public release blocked by trust/policy | 0.9.5 |
+| Documentation | Architecture/ADR/status/roadmap ownership established | Final README/changelog/status/TODO/smoke-checklist sign-off and known-limitations page | Docs drift at launch | 0.9.4 / 0.9.5 |
+| Post-launch | Stable 0.9 feature set | Live replay, more venues, VO/music, image-to-mesh props and seasonal content | Scope creep before launch | Post-1.0 |
+
+## Patch 0.9.1 — Dialog, button and UI polish
+
+Goal: make every player-facing screen read consistently and pass the Python
+screen-design judge before any model/texture changes. No gameplay rules change.
+
+### Screen and terminology inventory
+
+- [ ] Inventory every screen/panel: start menu, venue menu, tutorial, HUD, pause,
+      settings, Help, inspection, wand, radio/emergency, wheel, shift review,
+      timeline and campaign/continue screens.
+- [ ] Record the canonical terms for admit/deny, allow/refuse, warning/blocking,
+      assistance/emergency, body camera, shift/review and campaign; remove synonyms
+      that mean the same action.
+- [ ] Audit all button labels for verb-first wording, capitalization, ordering,
+      destructive-action confirmation and consistent confirm/cancel placement.
+- [ ] List every hardcoded player-facing string and route it through
+      `content/strings.en.json`; add placeholder validation for new keys.
+- [ ] Review NPC/door-staff/radio/tutorial/help/review/campaign dialogue for
+      repetition, ambiguity, tone and localization length.
+
+### Button and panel behavior
+
+- [ ] Audit normal/hover/pressed/focus/disabled states on every button, including
+      tutorial skip, venue continue, settings apply/cancel/reset, judge/review,
+      radio send/emergency hold and Help close.
+- [ ] Verify keyboard-only and gamepad-only navigation: focus order, wrapping,
+      default focus, confirm/cancel behavior and no focus traps.
+- [ ] Verify every modal closes with Esc/right-click where documented, recaptures
+      the mouse, and does not leave the guard frozen or the menu visible.
+- [ ] Test buttons at minimum/maximum HUD font scale and with 1.5–2× longer
+      strings; fix clipping, overflow and overlapping layouts.
+- [ ] Test destructive/irreversible actions (campaign reset, tutorial replay,
+      emergency send) require the intended confirmation/hold and cannot double-fire.
+- [ ] Verify radio normal-send vs emergency hold, inspection/wand allow/deny,
+      review continue/retry/menu and Help search/filter behavior end to end.
+
+### Visual and judge verification
+
+- [ ] Update the affected UI art/reference mapping where copy or button order
+      changes; keep the no-overwrite image convention.
+- [ ] Capture a deterministic screenshot for every dialog/button state that has a
+      design reference; add missing capture stages or an explicit coverage gap.
+- [ ] Run `tools/check_screenshots.sh` and `python3 tools/screen_designs.py compare`;
+      fix all `bad` results.
+- [ ] Run `python3 tools/screen_designs.py judge` with `--model auto` (or a pinned
+      model); clear every `diff` and record accepted `review` verdicts.
+- [ ] Record the judge model, fallback order, spend and evidence in
+      `docs/screens/realism/` or the screen-design report.
+- [ ] Add a short UI copy/button checklist to `docs/smoke-checklist.md`.
+- [ ] Exit: all screens have consistent terminology and button behavior, long
+      strings/scale pass, and the Python compare/judge gate has no unexplained
+      diff.
+
+## Patch 0.9.2 — NPC model refinement
+
+Goal: make the eight character variants and their gear hold up in portraits and
+normal play without changing the `npc_base`/`Rig/Head` contract.
+
+### Model and rig audit
+
+- [ ] Render all eight variants from front, profile, back and portrait angles;
+      compare faces, hair, ears, hands, shoes, proportions and gear fit.
+- [ ] Audit head/face readability (brow, eyes, lips, nose, hairline) at portrait
+      distance; fix the highest-impact silhouette/face issues.
+- [ ] Audit gear fit and clipping: caps/beanie/hood/helmet/sunglasses, shoulder bag,
+      backpack, SCBA tank, lanyard, hand items and the new coat/dress stride.
+- [ ] Audit coat/dress/skirt hems during walk, blocking, sitting and turning; fix
+      remaining leg/hem intersections with weights, geometry or stride limits.
+- [ ] Re-check the frozen contract: mesh `npc_base`, bone names, five tint slots,
+      front direction, attach points, triangle/vertex budgets and grounding.
+- [ ] Rebuild affected GLBs, bake AO, run `godot --headless --path . --import`, and
+      run `blender_assets.py audit` plus fit/portrait checks.
+
+### Pose and animation polish
+
+- [ ] Review idle, walk, warning, blocking, recognition, refusal, phone, clipboard,
+      photo, film, sit and responder poses for pops or floating props.
+- [ ] Add/adjust short transitions for negotiation/reaction poses without breaking
+      the seeded pose helpers or head-turn behavior.
+- [ ] Verify LOD tiers and the impostor at 16/24-NPC distances; re-run the budget
+      smoke and record any triangle/draw-call changes.
+- [ ] Refresh the Blender review sheets and character portraits; keep per-asset
+      previews local if gitignored.
+
+### Verification
+
+- [ ] Add/update headless tests for any new pose/model contract behavior.
+- [ ] Capture the portrait and character gallery; compare against the design
+      references and run the Python judge.
+- [ ] Update `docs/blender-assets.md`, architecture/status and `MEMORY.md` with the
+      revised budgets, limitations and rebuild commands.
+- [ ] Exit: portrait/readability and gear fit pass, no obvious P0/P1 clipping remains,
+      and the 24-NPC budget/full test suite are green.
+
+## Patch 0.9.3 — Texture and material refinement
+
+Goal: improve close-range surface and character texture quality while keeping GL
+Compatibility/Web parity, deterministic assets and offline CI.
+
+### Environment textures and materials
+
+- [ ] Audit the v2 picks (brick, sidewalk pavers, dry/wet asphalt, awning canvas,
+      day/dusk/night skylines) at close range and in the entrance/street shots for
+      seams, tiling, scale, contrast and normal-map strength.
+- [ ] Refine brick mortar/wear, paver joints/stains, asphalt aggregate/wet response
+      and awning weave using the existing image/asset tooling; never overwrite a
+      pick, use `-vN` candidates and promote validated results.
+- [ ] Check UV scales and material roughness/metallic profiles; keep day/night
+      phase behavior and the wet-street transition intact.
+- [ ] Review distant skyline haze and foliage/planter surfaces against the concept
+      references; fix obvious flatness without regressing readability.
+
+### Character and prop textures
+
+- [ ] Audit NPC skin, cloth, pants, hair and gear albedo/normal/AO maps in portraits;
+      refine fabric weave, skin variation and fixed detail materials.
+- [ ] Re-bake AO where geometry changes; verify the 256² maps and material wiring.
+- [ ] Audit library props and UI/card/icon textures at their actual screen sizes;
+      remove blurry/oversized or unused textures where safe.
+- [ ] Run texture audits, import, and the full asset test suite; record texture memory
+      and triangle/draw-call impact.
+
+### Visual verification
+
+- [ ] Run `python3 tools/scene_concepts.py realism` for the affected stages with the
+      judge enabled; record metric gaps and model/spend.
+- [ ] Re-run `tools/check_screenshots.sh` and the screen-design judge; clear all
+      `diff` verdicts.
+- [ ] Capture before/after close-ups for brick, pavement, asphalt, character cloth
+      and skyline; document accepted trade-offs.
+- [ ] Update asset docs and the changelog/status with the promoted texture versions.
+
+## Patch 0.9.4 — Integration, performance and judge gate
+
+Goal: integrate the UI/model/texture patches, prove the combined build on the
+target paths and leave a clean release-candidate handoff.
+
+### Integration and asset rebuild
+
+- [ ] Rebuild all changed Blender/GLB/AO assets, re-import, and verify manifest/fit/
+      audit coverage.
+- [ ] Run the complete headless suite, Python tooling and smoke matrix; fix any
+      regression from the three polish patches.
+- [ ] Re-run the 24-NPC budget smoke and record frame time, mesh count and any
+      texture-memory change; check Web and Desktop HQ if available.
+- [ ] Verify save/campaign/tutorial behavior is unchanged by the visual/UI patches.
+
+### Visual gallery and judge gate
+
+- [ ] Recapture the full gallery, portraits, venue/realsim stages and Desktop HQ A/B
+      as needed; no stale screenshots in the release set.
+- [ ] Run `tools/check_screenshots.sh`, `screen_designs.py compare` and
+      `screen_designs.py judge` on the final captures.
+- [ ] Run the realism judge for the affected concepts with a pinned model; record
+      model, attempt count, spend and verdicts.
+- [ ] Review all `review` verdicts manually; convert unexplained layout/composition
+      mismatches into fixes or explicit known limitations.
+- [ ] Ensure generated realism folders remain gitignored/local-only and only the
+      durable report decisions/docs are committed.
+
+### Release-candidate handoff
+
+- [ ] Update README, architecture, development status, changelog and TODO with the
+      final patch-level results and any remaining gaps.
+- [ ] Tag/version or otherwise freeze `0.9.4` as the integration checkpoint before
+      the `0.9.5` release candidate.
+- [ ] Exit: combined build is functionally green, visually reviewed, performance
+      measured and ready for the 0.9.5 content-lock/playtest phase.
+
+## Milestone 0.9.5 — Release candidate
+
+Goal: freeze the feature set, prove it with external players, clear release/legal blockers and
+verify every distribution path. This is the next shipped version before 1.0.
+
+### Content lock and external playtest
+
+- [ ] Declare a content/feature freeze for 0.9.5; only release-blocking fixes and balance changes
+      may land after the freeze.
+- [ ] Produce a release-candidate build with the tutorial, campaign, all three venues, Help,
+      accessibility settings and checkpoint/resume enabled.
+- [ ] Run at least five first-time-player sessions covering the tutorial and one full venue shift;
+      record where players get stuck, misunderstand evidence or choose disproportionate escalation.
+- [ ] Triage findings by severity (P0/P1/P2) and fix every P0/P1 onboarding/accessibility issue;
+      keep the rest as explicit known limitations or post-1.0 items.
+- [ ] Re-run the affected tutorial/campaign smokes after each fix and capture a fresh first-hour
+      walkthrough for the release notes.
+
+### Balance and fairness pass
+
+- [ ] Define measurable targets for routine compliance, access-decision accuracy, peaceful
+      resolution, justified emergency calls and false-positive/false-negative rates.
+- [ ] Run scripted venue sweeps across easy/normal/hard and all four phases; compare outcomes and
+      tune event weights, reaction tables, compliance and report strictness where targets fail.
+- [ ] Review emergency calls against actual danger: no routine behavior should make emergency the
+      dominant winning move, and genuine threats must remain answerable.
+- [ ] Verify the reputation grades, debrief explanations and campaign progression still communicate
+      the de-escalation-first design after tuning.
+- [ ] Record the balance evidence and any deliberate exceptions in `docs/development-status.md`
+      or `MEMORY.md`.
+
+### Save migration and session reliability
+
+- [ ] Add fixtures for a 0.8-era settings/campaign/history save and a 0.9.0 checkpoint; verify
+      migration/default-filling and a clean first launch with no files.
+- [ ] Test fresh install → tutorial → campaign → pause → quit → resume → review → next venue on
+      an isolated user-data directory.
+- [ ] Test corrupt JSON, partial temp files, missing optional fields and a failed atomic rename;
+      confirm fallback behavior never destroys a valid save.
+- [ ] Verify checkpoint resume after all three venues, after an incident, with NPCs at the door and
+      with flashlight/body-camera/door state set.
+- [ ] Document save locations, schema versions, reset behavior and rollback/export instructions in
+      `docs/getting-started.md` and the release notes.
+
+### Release engineering and distribution
+
+- [ ] Run `tools/build_releases.sh` from a clean checkout and verify Linux/Windows/macOS/Web/HQ
+      artifact names, sizes and checksums.
+- [ ] Smoke-test fresh Linux portable/AppImage, Windows portable/installer, macOS unzip/launch,
+      Web static hosting and Desktop HQ Vulkan fallback on the target matrix.
+- [ ] Add a disk-space preflight and retention policy to the release/publish scripts so a full
+      Gitea host cannot leave a partially uploaded release.
+- [ ] Verify release metadata, tag/version consistency, asset counts and download links; retain
+      at least the latest 0.8/0.9 releases and document older-asset pruning.
+- [ ] Decide and document whether macOS signing/notarization is required for 0.9.5 or explicitly
+      remains a 1.0 blocker; record the quarantine instructions either way.
+
+### Legal, credits and platform policy
+
+- [ ] Audit AI-assisted asset provenance and licenses; record source/model usage and any
+      redistribution constraints for textures, characters, props and UI art.
+- [ ] Audit audio/SFX/music licensing (or confirm everything is procedural) and add a credits file.
+- [ ] Review body-camera/privacy language, mental-health-crisis representation, age/content rating
+      and storefront requirements; fix any release-blocking copy or content.
+- [ ] Add the player-facing credits, known limitations, accessibility statement and privacy note to
+      the release package/README.
+- [ ] Mark external legal/storefront approval as complete or explicitly block 1.0 on it.
+
+### Documentation and visual sign-off
+
+- [ ] Update `README.md`, `PLAN.md`, `docs/architecture.md`, ADRs, `docs/development-status.md`,
+      `docs/getting-started.md`, `docs/smoke-checklist.md`, `CHANGELOG.md` and this roadmap.
+- [ ] Regenerate the full screenshot gallery and realism baselines after content lock; run
+      `check_screenshots.sh` and the pinned vision judge, recording model/spend/verdicts.
+- [ ] Run the manual smoke checklist on every target and attach/link the release-candidate evidence.
+- [ ] Verify the tutorial/campaign/help text at maximum font scale and with the longest strings.
+- [ ] Remove or archive stale plans/notes and confirm no contradictory version/status claims remain.
+
+### Release-candidate QA and exit
+
+- [ ] Run the complete headless suite, Python tooling, tutorial/campaign/session/scenario smokes,
+      24-NPC budget smoke and release build from a clean checkout.
+- [ ] Run the manual QA matrix: fresh install, upgrade, offline launch, gamepad, accessibility
+      settings, pause/resume, all venues and Desktop HQ fallback.
+- [ ] Confirm no P0/P1 defects remain; P2 items must be documented as known limitations or
+      post-1.0 work.
+- [ ] Create the `v0.9.5` version bump, changelog entry and tag; build/publish the release and
+      verify all assets and download links.
+- [ ] Exit: the release candidate is content-locked, externally played, legally reviewed,
+      documented, reproducibly built, and approved as the final stepping stone to 1.0.0.
+
+## Milestone 1.0.0 — Launch
+
+Goal: publish a stable, documented and supportable 1.0 build.
+
+- [ ] Freeze content and version, run full final QA on Windows/Linux/macOS/Web/Desktop HQ, and
+      verify fresh installs plus upgrade paths.
+- [ ] Publish store/release notes, credits, known limitations, accessibility statement and
+      controls; verify every download link and artifact checksum.
+- [ ] Tag `v1.0.0`, publish through CI, verify the release page and post-launch patch policy.
+- [ ] Definition of 1.0: three complete venues with campaign/tutorial, stable save/resume,
+      accessibility/localization acceptance, measured performance on the target matrix, signed
+      release artifacts where platform rules require it, and documentation synchronized with the
+      build.
+
+## Post-1.0 / non-blocking candidates
+
+- [ ] Live 3D body-camera replay.
+- [ ] Additional venues or seasonal events.
+- [ ] Real voice/dialogue audio.
+- [ ] Image-to-mesh prop pipeline.
+- [ ] Rare easter eggs/cameos (e.g. Bob Dobbs) only after core content and QA are stable.
+
+## Roadmap dependencies and risks
+
+- Content volume is the largest schedule risk; tutorial and campaign work must not outrun the
+      event/dialogue matrix.
+- The vision judge is a dev-time aid with an external key/budget; CI must never make it a hard gate.
+- Godot version changes can alter lighting/imports; do not combine an engine baseline move with a
+      content/feature milestone.
+- Signed macOS builds and legal/AI provenance are release blockers, not polish.
+- Keep the de-escalation-first rules and rare-emergency design unchanged while adding progression,
+      difficulty and feedback.
+
+## Realism follow-ups (deferred)
+
+- [x] Re-run the screen-design judge for `12-joke-shop`, `13-studio-arrival` and the
+      Forward+ A/B with the valid key: **13/13 match, 0 diff**; the HQ A/B is in the report.
+- [ ] Capture a hooded/winter NPC close-up once a scenario spawns types 5-7 (the explicit
+      `--portrait-type` override is already in `capture_realism.gd`).
+- [ ] Human-authored tree/hedge silhouettes: the whole scene now reads well except the foliage,
+      which is still flat-shaded clumps (`_shrub()`/`_tree()` in `tools/blender_assets.py`).
+      Only worth doing if a higher-poly organic builder is added to the library.
+- [ ] Camera height: the concept frames are shot at ~1.55 m with a slightly wider lens; the game
+      camera sits at 1.7 m. Decide whether the first-person height should match the art direction
+      or stay at the current gameplay value.
 
 ## Future ideas (optional, not scheduled)
 

assets/models/blender/manifest.json

@@ -287,12 +287,12 @@
       "bounds_godot": {
         "max": [
           0.26,
-          0.225,
+          0.245,
           0.26
         ],
         "min": [
           -0.26,
-          0.015,
+          0.035,
           -0.351
         ]
       },
@@ -453,7 +453,7 @@
         "max": [
           0.321,
           1.824,
-          0.186
+          0.185
         ],
         "min": [
           -0.321,
@@ -467,6 +467,7 @@
         "skin",
         "cloth",
         "pants",
+        "eye_white",
         "accessory",
         "hair",
         "rubber"
@@ -486,18 +487,18 @@
         "accessory",
         "hair"
       ],
-      "triangles": 3788,
-      "vertices": 3107
+      "triangles": 3974,
+      "vertices": 3744
     },
     "npc_coat": {
       "bounds_godot": {
         "max": [
-          0.327,
+          0.332,
           1.824,
-          0.186
+          0.185
         ],
         "min": [
-          -0.327,
+          -0.332,
           0,
           -0.18
         ]
@@ -508,6 +509,7 @@
         "skin",
         "cloth",
         "pants",
+        "eye_white",
         "accessory",
         "hair",
         "rubber"
@@ -526,8 +528,8 @@
         "accessory",
         "hair"
       ],
-      "triangles": 4640,
-      "vertices": 3974
+      "triangles": 5026,
+      "vertices": 4807
     },
     "npc_dress": {
       "bounds_godot": {
@@ -548,6 +550,7 @@
         "skin",
         "cloth",
         "pants",
+        "eye_white",
         "accessory",
         "hair",
         "rubber"
@@ -564,8 +567,8 @@
         "accessory",
         "hair"
       ],
-      "triangles": 4226,
-      "vertices": 3474
+      "triangles": 4428,
+      "vertices": 4026
     },
     "npc_firefighter": {
       "bounds_godot": {
@@ -586,6 +589,7 @@
         "skin",
         "cloth",
         "pants",
+        "eye_white",
         "accessory",
         "hair",
         "hivis",
@@ -604,15 +608,15 @@
         "accessory",
         "hair"
       ],
-      "triangles": 4382,
-      "vertices": 3919
+      "triangles": 4848,
+      "vertices": 4735
     },
     "npc_guard": {
       "bounds_godot": {
         "max": [
           0.361,
           1.819,
-          0.186
+          0.185
         ],
         "min": [
           -0.361,
@@ -626,6 +630,7 @@
         "skin",
         "cloth",
         "pants",
+        "eye_white",
         "accessory",
         "hair",
         "rubber",
@@ -647,15 +652,15 @@
         "accessory",
         "hair"
       ],
-      "triangles": 4154,
-      "vertices": 3838
+      "triangles": 4560,
+      "vertices": 4529
     },
     "npc_hoodie": {
       "bounds_godot": {
         "max": [
           0.326,
           1.856,
-          0.186
+          0.185
         ],
         "min": [
           -0.326,
@@ -669,6 +674,7 @@
         "skin",
         "cloth",
         "pants",
+        "eye_white",
         "accessory",
         "hair",
         "rubber"
@@ -687,18 +693,18 @@
         "accessory",
         "hair"
       ],
-      "triangles": 4640,
-      "vertices": 3954
+      "triangles": 4826,
+      "vertices": 4504
     },
     "npc_jacket": {
       "bounds_godot": {
         "max": [
-          0.326,
+          0.332,
           1.824,
-          0.186
+          0.185
         ],
         "min": [
-          -0.326,
+          -0.332,
           0,
           -0.178
         ]
@@ -709,6 +715,7 @@
         "skin",
         "cloth",
         "pants",
+        "eye_white",
         "accessory",
         "hair",
         "rubber"
@@ -727,15 +734,15 @@
         "accessory",
         "hair"
       ],
-      "triangles": 4016,
-      "vertices": 3415
+      "triangles": 4394,
+      "vertices": 4175
     },
     "npc_vest": {
       "bounds_godot": {
         "max": [
           0.321,
           1.819,
-          0.186
+          0.185
         ],
         "min": [
           -0.321,
@@ -749,6 +756,7 @@
         "skin",
         "cloth",
         "pants",
+        "eye_white",
         "accessory",
         "hair",
         "rubber",
@@ -767,8 +775,8 @@
         "accessory",
         "hair"
       ],
-      "triangles": 4284,
-      "vertices": 3784
+      "triangles": 4474,
+      "vertices": 4340
     },
     "palm_tree": {
       "bounds_godot": {
@@ -993,7 +1001,7 @@
       "attach": "back",
       "bounds_godot": {
         "max": [
-          0.25,
+          0.322,
           0.348,
           0.139
         ],
@@ -1009,7 +1017,7 @@
       ],
       "path": "assets/models/blender/npc_gear/shoulder_bag.glb",
       "triangles": 188,
-      "vertices": 212
+      "vertices": 209
     },
     "stanchion": {
       "bounds_godot": {
@@ -1089,13 +1097,13 @@
       "attach": "head",
       "bounds_godot": {
         "max": [
-          0.141,
-          0.065,
+          0.101,
+          0.059,
           0.158
         ],
         "min": [
-          -0.141,
-          0.005,
+          -0.101,
+          0.011,
           0.003
         ]
       },

content/strings.en.json

@@ -88,5 +88,17 @@
   "review.timeline_button": "Body camera timeline",
   "hud.nearby": "%d nearby · Tab or mouse wheel cycles targets",
   "hud.precision": "Precision walk (Shift)",
-  "hud.controls_gamepad": "Left stick move · Right stick look · A wheel/confirm · B cancel · X inspect · Y radio · LB slow · RB wand"
+  "hud.controls_gamepad": "Left stick move · Right stick look · A wheel/confirm · B cancel · X inspect · Y radio · LB slow · RB wand",
+  "tutorial.header": "FIRST SHIFT",
+  "tutorial.skip_hint": "F1 skip tutorial",
+  "tutorial.arrive": "Walk forward and look around. The entrance is behind you.",
+  "tutorial.focus": "Look at the visitor. Press Tab or the mouse wheel to cycle targets.",
+  "tutorial.wheel": "Open the action wheel with Space or left click.",
+  "tutorial.inspect": "Choose Inspect and read the access evidence.",
+  "tutorial.direction": "Close the panel and give a polite direction.",
+  "tutorial.warning": "Give a formal warning if the visitor persists. It arms the body camera.",
+  "tutorial.radio": "Open the assistance radio and submit a short report.",
+  "tutorial.review": "Finish the shift and review what happened.",
+  "tutorial.completed": "Tutorial complete.",
+  "tutorial.skipped": "Tutorial skipped."
 }

content/venues/hollywood_building.tres

@@ -1,154 +1,47 @@
-[gd_resource type="Resource" script_class="VenueScenario" load_steps=17 format=3]
+[gd_resource type="Resource" script_class="VenueScenario" format=3]
 
-[ext_resource type="Script" path="res://src/core/access_policy.gd" id="1_2u28i"]
-[ext_resource type="Script" path="res://src/core/npc_profile.gd" id="2_acokf"]
-[ext_resource type="Script" path="res://src/core/venue_scenario.gd" id="3_mqiqi"]
+[ext_resource type="Script" path="res://src/core/access_policy.gd" id="1_c5x6v"]
+[ext_resource type="Script" path="res://src/core/npc_profile.gd" id="2_7qk8j"]
+[ext_resource type="Script" path="res://src/core/venue_scenario.gd" id="3_lvgx2"]
 
-[sub_resource type="Resource" id="Resource_i8fga"]
-script = ExtResource("1_2u28i")
+[sub_resource type="Resource" id="Resource_xf4wh"]
+script = ExtResource("1_c5x6v")
 required_artifacts = {
 1: true
 }
-grant_if_any_required = false
-minimum_age = 0
-require_id = false
-wand_screening_required = false
 policy_summary = "Private property. Entry requires recognition or a valid wristband."
 
-[sub_resource type="Resource" id="Resource_c7lhe"]
-script = ExtResource("2_acokf")
+[sub_resource type="Resource" id="Resource_cgh52"]
+script = ExtResource("2_7qk8j")
 id = "tourist"
 display_name = "Tourist"
-npc_type = 0
 temperament = 0.1
 base_compliance = 0.9
-return_probability = 0.0
-reactions_by_level = {}
-default_reactions = {
-1: {
-0: 80,
-2: 8,
-3: 12
-},
-2: {
-0: 70,
-1: 10,
-2: 12,
-4: 8
-},
-3: {
-0: 55,
-1: 15,
-2: 20,
-4: 10
-},
-4: {
-1: 65,
-2: 15,
-7: 20
-},
-5: {
-1: 30,
-5: 40,
-7: 30
-}
-}
-reaction_delay = 0.6
 dialogue_lines = Array[String](["Oh sure, sorry, just taking a picture.", "Is there a better spot to stand?", "Understood, moving."])
-carried_items = Array[String]([])
 
-[sub_resource type="Resource" id="Resource_0t6ar"]
-script = ExtResource("2_acokf")
+[sub_resource type="Resource" id="Resource_qe635"]
+script = ExtResource("2_7qk8j")
 id = "confused_visitor"
 display_name = "Confused Visitor"
 npc_type = 3
 temperament = 0.2
 base_compliance = 0.85
-return_probability = 0.0
-reactions_by_level = {}
-default_reactions = {
-1: {
-0: 80,
-2: 8,
-3: 12
-},
-2: {
-0: 70,
-1: 10,
-2: 12,
-4: 8
-},
-3: {
-0: 55,
-1: 15,
-2: 20,
-4: 10
-},
-4: {
-1: 65,
-2: 15,
-7: 20
-},
-5: {
-1: 30,
-5: 40,
-7: 30
-}
-}
-reaction_delay = 0.6
 dialogue_lines = Array[String](["Wait, this isn't the entrance?", "Sorry about that, I'm a bit lost."])
-carried_items = Array[String]([])
 
-[sub_resource type="Resource" id="Resource_wyv8p"]
-script = ExtResource("2_acokf")
+[sub_resource type="Resource" id="Resource_u5nrp"]
+script = ExtResource("2_7qk8j")
 id = "delivery"
 display_name = "Delivery Worker"
 npc_type = 10
-temperament = 0.25
-base_compliance = 0.8
-return_probability = 0.0
-reactions_by_level = {}
-default_reactions = {
-1: {
-0: 80,
-2: 8,
-3: 12
-},
-2: {
-0: 70,
-1: 10,
-2: 12,
-4: 8
-},
-3: {
-0: 55,
-1: 15,
-2: 20,
-4: 10
-},
-4: {
-1: 65,
-2: 15,
-7: 20
-},
-5: {
-1: 30,
-5: 40,
-7: 30
-}
-}
-reaction_delay = 0.6
 dialogue_lines = Array[String](["Where should I leave this?"])
-carried_items = Array[String]([])
 
-[sub_resource type="Resource" id="Resource_v2hc4"]
-script = ExtResource("2_acokf")
+[sub_resource type="Resource" id="Resource_dsavb"]
+script = ExtResource("2_7qk8j")
 id = "street_performer"
 display_name = "Street Performer"
 npc_type = 1
 temperament = 0.45
 base_compliance = 0.55
-return_probability = 0.0
 reactions_by_level = {
 1: {
 0: 55,
@@ -156,47 +49,14 @@ reactions_by_level = {
 3: 30
 }
 }
-default_reactions = {
-1: {
-0: 80,
-2: 8,
-3: 12
-},
-2: {
-0: 70,
-1: 10,
-2: 12,
-4: 8
-},
-3: {
-0: 55,
-1: 15,
-2: 20,
-4: 10
-},
-4: {
-1: 65,
-2: 15,
-7: 20
-},
-5: {
-1: 30,
-5: 40,
-7: 30
-}
-}
-reaction_delay = 0.6
-dialogue_lines = Array[String]([])
-carried_items = Array[String]([])
 
-[sub_resource type="Resource" id="Resource_lg4td"]
-script = ExtResource("2_acokf")
+[sub_resource type="Resource" id="Resource_sexiy"]
+script = ExtResource("2_7qk8j")
 id = "influencer"
 display_name = "Influencer"
 npc_type = 2
 temperament = 0.5
 base_compliance = 0.5
-return_probability = 0.0
 reactions_by_level = {
 1: {
 0: 40,
@@ -218,47 +78,15 @@ reactions_by_level = {
 8: 25
 }
 }
-default_reactions = {
-1: {
-0: 80,
-2: 8,
-3: 12
-},
-2: {
-0: 70,
-1: 10,
-2: 12,
-4: 8
-},
-3: {
-0: 55,
-1: 15,
-2: 20,
-4: 10
-},
-4: {
-1: 65,
-2: 15,
-7: 20
-},
-5: {
-1: 30,
-5: 40,
-7: 30
-}
-}
-reaction_delay = 0.6
 dialogue_lines = Array[String](["This is public sidewalk, you can't stop me from filming."])
-carried_items = Array[String]([])
 
-[sub_resource type="Resource" id="Resource_ijl2s"]
-script = ExtResource("2_acokf")
+[sub_resource type="Resource" id="Resource_ghqd8"]
+script = ExtResource("2_7qk8j")
 id = "intoxicated"
 display_name = "Intoxicated Pedestrian"
 npc_type = 4
 temperament = 0.6
 base_compliance = 0.4
-return_probability = 0.0
 reactions_by_level = {
 1: {
 0: 30,
@@ -272,41 +100,10 @@ reactions_by_level = {
 4: 10
 }
 }
-default_reactions = {
-1: {
-0: 80,
-2: 8,
-3: 12
-},
-2: {
-0: 70,
-1: 10,
-2: 12,
-4: 8
-},
-3: {
-0: 55,
-1: 15,
-2: 20,
-4: 10
-},
-4: {
-1: 65,
-2: 15,
-7: 20
-},
-5: {
-1: 30,
-5: 40,
-7: 30
-}
-}
 reaction_delay = 1.8
-dialogue_lines = Array[String]([])
-carried_items = Array[String]([])
 
-[sub_resource type="Resource" id="Resource_eycmk"]
-script = ExtResource("2_acokf")
+[sub_resource type="Resource" id="Resource_g8peq"]
+script = ExtResource("2_7qk8j")
 id = "trespasser"
 display_name = "Trespasser"
 npc_type = 5
@@ -341,41 +138,10 @@ reactions_by_level = {
 7: 20
 }
 }
-default_reactions = {
-1: {
-0: 80,
-2: 8,
-3: 12
-},
-2: {
-0: 70,
-1: 10,
-2: 12,
-4: 8
-},
-3: {
-0: 55,
-1: 15,
-2: 20,
-4: 10
-},
-4: {
-1: 65,
-2: 15,
-7: 20
-},
-5: {
-1: 30,
-5: 40,
-7: 30
-}
-}
-reaction_delay = 0.6
 dialogue_lines = Array[String](["I'm just here to see a friend, come on.", "I'll be inside for ten seconds."])
-carried_items = Array[String]([])
 
-[sub_resource type="Resource" id="Resource_ggtpw"]
-script = ExtResource("2_acokf")
+[sub_resource type="Resource" id="Resource_4xl5p"]
+script = ExtResource("2_7qk8j")
 id = "mental_crisis"
 display_name = "Person in Crisis"
 npc_type = 7
@@ -411,47 +177,15 @@ reactions_by_level = {
 7: 15
 }
 }
-default_reactions = {
-1: {
-0: 80,
-2: 8,
-3: 12
-},
-2: {
-0: 70,
-1: 10,
-2: 12,
-4: 8
-},
-3: {
-0: 55,
-1: 15,
-2: 20,
-4: 10
-},
-4: {
-1: 65,
-2: 15,
-7: 20
-},
-5: {
-1: 30,
-5: 40,
-7: 30
-}
-}
 reaction_delay = 2.4
-dialogue_lines = Array[String]([])
-carried_items = Array[String]([])
 
-[sub_resource type="Resource" id="Resource_oa64f"]
-script = ExtResource("2_acokf")
+[sub_resource type="Resource" id="Resource_y6282"]
+script = ExtResource("2_7qk8j")
 id = "violent_threat"
 display_name = "Violent Threat"
 npc_type = 6
 temperament = 0.95
 base_compliance = 0.05
-return_probability = 0.0
 reactions_by_level = {
 1: {
 2: 25,
@@ -479,41 +213,9 @@ reactions_by_level = {
 7: 30
 }
 }
-default_reactions = {
-1: {
-0: 80,
-2: 8,
-3: 12
-},
-2: {
-0: 70,
-1: 10,
-2: 12,
-4: 8
-},
-3: {
-0: 55,
-1: 15,
-2: 20,
-4: 10
-},
-4: {
-1: 65,
-2: 15,
-7: 20
-},
-5: {
-1: 30,
-5: 40,
-7: 30
-}
-}
-reaction_delay = 0.6
-dialogue_lines = Array[String]([])
-carried_items = Array[String]([])
 
-[sub_resource type="Resource" id="Resource_7t7dh"]
-script = ExtResource("2_acokf")
+[sub_resource type="Resource" id="Resource_75a0r"]
+script = ExtResource("2_7qk8j")
 id = "protester"
 display_name = "Protester"
 npc_type = 12
@@ -547,66 +249,28 @@ reactions_by_level = {
 7: 20
 }
 }
-default_reactions = {
-1: {
-0: 80,
-2: 8,
-3: 12
-},
-2: {
-0: 70,
-1: 10,
-2: 12,
-4: 8
-},
-3: {
-0: 55,
-1: 15,
-2: 20,
-4: 10
-},
-4: {
-1: 65,
-2: 15,
-7: 20
-},
-5: {
-1: 30,
-5: 40,
-7: 30
-}
-}
-reaction_delay = 0.6
 dialogue_lines = Array[String](["I have every right to be on public sidewalk.", "You can't touch me, this is a lawful protest."])
-carried_items = Array[String]([])
 
-[sub_resource type="Resource" id="Resource_8tj1k"]
-script = ExtResource("2_acokf")
+[sub_resource type="Resource" id="Resource_ix35t"]
+script = ExtResource("2_7qk8j")
 id = "authorized_staff"
 display_name = "Staff Member"
 npc_type = 8
 temperament = 0.15
 base_compliance = 1.0
-return_probability = 0.0
-reactions_by_level = {}
 default_reactions = {
 1: {
 0: 100
 }
 }
-reaction_delay = 0.6
-dialogue_lines = Array[String]([])
-carried_items = Array[String]([])
 
-[sub_resource type="Resource" id="Resource_tnpxm"]
-script = ExtResource("2_acokf")
+[sub_resource type="Resource" id="Resource_0mcg3"]
+script = ExtResource("2_7qk8j")
 id = "authorized_guest"
 display_name = "Authorized Guest"
 npc_type = 9
 temperament = 0.2
 base_compliance = 0.95
-return_probability = 0.0
-reactions_by_level = {}
 default_reactions = {
 1: {
 0: 92,
@@ -617,16 +281,13 @@ default_reactions = {
 2: 12
 }
 }
-reaction_delay = 0.6
-dialogue_lines = Array[String]([])
-carried_items = Array[String]([])
 
 [resource]
-script = ExtResource("3_mqiqi")
+script = ExtResource("3_lvgx2")
 id = "hollywood_building"
 display_name = "Hollywood Boulevard Building"
 description = "Steps and entrance of a private building off Hollywood Boulevard."
-access_policy = SubResource("Resource_i8fga")
+access_policy = SubResource("Resource_xf4wh")
 equipment = Array[String](["wristband_policy", "flashlight", "radio"])
 locations = {
 "entrance": Vector3(0, 0, 1),
@@ -635,7 +296,7 @@ locations = {
 "sidewalk": Vector3(0, 0, 9),
 "steps_end": Vector3(0, 0, 3)
 }
-npc_profiles = Array[ExtResource("2_acokf")]([SubResource("Resource_c7lhe"), SubResource("Resource_0t6ar"), SubResource("Resource_wyv8p"), SubResource("Resource_v2hc4"), SubResource("Resource_lg4td"), SubResource("Resource_ijl2s"), SubResource("Resource_eycmk"), SubResource("Resource_ggtpw"), SubResource("Resource_oa64f"), SubResource("Resource_7t7dh"), SubResource("Resource_8tj1k"), SubResource("Resource_tnpxm")])
+npc_profiles = Array[ExtResource("2_7qk8j")]([SubResource("Resource_cgh52"), SubResource("Resource_qe635"), SubResource("Resource_u5nrp"), SubResource("Resource_dsavb"), SubResource("Resource_sexiy"), SubResource("Resource_ghqd8"), SubResource("Resource_g8peq"), SubResource("Resource_4xl5p"), SubResource("Resource_y6282"), SubResource("Resource_75a0r"), SubResource("Resource_ix35t"), SubResource("Resource_0mcg3")])
 event_pool = Array[Dictionary]([{
 "base_weight": 1.0,
 "id": "tourist_photo",
@@ -774,6 +435,15 @@ event_pool = Array[Dictionary]([{
 "probability": 0.28,
 "requires_emergency": true,
 "time_range_s": Vector2(760, 880)
+}, {
+"base_weight": 1.0,
+"id": "building_apology_return",
+"intent": "enter",
+"kind": "recovery",
+"npc_type": 9,
+"phase": 2,
+"probability": 0.22,
+"time_range_s": Vector2(620, 800)
 }])
 shift_phases = {
 0: {
@@ -789,6 +459,3 @@ shift_phases = {
 "start_s": 700.0
 }
 }
-shift_duration_s = 900.0
-policy_summary = ""
-door_staff_lines = {}

content/venues/joke_shop.tres

@@ -1,113 +1,59 @@
-[gd_resource type="Resource" script_class="VenueScenario" load_steps=13 format=3]
+[gd_resource type="Resource" script_class="VenueScenario" format=3]
 
-[ext_resource type="Script" path="res://src/core/access_policy.gd" id="1_lxsgk"]
-[ext_resource type="Script" path="res://src/core/npc_profile.gd" id="2_wfc6m"]
-[ext_resource type="Script" path="res://src/core/venue_scenario.gd" id="3_8xm7a"]
+[ext_resource type="Script" path="res://src/core/access_policy.gd" id="1_3pn5m"]
+[ext_resource type="Script" path="res://src/core/npc_profile.gd" id="2_l60ad"]
+[ext_resource type="Script" path="res://src/core/venue_scenario.gd" id="3_voh88"]
 
-[sub_resource type="Resource" id="Resource_xha77"]
-script = ExtResource("1_lxsgk")
+[sub_resource type="Resource" id="Resource_aal3l"]
+script = ExtResource("1_3pn5m")
 required_artifacts = {
 2: true,
 3: true
 }
-grant_if_any_required = false
 minimum_age = 21
 require_id = true
 wand_screening_required = true
 policy_summary = "Government ID and a valid ticket or reservation required. Carry items are screened."
 
-[sub_resource type="Resource" id="Resource_8ksyk"]
-script = ExtResource("2_wfc6m")
+[sub_resource type="Resource" id="Resource_57xgi"]
+script = ExtResource("2_l60ad")
 id = "tourist"
 display_name = "Tourist"
-npc_type = 0
 temperament = 0.1
 base_compliance = 0.9
-return_probability = 0.0
-reactions_by_level = {}
-default_reactions = {
-1: {
-0: 80,
-2: 8,
-3: 12
-},
-2: {
-0: 70,
-1: 10,
-2: 12,
-4: 8
-},
-3: {
-0: 55,
-1: 15,
-2: 20,
-4: 10
-},
-4: {
-1: 65,
-2: 15,
-7: 20
-},
-5: {
-1: 30,
-5: 40,
-7: 30
-}
-}
-reaction_delay = 0.6
 dialogue_lines = Array[String](["Oh sure, sorry, just taking a picture.", "Is there a better spot to stand?", "Understood, moving."])
-carried_items = Array[String]([])
 
-[sub_resource type="Resource" id="Resource_wt1op"]
-script = ExtResource("2_wfc6m")
+[sub_resource type="Resource" id="Resource_r873e"]
+script = ExtResource("2_l60ad")
 id = "confused_visitor"
 display_name = "Confused Visitor"
 npc_type = 3
 temperament = 0.2
 base_compliance = 0.85
-return_probability = 0.0
-reactions_by_level = {}
-default_reactions = {
-1: {
-0: 80,
-2: 8,
-3: 12
-},
-2: {
-0: 70,
-1: 10,
-2: 12,
-4: 8
-},
-3: {
-0: 55,
-1: 15,
-2: 20,
-4: 10
-},
-4: {
-1: 65,
-2: 15,
-7: 20
-},
-5: {
-1: 30,
-5: 40,
-7: 30
-}
-}
-reaction_delay = 0.6
 dialogue_lines = Array[String](["Wait, this isn't the entrance?", "Sorry about that, I'm a bit lost."])
-carried_items = Array[String]([])
 
-[sub_resource type="Resource" id="Resource_g1jr2"]
-script = ExtResource("2_wfc6m")
+[sub_resource type="Resource" id="Resource_3xy2u"]
+script = ExtResource("2_l60ad")
+id = "street_performer"
+display_name = "Street Performer"
+npc_type = 1
+temperament = 0.45
+base_compliance = 0.55
+reactions_by_level = {
+1: {
+0: 55,
+2: 15,
+3: 30
+}
+}
+
+[sub_resource type="Resource" id="Resource_50i1h"]
+script = ExtResource("2_l60ad")
 id = "influencer"
 display_name = "Influencer"
 npc_type = 2
 temperament = 0.5
 base_compliance = 0.5
-return_probability = 0.0
 reactions_by_level = {
 1: {
 0: 40,
@@ -129,47 +75,15 @@ reactions_by_level = {
 8: 25
 }
 }
-default_reactions = {
-1: {
-0: 80,
-2: 8,
-3: 12
-},
-2: {
-0: 70,
-1: 10,
-2: 12,
-4: 8
-},
-3: {
-0: 55,
-1: 15,
-2: 20,
-4: 10
-},
-4: {
-1: 65,
-2: 15,
-7: 20
-},
-5: {
-1: 30,
-5: 40,
-7: 30
-}
-}
-reaction_delay = 0.6
 dialogue_lines = Array[String](["This is public sidewalk, you can't stop me from filming."])
-carried_items = Array[String]([])
 
-[sub_resource type="Resource" id="Resource_ys0b0"]
-script = ExtResource("2_wfc6m")
+[sub_resource type="Resource" id="Resource_nsw77"]
+script = ExtResource("2_l60ad")
 id = "intoxicated"
 display_name = "Intoxicated Pedestrian"
 npc_type = 4
 temperament = 0.6
 base_compliance = 0.4
-return_probability = 0.0
 reactions_by_level = {
 1: {
 0: 30,
@@ -183,41 +97,10 @@ reactions_by_level = {
 4: 10
 }
 }
-default_reactions = {
-1: {
-0: 80,
-2: 8,
-3: 12
-},
-2: {
-0: 70,
-1: 10,
-2: 12,
-4: 8
-},
-3: {
-0: 55,
-1: 15,
-2: 20,
-4: 10
-},
-4: {
-1: 65,
-2: 15,
-7: 20
-},
-5: {
-1: 30,
-5: 40,
-7: 30
-}
-}
 reaction_delay = 1.8
-dialogue_lines = Array[String]([])
-carried_items = Array[String]([])
 
-[sub_resource type="Resource" id="Resource_bv0jw"]
-script = ExtResource("2_wfc6m")
+[sub_resource type="Resource" id="Resource_20knl"]
+script = ExtResource("2_l60ad")
 id = "trespasser"
 display_name = "Trespasser"
 npc_type = 5
@@ -252,47 +135,15 @@ reactions_by_level = {
 7: 20
 }
 }
-default_reactions = {
-1: {
-0: 80,
-2: 8,
-3: 12
-},
-2: {
-0: 70,
-1: 10,
-2: 12,
-4: 8
-},
-3: {
-0: 55,
-1: 15,
-2: 20,
-4: 10
-},
-4: {
-1: 65,
-2: 15,
-7: 20
-},
-5: {
-1: 30,
-5: 40,
-7: 30
-}
-}
-reaction_delay = 0.6
 dialogue_lines = Array[String](["I'm just here to see a friend, come on.", "I'll be inside for ten seconds."])
-carried_items = Array[String]([])
 
-[sub_resource type="Resource" id="Resource_7vgx3"]
-script = ExtResource("2_wfc6m")
+[sub_resource type="Resource" id="Resource_rivis"]
+script = ExtResource("2_l60ad")
 id = "violent_threat"
 display_name = "Violent Threat"
 npc_type = 6
 temperament = 0.95
 base_compliance = 0.05
-return_probability = 0.0
 reactions_by_level = {
 1: {
 2: 25,
@@ -320,66 +171,27 @@ reactions_by_level = {
 7: 30
 }
 }
-default_reactions = {
-1: {
-0: 80,
-2: 8,
-3: 12
-},
-2: {
-0: 70,
-1: 10,
-2: 12,
-4: 8
-},
-3: {
-0: 55,
-1: 15,
-2: 20,
-4: 10
-},
-4: {
-1: 65,
-2: 15,
-7: 20
-},
-5: {
-1: 30,
-5: 40,
-7: 30
-}
-}
-reaction_delay = 0.6
-dialogue_lines = Array[String]([])
-carried_items = Array[String]([])
 
-[sub_resource type="Resource" id="Resource_x43ed"]
-script = ExtResource("2_wfc6m")
+[sub_resource type="Resource" id="Resource_1dvkp"]
+script = ExtResource("2_l60ad")
 id = "authorized_staff"
 display_name = "Staff Member"
 npc_type = 8
 temperament = 0.15
 base_compliance = 1.0
-return_probability = 0.0
-reactions_by_level = {}
 default_reactions = {
 1: {
 0: 100
 }
 }
-reaction_delay = 0.6
-dialogue_lines = Array[String]([])
-carried_items = Array[String]([])
 
-[sub_resource type="Resource" id="Resource_07lsg"]
-script = ExtResource("2_wfc6m")
+[sub_resource type="Resource" id="Resource_7wsm0"]
+script = ExtResource("2_l60ad")
 id = "authorized_guest"
 display_name = "Authorized Guest"
 npc_type = 9
 temperament = 0.2
 base_compliance = 0.95
-return_probability = 0.0
-reactions_by_level = {}
 default_reactions = {
 1: {
 0: 92,
@@ -390,16 +202,13 @@ default_reactions = {
 2: 12
 }
 }
-reaction_delay = 0.6
-dialogue_lines = Array[String]([])
-carried_items = Array[String]([])
 
 [resource]
-script = ExtResource("3_8xm7a")
+script = ExtResource("3_voh88")
 id = "joke_shop"
 display_name = "The Joke Shop"
 description = "Comedy club door: IDs, reservations, and wand screening."
-access_policy = SubResource("Resource_xha77")
+access_policy = SubResource("Resource_aal3l")
 equipment = Array[String](["id_check", "guest_list", "wand", "radio"])
 locations = {
 "door_area": Vector3(0, 0, 3),
@@ -409,7 +218,7 @@ locations = {
 "sidewalk": Vector3(0, 0, 9),
 "steps_end": Vector3(0, 0, 3)
 }
-npc_profiles = Array[ExtResource("2_wfc6m")]([SubResource("Resource_8ksyk"), SubResource("Resource_wt1op"), SubResource("Resource_g1jr2"), SubResource("Resource_ys0b0"), SubResource("Resource_bv0jw"), SubResource("Resource_7vgx3"), SubResource("Resource_x43ed"), SubResource("Resource_07lsg")])
+npc_profiles = Array[ExtResource("2_l60ad")]([SubResource("Resource_57xgi"), SubResource("Resource_r873e"), SubResource("Resource_3xy2u"), SubResource("Resource_50i1h"), SubResource("Resource_nsw77"), SubResource("Resource_20knl"), SubResource("Resource_rivis"), SubResource("Resource_1dvkp"), SubResource("Resource_7wsm0")])
 event_pool = Array[Dictionary]([{
 "base_weight": 1.0,
 "id": "guest_valid",
@@ -564,6 +373,19 @@ event_pool = Array[Dictionary]([{
 "phase": 2,
 "probability": 0.5,
 "time_range_s": Vector2(650, 830)
+}, {
+"base_weight": 1.0,
+"id": "joke_denied_guest_return",
+"intent": "enter",
+"kind": "recovery",
+"npc_type": 9,
+"override_access": {
+"has_id": true,
+"has_ticket": true
+},
+"phase": 2,
+"probability": 0.2,
+"time_range_s": Vector2(650, 830)
 }])
 shift_phases = {
 0: {
@@ -579,8 +401,6 @@ shift_phases = {
 "start_s": 700.0
 }
 }
-shift_duration_s = 900.0
-policy_summary = ""
 door_staff_lines = {
 "id_check": ["May I see your ID, please?", "Could you show me some identification?"],
 "prohibited_item": ["I can't allow that item inside. Please leave it outside.", "That item isn't permitted in the venue."],

content/venues/tv_studio.tres

@@ -1,11 +1,11 @@
-[gd_resource type="Resource" script_class="VenueScenario" load_steps=17 format=3]
+[gd_resource type="Resource" script_class="VenueScenario" format=3]
 
-[ext_resource type="Script" path="res://src/core/access_policy.gd" id="1_xxhx3"]
-[ext_resource type="Script" path="res://src/core/npc_profile.gd" id="2_fiebn"]
-[ext_resource type="Script" path="res://src/core/venue_scenario.gd" id="3_2dvuq"]
+[ext_resource type="Script" path="res://src/core/access_policy.gd" id="1_3vwd0"]
+[ext_resource type="Script" path="res://src/core/npc_profile.gd" id="2_g7rkt"]
+[ext_resource type="Script" path="res://src/core/venue_scenario.gd" id="3_jd45y"]
 
-[sub_resource type="Resource" id="Resource_blmt0"]
-script = ExtResource("1_xxhx3")
+[sub_resource type="Resource" id="Resource_c55bb"]
+script = ExtResource("1_3vwd0")
 required_artifacts = {
 1: true,
 3: true,
@@ -13,145 +13,39 @@ required_artifacts = {
 5: true
 }
 grant_if_any_required = true
-minimum_age = 0
-require_id = false
-wand_screening_required = false
 policy_summary = "Entry requires a wristband, credential, ticket, or guest-list confirmation."
 
-[sub_resource type="Resource" id="Resource_oddac"]
-script = ExtResource("2_fiebn")
+[sub_resource type="Resource" id="Resource_yyxim"]
+script = ExtResource("2_g7rkt")
 id = "tourist"
 display_name = "Tourist"
-npc_type = 0
 temperament = 0.1
 base_compliance = 0.9
-return_probability = 0.0
-reactions_by_level = {}
-default_reactions = {
-1: {
-0: 80,
-2: 8,
-3: 12
-},
-2: {
-0: 70,
-1: 10,
-2: 12,
-4: 8
-},
-3: {
-0: 55,
-1: 15,
-2: 20,
-4: 10
-},
-4: {
-1: 65,
-2: 15,
-7: 20
-},
-5: {
-1: 30,
-5: 40,
-7: 30
-}
-}
-reaction_delay = 0.6
 dialogue_lines = Array[String](["Oh sure, sorry, just taking a picture.", "Is there a better spot to stand?", "Understood, moving."])
-carried_items = Array[String]([])
 
-[sub_resource type="Resource" id="Resource_byir2"]
-script = ExtResource("2_fiebn")
+[sub_resource type="Resource" id="Resource_lmn2c"]
+script = ExtResource("2_g7rkt")
 id = "confused_visitor"
 display_name = "Confused Visitor"
 npc_type = 3
 temperament = 0.2
 base_compliance = 0.85
-return_probability = 0.0
-reactions_by_level = {}
-default_reactions = {
-1: {
-0: 80,
-2: 8,
-3: 12
-},
-2: {
-0: 70,
-1: 10,
-2: 12,
-4: 8
-},
-3: {
-0: 55,
-1: 15,
-2: 20,
-4: 10
-},
-4: {
-1: 65,
-2: 15,
-7: 20
-},
-5: {
-1: 30,
-5: 40,
-7: 30
-}
-}
-reaction_delay = 0.6
 dialogue_lines = Array[String](["Wait, this isn't the entrance?", "Sorry about that, I'm a bit lost."])
-carried_items = Array[String]([])
 
-[sub_resource type="Resource" id="Resource_3tt0b"]
-script = ExtResource("2_fiebn")
+[sub_resource type="Resource" id="Resource_if2cj"]
+script = ExtResource("2_g7rkt")
 id = "delivery"
 display_name = "Delivery Worker"
 npc_type = 10
-temperament = 0.25
-base_compliance = 0.8
-return_probability = 0.0
-reactions_by_level = {}
-default_reactions = {
-1: {
-0: 80,
-2: 8,
-3: 12
-},
-2: {
-0: 70,
-1: 10,
-2: 12,
-4: 8
-},
-3: {
-0: 55,
-1: 15,
-2: 20,
-4: 10
-},
-4: {
-1: 65,
-2: 15,
-7: 20
-},
-5: {
-1: 30,
-5: 40,
-7: 30
-}
-}
-reaction_delay = 0.6
 dialogue_lines = Array[String](["Where should I leave this?"])
-carried_items = Array[String]([])
 
-[sub_resource type="Resource" id="Resource_ihxib"]
-script = ExtResource("2_fiebn")
+[sub_resource type="Resource" id="Resource_t47d3"]
+script = ExtResource("2_g7rkt")
 id = "street_performer"
 display_name = "Street Performer"
 npc_type = 1
 temperament = 0.45
 base_compliance = 0.55
-return_probability = 0.0
 reactions_by_level = {
 1: {
 0: 55,
@@ -159,47 +53,14 @@ reactions_by_level = {
 3: 30
 }
 }
-default_reactions = {
-1: {
-0: 80,
-2: 8,
-3: 12
-},
-2: {
-0: 70,
-1: 10,
-2: 12,
-4: 8
-},
-3: {
-0: 55,
-1: 15,
-2: 20,
-4: 10
-},
-4: {
-1: 65,
-2: 15,
-7: 20
-},
-5: {
-1: 30,
-5: 40,
-7: 30
-}
-}
-reaction_delay = 0.6
-dialogue_lines = Array[String]([])
-carried_items = Array[String]([])
 
-[sub_resource type="Resource" id="Resource_c57iy"]
-script = ExtResource("2_fiebn")
+[sub_resource type="Resource" id="Resource_j2mp5"]
+script = ExtResource("2_g7rkt")
 id = "influencer"
 display_name = "Influencer"
 npc_type = 2
 temperament = 0.5
 base_compliance = 0.5
-return_probability = 0.0
 reactions_by_level = {
 1: {
 0: 40,
@@ -221,47 +82,15 @@ reactions_by_level = {
 8: 25
 }
 }
-default_reactions = {
-1: {
-0: 80,
-2: 8,
-3: 12
-},
-2: {
-0: 70,
-1: 10,
-2: 12,
-4: 8
-},
-3: {
-0: 55,
-1: 15,
-2: 20,
-4: 10
-},
-4: {
-1: 65,
-2: 15,
-7: 20
-},
-5: {
-1: 30,
-5: 40,
-7: 30
-}
-}
-reaction_delay = 0.6
 dialogue_lines = Array[String](["This is public sidewalk, you can't stop me from filming."])
-carried_items = Array[String]([])
 
-[sub_resource type="Resource" id="Resource_bk410"]
-script = ExtResource("2_fiebn")
+[sub_resource type="Resource" id="Resource_uscqg"]
+script = ExtResource("2_g7rkt")
 id = "intoxicated"
 display_name = "Intoxicated Pedestrian"
 npc_type = 4
 temperament = 0.6
 base_compliance = 0.4
-return_probability = 0.0
 reactions_by_level = {
 1: {
 0: 30,
@@ -275,41 +104,10 @@ reactions_by_level = {
 4: 10
 }
 }
-default_reactions = {
-1: {
-0: 80,
-2: 8,
-3: 12
-},
-2: {
-0: 70,
-1: 10,
-2: 12,
-4: 8
-},
-3: {
-0: 55,
-1: 15,
-2: 20,
-4: 10
-},
-4: {
-1: 65,
-2: 15,
-7: 20
-},
-5: {
-1: 30,
-5: 40,
-7: 30
-}
-}
 reaction_delay = 1.8
-dialogue_lines = Array[String]([])
-carried_items = Array[String]([])
 
-[sub_resource type="Resource" id="Resource_jp52w"]
-script = ExtResource("2_fiebn")
+[sub_resource type="Resource" id="Resource_8aovb"]
+script = ExtResource("2_g7rkt")
 id = "trespasser"
 display_name = "Trespasser"
 npc_type = 5
@@ -344,41 +142,10 @@ reactions_by_level = {
 7: 20
 }
 }
-default_reactions = {
-1: {
-0: 80,
-2: 8,
-3: 12
-},
-2: {
-0: 70,
-1: 10,
-2: 12,
-4: 8
-},
-3: {
-0: 55,
-1: 15,
-2: 20,
-4: 10
-},
-4: {
-1: 65,
-2: 15,
-7: 20
-},
-5: {
-1: 30,
-5: 40,
-7: 30
-}
-}
-reaction_delay = 0.6
 dialogue_lines = Array[String](["I'm just here to see a friend, come on.", "I'll be inside for ten seconds."])
-carried_items = Array[String]([])
 
-[sub_resource type="Resource" id="Resource_5kplf"]
-script = ExtResource("2_fiebn")
+[sub_resource type="Resource" id="Resource_owl7s"]
+script = ExtResource("2_g7rkt")
 id = "mental_crisis"
 display_name = "Person in Crisis"
 npc_type = 7
@@ -414,47 +181,15 @@ reactions_by_level = {
 7: 15
 }
 }
-default_reactions = {
-1: {
-0: 80,
-2: 8,
-3: 12
-},
-2: {
-0: 70,
-1: 10,
-2: 12,
-4: 8
-},
-3: {
-0: 55,
-1: 15,
-2: 20,
-4: 10
-},
-4: {
-1: 65,
-2: 15,
-7: 20
-},
-5: {
-1: 30,
-5: 40,
-7: 30
-}
-}
 reaction_delay = 2.4
-dialogue_lines = Array[String]([])
-carried_items = Array[String]([])
 
-[sub_resource type="Resource" id="Resource_6bscs"]
-script = ExtResource("2_fiebn")
+[sub_resource type="Resource" id="Resource_rnay4"]
+script = ExtResource("2_g7rkt")
 id = "violent_threat"
 display_name = "Violent Threat"
 npc_type = 6
 temperament = 0.95
 base_compliance = 0.05
-return_probability = 0.0
 reactions_by_level = {
 1: {
 2: 25,
@@ -482,41 +217,9 @@ reactions_by_level = {
 7: 30
 }
 }
-default_reactions = {
-1: {
-0: 80,
-2: 8,
-3: 12
-},
-2: {
-0: 70,
-1: 10,
-2: 12,
-4: 8
-},
-3: {
-0: 55,
-1: 15,
-2: 20,
-4: 10
-},
-4: {
-1: 65,
-2: 15,
-7: 20
-},
-5: {
-1: 30,
-5: 40,
-7: 30
-}
-}
-reaction_delay = 0.6
-dialogue_lines = Array[String]([])
-carried_items = Array[String]([])
 
-[sub_resource type="Resource" id="Resource_n4lxh"]
-script = ExtResource("2_fiebn")
+[sub_resource type="Resource" id="Resource_lhp4m"]
+script = ExtResource("2_g7rkt")
 id = "protester"
 display_name = "Protester"
 npc_type = 12
@@ -550,66 +253,28 @@ reactions_by_level = {
 7: 20
 }
 }
-default_reactions = {
-1: {
-0: 80,
-2: 8,
-3: 12
-},
-2: {
-0: 70,
-1: 10,
-2: 12,
-4: 8
-},
-3: {
-0: 55,
-1: 15,
-2: 20,
-4: 10
-},
-4: {
-1: 65,
-2: 15,
-7: 20
-},
-5: {
-1: 30,
-5: 40,
-7: 30
-}
-}
-reaction_delay = 0.6
 dialogue_lines = Array[String](["I have every right to be on public sidewalk.", "You can't touch me, this is a lawful protest."])
-carried_items = Array[String]([])
 
-[sub_resource type="Resource" id="Resource_6st6l"]
-script = ExtResource("2_fiebn")
+[sub_resource type="Resource" id="Resource_s8tjd"]
+script = ExtResource("2_g7rkt")
 id = "authorized_staff"
 display_name = "Staff Member"
 npc_type = 8
 temperament = 0.15
 base_compliance = 1.0
-return_probability = 0.0
-reactions_by_level = {}
 default_reactions = {
 1: {
 0: 100
 }
 }
-reaction_delay = 0.6
-dialogue_lines = Array[String]([])
-carried_items = Array[String]([])
 
-[sub_resource type="Resource" id="Resource_nf2oq"]
-script = ExtResource("2_fiebn")
+[sub_resource type="Resource" id="Resource_ii8kq"]
+script = ExtResource("2_g7rkt")
 id = "authorized_guest"
 display_name = "Authorized Guest"
 npc_type = 9
 temperament = 0.2
 base_compliance = 0.95
-return_probability = 0.0
-reactions_by_level = {}
 default_reactions = {
 1: {
 0: 92,
@@ -620,16 +285,13 @@ default_reactions = {
 2: 12
 }
 }
-reaction_delay = 0.6
-dialogue_lines = Array[String]([])
-carried_items = Array[String]([])
 
 [resource]
-script = ExtResource("3_2dvuq")
+script = ExtResource("3_jd45y")
 id = "tv_studio"
 display_name = "Hollywood Blvd Late Night TV Studio"
 description = "Crowd, celebrities, and staff around a late-night studio."
-access_policy = SubResource("Resource_blmt0")
+access_policy = SubResource("Resource_c55bb")
 equipment = Array[String](["wristband_policy", "guest_list", "radio", "flashlight"])
 locations = {
 "entrance": Vector3(0, 0, 1),
@@ -639,7 +301,7 @@ locations = {
 "stage_door": Vector3(6, 0, -2),
 "steps_end": Vector3(0, 0, 3)
 }
-npc_profiles = Array[ExtResource("2_fiebn")]([SubResource("Resource_oddac"), SubResource("Resource_byir2"), SubResource("Resource_3tt0b"), SubResource("Resource_ihxib"), SubResource("Resource_c57iy"), SubResource("Resource_bk410"), SubResource("Resource_jp52w"), SubResource("Resource_5kplf"), SubResource("Resource_6bscs"), SubResource("Resource_n4lxh"), SubResource("Resource_6st6l"), SubResource("Resource_nf2oq")])
+npc_profiles = Array[ExtResource("2_g7rkt")]([SubResource("Resource_yyxim"), SubResource("Resource_lmn2c"), SubResource("Resource_if2cj"), SubResource("Resource_t47d3"), SubResource("Resource_j2mp5"), SubResource("Resource_uscqg"), SubResource("Resource_8aovb"), SubResource("Resource_owl7s"), SubResource("Resource_rnay4"), SubResource("Resource_lhp4m"), SubResource("Resource_s8tjd"), SubResource("Resource_ii8kq")])
 event_pool = Array[Dictionary]([{
 "base_weight": 1.0,
 "id": "audience_ticket",
@@ -790,6 +452,15 @@ event_pool = Array[Dictionary]([{
 "phase": 2,
 "probability": 0.45,
 "time_range_s": Vector2(700, 860)
+}, {
+"base_weight": 1.0,
+"id": "studio_manager_check",
+"intent": "enter",
+"kind": "recovery",
+"npc_type": 8,
+"phase": 2,
+"probability": 0.2,
+"time_range_s": Vector2(620, 820)
 }])
 shift_phases = {
 0: {
@@ -805,6 +476,3 @@ shift_phases = {
 "start_s": 700.0
 }
 }
-shift_duration_s = 900.0
-policy_summary = ""
-door_staff_lines = {}

docs/RELEASING.md

@@ -12,10 +12,11 @@ time you export, either:
   matching templates), or
 - Install them manually from the
   [Godot downloads](https://godotengine.org/download/) page by placing the
-  `Godot_v4.3-stable_export_templates.tpz` contents into
-  `~/.local/share/godot/export_templates/4.3.stable/`.
+  `Godot_v4.7.2-stable_export_templates.tpz` contents into
+  `~/.local/share/godot/export_templates/4.7.2.stable/`.
 
-Verify with:
+The templates must match the editor binary you use locally. CI and local
+development both use Godot 4.7.2 with its matching templates. Verify with:
 
 ```bash
 godot --headless --export-release "Linux" build/gig-line-smoke.x86_64
@@ -30,7 +31,7 @@ godot --headless --export-release "Linux" build/gig-line-smoke.x86_64
 
 The repository ships a Gitea Actions workflow (`.gitea/workflows/build.yml`):
 
-- Every push/PR runs the **checks** job: Godot 4.3 install, project import, and the
+- Every push/PR runs the **checks** job: Godot 4.7.2 install, project import, and the
   full headless test suite. This is the fast safety net.
 - **Tags (`v*`)** and **manual `workflow_dispatch`** runs additionally execute the
   **build** job: export templates install, import, `tools/build_releases.sh` for
@@ -62,10 +63,10 @@ setup, so do not rely on it.
 > artifacts. If CI publishing fails again, run
 > `./tools/publish_release.sh <version>` from a checkout with `~/.git-credentials`.
 
-> **No `actions/cache` for now:** the runner has no local actions-cache service, so
-> `actions/cache` times out against GitHub's cache API. We dropped it (Godot import
-> is only ~4s). If a host admin later enables Gitea `[cache.actions]` with a cache
-> server, the step can be reintroduced.
+> **Godot cache:** the workflow uses Gitea Actions cache for the Godot binary and the
+> 4.7.2 export templates. The first run still downloads them; subsequent runs restore
+> from cache. If the host cache service is unavailable, remove the cache steps and
+> let the install steps download fresh copies.
 
 > The workflow lives in `.gitea/workflows/` (Gitea's canonical path). The old
 > `.github/workflows/ci.yml` was removed to avoid double runs on hosts that scan
@@ -86,6 +87,8 @@ Artifacts are written to `build/` (all exports embed the PCK — single files):
 - `build/gig-line-macos-<version>.zip`
 - `build/gig-line-web-<version>.zip` — browser build (non-threaded Godot web
   template; unzip and serve the folder, no COOP/COEP headers required)
+- `build/gig-line-desktop-hq-<version>.zip` — optional Forward+ Windows/Linux
+  build with `override.cfg`; requires a Vulkan-capable GPU/driver
 
 When run in CI (tags/dispatch), the build job also packages:
 
@@ -94,6 +97,10 @@ When run in CI (tags/dispatch), the build job also packages:
 - `build/gig-line-<version>-x86_64.AppImage` — Linux AppImage (`packaging/linux/build_appimage.sh`,
   appimagetool via `APPIMAGE_EXTRACT_AND_RUN`)
 
+The optional Desktop HQ zip is assembled by `tools/build_releases.sh` from
+`packaging/desktop_hq/`; keep `override.cfg` next to the extracted executable.
+It is not part of the default Compatibility/Web build.
+
 Locally you can build the AppImage with `bash packaging/linux/build_appimage.sh <version>`;
 the NSIS installer requires `makensis` (covered by CI).
 
@@ -114,19 +121,21 @@ GITEA_TOKEN=your_api_token ./tools/publish_release.sh 0.2.1
 
 The script creates (or reuses) the release from `project.godot`'s
 `config/version`, uploads the three portable artifacts **plus** the NSIS
-installer and AppImage when present, and prints the release URL. If CI already
+installer, AppImage, Web zip and Desktop HQ zip when present, and prints the
+release URL. If CI already
 published the release, re-running the script only adds missing assets.
 
 > **Host note**: the release is fully built by CI, but anonymous users can only
 > browse and download when the instance sets `[service] REQUIRE_SIGNIN_VIEW=false`
-> in `app.ini` (the repo itself is public). See the TODO for the exact steps.
+> in `app.ini` (the repo itself is public). This is a host-admin setting, not a
+> repository file.
 
 Manual alternative:
 
 ### Via the web UI
 
 1. Create a **New Release** with tag `v<version>`.
-2. Attach all three `build/` artifacts.
+2. Attach all artifacts from `build/` (portables, installer/AppImage, Web and optional Desktop HQ).
 3. Write release notes (see checklist below).
 
 ### Via the API
@@ -163,7 +172,7 @@ change, update `tools/build_releases.sh` first.
 
 - [ ] All headless tests pass (exit code 0).
 - [ ] Game boots cleanly in a smoke test.
-- [ ] Controls documented in `README.md` match the build.
+- [ ] Controls documented in `docs/getting-started.md` match the build.
 - [ ] Version in `project.godot` matches the tag.
 - [ ] Export templates used are the official ones for the pinned engine.
 - [ ] Artifacts uploaded; README downloads page shows them.

docs/architecture.md

@@ -20,11 +20,12 @@ This document follows the structure of the arc42 architecture documentation temp
 - **Testability:** Rules and outcomes should be testable without rendering or real-time input.
 - **Consistency:** Similar situations should follow predictable venue and escalation rules.
 - **Respectful representation:** Mental-health crises and public interactions should not be reduced to stereotypes or treated as automatic threats.
+- **Realism:** The game world should look like the real world and NPC behaviors should feel consistent and believable within the established setting.
 
 ## 2. Constraints
 
 - The first implementation should be small enough for a playable vertical slice.
-- The engine is Godot 4 with GDScript; a playable prototype vertical slice is implemented.
+- The engine is Godot 4.7.2 with GDScript; a playable prototype vertical slice is implemented. CI, local development and exported builds use 4.7.2; the default renderer stays GL Compatibility for Web parity, with an optional Forward+ Desktop HQ build.
 - Venue-specific policies must be configurable rather than hard-coded into individual NPCs.
 - The game must preserve the de-escalation-first design described in [`PLAN.md`](../PLAN.md).
 - The project uses the repository workflow described in [`AGENTS.md`](../AGENTS.md).
@@ -36,7 +37,7 @@ This document follows the structure of the arc42 architecture documentation temp
 - **MINOR** — new venues, NPC archetypes, systems, or features that are backward compatible.
 - **PATCH** — bug fixes and small polish that do not change behavior.
 
-The single source of truth for the version is `config/version` in `project.godot` (currently `0.1.0`). Each release is tagged in git as `v<version>` (e.g. `v0.1.0`). The `0.x` series is pre-1.0, so MINOR bumps may introduce breaking changes while the prototype is still stabilizing. `tools/build_releases.sh` and `tools/publish_release.sh` read the version from `project.godot`, so bumping it there is the only required step before a release. The full bump checklist lives in [`RELEASING.md`](RELEASING.md).
+The single source of truth for the version is `config/version` in `project.godot` (currently `0.9.1`). Each release is tagged in git as `v<version>` (e.g. `v0.6.0`). The `0.x` series is pre-1.0, so MINOR bumps may introduce breaking changes while the prototype is still stabilizing. `tools/build_releases.sh` and `tools/publish_release.sh` read the version from `project.godot`, so bumping it there is the only required step before a release. The full bump checklist lives in [`RELEASING.md`](RELEASING.md).
 
 ## 3. Context and Scope
 
@@ -77,12 +78,13 @@ The player interacts with NPCs, venue entrances, access artifacts, equipment, st
 - `CrowdSystem` models queues, attention, congestion, and public reaction.
 - `ShiftReview` presents decisions, consequences, and improvement opportunities.
 - `SurfaceMaterials` (`src/game/materials.gd`) holds the surface profiles, textured albedo/normal recipes, baked-AO wiring, glass/emissive recipes, and the environment tune-up (tonemapping, glow, fog, grading) that the phase lighting applies.
-- `WorldBuilder` assembles the procedural venue and instantiates the generated prop models from `assets/models/generated/` with a procedural fallback.
+- `WorldBuilder` assembles the procedural venue from a per-venue `VENUE_SPECS` table (facade, windows, stairs, street, nav bounds, guard spawn, feature flags and prop placements), prefers the Blender prop library in `assets/models/blender/props/`, and falls back to `assets/models/generated/` or primitives. `GameManager` rebuilds only the `World` container when the venue changes, so the guard/UI and their state survive. It also wires the phase-driven library emissives and street dressing.
+- `src/game/ui/art.gd` loads runtime UI/scene art from `assets/images/ui/` and `assets/images/scenes/`, with null fallbacks so panels keep their procedural layouts.
 - `tools/model_pipeline.py` builds and audits the street-prop `.glb` models and packs their colour atlases.
 - `tools/npc_pipeline.py` builds and audits the skinned NPC base model (`assets/models/generated/npc_base.glb`) and its per-slot material maps, with an optional AI fabric override (ADR-0013).
 - `tools/blender_assets.py` builds, renders and audits the Blender asset library (`assets/models/blender/{npc,npc_gear,props}/` + `manifest.json`): NPC character variants that are drop-in for `npc_base`, attach-point gear, and street/venue props. `NpcAvatar` selects variants/gear by role/seed and `WorldBuilder` loads the prop replacements and new street dressing, with procedural fallbacks (see `docs/blender-assets.md`).
-- `tools/scene_concepts.py` generates realism-pass references (`docs/screens/concepts/`), skyline backdrops and surface tiles (raw `assets/textures/ai/v2/raw/` → candidates `assets/textures/ai/game_ready/v2/`), promotes the validated ones to the tracked `v2/picks/` that `SurfaceMaterials`/`WorldBuilder` preload, audits them, and scores `src/test/capture_realism.gd` A/B captures (five stages, runtime texture swaps) against the concepts (`docs/screens/realism/<run>/`).
-- `tools/asset_pipeline.py` generates and audits role-aware textures; `tools/screen_designs.py` generates screen references and judges captures.
+- `tools/scene_concepts.py` generates realism-pass references (`docs/screens/concepts/`), skyline backdrops and surface tiles (raw `assets/textures/ai/v2/raw/` → candidates `assets/textures/ai/game_ready/v2/`), promotes the validated ones to the tracked `v2/picks/` that `SurfaceMaterials`/`WorldBuilder` preload, audits them, and scores `src/test/capture_realism.gd` A/B captures (six stages, runtime texture swaps) against the concepts (`docs/screens/realism/<run>/`).
+- `tools/asset_pipeline.py` generates and audits role-aware textures; `tools/screen_designs.py` generates screen references and judges captures; `tools/check_screenshots.sh` renders the staged gallery and runs the compare gate.
 
 Confirmed game assets live in `assets/textures/ai/game_ready/` (audited surface, UI, and card textures), `assets/models/generated/` (prop and NPC `.glb` models plus their texture atlases), and `assets/textures/npc/` (NPC material maps and `palette.json`). Development-only outputs — AI concept sheets, Blender sources, raw AI fabrics — are gitignored and regenerated by the tools.
 
@@ -104,6 +106,36 @@ When reference art becomes runtime art, copy or process it into `assets/images/`
 new descriptive name (never overwrite an existing image) and keep a procedural fallback
 in code.
 
+### Content and asset pipeline architecture
+
+The asset/content pipeline is part of the architecture, not an external build detail:
+
+| Stage | Producer | Committed artifact | Runtime consumer | Failure fallback |
+| --- | --- | --- | --- | --- |
+| Scenario data | `ScenarioFactory` / editor export | `content/venues/*.tres`, event/profile data | `VenueScenario` → `ShiftCoordinator` | built-in scenario defaults |
+| NPC library | Blender flatpak + `tools/blender_assets.py` | `assets/models/blender/npc/*.glb`, manifest, baked AO | `NpcAvatar` | `npc_base.glb` → procedural rig |
+| Gear/props | Blender flatpak + tool + bake | `npc_gear/*.glb`, `props/*.glb`, `*_ao.png` | `NpcAvatar`, `WorldBuilder` | primitive assets / generated props |
+| Surface/UI art | Python pipelines / AI-assisted references | `assets/textures/ai/game_ready/`, `assets/images/` | `SurfaceMaterials`, `UiArt` | neutral material / procedural UI |
+| Screenshots/QA | capture scripts + `scene_concepts`/`screen_designs` | `docs/screenshots/`, `docs/screens/realism/` | reviewers and CI gates | regenerate; never runtime input |
+| Release | Gitea workflow + build/publish scripts | platform binaries, Web zip, Desktop HQ zip | players | source build |
+
+Contracts that keep the pipeline replaceable:
+
+- `npc_base` armature/bone names, five tint slots and front direction are frozen by tests; gear is authored in attach-point space and measured against the character silhouette.
+- Library characters, gear and props are audited for grounding, UVs, triangle budgets, degenerate triangles and manifest coverage; Blender is a developer tool, never a CI runtime dependency.
+- `WorldBuilder.VENUE_SPECS` drives geometry, navigation, features and prop placements; `GameManager` rebuilds only the world container on a venue change.
+- UI/scene art is loaded through `UiArt` with a null/neutral fallback; composed images live in `assets/images/`, not in the docs reference tree (ADR-0014).
+- CI stays offline: only committed `.glb`/`.png`/`.tres` and Godot are needed; optional AI/Blender steps are reproducible development tools.
+
+### Content authoring and runtime data flow
+
+`ScenarioFactory` is the source of truth for the three authored venues. `tools/export_venues.gd`
+writes `content/venues/<id>.tres` for editor inspection; the factory remains the canonical
+scenario definition. At runtime `GameManager` selects a `VenueScenario`, `ShiftCoordinator`
+schedules events and phases, and `NPCController`/`AccessVerifier`/`EscalationManager` produce
+incidents. `IncidentRecorder` is the authoritative event history; body-camera review,
+reputation, crowd reaction and shift review read it rather than resolving gameplay separately.
+
 ## 6. Runtime View
 
 ### Routine interaction
@@ -116,6 +148,19 @@ in code.
 6. The incident recorder stores the interaction.
 7. Reputation and crowd systems react to the outcome.
 
+### Venue switch
+
+1. The player selects a venue from the start menu or cycles with the debug shortcut.
+2. `GameManager` loads the matching `VenueScenario` and keeps the guard/UI state.
+3. `WorldBuilder` rebuilds only `world_root` from `VENUE_SPECS`, including geometry, props and the navigation mesh.
+4. Shift state, NPCs and incidents are reset for the new venue; phase lighting and the door state are reapplied.
+
+### Asset fallback
+
+1. A runtime loader asks for the library scene or texture.
+2. If the imported asset is missing, the loader uses the generated/procedural fallback rather than failing the boot.
+3. Contracts and audits ensure the fallback and library paths expose the same observable behaviour; CI runs headless against whichever path is available.
+
 ### Access check
 
 1. The player stops or receives an approaching person.
@@ -135,28 +180,30 @@ in code.
 
 ## 7. Deployment View
 
-The initial target is a single-player local game. The expected runtime consists of one client process containing presentation, simulation, rules, content, and persistence for local settings and shift results. No online backend is required for the first prototype.
+The game is a single-player local client containing presentation, simulation, rules, content, and persistence for local settings and shift results. No online backend is required. A non-threaded Web export ships alongside the desktop builds and can be served from any static host without special headers. The default renderer is GL Compatibility; an optional Desktop HQ zip uses Forward+ with volumetric fog/SDFGI on Vulkan-capable desktops. CI, local development and exported builds use Godot 4.7.2; the light-falloff code keeps a compatibility branch for older editors but the supported baseline is unified.
 
-Future options include external analytics, cloud saves, or replay sharing, but they are not part of the initial architecture.
+Future options include external analytics, cloud saves, or replay sharing, but they are not part of the current architecture.
 
 ### CI/CD build pipeline
 
-A continuous-integration pipeline keeps the headless test suite green on every change, with a planned extension to build and publish release artifacts automatically.
+A continuous-integration pipeline keeps the headless test suite green on every change and publishes tagged releases.
 
-- **CI workflow** (`.github/workflows/ci.yml`) runs on every push to `main` and on every pull request. It installs the pinned Godot 4.3 editor, caches the `.godot` import artifacts, imports the project to build the class cache, and runs the headless test suite (`res://src/test/test_runner.gd`). The job fails on a non-zero exit code or any `SCRIPT ERROR` in the output.
-- **Planned extension** grows the pipeline from "test only" to "test, build, and publish": a test stage (headless tests plus a `--quit-after 120` boot smoke test as the merge gate), a build stage (install export templates, run `tools/build_releases.sh`), and a publish stage (on a version tag, upload artifacts via `tools/publish_release.sh` with a `GITEA_TOKEN` secret).
-- **Hosting note:** the repository lives on Gitea/Forgejo (`https://git.allucanget.biz/zwitschi/security-game`); the workflow is authored for GitHub Actions and should be mirrored or ported to the host's own runner if Actions is unavailable there. Export templates must match the pinned engine version, and macOS builds are unsigned (production releases need notarization or clear quarantine guidance).
+- **Workflow:** `.gitea/workflows/build.yml` runs on pushes, pull requests, tags, and manual dispatches. The `checks` job restores/caches Godot 4.7.2, imports the project, and runs `res://src/test/test_runner.gd`; it fails on a non-zero exit code or any `SCRIPT ERROR` in the output.
+- **Build job:** runs for tags and manual dispatches. It installs export templates, exports Linux/Windows/macOS and the non-threaded Web build, packages the NSIS installer, Linux AppImage and optional Desktop HQ zip, verifies the installer contents, and uploads the artifacts.
+- **Publish job:** tag builds call `tools/publish_release.sh` to create the Gitea release and upload the standard artifacts plus the optional Desktop HQ zip. The script uses `GITEA_TOKEN` when configured and otherwise reuses the runner's checkout extraheader credentials.
+- **Hosting:** the repository lives on Gitea (`https://git.allucanget.biz/zwitschi/security-game`). Export templates must match the pinned Godot version; macOS builds are unsigned and need quarantine guidance or notarization for wider distribution.
 
 ### Release management
 
 Releases are produced from a tagged commit and published to the repository host's release page, where the README "Downloads" links point.
 
-- `export_presets.cfg` — committed Linux, Windows Desktop, and macOS export presets so builds are reproducible.
-- `tools/build_releases.sh` — exports all three desktop artifacts into `build/`, named `gig-line-<platform>-<version>.<ext>`.
-- `tools/publish_release.sh` — creates a release and uploads the artifacts via the Gitea/Forgejo API (requires `GITEA_TOKEN`).
+- `export_presets.cfg` — committed Linux, Windows, macOS, and Web export presets so builds are reproducible.
+- `tools/build_releases.sh` — exports the desktop binaries and Web zip into `build/`, named `gig-line-<platform>-<version>.<ext>`.
+- `tools/publish_release.sh` — creates a release and uploads the artifacts via the Gitea API, using `GITEA_TOKEN` or the checkout extraheader fallback.
+- Packaging — NSIS builds the Windows installer; `packaging/linux/build_appimage.sh` builds the AppImage.
 - [`RELEASING.md`](RELEASING.md) — step-by-step guide and release checklist.
 
-The release process is: bump the version, run the full test suite and boot smoke test, run `tools/build_releases.sh`, run `tools/publish_release.sh` (or create the release via the web UI), and verify the README "Downloads" links resolve to the new release.
+The release process is: bump the version, run the full test suite and `tools/check_screenshots.sh`, run `tools/build_releases.sh`, tag and push (CI publishes), then verify the README "Downloads" links and the release artifacts.
 
 ## 8. Cross-Cutting Concepts
 
@@ -167,7 +214,13 @@ The release process is: bump the version, run the full test suite and boot smoke
 - **Safety and proportionality:** The rules layer prevents ordinary noncompliance from automatically becoming a violent encounter.
 - **Determinism where useful:** Scenario tests should be able to use fixed seeds and scripted NPC behavior.
 - **Localization:** Dialogue and prompts should be externalized from logic.
-- **Observability:** Debug overlays should show NPC intent, access status, escalation level, active incidents, and response timers during development.
+- **Observability:** Debug overlays show NPC intent, access status, escalation level, active incidents, and response timers during development.
+- **Visual regression:** Staged captures are compared against the runtime reference art (`screen_designs.py compare`) and optionally judged by a vision model; `tools/check_screenshots.sh` makes the pass repeatable.
+- **Asset provenance and AI usage:** AI-assisted images/concepts are development inputs only; validated outputs are committed, audited and loaded through the same runtime asset contracts. Generated content must not become an offline/CI dependency.
+- **Campaign and checkpoint state:** `Campaign` owns venue order/progression; settings, campaign, completed shift history and a versioned pause checkpoint are separate JSON documents. The checkpoint snapshots coordinator systems, scheduler RNG and NPC presentation/access state; it deliberately does not serialize the tutorial overlay or transient input state.
+- **Difficulty:** easy/normal/hard only scale spawn pacing, NPC compliance tolerance and report-credibility strictness; access/escalation rules and emergency rarity are invariant.
+- **Settings and accessibility:** volume/motion/caption settings persist through `settings.json`; Help is generated from the input-binding catalogue and the HUD log is the text caption surface. CI/release, local development and exported builds are unified on Godot 4.7.2.
+- **Documentation ownership:** `PLAN.md` owns design intent; `docs/gameplay.md` owns playable mechanics; `docs/architecture.md` owns system boundaries, data flow, constraints and cross-cutting decisions; ADRs own decision history; `docs/development-status.md` owns the implemented/gap list; `TODO.md` owns the roadmap; `MEMORY.md` owns gotchas and open questions. Specialized docs link to these rather than becoming competing sources of truth.
 
 ## 9. Architecture Decisions
 
@@ -198,6 +251,9 @@ Architecture decisions are recorded as ADRs:
 | Performance | The target venue should support a believable crowd without harming input or simulation responsiveness. |
 | Testability | Access and escalation rules can be tested independently of presentation. |
 | Accessibility | Core actions are available through clear input alternatives and readable feedback. |
+| Reliability | A fresh checkout, missing optional asset, invalid AI key, or unavailable Forward+ renderer must not prevent a normal Compatibility/Web/headless boot. |
+| Performance | A busy venue should hold its budget at the target NPC cap on desktop and Web; the current 16-NPC check is a baseline, not a 1.0 guarantee. |
+| Documentation integrity | Every released version has a changelog entry, current status/roadmap, and architecture/ADR references that match the build. |
 
 ## 11. Risks and Technical Debt
 
@@ -207,8 +263,45 @@ Architecture decisions are recorded as ADRs:
 - Emergency response can overshadow the core game if it is too powerful or too frequent.
 - Mental-health-crisis scenarios require careful writing, playtesting, and respectful presentation.
 - The choice of engine may affect navigation, crowd scale, tooling, and content authoring.
+- Reference mockups can outpace the runtime art style; compare/judge catch gross drift but not composition errors, so the staged gallery needs human review after large visual changes.
+- Godot 4.7.2 is the unified CI/local/project baseline; future engine bumps still require import, visual and export smoke checks before changing that baseline.
+- Content volume and authoring tools are still thin; adding venues/events by editing the factory can become error-prone without schema validation and preview tooling.
+- Save data currently covers settings and shift history, not mid-shift resume; adding saves/replays requires a versioned schema and migration policy.
+- The optional judge and image-generation paths depend on an external key, model availability and budget; CI cannot make them a release gate, and keys must never be committed.
+- Accessibility and localization coverage is partial; a 1.0 release needs subtitles/captions, colour-independent cues, remapping, text expansion tests and at least a documented localization workflow.
+- Unsigned macOS builds, AI asset provenance and any storefront/legal requirements are release blockers for a public 1.0.
+- Documentation drift has already occurred (release version, implemented status and obsolete plan docs); the ownership map and roadmap must be kept current in the same change as the implementation.
 
-## 12. Glossary
+## 12. Documentation Consolidation and Ownership
+
+The documentation set is intentionally layered. Architecture-level material is consolidated here;
+specialized operational detail remains in focused pages so commands do not rot inside the
+architecture document.
+
+| Document | Canonical role | Relationship to this architecture |
+| --- | --- | --- |
+| [`PLAN.md`](../PLAN.md) | Product/design intent, pillars, venues and success criteria | Design source; architecture realizes it |
+| [`docs/gameplay.md`](gameplay.md) | Playable loop, escalation, venue mechanics | Runtime/behavioral view |
+| [`docs/architecture.md`](architecture.md) | System boundaries, data flow, constraints, deployment, cross-cutting decisions, quality risks | Single architecture source |
+| [`docs/adr/`](adr/) | Immutable decision records with context and consequences | Decision history linked from §9 |
+| [`docs/asset-tooling.md`](asset-tooling.md) | Build/audit/capture commands and pipeline usage | Operational appendix to the pipeline section |
+| [`docs/blender-assets.md`](blender-assets.md) | Blender character/gear/prop contracts and attach points | Detailed asset contract appendix |
+| [`docs/getting-started.md`](getting-started.md) | Setup, commands, controls | Developer onboarding |
+| [`docs/RELEASING.md`](RELEASING.md) | Release checklist and CI/publishing steps | Deployment appendix to §7 |
+| [`docs/smoke-checklist.md`](smoke-checklist.md) | Manual verification script | QA appendix to §10 |
+| [`docs/development-status.md`](development-status.md) | Implemented features and current gaps | Status companion to the roadmap |
+| [`TODO.md`](../TODO.md) | Active tasks and v1.0.0 roadmap | Planning source; no architecture duplication |
+| [`CHANGELOG.md`](../CHANGELOG.md) | User-facing release history | Release/version companion |
+
+Consolidation decisions:
+
+- **Architecture owns the "how"** (components, contracts, data flow, constraints, quality gates); **PLAN/gameplay own the "what"**; **ADRs own the "why"**. Links replace duplicated prose.
+- **Asset and release documents remain separate** because they are command-heavy operational procedures; their architecture-relevant contracts and failure modes are summarized in §5 and §7.
+- **Completed plans are removed, not kept as competing roadmaps.** Historical graphics work is summarized by ADR-0013, the asset pipeline section and the v0.6.0 changelog; new work belongs in TODO.
+- **Status and roadmap are separate from architecture.** `docs/development-status.md` records what exists; `TODO.md` records what remains, including the v1.0.0 gap analysis and milestone exit criteria.
+- **Documentation drift is a tracked risk:** release/version, test counts, renderer status, and stale plans must be corrected in the same commit as the change that invalidates them.
+
+## 13. Glossary
 
 - **Access artifact:** A wristband, ID, ticket, credential, or other item used to verify entry.
 - **Authorized person:** Someone permitted to enter under the current venue policy.

docs/asset-tooling.md

@@ -0,0 +1,285 @@
+# Asset Pipeline and Tooling
+
+Everything the game renders is produced or gated by the scripts below. Architecture-level contracts,
+data flow and failure fallbacks are summarized in
+[`architecture.md`](architecture.md#content-and-asset-pipeline-architecture); this page is the
+operational reference. Development-only outputs (AI concept sheets, Blender sources, raw AI fabrics)
+are gitignored; the audited game assets are committed.
+
+## Image Asset Tools
+
+Install the Pillow dependency used by the existing texture generator and the asset tools:
+
+```bash
+python3 -m pip install -r requirements-tools.txt
+```
+
+Generate a role-sized image (generation requires `OPENROUTER_API_KEY`):
+
+```bash
+python3 tools/asset_pipeline.py generate --prompt "weathered red brick" --role tile --output assets/textures/brick_extra.png
+```
+
+Generated images are resized to the selected role profile. Non-square requests use
+the validated `openai/gpt-5-image-mini` source ratio and crop to the final role dimensions.
+Transparent glyphs can be recolored while preserving their alpha mask with
+`--foreground '#ffffff'`.
+
+Crop uses the image center by default; `--x` and `--y` select an explicit crop origin. Resize defaults to aspect-preserving `contain`; use `--fit cover` to crop or `--fit stretch` to distort to the exact dimensions.
+
+```bash
+python3 tools/asset_pipeline.py crop assets/textures/source.png assets/textures/crop.png --width 256 --height 128
+python3 tools/asset_pipeline.py resize assets/textures/source.png assets/images/scenes/scene.png --width 1920 --height 1080 --fit cover
+python3 tools/asset_pipeline.py seamless assets/textures/rough_tile.png assets/textures/tile.png
+```
+
+Audit accepts image files or directories. `--role auto` infers common roles from paths and filenames; explicit roles include `tile`, `texture`, `icon`, `card`, `banner`, `backdrop`, `background`, `overlay`, `app_icon`, and `screenshot`.
+
+```bash
+python3 tools/asset_pipeline.py audit assets/textures
+python3 tools/asset_pipeline.py audit assets/images/scenes --role background --json
+python3 -m unittest discover -s tools -p 'test_*.py'
+```
+
+The audit classifies measurable fit issues as `good` or `bad` based on role-specific dimensions, aspect ratio, alpha requirements, and tile-edge continuity. It lists perspective/projection as a visual review item because image semantics cannot be judged reliably by these deterministic checks.
+
+## Prop models
+
+Street furniture (bollards, benches, bins, planters, newspaper boxes, a hydrant)
+is real 3D geometry generated by `tools/model_pipeline.py` and written to
+`assets/models/generated/*.glb`. Godot imports each file as a `PackedScene`, and
+`WorldBuilder` instantiates it with a procedural fallback when the model or its
+import is missing, so the world still builds on a fresh checkout.
+
+```bash
+# Print the catalogue (parts, triangle count, whether a model/concept exists)
+python3 tools/model_pipeline.py list
+
+# Rebuild the models (deterministic, offline) and validate them
+python3 tools/model_pipeline.py build
+python3 tools/model_pipeline.py audit
+
+# Optional: an image model supplies the colour palette per prop
+# (requires OPENROUTER_API_KEY; the repo .env is read automatically)
+python3 tools/model_pipeline.py concept
+python3 tools/model_pipeline.py concept --only bench --force
+```
+
+Each prop is a small list of boxes and cylinders, so `build` needs no network and
+the output is byte-identical between runs. `concept` asks an image model for a
+studio-style reference; `dominant_colors` and `assign_roles` then map that image's
+colours onto material roles (darkest → metal, warm saturated → wood, light grey →
+stone, green → foliage). glTF stores colours in linear space, so the tool converts
+the sRGB palettes before writing them. Re-run `build` and `godot --headless
+--path . --import` after changing a prop. See
+[ADR-0012](adr/0012-surface-materials-and-generated-props.md).
+
+Surface materials share one definition in `src/game/materials.gd`: named
+roughness/metallic profiles per surface, plus the environment tune-up (ACES
+tonemapping, glow, fog, colour grading) that the phase lighting applies.
+
+## NPC character model
+
+NPCs are moving from the procedural capsule rig to a skinned, UV-mapped base
+character authored in Blender ([ADR-0013](adr/0013-blender-authored-npc-characters.md)).
+`tools/npc_pipeline.py` builds `assets/models/generated/npc_base.glb` plus the
+per-slot material maps. `NpcAvatar` instantiates that skinned model, tints its
+five material slots from the seed-driven outfit, and drives the bones from the
+existing animation code; the procedural rig remains the offline fallback (see
+[ADR-0013](adr/0013-blender-authored-npc-characters.md) and
+[`blender-assets.md`](blender-assets.md)).
+
+```bash
+# Print the frozen contract (slots, bone names, triangle budget)
+python3 tools/npc_pipeline.py list
+
+# Rebuild the skinned base mesh + neutral maps in Blender and validate it
+flatpak run org.blender.Blender --background --python "$PWD/tools/npc_pipeline.py" -- build
+python3 tools/npc_pipeline.py audit
+
+# Layer the AI clothing albedos (shirt/trousers) over the procedural weave, and
+# derive per-fabric outfit colours for the avatar palette
+python3 tools/npc_pipeline.py prepare
+python3 tools/npc_pipeline.py palette
+```
+
+`prepare` resizes the AI fabric tiles (kept locally in `assets/textures/npc/ai/`,
+which is gitignored) onto the `cloth`/`pants` albedos; `build` bakes them into the
+`.glb` and regenerates the procedural normal + packed ORM maps. `palette` writes
+`assets/textures/npc/palette.json` using `model_pipeline.dominant_colors`.
+
+## Blender asset library (loaded by the game)
+
+`tools/blender_assets.py` models a larger library procedurally in Blender for the
+v0.6.0 integration: **8 skinned NPC characters** (casual, jacket, coat, hi-vis vest,
+dress, hoodie, firefighter, guard), each a drop-in for `npc_base.glb` (same bones,
+joint positions and tint slots); **18 gear pieces** authored at head/hand/back/chest
+attach points (caps, hood, helmet, backpack, SCBA tank, lanyard, phone, cup,
+clipboard, umbrella, camera, sign, flashlight, wand, radio, …); and **20 props**
+(octagonal bollard and bin, slatted bench, hydrant, news box, planters, street lamp,
+street and palm trees, A-frame sign, wall lantern, cone, crowd barrier, stanchion,
+handrail, podium, double door, marquee, sedan).
+
+`NpcAvatar` selects a character by role/seed, tints the five contract slots, and
+attaches gear at the documented points; `WorldBuilder` loads the library props
+with colliders/avoidance and drives their emissive parts from the day/night
+cycle. The single `npc_base.glb` and primitive props remain offline fallbacks.
+Contract and integration notes: [`blender-assets.md`](blender-assets.md).
+
+| Characters | Props |
+| --- | --- |
+| ![characters](../docs/blender_previews/sheet_npc.jpg) | ![props](../docs/blender_previews/sheet_props.jpg) |
+
+```bash
+flatpak run org.blender.Blender --background --python "$PWD/tools/blender_assets.py" -- build
+flatpak run org.blender.Blender --background --python "$PWD/tools/blender_assets.py" -- render
+python3 tools/blender_assets.py sheet   # docs/blender_previews/sheet_*.jpg
+python3 tools/blender_assets.py audit   # no Blender needed
+godot --headless --path . --import
+```
+
+## Confirmed game assets
+
+Everything below is audited and shipped in the game; development-only outputs
+(AI concept sheets, Blender sources, raw AI fabrics) are gitignored.
+
+| | |
+| --- | --- |
+| ![brick facade](../assets/textures/ai/game_ready/v2/picks/brick_facade.png) | ![sidewalk pavers](../assets/textures/ai/game_ready/v2/picks/sidewalk_pavers.png) |
+| ![asphalt](../assets/textures/ai/game_ready/v2/picks/asphalt.png) | ![awning](../assets/textures/ai/game_ready/v2/picks/awning_canvas.png) |
+| ![skyline day](../assets/textures/ai/game_ready/v2/picks/skyline_day.png) | ![skyline night](../assets/textures/ai/game_ready/v2/picks/skyline_night.png) |
+
+- **Surface textures:** the v2 picks above (brick, sidewalk pavers, dry and wet asphalt, awning canvas) plus their normal maps, loaded by `src/game/materials.gd` and `WorldBuilder`; the three skyline panoramas are switched per shift phase. The first-generation tiles and `assets/textures/skyline.png` are no longer loaded.
+- **UI art:** `assets/textures/ai/game_ready/icons/` (flashlight, door lock, wand, REC) and `assets/textures/ai/game_ready/cards/` (ID, wristband, ticket, credential, guest list), loaded by `src/game/ui/hud.gd`.
+- **Generated models:** `assets/models/generated/*.glb` — bollard, bench, trash bin, planter, newspaper box, hydrant, and the NPC base — plus their colour atlases.
+- **NPC material maps:** `assets/textures/npc/*_{albedo,normal,orm}.png` and `palette.json`.
+
+Audit them all:
+
+```bash
+python3 tools/asset_pipeline.py audit assets/textures/ai/game_ready
+python3 tools/model_pipeline.py audit
+python3 tools/npc_pipeline.py audit
+```
+
+## Realism pass: scene concepts, skylines and textures
+
+The skyline, surface tiles and phase lighting were rebuilt against AI concept frames. The
+concepts live in [`docs/screens/concepts/`](../docs/screens/concepts/README.md); the validated
+picks the game loads are in `assets/textures/ai/game_ready/v2/picks/` (day/dusk/night
+panoramas, brick, sidewalk pavers, dry and wet asphalt, awning canvas, each with a normal
+map).
+
+`tools/scene_concepts.py` generates and processes new candidates, promotes the validated ones
+to stable names, audits them, and scores captures against the concepts. It never overwrites an
+image: new files get a `-vN` suffix, and `process` skips existing candidates unless `--new`.
+
+```bash
+python3 tools/scene_concepts.py generate --group scene        # or backdrop / texture, --variants N
+python3 tools/scene_concepts.py process && python3 tools/scene_concepts.py audit
+python3 tools/scene_concepts.py promote                       # validated picks -> v2/picks/
+godot --headless --path . --import
+
+# A/B a candidate without touching game code: the same cameras, textures swapped at runtime.
+godot --path . --script res://src/test/capture_realism.gd -- --out=res://docs/screens/realism/<run>/after
+godot --path . --script res://src/test/capture_realism.gd -- --out=res://docs/screens/realism/<run>/try \
+  --swap=res://assets/textures/ai/game_ready/v2/picks/brick_facade.png=res://assets/textures/ai/game_ready/v2/brick_facade-v2.png
+
+# Score before/after against the concepts (Pillow detail metrics + vision judge).
+python3 tools/scene_concepts.py realism --run docs/screens/realism/<run> --judge \
+  --model google/gemini-2.5-flash --repeats 3
+```
+
+Judges default to `--model auto`: `tools/openrouter_judge.py` reads the live
+OpenRouter catalogue, keeps image-input models that support `response_format`,
+and ranks them by advertised token/image price. The run falls through the list
+on provider/model errors and aborts on an invalid key. Use
+`GIG_LINE_JUDGE_MODEL` or `--model <id>` for a pinned comparison.
+
+`capture_realism.gd` runs six stages (day, portrait, evening, late, Joke Shop, studio);
+`--stages=day,late` limits it while tuning; `--flashlight` turns on the guard lamp for
+night stages (used by the Desktop HQ A/B). The `portrait` shot freezes one NPC on open sidewalk
+and frames the face, which is the only capture that can judge avatar detail
+(`--portrait-type=N` picks a role). The generated realism runs under
+`docs/screens/realism/` are **local, gitignored QA artifacts**; commit only the
+resulting decisions/docs, not the run folders. The texture-adoption run compared
+the pre-adoption captures with the current build: on the shots both sets captured,
+the judge's like-for-like means rose on every sub-score (overall 0.8 → 1.0,
+backdrop 0.6 → 1.6) and the Pillow metric gap fell 0.444 → 0.348. The character
+pass added the portrait shot and recorded the new faces, hands and sleeve cuffs.
+The Forward+ A/B compared the Compatibility entrance with the optional Desktop HQ
+preset. The gear-fit run checked the sunglasses, bag and helmet against measured
+head/skirt bounds with `python3 tools/blender_assets.py fit`; it also fixed the
+portrait yaw and hid the focus overlay so the close-up shows the avatar.
+
+Regenerate a run locally with the capture and `realism --run ...` commands above;
+the reports and sheets are intentionally not part of the release repository.
+
+## Screen design references
+
+Screen mockups and screenshot comparison use `tools/screen_designs.py`. It turns the
+screen descriptions in `docs/` (README captions, ADRs 0007–0010, `PLAN.md`, and
+`architecture.md`) into runtime reference art under `assets/images/ui/` (with a
+reference-only snapshot in `docs/screens/designs/`), then uses those images as
+the expected state to check the game's captures.
+
+Each screen is tagged `scene` (a realistic first-person 3D world view) or `ui`
+(an in-game panel overlaid on a softened scene), and the generator appends a
+shared art-direction suffix so the frames read as one coherent game. Requests use
+a 3:2 landscape source and crop to the 16:9 capture dimensions.
+
+```bash
+# Export the built-in scenarios to editor-authorable .tres resources
+godot --headless --path . --script res://tools/export_venues.gd
+
+# List the catalogue (name, kind, whether a reference design exists)
+python3 tools/screen_designs.py list
+
+# Deterministic wireframes (offline, no API key); existing designs are kept
+# unless --force is passed, so an offline run never replaces an AI mockup
+python3 tools/screen_designs.py generate --draft
+python3 tools/screen_designs.py generate --draft --only wand --force
+
+# Realistic 3D scenes and in-game screen designs via OpenRouter
+# (requires OPENROUTER_API_KEY)
+python3 tools/screen_designs.py generate
+
+# Prop gallery (studio line-up) for close-range prop checks
+godot --path . --script res://src/test/capture_prop_gallery.gd
+
+# Compare docs/screenshots/*.png against the designs
+python3 tools/screen_designs.py compare
+python3 tools/screen_designs.py compare --json
+
+# Ask a vision model whether each capture realises its design's screen and layout
+# (requires OPENROUTER_API_KEY; the repo .env is read automatically)
+python3 tools/screen_designs.py judge
+python3 tools/screen_designs.py judge --model openai/gpt-4o-mini --json
+python3 tools/screen_designs.py judge --only 03-   # one capture
+python3 tools/screen_designs.py judge --dry-run    # build requests, no network
+```
+
+The catalogue covers 21 screens: the eleven README captures plus the start menu,
+pause overlay, settings, shift review, radial menu, emergency radio, wand
+screening, Joke Shop queue, TV Studio arrival, crowd panic, responder arrival,
+body-camera timeline, and the escalation HUD. All 21 have an AI reference in
+`assets/images/ui/` (snapshot in `docs/screens/designs/`); the eleven screens with
+staged captures are also compared or judged against the running game.
+
+`compare` flags gross drift: wrong aspect ratio, undersized frame, near-blank
+frame, and large layout/palette/detail distance. It is a regression gate, not a
+semantic judge — pixel and perceptual metrics cannot decide whether a frame's
+composition is *right*.
+
+`judge` covers that gap: it sends each capture together with its concept mockup to
+a vision model and asks whether the capture realises the same screen and layout
+intent. Art style, fidelity, fonts, and placeholder text are explicitly ignored.
+Verdicts are classed as `match`, `review` (a mismatch below `--fail-confidence`,
+default 0.6 — expected when a concept mockup is more stylised than the game), or
+`diff` (a confident mismatch, which exits non-zero). Regenerate the designs after changing screen layout, then re-run
+`compare` after regenerating the game screenshots with
+`src/test/capture_screenshots.gd`.
+
+For a one-command drift check, run `tools/check_screenshots.sh`. It renders the
+staged captures and prop gallery into `docs/screenshots/` (using `xvfb-run` when
+no display is available) and then runs `screen_designs.py compare`.

docs/blender-assets.md

@@ -1,9 +1,11 @@
 # Blender asset library
 
+Architecture context: the asset contracts and fallback path are summarized in
+[`architecture.md`](architecture.md#content-and-asset-pipeline-architecture).
+
 Status: built, audited, and integrated (2026-11-01). `NpcAvatar` selects the
 character variants and attaches the gear; `WorldBuilder` loads the prop library
-with colliders and phase-driven emissives. See the Phase 3.5 integration in
-[`plan-graphics-v0.6.md`](plan-graphics-v0.6.md).
+with colliders and phase-driven emissives.
 
 Generator: [`tools/blender_assets.py`](../tools/blender_assets.py). Manifest (the
 source of truth for integration):
@@ -41,6 +43,7 @@ flatpak run org.blender.Blender --background \
   --python "$PWD/tools/blender_assets.py" -- render
 python3 tools/blender_assets.py sheet   # -> docs/blender_previews/sheet_<category>.jpg
 python3 tools/blender_assets.py audit   # stdlib only; exit 1 on any issue
+python3 tools/blender_assets.py fit     # head/clothing fit + bag-body clearance, per character
 python3 tools/blender_assets.py list
 godot --headless --path . --import      # after any rebuild
 ```
@@ -86,16 +89,20 @@ All eight use the `npc_base` contract, so each one can replace
 - material slots `skin`, `cloth`, `pants`, `accessory`, `hair` carry the same
   neutral `assets/textures/npc/<slot>_{albedo,normal}.png` maps, so
   `Materials.npc_slot()` tints them the same way it tints `npc_base`.
-- budget ≤ 6000 triangles and ≤ 4000 vertices (glTF vertex count, after seam
-  splits). The current range is 3,788–4,640 triangles and 3,200–3,960
-  vertices.
+- budget ≤ 6000 triangles and ≤ 5000 vertices (glTF vertex count, after seam
+  splits; `CHAR_MAX_VERTS` in `tools/blender_assets.py`, raised from 4000 for
+  the 2026-11-01 face/hand pass). The current range is 3,974–5,026 triangles
+  and 3,744–4,807 vertices.
 
 Construction: the torso and limbs are one continuous Skin-modifier mesh,
-subdivided twice, decimated to 36 % with X symmetry, and cut at the waist, cuffs,
-sleeves and neck so the material borders are clean edge loops. The head,
-face (nose, ears, eyes, brows, mouth), hair, hands, shoes and clothing layers are
-separate parts. Weights come from distance to the bone segments, limited by body
-region. Parts that should stay rigid (head, hands, shoes) get a single bone.
+subdivided twice, decimated to 26 % with X symmetry, and cut at the waist, cuffs,
+sleeves and neck so the material borders are clean edge loops. The head is a
+separate part carrying the face detail: brow ridge, sclera/iris/upper-lid per eye,
+cheekbones, a nose with a bridge and tip, ears with lobes, and upper and lower
+lips. Hands have four fingers plus a thumb; sleeves end in a cuff ring.
+Hair, shoes and clothing layers are separate parts. Weights come from distance to
+the bone segments, limited by body region. Parts that should stay rigid (head,
+hands, shoes) get a single bone.
 
 | Character | `layer_for()` / look | Suggested roles | Preview gear |
 | --- | --- | --- | --- |
@@ -154,16 +161,16 @@ exactly these points, which gives a quick visual check of the convention.
 | `marquee` | the procedural marquee | 6 m canopy and sign box; emissive `bulb` + `sign_face`. Overlay the text with the existing `Label3D` |
 | `sedan` | new (studio arrival) | 4.6 m; emissive `headlight`, red tail lamps |
 
-Props use plain PBR factors (base colour, roughness, metallic, emission) and
-have no textures. They are not yet AO-baked; that is still a Phase 4 task.
-Emissive materials are always on in the GLB. The integration should tie them to
-`WorldBuilder.set_night_mode()`.
+Props use plain PBR factors (base colour, roughness, metallic, emission) plus
+the committed 256² baked AO maps (`<name>_ao.png`) wired by `WorldBuilder`;
+emissive materials are tied to `WorldBuilder.set_night_mode()`. Characters
+carry baked AO and the shared neutral material maps described above.
 
 ## Checks
 
 - `python3 tools/blender_assets.py audit`: container, `POSITION`/`NORMAL`/
   `TEXCOORD_0`, UVs in [0, 1], no zero-area triangles (Godot warns about them
-  during LOD generation), budgets (characters 6000/4000, gear 1500, props 4000
+  during LOD generation), budgets (characters 6000/5000, gear 1500, props 4000
   triangles), grounding, and an editable `.blend`. For characters it also
   checks skinning, bones, slots, the `npc_base` mesh node and the height.
 - `tools/test_blender_assets.py`: catalogue and contract consistency with
@@ -176,7 +183,8 @@ Emissive materials are always on in the GLB. The integration should tie them to
 
 ## Known limitations
 
-- The characters have no baked AO or ORM texture of their own. They reuse the
+- Characters carry a baked `<name>_ao.png` (red channel, wired by
+  `_apply_outfit_materials()`), but no ORM texture of their own. They reuse the
   tiling slot maps, so the runtime `SurfaceMaterials` recipes still supply
   roughness.
 - There is a single body topology per build (average, slim, broad) and no

docs/development-status.md

@@ -0,0 +1,52 @@
+# Development Status
+
+Implemented so far:
+
+- Godot 4.7.2 project scaffold, input map, procedural world builder (CI/local/release unified)
+- Venue-driven simulation core: `ShiftCoordinator`, `VenueScenario`, `EventScheduler`, `NPCController` + FSM, `AccessVerifier`, `EscalationManager`, `RadioSystem`, `IncidentRecorder`, `ReputationEvaluator`, `CrowdSystem`
+- Three authored scenarios (Hollywood Boulevard building, The Joke Shop, Late Night TV Studio) with access policies, NPC archetypes, and event pools
+- Headless unit tests: **250 passing** (access rules and venue-correct access loadout, escalation, radio cooldown/battery, NPC reaction determinism, door lock, flashlight perception, persistence round-trip, settings round-trip, input remaps, navmesh, step colliders, skyline alpha, scenario data, full-shift simulation, wand screening, responder dispatch, localization strings, focus cone, action wheel, session shell, PLAN verbs and incident recording, crowd presentation, emergency aftermath, body-camera timeline, NPC theater poses, audio, accessibility, authored scenario content, string formatting, `.tres` venue round-trip, surface materials and environment, focus ranking and outfit/gait helpers, generated prop models, web export preset, prop atlas material, player movement, NPC character layers/LOD/queue, input bindings)
+- Simulation extras: protester archetype, CALL_SOMEONE reaction, door lock/secure mechanic (visual indicator), flashlight with night perception bonus, LATE shift phase reaching the violent-threat event
+- First-person prototype with interaction HUD, access inspection, wand screening, radio report form (incl. emergency hold-to-confirm), dispatched responder avatars, aim-free targeting, venue cycling between all three scenarios, color-coded escalation feedback, procedural audio cues, navigation-mesh NPC paths, JSON-backed localized strings, persisted shift history, debug overlay, and shift review
+- Control pass: focus cone on NPC heads with a billboarded blue circle in front of the face and name, action wheel (LMB/Space) with de-escalation-first slices, mouse-look freeze while a panel is open, acceleration-based walking, and named input actions (`action_menu`, `confirm`, `cancel`, `inspect`, `wand`)
+- Session shell: venue start menu (keyboard + mouse), Esc pause overlay (resume / restart / settings / quit to menu), settings panel with mouse-look sensitivity and HUD font scale persisted to `user://settings.json`, and "Run another shift" returning to the venue menu
+- World presentation: skyline backdrop rendered with an alpha material, walkable step and landing colliders, larger marquee text, and larger focus circle / name tag
+- Routine traffic despawns after a while at its waypoint so the crowd cap no longer fills with idle standers
+- PLAN verbs: eye contact (distinct Level 1 cue), recognizing a person as a player decision recorded as access evidence, a body-camera flag that a formal warning arms (and `B` toggles), blocking that physically stations the guard between the person and the door, and a Level 3 request-reason ask answered from the NPC's `dialogue_lines`
+- Incidents are now actually opened on focus and closed at shift end, so player actions, access evidence, escalation levels, and unresolved interactions reach the review (previously every recorded event was dropped)
+- Crowd presentation: aggressive behavior and responder arrivals make idle bystanders stop and face the incident; panic sends people away from the door (and they leave the scene). A busy 16-NPC entrance measured ~1.2 ms/frame, so no LOD/culling was needed at the current cap
+- Distant skyline ring: four alpha-scissored planes at 200 m read as a hazy city on the horizon (the baked backdrop used to show as a black slab), with a larger ground plane so the buildings meet the street
+- Flashlight aims straight ahead and lights the person/door being checked instead of the ground in front of the guard
+- Emergency aftermath: the `evacuation` outcome locks the door and clears the entrance, an emergency call that the situation did not justify opens an investigation and applies the false-report hit, and the shift review names the responder outcome and any investigations
+- Body-camera timeline: the shift review opens a text timeline of every recorded incident event (time, person, action/outcome) that you step through with the arrow keys or buttons. No live 3D replay yet
+- NPC theater: seated guests sit on the steps with bent legs, influencers and tourists raise a camera prop while photographing, performers sway their sign, and filming visitors pan slowly — all once they reach their intent's waypoint
+- Audio: a looping procedural crowd bed (filtered murmur) whose volume follows `CrowdSystem.mood`, plus radio open/close crackle. All generated at runtime, no audio assets, and safe with a dummy audio server
+- Accessibility: the escalation cue shows a shape meter plus the numeric level (`Escalation: Blocking [###--] L3/5`) so it reads in grayscale, and the HUD font scale from settings is applied at boot by resizing fonts (not Control.scale, which broke the right-aligned layout)
+- Editor-ready venues: `tools/export_venues.gd` writes `content/venues/<id>.tres` from `ScenarioFactory`, and the `.tres` files load back with events, profiles, policy, phases, door lines, and locations intact (the factory stays the source of truth)
+- Localization safety: `Strings.fmt` validates the placeholder count before formatting and fails safe (warns, returns the template) instead of raising an engine error, `Strings.placeholder_count` ignores `%%`, and `Strings.validate()` lints the table for trailing `%`, unsupported conversions, and mixed positional/sequential placeholders
+- Authored scenario content: Joke Shop reservation-without-ID, borrowed/mismatched ID, a guest who refuses the wand screen, and a late arrival during a performance; Studio filming-boundary repeats and a celebrity arrival that draws a small crowd; Building events that point the player at the body camera and request-reason verbs
+- Visual polish pass (v0.2.0): phase-based lighting (sun/sky/ambient per shift phase), street lamps with night-mode bulbs and omni lights, glowing marquee signage, crosswalk, planters and low-poly street trees, NPC height/brightness variety, denser routine traffic — day and late-night screenshot sets
+- Assets pass: authored textures in `assets/textures/` (brick facade, concrete, asphalt, awning, skyline, vignette, HUD icons, access-card art) generated by `tools/generate_textures.py`, soft sun shadows, humanoid NPC rigs with archetype props + procedural walk bob and attention head-turn, inspection artifact cards, escalation vignette, mode icons, and a body-camera overlay (REC + shift clock)
+- Rendering pass (v0.3.0 work, [ADR-0012](adr/0012-surface-materials-and-generated-props.md)): one material module with roughness/metallic profiles per surface, ACES tonemapping, glow, aerial fog and colour grading driven by the shift phase, correctly scaled brick, framed facade windows that light up at night, door trim and handles, a curb and lane dashes, and the glowing marquee/lamp bulbs. NPCs gained per-role clothing palettes, caps/hoods/backpacks/sunglasses/lanyards, hands and shoes, and an arm/leg walk swing
+- NPC characters (v0.5.0): articulated limb rigs, layered outfits, hand items, face/hair variety, idle behaviour (phone, clipboard, crossed arms, look-around), escalation gestures, readable reaction symbols, door-queue offsets, and three LOD tiers with a billboard impostor
+- Player movement (v0.5.0): separate acceleration/braking, step-up assist, head bob and landing dip (toggleable), precision-walk FOV/chip/tick, surface-aware footsteps, gamepad support, and persistent key/button remapping in settings
+- Prop collision and placement (v0.4.0): every prop fits a static collider from its mesh bounds and publishes a navigation obstacle, so the guard and guests cannot walk through benches, bins, or bollards; placements are grouped into zones with a validator, and deterministic variants add rotation, scale, and small clutter
+- Prop atlas (v0.3.1): `tools/model_pipeline.py` packs each prop's palette into one power-of-two colour atlas plus a metallic/roughness atlas and emits a single material with per-vertex UVs, so a prop is one draw material rather than one per part; `audit` enforces the contract
+- Generated prop models (v0.3.0 work): `tools/model_pipeline.py` builds bollards, benches, bins, planters, newspaper boxes and a hydrant as `.glb` props with per-part materials, loaded by `WorldBuilder` with a procedural fallback; the optional AI concept step (`model_pipeline.py concept`) supplies per-prop colour palettes
+- Environment pass (v0.6.0): 1024² brick/concrete/asphalt with derived tangent normal maps, 256² baked AO maps for every Blender character/gear/prop, and library props whose bulbs/LEDs/sign faces follow the day/night phase
+- NPC characters + library (v0.6.0): `NpcAvatar` loads one of 8 Blender-authored skinned variants (role/seed selected) with five tintable material slots, `Rig/Head` focus anchor, and attach-point gear; `npc_base.glb` and the procedural rig remain fallbacks. `tools/blender_assets.py` builds/audits the character, gear, and 20-prop library; `WorldBuilder` loads the replacements and new street dressing (lamp, trees, palms, planters, barriers, podium, doors, marquee, sedan, handrail) with colliders, navigation obstacles, and phase-driven emissives
+- Web build: `build/gig-line-web-<version>.zip` (Godot's non-threaded web template, no COOP/COEP headers needed) built by `tools/build_releases.sh` and published with the desktop artifacts; serve the unzipped folder from any static host
+- Aim-free selection pass (v0.3.0 work, [ADR-0011](adr/0011-aim-free-selection-and-precision-walk.md)): the focus cone ranks candidates by angle then distance, `Tab` and the mouse wheel cycle nearby people nearest-first and pin the selection, right click clears focus with a short re-acquire grace, the HUD reports how many people are in the ring, and holding `Shift` walks at half speed for close work
+
+- Visual alignment: start/venue menu, pause, settings, shift review, radio, wand, inspection, timeline, HUD target chip/escalation bar, and radial menu now use or match their AI references in `assets/images/ui/`. The runtime art loader (`src/game/ui/art.gd`) falls back cleanly when a file is missing.
+- Realism adoption (post-v0.6.0): v2 per-phase skylines and surface tiles with normal maps, retuned sun/exposure/fog, wet asphalt, denser foliage, a visible additive flashlight beam, and refreshed staging captures. `tools/check_screenshots.sh` is the repeatable capture/compare gate; judge is clean of `diff` verdicts.
+- Input/reliability fixes: selecting a venue releases the start-menu input lock and recaptures the mouse; the body-camera overlay no longer covers the shift status. Mouse look now reads at `_input`, restores capture on window focus/click-back, and the HUD is mouse-transparent. Normal radio reports submit on click; emergency calls still require the hold-to-confirm path.
+- Production-quality pass (v0.9.0): mixer/accessibility settings, audio volume clamping, 24-NPC budget smoke, shortened coat/dress stride, and a unified Godot 4.7.2 CI/local support baseline with documented upgrade/rollback requirements.
+- Campaign and first-hour pass (v0.8.0): campaign progression, checkpoint resume, difficulty presets, a searchable Help overlay, recovery events, contextual dialogue, policy/debrief lines and tutorial/replay/skip. Scripted QA bypasses the tutorial unless `--tutorial` is passed.
+- Tutorial pass (0.8.0 work): the eight-beat first shift is wired through a non-blocking prompt overlay, a safe compliant visitor, real wheel/inspection/warning/radio panels, persisted completion/skip and a Settings replay action. Scripted tests/captures bypass it unless `--tutorial` is passed; `smoke_tutorial.gd` covers the full flow.
+- Vision judge (v0.7.2): discovers the cheapest current OpenRouter image+JSON model, reports the model/fallbacks used, and clears the full screen-design judge (13/13 match, 0 diff).
+- Desktop HQ (v0.7.1): optional Forward+ Windows/Linux zip with volumetric fog, SDFGI and a volumetric flashlight; the default Compatibility/Web builds and headless tests gate the effect off. A/B captures are generated locally under `docs/screens/realism/` (gitignored).
+- Venue geometry (v0.7.0): the Joke Shop now builds as a narrow brick alley with a warm wall lantern, shutters, dumpster/AC clutter and no skyline; the TV Studio builds a stone facade, bulb canopy, glossy black car and barrier line. `WorldBuilder.VENUE_SPECS` drives facade/street/nav dimensions, and `GameManager` rebuilds only the world container when the venue changes.
+- Gear fit (post-v0.6.0): Blender gear is measured against the avatar head/skirt silhouette and the checks run in both the Python tooling and the headless suite. Sunglasses, the shoulder bag and the firefighter helmet were fitted to the new faces; the Influencer portrait and gallery were recaptured with a before/after report.
+
+Current gaps for v1.0.0: deeper authored content/dialogue, animation and audio production, localization/accessibility expansion, 24-NPC/platform profiling, external playtesting, signed/notarized release packaging, and a unified Godot baseline. The full gap analysis and milestone plan live in [`TODO.md`](../TODO.md); the current architecture and documentation ownership map are in [`docs/architecture.md`](architecture.md).

docs/gameplay.md

@@ -0,0 +1,63 @@
+# Gameplay
+
+The complete design rationale also lives in [`PLAN.md`](../PLAN.md); this page keeps the playable mechanics close to the README.
+
+## Game Overview
+
+A typical shift lasts 10–15 minutes. The first-person camera stays at the gameplay height of 1.7 m; the concept frames use a lower ~1.55 m reference camera, but gameplay readability and body-camera framing take priority. The player:
+
+1. Watches the entrance, steps, queue, and surrounding sidewalk.
+2. Determines why each person is approaching.
+3. Uses simple gestures or polite directions first.
+4. Verifies authorized access using recognition, wristbands, credentials, tickets, or guest lists.
+5. Escalates only when a person refuses directions, attempts unauthorized entry, or presents a genuine threat.
+6. Records the incident through body-camera and radio systems.
+7. Finishes the shift with a performance review based on safety, judgment, and professionalism.
+
+The game rewards calm resolutions rather than aggressive behavior. Emergency assistance and armed responders are rare last-resort systems with meaningful consequences.
+
+The first shift starts with an in-game tutorial covering movement/look, focus cycling, the action wheel, access inspection, polite direction, formal warning/body camera, radio and shift review. Its beat sheet is in [`tutorial.md`](tutorial.md). After that a short campaign runs Hollywood → Joke Shop → TV Studio; progress, difficulty and a pause-safe checkpoint are persisted locally. Help (from the venue menu) explains the controls and the current venue policy.
+
+## Venues
+
+### Hollywood Boulevard Building
+
+The original scenario places the guard at the top of the steps outside a fictional building. Tourists, street performers, influencers, confused visitors, intoxicated pedestrians, trespassers, people experiencing a mental-health crisis, and rare violent threats may approach the entrance.
+
+Authorized people must either be recognized by the guard or present a valid wristband. Wristbands can have different colors, patterns, dates, or event markings. They may be valid, expired, counterfeit, or missing.
+
+### The Joke Shop
+
+The Joke Shop is a narrow brick alley with a recessed door, shuttered windows, a warm wall lantern, a dumpster and wall-mounted AC clutter. The door person checks IDs, tickets, reservations, and guest-list status, then uses a handheld security wand according to venue policy. The player must interpret wand alerts rather than treating every alert as proof of a weapon; keys, belts, phones, and other harmless objects can trigger false alarms.
+
+### Hollywood Boulevard Late Night TV Studio
+
+This scenario combines the previously defined NPC types with a busy television-studio entrance: a stone facade, a bulb-lit canopy, a glossy black car at the curb, and stanchions/barriers holding the arrival line. The player manages audience members, production staff, performers, guests, deliveries, celebrity arrivals, tourists, street performers, influencers, confused visitors, intoxicated pedestrians, trespassers, people experiencing a mental-health crisis, and rare violent threats.
+
+The studio uses wristbands, credentials, tickets, guest-list confirmation, and personal recognition to authorize entry. Crowd control, filming boundaries, following authorized guests through the door, and counterfeit credentials are key events.
+
+## Escalation Model
+
+The common escalation model has six levels:
+
+0. **Observation** — Decide whether intervention is necessary.
+1. **Simple deterrence and polite direction** — Raise an open hand, make eye contact, point toward the sidewalk or check-in area, shake the head, or give a short instruction.
+2. **Formal warning** — Clearly explain the rule and request compliance.
+3. **Blocking and physical positioning** — Secure the entrance, maintain distance, preserve an escape route, and deny access without starting a fight.
+4. **Radio for security assistance** — Request a supervisor, second guard, building management, or other appropriate support.
+5. **Emergency response** — Hold the emergency-radio button and confirm only when there is an immediate threat, such as a weapon, assault, forced entry, or serious threat to occupants.
+
+An off-duty law-enforcement officer or armed emergency responder may arrive during a valid emergency. This character is not intended to be a routine stronger attack. Their role is crisis control, evacuation, restraint, arrest, or other appropriate intervention, with force governed by the situation and meaningful consequences for unjustified calls.
+
+## Core Systems
+
+- **NPC behavior:** NPCs have different motivations, temperaments, compliance levels, and reactions to the player’s approach.
+- **Access verification:** Recognition, wristbands, IDs, tickets, credentials, and guest lists determine who may enter.
+- **Nonverbal deterrence:** Small actions such as raising a hand can resolve low-risk situations without dialogue or force.
+- **Dialogue:** Polite directions and warnings affect outcomes; simple gestures can resolve low-risk situations without dialogue.
+- **Escalation:** The player chooses the lowest effective response.
+- **Radio assistance:** Calls require useful information and may take time to arrive.
+- **Evidence:** Body-camera records support shift review and accountability.
+- **Crowd reaction:** Aggressive behavior, visible weapons, and emergency response can create panic or attract a crowd.
+- **Reputation:** Peaceful resolutions, accurate reports, low property damage, and justified calls improve performance; unnecessary confrontations and false reports reduce it.
+- **Shift review:** The player receives feedback on access decisions, escalation choices, public complaints, injuries, and security outcomes.

docs/getting-started.md

@@ -0,0 +1,103 @@
+# Setup, Run and Test, and Controls
+
+## Setup
+
+1. Download Godot **4.7.2** (official build) and put `godot` on your PATH. The project, local tooling and CI use the same version; engine upgrades require import, headless, screenshot and Desktop HQ smoke checks before changing the baseline.
+2. Open or run the project from this directory.
+
+## Run and Test
+
+```bash
+# Open in the editor
+godot --editor --path .
+
+# Run the game
+godot --path .
+
+# Headless smoke boot (120 frames then exit)
+godot --headless --path . --quit-after 120
+
+# Run all unit tests headlessly (exit code 0 = pass)
+godot --headless --path . --script res://src/test/test_runner.gd
+
+# Save a screenshot to user:// (windowed)
+godot --path . --script res://src/test/take_screenshot.gd
+
+# Visual-regression smoke: render the staged captures + prop gallery, then compare them
+./tools/check_screenshots.sh
+
+# Windowed control smoke: focus circle, action wheel, wheel cycling + right-click clear; saves PNGs, exits 1 on failure
+godot --path . --script res://src/test/smoke_focus_radial.gd
+
+# Session-shell smoke: menu → shift → pause → settings → menu (headless or windowed)
+godot --headless --path . --script res://src/test/smoke_session_shell.gd
+
+# PLAN-verb smoke: recognize, request reason, body camera, warning, blocking
+godot --headless --path . --script res://src/test/smoke_plan_verbs.gd
+
+# Prop-collision smoke (windowed): guard stops at a bench, guest routes around it
+godot --path . --script res://src/test/smoke_props.gd
+
+# NPC budget smoke: 24 full-rig avatars against the documented frame budget
+godot --headless --path . --script res://src/test/smoke_npc_budget.gd
+
+# Movement smoke (windowed): steps, precision walk, footsteps and landing
+godot --path . --script res://src/test/smoke_movement.gd
+
+# Crowd smoke: rubbernecking on aggression, panic clearing the entrance
+godot --headless --path . --script res://src/test/smoke_crowd.gd
+
+# Emergency smoke: unjustified call, investigation note, evacuation aftermath
+godot --headless --path . --script res://src/test/smoke_emergency.gd
+
+# Body-camera timeline smoke: review → timeline → step through → back to review
+godot --headless --path . --script res://src/test/smoke_timeline.gd
+
+# Audio smoke: crowd bed follows mood, radio open/close crackle
+godot --headless --path . --script res://src/test/smoke_audio.gd
+
+# Scenario-content smoke: wand refusal, celebrity crowd spike
+godot --headless --path . --script res://src/test/smoke_scenario_content.gd
+
+# Tutorial smoke (windowed): completion, replay and skip; isolated user data
+XDG_DATA_HOME=/tmp/gigline-tutorial godot --path . --fixed-fps 60 --script res://src/test/smoke_tutorial.gd -- --tutorial
+
+# Campaign/checkpoint smoke (windowed): resume, review continue, help; isolated data
+XDG_DATA_HOME=/tmp/gigline-campaign godot --path . --fixed-fps 60 --script res://src/test/smoke_campaign.gd
+```
+
+The unit test runner is the project's own lightweight harness (no editor plugin required) so CI can run it without the editor.
+
+## Controls
+
+Keyboard and mouse are the default; a gamepad works without configuration (left stick moves,
+right stick looks, A opens/confirms the wheel, B cancels, X inspects, Y calls the radio, LB walks
+slowly, RB uses the wand). Keys and pad buttons can be rebound in Settings, and the remaps persist
+in `user://settings.json`. The HUD legend switches to gamepad hints when a pad event arrives.
+
+| Input | Action |
+| --- | --- |
+| W/A/S/D + mouse | Move and look |
+| Space / left click | Action wheel for the focused person (Stop, Look, Point, No, Ask, Inspect, Wand, Warn, Block, Reason, Recognize, Radio) |
+| A / D or ←/→ | Step through the action wheel (while it is open) |
+| Space / left click | Confirm the highlighted action (while the wheel is open) |
+| Esc / right click | Close the top panel; Esc with nothing open pauses the shift (Esc again resumes) |
+| ← / → or ↑ / ↓ | Navigate the venue menu and the pause / settings panels |
+| Enter | Start the highlighted venue from the menu, or confirm in a panel |
+| 1 / 2 / 3 | Quick gestures without the wheel: raise hand, point, head shake (Level 1) |
+| Q | Polite direction (Level 1) |
+| 4 | Formal warning (Level 2) |
+| 5 | Blocking and positioning (Level 3) |
+| 6 | Security assistance radio (Level 4) |
+| R | Emergency radio, hold on-screen button ~1.6s (Level 5) |
+| E | Inspect access artifacts / close inspection |
+| C | Handheld wand screening (wand venues only) |
+| A / D | Allow / deny entry during inspection or wand check |
+| V | Cycle venue (debug shortcut; restart via V restarts the current shift) |
+| Tab / mouse wheel ↓ / ↑ | Cycle the target among nearby NPCs, nearest first (aim-free; the target stays selected) |
+| Right click (nothing open) | Clear the focused person and return to aim-based focus |
+| Shift (hold) | Precision walk at roughly half speed for close work at the door |
+| G | Toggle flashlight (widens NPC perception at night) |
+| B | Toggle the body camera; a formal warning switches it on automatically |
+| L | Lock / unlock the restricted door (thwarts forced entry) |
+| F | Toggle debug overlay |

docs/plan-graphics-v0.6.md

@@ -1,293 +0,0 @@
-# Development Plan — Graphics Quality v0.6.0 (Blender-authored NPCs)
-
-> Status: Proposed · Target version: **v0.6.0** (MINOR)
-> Companion decision: [ADR-0013](adr/0013-blender-authored-npc-characters.md)
-
-## Why this exists
-
-The game is functionally complete through v0.5.0, but NPCs are still the
-procedural capsule-and-box rig from [ADR-0010](adr/0010-procedural-npc-presentation.md).
-They read as people at conversation distance but not at cinematic distance, and
-every surface on a body is a flat color. ADR-0010 recorded that "a later
-skinned-mesh pass will replace this rig and must keep the `Head` contract" —
-this plan is that pass.
-
-The goal is **better NPCs first**, then a modest environment lift, using the
-existing AI tooling for art direction and quality gates, and **Blender** for the
-geometry, UVs, skeleton, and baked material maps.
-
-## Constraints that shape the plan
-
-- **Renderer is GL Compatibility** (`project.godot` `config/features`). SSAO,
-  SSIL, and volumetrics are unavailable. Quality therefore comes from better
-  meshes, baked maps (AO/normal/roughness), and lighting — not from a renderer
-  switch.
-- **CI builds offline.** `.gitea/workflows/build.yml` runs the Godot editor only
-  (no Blender, no network). Everything the game loads must be committed; the
-  Blender step is a developer tool, and the game keeps a procedural fallback so a
-  fresh checkout still boots and the headless suite still passes.
-- **Determinism.** Seed-driven variety (`outfit_for`, `layer_for`,
-  `hand_item_for`, `idle_style_for`) must keep working and keep its tests green.
-  AI generation is a dev-time input, not a runtime dependency; the committed
-  assets are the source of truth.
-- **Frame budget.** v0.5.0 measured 16 avatars = 534 meshes ≈ 6.9 ms headless.
-  A skinned rig replaces ~33 draw calls per avatar with one skin, but skinning
-  costs CPU. Re-measure with `src/test/smoke_npc_budget.gd` before raising
-  `MAX_LIVE_NPCS`.
-
-## The NPC asset contract (what must not break)
-
-From `src/game/npc_avatar.gd` and `src/game/guard_controller.gd`:
-
-- A scene-level node named **`Rig/Head`** — `GuardController` raycasts for it
-  (`get_node_or_null("Rig/Head")`), and the focus circle + name tag + reaction
-  tag attach under it.
-- Limb pivots currently named `HipL`/`HipR` → `Knee`, `ShoulderL`/`ShoulderR` →
-  `Elbow` → `Hand`. `_animate()` and `_idle_layer()` drive them by `rotation.x`.
-- Pure static helpers must stay pure and seed-deterministic: `outfit_for`,
-  `layer_for`, `hand_item_for`, `idle_style_for`, `queue_slot_for`,
-  `lod_tier_for_distance`, `reaction_label`, `crouch_for_pose`,
-  `prop_lift_for_pose`, `limb_swing`, `sway_for_pose`.
-- LOD tiers (`apply_lod`, 0 / 1 / 2 with a billboard impostor at tier 2) must
-  keep working; `_detail_nodes` are hidden at tier 1.
-- `set_focus_visual`, `_focus_circle`, `_name_tag`, `_reaction_tag`, the
-  theater poses, and the crowd reaction (`start_rubberneck`, `start_flee`) all
-  operate on the rig and must survive the swap.
-
-## Workstreams
-
-### Phase 0 — Toolchain spike and contract freeze (small, throwaway)
-
-1. Confirm headless Blender works in this environment. Blender **5.2.0 LTS**
-   flatpak is installed; the sandbox cwd is `/app/blender`, so `--python` and
-   all input/output paths must be absolute:
-
-   ```bash
-   flatpak run org.blender.Blender --background \
-     --python /var/home/zwitschi/Documents/06-games/security-game/tools/npc_pipeline.py -- --build
-   ```
-
-   Record the working invocation in `MEMORY.md` (the Im-Dornäcker notes already
-   warn about the cwd gotcha).
-2. Freeze the asset contract in writing (this document + ADR-0013). No
-   animation clips are exported: `_animate()` and `_idle_layer()` drive the
-   armature bones directly at runtime, so the GLB only needs the skinned rest
-   mesh, the armature, and the material maps.
-   - `assets/models/generated/npc_base.glb` — one skinned mesh (or a small fixed
-     set of sub-meshes: body / head / hands) with a **named armature** and UVs.
-   - Material slots rather than one atlas-per-prop: `skin`, `cloth`,
-     `pants`, `accessory`, `hair` each carry a neutral albedo + normal + ORM
-     (occlusion/roughness/metallic) map. `outfit_for` colors tint the slot, so
-     multi-color outfits and seed variety survive.
-   - Bone names mirror the current node names (`Head`, `HipL/R`, `KneeL/R`,
-     `ShoulderL/R`, `ElbowL/R`, `HandL/R`) so `_animate()` can target them.
-   - Budget: tier-0 base body ≤ ~6,000 triangles, ≤ ~4,000 vertices (revisit
-     after the first `smoke_npc_budget.gd` run).
-
-### Phase 1 — `tools/npc_pipeline.py`: author + export + audit
-
-New tool, run through the Blender flatpak, mirroring the `model_pipeline.py`
-shape (`list` / `build` / `audit`):
-
-1. **Author** a low-poly base humanoid in Blender: torso, articulated arms/legs,
-   head with a face front (so the focus ring and the "noticed the guard" cue
-   keep a direction), hands, shoes. Keep the current silhouette language
-   (heads, caps, hoods, backpacks, lanyards) so existing `outfit_for`
-   accessories still attach.
-2. **Rig** it with an armature whose bones are named to match the node contract.
-   Godot 4.3 imports glTF skeletons as `Skeleton3D`; keep the bone rest pose
-   matching the current `_animate()` assumptions (arms hang, legs straight,
-   +Y up, origin at the feet on the floor).
-3. **UV-unwrap** into a power-of-two layout and **bake** maps in Blender from
-   node materials or a higher-detail source:
-   - neutral albedo (white fabric pattern) per material slot,
-   - normal map (fabric weave, denim, knit),
-   - ORM map (occlusion in R, roughness in G, metallic in B — same packing
-     `model_pipeline.atlas_for` already uses),
-   - ambient occlusion baked into the albedo or the ORM R channel (this is the
-     Compatibility renderer's only AO source).
-4. **Export** `npc_base.glb` with materials referenced as Godot-importable
-   textures (or export textures alongside and wire them in GDScript — decide in
-   the spike).
-5. **Audit** (`npc_pipeline.py audit`) enforcing: UVs in [0,1], expected bone
-   names present, triangle/vertex budget, feet at y ≈ 0, no missing material
-   slots. Reuse the checks and the colour-space discipline from
-   `model_pipeline.py` (glTF `baseColorFactor` is linear; albedo textures are
-   sRGB — do not mix them up).
-6. **Commit** the `.blend` source (`assets/models/npc/npc_base.blend`) so the
-   build is reproducible and editable, plus the generated `.glb` + textures so
-   CI never needs Blender.
-
-### Phase 2 — AI-assisted texturing (existing tools only)
-
-Use the tools already in `tools/`, not new services:
-
-1. `tools/asset_pipeline.py generate` (OpenRouter,
-   `openai/gpt-5-image-mini`) for seamless clothing albedos — shirt, trousers,
-   jacket, hi-vis vest, coat, dress — at the role sizes its `audit` validates.
-   Run `seamless` for tile-edge blending and `audit` to reject wrong sizes.
-2. `tools/model_pipeline.py`'s palette helpers (`dominant_colors`,
-   `assign_roles`) or a small shared import, to derive per-role outfit palettes
-   from AI concept sheets (`concept`). `outfit_for` keeps determinism: the AI
-   supplies palettes and textures, never per-frame randomness.
-3. Normal/roughness detail (fabric weave, denim) baked procedurally in Blender,
-   with the AI albedos layered on top.
-4. Close the loop with `tools/screen_designs.py judge`: regenerate the staged
-   captures and confirm the new NPCs realise the same screen intents (art style
-   is ignored by the judge; layout and readability are not).
-
-Outputs land under `assets/textures/ai/game_ready/` (or a new
-`assets/textures/npc/`) and are **committed**.
-
-### Phase 3 — Godot integration (`npc_avatar.gd`, `materials.gd`)
-
-1. Add a `_load_model()` path in `NpcAvatar` that instantiates the imported
-   `npc_base.glb` `PackedScene`, exactly like `WorldBuilder._add_prop_model()`
-   loads props. Keep `_build_body()` as the offline/procedural fallback; choose
-   per-avatar with the same "asset or fallback" pattern (record the choice in a
-   `loaded_model` / `fallback_avatar` field for tests).
-2. Map `outfit_for()` onto the model's material slots (skin/cloth/pants/
-   accessory/hair) so seed variety, `layer_for`, `hand_item_for`, and the
-   archetype color read stay intact. Accessories (cap/hood/backpack/
-   sunglasses/lanyard) keep attaching under `Rig`/`Head` as they do today.
-3. Add `SurfaceMaterials` recipes for the baked maps — e.g. `npc()` /
-   `skin()` / `cloth()` — so `_material()` gains a textured path and the body
-   stops calling `Materials.flat()`.
-4. Abstract the animation targets so `_animate()` / `_idle_layer()` write to
-   either the procedural `Node3D` pivots (fallback) or `Skeleton3D` bones
-   (skinned). Keep the existing `rotation.x` math; the abstraction is a thin
-   `_set_limb_rotation(part, axis, radians)` wrapper.
-5. Keep `Rig/Head` as a real scene node (a marker following the head bone, or
-   the imported bone's Godot node) so focus, nametag, and head-turn still find
-   it. Re-verify the focus cone smoke and `test_npc_character` /
-   `test_npc_theater` / `test_target_cycle`.
-6. Re-measure `smoke_npc_budget.gd`; adjust `LOD_TIERS` if the skinned rig is
-   heavier up close. The impostor path is unchanged.
-
-### Phase 3.5 — Blender asset library (characters, gear, props)
-
-The library generator is `tools/blender_assets.py` (flatpak Blender, headless).
-**Status: integrated** — `NpcAvatar` selects characters/gear and `WorldBuilder`
-loads the replacement/new props plus phase-driven emissives; the procedural rig
-and primitive props remain fallbacks. Integration notes:
-[`blender-assets.md`](blender-assets.md).
-
-**Outputs and contract**
-
-| Kind | Path | Notes |
-| --- | --- | --- |
-| Characters | `assets/models/blender/npc/<name>.glb` | 8 variants: `npc_casual`, `npc_jacket`, `npc_coat`, `npc_vest`, `npc_dress`, `npc_hoodie`, `npc_firefighter`, `npc_guard` |
-| Gear | `assets/models/blender/npc_gear/<name>.glb` | 18 pieces; authored in attach-point space (`head`, `hand`, `back`, `chest`) |
-| Props | `assets/models/blender/props/<name>.glb` | 20 pieces; the first nine replace current generated/primitive street furniture, the rest are new venue dressing |
-| Manifest | `assets/models/blender/manifest.json` | path, category, triangles, vertices, bounds, materials, roles, tint slots, attach points |
-| Sources | `assets/models/blender_src/<name>.blend` | committed, editable source |
-| Previews | `docs/blender_previews/sheet_<category>.jpg` (committed) + per-asset `*.png` (local) | `render` / `sheet` for visual review |
-
-All characters reuse the `npc_base` contract: mesh node `npc_base`, bones
-`Head/HipL/R/KneeL/R/ShoulderL/R/ElbowL/R/HandL/R` (+ Hips/Spine/Neck),
-material slots `skin/cloth/pants/accessory/hair`, front toward Blender `-Y`
-(Godot `+Z`), feet at `y ~= 0`. Gear origins are the attach points (head at
-`Rig/Head`, hand at the hand proxy, back at the spine, chest at the sternum).
-Props are grounded except `wall_lantern` and `marquee`; both may be emissive.
-
-**Integration steps**
-
-1. **Audit the finished build.** `python3 tools/blender_assets.py audit` and
-   `sheet`; fix assets or reconcile the budgets. **Done 2026-11-01:** the
-   characters were simplified to fit the unchanged 6,000 / 4,000 contract
-   (3,788–4,640 tris), and all 46 assets audit clean.
-2. **Commit the library and sources.** Add `assets/models/blender/**`,
-   `assets/models/blender_src/**`, the generator, manifest, previews, and
-   `docs/blender-assets.md`; generated folders that CI can rebuild offline may
-   stay ignored. `blender_assets.py audit` must work without Blender.
-3. **Select characters by role.** Extend `NpcAvatar` to pick a variant from the
-   manifest using the profile's role and `outfit_for`/`layer_for` (casual,
-   jacket, coat, vest, dress, hoodie, firefighter, guard). Fall back to
-   `npc_base.glb`, then to the procedural rig, and record the chosen path.
-4. **Tint and anchor.** Apply `outfit_for` to every variant's five slots via
-   `SurfaceMaterials.npc_slot()`; keep `Rig/Head` for the focus circle, name tag,
-   reaction tag, and accessories. Keep the walk/idle/escalation bone-driving
-   wrapper.
-5. **Replace procedural gear.** Use the `npc_gear` catalogue for caps, hoods,
-   helmets, backpacks, lanyards, hand items (phone, cup, clipboard, umbrella,
-   camera, sign, flashlight, wand, radio) and the SCBA tank; attach at the
-   documented points and fall back to the current primitives when an asset is
-   missing.
-6. **Replace and extend props.** Load the replacement set through
-   `WorldBuilder` (`bollard`, `bench`, `trash_bin`, `planter_box`,
-   `newspaper_box`, `fire_hydrant`, `street_lamp`, `street_tree`,
-   `traffic_cone`), then place the new dressing (`palm_tree`, `round_planter`,
-   `a_frame_sign`, `wall_lantern`, `crowd_barrier`, `stanchion`, `handrail`,
-   `security_podium`, `double_door`, `marquee`, `sedan`) using the existing
-   placement table/collider/avoidance contract. No prop may enter the
-   door/steps/guest lane.
-7. **Wire emissives to the phase.** Street-lamp bulbs, wall lanterns, the door
-   lock LED, marquee bulbs/sign face, and sedan headlights should follow the
-   existing day/night lighting rather than staying always on.
-8. **Measure and gate.** Re-run `smoke_npc_budget.gd` with the new characters
-   before raising `MAX_LIVE_NPCS`; add a prop triangle/draw budget check. Then
-   recapture `docs/screenshots/` and run `screen_designs.py compare` + `judge`
-   plus a close-up target shot for character readability.
-9. **Fallbacks stay offline.** A fresh checkout with no Blender and no network
-   must boot on the committed library (or `npc_base.glb`/procedural rig when an
-   asset is absent); CI still runs the Godot import and headless suite.
-
-
-### Phase 4 — Environment and lighting lift (after NPCs land) ✅
-
-1. **Baked AO on props:** use the Phase 3.5 Blender prop replacements
-   (`street_lamp`, `street_tree`, `bench`, …) and bake AO into their
-   albedo/ORM maps so contact shadows read without SSAO. Keep the same
-   `WorldBuilder` load/fallback contract (ADR-0012's follow-up).
-2. **Higher-resolution environment textures:** regenerate brick/concrete/asphalt
-   through `asset_pipeline.py` with normal maps, keeping the current UV scales;
-   use the same sRGB/albedo + packed ORM discipline as the library assets.
-3. **Evaluate a desktop-only Forward+ preset** — done: it boots on the desktop Vulkan
-driver, but the renderer is project-wide and the Web preset must stay GL
-Compatibility. v0.6.0 keeps Compatibility; a desktop-only override is deferred.
-4. Regenerate `docs/screenshots/` with `capture_screenshots.gd`, then run
-   `screen_designs.py compare` and `judge` as the regression gate, plus
-   `blender_assets.py sheet` for the character/gear/prop library.
-
-### Phase 5 — Verification and release
-
-- Headless: fallback build, `npc_pipeline.py audit` (via `test_model_pipeline`
-  style Python tests if Blender is present, otherwise skip with reason), outfit
-  determinism, `Rig/Head` presence, material recipe assertions.
-- Windowed smokes: `smoke_npc_budget.gd`, `smoke_movement.gd`,
-  `smoke_focus_radial.gd`, `smoke_props.gd`; screenshot comparison.
-- Bump `config/version` to `0.6.0`, update `README.md`, `docs/architecture.md`
-  (Level 2 gains `tools/npc_pipeline.py`), and publish per
-  [`docs/RELEASING.md`](RELEASING.md).
-
-## Risks and mitigations
-
-| Risk | Mitigation |
-| --- | --- |
-| Blender flatpak sandbox paths (cwd `/app/blender`) | Absolute paths everywhere; record the invocation in `MEMORY.md`. |
-| glTF colour space (linear factors vs sRGB textures) | Reuse `model_pipeline.srgb_to_linear`; bake textures as sRGB, keep factors linear; assert in `audit`. |
-| Skeleton retargeting vs current node math | Keep the bone names + a thin limb-rotation wrapper; fallback rig keeps old math running. |
-| Frame budget with skinned avatars | Measure first (`smoke_npc_budget.gd`); tune `LOD_TIERS`; impostor path unchanged. |
-| No SSAO in Compatibility | Bake AO into albedo/ORM; contact-shadow tune in Phase 4. |
-| AI output nondeterminism | Generation is dev-time only; commit outputs and gate with `audit`/`judge`/`compare`. |
-| Blender unavailable in CI | Committed `.glb` + textures; procedural fallback; `audit` skipped with reason when Blender is absent. |
-
-## Acceptance criteria (definition of done)
-
-1. NPCs and street furniture are Blender-authored meshes with baked maps; the
-   character variants, gear, and props read as people/objects at conversation
-   distance and survive a cinematic close-up.
-2. `Rig/Head`, the focus cone, nametag, theater poses, crowd reactions, and LOD
-   all still work; all existing NPC tests pass unchanged or are updated with
-   clear reasons.
-3. The game boots and plays from a fresh checkout with **no** Blender and no
-   network (committed assets + procedural fallback).
-4. `npc_pipeline.py build` is deterministic and `audit` enforces the contract.
-5. 212 headless + 60 Python tests stay green (Blender-dependent Python tests
-   skip with a reason when Blender is absent); `npc_pipeline.py audit` and
-   `blender_assets.py audit` pass; NPC-budget and movement smokes pass;
-   screenshot `compare`/`judge` and the library contact sheets show no
-   regressions.
-6. The library is committed with its generator/manifest/previews, runtime
-   selection and fallbacks are covered by tests, version bumped to v0.6.0,
-   docs and ADR-0013 updated, release published.

docs/screens/concepts/README.md

@@ -20,9 +20,15 @@ file here; they are saved as `<name>-vN.png`.
 | `entrance_steps_podium` | granite steps, handrails, glass doors, the check-in podium |
 | `crowd_barrier_line` | steel barriers, a red carpet, a crowd with depth-of-field haze |
 | `responder_arrival_wide` | fire engine, turnout gear, red/blue light spill on wet pavement |
+| `npc_portrait_day` | close portrait of a pedestrian: skin with visible pores and stubble, fabric weave, shallow depth of field. The bar for an avatar close-up, not for the crowd shots |
 
-Cross-cutting targets, for comparison with the 2026-11-01 captures in
-`docs/screens/realism/2026-11-01-v2/sheet.jpg`:
+The `npc_portrait` capture in `capture_realism.gd` is staged, not posed by the
+crowd: it freezes one NPC on an open patch of sidewalk, parks the rest of the
+crowd out of frame, turns the subject into the camera and stands the guard on the
+sunlit side. It is the only shot where a face fills the frame, so it is the one to
+eyeball after an avatar change (generate a local run under `docs/screens/realism/`).
+
+Cross-cutting targets, for comparison with locally generated realism runs:
 
 - **Exposure.** The concepts keep the ground mid-grey. The game's sidewalk is close to white,
   so it is overexposed.

docs/screens/realism/2026-11-01-adopt/report.json

@@ -1,878 +0,0 @@
-{
-  "run": "docs/screens/realism/2026-11-01-adopt",
-  "judge_model": "google/gemini-2.5-flash",
-  "sets": {
-    "after": {
-      "boulevard_day": {
-        "target": "docs/screens/concepts/boulevard_skyline_day.png",
-        "metrics": {
-          "edge_density": 23.21,
-          "fine_detail": 8.88,
-          "contrast": 38.78,
-          "saturation_mean": 99.58,
-          "colour_spread": 46.73
-        },
-        "target_metrics": {
-          "edge_density": 20.74,
-          "fine_detail": 8.23,
-          "contrast": 54.85,
-          "saturation_mean": 73.09,
-          "colour_spread": 58.16
-        },
-        "metric_gap": 0.172,
-        "judge": {
-          "scores": {
-            "overall": 1.0,
-            "backdrop": 3.0,
-            "lighting": 1.0,
-            "characters": 0.0,
-            "texture_detail": 1.0,
-            "materials": 1.0
-          },
-          "score_range": {
-            "overall": [
-              1.0,
-              1.0
-            ],
-            "backdrop": [
-              3.0,
-              3.0
-            ],
-            "lighting": [
-              1.0,
-              1.0
-            ],
-            "characters": [
-              0.0,
-              0.0
-            ],
-            "texture_detail": [
-              1.0,
-              1.0
-            ],
-            "materials": [
-              1.0,
-              1.0
-            ]
-          },
-          "runs": 3,
-          "fixes": [
-            "Implement physically based rendering (PBR) materials for all assets, focusing on realistic albedo, roughness, and metallic maps to achieve accurate surface responses to light.",
-            "Overhaul lighting system to include global illumination, realistic skybox/HDRI for ambient light, and accurate sun/directional light with proper shadows and atmospheric scattering (haze/fog).",
-            "Replace placeholder low-polygon models with high-detail 3D assets for trees, street furniture, and buildings, ensuring proper UV mapping and texture application.",
-            "Improve texture resolution and detail across all surfaces, adding normal maps for surface imperfections and detail, and ensuring textures are seamlessly tiled or uniquely mapped where appropriate.",
-            "Develop a realistic character pipeline, including high-fidelity models, animations, and PBR materials for skin, clothing, and hair, to populate the scene."
-          ]
-        }
-      },
-      "boulevard_night": {
-        "target": "docs/screens/concepts/hollywood_entrance_rain_night.png",
-        "metrics": {
-          "edge_density": 16.02,
-          "fine_detail": 7.13,
-          "contrast": 39.4,
-          "saturation_mean": 163.01,
-          "colour_spread": 40.42
-        },
-        "target_metrics": {
-          "edge_density": 8.43,
-          "fine_detail": 3.51,
-          "contrast": 27.34,
-          "saturation_mean": 159.44,
-          "colour_spread": 26.61
-        },
-        "metric_gap": 0.723,
-        "judge": {
-          "scores": {
-            "overall": 1.0,
-            "backdrop": 2.0,
-            "lighting": 1.0,
-            "characters": 1.0,
-            "texture_detail": 1.0,
-            "materials": 1.0
-          },
-          "score_range": {
-            "overall": [
-              1.0,
-              1.0
-            ],
-            "backdrop": [
-              2.0,
-              2.0
-            ],
-            "lighting": [
-              1.0,
-              1.0
-            ],
-            "characters": [
-              1.0,
-              1.0
-            ],
-            "texture_detail": [
-              1.0,
-              1.0
-            ],
-            "materials": [
-              1.0,
-              1.0
-            ]
-          },
-          "runs": 3,
-          "fixes": [
-            "Implement a physically based rendering (PBR) material pipeline for all assets to achieve realistic surface responses to light, especially for wet surfaces and brick.",
-            "Overhaul the lighting system to include global illumination, volumetric fog/rain, and realistic light sources with proper falloff and color temperature, focusing on dramatic contrast and mood.",
-            "Replace low-polygon models with high-detail meshes and high-resolution textures, including normal and roughness maps, for all environmental elements (buildings, street, props, characters).",
-            "Redesign the backdrop with a more detailed and atmospheric skyline, incorporating distance haze, subtle cloud formations, and appropriate night sky colors to match the target's mood.",
-            "Update character models to be realistic, with detailed clothing, skin, and hair textures, and implement realistic animation and shading."
-          ]
-        }
-      },
-      "entrance_day": {
-        "target": "docs/screens/concepts/hollywood_entrance_morning.png",
-        "metrics": {
-          "edge_density": 25.88,
-          "fine_detail": 9.86,
-          "contrast": 40.18,
-          "saturation_mean": 93.04,
-          "colour_spread": 43.24
-        },
-        "target_metrics": {
-          "edge_density": 16.87,
-          "fine_detail": 6.92,
-          "contrast": 70.27,
-          "saturation_mean": 121.02,
-          "colour_spread": 69.83
-        },
-        "metric_gap": 0.442,
-        "judge": {
-          "scores": {
-            "overall": 1.0,
-            "backdrop": 0.0,
-            "lighting": 1.0,
-            "characters": 0.0,
-            "texture_detail": 1.0,
-            "materials": 1.0
-          },
-          "score_range": {
-            "overall": [
-              1.0,
-              1.0
-            ],
-            "backdrop": [
-              0.0,
-              0.0
-            ],
-            "lighting": [
-              1.0,
-              1.0
-            ],
-            "characters": [
-              0.0,
-              0.0
-            ],
-            "texture_detail": [
-              1.0,
-              1.0
-            ],
-            "materials": [
-              1.0,
-              1.0
-            ]
-          },
-          "runs": 3,
-          "fixes": [
-            "Implement a physically based rendering (PBR) material pipeline for all assets to achieve realistic surface responses to light.",
-            "Overhaul the lighting system to include global illumination, realistic skyboxes with atmospheric scattering, and dynamic shadows.",
-            "Replace placeholder low-polygon models with high-fidelity assets that include detailed normal maps and displacement maps for architectural elements, foliage, and street furniture.",
-            "Develop a detailed backdrop with distant buildings, varied skyline, and atmospheric haze to create depth and realism.",
-            "Add realistic foliage models with proper leaf textures, branch structures, and varied forms instead of simple geometric shapes."
-          ]
-        }
-      },
-      "entrance_late": {
-        "target": "docs/screens/concepts/hollywood_entrance_rain_night.png",
-        "metrics": {
-          "edge_density": 18.4,
-          "fine_detail": 8.41,
-          "contrast": 51.61,
-          "saturation_mean": 127.4,
-          "colour_spread": 51.96
-        },
-        "target_metrics": {
-          "edge_density": 8.43,
-          "fine_detail": 3.51,
-          "contrast": 27.34,
-          "saturation_mean": 159.44,
-          "colour_spread": 26.61
-        },
-        "metric_gap": 1.105,
-        "judge": {
-          "scores": {
-            "overall": 1.0,
-            "backdrop": 0.0,
-            "lighting": 1.0,
-            "characters": 0.0,
-            "texture_detail": 1.33,
-            "materials": 1.33
-          },
-          "score_range": {
-            "overall": [
-              1.0,
-              1.0
-            ],
-            "backdrop": [
-              0.0,
-              0.0
-            ],
-            "lighting": [
-              1.0,
-              1.0
-            ],
-            "characters": [
-              0.0,
-              0.0
-            ],
-            "texture_detail": [
-              1.0,
-              2.0
-            ],
-            "materials": [
-              1.0,
-              2.0
-            ]
-          },
-          "runs": 3,
-          "fixes": [
-            "Implement volumetric fog and rain effects to create atmospheric depth and mood, especially around light sources.",
-            "Overhaul lighting system to include realistic light falloff, bounce light, and wet surface reflections, focusing on the marquee and streetlights.",
-            "Redesign all materials with PBR workflows, ensuring accurate roughness, metallic, and normal maps for brick, concrete, metal, and wet surfaces.",
-            "Add high-resolution, detailed textures for all surfaces, particularly the brickwork, sidewalk, and marquee, to capture fine imperfections and wear.",
-            "Develop a detailed backdrop with distant buildings, subtle city lights, and atmospheric haze to replace the current flat sky."
-          ]
-        }
-      },
-      "joke_shop_door": {
-        "target": "docs/screens/concepts/joke_shop_door_closeup.png",
-        "metrics": {
-          "edge_density": 14.84,
-          "fine_detail": 7.04,
-          "contrast": 47.63,
-          "saturation_mean": 132.89,
-          "colour_spread": 49.43
-        },
-        "target_metrics": {
-          "edge_density": 9.79,
-          "fine_detail": 3.59,
-          "contrast": 26.09,
-          "saturation_mean": 117.17,
-          "colour_spread": 25.09
-        },
-        "metric_gap": 0.818,
-        "judge": {
-          "scores": {
-            "overall": 2.0,
-            "backdrop": 4.0,
-            "lighting": 2.0,
-            "characters": 0.0,
-            "texture_detail": 3.0,
-            "materials": 3.0
-          },
-          "score_range": {
-            "overall": [
-              2.0,
-              2.0
-            ],
-            "backdrop": [
-              4.0,
-              4.0
-            ],
-            "lighting": [
-              2.0,
-              2.0
-            ],
-            "characters": [
-              0.0,
-              0.0
-            ],
-            "texture_detail": [
-              3.0,
-              3.0
-            ],
-            "materials": [
-              3.0,
-              3.0
-            ]
-          },
-          "runs": 3,
-          "fixes": [
-            "Implement physically based rendering (PBR) materials for all surfaces, especially brick, wood, and metal, to achieve realistic light interaction and surface properties.",
-            "Overhaul the lighting system to include more nuanced light sources, volumetric effects, and global illumination. Focus on creating warm, inviting pools of light around entrances and signs, with realistic falloff and shadows.",
-            "Improve texture resolution and detail for all assets, particularly the brickwork, ground, and signage. Add normal maps and displacement maps to give surfaces depth and tactile quality.",
-            "Redesign the 'Comedy Club' sign to be a prominent, well-lit feature with appropriate emissive materials and a more stylized font, similar to the target image's 'COMEDY CLUB' sign.",
-            "Enhance the backdrop with more detailed city lights, atmospheric haze, and a more realistic skybox to create a sense of depth and a believable urban environment."
-          ]
-        }
-      },
-      "street_day": {
-        "target": "docs/screens/concepts/boulevard_skyline_day.png",
-        "metrics": {
-          "edge_density": 18.69,
-          "fine_detail": 7.42,
-          "contrast": 42.69,
-          "saturation_mean": 106.86,
-          "colour_spread": 48.19
-        },
-        "target_metrics": {
-          "edge_density": 20.74,
-          "fine_detail": 8.23,
-          "contrast": 54.85,
-          "saturation_mean": 73.09,
-          "colour_spread": 58.16
-        },
-        "metric_gap": 0.148,
-        "judge": {
-          "scores": {
-            "overall": 1.0,
-            "backdrop": 2.0,
-            "lighting": 1.0,
-            "characters": 0.0,
-            "texture_detail": 1.0,
-            "materials": 1.0
-          },
-          "score_range": {
-            "overall": [
-              1.0,
-              1.0
-            ],
-            "backdrop": [
-              2.0,
-              2.0
-            ],
-            "lighting": [
-              1.0,
-              1.0
-            ],
-            "characters": [
-              0.0,
-              0.0
-            ],
-            "texture_detail": [
-              1.0,
-              1.0
-            ],
-            "materials": [
-              1.0,
-              1.0
-            ]
-          },
-          "runs": 3,
-          "fixes": [
-            "Implement physically based rendering (PBR) materials for all assets, focusing on realistic albedo, roughness, and metallic values to achieve accurate light interaction.",
-            "Overhaul the lighting system to include a directional light representing the sun, a skybox/HDRI for ambient light, and global illumination to simulate bounced light, matching the target's clear, bright, and slightly warm daylight.",
-            "Replace placeholder geometry with high-fidelity 3D models for cars, buildings, and environmental elements (e.g., palm trees, streetlights, sidewalks) that match the realistic proportions and details of the target image.",
-            "Develop detailed textures for all surfaces, including road asphalt, concrete sidewalks, building facades, and foliage, ensuring appropriate resolution and variety to avoid tiling artifacts and enhance realism.",
-            "Create a realistic backdrop with a detailed skyline, atmospheric perspective (distance haze), and a clear blue sky that accurately reflects the target's Los Angeles aesthetic, integrating it seamlessly with the foreground."
-          ]
-        }
-      },
-      "street_late": {
-        "target": "docs/screens/concepts/boulevard_skyline_dusk.png",
-        "metrics": {
-          "edge_density": 12.95,
-          "fine_detail": 6.27,
-          "contrast": 31.94,
-          "saturation_mean": 122.75,
-          "colour_spread": 36.44
-        },
-        "target_metrics": {
-          "edge_density": 8.83,
-          "fine_detail": 4.61,
-          "contrast": 33.26,
-          "saturation_mean": 188.16,
-          "colour_spread": 35.38
-        },
-        "metric_gap": 0.224,
-        "judge": {
-          "scores": {
-            "overall": 0.0,
-            "backdrop": 0.0,
-            "lighting": 0.0,
-            "characters": 0.0,
-            "texture_detail": 0.0,
-            "materials": 0.0
-          },
-          "score_range": {
-            "overall": [
-              0.0,
-              0.0
-            ],
-            "backdrop": [
-              0.0,
-              0.0
-            ],
-            "lighting": [
-              0.0,
-              0.0
-            ],
-            "characters": [
-              0.0,
-              0.0
-            ],
-            "texture_detail": [
-              0.0,
-              0.0
-            ],
-            "materials": [
-              0.0,
-              0.0
-            ]
-          },
-          "runs": 3,
-          "fixes": [
-            "Implement a full physically-based lighting model with global illumination, volumetric fog, and atmospheric scattering to achieve realistic sunset colors and light interaction.",
-            "Replace placeholder geometry with detailed 3D models for buildings, palm trees, and vehicles, ensuring proper scale and architectural variety.",
-            "Develop high-resolution PBR (Physically Based Rendering) materials for all surfaces, including reflective wet asphalt, glowing neon signs, and varied building facades, with appropriate roughness, metallic, and normal maps.",
-            "Create a dynamic skybox system that accurately renders sunset gradients, distant city skylines with emissive windows, and atmospheric haze, replacing the current flat backdrop.",
-            "Add realistic character models with appropriate clothing and animations to populate the scene, contributing to the overall realism and sense of a living city."
-          ]
-        }
-      },
-      "street_night": {
-        "target": "docs/screens/concepts/boulevard_skyline_dusk.png",
-        "metrics": {
-          "edge_density": 10.97,
-          "fine_detail": 5.57,
-          "contrast": 24.27,
-          "saturation_mean": 190.35,
-          "colour_spread": 25.15
-        },
-        "target_metrics": {
-          "edge_density": 8.83,
-          "fine_detail": 4.61,
-          "contrast": 33.26,
-          "saturation_mean": 188.16,
-          "colour_spread": 35.38
-        },
-        "metric_gap": 0.253,
-        "judge": {
-          "scores": {
-            "overall": 1.0,
-            "backdrop": 1.0,
-            "lighting": 1.0,
-            "characters": 0.0,
-            "texture_detail": 1.0,
-            "materials": 1.0
-          },
-          "score_range": {
-            "overall": [
-              1.0,
-              1.0
-            ],
-            "backdrop": [
-              1.0,
-              1.0
-            ],
-            "lighting": [
-              1.0,
-              1.0
-            ],
-            "characters": [
-              0.0,
-              0.0
-            ],
-            "texture_detail": [
-              1.0,
-              1.0
-            ],
-            "materials": [
-              1.0,
-              1.0
-            ]
-          },
-          "runs": 3,
-          "fixes": [
-            "Implement a full physically-based lighting model with global illumination, volumetric fog, and proper emissive materials for signs and car lights to capture the sunset glow and light trails.",
-            "Replace placeholder geometry with detailed 3D models for buildings, palm trees, and vehicles, ensuring accurate proportions and architectural details.",
-            "Develop high-resolution PBR textures for all surfaces (roads, buildings, signs, vehicles) with appropriate albedo, roughness, metallic, and normal maps to add realism and detail.",
-            "Create a dynamic skybox with a realistic sunset gradient, distant city skyline with illuminated windows, and atmospheric haze to match the target's depth and mood.",
-            "Add realistic character models with appropriate clothing and animations to populate the scene and enhance the sense of a living city."
-          ]
-        }
-      },
-      "studio_door": {
-        "target": "docs/screens/concepts/studio_stage_door_night.png",
-        "metrics": {
-          "edge_density": 16.62,
-          "fine_detail": 7.65,
-          "contrast": 48.52,
-          "saturation_mean": 133.55,
-          "colour_spread": 49.81
-        },
-        "target_metrics": {
-          "edge_density": 11.39,
-          "fine_detail": 4.87,
-          "contrast": 39.17,
-          "saturation_mean": 104.49,
-          "colour_spread": 38.0
-        },
-        "metric_gap": 0.395,
-        "judge": {
-          "scores": {
-            "overall": 1.0,
-            "backdrop": 0.0,
-            "lighting": 1.0,
-            "characters": 0.0,
-            "texture_detail": 1.0,
-            "materials": 1.0
-          },
-          "score_range": {
-            "overall": [
-              1.0,
-              1.0
-            ],
-            "backdrop": [
-              0.0,
-              0.0
-            ],
-            "lighting": [
-              1.0,
-              1.0
-            ],
-            "characters": [
-              0.0,
-              0.0
-            ],
-            "texture_detail": [
-              1.0,
-              1.0
-            ],
-            "materials": [
-              1.0,
-              1.0
-            ]
-          },
-          "runs": 3,
-          "fixes": [
-            "Implement physically based rendering (PBR) materials for all surfaces, focusing on realistic albedo, roughness, and metallic values to achieve accurate light interaction.",
-            "Overhaul the lighting system to include global illumination, volumetric fog, and realistic light sources with proper falloff and color temperature, especially for the marquee and wall sconces.",
-            "Add high-resolution, detailed textures with normal and displacement maps for brickwork, concrete, and metallic elements to introduce surface imperfections and depth.",
-            "Develop a realistic backdrop with a distant city skyline, atmospheric haze, and a dark, moody sky to establish a sense of depth and environment.",
-            "Introduce realistic 3D character models with proper clothing, hair, and skin shaders, along with a high-fidelity car model, to populate the scene and match the target's visual complexity."
-          ]
-        }
-      }
-    },
-    "before": {
-      "boulevard_day": {
-        "target": "docs/screens/concepts/boulevard_skyline_day.png",
-        "metrics": {
-          "edge_density": 20.75,
-          "fine_detail": 8.2,
-          "contrast": 49.63,
-          "saturation_mean": 72.04,
-          "colour_spread": 55.45
-        },
-        "target_metrics": {
-          "edge_density": 20.74,
-          "fine_detail": 8.23,
-          "contrast": 54.85,
-          "saturation_mean": 73.09,
-          "colour_spread": 58.16
-        },
-        "metric_gap": 0.036,
-        "judge": {
-          "scores": {
-            "overall": 1.0,
-            "backdrop": 1.0,
-            "lighting": 1.0,
-            "characters": 1.0,
-            "texture_detail": 1.0,
-            "materials": 1.0
-          },
-          "score_range": {
-            "overall": [
-              1.0,
-              1.0
-            ],
-            "backdrop": [
-              1.0,
-              1.0
-            ],
-            "lighting": [
-              1.0,
-              1.0
-            ],
-            "characters": [
-              1.0,
-              1.0
-            ],
-            "texture_detail": [
-              1.0,
-              1.0
-            ],
-            "materials": [
-              1.0,
-              1.0
-            ]
-          },
-          "runs": 3,
-          "fixes": [
-            "Implement a physically based rendering (PBR) material system for all assets to achieve realistic surface interactions with light.",
-            "Integrate a global illumination solution (e.g., ray tracing, baked lightmaps) to simulate realistic light bouncing and ambient occlusion.",
-            "Replace placeholder low-resolution textures with high-resolution, detailed textures, including normal maps and roughness maps for all surfaces.",
-            "Develop a realistic skybox and distant cityscape with atmospheric scattering and haze effects to match the target's backdrop.",
-            "Redesign character models with realistic proportions, detailed clothing, and proper skin shaders, along with animation systems for natural movement."
-          ]
-        }
-      },
-      "boulevard_night": {
-        "target": "docs/screens/concepts/hollywood_entrance_rain_night.png",
-        "metrics": {
-          "edge_density": 21.77,
-          "fine_detail": 8.45,
-          "contrast": 50.38,
-          "saturation_mean": 95.12,
-          "colour_spread": 55.61
-        },
-        "target_metrics": {
-          "edge_density": 8.43,
-          "fine_detail": 3.51,
-          "contrast": 27.34,
-          "saturation_mean": 159.44,
-          "colour_spread": 26.61
-        },
-        "metric_gap": 1.231,
-        "judge": {
-          "scores": {
-            "overall": 1.0,
-            "backdrop": 1.0,
-            "lighting": 1.0,
-            "characters": 1.0,
-            "texture_detail": 1.0,
-            "materials": 1.0
-          },
-          "score_range": {
-            "overall": [
-              1.0,
-              1.0
-            ],
-            "backdrop": [
-              1.0,
-              1.0
-            ],
-            "lighting": [
-              1.0,
-              1.0
-            ],
-            "characters": [
-              1.0,
-              1.0
-            ],
-            "texture_detail": [
-              1.0,
-              1.0
-            ],
-            "materials": [
-              1.0,
-              1.0
-            ]
-          },
-          "runs": 3,
-          "fixes": [
-            "Implement a physically based rendering (PBR) material pipeline for all assets to achieve realistic surface responses to light.",
-            "Overhaul the lighting system to include global illumination, volumetric effects (fog/haze), and realistic light sources with proper falloff and color temperature.",
-            "Redesign character models with higher polygon counts, detailed textures (albedo, normal, roughness, metallic maps), and realistic rigging/animation.",
-            "Replace placeholder textures with high-resolution, detailed textures that include normal maps for surface imperfections and depth.",
-            "Develop a more complex backdrop with detailed buildings, atmospheric perspective (distance haze), and a dynamic sky system that reflects time of day and weather."
-          ]
-        }
-      },
-      "entrance_day": {
-        "target": "docs/screens/concepts/hollywood_entrance_morning.png",
-        "metrics": {
-          "edge_density": 26.19,
-          "fine_detail": 9.27,
-          "contrast": 56.39,
-          "saturation_mean": 65.24,
-          "colour_spread": 59.96
-        },
-        "target_metrics": {
-          "edge_density": 16.87,
-          "fine_detail": 6.92,
-          "contrast": 70.27,
-          "saturation_mean": 121.02,
-          "colour_spread": 69.83
-        },
-        "metric_gap": 0.308,
-        "judge": {
-          "scores": {
-            "overall": 1.0,
-            "backdrop": 0.0,
-            "lighting": 1.0,
-            "characters": 0.0,
-            "texture_detail": 1.0,
-            "materials": 1.0
-          },
-          "score_range": {
-            "overall": [
-              1.0,
-              1.0
-            ],
-            "backdrop": [
-              0.0,
-              0.0
-            ],
-            "lighting": [
-              1.0,
-              1.0
-            ],
-            "characters": [
-              0.0,
-              0.0
-            ],
-            "texture_detail": [
-              1.0,
-              1.0
-            ],
-            "materials": [
-              1.0,
-              1.0
-            ]
-          },
-          "runs": 3,
-          "fixes": [
-            "Implement a physically based rendering (PBR) material pipeline for all assets to achieve realistic surface interactions with light.",
-            "Overhaul the lighting system to include global illumination, realistic skyboxes with atmospheric scattering, and dynamic shadows to match the soft, warm lighting of the target.",
-            "Replace placeholder textures with high-resolution, detailed textures that include normal maps, roughness maps, and metallic maps to add surface complexity and realism.",
-            "Develop a detailed backdrop with distant buildings, realistic palm trees, and atmospheric haze to create depth and a sense of place.",
-            "Redesign all environmental props (trees, trash cans, bollards) with realistic models and textures, moving away from the current stylized, low-poly aesthetic."
-          ]
-        }
-      },
-      "street_day": {
-        "target": "docs/screens/concepts/boulevard_skyline_day.png",
-        "metrics": {
-          "edge_density": 12.44,
-          "fine_detail": 5.32,
-          "contrast": 41.37,
-          "saturation_mean": 77.84,
-          "colour_spread": 44.96
-        },
-        "target_metrics": {
-          "edge_density": 20.74,
-          "fine_detail": 8.23,
-          "contrast": 54.85,
-          "saturation_mean": 73.09,
-          "colour_spread": 58.16
-        },
-        "metric_gap": 0.307,
-        "judge": {
-          "scores": {
-            "overall": 0.0,
-            "backdrop": 0.0,
-            "lighting": 0.0,
-            "characters": 0.0,
-            "texture_detail": 0.0,
-            "materials": 0.0
-          },
-          "score_range": {
-            "overall": [
-              0.0,
-              0.0
-            ],
-            "backdrop": [
-              0.0,
-              0.0
-            ],
-            "lighting": [
-              0.0,
-              0.0
-            ],
-            "characters": [
-              0.0,
-              0.0
-            ],
-            "texture_detail": [
-              0.0,
-              0.0
-            ],
-            "materials": [
-              0.0,
-              0.0
-            ]
-          },
-          "runs": 3,
-          "fixes": [
-            "Implement a physically based rendering (PBR) material system for all assets to achieve realistic surface interactions with light.",
-            "Develop a dynamic sky and atmospheric scattering system to accurately simulate sky color, haze, and sun position based on time of day.",
-            "Replace placeholder block models with detailed 3D models for buildings, vehicles, and environmental props, including proper UV mapping and high-resolution textures.",
-            "Integrate a global illumination solution (e.g., ray tracing or baked lightmaps) to simulate realistic indirect lighting and soft shadows.",
-            "Create realistic character models with detailed textures, proper rigging, and animations, ensuring they blend seamlessly with the environment."
-          ]
-        }
-      },
-      "street_night": {
-        "target": "docs/screens/concepts/boulevard_skyline_dusk.png",
-        "metrics": {
-          "edge_density": 11.94,
-          "fine_detail": 5.35,
-          "contrast": 48.34,
-          "saturation_mean": 98.21,
-          "colour_spread": 48.85
-        },
-        "target_metrics": {
-          "edge_density": 8.83,
-          "fine_detail": 4.61,
-          "contrast": 33.26,
-          "saturation_mean": 188.16,
-          "colour_spread": 35.38
-        },
-        "metric_gap": 0.337,
-        "judge": {
-          "scores": {
-            "overall": 1.0,
-            "backdrop": 1.0,
-            "lighting": 1.0,
-            "characters": 1.0,
-            "texture_detail": 1.0,
-            "materials": 1.0
-          },
-          "score_range": {
-            "overall": [
-              1.0,
-              1.0
-            ],
-            "backdrop": [
-              1.0,
-              1.0
-            ],
-            "lighting": [
-              1.0,
-              1.0
-            ],
-            "characters": [
-              1.0,
-              1.0
-            ],
-            "texture_detail": [
-              1.0,
-              1.0
-            ],
-            "materials": [
-              1.0,
-              1.0
-            ]
-          },
-          "runs": 3,
-          "fixes": [
-            "Implement a physically based lighting model with global illumination to accurately simulate light bounces and color bleeding, especially for the sunset and artificial lights.",
-            "Replace placeholder geometry with detailed 3D models for buildings, vehicles, and environmental props, ensuring proper UV mapping and high-resolution textures.",
-            "Develop a comprehensive material library with realistic PBR (Physically Based Rendering) materials for various surfaces (e.g., wet asphalt, neon signs, building facades, car paint) including roughness, metallic, and normal maps.",
-            "Create a dynamic skybox system that accurately represents a sunset with atmospheric scattering, volumetric clouds, and distance haze, matching the vibrant purple and orange hues of the target.",
-            "Design and integrate realistic character models with detailed clothing, hair, and skin textures, and implement a robust animation system for natural movement."
-          ]
-        }
-      }
-    }
-  }
-}

docs/screens/realism/2026-11-01-adopt/report.md

@@ -1,131 +0,0 @@
-# Realism report: `docs/screens/realism/2026-11-01-adopt`
-
-Vision judge: `google/gemini-2.5-flash` (scores 0-10, higher is more realistic compared with the concept target).
-
-| set | shot | target | gap ↓ | edges | detail | contrast | overall | lighting | materials | texture | backdrop |
-| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
-| after | boulevard_day | boulevard_skyline_day | 0.172 | 23.21 | 8.88 | 38.78 | 1.0 | 1.0 | 1.0 | 1.0 | 3.0 |
-| after | boulevard_night | hollywood_entrance_rain_night | 0.723 | 16.02 | 7.13 | 39.4 | 1.0 | 1.0 | 1.0 | 1.0 | 2.0 |
-| after | entrance_day | hollywood_entrance_morning | 0.442 | 25.88 | 9.86 | 40.18 | 1.0 | 1.0 | 1.0 | 1.0 | 0.0 |
-| after | entrance_late | hollywood_entrance_rain_night | 1.105 | 18.4 | 8.41 | 51.61 | 1.0 | 1.0 | 1.33 | 1.33 | 0.0 |
-| after | joke_shop_door | joke_shop_door_closeup | 0.818 | 14.84 | 7.04 | 47.63 | 2.0 | 2.0 | 3.0 | 3.0 | 4.0 |
-| after | street_day | boulevard_skyline_day | 0.148 | 18.69 | 7.42 | 42.69 | 1.0 | 1.0 | 1.0 | 1.0 | 2.0 |
-| after | street_late | boulevard_skyline_dusk | 0.224 | 12.95 | 6.27 | 31.94 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 |
-| after | street_night | boulevard_skyline_dusk | 0.253 | 10.97 | 5.57 | 24.27 | 1.0 | 1.0 | 1.0 | 1.0 | 1.0 |
-| after | studio_door | studio_stage_door_night | 0.395 | 16.62 | 7.65 | 48.52 | 1.0 | 1.0 | 1.0 | 1.0 | 0.0 |
-| before | boulevard_day | boulevard_skyline_day | 0.036 | 20.75 | 8.2 | 49.63 | 1.0 | 1.0 | 1.0 | 1.0 | 1.0 |
-| before | boulevard_night | hollywood_entrance_rain_night | 1.231 | 21.77 | 8.45 | 50.38 | 1.0 | 1.0 | 1.0 | 1.0 | 1.0 |
-| before | entrance_day | hollywood_entrance_morning | 0.308 | 26.19 | 9.27 | 56.39 | 1.0 | 1.0 | 1.0 | 1.0 | 0.0 |
-| before | street_day | boulevard_skyline_day | 0.307 | 12.44 | 5.32 | 41.37 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 |
-| before | street_night | boulevard_skyline_dusk | 0.337 | 11.94 | 5.35 | 48.34 | 1.0 | 1.0 | 1.0 | 1.0 | 1.0 |
-
-Mean scores per set (all captured shots):
-
-| set | shots | gap ↓ | overall | lighting | materials | texture_detail | backdrop | characters |
-| --- | --- | --- | --- | --- | --- | --- | --- | --- |
-| after | 9 | 0.476 | 1.0 | 1.0 | 1.15 | 1.15 | 1.33 | 0.11 |
-| before | 5 | 0.444 | 0.8 | 0.8 | 0.8 | 0.8 | 0.6 | 0.6 |
-
-Mean over the shots every set captured (like for like):
-
-| set | shots | gap ↓ | overall | lighting | materials | texture_detail | backdrop | characters |
-| --- | --- | --- | --- | --- | --- | --- | --- | --- |
-| after | 5 | 0.348 | 1.0 | 1.0 | 1.0 | 1.0 | 1.6 | 0.2 |
-
-**after / boulevard_day** fixes:
-- Implement physically based rendering (PBR) materials for all assets, focusing on realistic albedo, roughness, and metallic maps to achieve accurate surface responses to light.
-- Overhaul lighting system to include global illumination, realistic skybox/HDRI for ambient light, and accurate sun/directional light with proper shadows and atmospheric scattering (haze/fog).
-- Replace placeholder low-polygon models with high-detail 3D assets for trees, street furniture, and buildings, ensuring proper UV mapping and texture application.
-- Improve texture resolution and detail across all surfaces, adding normal maps for surface imperfections and detail, and ensuring textures are seamlessly tiled or uniquely mapped where appropriate.
-- Develop a realistic character pipeline, including high-fidelity models, animations, and PBR materials for skin, clothing, and hair, to populate the scene.
-
-**after / boulevard_night** fixes:
-- Implement a physically based rendering (PBR) material pipeline for all assets to achieve realistic surface responses to light, especially for wet surfaces and brick.
-- Overhaul the lighting system to include global illumination, volumetric fog/rain, and realistic light sources with proper falloff and color temperature, focusing on dramatic contrast and mood.
-- Replace low-polygon models with high-detail meshes and high-resolution textures, including normal and roughness maps, for all environmental elements (buildings, street, props, characters).
-- Redesign the backdrop with a more detailed and atmospheric skyline, incorporating distance haze, subtle cloud formations, and appropriate night sky colors to match the target's mood.
-- Update character models to be realistic, with detailed clothing, skin, and hair textures, and implement realistic animation and shading.
-
-**after / entrance_day** fixes:
-- Implement a physically based rendering (PBR) material pipeline for all assets to achieve realistic surface responses to light.
-- Overhaul the lighting system to include global illumination, realistic skyboxes with atmospheric scattering, and dynamic shadows.
-- Replace placeholder low-polygon models with high-fidelity assets that include detailed normal maps and displacement maps for architectural elements, foliage, and street furniture.
-- Develop a detailed backdrop with distant buildings, varied skyline, and atmospheric haze to create depth and realism.
-- Add realistic foliage models with proper leaf textures, branch structures, and varied forms instead of simple geometric shapes.
-
-**after / entrance_late** fixes:
-- Implement volumetric fog and rain effects to create atmospheric depth and mood, especially around light sources.
-- Overhaul lighting system to include realistic light falloff, bounce light, and wet surface reflections, focusing on the marquee and streetlights.
-- Redesign all materials with PBR workflows, ensuring accurate roughness, metallic, and normal maps for brick, concrete, metal, and wet surfaces.
-- Add high-resolution, detailed textures for all surfaces, particularly the brickwork, sidewalk, and marquee, to capture fine imperfections and wear.
-- Develop a detailed backdrop with distant buildings, subtle city lights, and atmospheric haze to replace the current flat sky.
-
-**after / joke_shop_door** fixes:
-- Implement physically based rendering (PBR) materials for all surfaces, especially brick, wood, and metal, to achieve realistic light interaction and surface properties.
-- Overhaul the lighting system to include more nuanced light sources, volumetric effects, and global illumination. Focus on creating warm, inviting pools of light around entrances and signs, with realistic falloff and shadows.
-- Improve texture resolution and detail for all assets, particularly the brickwork, ground, and signage. Add normal maps and displacement maps to give surfaces depth and tactile quality.
-- Redesign the 'Comedy Club' sign to be a prominent, well-lit feature with appropriate emissive materials and a more stylized font, similar to the target image's 'COMEDY CLUB' sign.
-- Enhance the backdrop with more detailed city lights, atmospheric haze, and a more realistic skybox to create a sense of depth and a believable urban environment.
-
-**after / street_day** fixes:
-- Implement physically based rendering (PBR) materials for all assets, focusing on realistic albedo, roughness, and metallic values to achieve accurate light interaction.
-- Overhaul the lighting system to include a directional light representing the sun, a skybox/HDRI for ambient light, and global illumination to simulate bounced light, matching the target's clear, bright, and slightly warm daylight.
-- Replace placeholder geometry with high-fidelity 3D models for cars, buildings, and environmental elements (e.g., palm trees, streetlights, sidewalks) that match the realistic proportions and details of the target image.
-- Develop detailed textures for all surfaces, including road asphalt, concrete sidewalks, building facades, and foliage, ensuring appropriate resolution and variety to avoid tiling artifacts and enhance realism.
-- Create a realistic backdrop with a detailed skyline, atmospheric perspective (distance haze), and a clear blue sky that accurately reflects the target's Los Angeles aesthetic, integrating it seamlessly with the foreground.
-
-**after / street_late** fixes:
-- Implement a full physically-based lighting model with global illumination, volumetric fog, and atmospheric scattering to achieve realistic sunset colors and light interaction.
-- Replace placeholder geometry with detailed 3D models for buildings, palm trees, and vehicles, ensuring proper scale and architectural variety.
-- Develop high-resolution PBR (Physically Based Rendering) materials for all surfaces, including reflective wet asphalt, glowing neon signs, and varied building facades, with appropriate roughness, metallic, and normal maps.
-- Create a dynamic skybox system that accurately renders sunset gradients, distant city skylines with emissive windows, and atmospheric haze, replacing the current flat backdrop.
-- Add realistic character models with appropriate clothing and animations to populate the scene, contributing to the overall realism and sense of a living city.
-
-**after / street_night** fixes:
-- Implement a full physically-based lighting model with global illumination, volumetric fog, and proper emissive materials for signs and car lights to capture the sunset glow and light trails.
-- Replace placeholder geometry with detailed 3D models for buildings, palm trees, and vehicles, ensuring accurate proportions and architectural details.
-- Develop high-resolution PBR textures for all surfaces (roads, buildings, signs, vehicles) with appropriate albedo, roughness, metallic, and normal maps to add realism and detail.
-- Create a dynamic skybox with a realistic sunset gradient, distant city skyline with illuminated windows, and atmospheric haze to match the target's depth and mood.
-- Add realistic character models with appropriate clothing and animations to populate the scene and enhance the sense of a living city.
-
-**after / studio_door** fixes:
-- Implement physically based rendering (PBR) materials for all surfaces, focusing on realistic albedo, roughness, and metallic values to achieve accurate light interaction.
-- Overhaul the lighting system to include global illumination, volumetric fog, and realistic light sources with proper falloff and color temperature, especially for the marquee and wall sconces.
-- Add high-resolution, detailed textures with normal and displacement maps for brickwork, concrete, and metallic elements to introduce surface imperfections and depth.
-- Develop a realistic backdrop with a distant city skyline, atmospheric haze, and a dark, moody sky to establish a sense of depth and environment.
-- Introduce realistic 3D character models with proper clothing, hair, and skin shaders, along with a high-fidelity car model, to populate the scene and match the target's visual complexity.
-
-**before / boulevard_day** fixes:
-- Implement a physically based rendering (PBR) material system for all assets to achieve realistic surface interactions with light.
-- Integrate a global illumination solution (e.g., ray tracing, baked lightmaps) to simulate realistic light bouncing and ambient occlusion.
-- Replace placeholder low-resolution textures with high-resolution, detailed textures, including normal maps and roughness maps for all surfaces.
-- Develop a realistic skybox and distant cityscape with atmospheric scattering and haze effects to match the target's backdrop.
-- Redesign character models with realistic proportions, detailed clothing, and proper skin shaders, along with animation systems for natural movement.
-
-**before / boulevard_night** fixes:
-- Implement a physically based rendering (PBR) material pipeline for all assets to achieve realistic surface responses to light.
-- Overhaul the lighting system to include global illumination, volumetric effects (fog/haze), and realistic light sources with proper falloff and color temperature.
-- Redesign character models with higher polygon counts, detailed textures (albedo, normal, roughness, metallic maps), and realistic rigging/animation.
-- Replace placeholder textures with high-resolution, detailed textures that include normal maps for surface imperfections and depth.
-- Develop a more complex backdrop with detailed buildings, atmospheric perspective (distance haze), and a dynamic sky system that reflects time of day and weather.
-
-**before / entrance_day** fixes:
-- Implement a physically based rendering (PBR) material pipeline for all assets to achieve realistic surface interactions with light.
-- Overhaul the lighting system to include global illumination, realistic skyboxes with atmospheric scattering, and dynamic shadows to match the soft, warm lighting of the target.
-- Replace placeholder textures with high-resolution, detailed textures that include normal maps, roughness maps, and metallic maps to add surface complexity and realism.
-- Develop a detailed backdrop with distant buildings, realistic palm trees, and atmospheric haze to create depth and a sense of place.
-- Redesign all environmental props (trees, trash cans, bollards) with realistic models and textures, moving away from the current stylized, low-poly aesthetic.
-
-**before / street_day** fixes:
-- Implement a physically based rendering (PBR) material system for all assets to achieve realistic surface interactions with light.
-- Develop a dynamic sky and atmospheric scattering system to accurately simulate sky color, haze, and sun position based on time of day.
-- Replace placeholder block models with detailed 3D models for buildings, vehicles, and environmental props, including proper UV mapping and high-resolution textures.
-- Integrate a global illumination solution (e.g., ray tracing or baked lightmaps) to simulate realistic indirect lighting and soft shadows.
-- Create realistic character models with detailed textures, proper rigging, and animations, ensuring they blend seamlessly with the environment.
-
-**before / street_night** fixes:
-- Implement a physically based lighting model with global illumination to accurately simulate light bounces and color bleeding, especially for the sunset and artificial lights.
-- Replace placeholder geometry with detailed 3D models for buildings, vehicles, and environmental props, ensuring proper UV mapping and high-resolution textures.
-- Develop a comprehensive material library with realistic PBR (Physically Based Rendering) materials for various surfaces (e.g., wet asphalt, neon signs, building facades, car paint) including roughness, metallic, and normal maps.
-- Create a dynamic skybox system that accurately represents a sunset with atmospheric scattering, volumetric clouds, and distance haze, matching the vibrant purple and orange hues of the target.
-- Design and integrate realistic character models with detailed clothing, hair, and skin textures, and implement a robust animation system for natural movement.

docs/screens/realism/2026-11-01-v2/report-v2.json

@@ -1,526 +0,0 @@
-{
-  "run": "docs/screens/realism/2026-11-01-v2",
-  "judge_model": "google/gemini-2.5-flash-lite",
-  "sets": {
-    "baseline": {
-      "boulevard_day": {
-        "target": "docs/screens/concepts/boulevard_skyline_day.png",
-        "metrics": {
-          "edge_density": 20.75,
-          "fine_detail": 8.2,
-          "contrast": 49.63,
-          "saturation_mean": 72.04,
-          "colour_spread": 55.45
-        },
-        "target_metrics": {
-          "edge_density": 20.74,
-          "fine_detail": 8.23,
-          "contrast": 54.85,
-          "saturation_mean": 73.09,
-          "colour_spread": 58.16
-        },
-        "metric_gap": 0.036,
-        "judge": {
-          "scores": {
-            "lighting": 3.0,
-            "materials": 2.0,
-            "texture_detail": 1.0,
-            "backdrop": 4.0,
-            "characters": 1.0,
-            "overall": 2.0
-          },
-          "fixes": [
-            "Improve the lighting model to include more realistic global illumination and soft shadows. The current lighting is too flat and harsh.",
-            "Replace the current low-polygon character models with more detailed and anatomically correct models. Add variations in clothing and appearance.",
-            "Increase the texture resolution and detail on all surfaces, especially buildings, roads, and foliage. Implement normal maps and specular maps for greater realism.",
-            "Enhance the backdrop by adding more detailed building models in the distance, atmospheric perspective (haze), and a more nuanced skybox.",
-            "Refine the material properties of all objects to better simulate real-world materials. This includes adjusting reflectivity, roughness, and subsurface scattering where appropriate."
-          ]
-        }
-      },
-      "boulevard_night": {
-        "target": "docs/screens/concepts/hollywood_entrance_rain_night.png",
-        "metrics": {
-          "edge_density": 21.77,
-          "fine_detail": 8.45,
-          "contrast": 50.38,
-          "saturation_mean": 95.12,
-          "colour_spread": 55.61
-        },
-        "target_metrics": {
-          "edge_density": 8.43,
-          "fine_detail": 3.51,
-          "contrast": 27.34,
-          "saturation_mean": 159.44,
-          "colour_spread": 26.61
-        },
-        "metric_gap": 1.231,
-        "judge": {
-          "scores": {
-            "lighting": 2.0,
-            "materials": 1.0,
-            "texture_detail": 1.0,
-            "backdrop": 2.0,
-            "characters": 1.0,
-            "overall": 1.0
-          },
-          "fixes": [
-            "Improve lighting to match the dramatic, atmospheric, and volumetric lighting of the target image, focusing on warm, directional light from the marquee and streetlamp, and realistic reflections on wet surfaces.",
-            "Significantly upgrade material shaders to achieve realistic PBR (Physically Based Rendering) properties, especially for brick, asphalt, glass, and metal, to mimic the specular highlights, subsurface scattering, and roughness of the target.",
-            "Increase texture resolution and detail for all surfaces, particularly the brickwork, sidewalk, and building facades, to match the fine-grained realism of the target.",
-            "Redesign character models with higher polygon counts, more detailed textures, and realistic clothing and facial features to match the stylized but grounded look of the target's lone figure.",
-            "Enhance the backdrop by adding atmospheric effects like fog, rain, and distant city lights, and refine the building models to have more architectural detail and variation, similar to the target's moody urban environment."
-          ]
-        }
-      },
-      "entrance_day": {
-        "target": "docs/screens/concepts/hollywood_entrance_morning.png",
-        "metrics": {
-          "edge_density": 26.19,
-          "fine_detail": 9.27,
-          "contrast": 56.39,
-          "saturation_mean": 65.24,
-          "colour_spread": 59.96
-        },
-        "target_metrics": {
-          "edge_density": 16.87,
-          "fine_detail": 6.92,
-          "contrast": 70.27,
-          "saturation_mean": 121.02,
-          "colour_spread": 69.83
-        },
-        "metric_gap": 0.308,
-        "judge": {
-          "scores": {
-            "lighting": 3.0,
-            "materials": 2.0,
-            "texture_detail": 2.0,
-            "backdrop": 3.0,
-            "characters": 10.0,
-            "overall": 2.0
-          },
-          "fixes": [
-            "Improve brick texture and material to match the target's depth and variation.",
-            "Add more detailed and varied foliage, especially for the trees and bushes, to match the target's organic look.",
-            "Enhance lighting to create softer shadows, more atmospheric haze, and warmer tones, particularly around the building entrance and street.",
-            "Refine building details, such as window frames, signage, and architectural elements, to increase realism.",
-            "Introduce subtle imperfections and wear on surfaces like the sidewalk and building facade to mimic real-world aging."
-          ]
-        }
-      },
-      "street_day": {
-        "target": "docs/screens/concepts/boulevard_skyline_day.png",
-        "metrics": {
-          "edge_density": 12.44,
-          "fine_detail": 5.32,
-          "contrast": 41.37,
-          "saturation_mean": 77.84,
-          "colour_spread": 44.96
-        },
-        "target_metrics": {
-          "edge_density": 20.74,
-          "fine_detail": 8.23,
-          "contrast": 54.85,
-          "saturation_mean": 73.09,
-          "colour_spread": 58.16
-        },
-        "metric_gap": 0.307,
-        "judge": {
-          "scores": {
-            "lighting": 2.0,
-            "materials": 1.0,
-            "texture_detail": 1.0,
-            "backdrop": 2.0,
-            "characters": 2.0,
-            "overall": 1.0
-          },
-          "fixes": [
-            "Improve lighting to match the warm, directional sunlight and soft shadows of the target. Add volumetric fog for atmospheric perspective.",
-            "Replace flat, untextured building models with detailed geometry and realistic materials (concrete, glass, metal).",
-            "Add high-resolution textures to all surfaces, especially the road, sidewalk, and buildings, to mimic the detail in the target.",
-            "Model a more detailed and varied cityscape for the backdrop, including buildings with distinct architectural styles and realistic lighting.",
-            "Redesign character models to be more anatomically correct and have realistic clothing textures and animations."
-          ]
-        }
-      },
-      "street_night": {
-        "target": "docs/screens/concepts/boulevard_skyline_dusk.png",
-        "metrics": {
-          "edge_density": 11.94,
-          "fine_detail": 5.35,
-          "contrast": 48.34,
-          "saturation_mean": 98.21,
-          "colour_spread": 48.85
-        },
-        "target_metrics": {
-          "edge_density": 8.83,
-          "fine_detail": 4.61,
-          "contrast": 33.26,
-          "saturation_mean": 188.16,
-          "colour_spread": 35.38
-        },
-        "metric_gap": 0.337,
-        "judge": {
-          "scores": {
-            "lighting": 3.0,
-            "materials": 2.0,
-            "texture_detail": 1.0,
-            "backdrop": 2.0,
-            "characters": 1.0,
-            "overall": 2.0
-          },
-          "fixes": [
-            "Improve lighting to match the dramatic sunset and neon glow of the target image, focusing on volumetric lighting and bloom effects.",
-            "Enhance material properties for buildings, road, and car to achieve a more realistic PBR (Physically Based Rendering) look, with appropriate reflections and specularity.",
-            "Increase texture resolution and detail on all surfaces, especially the road and building facades, to mimic the fine grain and imperfections seen in the target.",
-            "Redesign the backdrop to include a more detailed and atmospheric skyline with realistic haze and a richer sunset color gradient.",
-            "Replace the current character models with more detailed and realistically proportioned characters that fit the urban environment."
-          ]
-        }
-      }
-    },
-    "candidate": {
-      "boulevard_day": {
-        "target": "docs/screens/concepts/boulevard_skyline_day.png",
-        "metrics": {
-          "edge_density": 20.67,
-          "fine_detail": 7.8,
-          "contrast": 42.49,
-          "saturation_mean": 67.55,
-          "colour_spread": 48.32
-        },
-        "target_metrics": {
-          "edge_density": 20.74,
-          "fine_detail": 8.23,
-          "contrast": 54.85,
-          "saturation_mean": 73.09,
-          "colour_spread": 58.16
-        },
-        "metric_gap": 0.113,
-        "judge": {
-          "scores": {
-            "lighting": 3.0,
-            "materials": 2.0,
-            "texture_detail": 2.0,
-            "backdrop": 5.0,
-            "characters": 1.0,
-            "overall": 2.0
-          },
-          "fixes": [
-            "Improve road and sidewalk materials to have more realistic specular highlights and surface imperfections.",
-            "Increase texture resolution and detail on buildings, especially the brickwork, to match the target's fidelity.",
-            "Replace stylized character models with realistic human models that have appropriate proportions and clothing.",
-            "Enhance lighting to create softer shadows, more realistic ambient occlusion, and better global illumination, especially around the streetlights and building facades.",
-            "Add atmospheric perspective and volumetric fog to the distant cityscape to create a more convincing sense of depth and distance haze."
-          ]
-        }
-      },
-      "boulevard_night": {
-        "target": "docs/screens/concepts/hollywood_entrance_rain_night.png",
-        "metrics": {
-          "edge_density": 20.67,
-          "fine_detail": 7.86,
-          "contrast": 46.43,
-          "saturation_mean": 98.69,
-          "colour_spread": 50.59
-        },
-        "target_metrics": {
-          "edge_density": 8.43,
-          "fine_detail": 3.51,
-          "contrast": 27.34,
-          "saturation_mean": 159.44,
-          "colour_spread": 26.61
-        },
-        "metric_gap": 1.073,
-        "judge": {
-          "scores": {
-            "lighting": 2.0,
-            "materials": 1.0,
-            "texture_detail": 1.0,
-            "backdrop": 3.0,
-            "characters": 2.0,
-            "overall": 1.0
-          },
-          "fixes": [
-            "Improve lighting to create atmospheric mood, with strong contrast and volumetric effects like fog/rain.",
-            "Enhance material properties for realism: add specular highlights, subsurface scattering for skin, and more detailed surface imperfections.",
-            "Increase texture resolution and detail, especially on buildings, pavement, and clothing, to match the target's gritty realism.",
-            "Redesign characters to have more realistic proportions, clothing, and facial features, and animate them with more natural movement.",
-            "Develop a more detailed and atmospheric backdrop, including realistic city buildings, distant haze, and appropriate weather effects."
-          ]
-        }
-      },
-      "entrance_day": {
-        "target": "docs/screens/concepts/hollywood_entrance_morning.png",
-        "metrics": {
-          "edge_density": 24.54,
-          "fine_detail": 8.92,
-          "contrast": 52.41,
-          "saturation_mean": 61.63,
-          "colour_spread": 54.98
-        },
-        "target_metrics": {
-          "edge_density": 16.87,
-          "fine_detail": 6.92,
-          "contrast": 70.27,
-          "saturation_mean": 121.02,
-          "colour_spread": 69.83
-        },
-        "metric_gap": 0.303,
-        "judge": {
-          "scores": {
-            "lighting": 3.0,
-            "materials": 2.0,
-            "texture_detail": 2.0,
-            "backdrop": 3.0,
-            "characters": 1.0,
-            "overall": 2.0
-          },
-          "fixes": [
-            "Improve brick texture and material to add more variation, grime, and imperfections.",
-            "Enhance lighting to create softer shadows, more atmospheric haze, and realistic light falloff.",
-            "Add more detail and variation to the building facade, including window frames, signage, and architectural elements.",
-            "Replace low-poly trees and bushes with more detailed and realistic foliage models.",
-            "Refine character models to match the realistic style of the target image, focusing on proportions, clothing, and facial features."
-          ]
-        }
-      },
-      "street_day": {
-        "target": "docs/screens/concepts/boulevard_skyline_day.png",
-        "metrics": {
-          "edge_density": 14.54,
-          "fine_detail": 5.32,
-          "contrast": 36.3,
-          "saturation_mean": 74.49,
-          "colour_spread": 39.9
-        },
-        "target_metrics": {
-          "edge_density": 20.74,
-          "fine_detail": 8.23,
-          "contrast": 54.85,
-          "saturation_mean": 73.09,
-          "colour_spread": 58.16
-        },
-        "metric_gap": 0.326,
-        "judge": {
-          "scores": {
-            "lighting": 2.0,
-            "materials": 1.0,
-            "texture_detail": 1.0,
-            "backdrop": 3.0,
-            "characters": 1.0,
-            "overall": 1.0
-          },
-          "fixes": [
-            "Improve road and sidewalk materials to have more realistic specular highlights and surface imperfections.",
-            "Add significant detail to the car models, including realistic reflections, panel gaps, and tire textures.",
-            "Implement volumetric fog and atmospheric scattering to create a more convincing sense of depth and haze in the backdrop.",
-            "Replace the placeholder character with a detailed, realistically lit 3D model that matches the environment's style.",
-            "Enhance the lighting model to include softer shadows, more accurate ambient occlusion, and realistic light bounce."
-          ]
-        }
-      },
-      "street_night": {
-        "target": "docs/screens/concepts/boulevard_skyline_dusk.png",
-        "metrics": {
-          "edge_density": 16.12,
-          "fine_detail": 6.06,
-          "contrast": 48.36,
-          "saturation_mean": 103.44,
-          "colour_spread": 49.1
-        },
-        "target_metrics": {
-          "edge_density": 8.83,
-          "fine_detail": 4.61,
-          "contrast": 33.26,
-          "saturation_mean": 188.16,
-          "colour_spread": 35.38
-        },
-        "metric_gap": 0.495,
-        "judge": {
-          "scores": {
-            "lighting": 3.0,
-            "materials": 2.0,
-            "texture_detail": 2.0,
-            "backdrop": 4.0,
-            "characters": 1.0,
-            "overall": 2.0
-          },
-          "fixes": [
-            "Improve lighting to match the dramatic, atmospheric sunset and neon glow of the target image. Add volumetric fog and bloom effects.",
-            "Significantly enhance material properties for buildings, road, and vehicles to achieve a more realistic PBR (Physically Based Rendering) look, with appropriate reflections and surface imperfections.",
-            "Increase texture resolution and detail on all surfaces, especially buildings and the road, to match the crispness and complexity of the target.",
-            "Redesign the backdrop to include a more detailed and atmospheric city skyline with appropriate haze and color grading to match the sunset.",
-            "Completely overhaul character models to be significantly more detailed, with realistic proportions, clothing, and animation, to match the quality of the target scene."
-          ]
-        }
-      }
-    },
-    "candidate_dusk": {
-      "boulevard_day": {
-        "target": "docs/screens/concepts/boulevard_skyline_day.png",
-        "metrics": {
-          "edge_density": 20.64,
-          "fine_detail": 7.79,
-          "contrast": 42.52,
-          "saturation_mean": 67.55,
-          "colour_spread": 48.35
-        },
-        "target_metrics": {
-          "edge_density": 20.74,
-          "fine_detail": 8.23,
-          "contrast": 54.85,
-          "saturation_mean": 73.09,
-          "colour_spread": 58.16
-        },
-        "metric_gap": 0.113,
-        "judge": {
-          "scores": {
-            "lighting": 3.0,
-            "materials": 2.0,
-            "texture_detail": 2.0,
-            "backdrop": 5.0,
-            "characters": 1.0,
-            "overall": 2.0
-          },
-          "fixes": [
-            "Improve lighting to match the warm, directional sunlight and soft shadows of the target. Add volumetric fog or atmospheric perspective to the distant cityscape.",
-            "Replace low-poly, stylized assets (trees, characters, buildings) with high-fidelity models that have realistic proportions and details.",
-            "Apply PBR materials with appropriate roughness, metallic, and normal maps to all surfaces (road, sidewalk, buildings, foliage) to simulate real-world material properties.",
-            "Increase texture resolution and add surface imperfections (grime, wear, subtle variations) to the road, sidewalk, and building facades.",
-            "Refine character models to have realistic anatomy, clothing, and animation, and ensure they are properly lit and integrated into the scene."
-          ]
-        }
-      },
-      "boulevard_night": {
-        "target": "docs/screens/concepts/hollywood_entrance_rain_night.png",
-        "metrics": {
-          "edge_density": 21.29,
-          "fine_detail": 7.93,
-          "contrast": 43.3,
-          "saturation_mean": 97.44,
-          "colour_spread": 47.83
-        },
-        "target_metrics": {
-          "edge_density": 8.43,
-          "fine_detail": 3.51,
-          "contrast": 27.34,
-          "saturation_mean": 159.44,
-          "colour_spread": 26.61
-        },
-        "metric_gap": 1.041,
-        "judge": {
-          "scores": {
-            "lighting": 3.0,
-            "materials": 2.0,
-            "texture_detail": 2.0,
-            "backdrop": 4.0,
-            "characters": 1.0,
-            "overall": 2.0
-          },
-          "fixes": [
-            "Improve the lighting to match the dramatic, atmospheric, and volumetric lighting of the target image, focusing on warm, directional light from the marquee and streetlamp, and realistic reflections on wet surfaces.",
-            "Significantly upgrade the character models and animations to be more realistic, with detailed clothing, facial features, and natural posing, rather than the current low-poly, cartoonish style.",
-            "Enhance material properties and textures for all surfaces (brick, pavement, doors, clothing) to achieve a photorealistic look, with appropriate roughness, reflectivity, and detailed normal maps, especially for the wet environment.",
-            "Refine the backdrop elements, including the distant city skyline and atmospheric haze, to create a sense of depth and realism consistent with the target image's moody atmosphere.",
-            "Implement more realistic environmental effects, such as rain, puddles with accurate reflections, and subtle fog, to enhance the overall immersion and match the target's gritty, wet ambiance."
-          ]
-        }
-      },
-      "entrance_day": {
-        "target": "docs/screens/concepts/hollywood_entrance_morning.png",
-        "metrics": {
-          "edge_density": 24.44,
-          "fine_detail": 8.87,
-          "contrast": 52.25,
-          "saturation_mean": 61.51,
-          "colour_spread": 54.84
-        },
-        "target_metrics": {
-          "edge_density": 16.87,
-          "fine_detail": 6.92,
-          "contrast": 70.27,
-          "saturation_mean": 121.02,
-          "colour_spread": 69.83
-        },
-        "metric_gap": 0.3,
-        "judge": {
-          "scores": {},
-          "fixes": [
-            "judge failed: OpenRouter HTTP 400: {\"error\":{\"message\":\"Provider returned error\",\"code\":400,\"metadata\":{\"raw\":\"{\\n  \\\"error\\\": {\\n    \\\"code\\\": 400,\\n    \\\"message\\\": \\\"API key not valid. Please pass a valid API key.\\\",\\n    \\\"status\\\": \\\"INVALID_ARGUMENT\\\",\\n    \\\"details\\\": [\\n      {\\n        \\\"@type\\\": \\\"type.googleapis.com/googl"
-          ]
-        }
-      },
-      "street_day": {
-        "target": "docs/screens/concepts/boulevard_skyline_day.png",
-        "metrics": {
-          "edge_density": 14.55,
-          "fine_detail": 5.33,
-          "contrast": 36.3,
-          "saturation_mean": 74.49,
-          "colour_spread": 39.9
-        },
-        "target_metrics": {
-          "edge_density": 20.74,
-          "fine_detail": 8.23,
-          "contrast": 54.85,
-          "saturation_mean": 73.09,
-          "colour_spread": 58.16
-        },
-        "metric_gap": 0.326,
-        "judge": {
-          "scores": {
-            "lighting": 3.0,
-            "materials": 2.0,
-            "texture_detail": 1.0,
-            "backdrop": 4.0,
-            "characters": 1.0,
-            "overall": 2.0
-          },
-          "fixes": [
-            "Improve road and sidewalk material PBR values to match the target's roughness and reflectivity.",
-            "Increase the resolution and detail of building textures in the backdrop to reduce the blurry, low-poly appearance.",
-            "Add atmospheric perspective and volumetric fog to the distant cityscape to mimic the target's depth and haze.",
-            "Enhance car material properties, particularly reflections and specular highlights, to match the target's realism.",
-            "Redesign character models to have more detailed geometry, textures, and more natural proportions and posing."
-          ]
-        }
-      },
-      "street_night": {
-        "target": "docs/screens/concepts/boulevard_skyline_dusk.png",
-        "metrics": {
-          "edge_density": 17.04,
-          "fine_detail": 6.13,
-          "contrast": 43.69,
-          "saturation_mean": 96.82,
-          "colour_spread": 45.18
-        },
-        "target_metrics": {
-          "edge_density": 8.83,
-          "fine_detail": 4.61,
-          "contrast": 33.26,
-          "saturation_mean": 188.16,
-          "colour_spread": 35.38
-        },
-        "metric_gap": 0.463,
-        "judge": {
-          "scores": {
-            "lighting": 3.0,
-            "materials": 2.0,
-            "texture_detail": 2.0,
-            "backdrop": 3.0,
-            "characters": 1.0,
-            "overall": 2.0
-          },
-          "fixes": [
-            "Improve lighting to match the dramatic, atmospheric sunset and neon glow of the target image. Add volumetric fog and bloom effects.",
-            "Enhance material properties for buildings, road, and vehicles to achieve a more realistic PBR (Physically Based Rendering) look, with appropriate reflections and specularity.",
-            "Increase texture resolution and detail on all surfaces, especially buildings and the road, to match the fine details seen in the target.",
-            "Redesign the backdrop to include a more detailed and atmospheric city skyline with appropriate haze and color grading to mimic the target's sunset.",
-            "Significantly rework character models to be more realistic in terms of proportions, texturing, and animation, as the current models are very stylized and cartoony."
-          ]
-        }
-      }
-    }
-  }
-}

docs/screens/realism/2026-11-01-v2/report-v2.md

@@ -1,130 +0,0 @@
-# Realism report: `docs/screens/realism/2026-11-01-v2`
-
-Vision judge: `google/gemini-2.5-flash-lite` (scores 0-10, higher is more realistic compared with the concept target).
-
-| set | shot | target | gap ↓ | edges | detail | contrast | overall | lighting | materials | texture | backdrop |
-| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
-| baseline | boulevard_day | boulevard_skyline_day | 0.036 | 20.75 | 8.2 | 49.63 | 2.0 | 3.0 | 2.0 | 1.0 | 4.0 |
-| baseline | boulevard_night | hollywood_entrance_rain_night | 1.231 | 21.77 | 8.45 | 50.38 | 1.0 | 2.0 | 1.0 | 1.0 | 2.0 |
-| baseline | entrance_day | hollywood_entrance_morning | 0.308 | 26.19 | 9.27 | 56.39 | 2.0 | 3.0 | 2.0 | 2.0 | 3.0 |
-| baseline | street_day | boulevard_skyline_day | 0.307 | 12.44 | 5.32 | 41.37 | 1.0 | 2.0 | 1.0 | 1.0 | 2.0 |
-| baseline | street_night | boulevard_skyline_dusk | 0.337 | 11.94 | 5.35 | 48.34 | 2.0 | 3.0 | 2.0 | 1.0 | 2.0 |
-| candidate | boulevard_day | boulevard_skyline_day | 0.113 | 20.67 | 7.8 | 42.49 | 2.0 | 3.0 | 2.0 | 2.0 | 5.0 |
-| candidate | boulevard_night | hollywood_entrance_rain_night | 1.073 | 20.67 | 7.86 | 46.43 | 1.0 | 2.0 | 1.0 | 1.0 | 3.0 |
-| candidate | entrance_day | hollywood_entrance_morning | 0.303 | 24.54 | 8.92 | 52.41 | 2.0 | 3.0 | 2.0 | 2.0 | 3.0 |
-| candidate | street_day | boulevard_skyline_day | 0.326 | 14.54 | 5.32 | 36.3 | 1.0 | 2.0 | 1.0 | 1.0 | 3.0 |
-| candidate | street_night | boulevard_skyline_dusk | 0.495 | 16.12 | 6.06 | 48.36 | 2.0 | 3.0 | 2.0 | 2.0 | 4.0 |
-| candidate_dusk | boulevard_day | boulevard_skyline_day | 0.113 | 20.64 | 7.79 | 42.52 | 2.0 | 3.0 | 2.0 | 2.0 | 5.0 |
-| candidate_dusk | boulevard_night | hollywood_entrance_rain_night | 1.041 | 21.29 | 7.93 | 43.3 | 2.0 | 3.0 | 2.0 | 2.0 | 4.0 |
-| candidate_dusk | entrance_day | hollywood_entrance_morning | 0.3 | 24.44 | 8.87 | 52.25 | - | - | - | - | - |
-| candidate_dusk | street_day | boulevard_skyline_day | 0.326 | 14.55 | 5.33 | 36.3 | 2.0 | 3.0 | 2.0 | 1.0 | 4.0 |
-| candidate_dusk | street_night | boulevard_skyline_dusk | 0.463 | 17.04 | 6.13 | 43.69 | 2.0 | 3.0 | 2.0 | 2.0 | 3.0 |
-
-Mean scores per set:
-
-| set | gap ↓ | overall | lighting | materials | texture_detail | backdrop | characters |
-| --- | --- | --- | --- | --- | --- | --- | --- |
-| baseline | 0.444 | 1.6 | 2.6 | 1.6 | 1.2 | 2.6 | 3.0 |
-| candidate | 0.462 | 1.6 | 2.6 | 1.6 | 1.6 | 3.6 | 1.2 |
-| candidate_dusk | 0.449 | 2.0 | 3.0 | 2.0 | 1.75 | 4.0 | 1.0 |
-
-**baseline / boulevard_day** fixes:
-- Improve the lighting model to include more realistic global illumination and soft shadows. The current lighting is too flat and harsh.
-- Replace the current low-polygon character models with more detailed and anatomically correct models. Add variations in clothing and appearance.
-- Increase the texture resolution and detail on all surfaces, especially buildings, roads, and foliage. Implement normal maps and specular maps for greater realism.
-- Enhance the backdrop by adding more detailed building models in the distance, atmospheric perspective (haze), and a more nuanced skybox.
-- Refine the material properties of all objects to better simulate real-world materials. This includes adjusting reflectivity, roughness, and subsurface scattering where appropriate.
-
-**baseline / boulevard_night** fixes:
-- Improve lighting to match the dramatic, atmospheric, and volumetric lighting of the target image, focusing on warm, directional light from the marquee and streetlamp, and realistic reflections on wet surfaces.
-- Significantly upgrade material shaders to achieve realistic PBR (Physically Based Rendering) properties, especially for brick, asphalt, glass, and metal, to mimic the specular highlights, subsurface scattering, and roughness of the target.
-- Increase texture resolution and detail for all surfaces, particularly the brickwork, sidewalk, and building facades, to match the fine-grained realism of the target.
-- Redesign character models with higher polygon counts, more detailed textures, and realistic clothing and facial features to match the stylized but grounded look of the target's lone figure.
-- Enhance the backdrop by adding atmospheric effects like fog, rain, and distant city lights, and refine the building models to have more architectural detail and variation, similar to the target's moody urban environment.
-
-**baseline / entrance_day** fixes:
-- Improve brick texture and material to match the target's depth and variation.
-- Add more detailed and varied foliage, especially for the trees and bushes, to match the target's organic look.
-- Enhance lighting to create softer shadows, more atmospheric haze, and warmer tones, particularly around the building entrance and street.
-- Refine building details, such as window frames, signage, and architectural elements, to increase realism.
-- Introduce subtle imperfections and wear on surfaces like the sidewalk and building facade to mimic real-world aging.
-
-**baseline / street_day** fixes:
-- Improve lighting to match the warm, directional sunlight and soft shadows of the target. Add volumetric fog for atmospheric perspective.
-- Replace flat, untextured building models with detailed geometry and realistic materials (concrete, glass, metal).
-- Add high-resolution textures to all surfaces, especially the road, sidewalk, and buildings, to mimic the detail in the target.
-- Model a more detailed and varied cityscape for the backdrop, including buildings with distinct architectural styles and realistic lighting.
-- Redesign character models to be more anatomically correct and have realistic clothing textures and animations.
-
-**baseline / street_night** fixes:
-- Improve lighting to match the dramatic sunset and neon glow of the target image, focusing on volumetric lighting and bloom effects.
-- Enhance material properties for buildings, road, and car to achieve a more realistic PBR (Physically Based Rendering) look, with appropriate reflections and specularity.
-- Increase texture resolution and detail on all surfaces, especially the road and building facades, to mimic the fine grain and imperfections seen in the target.
-- Redesign the backdrop to include a more detailed and atmospheric skyline with realistic haze and a richer sunset color gradient.
-- Replace the current character models with more detailed and realistically proportioned characters that fit the urban environment.
-
-**candidate / boulevard_day** fixes:
-- Improve road and sidewalk materials to have more realistic specular highlights and surface imperfections.
-- Increase texture resolution and detail on buildings, especially the brickwork, to match the target's fidelity.
-- Replace stylized character models with realistic human models that have appropriate proportions and clothing.
-- Enhance lighting to create softer shadows, more realistic ambient occlusion, and better global illumination, especially around the streetlights and building facades.
-- Add atmospheric perspective and volumetric fog to the distant cityscape to create a more convincing sense of depth and distance haze.
-
-**candidate / boulevard_night** fixes:
-- Improve lighting to create atmospheric mood, with strong contrast and volumetric effects like fog/rain.
-- Enhance material properties for realism: add specular highlights, subsurface scattering for skin, and more detailed surface imperfections.
-- Increase texture resolution and detail, especially on buildings, pavement, and clothing, to match the target's gritty realism.
-- Redesign characters to have more realistic proportions, clothing, and facial features, and animate them with more natural movement.
-- Develop a more detailed and atmospheric backdrop, including realistic city buildings, distant haze, and appropriate weather effects.
-
-**candidate / entrance_day** fixes:
-- Improve brick texture and material to add more variation, grime, and imperfections.
-- Enhance lighting to create softer shadows, more atmospheric haze, and realistic light falloff.
-- Add more detail and variation to the building facade, including window frames, signage, and architectural elements.
-- Replace low-poly trees and bushes with more detailed and realistic foliage models.
-- Refine character models to match the realistic style of the target image, focusing on proportions, clothing, and facial features.
-
-**candidate / street_day** fixes:
-- Improve road and sidewalk materials to have more realistic specular highlights and surface imperfections.
-- Add significant detail to the car models, including realistic reflections, panel gaps, and tire textures.
-- Implement volumetric fog and atmospheric scattering to create a more convincing sense of depth and haze in the backdrop.
-- Replace the placeholder character with a detailed, realistically lit 3D model that matches the environment's style.
-- Enhance the lighting model to include softer shadows, more accurate ambient occlusion, and realistic light bounce.
-
-**candidate / street_night** fixes:
-- Improve lighting to match the dramatic, atmospheric sunset and neon glow of the target image. Add volumetric fog and bloom effects.
-- Significantly enhance material properties for buildings, road, and vehicles to achieve a more realistic PBR (Physically Based Rendering) look, with appropriate reflections and surface imperfections.
-- Increase texture resolution and detail on all surfaces, especially buildings and the road, to match the crispness and complexity of the target.
-- Redesign the backdrop to include a more detailed and atmospheric city skyline with appropriate haze and color grading to match the sunset.
-- Completely overhaul character models to be significantly more detailed, with realistic proportions, clothing, and animation, to match the quality of the target scene.
-
-**candidate_dusk / boulevard_day** fixes:
-- Improve lighting to match the warm, directional sunlight and soft shadows of the target. Add volumetric fog or atmospheric perspective to the distant cityscape.
-- Replace low-poly, stylized assets (trees, characters, buildings) with high-fidelity models that have realistic proportions and details.
-- Apply PBR materials with appropriate roughness, metallic, and normal maps to all surfaces (road, sidewalk, buildings, foliage) to simulate real-world material properties.
-- Increase texture resolution and add surface imperfections (grime, wear, subtle variations) to the road, sidewalk, and building facades.
-- Refine character models to have realistic anatomy, clothing, and animation, and ensure they are properly lit and integrated into the scene.
-
-**candidate_dusk / boulevard_night** fixes:
-- Improve the lighting to match the dramatic, atmospheric, and volumetric lighting of the target image, focusing on warm, directional light from the marquee and streetlamp, and realistic reflections on wet surfaces.
-- Significantly upgrade the character models and animations to be more realistic, with detailed clothing, facial features, and natural posing, rather than the current low-poly, cartoonish style.
-- Enhance material properties and textures for all surfaces (brick, pavement, doors, clothing) to achieve a photorealistic look, with appropriate roughness, reflectivity, and detailed normal maps, especially for the wet environment.
-- Refine the backdrop elements, including the distant city skyline and atmospheric haze, to create a sense of depth and realism consistent with the target image's moody atmosphere.
-- Implement more realistic environmental effects, such as rain, puddles with accurate reflections, and subtle fog, to enhance the overall immersion and match the target's gritty, wet ambiance.
-
-**candidate_dusk / entrance_day** fixes:
-- judge failed: OpenRouter HTTP 400: {"error":{"message":"Provider returned error","code":400,"metadata":{"raw":"{\n  \"error\": {\n    \"code\": 400,\n    \"message\": \"API key not valid. Please pass a valid API key.\",\n    \"status\": \"INVALID_ARGUMENT\",\n    \"details\": [\n      {\n        \"@type\": \"type.googleapis.com/googl
-
-**candidate_dusk / street_day** fixes:
-- Improve road and sidewalk material PBR values to match the target's roughness and reflectivity.
-- Increase the resolution and detail of building textures in the backdrop to reduce the blurry, low-poly appearance.
-- Add atmospheric perspective and volumetric fog to the distant cityscape to mimic the target's depth and haze.
-- Enhance car material properties, particularly reflections and specular highlights, to match the target's realism.
-- Redesign character models to have more detailed geometry, textures, and more natural proportions and posing.
-
-**candidate_dusk / street_night** fixes:
-- Improve lighting to match the dramatic, atmospheric sunset and neon glow of the target image. Add volumetric fog and bloom effects.
-- Enhance material properties for buildings, road, and vehicles to achieve a more realistic PBR (Physically Based Rendering) look, with appropriate reflections and specularity.
-- Increase texture resolution and detail on all surfaces, especially buildings and the road, to match the fine details seen in the target.
-- Redesign the backdrop to include a more detailed and atmospheric city skyline with appropriate haze and color grading to mimic the target's sunset.
-- Significantly rework character models to be more realistic in terms of proportions, texturing, and animation, as the current models are very stylized and cartoony.

docs/screens/realism/2026-11-01-v2/report.json

@@ -1,360 +0,0 @@
-{
-  "run": "docs/screens/realism/2026-11-01-v2",
-  "judge_model": "google/gemini-2.5-flash-lite",
-  "sets": {
-    "baseline": {
-      "boulevard_day": {
-        "target": "docs/screens/concepts/boulevard_skyline_day.png",
-        "metrics": {
-          "edge_density": 20.75,
-          "fine_detail": 8.2,
-          "contrast": 49.63,
-          "saturation_mean": 72.04,
-          "colour_spread": 55.45
-        },
-        "target_metrics": {
-          "edge_density": 20.74,
-          "fine_detail": 8.23,
-          "contrast": 54.85,
-          "saturation_mean": 73.09,
-          "colour_spread": 58.16
-        },
-        "metric_gap": 0.036,
-        "judge": {
-          "scores": {
-            "lighting": 3.0,
-            "materials": 2.0,
-            "texture_detail": 1.0,
-            "backdrop": 4.0,
-            "characters": 1.0,
-            "overall": 2.0
-          },
-          "fixes": [
-            "Improve the lighting model to include more realistic global illumination and soft shadows. The current lighting is too flat and harsh.",
-            "Replace the current low-polygon character models with more detailed and anatomically correct models. Add variations in clothing and appearance.",
-            "Increase the texture resolution and detail on all surfaces, especially buildings, roads, and foliage. Implement normal maps and specular maps for greater realism.",
-            "Enhance the backdrop by adding more detailed building models in the distance, atmospheric perspective (haze), and a more nuanced skybox.",
-            "Refine the material properties of all objects to better simulate real-world materials. This includes adjusting reflectivity, roughness, and subsurface scattering where appropriate."
-          ]
-        }
-      },
-      "boulevard_night": {
-        "target": "docs/screens/concepts/hollywood_entrance_rain_night.png",
-        "metrics": {
-          "edge_density": 21.77,
-          "fine_detail": 8.45,
-          "contrast": 50.38,
-          "saturation_mean": 95.12,
-          "colour_spread": 55.61
-        },
-        "target_metrics": {
-          "edge_density": 8.43,
-          "fine_detail": 3.51,
-          "contrast": 27.34,
-          "saturation_mean": 159.44,
-          "colour_spread": 26.61
-        },
-        "metric_gap": 1.231,
-        "judge": {
-          "scores": {
-            "lighting": 2.0,
-            "materials": 1.0,
-            "texture_detail": 1.0,
-            "backdrop": 2.0,
-            "characters": 1.0,
-            "overall": 1.0
-          },
-          "fixes": [
-            "Improve lighting to match the dramatic, atmospheric, and volumetric lighting of the target image, focusing on warm, directional light from the marquee and streetlamp, and realistic reflections on wet surfaces.",
-            "Significantly upgrade material shaders to achieve realistic PBR (Physically Based Rendering) properties, especially for brick, asphalt, glass, and metal, to mimic the specular highlights, subsurface scattering, and roughness of the target.",
-            "Increase texture resolution and detail for all surfaces, particularly the brickwork, sidewalk, and building facades, to match the fine-grained realism of the target.",
-            "Redesign character models with higher polygon counts, more detailed textures, and realistic clothing and facial features to match the stylized but grounded look of the target's lone figure.",
-            "Enhance the backdrop by adding atmospheric effects like fog, rain, and distant city lights, and refine the building models to have more architectural detail and variation, similar to the target's moody urban environment."
-          ]
-        }
-      },
-      "entrance_day": {
-        "target": "docs/screens/concepts/hollywood_entrance_morning.png",
-        "metrics": {
-          "edge_density": 26.19,
-          "fine_detail": 9.27,
-          "contrast": 56.39,
-          "saturation_mean": 65.24,
-          "colour_spread": 59.96
-        },
-        "target_metrics": {
-          "edge_density": 16.87,
-          "fine_detail": 6.92,
-          "contrast": 70.27,
-          "saturation_mean": 121.02,
-          "colour_spread": 69.83
-        },
-        "metric_gap": 0.308,
-        "judge": {
-          "scores": {
-            "lighting": 3.0,
-            "materials": 2.0,
-            "texture_detail": 2.0,
-            "backdrop": 3.0,
-            "characters": 10.0,
-            "overall": 2.0
-          },
-          "fixes": [
-            "Improve brick texture and material to match the target's depth and variation.",
-            "Add more detailed and varied foliage, especially for the trees and bushes, to match the target's organic look.",
-            "Enhance lighting to create softer shadows, more atmospheric haze, and warmer tones, particularly around the building entrance and street.",
-            "Refine building details, such as window frames, signage, and architectural elements, to increase realism.",
-            "Introduce subtle imperfections and wear on surfaces like the sidewalk and building facade to mimic real-world aging."
-          ]
-        }
-      },
-      "street_day": {
-        "target": "docs/screens/concepts/boulevard_skyline_day.png",
-        "metrics": {
-          "edge_density": 12.44,
-          "fine_detail": 5.32,
-          "contrast": 41.37,
-          "saturation_mean": 77.84,
-          "colour_spread": 44.96
-        },
-        "target_metrics": {
-          "edge_density": 20.74,
-          "fine_detail": 8.23,
-          "contrast": 54.85,
-          "saturation_mean": 73.09,
-          "colour_spread": 58.16
-        },
-        "metric_gap": 0.307,
-        "judge": {
-          "scores": {
-            "lighting": 2.0,
-            "materials": 1.0,
-            "texture_detail": 1.0,
-            "backdrop": 2.0,
-            "characters": 2.0,
-            "overall": 1.0
-          },
-          "fixes": [
-            "Improve lighting to match the warm, directional sunlight and soft shadows of the target. Add volumetric fog for atmospheric perspective.",
-            "Replace flat, untextured building models with detailed geometry and realistic materials (concrete, glass, metal).",
-            "Add high-resolution textures to all surfaces, especially the road, sidewalk, and buildings, to mimic the detail in the target.",
-            "Model a more detailed and varied cityscape for the backdrop, including buildings with distinct architectural styles and realistic lighting.",
-            "Redesign character models to be more anatomically correct and have realistic clothing textures and animations."
-          ]
-        }
-      },
-      "street_night": {
-        "target": "docs/screens/concepts/boulevard_skyline_dusk.png",
-        "metrics": {
-          "edge_density": 11.94,
-          "fine_detail": 5.35,
-          "contrast": 48.34,
-          "saturation_mean": 98.21,
-          "colour_spread": 48.85
-        },
-        "target_metrics": {
-          "edge_density": 8.83,
-          "fine_detail": 4.61,
-          "contrast": 33.26,
-          "saturation_mean": 188.16,
-          "colour_spread": 35.38
-        },
-        "metric_gap": 0.337,
-        "judge": {
-          "scores": {
-            "lighting": 3.0,
-            "materials": 2.0,
-            "texture_detail": 1.0,
-            "backdrop": 2.0,
-            "characters": 1.0,
-            "overall": 2.0
-          },
-          "fixes": [
-            "Improve lighting to match the dramatic sunset and neon glow of the target image, focusing on volumetric lighting and bloom effects.",
-            "Enhance material properties for buildings, road, and car to achieve a more realistic PBR (Physically Based Rendering) look, with appropriate reflections and specularity.",
-            "Increase texture resolution and detail on all surfaces, especially the road and building facades, to mimic the fine grain and imperfections seen in the target.",
-            "Redesign the backdrop to include a more detailed and atmospheric skyline with realistic haze and a richer sunset color gradient.",
-            "Replace the current character models with more detailed and realistically proportioned characters that fit the urban environment."
-          ]
-        }
-      }
-    },
-    "candidate": {
-      "boulevard_day": {
-        "target": "docs/screens/concepts/boulevard_skyline_day.png",
-        "metrics": {
-          "edge_density": 20.67,
-          "fine_detail": 7.8,
-          "contrast": 42.49,
-          "saturation_mean": 67.55,
-          "colour_spread": 48.32
-        },
-        "target_metrics": {
-          "edge_density": 20.74,
-          "fine_detail": 8.23,
-          "contrast": 54.85,
-          "saturation_mean": 73.09,
-          "colour_spread": 58.16
-        },
-        "metric_gap": 0.113,
-        "judge": {
-          "scores": {
-            "lighting": 3.0,
-            "materials": 2.0,
-            "texture_detail": 2.0,
-            "backdrop": 5.0,
-            "characters": 1.0,
-            "overall": 2.0
-          },
-          "fixes": [
-            "Improve road and sidewalk materials to have more realistic specular highlights and surface imperfections.",
-            "Increase texture resolution and detail on buildings, especially the brickwork, to match the target's fidelity.",
-            "Replace stylized character models with realistic human models that have appropriate proportions and clothing.",
-            "Enhance lighting to create softer shadows, more realistic ambient occlusion, and better global illumination, especially around the streetlights and building facades.",
-            "Add atmospheric perspective and volumetric fog to the distant cityscape to create a more convincing sense of depth and distance haze."
-          ]
-        }
-      },
-      "boulevard_night": {
-        "target": "docs/screens/concepts/hollywood_entrance_rain_night.png",
-        "metrics": {
-          "edge_density": 20.67,
-          "fine_detail": 7.86,
-          "contrast": 46.43,
-          "saturation_mean": 98.69,
-          "colour_spread": 50.59
-        },
-        "target_metrics": {
-          "edge_density": 8.43,
-          "fine_detail": 3.51,
-          "contrast": 27.34,
-          "saturation_mean": 159.44,
-          "colour_spread": 26.61
-        },
-        "metric_gap": 1.073,
-        "judge": {
-          "scores": {
-            "lighting": 2.0,
-            "materials": 1.0,
-            "texture_detail": 1.0,
-            "backdrop": 3.0,
-            "characters": 2.0,
-            "overall": 1.0
-          },
-          "fixes": [
-            "Improve lighting to create atmospheric mood, with strong contrast and volumetric effects like fog/rain.",
-            "Enhance material properties for realism: add specular highlights, subsurface scattering for skin, and more detailed surface imperfections.",
-            "Increase texture resolution and detail, especially on buildings, pavement, and clothing, to match the target's gritty realism.",
-            "Redesign characters to have more realistic proportions, clothing, and facial features, and animate them with more natural movement.",
-            "Develop a more detailed and atmospheric backdrop, including realistic city buildings, distant haze, and appropriate weather effects."
-          ]
-        }
-      },
-      "entrance_day": {
-        "target": "docs/screens/concepts/hollywood_entrance_morning.png",
-        "metrics": {
-          "edge_density": 24.54,
-          "fine_detail": 8.92,
-          "contrast": 52.41,
-          "saturation_mean": 61.63,
-          "colour_spread": 54.98
-        },
-        "target_metrics": {
-          "edge_density": 16.87,
-          "fine_detail": 6.92,
-          "contrast": 70.27,
-          "saturation_mean": 121.02,
-          "colour_spread": 69.83
-        },
-        "metric_gap": 0.303,
-        "judge": {
-          "scores": {
-            "lighting": 3.0,
-            "materials": 2.0,
-            "texture_detail": 2.0,
-            "backdrop": 3.0,
-            "characters": 1.0,
-            "overall": 2.0
-          },
-          "fixes": [
-            "Improve brick texture and material to add more variation, grime, and imperfections.",
-            "Enhance lighting to create softer shadows, more atmospheric haze, and realistic light falloff.",
-            "Add more detail and variation to the building facade, including window frames, signage, and architectural elements.",
-            "Replace low-poly trees and bushes with more detailed and realistic foliage models.",
-            "Refine character models to match the realistic style of the target image, focusing on proportions, clothing, and facial features."
-          ]
-        }
-      },
-      "street_day": {
-        "target": "docs/screens/concepts/boulevard_skyline_day.png",
-        "metrics": {
-          "edge_density": 14.54,
-          "fine_detail": 5.32,
-          "contrast": 36.3,
-          "saturation_mean": 74.49,
-          "colour_spread": 39.9
-        },
-        "target_metrics": {
-          "edge_density": 20.74,
-          "fine_detail": 8.23,
-          "contrast": 54.85,
-          "saturation_mean": 73.09,
-          "colour_spread": 58.16
-        },
-        "metric_gap": 0.326,
-        "judge": {
-          "scores": {
-            "lighting": 2.0,
-            "materials": 1.0,
-            "texture_detail": 1.0,
-            "backdrop": 3.0,
-            "characters": 1.0,
-            "overall": 1.0
-          },
-          "fixes": [
-            "Improve road and sidewalk materials to have more realistic specular highlights and surface imperfections.",
-            "Add significant detail to the car models, including realistic reflections, panel gaps, and tire textures.",
-            "Implement volumetric fog and atmospheric scattering to create a more convincing sense of depth and haze in the backdrop.",
-            "Replace the placeholder character with a detailed, realistically lit 3D model that matches the environment's style.",
-            "Enhance the lighting model to include softer shadows, more accurate ambient occlusion, and realistic light bounce."
-          ]
-        }
-      },
-      "street_night": {
-        "target": "docs/screens/concepts/boulevard_skyline_dusk.png",
-        "metrics": {
-          "edge_density": 16.12,
-          "fine_detail": 6.06,
-          "contrast": 48.36,
-          "saturation_mean": 103.44,
-          "colour_spread": 49.1
-        },
-        "target_metrics": {
-          "edge_density": 8.83,
-          "fine_detail": 4.61,
-          "contrast": 33.26,
-          "saturation_mean": 188.16,
-          "colour_spread": 35.38
-        },
-        "metric_gap": 0.495,
-        "judge": {
-          "scores": {
-            "lighting": 3.0,
-            "materials": 2.0,
-            "texture_detail": 2.0,
-            "backdrop": 4.0,
-            "characters": 1.0,
-            "overall": 2.0
-          },
-          "fixes": [
-            "Improve lighting to match the dramatic, atmospheric sunset and neon glow of the target image. Add volumetric fog and bloom effects.",
-            "Significantly enhance material properties for buildings, road, and vehicles to achieve a more realistic PBR (Physically Based Rendering) look, with appropriate reflections and surface imperfections.",
-            "Increase texture resolution and detail on all surfaces, especially buildings and the road, to match the crispness and complexity of the target.",
-            "Redesign the backdrop to include a more detailed and atmospheric city skyline with appropriate haze and color grading to match the sunset.",
-            "Completely overhaul character models to be significantly more detailed, with realistic proportions, clothing, and animation, to match the quality of the target scene."
-          ]
-        }
-      }
-    }
-  }
-}

docs/screens/realism/2026-11-01-v2/report.md

@@ -1,86 +0,0 @@
-# Realism report: `docs/screens/realism/2026-11-01-v2`
-
-Vision judge: `google/gemini-2.5-flash-lite` (scores 0-10, higher is more realistic compared with the concept target).
-
-| set | shot | target | gap ↓ | edges | detail | contrast | overall | lighting | materials | texture | backdrop |
-| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
-| baseline | boulevard_day | boulevard_skyline_day | 0.036 | 20.75 | 8.2 | 49.63 | 2.0 | 3.0 | 2.0 | 1.0 | 4.0 |
-| baseline | boulevard_night | hollywood_entrance_rain_night | 1.231 | 21.77 | 8.45 | 50.38 | 1.0 | 2.0 | 1.0 | 1.0 | 2.0 |
-| baseline | entrance_day | hollywood_entrance_morning | 0.308 | 26.19 | 9.27 | 56.39 | 2.0 | 3.0 | 2.0 | 2.0 | 3.0 |
-| baseline | street_day | boulevard_skyline_day | 0.307 | 12.44 | 5.32 | 41.37 | 1.0 | 2.0 | 1.0 | 1.0 | 2.0 |
-| baseline | street_night | boulevard_skyline_dusk | 0.337 | 11.94 | 5.35 | 48.34 | 2.0 | 3.0 | 2.0 | 1.0 | 2.0 |
-| candidate | boulevard_day | boulevard_skyline_day | 0.113 | 20.67 | 7.8 | 42.49 | 2.0 | 3.0 | 2.0 | 2.0 | 5.0 |
-| candidate | boulevard_night | hollywood_entrance_rain_night | 1.073 | 20.67 | 7.86 | 46.43 | 1.0 | 2.0 | 1.0 | 1.0 | 3.0 |
-| candidate | entrance_day | hollywood_entrance_morning | 0.303 | 24.54 | 8.92 | 52.41 | 2.0 | 3.0 | 2.0 | 2.0 | 3.0 |
-| candidate | street_day | boulevard_skyline_day | 0.326 | 14.54 | 5.32 | 36.3 | 1.0 | 2.0 | 1.0 | 1.0 | 3.0 |
-| candidate | street_night | boulevard_skyline_dusk | 0.495 | 16.12 | 6.06 | 48.36 | 2.0 | 3.0 | 2.0 | 2.0 | 4.0 |
-
-**baseline / boulevard_day** fixes:
-- Improve the lighting model to include more realistic global illumination and soft shadows. The current lighting is too flat and harsh.
-- Replace the current low-polygon character models with more detailed and anatomically correct models. Add variations in clothing and appearance.
-- Increase the texture resolution and detail on all surfaces, especially buildings, roads, and foliage. Implement normal maps and specular maps for greater realism.
-- Enhance the backdrop by adding more detailed building models in the distance, atmospheric perspective (haze), and a more nuanced skybox.
-- Refine the material properties of all objects to better simulate real-world materials. This includes adjusting reflectivity, roughness, and subsurface scattering where appropriate.
-
-**baseline / boulevard_night** fixes:
-- Improve lighting to match the dramatic, atmospheric, and volumetric lighting of the target image, focusing on warm, directional light from the marquee and streetlamp, and realistic reflections on wet surfaces.
-- Significantly upgrade material shaders to achieve realistic PBR (Physically Based Rendering) properties, especially for brick, asphalt, glass, and metal, to mimic the specular highlights, subsurface scattering, and roughness of the target.
-- Increase texture resolution and detail for all surfaces, particularly the brickwork, sidewalk, and building facades, to match the fine-grained realism of the target.
-- Redesign character models with higher polygon counts, more detailed textures, and realistic clothing and facial features to match the stylized but grounded look of the target's lone figure.
-- Enhance the backdrop by adding atmospheric effects like fog, rain, and distant city lights, and refine the building models to have more architectural detail and variation, similar to the target's moody urban environment.
-
-**baseline / entrance_day** fixes:
-- Improve brick texture and material to match the target's depth and variation.
-- Add more detailed and varied foliage, especially for the trees and bushes, to match the target's organic look.
-- Enhance lighting to create softer shadows, more atmospheric haze, and warmer tones, particularly around the building entrance and street.
-- Refine building details, such as window frames, signage, and architectural elements, to increase realism.
-- Introduce subtle imperfections and wear on surfaces like the sidewalk and building facade to mimic real-world aging.
-
-**baseline / street_day** fixes:
-- Improve lighting to match the warm, directional sunlight and soft shadows of the target. Add volumetric fog for atmospheric perspective.
-- Replace flat, untextured building models with detailed geometry and realistic materials (concrete, glass, metal).
-- Add high-resolution textures to all surfaces, especially the road, sidewalk, and buildings, to mimic the detail in the target.
-- Model a more detailed and varied cityscape for the backdrop, including buildings with distinct architectural styles and realistic lighting.
-- Redesign character models to be more anatomically correct and have realistic clothing textures and animations.
-
-**baseline / street_night** fixes:
-- Improve lighting to match the dramatic sunset and neon glow of the target image, focusing on volumetric lighting and bloom effects.
-- Enhance material properties for buildings, road, and car to achieve a more realistic PBR (Physically Based Rendering) look, with appropriate reflections and specularity.
-- Increase texture resolution and detail on all surfaces, especially the road and building facades, to mimic the fine grain and imperfections seen in the target.
-- Redesign the backdrop to include a more detailed and atmospheric skyline with realistic haze and a richer sunset color gradient.
-- Replace the current character models with more detailed and realistically proportioned characters that fit the urban environment.
-
-**candidate / boulevard_day** fixes:
-- Improve road and sidewalk materials to have more realistic specular highlights and surface imperfections.
-- Increase texture resolution and detail on buildings, especially the brickwork, to match the target's fidelity.
-- Replace stylized character models with realistic human models that have appropriate proportions and clothing.
-- Enhance lighting to create softer shadows, more realistic ambient occlusion, and better global illumination, especially around the streetlights and building facades.
-- Add atmospheric perspective and volumetric fog to the distant cityscape to create a more convincing sense of depth and distance haze.
-
-**candidate / boulevard_night** fixes:
-- Improve lighting to create atmospheric mood, with strong contrast and volumetric effects like fog/rain.
-- Enhance material properties for realism: add specular highlights, subsurface scattering for skin, and more detailed surface imperfections.
-- Increase texture resolution and detail, especially on buildings, pavement, and clothing, to match the target's gritty realism.
-- Redesign characters to have more realistic proportions, clothing, and facial features, and animate them with more natural movement.
-- Develop a more detailed and atmospheric backdrop, including realistic city buildings, distant haze, and appropriate weather effects.
-
-**candidate / entrance_day** fixes:
-- Improve brick texture and material to add more variation, grime, and imperfections.
-- Enhance lighting to create softer shadows, more atmospheric haze, and realistic light falloff.
-- Add more detail and variation to the building facade, including window frames, signage, and architectural elements.
-- Replace low-poly trees and bushes with more detailed and realistic foliage models.
-- Refine character models to match the realistic style of the target image, focusing on proportions, clothing, and facial features.
-
-**candidate / street_day** fixes:
-- Improve road and sidewalk materials to have more realistic specular highlights and surface imperfections.
-- Add significant detail to the car models, including realistic reflections, panel gaps, and tire textures.
-- Implement volumetric fog and atmospheric scattering to create a more convincing sense of depth and haze in the backdrop.
-- Replace the placeholder character with a detailed, realistically lit 3D model that matches the environment's style.
-- Enhance the lighting model to include softer shadows, more accurate ambient occlusion, and realistic light bounce.
-
-**candidate / street_night** fixes:
-- Improve lighting to match the dramatic, atmospheric sunset and neon glow of the target image. Add volumetric fog and bloom effects.
-- Significantly enhance material properties for buildings, road, and vehicles to achieve a more realistic PBR (Physically Based Rendering) look, with appropriate reflections and surface imperfections.
-- Increase texture resolution and detail on all surfaces, especially buildings and the road, to match the crispness and complexity of the target.
-- Redesign the backdrop to include a more detailed and atmospheric city skyline with appropriate haze and color grading to match the sunset.
-- Completely overhaul character models to be significantly more detailed, with realistic proportions, clothing, and animation, to match the quality of the target scene.

docs/smoke-checklist.md

@@ -0,0 +1,42 @@
+# Smoke Test Checklist
+
+1. `godot --path .` starts the game on the venue menu without script errors.
+2. Choosing a venue (click or ↑/↓ + Enter) starts that venue's shift and hides the menu.
+3. The guard moves and looks around; the building, steps, and sidewalk are visible.
+4. The guard's camera sits at eye height and the guard stands on the landing, not inside the building.
+5. Walking into the steps carries the guard up onto the landing (steps have colliders).
+6. The skyline backdrop shows silhouettes against the sky, not an opaque black slab.
+7. The `GIG LINE` marquee is readable from the sidewalk.
+8. NPCs spawn and approach the entrance during the first minutes.
+9. Looking at an NPC inside the focus cone shows a blue focus circle in front of the face, the person's name, and the HUD target line.
+10. `Space` or left click opens the action wheel; `A`/`D` highlight a slice, `Space` confirms it, `Esc`/right click cancels without a log entry.
+11. `E`/`C` open the inspection/wand panels from the wheel and freeze movement until they close; walking never fires the wand.
+12. Pressing `Q` produces a reaction log entry and reputation feedback.
+13. `E` opens access inspection showing venue-correct artifacts and policy result; `A`/`D` record a decision.
+14. `6` opens the assistance form; submitting shows dispatch feedback.
+15. `R` opens the emergency form; the button must be held ~1.6s or the call cancels.
+16. `G` toggles the flashlight (indicator appears in the HUD); `L` toggles the door lock (indicator turns red when locked).
+17. `F` toggles the debug overlay with NPC states and shift stats.
+18. The wheel's `Look` slice is eye contact (Level 1) and logs as its own action.
+19. `Reason` asks why the person is there and logs their `dialogue_lines` reply.
+20. `Recognize` records the guard's recognition as access evidence; pressing it twice says so.
+21. `Warn` turns the body camera on (REC overlay appears); `B` toggles it manually.
+22. `Block` moves the guard between the person and the door.
+23. The shift review reports the incident count, including interactions left unresolved.
+24. Escalating on someone (or a responder arriving) makes idle bystanders stop and face the incident.
+25. Repeated alarms panic the crowd and nearby people clear away from the door instead of standing around.
+26. `Esc` with nothing open pauses the shift; resume / restart / settings / quit-to-menu all work, and settings changes persist across a restart.
+27. NPCs route around the building using the navigation mesh (no stuck-at-wall behavior during a smoke run).
+28. An unjustified emergency call (calm person, no weapon) logs an investigation and costs reputation.
+29. After an evacuation outcome the door is locked and NPCs are leaving the entrance.
+30. The shift review's "Body camera timeline" button steps through the recorded events (Left/Right or the buttons) and Esc returns to the review.
+31. The escalation label shows a `[###--] L3/5` shape meter as well as the level name, and stays readable in grayscale.
+32. Changing "HUD font scale" in Settings resizes the HUD text and persists across a restart.
+33. When the shift timer reaches 0, the shift review screen shows grade, policy, incident summary, responder outcomes, investigations, and persisted shift history; campaign Continue starts the next venue.
+34. On a fresh profile the tutorial starts on Hollywood, advances through its eight beats, and F1 skips it; Settings Replay tutorial restarts it.
+35. Pausing saves a checkpoint: returning to the menu and choosing Continue resumes elapsed time, NPCs, incidents, door/flashlight state and campaign position.
+36. Settings difficulty changes spawn pacing/compliance/report strictness while escalation rules stay the same; Help filters controls and shows the venue policy.
+37. The F debug overlay lists the next eligible events; recovery events and recently played scripted events behave as authored.
+38. Master/SFX/ambience volume settings clamp at 0/1 and persist; Reduce motion disables head bob; the captions toggle persists.
+39. The 24-NPC budget smoke stays inside its frame budget; coats/dresses do not show obvious leg clipping in a normal walk.
+40. Help remains readable with the largest HUD font scale, and CI/local verification use the same Godot 4.7.2 baseline.

docs/tutorial.md

@@ -0,0 +1,47 @@
+# First-shift tutorial
+
+Status: implemented for v0.8.0. The tutorial teaches the real controls and the real
+inspection/wheel/radio panels; it is not a fake UI or a separate combat mode.
+Scripted test/capture runs bypass it unless `--tutorial` is passed; a windowed
+smoke covers completion, replay and skip.
+
+## Rules
+
+- One short, safe, compliant visitor. No emergency, threat, crowd panic or random
+  event can interrupt the tutorial.
+- Prompts advance on the performed action, not on a timer. The player can keep
+  moving/looking while a prompt is visible.
+- The tutorial is skippable at any point (F1). Completion and skip are both
+  persisted separately; a skipped tutorial can be replayed from Settings.
+- The tutorial state machine is independent of the shift FSM. It observes the
+  same actions as normal play and must be deterministic for tests.
+
+## Beat sheet
+
+| # | Beat | Prompt | Advances when | Notes |
+| --- | --- | --- | --- | --- |
+| 1 | Arrive | "Walk forward and look around. The entrance is behind you." | The guard has moved at least 1 m and looked away/returned | Start at the normal guard post, facing the street. |
+| 2 | Focus | "Look at the visitor. Press Tab or the mouse wheel to cycle targets." | A target is acquired and explicitly cycled | The visitor waits at the foot of the steps; no other guest is required. |
+| 3 | Wheel | "Open the action wheel with Space or left click." | The radial wheel opens on the visitor | The wheel is the real de-escalation-first wheel. |
+| 4 | Inspect | "Choose Inspect and read the access evidence." | The inspection panel is opened and the policy result is visible | Use a valid wristband so the tutorial can teach both evidence and a safe admit/deny decision. |
+| 5 | Direction | "Close the panel and give a polite direction." | A Level 1 polite-direction action is applied | The visitor complies; there is no escalation requirement. |
+| 6 | Warning | "Give a formal warning if the visitor persists. It arms the body camera." | A Level 2 warning is applied or the body camera is switched on | Show the REC overlay and the escalation cue. |
+| 7 | Radio | "Open the assistance radio and submit a short report." | The assistance report is submitted successfully | A non-emergency assistance call; no responder is required to resolve the tutorial. |
+| 8 | Review | "Finish the shift and review what happened." | The shift review opens | The tutorial ends; the real review remains available for inspection. |
+
+## Visitor script
+
+- Display name: `Visitor`.
+- Intent: `enter` (approaches the door, then waits for interaction).
+- Access: valid wristband evidence; the policy result should be unambiguous.
+- Behavior: compliant at every escalation level; never becomes a threat, never
+  joins a crowd and never triggers an emergency.
+- Failure handling: if the player denies admission incorrectly, the tutorial
+  explains the evidence but does not fail the run; the visitor remains safe and
+  the review records the decision.
+
+## Persistence and replay
+
+Settings gain `tutorial_completed` and `tutorial_skipped`. A first launch starts
+the tutorial after venue selection. Skipping sets `tutorial_skipped`; Settings/
+Help offers "Replay tutorial", which clears both flags for the next shift.

packaging/desktop_hq/README.txt

@@ -0,0 +1,16 @@
+Gig Line — Desktop HQ build
+===========================
+
+This build uses Godot's Forward+ renderer instead of the default
+GL Compatibility renderer, enabling volumetric fog and SDFGI.
+
+Requirements:
+- A Vulkan-capable GPU/driver (Linux or Windows).
+- Keep override.cfg next to the executable. Without it the binary falls back
+  to the normal Compatibility build.
+
+The game still runs if Forward+ is unavailable, but the desktop-only effects
+will be disabled.
+
+Linux:   chmod +x gig-line-linux-*.x86_64 && ./gig-line-linux-*.x86_64
+Windows: run gig-line-windows-*.exe

packaging/desktop_hq/override.cfg

@@ -0,0 +1,12 @@
+; Gig Line desktop HQ preset. Place this file next to the exported executable.
+; It switches only that copy to Forward+; project.godot and the default builds
+; stay on GL Compatibility for Web/CI parity.
+[rendering]
+
+renderer/rendering_method="forward_plus"
+renderer/rendering_method.mobile="forward_plus"
+environment/volumetric_fog/volume_size=128
+environment/volumetric_fog/volume_depth=128
+environment/volumetric_fog/use_filter=1
+global_illumination/sdfgi/frames_to_converge=4
+global_illumination/sdfgi/frames_to_update_lights=2

project.godot

@@ -12,9 +12,9 @@ config_version=5
 
 config/name="Gig Line"
 config/description="Workplace security simulation about observation, access verification, and proportionate escalation."
-config/version="0.6.0"
+config/version="0.9.1"
 run/main_scene="res://scenes/main.tscn"
-config/features=PackedStringArray("4.3", "GL Compatibility")
+config/features=PackedStringArray("4.7", "GL Compatibility")
 
 [autoload]
 

src/autoload/save.gd

@@ -4,6 +4,8 @@ extends Node
 
 const SHIFT_RESULTS_FILE := "shift_results.json"
 const SETTINGS_FILE := "settings.json"
+const CAMPAIGN_FILE := "campaign.json"
+const SHIFT_STATE_FILE := "shift_state.json"
 
 func _load_json(file_name: String) -> Variant:
 	var path := "user://" + file_name
@@ -17,13 +19,17 @@ func _load_json(file_name: String) -> Variant:
 
 func _save_json(file_name: String, data: Variant) -> Error:
 	var path := "user://" + file_name
+	var temp := path + ".tmp"
 	var text := JSON.stringify(data, "\t")
-	var f := FileAccess.open(path, FileAccess.WRITE)
+	var f := FileAccess.open(temp, FileAccess.WRITE)
 	if f == null:
 		return FileAccess.get_open_error()
 	f.store_string(text)
 	f.close()
-	return OK
+	# Replace the target only after the complete JSON has been written, so a
+	# crash cannot leave a partial save in place.
+	return DirAccess.rename_absolute(ProjectSettings.globalize_path(temp),
+		ProjectSettings.globalize_path(path))
 
 ## Load previous shift results. Returns Array of Dictionaries or [].
 func load_shift_results() -> Array:
@@ -38,6 +44,29 @@ func save_shift_result(result: Dictionary) -> Error:
 	results.append(result)
 	return _save_json(SHIFT_RESULTS_FILE, results)
 
+## Campaign/session progression (separate from settings and shift history).
+func load_campaign() -> Dictionary:
+	var data = _load_json(CAMPAIGN_FILE)
+	return data if data is Dictionary else {}
+
+func save_campaign(data: Dictionary) -> Error:
+	return _save_json(CAMPAIGN_FILE, data)
+
+func reset_campaign() -> Error:
+	return _save_json(CAMPAIGN_FILE, {})
+
+## Mid-shift checkpoint. Kept separate so a completed shift history is never
+## overwritten by a resumable snapshot.
+func load_shift_state() -> Dictionary:
+	var data = _load_json(SHIFT_STATE_FILE)
+	return data if data is Dictionary else {}
+
+func save_shift_state(data: Dictionary) -> Error:
+	return _save_json(SHIFT_STATE_FILE, data)
+
+func clear_shift_state() -> Error:
+	return _save_json(SHIFT_STATE_FILE, {})
+
 ## Defaults for player settings. Kept in code so a missing or partial
 ## settings.json still produces a usable config.
 const DEFAULT_SETTINGS := {
@@ -47,6 +76,13 @@ const DEFAULT_SETTINGS := {
 	"head_bob": true,
 	"input_bindings": {},
 	"ai_difficulty": "normal",
+	"tutorial_completed": false,
+	"tutorial_skipped": false,
+	"master_volume": 1.0,
+	"sfx_volume": 1.0,
+	"ambience_volume": 1.0,
+	"reduce_motion": false,
+	"captions_enabled": true,
 }
 
 ## Load player settings, merged over the defaults. Returns a Dictionary.

src/content/scenario_factory.gd

@@ -21,6 +21,11 @@ static func shared_profiles() -> Array[NpcProfile]:
 	tourist.npc_type = Rules.NpcType.TOURIST
 	tourist.temperament = 0.1
 	tourist.base_compliance = 0.9
+	tourist.context_lines = {
+		"refusal": ["I just want a photo, I'm not staying.", "I didn't know this entrance was restricted."],
+		"deescalation": ["Okay, I'll move to the sidewalk.", "Sorry, I'll put the camera away."],
+		"recognition": ["You remember me from the tour, right?"],
+	}
 	tourist.dialogue_lines = [
 		"Oh sure, sorry, just taking a picture.",
 		"Is there a better spot to stand?",
@@ -34,6 +39,10 @@ static func shared_profiles() -> Array[NpcProfile]:
 	confused.npc_type = Rules.NpcType.CONFUSED_VISITOR
 	confused.temperament = 0.2
 	confused.base_compliance = 0.85
+	confused.context_lines = {
+		"refusal": ["I'm sure the event is here. Let me check my phone."],
+		"deescalation": ["Oh, I understand. I'll check with the box office."],
+	}
 	confused.dialogue_lines = [
 		"Wait, this isn't the entrance?",
 		"Sorry about that, I'm a bit lost.",
@@ -389,6 +398,16 @@ static func hollywood_building() -> VenueScenario:
 			"base_weight": 1.0,
 			"requires_emergency": true,
 		},
+		{
+			"id": "building_apology_return",
+			"phase": Rules.Phase.EVENING,
+			"kind": "recovery",
+			"npc_type": Rules.NpcType.AUTHORIZED_GUEST,
+			"intent": "enter",
+			"time_range_s": Vector2(620, 800),
+			"probability": 0.22,
+			"base_weight": 1.0,
+		},
 	]
 	return scenario
 
@@ -451,7 +470,7 @@ static func joke_shop() -> VenueScenario:
 
 	scenario.npc_profiles = _filter_profiles([
 		"tourist", "confused_visitor", "authorized_guest", "authorized_staff",
-		"influencer", "intoxicated", "trespasser", "violent_threat",
+		"street_performer", "influencer", "intoxicated", "trespasser", "violent_threat",
 	])
 
 	scenario.event_pool = [
@@ -533,6 +552,17 @@ static func joke_shop() -> VenueScenario:
 			"probability": 0.5,
 			"base_weight": 1.0,
 		},
+		{
+			"id": "joke_denied_guest_return",
+			"phase": Rules.Phase.EVENING,
+			"kind": "recovery",
+			"npc_type": Rules.NpcType.AUTHORIZED_GUEST,
+			"intent": "enter",
+			"time_range_s": Vector2(650, 830),
+			"probability": 0.2,
+			"base_weight": 1.0,
+			"override_access": {"has_id": true, "has_ticket": true},
+		},
 	]
 	return scenario
 
@@ -648,6 +678,16 @@ static func tv_studio() -> VenueScenario:
 			"probability": 0.45,
 			"base_weight": 1.0,
 		},
+		{
+			"id": "studio_manager_check",
+			"phase": Rules.Phase.EVENING,
+			"kind": "recovery",
+			"npc_type": Rules.NpcType.AUTHORIZED_STAFF,
+			"intent": "enter",
+			"time_range_s": Vector2(620, 820),
+			"probability": 0.2,
+			"base_weight": 1.0,
+		},
 	]
 	return scenario
 

src/core/campaign.gd

@@ -0,0 +1,64 @@
+class_name Campaign
+extends RefCounted
+## Small campaign/session progression model. Venue rules stay in VenueScenario;
+## this only owns order, completed shifts, difficulty and the next venue.
+
+const ORDER := ["hollywood_building", "joke_shop", "tv_studio"]
+
+var index := 0
+var shift_number := 1
+var completed: Array[String] = []
+var difficulty := "normal"
+var complete := false
+var last_grade := ""
+
+func setup(data: Dictionary = {}) -> void:
+	index = clampi(int(data.get("index", 0)), 0, ORDER.size())
+	shift_number = maxi(1, int(data.get("shift_number", 1)))
+	difficulty = str(data.get("difficulty", "normal"))
+	completed.clear()
+	for item in data.get("completed", []):
+		var value := str(item)
+		if value in ORDER and value not in completed:
+			completed.append(value)
+	complete = bool(data.get("complete", index >= ORDER.size()))
+	last_grade = str(data.get("last_grade", ""))
+
+func next_venue() -> String:
+	if complete or index >= ORDER.size():
+		return ""
+	return ORDER[index]
+
+func summary() -> Dictionary:
+	return {
+		"index": index,
+		"next_venue": next_venue(),
+		"shift_number": shift_number,
+		"difficulty": difficulty,
+		"complete": complete,
+		"completed": completed.duplicate(),
+		"last_grade": last_grade,
+	}
+
+## Record one finished shift. Idempotent per venue for a single campaign run.
+func record_shift(scenario_id: String, review: Dictionary = {}) -> bool:
+	if complete:
+		return false
+	if scenario_id != next_venue():
+		return false
+	if scenario_id not in completed:
+		completed.append(scenario_id)
+	var rep: Dictionary = review.get("reputation", {})
+	last_grade = str(rep.get("grade", last_grade))
+	index += 1
+	shift_number = index + 1
+	if index >= ORDER.size():
+		complete = true
+	return true
+
+func set_difficulty(value: String) -> void:
+	if value in ["easy", "normal", "hard"]:
+		difficulty = value
+
+func reset() -> void:
+	setup({})

src/core/crowd_system.gd

@@ -65,3 +65,11 @@ func summary() -> Dictionary:
 		"attention": attention,
 		"panic": crowd_panic,
 	}
+
+func snapshot() -> Dictionary:
+	return summary()
+
+func restore(data: Dictionary) -> void:
+	mood = clampf(float(data.get("mood", 0.05)), 0.0, 1.0)
+	attention = clampf(float(data.get("attention", 0.0)), 0.0, 1.0)
+	crowd_panic = bool(data.get("panic", mood >= 0.75))

src/core/event_scheduler.gd

@@ -11,6 +11,9 @@ signal event_ready(event_data: Dictionary)
 var rng := RandomNumberGenerator.new()
 var _scenario: VenueScenario = null
 var _weighted_pool: Array[Dictionary] = []
+## Difficulty/pacing knob: <1 is calmer, >1 sends more events and routine traffic.
+var spawn_rate_multiplier := 1.0
+var _recent_scripted: Array[String] = []
 
 func _init() -> void:
 	pass
@@ -38,17 +41,47 @@ func pull_due(elapsed_s: float, phase: int) -> Array[Dictionary]:
 			continue
 		var prob: float = event.get("probability", 0.0)
 		var base: float = event.get("base_weight", 1.0)
+		var event_id := str(event.get("id", ""))
+		if str(event.get("kind", "routine")) == "scripted" and event_id in _recent_scripted:
+			continue
 		var spawn_rate: float = event.get("spawn_rate", 0.0)
+		var due_event := false
 		if spawn_rate > 0.0:
 			# Rate-based spawning: emit at most one per second window.
-			if rng.randf() < spawn_rate:
+			if rng.randf() < clampf(spawn_rate * spawn_rate_multiplier, 0.0, 1.0):
 				if rng.randf() < prob:
-					due.append(event.duplicate())
+					due_event = true
 		else:
-			if rng.randf() < prob * base:
-				due.append(event.duplicate())
+			if rng.randf() < clampf(prob * base * spawn_rate_multiplier, 0.0, 1.0):
+				due_event = true
+		if due_event:
+			due.append(event.duplicate())
+			if str(event.get("kind", "routine")) == "scripted" and event_id != "":
+				_recent_scripted.append(event_id)
+				if _recent_scripted.size() > 4:
+					_recent_scripted.pop_front()
 	return due
 
+## Debug/content preview: events that could be selected now, without consuming
+## RNG or marking anything as recently played.
+func preview(elapsed_s: float, phase: int) -> Array[String]:
+	var out: Array[String] = []
+	if _scenario == null:
+		return out
+	for event in _weighted_pool:
+		var time_range: Vector2 = event.get("time_range_s", Vector2(0, _scenario.shift_duration_s))
+		if elapsed_s < time_range.x or elapsed_s > time_range.y:
+			continue
+		if int(event.get("phase", -1)) != phase:
+			continue
+		var event_id := str(event.get("id", ""))
+		if str(event.get("kind", "routine")) == "scripted" and event_id in _recent_scripted:
+			continue
+		out.append("%s (%s)" % [event_id, str(event.get("kind", "routine"))])
+		if out.size() >= 8:
+			break
+	return out
+
 func fallback_routine_traffic(phase: int) -> Array[Dictionary]:
 	## Cheap routine traffic so the street never feels empty.
 	var out: Array[Dictionary] = []
@@ -56,10 +89,19 @@ func fallback_routine_traffic(phase: int) -> Array[Dictionary]:
 	if pool.is_empty():
 		return out
 	for i in 3:
-		if rng.randf() < 0.35:
+		if rng.randf() < clampf(0.35 * spawn_rate_multiplier, 0.0, 1.0):
 			out.append(pool[rng.randi_range(0, pool.size() - 1)].duplicate())
 	return out
 
+func snapshot() -> Dictionary:
+	return {"rng_state": rng.state, "recent_scripted": _recent_scripted.duplicate()}
+
+func restore(data: Dictionary) -> void:
+	rng.state = int(data.get("rng_state", rng.state))
+	_recent_scripted.clear()
+	for event_id in data.get("recent_scripted", []):
+		_recent_scripted.append(str(event_id))
+
 func _routine_pool(phase: int) -> Array:
 	var out: Array = []
 	for event in _weighted_pool:

src/core/incident_recorder.gd

@@ -96,3 +96,20 @@ func to_dict() -> Dictionary:
 		"incidents": incidents.duplicate(true),
 		"open_count": _open_incidents.size(),
 	}
+
+func snapshot() -> Dictionary:
+	return {
+		"incidents": incidents.duplicate(true),
+		"open_incidents": _open_incidents.duplicate(true),
+	}
+
+func restore(data: Dictionary) -> void:
+	incidents.clear()
+	_open_incidents.clear()
+	for incident in data.get("incidents", []):
+		if incident is Dictionary:
+			incidents.append((incident as Dictionary).duplicate(true))
+	for npc_id in (data.get("open_incidents", {}) as Dictionary).keys():
+		var incident = (data["open_incidents"] as Dictionary)[npc_id]
+		if incident is Dictionary:
+			_open_incidents[str(npc_id)] = (incident as Dictionary).duplicate(true)

src/core/npc_controller.gd

@@ -71,10 +71,13 @@ func _build_fsm(initial_state: String) -> void:
 	fsm.add_transition("THREATENING", "FORCING_ENTRY")
 	fsm.start(initial_state)
 
-func roll_reaction(level: int) -> int:
-	## Weighted pick from profile's reaction table for `level`.
+func roll_reaction(level: int, compliance_bonus: float = 0.0) -> int:
+	## Weighted pick from profile's reaction table for `level`. Difficulty can
+	## nudge compliance without changing the authored weights.
 	highest_escalation_received = maxi(highest_escalation_received, level)
 	var weights: Dictionary = profile.pickup_reactions_per_level(level).duplicate()
+	if compliance_bonus != 0.0:
+		weights[Rules.Reaction.COMPLY] = maxf(0.0, float(weights.get(Rules.Reaction.COMPLY, 0)) + compliance_bonus * 100.0)
 	var roll_value := rng.randf()
 	var total := 0.0
 	for key in weights.keys():
@@ -88,9 +91,12 @@ func roll_reaction(level: int) -> int:
 			return key
 	return Rules.Reaction.LEAVE
 
-func apply_player_action(level: int) -> Dictionary:
+func context_line(context: String) -> String:
+	return profile.line_for(context, rng) if profile else ""
+
+func apply_player_action(level: int, compliance_bonus: float = 0.0) -> Dictionary:
 	## Returns reaction to the player's action and updates FSM when needed.
-	var performed_reaction := roll_reaction(level)
+	var performed_reaction := roll_reaction(level, compliance_bonus)
 	reaction = performed_reaction
 	reaction_set = true
 	_update_state_for_reaction(performed_reaction)

src/core/npc_profile.gd

@@ -61,10 +61,27 @@ const Rules := preload("res://src/core/rules.gd")
 ## Dialogue lines this NPC uses. Falls back to generic lines when empty.
 @export var dialogue_lines: Array[String] = []
 
+## Context-specific dialogue: keys such as "reason", "refusal", "deescalation",
+## "recognition" and "group". Missing contexts fall back to `dialogue_lines`.
+@export var context_lines: Dictionary = {}
+
 ## Items the NPC is carrying, used by the handheld wand (The Joke Shop).
 ## Values are item names: "keys", "belt", "phone", "weapon", "knife", etc.
 @export var carried_items: Array[String] = []
 
+func line_for(context: String, rng: RandomNumberGenerator = null) -> String:
+	var pool: Array = []
+	if context_lines.has(context):
+		pool = context_lines[context]
+	elif context == "reason":
+		pool = dialogue_lines
+	if pool.is_empty():
+		return ""
+	var index := 0
+	if rng != null:
+		index = rng.randi_range(0, pool.size() - 1)
+	return str(pool[index])
+
 func pickup_reactions_per_level(level: int) -> Dictionary:
 	if reactions_by_level.has(level):
 		return reactions_by_level[level]

src/core/radio_system.gd

@@ -123,6 +123,23 @@ func tick(delta: float) -> void:
 		if event_bus:
 			event_bus.responder_arrived.emit(call)
 
+func snapshot() -> Dictionary:
+	return {
+		"battery": battery,
+		"emergency_cooldown_remaining": emergency_cooldown_remaining,
+		"accepting_calls": accepting_calls,
+		"pending_calls": pending_calls.duplicate(true),
+	}
+
+func restore(data: Dictionary) -> void:
+	battery = clampf(float(data.get("battery", 100.0)), 0.0, max_battery)
+	emergency_cooldown_remaining = maxf(0.0, float(data.get("emergency_cooldown_remaining", 0.0)))
+	accepting_calls = bool(data.get("accepting_calls", true))
+	pending_calls.clear()
+	for call in data.get("pending_calls", []):
+		if call is Dictionary:
+			pending_calls.append((call as Dictionary).duplicate(true))
+
 ## Determine the responder's resolution outcome for a call. The responder
 ## commands, restrains, evacuates, or arrests based on the reported danger
 ## level and whether a weapon was seen (PLAN.md: Level 5 Emergency Response).

src/core/reputation_evaluator.gd

@@ -52,3 +52,13 @@ func summary() -> Dictionary:
 		"grade": grade_for(rating),
 		"modifiers": _modifiers.duplicate(true),
 	}
+
+func snapshot() -> Dictionary:
+	return {"rating": rating, "modifiers": _modifiers.duplicate(true)}
+
+func restore(data: Dictionary) -> void:
+	rating = clampf(float(data.get("rating", 70.0)), 0.0, 100.0)
+	_modifiers.clear()
+	for modifier in data.get("modifiers", []):
+		if modifier is Dictionary:
+			_modifiers.append((modifier as Dictionary).duplicate(true))

src/core/scenario_validator.gd

@@ -0,0 +1,60 @@
+class_name ScenarioValidator
+extends RefCounted
+## Validates authored venue data before a shift. Keeps content-matrix failures
+## out of runtime: every event must reference a known profile and a valid phase,
+## event ids must be unique, and the matrix must cover enough kinds/phases.
+
+const Rules := preload("res://src/core/rules.gd")
+
+static func validate(scenario: Resource) -> Array[String]:
+	var problems: Array[String] = []
+	if scenario == null:
+		return ["scenario is null"]
+	var profile_types := {}
+	for profile in scenario.npc_profiles:
+		if profile != null:
+			profile_types[int(profile.npc_type)] = true
+	var ids := {}
+	var routine := 0
+	var scripted := 0
+	var recovery := 0
+	var phases := {}
+	for event in scenario.event_pool:
+		if not (event is Dictionary):
+			problems.append("event is not a dictionary")
+			continue
+		var event_id := str(event.get("id", ""))
+		if event_id == "":
+			problems.append("event has no id")
+		elif ids.has(event_id):
+			problems.append("duplicate event id: %s" % event_id)
+		ids[event_id] = true
+		var phase := int(event.get("phase", -1))
+		if phase < Rules.Phase.EARLY or phase > Rules.Phase.LATE:
+			problems.append("%s has invalid phase %d" % [event_id, phase])
+		var npc_type := int(event.get("npc_type", -1))
+		if not profile_types.has(npc_type):
+			problems.append("%s references missing profile type %d" % [event_id, npc_type])
+		if str(event.get("intent", "")) == "":
+			problems.append("%s has no intent" % event_id)
+		var kind := str(event.get("kind", "routine"))
+		if kind == "routine":
+			routine += 1
+		elif kind == "scripted":
+			scripted += 1
+		elif kind == "recovery":
+			recovery += 1
+		elif kind != "routine":
+			problems.append("%s has unknown kind %s" % [event_id, kind])
+		phases[phase] = true
+	if scenario.event_pool.size() < 12:
+		problems.append("event matrix has %d events; need at least 12" % scenario.event_pool.size())
+	if routine < 6:
+		problems.append("event matrix needs at least 6 routine events")
+	if scripted < 2:
+		problems.append("event matrix needs at least 2 scripted events")
+	if recovery < 1:
+		problems.append("event matrix needs at least 1 recovery event")
+	if phases.size() < 2:
+		problems.append("event matrix must cover at least 2 shift phases")
+	return problems

src/core/shift_coordinator.gd

@@ -155,5 +155,39 @@ func build_review() -> Dictionary:
 		"completed_at_ms": Time.get_ticks_msec(),
 	}
 
+func snapshot() -> Dictionary:
+	return {
+		"scenario_id": scenario.id if scenario else "",
+		"duration_s": duration_s,
+		"elapsed_s": elapsed_s,
+		"current_phase": current_phase,
+		"spawned_count": spawned_count,
+		"responder_outcomes": responder_outcomes.duplicate(),
+		"investigations": investigations.duplicate(),
+		"recorder": recorder.snapshot(),
+		"reputation": reputation.snapshot(),
+		"crowd": crowd.snapshot(),
+		"radio": radio.snapshot(),
+		"scheduler": scheduler.snapshot(),
+	}
+
+func restore(data: Dictionary) -> void:
+	duration_s = float(data.get("duration_s", duration_s))
+	elapsed_s = float(data.get("elapsed_s", 0.0))
+	current_phase = int(data.get("current_phase", Rules.Phase.EARLY))
+	spawned_count = int(data.get("spawned_count", 0))
+	responder_outcomes.clear()
+	for value in data.get("responder_outcomes", []):
+		responder_outcomes.append(str(value))
+	investigations.clear()
+	for value in data.get("investigations", []):
+		investigations.append(str(value))
+	recorder.restore(data.get("recorder", {}))
+	reputation.restore(data.get("reputation", {}))
+	crowd.restore(data.get("crowd", {}))
+	radio.restore(data.get("radio", {}))
+	scheduler.restore(data.get("scheduler", {}))
+	_shift_finished = false
+
 func spawn_context_dict(profile: NpcProfile, intent: String) -> Dictionary:
 	return {"profile": profile, "intent": intent}

src/game/audio_feedback.gd

@@ -16,6 +16,23 @@ var radio_crackles := 0
 var footsteps := 0
 var landings := 0
 var precision_ticks := 0
+var master_volume := 1.0
+var sfx_volume := 1.0
+var ambience_volume := 1.0
+var _master_db := 0.0
+var _sfx_db := 0.0
+var _ambience_db := 0.0
+
+## 0..1 mixer controls from Settings. Headless/no-audio builds just store them.
+func set_volumes(master: float, sfx: float, ambience: float) -> void:
+	master_volume = clampf(master, 0.0, 1.0)
+	sfx_volume = clampf(sfx, 0.0, 1.0)
+	ambience_volume = clampf(ambience, 0.0, 1.0)
+	_master_db = linear_to_db(maxf(master_volume, 0.0001))
+	_sfx_db = linear_to_db(maxf(sfx_volume, 0.0001))
+	_ambience_db = linear_to_db(maxf(ambience_volume, 0.0001))
+	if _bed_player:
+		_bed_player.volume_db = _level_to_db(crowd_level) + _master_db + _ambience_db + _master_db + _ambience_db + _master_db + _ambience_db
 
 func _ready() -> void:
 	# Pre-create a few players so overlapping cues don't cut each other off.
@@ -112,7 +129,7 @@ func _play_tone(freq: float, duration: float, volume: float, delay: float = 0.0)
 	stream.mix_rate = SAMPLE_RATE
 	stream.buffer_length = duration + 0.05
 	player.stream = stream
-	player.volume_db = linear_to_db(volume)
+	player.volume_db = linear_to_db(volume) + _master_db + _sfx_db
 	player.play()
 	# Fill the generator buffer with a sine wave.
 	var playback: AudioStreamGeneratorPlayback = player.get_stream_playback()
@@ -174,7 +191,7 @@ func _play_noise(duration: float, volume: float, cutoff_hz: float = 3200.0) -> v
 	stream.stereo = false
 	stream.data = data
 	player.stream = stream
-	player.volume_db = linear_to_db(volume)
+	player.volume_db = linear_to_db(volume) + _master_db + _sfx_db
 	player.play()
 
 func _free_player() -> AudioStreamPlayer:

src/game/game_manager.gd

@@ -30,8 +30,15 @@ const StartMenu := preload("res://src/game/ui/start_menu.gd")
 const PauseOverlay := preload("res://src/game/ui/pause_overlay.gd")
 const SettingsPanel := preload("res://src/game/ui/settings_panel.gd")
 const EventTimeline := preload("res://src/game/ui/event_timeline.gd")
+const Tutorial := preload("res://src/game/tutorial.gd")
+const TutorialOverlay := preload("res://src/game/ui/tutorial_overlay.gd")
+const Campaign := preload("res://src/core/campaign.gd")
+const HelpOverlay := preload("res://src/game/ui/help_overlay.gd")
 
 var world_builder: WorldBuilder = null
+## Dedicated container for the procedural world, so switching venues can rebuild
+## the geometry without touching the guard, UI, or other scene-root children.
+var world_root: Node3D = null
 var door := DoorState.new()
 var flashlight_on := false
 var body_camera_on := false
@@ -51,7 +58,7 @@ const PHASE_LIGHTING := {
 		"sky_ground": Color(0.45, 0.5, 0.55), "ambient": Color(0.75, 0.78, 0.85), "night": false,
 		"exposure": 0.6, "glow": 0.45, "fog_color": Color(0.87, 0.83, 0.76),
 		"fog_density": 0.0034, "fog_energy": 0.5, "contrast": 1.05, "saturation": 1.04,
-		"ambient_energy": 0.1,
+		"ambient_energy": 0.1, "volumetric_density": 0.004, "volumetric_energy": 0.0,
 	},
 	Rules.Phase.MIDDAY: {
 		"sun_energy": 1.0, "sun_angle": -62.0, "sun_yaw": -30.0, "sun_color": Color(1.0, 0.99, 0.96),
@@ -59,7 +66,7 @@ const PHASE_LIGHTING := {
 		"sky_ground": Color(0.5, 0.54, 0.58), "ambient": Color(0.85, 0.88, 0.95), "night": false,
 		"exposure": 0.6, "glow": 0.4, "fog_color": Color(0.88, 0.87, 0.83),
 		"fog_density": 0.0028, "fog_energy": 0.5, "contrast": 1.06, "saturation": 1.04,
-		"ambient_energy": 0.28,
+		"ambient_energy": 0.28, "volumetric_density": 0.003, "volumetric_energy": 0.0,
 	},
 	# Evening is dusk, not a bright sunset: the sun is almost down and the street
 	# is carried by the marquee, the lamps and the lit windows (realism pass).
@@ -69,7 +76,7 @@ const PHASE_LIGHTING := {
 		"sky_ground": Color(0.1, 0.09, 0.12), "ambient": Color(0.2, 0.19, 0.26), "night": true,
 		"exposure": 0.72, "glow": 0.8, "fog_color": Color(0.34, 0.27, 0.3),
 		"fog_density": 0.0026, "fog_energy": 0.45, "contrast": 1.1, "saturation": 1.05,
-		"ambient_energy": 0.12,
+		"ambient_energy": 0.12, "volumetric_density": 0.014, "volumetric_energy": 0.10,
 	},
 	Rules.Phase.LATE: {
 		"sun_energy": 0.02, "sun_angle": -8.0, "sun_color": Color(0.3, 0.35, 0.5),
@@ -77,7 +84,7 @@ const PHASE_LIGHTING := {
 		"sky_ground": Color(0.03, 0.03, 0.05), "ambient": Color(0.06, 0.07, 0.12), "night": true,
 		"exposure": 0.95, "glow": 1.15, "fog_color": Color(0.08, 0.1, 0.2),
 		"fog_density": 0.0028, "fog_energy": 0.45, "contrast": 1.12, "saturation": 1.0,
-		"ambient_energy": 0.22,
+		"ambient_energy": 0.22, "volumetric_density": 0.020, "volumetric_energy": 0.14,
 	},
 }
 var hud: Hud = null
@@ -88,6 +95,16 @@ var start_menu: StartMenu = null
 var pause_overlay: PauseOverlay = null
 var settings_panel: SettingsPanel = null
 var event_timeline: EventTimeline = null
+var tutorial_overlay: TutorialOverlay = null
+var help_overlay: HelpOverlay = null
+var tutorial: Tutorial = null
+var tutorial_active := false
+var campaign: Campaign = null
+var _resuming := false
+var _resume_pending: Dictionary = {}
+var _tutorial_start_pos := Vector3.ZERO
+var _tutorial_start_yaw := 0.0
+var _tutorial_start_pitch := 0.0
 var _timeline_from_review := false
 var _queue_tick := 0.0
 var _input_device := "keyboard"
@@ -104,6 +121,12 @@ var active_scenario_id := "hollywood_building"
 var scenario_duration_s: float = 900.0
 var _wand_cooldown := 0.0
 const WAND_COOLDOWN_S := 0.8
+## Difficulty only changes pacing/forgiveness; the de-escalation rules stay fixed.
+const DIFFICULTY := {
+	"easy": {"spawn": 0.7, "compliance": 0.12, "report": 0.7},
+	"normal": {"spawn": 1.0, "compliance": 0.0, "report": 1.0},
+	"hard": {"spawn": 1.35, "compliance": -0.08, "report": 1.5},
+}
 var scene_root: Node3D = null
 var npcs: Array = []
 var npc_counter := 0
@@ -135,8 +158,11 @@ func _ready() -> void:
 	scene_root = Node3D.new()
 	scene_root.name = "SceneRoot"
 	add_child(scene_root)
+	world_root = Node3D.new()
+	world_root.name = "World"
+	scene_root.add_child(world_root)
 
-	world_builder = WorldBuilder.new(scene_root)
+	world_builder = WorldBuilder.new(world_root, active_scenario_id)
 	world_builder.build()
 	_ensure_lighting()
 
@@ -154,12 +180,15 @@ func _ready() -> void:
 	scenario_duration_s = selected_scenario.shift_duration_s
 	coordinator = ShiftCoordinator.new()
 	coordinator.setup(selected_scenario, scenario_duration_s, 4242)
+	coordinator.scheduler.spawn_rate_multiplier = float(_difficulty()["spawn"])
 	coordinator.npc_spawn_requested.connect(_spawn_npc)
 	coordinator.shift_ended.connect(_on_shift_ended)
 	_connect_radio()
 	_connect_crowd()
 
 	_build_ui()
+	campaign = Campaign.new()
+	campaign.setup(Save.load_campaign() if Save else {})
 	# The HUD does not exist yet when settings are loaded, so push them again now
 	# that it does (otherwise the saved font scale is ignored until the next apply).
 	_apply_settings(player_settings)
@@ -190,31 +219,14 @@ func _build_guard() -> GuardController:
 	# Aim straight ahead: tilting it down made the cone hit the ground right in
 	# front of the guard instead of the person or door being checked.
 	flashlight.rotation_degrees = Vector3.ZERO
-	flashlight.spot_range = 16.0
-	flashlight.spot_angle = 20.0
-	flashlight.light_energy = 4.0
-	flashlight.spot_attenuation = 0.8
+	flashlight.spot_range = 30.0 if Materials.modern_light_falloff() else 20.0
+	flashlight.spot_angle = 14.0
+	flashlight.light_energy = 4.2
+	flashlight.spot_attenuation = 0.0 if Materials.modern_light_falloff() else 0.9
 	flashlight.spot_angle_attenuation = 0.9
-	# Visible beam: a fading additive cone parented to the lamp, because the
-	# Compatibility renderer has no volumetric light. It is offset forward so the
-	# near cap never fills the first-person view.
-	var beam := MeshInstance3D.new()
-	beam.name = "Beam"
-	var cone := CylinderMesh.new()
-	cone.top_radius = 1.0
-	cone.bottom_radius = 0.05
-	cone.height = 5.5
-	cone.radial_segments = 16
-	cone.rings = 1
-	cone.cap_top = false
-	cone.cap_bottom = false
-	beam.mesh = cone
-	# Cylinder axis is +Y; -90° about X aims the wide end along -Z (forward).
-	beam.rotation_degrees = Vector3(-90, 0, 0)
-	beam.position = Vector3(0, 0, -3.65)
-	beam.material_override = Materials.light_beam()
-	beam.cast_shadow = GeometryInstance3D.SHADOW_CASTING_SETTING_OFF
-	flashlight.add_child(beam)
+	# The volumetric shaft is a Forward+ (desktop HQ) effect. Compatibility and
+	# headless builds leave the light non-volumetric, so their look is unchanged.
+	flashlight.light_volumetric_fog_energy = 3.0 if RenderingServer.get_rendering_device() != null else 0.0
 	head.add_child(flashlight)
 	var collider := CollisionShape3D.new()
 	var shape := CapsuleShape3D.new()
@@ -255,12 +267,31 @@ func _build_scenario(id: String) -> VenueScenario:
 func switch_scenario(id: String) -> void:
 	active_scenario_id = id
 	selected_scenario = _build_scenario(id)
+	_rebuild_world_for_venue(id)
 	if coordinator:
 		restart_shift()
 
+## Rebuild the procedural venue in place. The guard/UI stay under `SceneRoot`;
+## only the `World` container is replaced, so navigation, props, lights and the
+## venue-specific dressing match the selected scenario.
+func _rebuild_world_for_venue(id: String) -> void:
+	if world_root == null:
+		return
+	for child in world_root.get_children():
+		child.free()
+	world_builder = WorldBuilder.new(world_root, id)
+	world_builder.build()
+	if guard != null:
+		guard.global_position = world_builder.spec.get("guard_spawn", Vector3(0, 0.1, -2.0))
+		guard.rotation.y = PI
+	if world_builder != null:
+		world_builder.set_door_locked(door.locked)
+
 func restart_shift() -> void:
 	if shift_review_panel:
 		shift_review_panel.hide()
+	if Save:
+		Save.clear_shift_state()
 	_reset_shift_state()
 	_start_shift()
 
@@ -284,6 +315,7 @@ func _reset_shift_state() -> void:
 		hud.set_body_camera(false)
 	scenario_duration_s = selected_scenario.shift_duration_s
 	coordinator.setup(selected_scenario, scenario_duration_s, 4242)
+	coordinator.scheduler.spawn_rate_multiplier = float(_difficulty()["spawn"])
 	_connect_radio()
 	_connect_crowd()
 	_last_phase = -1
@@ -298,6 +330,7 @@ func _start_shift() -> void:
 	coordinator.start()
 	if hud:
 		hud.set_shift_state(coordinator, selected_scenario)
+	_maybe_start_tutorial()
 	# Leaving the venue menu clears input_locked and returns the mouse to
 	# captured mode; without this the guard stays frozen until another modal
 	# opens and closes.
@@ -313,37 +346,86 @@ func _show_start_menu() -> void:
 		guard.input_locked = true
 	Input.set_mouse_mode(Input.MOUSE_MODE_VISIBLE)
 	if start_menu:
-		start_menu.open()
+		start_menu.open(campaign.summary() if campaign else {})
 
 func _on_venue_selected(scenario_id: String) -> void:
 	if start_menu and start_menu.visible:
 		start_menu.close()
+	if not _resuming and Save:
+		Save.clear_shift_state()
 	active_scenario_id = scenario_id
 	_venue_index = maxi(0, VENUE_ORDER.find(scenario_id))
 	selected_scenario = _build_scenario(scenario_id)
+	_rebuild_world_for_venue(scenario_id)
 	if hud:
 		hud.set_wand_icon(false)
 	_reset_shift_state()
 	_start_shift()
+	if not _resume_pending.is_empty():
+		var pending := _resume_pending
+		_resume_pending = {}
+		_restore_shift_state(pending)
+		_resuming = false
 
 ## Apply loaded settings to the guard and HUD.
+func _difficulty() -> Dictionary:
+	return DIFFICULTY.get(str(player_settings.get("ai_difficulty", "normal")),
+		DIFFICULTY["normal"])
+
 func _apply_settings(settings: Dictionary) -> void:
 	player_settings = settings
 	if guard:
 		guard.look_sensitivity = float(settings.get("look_sensitivity", 0.0022))
 		guard.invert_y = bool(settings.get("invert_y", false))
-		guard.head_bob_enabled = bool(settings.get("head_bob", true))
+		guard.head_bob_enabled = bool(settings.get("head_bob", true)) and not bool(settings.get("reduce_motion", false))
+	if audio:
+		audio.set_volumes(float(settings.get("master_volume", 1.0)),
+			float(settings.get("sfx_volume", 1.0)), float(settings.get("ambience_volume", 1.0)))
 	InputBindings.apply(settings.get("input_bindings", {}))
 	if hud and hud.has_method("set_font_scale"):
 		hud.set_font_scale(float(settings.get("hud_font_scale", 1.0)))
 
 func _on_settings_applied(settings: Dictionary) -> void:
 	_apply_settings(settings)
+	if campaign:
+		campaign.set_difficulty(str(settings.get("ai_difficulty", "normal")))
+		if Save:
+			Save.save_campaign(campaign.summary())
+	if coordinator:
+		coordinator.scheduler.spawn_rate_multiplier = float(_difficulty()["spawn"])
 	if start_menu and start_menu.visible:
-		start_menu.open()
+		start_menu.open(campaign.summary() if campaign else {})
 	elif _shift_running:
 		_open_pause()
 
+## Clear the tutorial completion/skip flags and restart the Hollywood shift so
+## the next player can replay the first-shift lesson from Settings.
+func _on_reset_campaign() -> void:
+	if Save:
+		Save.reset_campaign()
+	if campaign:
+		campaign.setup({})
+	if settings_panel:
+		settings_panel.close()
+	if pause_overlay:
+		pause_overlay.close()
+	_show_start_menu()
+
+func _on_replay_tutorial() -> void:
+	player_settings["tutorial_completed"] = false
+	player_settings["tutorial_skipped"] = false
+	if Save:
+		Save.save_settings(player_settings)
+	if settings_panel:
+		settings_panel.close()
+	if pause_overlay:
+		pause_overlay.close()
+	_on_venue_selected("hollywood_building")
+
+func _open_help() -> void:
+	if help_overlay:
+		help_overlay.open(selected_scenario.policy_summary if selected_scenario else "")
+
 func _open_settings() -> void:
 	if start_menu:
 		start_menu.close()
@@ -355,6 +437,7 @@ func _open_settings() -> void:
 func _open_pause() -> void:
 	if pause_overlay == null or not _shift_running:
 		return
+	_save_shift_checkpoint()
 	if _close_top_modal():
 		pass
 	pause_overlay.open()
@@ -398,6 +481,7 @@ func _build_ui() -> void:
 	add_child(shift_review_panel)
 	shift_review_panel.hide()
 	shift_review_panel.restart_requested.connect(_on_review_restart)
+	shift_review_panel.continue_requested.connect(_on_review_continue)
 	shift_review_panel.timeline_requested.connect(_open_timeline)
 	shift_review_panel.visible = false
 
@@ -413,16 +497,27 @@ func _build_ui() -> void:
 	add_child(settings_panel)
 	settings_panel.hide()
 	settings_panel.applied.connect(_on_settings_applied)
+	settings_panel.replay_tutorial_requested.connect(_on_replay_tutorial)
+	settings_panel.reset_campaign_requested.connect(_on_reset_campaign)
 
 	event_timeline = EventTimeline.new()
 	add_child(event_timeline)
 	event_timeline.hide()
 	event_timeline.closed.connect(_on_timeline_closed)
 
+	tutorial_overlay = TutorialOverlay.new()
+	add_child(tutorial_overlay)
+
+	help_overlay = HelpOverlay.new()
+	add_child(help_overlay)
+	help_overlay.closed.connect(_refresh_freeze)
+
 	start_menu = StartMenu.new()
 	add_child(start_menu)
 	start_menu.hide()
 	start_menu.venue_selected.connect(_on_venue_selected)
+	start_menu.continue_requested.connect(_on_campaign_continue)
+	start_menu.help_requested.connect(_open_help)
 	start_menu.settings_requested.connect(_open_settings)
 	start_menu.quit_requested.connect(func(): get_tree().quit())
 
@@ -443,10 +538,147 @@ func _on_timeline_closed() -> void:
 	_timeline_from_review = false
 	_refresh_freeze()
 
+## Pause-safe checkpoint: enough state to resume the current shift without
+## replaying completed interactions. The scheduler RNG is restored so future
+## routine traffic does not repeat the same sequence.
+func _save_shift_checkpoint() -> void:
+	if Save == null or not _shift_running or coordinator == null:
+		return
+	var npc_rows: Array = []
+	for avatar in npcs:
+		if not is_instance_valid(avatar):
+			continue
+		var controller: Object = avatar.get_npc_controller() if avatar.has_method("get_npc_controller") else null
+		var profile: Object = controller.profile if controller else null
+		npc_rows.append({
+			"npc_id": str(controller.npc_id) if controller else "",
+			"npc_type": int(profile.npc_type) if profile else Rules.NpcType.TOURIST,
+			"profile_id": str(profile.id) if profile else "",
+			"intent": str(controller.intent) if controller else "roam",
+			"position": _vec3_array(avatar.global_position),
+			"target": _vec3_array(avatar.target_position),
+			"carried_items": controller.profile.carried_items.duplicate() if controller and controller.profile else [],
+			"leave_requested": bool(controller.leave_requested) if controller else false,
+			"player_recognized": bool(controller.player_recognized) if controller else false,
+			"access_override": (controller.access_override as Dictionary).duplicate(true) if controller else {},
+			"ephemeral": bool(avatar.ephemeral),
+			"lifetime_s": float(avatar.lifetime_s),
+		})
+	var _save_err := Save.save_shift_state({
+		"version": 1,
+		"scenario_id": active_scenario_id,
+		"guard_position": _vec3_array(guard.global_position) if guard else [0.0, 0.0, 0.0],
+		"guard_yaw": guard.rotation.y if guard else 0.0,
+		"head_pitch": guard.head.rotation.x if guard else 0.0,
+		"door_locked": door.locked,
+		"flashlight_on": flashlight_on,
+		"body_camera_on": body_camera_on,
+		"npc_counter": npc_counter,
+		"coordinator": coordinator.snapshot(),
+		"npcs": npc_rows,
+	})
+
+func _vec3_array(value: Vector3) -> Array:
+	return [value.x, value.y, value.z]
+
+func _vec3_from(value: Variant, fallback: Vector3 = Vector3.ZERO) -> Vector3:
+	if value is Vector3:
+		return value
+	if value is Array and (value as Array).size() >= 3:
+		return Vector3(float(value[0]), float(value[1]), float(value[2]))
+	return fallback
+
+func _resume_shift(state: Dictionary) -> void:
+	if state.is_empty() or not state.has("scenario_id"):
+		return
+	_resume_pending = state
+	_resuming = true
+	_on_venue_selected(str(state["scenario_id"]))
+
+func _restore_shift_state(state: Dictionary) -> void:
+	if coordinator == null or not state.has("coordinator"):
+		return
+	coordinator.restore(state.get("coordinator", {}))
+	coordinator.running = true
+	npc_counter = int(state.get("npc_counter", 0))
+	npcs.clear()
+	for row in state.get("npcs", []):
+		if not (row is Dictionary):
+			continue
+		var data: Dictionary = row
+		var profile: NpcProfile = selected_scenario.profile_for(int(data.get("npc_type", Rules.NpcType.TOURIST)))
+		if profile == null:
+			profile = NpcProfile.new()
+			profile.id = str(data.get("profile_id", "guest"))
+			profile.display_name = str(data.get("profile_id", "Guest")).replace("_", " ").capitalize()
+			profile.npc_type = int(data.get("npc_type", Rules.NpcType.TOURIST))
+		_spawn_npc(profile, str(data.get("intent", "roam")), str(data.get("npc_id", "resumed")),
+			{"kind": "scripted"})
+		if npcs.is_empty():
+			continue
+		var avatar: Node3D = npcs[npcs.size() - 1]
+		avatar.global_position = _vec3_from(data.get("position"), avatar.global_position)
+		avatar.target_position = _vec3_from(data.get("target"), avatar.target_position)
+		var controller: Object = avatar.get_npc_controller()
+		if controller:
+			controller.leave_requested = bool(data.get("leave_requested", false))
+			controller.player_recognized = bool(data.get("player_recognized", false))
+			controller.access_override = (data.get("access_override", {}) as Dictionary).duplicate(true)
+			controller.profile.carried_items = []
+			for item in data.get("carried_items", []):
+				controller.profile.carried_items.append(str(item))
+		avatar.ephemeral = bool(data.get("ephemeral", false))
+		avatar.lifetime_s = float(data.get("lifetime_s", 60.0))
+	# Restore presentation state after the world/NPC reset.
+	if guard:
+		guard.global_position = _vec3_from(state.get("guard_position"), guard.global_position)
+		guard.rotation.y = float(state.get("guard_yaw", guard.rotation.y))
+		guard.head.rotation.x = float(state.get("head_pitch", 0.0))
+	door.set_locked(bool(state.get("door_locked", false)))
+	if world_builder:
+		world_builder.set_door_locked(door.locked)
+	flashlight_on = bool(state.get("flashlight_on", false))
+	body_camera_on = bool(state.get("body_camera_on", false))
+	if hud:
+		hud.set_door(door.locked)
+		hud.set_flashlight(flashlight_on)
+		hud.set_body_camera(body_camera_on)
+	if guard:
+		var lamp := guard.get_node_or_null("Head/Flashlight") as SpotLight3D
+		if lamp:
+			lamp.visible = flashlight_on
+	_last_phase = -1
+	_apply_phase_lighting()
+	_refresh_freeze()
+
 ## "Run another shift" on the review screen returns to the venue menu.
 func _on_review_restart() -> void:
 	_show_start_menu()
 
+## Campaign "continue" starts the next venue; completing the last venue returns
+## to the free-play menu.
+func _on_review_continue() -> void:
+	if shift_review_panel:
+		shift_review_panel.visible = false
+	var next_id := campaign.next_venue() if campaign else ""
+	if next_id == "":
+		_show_start_menu()
+		return
+	_on_venue_selected(next_id)
+
+func _on_campaign_continue() -> void:
+	var saved := Save.load_shift_state() if Save else {}
+	if not saved.is_empty() and saved.has("scenario_id"):
+		_resume_shift(saved)
+		return
+	if campaign == null:
+		return
+	var next_id := campaign.next_venue()
+	if next_id == "":
+		_show_start_menu()
+	else:
+		_on_venue_selected(next_id)
+
 func _add_crosshair() -> void:
 	var layer := CanvasLayer.new()
 	layer.layer = 9
@@ -521,7 +753,108 @@ func _apply_phase_lighting() -> void:
 		# night lighting, so the backdrop always matches the phase.
 		world_builder.set_phase(phase)
 
+## Start the first-shift tutorial only for a real player run: scripted tests,
+## captures and smokes pass --script and are explicitly exempt. A tutorial smoke
+## can opt back in with a user `--tutorial` argument.
+func _maybe_start_tutorial() -> void:
+	if tutorial_active or _resuming or active_scenario_id != "hollywood_building":
+		return
+	if bool(player_settings.get("tutorial_completed", false)) \
+			or bool(player_settings.get("tutorial_skipped", false)):
+		return
+	var scripted := false
+	var explicit := false
+	for arg in OS.get_cmdline_args():
+		scripted = scripted or str(arg) == "--script"
+	for arg in OS.get_cmdline_user_args():
+		explicit = explicit or str(arg) == "--tutorial"
+	if scripted and not explicit:
+		return
+	tutorial_active = true
+	tutorial = Tutorial.new()
+	tutorial.beat_changed.connect(_on_tutorial_beat)
+	tutorial.completed.connect(_on_tutorial_completed)
+	_tutorial_start_pos = guard.global_position if guard else Vector3.ZERO
+	_tutorial_start_yaw = guard.rotation.y if guard else 0.0
+	_tutorial_start_pitch = guard.head.rotation.x if guard else 0.0
+	_spawn_tutorial_visitor()
+	tutorial.start()
+	if tutorial_overlay:
+		tutorial_overlay.show_beat(_tutorial_prompt(tutorial.current()), tutorial.progress())
+
+func _spawn_tutorial_visitor() -> void:
+	var p := NpcProfile.new()
+	p.id = "tutorial_visitor"
+	p.display_name = "Visitor"
+	p.npc_type = Rules.NpcType.AUTHORIZED_GUEST
+	p.temperament = 0.0
+	p.base_compliance = 1.0
+	p.reaction_delay = 0.15
+	p.dialogue_lines = ["I have a wristband for the event."]
+	_spawn_npc(p, "enter", "tutorial_visitor", {
+		"kind": "scripted",
+		"tutorial": true,
+		"override_access": {"has_wristband": true},
+	})
+	# Keep the one tutorial subject near the steps so focus/cycling is immediate.
+	if not npcs.is_empty():
+		var visitor: Node3D = npcs[npcs.size() - 1]
+		visitor.global_position = Vector3(2.0, 0.5, 6.0)
+		visitor.target_position = selected_scenario._location_or_default(
+			"entrance", Vector3(0.0, 0.5, 1.2))
+
+func _tutorial_prompt(beat: Dictionary) -> String:
+	var key := str(beat.get("prompt_key", ""))
+	return Strings.lookup(key) if key != "" else str(beat.get("prompt", ""))
+
+func _on_tutorial_beat(_index: int, beat: Dictionary) -> void:
+	if tutorial_overlay:
+		tutorial_overlay.show_beat(_tutorial_prompt(beat), tutorial.progress())
+
+func _tutorial_advance(event: String) -> void:
+	if not tutorial_active or tutorial == null:
+		return
+	tutorial.advance(event)
+
+func _on_tutorial_completed(skipped: bool) -> void:
+	if tutorial == null:
+		return
+	tutorial_active = false
+	player_settings["tutorial_completed"] = not skipped
+	player_settings["tutorial_skipped"] = skipped
+	if Save:
+		Save.save_settings(player_settings)
+	if tutorial_overlay:
+		tutorial_overlay.close()
+	if hud:
+		hud.log(Strings.lookup("tutorial.skipped" if skipped else "tutorial.completed"))
+	if not skipped:
+		# Let the visitor leave cleanly after the final lesson.
+		for avatar in npcs:
+			if is_instance_valid(avatar):
+				var controller: Object = avatar.get_npc_controller()
+				if controller and controller.npc_id == "tutorial_visitor":
+					controller.leave_requested = true
+					break
+
+func _skip_tutorial() -> void:
+	if tutorial_active and tutorial:
+		tutorial.skip()
+
+func _tutorial_tick() -> void:
+	if not tutorial_active or tutorial == null or guard == null:
+		return
+	if tutorial.current().get("id", "") != "arrive":
+		return
+	var moved := guard.global_position.distance_to(_tutorial_start_pos) > 0.75
+	var yaw := absf(wrapf(guard.rotation.y - _tutorial_start_yaw, -PI, PI))
+	var pitch := absf(guard.head.rotation.x - _tutorial_start_pitch)
+	if moved and (yaw > 0.05 or pitch > 0.05):
+		_tutorial_advance("moved")
+
 func _spawn_npc(profile: NpcProfile, intent: String, npc_id: String, event: Dictionary = {}) -> void:
+	if tutorial_active and not bool(event.get("tutorial", false)):
+		return
 	_purge_npcs()
 	if npcs.size() >= MAX_LIVE_NPCS and event.get("kind", "routine") == "routine":
 		return
@@ -705,7 +1038,15 @@ func _on_shift_ended(review: Dictionary) -> void:
 	# Persist the finished shift locally (Save autoload, user:// JSON).
 	if Save:
 		Save.save_shift_result(review)
-	shift_review_panel.show_review(review, selected_scenario, Save.load_shift_results() if Save else [])
+		Save.clear_shift_state()
+	if campaign:
+		campaign.record_shift(active_scenario_id, review)
+		if Save:
+			Save.save_campaign(campaign.summary())
+	shift_review_panel.show_review(review, selected_scenario,
+		Save.load_shift_results() if Save else [],
+		campaign.summary() if campaign else {})
+	_tutorial_advance("review_opened")
 	_refresh_freeze()
 
 ## Keep the people waiting at the door in a deterministic queue: nearest first,
@@ -870,6 +1211,9 @@ func _modal_blocks_radial() -> bool:
 
 func _handle_key(event: InputEvent) -> void:
 	var keycode: Key = event.keycode
+	if tutorial_active and keycode == KEY_F1:
+		_skip_tutorial()
+		return
 	if radial and radial.is_open:
 		if event.is_action_pressed("confirm"):
 			_confirm_radial()
@@ -1006,6 +1350,7 @@ func _open_radial() -> void:
 		p_name = str(controller.profile.display_name)
 	var wand_ok := selected_scenario != null and selected_scenario.equipment.has("wand")
 	radial.open_menu(p_name, wand_ok)
+	_tutorial_advance("wheel_opened")
 	if targeted_npc and targeted_npc.has_method("set_focus_visual"):
 		targeted_npc.set_focus_visual(true, true)
 	_refresh_freeze()
@@ -1103,6 +1448,8 @@ func _set_body_camera(on: bool, reason: String) -> void:
 	if body_camera_on == on:
 		return
 	body_camera_on = on
+	if on:
+		_tutorial_advance("body_camera")
 	if hud:
 		hud.set_body_camera(on)
 	var controller: Object = _targeted_controller()
@@ -1143,6 +1490,8 @@ func _cycle_nearby_target(direction: int = 1) -> void:
 	if guard == null:
 		return
 	var next_target: Node3D = guard.cycle_target(direction)
+	if next_target != null:
+		_tutorial_advance("cycled")
 	if next_target == null:
 		hud.log(Strings.lookup("hud.no_one_nearby"))
 		_refresh_nearby_hint()
@@ -1180,7 +1529,8 @@ func _apply_interaction(level: int, action_name: String) -> void:
 	if controller == null or coordinator == null:
 		return
 	_ensure_incident(controller)
-	var outcome: Dictionary = controller.apply_player_action(level)
+	var outcome: Dictionary = controller.apply_player_action(
+		level, float(_difficulty()["compliance"]))
 	var npc_id: String = controller.npc_id
 	coordinator.recorder.add_event(npc_id, {
 		"type": "player_action",
@@ -1194,6 +1544,10 @@ func _apply_interaction(level: int, action_name: String) -> void:
 	# light goes on: it creates a record of the interaction (PLAN Level 2).
 	if level == Rules.Level.FORMAL_WARNING and not body_camera_on:
 		_set_body_camera(true, "formal warning")
+	if level == Rules.Level.SIMPLE_DETERRENCE and action_name == "polite direction":
+		_tutorial_advance("polite_direction")
+	if level == Rules.Level.FORMAL_WARNING:
+		_tutorial_advance("formal_warning")
 	# Blocking also means physically standing between the person and the door
 	# (PLAN Level 3), not just sending the escalation level.
 	if level == Rules.Level.BLOCKING:
@@ -1201,6 +1555,15 @@ func _apply_interaction(level: int, action_name: String) -> void:
 	hud.set_escalation(level)
 	if audio:
 		audio.play_escalation(level)
+	var context := ""
+	if outcome.get("reaction", -1) in [Rules.Reaction.COMPLY, Rules.Reaction.LEAVE]:
+		context = "deescalation"
+	elif outcome.get("reaction", -1) in [Rules.Reaction.ARGUE, Rules.Reaction.RECORD]:
+		context = "refusal"
+	if context != "":
+		var line: String = controller.context_line(context)
+		if line != "":
+			hud.log("\"%s\"" % line)
 	_react_to_outcome(controller, outcome)
 
 ## Level 1 eye contact: a distinct, quieter cue than raise-hand (PLAN.md). It
@@ -1221,6 +1584,9 @@ func _recognize_target() -> void:
 		return
 	_ensure_incident(controller)
 	controller.player_recognized = true
+	var recognition_line: String = controller.context_line("recognition")
+	if recognition_line != "":
+		hud.log("\"%s\"" % recognition_line)
 	coordinator.recorder.add_access_evidence(controller.npc_id, {
 		"kind": "recognition",
 		"source": "guard_decision",
@@ -1337,7 +1703,9 @@ func _on_radio_submitted(report: Dictionary, emergency: bool) -> void:
 	if not result.get("ok", false):
 		hud.log(Strings.fmt("radio.blocked", [result.get("reason", "unknown")]))
 		return
+	_tutorial_advance("radio_submitted")
 	var hits: int = coordinator.radio.credibility_hits(report, current_npc_truth)
+	hits = int(ceil(float(hits) * float(_difficulty()["report"])))
 	if hits > 0:
 		coordinator.reputation.apply("false_report", -4.0 * hits, "inaccurate radio report")
 		hud.log(Strings.fmt("radio.inaccurate", [4 * hits]))
@@ -1394,6 +1762,7 @@ func _toggle_inspection() -> void:
 	var artifacts := _artifacts_for(controller)
 	var result: Dictionary = verifier.verify(artifacts, selected_scenario.access_policy, controller.screened)
 	hud.show_inspection(controller, artifacts, result)
+	_tutorial_advance("inspected")
 	_refresh_freeze()
 	# Venue door-staff flavor: an applicable check line (PLAN.md: door-staff dialogue).
 	var line := _door_context_line()
@@ -1604,10 +1973,16 @@ func _physics_process(delta: float) -> void:
 	if coordinator == null or not coordinator.running:
 		return
 	coordinator.tick(delta)
+	_tutorial_tick()
 	if coordinator.current_phase != _last_phase:
 		_last_phase = coordinator.current_phase
 		_apply_phase_lighting()
+		if hud and not tutorial_active:
+			hud.log("Objective: %s — keep the entrance clear and verify access." % str(
+				Rules.PHASE_NAMES.get(coordinator.current_phase, "Early")))
 	hud.set_shift_state(coordinator, selected_scenario)
+	var preview := coordinator.scheduler.preview(coordinator.elapsed_s, coordinator.current_phase)
+	hud.refresh_debug(coordinator, npcs, preview)
 	_perception_pass()
 
 ## Perception pass: NPCs notice the guard's proximity (PLAN.md: Level 0

src/game/guard_controller.gd

@@ -115,14 +115,36 @@ static func _ensure_gamepad_bindings() -> void:
 			press.pressed = false
 			InputMap.action_add_event(action, press)
 
-func _unhandled_input(event: InputEvent) -> void:
+## Mouse look is read at the `_input` stage, before GUI/Control handling. A
+## full-screen HUD or a focused control must never be able to swallow relative
+## mouse motion while the game is in captured mode.
+func _input(event: InputEvent) -> void:
 	if input_locked:
 		return
-	if event is InputEventMouseMotion and Input.get_mouse_mode() == Input.MOUSE_MODE_CAPTURED:
-		rotate_y(-event.relative.x * look_sensitivity)
-		var pitch_sign := 1.0 if invert_y else -1.0
-		head.rotate_x(pitch_sign * event.relative.y * look_sensitivity)
-		head.rotation.x = clampf(head.rotation.x, deg_to_rad(-80.0), deg_to_rad(80.0))
+	if event is InputEventMouseMotion:
+		if Input.get_mouse_mode() != Input.MOUSE_MODE_CAPTURED:
+			return
+		_apply_mouse_look(event.relative)
+		get_viewport().set_input_as_handled()
+	elif event is InputEventMouseButton and event.pressed 			and Input.get_mouse_mode() != Input.MOUSE_MODE_CAPTURED:
+		# Recover capture if the window lost it (alt-tab, compositor focus,
+		# clicking back into the game) without opening the radial menu.
+		Input.set_mouse_mode(Input.MOUSE_MODE_CAPTURED)
+		get_viewport().set_input_as_handled()
+
+## Pure look update, kept separate so the rotation math is testable.
+func _apply_mouse_look(relative: Vector2) -> void:
+	rotate_y(-relative.x * look_sensitivity)
+	var pitch_sign := 1.0 if invert_y else -1.0
+	head.rotate_x(pitch_sign * relative.y * look_sensitivity)
+	head.rotation.x = clampf(head.rotation.x, deg_to_rad(-80.0), deg_to_rad(80.0))
+
+func _notification(what: int) -> void:
+	# A window/compositor focus change can silently release capture. Restore it
+	# when gameplay owns the input layer; menus set input_locked instead.
+	if what == NOTIFICATION_APPLICATION_FOCUS_IN or what == NOTIFICATION_WM_WINDOW_FOCUS_IN:
+		if is_inside_tree() and not input_locked:
+			Input.set_mouse_mode(Input.MOUSE_MODE_CAPTURED)
 
 func _physics_process(_delta: float) -> void:
 	if focus_suppress_s > 0.0:

src/game/materials.gd

@@ -128,27 +128,6 @@ static func emissive(color: Color, energy: float = 1.4) -> StandardMaterial3D:
 	mat.roughness = 0.4
 	return mat
 
-## Fake light shaft for the flashlight (Compatibility has no volumetrics).
-## Additive, unshaded, no depth write: it glows over the scene, is still occluded
-## by walls, and fades out along its length instead of ending in a hard disc.
-static func light_beam() -> StandardMaterial3D:
-	var mat := StandardMaterial3D.new()
-	mat.shading_mode = BaseMaterial3D.SHADING_MODE_UNSHADED
-	mat.transparency = BaseMaterial3D.TRANSPARENCY_ALPHA
-	mat.blend_mode = BaseMaterial3D.BLEND_MODE_ADD
-	mat.cull_mode = BaseMaterial3D.CULL_DISABLED
-	mat.depth_draw_mode = BaseMaterial3D.DEPTH_DRAW_DISABLED
-	mat.albedo_color = Color(1.0, 0.95, 0.82, 1.0)
-	var fade := Gradient.new()
-	fade.set_color(0, Color(1.0, 0.95, 0.82, 0.0))
-	fade.add_point(0.18, Color(1.0, 0.95, 0.82, 0.22))
-	fade.set_color(fade.get_point_count() - 1, Color(1.0, 0.95, 0.82, 0.0))
-	var ramp := GradientTexture1D.new()
-	ramp.gradient = fade
-	mat.albedo_texture = ramp
-	mat.texture_filter = BaseMaterial3D.TEXTURE_FILTER_LINEAR
-	return mat
-
 ## Dark glass for windows and the entrance door. The alpha keeps the interior
 ## visible, and the low roughness gives the facade a highlight instead of a hole.
 static func glass(color: Color = Color(0.42, 0.56, 0.72, 0.75)) -> StandardMaterial3D:
@@ -173,9 +152,24 @@ static func window_pane() -> StandardMaterial3D:
 	mat.emission_energy_multiplier = 0.0
 	return mat
 
+## Godot 4.7 changed the Compatibility light falloff in practice: the same
+## attenuation/range that read well on 4.3 leaves the night scene nearly black.
+## Use this switch for local lights until the project moves its baseline to 4.7.
+static func modern_light_falloff() -> bool:
+	var info := Engine.get_version_info()
+	return int(info.get("major", 4)) > 4 \
+		or (int(info.get("major", 4)) == 4 and int(info.get("minor", 0)) >= 7)
+
+## True only when a real RenderingDevice exists. The Compatibility renderer and
+## the headless dummy renderer return null, so the desktop-only effects can be
+## gated without Web/CI builds ever enabling them.
+static func forward_plus_active() -> bool:
+	return RenderingServer.get_rendering_device() != null
+
 ## Environment look shared by every phase: ACES tonemapping, soft glow, aerial
 ## fog for depth, and a mild contrast/saturation lift. Phase values come from
-## `GameManager.PHASE_LIGHTING`.
+## `GameManager.PHASE_LIGHTING`. Volumetric fog and SDFGI are only enabled when
+## Forward+ is actually available (the optional desktop preset).
 static func configure_environment(env: Environment, cfg: Dictionary) -> void:
 	if env == null:
 		return
@@ -201,6 +195,24 @@ static func configure_environment(env: Environment, cfg: Dictionary) -> void:
 	env.fog_density = float(cfg.get("fog_density", 0.0035))
 	env.fog_aerial_perspective = 0.25
 	env.fog_sky_affect = 0.4
+	var advanced := forward_plus_active()
+	env.volumetric_fog_enabled = advanced
+	env.sdfgi_enabled = advanced
+	if advanced:
+		# Desktop HQ: a shallow, cool fog gives the torch a visible shaft while
+		# keeping the entrance facade readable. Phase values are tuned per phase.
+		env.volumetric_fog_density = float(cfg.get("volumetric_density", 0.012))
+		env.volumetric_fog_albedo = cfg.get("volumetric_albedo", Color(0.55, 0.62, 0.72))
+		env.volumetric_fog_emission = cfg.get("volumetric_emission", Color.BLACK)
+		env.volumetric_fog_emission_energy = float(cfg.get("volumetric_energy", 0.0))
+		env.volumetric_fog_anisotropy = 0.25
+		env.volumetric_fog_length = 48.0
+		env.volumetric_fog_ambient_inject = 0.15
+		env.volumetric_fog_sky_affect = 0.2
+		env.sdfgi_use_occlusion = true
+		env.sdfgi_cascades = 4
+		env.sdfgi_min_cell_size = 0.2
+		env.sdfgi_energy = 0.7
 	env.adjustment_enabled = true
 	env.adjustment_brightness = 1.0
 	env.adjustment_contrast = float(cfg.get("contrast", 1.06))

src/game/npc_avatar.gd

@@ -1050,7 +1050,10 @@ func _animate(delta: float) -> void:
 		_idle_t = 0.0
 		_bob_phase += delta * (6.0 + speed * 1.7)
 		var urgency := 1.35 if reaction_mode == "flee" else 1.0
-		var stride := clampf(0.36 + speed * 0.10, 0.42, 0.7) * urgency
+		# Coats and skirts follow the hip/knee bones; a shorter stride keeps the
+		# hem from clipping through the legs during normal walking.
+		var hem_scale := 0.76 if character_model in ["npc_dress", "npc_coat"] else 1.0
+		var stride := clampf(0.36 + speed * 0.10, 0.42, 0.7) * urgency * hem_scale
 		_rig.position.y = sin(_bob_phase * 2.0) * 0.03
 		_rig.position.x = 0.0
 		_rig.rotation.x = sin(_bob_phase) * 0.03

src/game/tutorial.gd

@@ -0,0 +1,126 @@
+class_name Tutorial
+extends RefCounted
+## Deterministic first-shift tutorial state machine. It observes player actions
+## but owns no UI or simulation nodes, so it can be tested headlessly and wired
+## into GameManager without changing the shift FSM. `advance()` only accepts the
+## event for the current beat; wrong actions are ignored.
+
+signal beat_changed(index: int, beat: Dictionary)
+signal completed(skipped: bool)
+
+const BEATS := [
+	{
+		"id": "arrive",
+		"prompt_key": "tutorial.arrive",
+		"prompt": "Walk forward and look around. The entrance is behind you.",
+		"event": "moved",
+	},
+	{
+		"id": "focus",
+		"prompt_key": "tutorial.focus",
+		"prompt": "Look at the visitor. Press Tab or the mouse wheel to cycle targets.",
+		"event": "cycled",
+	},
+	{
+		"id": "wheel",
+		"prompt_key": "tutorial.wheel",
+		"prompt": "Open the action wheel with Space or left click.",
+		"event": "wheel_opened",
+	},
+	{
+		"id": "inspect",
+		"prompt_key": "tutorial.inspect",
+		"prompt": "Choose Inspect and read the access evidence.",
+		"event": "inspected",
+	},
+	{
+		"id": "direction",
+		"prompt_key": "tutorial.direction",
+		"prompt": "Close the panel and give a polite direction.",
+		"event": "polite_direction",
+	},
+	{
+		"id": "warning",
+		"prompt_key": "tutorial.warning",
+		"prompt": "Give a formal warning if the visitor persists. It arms the body camera.",
+		"event": "formal_warning",
+		"alternate_event": "body_camera",
+	},
+	{
+		"id": "radio",
+		"prompt_key": "tutorial.radio",
+		"prompt": "Open the assistance radio and submit a short report.",
+		"event": "radio_submitted",
+	},
+	{
+		"id": "review",
+		"prompt_key": "tutorial.review",
+		"prompt": "Finish the shift and review what happened.",
+		"event": "review_opened",
+	},
+]
+
+var index := -1
+var complete := false
+var skipped := false
+
+func start() -> Dictionary:
+	index = 0
+	complete = false
+	skipped = false
+	var beat: Dictionary = BEATS[0]
+	beat_changed.emit(index, beat)
+	return beat
+
+func current() -> Dictionary:
+	if index < 0 or index >= BEATS.size() or complete:
+		return {}
+	return BEATS[index]
+
+func prompt() -> String:
+	return str(current().get("prompt", ""))
+
+func advance(event: String) -> bool:
+	if complete:
+		return false
+	if index < 0:
+		start()
+	if index >= BEATS.size():
+		return false
+	var beat: Dictionary = BEATS[index]
+	var accepted: Array = [str(beat.get("event", ""))]
+	if beat.has("alternate_event"):
+		accepted.append(str(beat["alternate_event"]))
+	if event not in accepted:
+		return false
+	index += 1
+	if index >= BEATS.size():
+		complete = true
+		index = BEATS.size()
+		completed.emit(false)
+	else:
+		beat_changed.emit(index, BEATS[index])
+	return true
+
+## Skip is recorded separately so Settings/Help can offer "Replay tutorial".
+func skip() -> void:
+	if complete:
+		return
+	skipped = true
+	complete = true
+	index = BEATS.size()
+	completed.emit(true)
+
+func restart() -> Dictionary:
+	return start()
+
+func is_complete() -> bool:
+	return complete
+
+func is_skipped() -> bool:
+	return skipped
+
+## (current beat number, total beats); one-based for display, (total, total)
+## after completion.
+func progress() -> Vector2i:
+	return Vector2i(clampi(index + 1, 1, BEATS.size()), BEATS.size())

src/game/ui/help_overlay.gd

@@ -0,0 +1,109 @@
+class_name HelpOverlay
+extends CanvasLayer
+## New-player help: controls, interaction flow and the current venue policy.
+
+const Strings := preload("res://src/core/strings.gd")
+const InputBindings := preload("res://src/core/input_bindings.gd")
+
+signal closed()
+
+var _root: Control = null
+var _search: LineEdit = null
+var _body: Label = null
+var _policy: String = ""
+var _lines: Array[String] = []
+
+const CONTROL_LINES := [
+	"Movement: W/A/S/D · mouse look · Shift precision walk",
+	"Focus: crosshair cone · Tab / mouse wheel cycles nearby people",
+	"Action wheel: Space or left click · A/D or arrows step · Space confirms",
+	"Inspect access: E · Wand: C · Polite direction: Q",
+	"Warning: 4 · Blocking: 5 · Security radio: 6",
+	"Emergency radio: R, hold the on-screen button to confirm",
+	"Body camera: B · Flashlight: G · Door lock: L",
+	"Pause: Esc · Debug overlay: F",
+]
+
+func _init() -> void:
+	layer = 23
+	_build()
+	hide()
+
+func _build() -> void:
+	_root = Control.new()
+	_root.name = "HelpRoot"
+	_root.set_anchors_preset(Control.PRESET_FULL_RECT)
+	_root.mouse_filter = Control.MOUSE_FILTER_STOP
+	add_child(_root)
+	var dim := ColorRect.new()
+	dim.color = Color(0.02, 0.03, 0.05, 0.86)
+	dim.set_anchors_preset(Control.PRESET_FULL_RECT)
+	dim.mouse_filter = Control.MOUSE_FILTER_IGNORE
+	_root.add_child(dim)
+
+	var center := CenterContainer.new()
+	center.set_anchors_preset(Control.PRESET_FULL_RECT)
+	_root.add_child(center)
+	var column := VBoxContainer.new()
+	column.custom_minimum_size = Vector2(620, 0)
+	column.add_theme_constant_override("separation", 10)
+	center.add_child(column)
+
+	var title := Label.new()
+	title.text = "Help"
+	title.add_theme_font_size_override("font_size", 30)
+	title.horizontal_alignment = HORIZONTAL_ALIGNMENT_CENTER
+	column.add_child(title)
+
+	_search = LineEdit.new()
+	_search.placeholder_text = "Filter controls…"
+	_search.text_changed.connect(_refresh)
+	column.add_child(_search)
+
+	_body = Label.new()
+	_body.autowrap_mode = TextServer.AUTOWRAP_WORD_SMART
+	_body.custom_minimum_size = Vector2(600, 330)
+	_body.vertical_alignment = VERTICAL_ALIGNMENT_TOP
+	column.add_child(_body)
+
+	var close := Button.new()
+	close.text = "Close"
+	close.pressed.connect(func(): close_panel())
+	close.size_flags_horizontal = Control.SIZE_SHRINK_CENTER
+	column.add_child(close)
+
+func open(policy: String = "") -> void:
+	_policy = policy
+	visible = true
+	_root.visible = true
+	_search.text = ""
+	_refresh("")
+	Input.set_mouse_mode(Input.MOUSE_MODE_VISIBLE)
+
+func close_panel() -> void:
+	visible = false
+	_root.visible = false
+	closed.emit()
+
+func _refresh(filter: String) -> void:
+	_lines = []
+	var needle := filter.strip_edges().to_lower()
+	var dynamic := []
+	for action in InputBindings.REMAPPABLE:
+		var label := InputBindings.label_for(InputBindings.current_descriptor(action))
+		dynamic.append("%s: %s" % [str(action).replace("_", " ").capitalize(), label])
+	for line in (CONTROL_LINES + dynamic):
+		if needle == "" or line.to_lower().contains(needle):
+			_lines.append(line)
+	var text := "\n".join(_lines)
+	if _policy != "":
+		text += "\n\nVenue policy: " + _policy
+	_body.text = text
+
+func _unhandled_input(event: InputEvent) -> void:
+	if not visible:
+		return
+	if event is InputEventKey and event.pressed and not event.echo \
+			and event.keycode == KEY_ESCAPE:
+		close_panel()
+		get_viewport().set_input_as_handled()