Fix mouse look swallowing by the HUD

Move guard look handling to the _input stage, recapture the cursor on
window-focus return and when clicking back into gameplay, and make HUD controls
mouse-transparent. Add regression tests for yaw/pitch and HUD mouse filters.
Verified under Xvfb with real relative mouse motion. Headless 237/237, Python
94/94, movement smoke 60 fps.

.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
+# Realism pass (tools/scene_concepts.py): candidate pools, per-run captures and
-# stay local; the validated picks are tracked under game_ready/v2/picks/ (ADR-0014),
+# generated reports stay local; validated picks are tracked under
-# and each run commits its report.{json,md} + sheet.jpg. Concept references are
+# game_ready/v2/picks/ (ADR-0014). Concept references are committed in
-# committed in docs/screens/concepts/.
+# 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

@@ -44,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 `[-]`
@@ -61,11 +67,20 @@ Recommended format:
 ```md
 # TODO
 
-## Core Gameplay
+## Milestone 0.8.0 — First hour and content depth
 
-- [ ] Add player movement controls.
+### 0.8.1 First-shift tutorial
-- [-] Implement NPC approach behavior. (claimed; implementation/verification in progress)
+
-- [x] Define escalation levels.
+- [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
 
@@ -74,16 +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]`.
+1. **Level-3 workstream:** verify the work, mark every checkbox `[x]`, and add a short completion
-2. Move the entire completed section, including its heading and checklist, to `DONE.md`.
+   note. Leave the completed workstream under its parent milestone; do not move an isolated
-3. Remove that section from `TODO.md`.
+   level-3 section to `DONE.md`.
-4. Add a short completion note or date when useful.
+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
-When a completed section 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).
+entry in `CHANGELOG.md` (see "Maintain `CHANGELOG.md`" below).
 
 ### 4. Maintain `MEMORY.md`
 
@@ -154,7 +179,7 @@ The root-level `CHANGELOG.md` records the user-facing changes for every release.
 - 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 level-2 section in `TODO.md` is implemented, completed, and moved to `DONE.md`:
+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.
@@ -172,9 +197,9 @@ For each task:
 4. Run the relevant tests, checks, or manual verification.
 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 (after recording its `CHANGELOG.md` entry).
+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 section 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.
+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.
 

CHANGELOG.md

@@ -4,6 +4,36 @@ 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.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

DONE.md

@@ -1311,3 +1311,28 @@ path.
       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).

MEMORY.md

@@ -23,13 +23,11 @@ Session memory for durable decisions, state, and gotchas. Keep concise, remove o
   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: the finished lighting/flashlight/NPC items
+- Post-realism work is split by theme, not by date: finished items are archived in `DONE.md`, and
-  are archived in `DONE.md`, and `TODO.md` carries three planned workstreams (NPC gear fit,
+  `TODO.md` carries the v1.0.0 gap register and milestone roadmap. New work belongs there, not in
-  venue geometry + committed gallery, Forward+ desktop preset). New visual work should be added
+  a revived historical plan document.
-  as concrete steps under one of those headings instead of a new "realism" bucket.
 
-- Graphics v0.6.0 plan (2026-11-01): NPCs move to Blender-authored skinned meshes
+- Graphics v0.6.0 plan (completed 2026-11-01; ADR-0013): NPCs move to Blender-authored skinned meshes. `tools/npc_pipeline.py` builds
-  (`docs/plan-graphics-v0.6.md`, ADR-0013). `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
@@ -44,6 +42,10 @@ Session memory for durable decisions, state, and gotchas. Keep concise, remove o
 - 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.
+- **Tutorial foundation (0.8.0 work):** `docs/tutorial.md` is the eight-beat design; `src/game/tutorial.gd` is a pure `RefCounted` state machine with skip/restart and tests. It is not yet wired into `GameManager`; when wiring it, add an explicit QA bypass because captures/smokes would otherwise see prompts.
+- **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

PLAN.md

@@ -153,13 +153,13 @@ The visual direction is readable stylized realism:
 - **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.
 
-Remaining visual work is tracked in `TODO.md` (NPC fidelity and the two venue stages), not in this plan.
+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.
 
 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.3, GL Compatibility renderer (Web parity).
+- **Engine:** Godot 4.3 baseline (local dev verified with 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`.
@@ -172,7 +172,7 @@ Primary decisions: [ADR-0007](docs/adr/0007-locomotion-and-input-layers.md), [AD
 
 ## Versioning and Delivery
 
-`config/version` in `project.godot` is the single version source (currently `0.7.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.
+`config/version` in `project.godot` is the single version source (currently `0.7.3`). 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
 

README.md

@@ -31,15 +31,16 @@ precision walk, the Joke Shop alley, the TV Studio arrival, and the prop lineup.
 | **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.7.0** — distinct Joke Shop and TV Studio geometry, fitted NPC gear,
+> **Latest: v0.7.3** — mouse-look input reliability fixes, plus the v0.7.2
-> and the post-v0.6.0 realism/visual-alignment work (v2 skylines/textures, UI mockup
+> cost-aware OpenRouter judge, optional Forward+ Desktop HQ build, distinct
-> art, flashlight beam, HUD fixes).
+> venues and fitted NPC gear.
 > 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
@@ -74,7 +75,7 @@ decisions are recorded as ADRs in [`docs/adr/`](docs/adr/).
 
 ## Tech Stack
 
-- **Engine:** Godot 4.x · **Language:** GDScript
+- **Engine:** Godot 4.3 baseline (local dev verified with 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/`
@@ -102,28 +103,28 @@ Full setup, every run/test/smoke command, and the controls table are in
 
 - [`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/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.
-- [`docs/plan-graphics-v0.6.md`](docs/plan-graphics-v0.6.md) — Graphics-quality plan: Blender-authored NPC characters.
+- [`TODO.md`](TODO.md) — Active tasks plus the v1.0.0 gap analysis and milestone roadmap.
 
 ## Development Status
 
-v0.7.0 shipped distinct venue geometry: the Joke Shop alley and TV Studio
+v0.7.2 ships the cost-aware OpenRouter judge and the optional Desktop HQ build.
-entrance no longer share the Hollywood layout. It builds on v0.6.1's fitted NPC
+The three venues now have distinct geometry, fitted NPC gear, the Blender asset
-gear and v0.6.0's Blender asset library, baked AO and environment lift. See
+library and the post-v0.6.0 realism pass. See
-[`docs/development-status.md`](docs/development-status.md) for the full
+[`docs/development-status.md`](docs/development-status.md) for the implemented
-implemented list and [`TODO.md`](TODO.md) for what's next. Manual verification
+list, and [`TODO.md`](TODO.md) for the v1.0.0 gap analysis and roadmap. Manual
-uses the [`docs/smoke-checklist.md`](docs/smoke-checklist.md).
+verification uses the [`docs/smoke-checklist.md`](docs/smoke-checklist.md).
 
 ## Development Workflow
 

TODO.md

@@ -3,11 +3,249 @@
 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.
 
+## Gap Analysis and v1.0.0 Roadmap
+
+Baseline: **v0.7.2** (2026-11-01). Three playable venues, a complete escalation/access/radio
+loop, shift review, a Blender character/gear/prop library, 231 headless + 94 Python tests, a
+13/13 clean screen-design judge and an optional Forward+ Desktop HQ build. This is a strong
+vertical slice, 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
+
+| Area | Current baseline | Gap to 1.0 | Risk | Milestone |
+| --- | --- | --- | --- | --- |
+| First-hour experience | Venue menu and controls exist; no tutorial | No guided first shift, control coaching, objective recap or "what went wrong" debrief | New players bounce before the de-escalation loop lands | 0.8.0 |
+| Campaign/progression | Venue selection and debug cycle | No career/venue order, unlocks, difficulty curve or persistent player progression | Shift loop feels like a tech demo rather than a game | 0.8.0 |
+| Authored content | 3 venues, small event pools, one-line dialogue | Need a larger event matrix per venue, repeat/remix rules, failure/recovery events and more NPC dialogue | Repetition after a few shifts | 0.8.0 |
+| NPC behavior | FSM intents, reactions, crowd/theater poses | Deeper negotiation, memory of earlier interactions, group dynamics, believable refusal/escalation edges | NPCs still feel deterministic/scripted | 0.8.0 |
+| Access/evaluation | Recognition, wristbands/IDs/tickets/credentials, reputation/review | Fairness tuning, ambiguous cases, clearer evidence trail, richer grades and actionable feedback | Players cannot learn why a decision scored poorly | 0.8.0 |
+| Shift lifecycle | Settings + completed-shift history persist | No mid-shift save/resume, pause-safe serialization, versioned save schema or replay | Interrupted sessions lose the run; future changes can break saves | 0.8.0 |
+| Accessibility | Key remapping, gamepad, HUD font scale, shape escalation cue | Subtitles/captions, colour-independent cues, motion/audio sensitivity, text expansion, menu narration and full input alternatives need an audit | Public 1.0 cannot claim accessible play | 0.8.0–0.9.0 |
+| Localization | English strings in `content/strings.en.json` | String extraction/coverage, pseudo-locale test, font fallback, text-length layout budgets and translator workflow | Text bugs and unsupported locales at release | 0.9.0 |
+| Audio | Procedural crowd bed and radio crackle | Music/ambience direction, event SFX, voice/VO decision, caption hooks and mix budgets | Scene can feel silent/placeholder | 0.9.0 |
+| Animation/presentation | Procedural poses, walk/idle theater, LOD impostor | More reaction/idle/negotiation poses, transitions, facial readability at portrait distance, camera-height decision | Cinematic close-ups expose the prototype layer | 0.9.0 |
+| Performance/platform | 16-NPC budget measured headlessly; Compatibility default; optional Vulkan HQ | Target hardware matrix, 24-NPC profiling, draw-call/memory budgets, Web/HQ parity and frame-time regression gates | Crowded studio or Web drops frames | 0.9.0 |
+| Content tooling | ScenarioFactory/.tres export, Blender manifest, asset audits | Schema validation, previews, event authoring workflow, reproducible asset rebuild notes and contributor onboarding | Content expansion becomes expensive/error-prone | 0.8.0–0.9.0 |
+| QA/CI | Headless suite, smokes, screenshot compare, model-aware judge | End-to-end shift automation, full venue matrix, CI Godot-version strategy, manual judge budget and release checklist automation | Regressions escape or CI becomes non-reproducible | 0.9.0 |
+| Release/legal | Tag-driven unsigned builds, Web zip, optional HQ | Signing/notarization, checksums, AI-asset provenance/licensing, credits, privacy/body-camera statement and storefront requirements | Public release blocked by trust/policy issues | 0.9.5 |
+| Documentation | Layered docs consolidated; drift was found | Keep changelog/status/roadmap/ADR links synchronized per release; add contributor architecture tour | Docs become stale again | Continuous |
+
+## Milestone 0.8.0 — First hour and content depth
+
+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.
+- [ ] Add contextual prompts that advance on the performed action, not on a timer. Prompts must
+      not block normal input or repeat after the player has learned the control.
+- [ ] Stage a safe encounter with one compliant visitor; no emergency, threat or crowd panic in
+      the tutorial. Reuse the real inspection/wheel/radio panels rather than a fake UI.
+- [ ] Persist tutorial completion in settings and add a "Replay tutorial" entry to the help/settings
+      screen.
+- [ ] Add localized tutorial strings and caption-ready prompt hooks.
+- [ ] Add a headless tutorial-state test and a windowed smoke test covering skip, replay and
+      completion.
+
+### 0.8.2 Campaign and session shell
+
+- [ ] Define campaign data separately from `VenueScenario`: venue order, unlock conditions,
+      shift number, selected difficulty and completion state.
+- [ ] Add a campaign-select/continue screen that shows the next shift, venue, policy summary and
+      previous result; keep the existing debug venue cycle separate.
+- [ ] Add a "Continue shift" path with an explicit resume point; define whether resume restores
+      the exact paused shift or the last safe checkpoint.
+- [ ] Add a post-shift screen that names the next objective and offers retry, continue or return
+      to the menu. Do not silently reset progression on failure.
+- [ ] Persist campaign state and expose a reset-campaign action with confirmation.
+- [ ] Add deterministic tests for fresh campaign, resume, completed venue and failed/retried shift.
+
+### 0.8.3 Venue content matrix
+
+- [ ] Add a content matrix per venue with columns for phase, event kind (routine/scripted/edge/
+      recovery/threat), NPC type, intent, access artifact, expected escalation ceiling, failure/
+      recovery path and spawn weight.
+- [ ] Add a validation test that every event references an existing profile, location and phase;
+      reject duplicate IDs and unreachable waypoints at load time.
+- [ ] Expand each venue toward at least 12 authored events and 6 reusable routine variants,
+      covering all four shift phases; prioritize repeatable combinations over one-off set pieces.
+- [ ] Add a no-repeat rule and phase-aware weighting so consecutive shifts do not replay the same
+      scripted event, while rare threats remain genuinely rare.
+- [ ] Add recovery events after player mistakes: a refused authorized guest returns, a manager
+      intervention, a crowd-calming opportunity, or a second chance to explain a policy.
+- [ ] Add a content preview/debug list showing the next eligible events and why they were chosen.
+- [ ] Add tests for phase gating, no-repeat selection, recovery eligibility and event reachability.
+
+### 0.8.4 NPC dialogue and negotiation
+
+- [ ] Define a dialogue data format for intent-specific and context-specific lines: greeting,
+      refusal, de-escalation response, recognition callback, group reaction and resolution.
+- [ ] Expand `NpcProfile` dialogue beyond one-line replies and select lines deterministically from
+      seed, prior interaction and current escalation level; no runtime LLM dependency.
+- [ ] Wire Ask/Reason, polite direction, warning, blocking, recognition and inspection outcomes to
+      the new lines and log entries, with visible differences between comply, argue and refuse.
+- [ ] Add a small set of group reactions so nearby NPCs respond to a raised voice, a warning, a
+      responder or a crowd panic without every NPC speaking at once.
+- [ ] Add placeholder-safe localized strings and tests for deterministic selection, missing lines
+      and dialogue length in the HUD/log.
+- [ ] Run a short dialogue readability pass on the three venues and replace repeated phrases.
+
+### 0.8.5 Objective, policy and debrief layer
+
+- [ ] Add a compact venue-policy card (accepted artifacts, door rules, emergency threshold) that
+      is available from the help overlay and the shift-review screen.
+- [ ] Add an in-shift "current objective" line when the scenario phase changes, without turning
+      the HUD into a quest log.
+- [ ] After an incident, record and display the evidence checked, the chosen escalation level and
+      the reason the response was judged fair, weak or excessive.
+- [ ] Add a first-shift completion summary that explains the grade in plain language and points to
+      the specific decision(s) that mattered.
+- [ ] Add tests for policy-card content, debrief evidence ordering and unknown/missing evidence.
+
+### 0.8.6 Save, resume and settings
+
+- [ ] Define a versioned save schema covering settings, tutorial completion, campaign progress,
+      difficulty and resumable shift state; document what is deliberately not serialized.
+- [ ] Implement atomic writes, corruption detection and safe fallback to defaults or the last
+      completed shift; never overwrite a valid save with a partial one.
+- [ ] Add save migration from the current settings/shift-history format and a test fixture for the
+      previous schema.
+- [ ] Add mid-shift resume that restores RNG state, elapsed time, NPC/incident state and the door
+      state consistently; verify a resumed shift can reach its review.
+- [ ] Add persistence tests for fresh install, corrupt save, version migration, completed shift and
+      resumed shift.
+
+### 0.8.7 Difficulty, pacing and help
+
+- [ ] Add difficulty presets that only adjust spawn rate, tolerance, report strictness and event
+      weights; the de-escalation-first rules and emergency rarity must not change.
+- [ ] Expose difficulty in the campaign/settings UI with the current build as the default "normal"
+      preset and a clear description of each change.
+- [ ] Add a new-player help overlay separate from the HUD: controls, focus/wheel flow, access
+      evidence, body camera, radio and shift review.
+- [ ] Add a searchable/filterable controls reference and keep it synchronized with input bindings.
+- [ ] Add a readability pass for first-shift HUD density; hide advanced debug-only information by
+      default.
+- [ ] Add tests for difficulty defaults, settings persistence and help/controls coverage of every
+      named input action.
+
+### 0.8.8 Verification and exit criteria
+
+- [ ] Add headless tests for tutorial progression, campaign state, content-matrix validation,
+      dialogue selection, save migration and difficulty defaults.
+- [ ] Add windowed/headless smokes for a complete tutorial, a resumed shift, a campaign venue
+      transition and the help overlay.
+- [ ] Run a manual first-hour test with at least three people unfamiliar with the project; record
+      where they get stuck and fix P0/P1 onboarding issues before closing the milestone.
+- [ ] Re-run the full headless suite, Python tooling and smoke checklist; update
+      `docs/development-status.md`, architecture links, changelog and README where behavior changed.
+- [ ] Exit: a first-time player can complete the tutorial and a first real shift without external
+      documentation; each venue has a repeatable content matrix; save/resume survives restart;
+      the 0.8 test matrix is green.
+
+## Milestone 0.9.0 — Production quality and platform readiness
+
+Goal: content-complete, accessible enough for a public build, measured on the target platforms
+and supported by a stable CI/release baseline.
+
+- [ ] Animation/presentation pass: negotiation/reaction poses and transitions, readable faces in
+      portrait, resolved camera height, and no coat/skirt leg clipping in normal movement.
+- [ ] Audio pass: music/ambience direction, event SFX, radio/crowd mix, caption hooks and a VO
+      decision with production scope.
+- [ ] Localization pass: all player-facing strings externalized, pseudo-locale layout test, font
+      fallback and a contributor translation workflow.
+- [ ] Accessibility pass: subtitles/captions, colour-independent access/escalation cues, motion
+      and flash options, full keyboard/gamepad parity and documented assist options.
+- [ ] Performance pass: profile 24 live NPCs, all venues, Web and Desktop HQ; record frame-time,
+      draw-call and memory budgets; add regression checks where automation is possible.
+- [ ] QA pass: automated end-to-end shift for each venue, full smoke matrix, screenshot/judge
+      baselines, and a documented manual judge budget/model pin.
+- [ ] Resolve the Godot baseline: choose one supported version (or an explicit 4.3-CI/4.7-local
+      matrix), align export templates and visual smoke results, and document the policy.
+- [ ] Exit: production content is feature-complete, accessibility/localization acceptance criteria
+      pass, target hardware matrix is measured, and no P0/P1 defect remains open.
+
+## Milestone 0.9.5 — Release candidate
+
+Goal: freeze content, prove it with external players, clear release/legal blockers and verify
+every distribution path.
+
+- [ ] Content lock and external playtest round (at least five first-time players); triage findings
+      by severity and fix all P0/P1 issues.
+- [ ] Balance and fairness pass across all venues: scoring, difficulty, event weights, NPC
+      compliance and emergency false-positive/negative rates.
+- [ ] Save migration test from 0.8/0.9 saves; verify settings, shift history and resume paths.
+- [ ] Release engineering: signed/notarized macOS where possible, checksums, Windows/Linux install
+      smoke tests, AppImage update, Web hosting verification and Desktop HQ Vulkan fallback.
+- [ ] Legal/credits review: AI-assisted asset provenance, music/SFX licenses, privacy/body-camera
+      language, age/content rating and storefront requirements.
+- [ ] Documentation sign-off: architecture/ADR/status/TODO/changelog/README/smoke checklist all
+      match the release candidate; capture final gallery and run compare + judge.
+- [ ] Exit: release candidate passes the manual smoke checklist on every target; no release-blocking
+      legal or platform issue remains.
+
+## 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)
 
-- [ ] Re-run the screen-design judge for `12-joke-shop`, `13-studio-arrival` and the
+- [x] Re-run the screen-design judge for `12-joke-shop`, `13-studio-arrival` and the
-      Forward+ A/B when `OPENROUTER_API_KEY` is valid; the 2026-11-01 attempt failed with an
+      Forward+ A/B with the valid key: **13/13 match, 0 diff**; the HQ A/B is in the report.
-      invalid-key HTTP 400.
 - [ ] 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,

docs/RELEASING.md

@@ -127,14 +127,15 @@ 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
@@ -171,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

@@ -25,7 +25,7 @@ This document follows the structure of the arc42 architecture documentation temp
 ## 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 with GDScript; a playable prototype vertical slice is implemented. CI pins Godot 4.3 while local development is verified with 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).
@@ -37,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.7.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).
+The single source of truth for the version is `config/version` in `project.godot` (currently `0.7.3`). 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
 
@@ -83,7 +83,7 @@ The player interacts with NPCs, venue entrances, access artifacts, equipment, st
 - `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/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.
@@ -106,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
@@ -118,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.
@@ -137,7 +180,7 @@ in code.
 
 ## 7. Deployment View
 
-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 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 pins Godot 4.3 while local development is verified with 4.7.2, so the light falloff path is version-adaptive until the baseline is unified.
 
 Future options include external analytics, cloud saves, or replay sharing, but they are not part of the current architecture.
 
@@ -173,6 +216,8 @@ The release process is: bump the version, run the full test suite and `tools/che
 - **Localization:** Dialogue and prompts should be externalized from logic.
 - **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.
+- **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
 
@@ -203,6 +248,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
 
@@ -213,8 +261,44 @@ Architecture decisions are recorded as ADRs:
 - 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 version skew (CI 4.3 vs local 4.7.2) can change lighting, import sidecars and generated UIDs; a single supported version and a visual smoke matrix are required before 1.0.
+- 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

@@ -1,6 +1,10 @@
 # Asset Pipeline and Tooling
 
-Everything the game renders is produced or gated by the scripts below. Development-only outputs (AI concept sheets, Blender sources, raw AI fabrics) are gitignored; the audited game assets are committed.
+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
 
@@ -82,7 +86,8 @@ character authored in Blender ([ADR-0013](adr/0013-blender-authored-npc-characte
 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](plan-graphics-v0.6.md)).
+[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)
@@ -185,26 +190,30 @@ 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 texture-adoption run,
+(`--portrait-type=N` picks a role). The generated realism runs under
-[`docs/screens/realism/2026-11-01-adopt/`](../docs/screens/realism/2026-11-01-adopt/report.md),
+`docs/screens/realism/` are **local, gitignored QA artifacts**; commit only the
-compares the pre-adoption captures with the current build: on the shots both sets captured the
+resulting decisions/docs, not the run folders. The texture-adoption run compared
-judge's like-for-like means rose on every sub-score (overall 0.8 → 1.0, backdrop 0.6 → 1.6) and
+the pre-adoption captures with the current build: on the shots both sets captured,
-the Pillow metric gap fell 0.444 → 0.348. The character pass
+the judge's like-for-like means rose on every sub-score (overall 0.8 → 1.0,
-([`2026-11-01-npc/`](../docs/screens/realism/2026-11-01-npc/report.md)) adds the portrait shot and
+backdrop 0.6 → 1.6) and the Pillow metric gap fell 0.444 → 0.348. The character
-records the new faces, hands and sleeve cuffs. The
+pass added the portrait shot and recorded the new faces, hands and sleeve cuffs.
-Forward+ A/B ([`2026-11-01-forward-plus/`](../docs/screens/realism/2026-11-01-forward-plus/report.md))
+The Forward+ A/B compared the Compatibility entrance with the optional Desktop HQ
-compares the Compatibility entrance with the optional Desktop HQ preset.
+preset. The gear-fit run checked the sunglasses, bag and helmet against measured
- The gear-fit run
+head/skirt bounds with `python3 tools/blender_assets.py fit`; it also fixed the
-([`2026-11-01-gear/`](../docs/screens/realism/2026-11-01-gear/report.md)) checks
+portrait yaw and hid the focus overlay so the close-up shows the avatar.
-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.
 
-![realism run](../docs/screens/realism/2026-11-01-adopt/sheet.jpg)
+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
 

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
+with colliders and phase-driven emissives.
-[`plan-graphics-v0.6.md`](plan-graphics-v0.6.md).
 
 Generator: [`tools/blender_assets.py`](../tools/blender_assets.py). Manifest (the
 source of truth for integration):
@@ -159,10 +161,10 @@ 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
+Props use plain PBR factors (base colour, roughness, metallic, emission) plus
-have no textures. They are not yet AO-baked; that is still a Phase 4 task.
+the committed 256² baked AO maps (`<name>_ao.png`) wired by `WorldBuilder`;
-Emissive materials are always on in the GLB. The integration should tie them to
+emissive materials are tied to `WorldBuilder.set_night_mode()`. Characters
-`WorldBuilder.set_night_mode()`.
+carry baked AO and the shared neutral material maps described above.
 
 ## Checks
 

docs/development-status.md

@@ -5,7 +5,7 @@ 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: **231 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)
+- Headless unit tests: **237 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`)
@@ -40,9 +40,11 @@ Implemented so far:
 
 - 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 now releases the start-menu input lock and recaptures the mouse; the body-camera overlay no longer covers the shift status.
+- 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.
-- 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 live in `docs/screens/realism/2026-11-01-forward-plus/`.
+- Tutorial foundation (0.8.0 work): the eight-beat first-shift design and a deterministic, skippable/restartable `Tutorial` state machine exist; the in-game prompt/visitor wiring is the next step.
+- 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.
 
-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`](../TODO.md)).
+Current gaps for v1.0.0: onboarding/campaign progression, deeper authored content and NPC dialogue, mid-shift save/resume and replay, localization/accessibility expansion, voice/audio production, wider performance profiling, 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

@@ -16,6 +16,8 @@ A typical shift lasts 10–15 minutes. The player:
 
 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).
+
 ## Venues
 
 ### Hollywood Boulevard Building

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

@@ -26,10 +26,9 @@ 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 (`docs/screens/realism/2026-11-01-npc/`).
+eyeball after an avatar change (generate a local run under `docs/screens/realism/`).
 
-Cross-cutting targets, for comparison with the 2026-11-01 captures in
+Cross-cutting targets, for comparison with locally generated realism runs:
-`docs/screens/realism/2026-11-01-v2/sheet.jpg`:
 
 - **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-forward-plus/report.json

@@ -1,82 +0,0 @@
-{
-  "run": "docs/screens/realism/2026-11-01-forward-plus-eval",
-  "judge_model": null,
-  "sets": {
-    "baseline": {
-      "entrance_late": {
-        "target": "docs/screens/concepts/hollywood_entrance_rain_night.png",
-        "metrics": {
-          "edge_density": 21.3,
-          "fine_detail": 9.55,
-          "contrast": 68.03,
-          "saturation_mean": 127.45,
-          "colour_spread": 67.44
-        },
-        "target_metrics": {
-          "edge_density": 8.43,
-          "fine_detail": 3.51,
-          "contrast": 27.34,
-          "saturation_mean": 159.44,
-          "colour_spread": 26.61
-        },
-        "metric_gap": 1.568
-      },
-      "street_late": {
-        "target": "docs/screens/concepts/boulevard_skyline_dusk.png",
-        "metrics": {
-          "edge_density": 10.57,
-          "fine_detail": 6.21,
-          "contrast": 26.84,
-          "saturation_mean": 74.1,
-          "colour_spread": 26.55
-        },
-        "target_metrics": {
-          "edge_density": 8.83,
-          "fine_detail": 4.61,
-          "contrast": 33.26,
-          "saturation_mean": 188.16,
-          "colour_spread": 35.38
-        },
-        "metric_gap": 0.247
-      }
-    },
-    "candidate": {
-      "entrance_late": {
-        "target": "docs/screens/concepts/hollywood_entrance_rain_night.png",
-        "metrics": {
-          "edge_density": 19.31,
-          "fine_detail": 8.37,
-          "contrast": 55.27,
-          "saturation_mean": 104.53,
-          "colour_spread": 54.55
-        },
-        "target_metrics": {
-          "edge_density": 8.43,
-          "fine_detail": 3.51,
-          "contrast": 27.34,
-          "saturation_mean": 159.44,
-          "colour_spread": 26.61
-        },
-        "metric_gap": 1.187
-      },
-      "street_late": {
-        "target": "docs/screens/concepts/boulevard_skyline_dusk.png",
-        "metrics": {
-          "edge_density": 11.4,
-          "fine_detail": 6.21,
-          "contrast": 27.58,
-          "saturation_mean": 77.86,
-          "colour_spread": 27.49
-        },
-        "target_metrics": {
-          "edge_density": 8.83,
-          "fine_detail": 4.61,
-          "contrast": 33.26,
-          "saturation_mean": 188.16,
-          "colour_spread": 35.38
-        },
-        "metric_gap": 0.258
-      }
-    }
-  }
-}

docs/screens/realism/2026-11-01-forward-plus/report.md

@@ -1,42 +0,0 @@
-# Realism report: `docs/screens/realism/2026-11-01-forward-plus`
-
-| set | shot | target | gap ↓ | edges | detail | contrast | overall | lighting | materials | texture | backdrop |
-| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
-| baseline | entrance_late | hollywood_entrance_rain_night | 1.568 | 21.3 | 9.55 | 68.03 | - | - | - | - | - |
-| baseline | street_late | boulevard_skyline_dusk | 0.247 | 10.57 | 6.21 | 26.84 | - | - | - | - | - |
-| candidate | entrance_late | hollywood_entrance_rain_night | 1.187 | 19.31 | 8.37 | 55.27 | - | - | - | - | - |
-| candidate | street_late | boulevard_skyline_dusk | 0.258 | 11.4 | 6.21 | 27.58 | - | - | - | - | - |
-
-Mean scores per set (all captured shots):
-
-| set | shots | gap ↓ | overall | lighting | materials | texture_detail | backdrop | characters |
-| --- | --- | --- | --- | --- | --- | --- | --- | --- |
-| baseline | 2 | 0.907 | - | - | - | - | - | - |
-| candidate | 2 | 0.723 | - | - | - | - | - | - |
-
-
-## Desktop HQ A/B
-
-`baseline` is the normal GL Compatibility build; `candidate` is the same
-staging with `packaging/desktop_hq/override.cfg` beside the project (Forward+,
-SDFGI and volumetric fog). Both use `--stages=late --flashlight`.
-
-The entrance metric gap improved **1.568 → 1.187** and the two-shot mean
-**0.907 → 0.723**. The flashlight now lights the door instead of disappearing
-into the dark, while the LATE volumetric density (0.020) leaves the brick
-facade readable instead of washing it out. `street_late` is nearly unchanged
-(0.247 → 0.258), which is expected because the fog is tuned around the
-entrance.
-
-Capture command:
-
-```bash
-cp packaging/desktop_hq/override.cfg ./override.cfg
-xvfb-run -a godot --path . --script res://src/test/capture_realism.gd -- \
-  --stages=late --flashlight \
-  --out=res://docs/screens/realism/2026-11-01-forward-plus/candidate
-rm override.cfg
-```
-
-The vision judge could not run because `OPENROUTER_API_KEY` is invalid; the
-retry is recorded in `TODO.md`.

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

@@ -1,134 +0,0 @@
-{
-  "run": "docs/screens/realism/2026-11-01-gear-judge",
-  "judge_model": "google/gemini-2.5-flash-lite",
-  "sets": {
-    "baseline": {
-      "npc_portrait": {
-        "target": "docs/screens/concepts/npc_portrait_day.png",
-        "metrics": {
-          "edge_density": 24.42,
-          "fine_detail": 9.88,
-          "contrast": 43.77,
-          "saturation_mean": 90.21,
-          "colour_spread": 50.11
-        },
-        "target_metrics": {
-          "edge_density": 7.47,
-          "fine_detail": 3.47,
-          "contrast": 52.66,
-          "saturation_mean": 93.44,
-          "colour_spread": 54.88
-        },
-        "metric_gap": 1.093,
-        "judge": {
-          "scores": {
-            "backdrop": 4.0,
-            "lighting": 3.0,
-            "overall": 2.0,
-            "materials": 2.0,
-            "texture_detail": 1.0,
-            "characters": 1.0
-          },
-          "score_range": {
-            "backdrop": [
-              4.0,
-              4.0
-            ],
-            "lighting": [
-              3.0,
-              3.0
-            ],
-            "overall": [
-              2.0,
-              2.0
-            ],
-            "materials": [
-              2.0,
-              2.0
-            ],
-            "texture_detail": [
-              1.0,
-              1.0
-            ],
-            "characters": [
-              1.0,
-              1.0
-            ]
-          },
-          "runs": 1,
-          "fixes": [
-            "Improve character model realism with more detailed facial features, realistic skin shaders, and better clothing textures.",
-            "Enhance material properties for all objects, especially the brick building and pavement, to better simulate real-world reflectivity, roughness, and subsurface scattering.",
-            "Increase texture resolution and detail for all assets, particularly for the brickwork, pavement, and character clothing, to reduce the appearance of tiling and blurriness.",
-            "Refine lighting to match the warm, directional sunlight and soft shadows of the target image, paying attention to ambient occlusion and global illumination.",
-            "Add atmospheric perspective and volumetric fog to the backdrop to create a sense of depth and distance, mimicking the haze seen in the target image."
-          ]
-        }
-      }
-    },
-    "candidate": {
-      "npc_portrait": {
-        "target": "docs/screens/concepts/npc_portrait_day.png",
-        "metrics": {
-          "edge_density": 24.43,
-          "fine_detail": 9.89,
-          "contrast": 43.74,
-          "saturation_mean": 90.17,
-          "colour_spread": 50.08
-        },
-        "target_metrics": {
-          "edge_density": 7.47,
-          "fine_detail": 3.47,
-          "contrast": 52.66,
-          "saturation_mean": 93.44,
-          "colour_spread": 54.88
-        },
-        "metric_gap": 1.094,
-        "judge": {
-          "scores": {
-            "backdrop": 5.0,
-            "lighting": 4.0,
-            "overall": 3.0,
-            "materials": 3.0,
-            "texture_detail": 2.0,
-            "characters": 2.0
-          },
-          "score_range": {
-            "backdrop": [
-              5.0,
-              5.0
-            ],
-            "lighting": [
-              4.0,
-              4.0
-            ],
-            "overall": [
-              3.0,
-              3.0
-            ],
-            "materials": [
-              3.0,
-              3.0
-            ],
-            "texture_detail": [
-              2.0,
-              2.0
-            ],
-            "characters": [
-              2.0,
-              2.0
-            ]
-          },
-          "runs": 1,
-          "fixes": [
-            "Improve character model realism with more detailed facial features, realistic skin shaders, and better hair simulation.",
-            "Enhance material properties for clothing, pavement, and buildings to include subsurface scattering, anisotropic reflections, and more varied roughness maps.",
-            "Increase texture resolution and add micro-detail (e.g., pores, fabric weave, concrete imperfections) to all surfaces.",
-            "Implement more sophisticated global illumination and atmospheric scattering for a softer, more realistic lighting and haze effect.",
-            "Refine the backdrop by adding more complex building geometry, varied foliage, and realistic distant city details with appropriate atmospheric perspective."
-          ]
-        }
-      }
-    }
-  }
-}

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

@@ -1,55 +0,0 @@
-# Gear fit report: `docs/screens/realism/2026-11-01-gear`
-
-Influencer (`npc_coat`) portrait, forced with `--portrait-type=2`, before the gear-fit
-changes (`da876e3`, with the capture yaw/focus fixes backported) and after them (`a478bfb`).
-Both frames use the same camera, sun and portrait staging. The focus disc is hidden because
-it is a gameplay overlay, not part of the character still.
-
-| measurement | before | after |
-| --- | --- | --- |
-| sunglasses width | 0.282 m (0.90× head) | **0.202 m** (0.64× head) |
-| bag body inner face | 0.168 m (coat skirt 0.225, dress 0.260) | **0.262 m** (clears both) |
-| firefighter helmet brim | sat on the brow ridge | **raised 2 cm** |
-
-Capture commands:
-
-```
-xvfb-run -a godot --path . --script res://src/test/capture_realism.gd -- \
-  --stages=portrait --portrait-type=2 \
-  --out=res://docs/screens/realism/2026-11-01-gear/candidate-v2
-tools/check_screenshots.sh   # 11 good / 0 bad
-python3 tools/scene_concepts.py realism \
-  --run docs/screens/realism/2026-11-01-gear --judge
-```
-
-The judge improved the portrait from **overall 2 / characters 1** (baseline) to
-**overall 3 / characters 2** (candidate); the remaining fixes are the broader realism
-targets (skin/cloth shaders, GI, backdrop haze), not gear fit.
-
-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 | npc_portrait | npc_portrait_day | 1.093 | 24.42 | 9.88 | 43.77 | 2.0 | 3.0 | 2.0 | 1.0 | 4.0 |
-| candidate | npc_portrait | npc_portrait_day | 1.094 | 24.43 | 9.89 | 43.74 | 3.0 | 4.0 | 3.0 | 2.0 | 5.0 |
-
-Mean scores per set (all captured shots):
-
-| set | shots | gap ↓ | overall | lighting | materials | texture_detail | backdrop | characters |
-| --- | --- | --- | --- | --- | --- | --- | --- | --- |
-| baseline | 1 | 1.093 | 2.0 | 3.0 | 2.0 | 1.0 | 4.0 | 1.0 |
-| candidate | 1 | 1.094 | 3.0 | 4.0 | 3.0 | 2.0 | 5.0 | 2.0 |
-
-**baseline / npc_portrait** fixes:
-- Improve character model realism with more detailed facial features, realistic skin shaders, and better clothing textures.
-- Enhance material properties for all objects, especially the brick building and pavement, to better simulate real-world reflectivity, roughness, and subsurface scattering.
-- Increase texture resolution and detail for all assets, particularly for the brickwork, pavement, and character clothing, to reduce the appearance of tiling and blurriness.
-- Refine lighting to match the warm, directional sunlight and soft shadows of the target image, paying attention to ambient occlusion and global illumination.
-- Add atmospheric perspective and volumetric fog to the backdrop to create a sense of depth and distance, mimicking the haze seen in the target image.
-
-**candidate / npc_portrait** fixes:
-- Improve character model realism with more detailed facial features, realistic skin shaders, and better hair simulation.
-- Enhance material properties for clothing, pavement, and buildings to include subsurface scattering, anisotropic reflections, and more varied roughness maps.
-- Increase texture resolution and add micro-detail (e.g., pores, fabric weave, concrete imperfections) to all surfaces.
-- Implement more sophisticated global illumination and atmospheric scattering for a softer, more realistic lighting and haze effect.
-- Refine the backdrop by adding more complex building geometry, varied foliage, and realistic distant city details with appropriate atmospheric perspective.

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

@@ -1,171 +0,0 @@
-# Realism report: `docs/screens/realism/2026-11-01-npc`
-
-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 |
-| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
-| after | boulevard_day | boulevard_skyline_day | 0.168 | 23.78 | 9.03 | 40.34 | 3.0 | 4.0 | 3.0 | 3.0 | 6.0 |
-| after | boulevard_night | hollywood_entrance_rain_night | 0.728 | 16.21 | 7.16 | 38.99 | 2.0 | 3.0 | 2.0 | 2.0 | 4.0 |
-| after | entrance_day | hollywood_entrance_morning | 0.457 | 27.12 | 10.33 | 43.1 | 3.0 | 4.0 | 3.0 | 3.0 | 3.0 |
-| after | entrance_late | hollywood_entrance_rain_night | 1.134 | 18.8 | 8.52 | 52.15 | 2.0 | 3.0 | 2.0 | 2.0 | 1.0 |
-| after | joke_shop_door | joke_shop_door_closeup | 0.864 | 15.4 | 7.24 | 48.56 | 2.0 | 3.0 | 4.0 | 3.0 | 2.0 |
-| after | npc_portrait | npc_portrait_day | 1.108 | 24.87 | 9.87 | 43.79 | 3.0 | 4.0 | 3.0 | 3.0 | 5.0 |
-| after | street_day | boulevard_skyline_day | 0.119 | 19.96 | 7.55 | 43.9 | 2.0 | 3.0 | 2.0 | 2.0 | 4.0 |
-| after | street_late | boulevard_skyline_dusk | 0.273 | 13.81 | 6.73 | 33.25 | 2.0 | 3.0 | 2.0 | 2.0 | 4.0 |
-| after | street_night | boulevard_skyline_dusk | 0.308 | 12.51 | 6.14 | 25.49 | 2.0 | 3.0 | 2.0 | 2.0 | 3.0 |
-| after | studio_door | studio_stage_door_night | 0.433 | 17.21 | 7.97 | 49.17 | 2.0 | 3.0 | 2.0 | 2.0 | 1.0 |
-| before | boulevard_day | boulevard_skyline_day | 0.172 | 23.21 | 8.88 | 38.78 | 2.0 | 3.0 | 2.0 | 2.0 | 5.0 |
-| before | boulevard_night | hollywood_entrance_rain_night | 0.723 | 16.02 | 7.13 | 39.4 | 2.0 | 3.0 | 2.0 | 2.0 | 4.0 |
-| before | entrance_day | hollywood_entrance_morning | 0.442 | 25.88 | 9.86 | 40.18 | 2.0 | 3.0 | 2.0 | 2.0 | 3.0 |
-| before | entrance_late | hollywood_entrance_rain_night | 1.105 | 18.4 | 8.41 | 51.61 | 2.0 | 3.0 | 2.0 | 2.0 | 3.0 |
-| before | joke_shop_door | joke_shop_door_closeup | 0.818 | 14.84 | 7.04 | 47.63 | 3.0 | 3.0 | 4.0 | 3.0 | 5.0 |
-| before | street_day | boulevard_skyline_day | 0.148 | 18.69 | 7.42 | 42.69 | 2.0 | 3.0 | 2.0 | 2.0 | 4.0 |
-| before | street_late | boulevard_skyline_dusk | 0.224 | 12.95 | 6.27 | 31.94 | 2.0 | 3.0 | 2.0 | 2.0 | 4.0 |
-| before | street_night | boulevard_skyline_dusk | 0.253 | 10.97 | 5.57 | 24.27 | 2.0 | 3.0 | 2.0 | 2.0 | 4.0 |
-| before | studio_door | studio_stage_door_night | 0.395 | 16.62 | 7.65 | 48.52 | 2.0 | 3.0 | 2.0 | 2.0 | 1.0 |
-
-Mean scores per set (all captured shots):
-
-| set | shots | gap ↓ | overall | lighting | materials | texture_detail | backdrop | characters |
-| --- | --- | --- | --- | --- | --- | --- | --- | --- |
-| after | 10 | 0.559 | 2.3 | 3.3 | 2.5 | 2.4 | 3.3 | 2.2 |
-| before | 9 | 0.476 | 2.11 | 3.0 | 2.22 | 2.11 | 3.67 | 2.33 |
-
-Mean over the shots every set captured (like for like):
-
-| set | shots | gap ↓ | overall | lighting | materials | texture_detail | backdrop | characters |
-| --- | --- | --- | --- | --- | --- | --- | --- | --- |
-| after | 9 | 0.498 | 2.22 | 3.22 | 2.44 | 2.33 | 3.11 | 2.22 |
-
-**after / boulevard_day** fixes:
-- Improve the lighting model to better simulate global illumination and soft shadows, especially for the sky and ambient light.
-- Increase the polygon count and add normal maps to the trees and foliage to give them a more organic and detailed appearance.
-- Replace the current brick material with a more detailed texture that includes variations in color, mortar lines, and subtle imperfections.
-- Add more complex geometry and finer details to the buildings in the background, such as windows, balconies, and architectural elements, to match the target's complexity.
-- Implement a more sophisticated atmospheric perspective effect for the distant cityscape to create a greater sense of depth and realism.
-
-**after / boulevard_night** fixes:
-- Improve the lighting to be more atmospheric and volumetric, with softer shadows and more realistic reflections on wet surfaces.
-- Enhance material properties for brick, pavement, and building facades to include more subtle variations, specularity, and roughness.
-- Increase texture detail on all surfaces, especially the brickwork, pavement, and character models, to reduce the 'plastic' look.
-- Redesign character models to be more anatomically correct and detailed, with better clothing textures and facial features.
-- Add more subtle environmental details like rain streaks, puddles with ripples, and more varied foliage to enhance realism.
-
-**after / entrance_day** fixes:
-- Improve brick texture and material to add more variation, grime, and imperfections.
-- Add atmospheric perspective and volumetric fog to the background to create depth and match the target's hazy distance.
-- Enhance lighting to include softer shadows, more subtle ambient occlusion, and realistic light falloff, especially around the marquee lights.
-- Replace low-polygon trees with more detailed models that have varied leaf textures and shapes.
-- Add subtle surface imperfections and wear to the concrete sidewalk and steps.
-
-**after / entrance_late** fixes:
-- Improve the lighting to match the dramatic, atmospheric, and volumetric lighting of the target image. Focus on warm, directional light from the marquee and street lamp, with soft ambient occlusion and reflections.
-- Enhance material properties for realism. The brickwork, pavement, and building facade in the capture are too flat and lack subsurface scattering or specular highlights. The target image shows wet, reflective surfaces with subtle variations in material.
-- Increase texture detail significantly. The brick textures are low-resolution and repetitive. The target image features high-resolution, varied brick patterns with grime and weathering.
-- Redesign the backdrop to include a distant city skyline with atmospheric perspective (haze) and more detailed building structures, similar to the target image.
-- Refine the character model and its integration into the scene. The character in the capture is low-poly and appears out of place. The target image's character has more realistic proportions, clothing detail, and is better lit to blend with the environment.
-
-**after / joke_shop_door** fixes:
-- Improve brick texture and material properties to match the target's depth and roughness.
-- Enhance the lighting to create softer, more volumetric shadows and a warmer glow from the lamp.
-- Add more detail to the building facade, such as subtle variations in brick color and mortar.
-- Introduce atmospheric perspective and haze to the distant cityscape to create a sense of depth.
-- Significantly increase the polygon count and detail of the character model to match the target's realism.
-
-**after / npc_portrait** fixes:
-- Improve character model realism: Focus on facial features, skin texture, and clothing wrinkles to match the target's detail and natural appearance.
-- Enhance material properties: Make brick, pavement, and clothing materials more realistic with better specular highlights, subsurface scattering, and wear/tear details.
-- Refine lighting: Mimic the warm, directional lighting of the target, paying attention to soft shadows and rim lighting on the character.
-- Increase texture detail: Apply higher resolution and more nuanced textures to all surfaces, especially the character's skin and clothing, and the brickwork.
-- Adjust backdrop realism: Add atmospheric perspective (haze) to the distant city skyline and improve the detail and lighting of the palm trees to match the target.
-
-**after / street_day** fixes:
-- Improve road material to have more subtle variations in color and reflectivity, and add tire marks and debris.
-- Enhance building textures with more detailed facades, windows, and architectural elements. Add subtle weathering and grime.
-- Increase the density and variety of vegetation, ensuring realistic palm tree models and ground cover.
-- Refine lighting to create softer shadows, more atmospheric scattering, and realistic specular highlights on surfaces.
-- Add atmospheric perspective to the distant cityscape with appropriate haze and color grading to simulate distance.
-
-**after / street_late** fixes:
-- Improve the lighting to match the warm, atmospheric glow of the target image, paying close attention to the neon signs and streetlights.
-- 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 detail on all surfaces, especially the road and building facades, to add depth and realism.
-- Refine the backdrop, particularly the city skyline and atmospheric haze, to create a more convincing sense of distance and depth.
-- Significantly improve character models and their integration into the scene, as they currently appear very low-fidelity and out of place.
-
-**after / street_night** fixes:
-- Improve lighting to match the warm, atmospheric glow of the target, especially the neon signs and streetlights.
-- Increase the detail and realism of building materials and textures, adding grime, wear, and more complex architectural features.
-- Enhance the texture detail on the road surface, palm trees, and vehicles to be less uniform and more photorealistic.
-- Refine the backdrop, adding atmospheric haze and more detailed city silhouettes that mimic the depth and complexity of the target.
-- Significantly improve character models and animations to match the realistic style of the target image.
-
-**after / studio_door** fixes:
-- Improve the lighting to match the dramatic, moody atmosphere of the target, focusing on soft, volumetric light and realistic reflections.
-- Enhance material properties for the building facade, car, and pavement to achieve a more realistic look with appropriate specularity, roughness, and subsurface scattering.
-- Increase texture detail on all surfaces, especially the brickwork, stone, and car paint, to add fine details and imperfections.
-- Add atmospheric effects like fog or haze to the backdrop to create depth and a sense of distance, similar to the target image.
-- Significantly improve character models and their integration into the scene, paying attention to detail, lighting, and animation.
-
-**before / boulevard_day** fixes:
-- Improve road and sidewalk materials to have more realistic roughness and subtle variations.
-- Add significantly more geometric detail and realistic textures to buildings, especially the brickwork.
-- Replace low-polygon trees and foliage with more detailed and varied models, and add more natural scattering.
-- Enhance lighting to include softer shadows, more realistic ambient occlusion, and subtle specular highlights on surfaces.
-- Implement atmospheric perspective for the distant cityscape to create a sense of depth and haze.
-
-**before / 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 street lamp, with realistic reflections on wet surfaces.
-- Enhance material properties to achieve a more realistic look, particularly for the brickwork, pavement, and building facade, incorporating subtle imperfections, wear, and specular highlights that react realistically to light.
-- Increase texture detail significantly across all assets, especially the brick walls, pavement, and character models, to add depth, realism, and a sense of age and grit.
-- Redesign character models to be more anatomically correct and detailed, with realistic clothing textures and subtle animations that convey a sense of life and presence.
-- Refine the backdrop to include more atmospheric elements like fog, rain effects, and a more detailed, less stylized cityscape with appropriate haze for distance.
-
-**before / entrance_day** fixes:
-- Improve brick texture and material properties to add more variation, grime, and imperfections.
-- Enhance lighting to create softer shadows, more atmospheric volumetric light, and a warmer, more natural color temperature.
-- Add more detailed geometry and textures to the building facade, windows, and surrounding elements like trees and planters.
-- Introduce atmospheric perspective and fog to the distant cityscape to create a sense of depth and realism.
-- Replace low-polygon trees with more detailed models and textures that better match the target's style.
-
-**before / entrance_late** fixes:
-- Improve the lighting to be more atmospheric and volumetric, with softer shadows and more realistic light falloff, especially around the marquee and streetlights.
-- Enhance material properties for brick, pavement, and building facades to include realistic reflections, specularity, and subsurface scattering where appropriate.
-- Increase texture resolution and detail for all surfaces, particularly the brickwork, to reduce the appearance of tiling and blurriness.
-- Add more complex geometry and detail to the backdrop buildings and sky, including atmospheric perspective and subtle variations in color and light.
-- Refine character models with more detailed clothing, facial features (if visible), and more natural posing to match the realistic aesthetic.
-
-**before / joke_shop_door** fixes:
-- Improve brick texture and normal mapping to match the target's depth and roughness.
-- Enhance the lighting to create softer, more volumetric shadows and a warmer glow from the lamp.
-- Add more detail to the door material, including wood grain and subtle imperfections.
-- Refine the sign's material and lighting to appear less flat and more integrated with the environment.
-- Significantly improve character models to achieve a realistic appearance, focusing on form, texture, and animation.
-
-**before / street_day** fixes:
-- Improve road material to have more micro-details, reflections, and wear.
-- Add atmospheric perspective and volumetric fog to the distant cityscape to match the target's depth.
-- Enhance building materials with more varied textures, specular highlights, and subtle imperfections.
-- Increase the polygon count and texture resolution for the car model, paying attention to reflections and material properties.
-- Implement more realistic lighting with softer shadows, global illumination, and subtle color grading to mimic natural sunlight.
-
-**before / street_late** fixes:
-- Improve the lighting to match the warm, atmospheric glow of the target image, paying attention to the neon signs and streetlights.
-- Enhance material properties for buildings, road, and car to achieve a more realistic sheen and surface detail, especially reflections.
-- Increase texture resolution and detail on all surfaces, particularly the road and building facades, to mimic the fine grain and imperfections of the target.
-- Develop a more detailed and atmospheric backdrop, including a richer sky gradient and more nuanced city skyline with atmospheric perspective.
-- Significantly improve character models and their integration into the scene, as they are currently very basic and unrealistic.
-
-**before / street_night** fixes:
-- Improve lighting to match the warm, atmospheric glow of neon signs and streetlights in the target image, with more volumetric effects and softer shadows.
-- Enhance material properties to achieve a more realistic sheen and reflectivity on surfaces like the road, buildings, and car, especially under the artificial lights.
-- Increase texture detail on buildings, road surfaces, and palm trees to add grit, imperfections, and finer details that are present in the target image.
-- Add atmospheric perspective and haze to the distant cityscape and sky to create a sense of depth and realism, similar to the target image.
-- Significantly improve character models and their integration into the scene, as they are currently very basic and detract from realism.
-
-**before / studio_door** fixes:
-- Improve the lighting to match the dramatic, moody, and volumetric feel of the target image. Focus on soft, warm light sources and atmospheric fog.
-- Enhance material properties for the building facade, stairs, and car to achieve a more realistic PBR (Physically Based Rendering) look, with appropriate reflections and surface imperfections.
-- Increase texture detail on all surfaces, especially the brickwork and stone, to add grit, wear, and finer details that are present in the target.
-- Redesign the backdrop to include atmospheric haze and a more distant, less defined background, similar to the target image's sense of depth and mood.
-- Significantly improve character models and their rendering to match the realistic style and subtle details of the people in the target image.

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/tutorial.md

@@ -0,0 +1,45 @@
+# First-shift tutorial
+
+Status: planned 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.
+
+## 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. Completion and skip are both persisted
+  separately; a skipped tutorial can be replayed from Help/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.

project.godot

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

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:
+	if event is InputEventMouseMotion:
-		rotate_y(-event.relative.x * look_sensitivity)
+		if Input.get_mouse_mode() != Input.MOUSE_MODE_CAPTURED:
-		var pitch_sign := 1.0 if invert_y else -1.0
+			return
-		head.rotate_x(pitch_sign * event.relative.y * look_sensitivity)
+		_apply_mouse_look(event.relative)
-		head.rotation.x = clampf(head.rotation.x, deg_to_rad(-80.0), deg_to_rad(80.0))
+		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/tutorial.gd

@@ -0,0 +1,118 @@
+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": "Walk forward and look around. The entrance is behind you.",
+		"event": "moved",
+	},
+	{
+		"id": "focus",
+		"prompt": "Look at the visitor. Press Tab or the mouse wheel to cycle targets.",
+		"event": "cycled",
+	},
+	{
+		"id": "wheel",
+		"prompt": "Open the action wheel with Space or left click.",
+		"event": "wheel_opened",
+	},
+	{
+		"id": "inspect",
+		"prompt": "Choose Inspect and read the access evidence.",
+		"event": "inspected",
+	},
+	{
+		"id": "direction",
+		"prompt": "Close the panel and give a polite direction.",
+		"event": "polite_direction",
+	},
+	{
+		"id": "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": "Open the assistance radio and submit a short report.",
+		"event": "radio_submitted",
+	},
+	{
+		"id": "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/hud.gd

@@ -356,6 +356,17 @@ func _init() -> void:
 	debug_label.add_theme_font_size_override("font_size", 11)
 	debug_label.autowrap_mode = TextServer.AUTOWRAP_WORD_SMART
 	add_child(debug_label)
+	_ignore_mouse(self)
+
+## HUD controls are presentation-only. Leaving the full-screen containers on the
+## default MOUSE_FILTER_STOP can swallow mouse motion/buttons before the guard's
+## captured-look input sees them. Make every non-gameplay HUD control inert to
+## the mouse; modal menus are separate CanvasLayers and keep their own filters.
+func _ignore_mouse(node: Node) -> void:
+	for child in node.get_children():
+		if child is Control:
+			(child as Control).mouse_filter = Control.MOUSE_FILTER_IGNORE
+		_ignore_mouse(child)
 
 func set_shift_state(coordinator: Object, scenario: Resource) -> void:
 	top_label.text = scenario.display_name if scenario else "Gig Line"

src/test/tests/test_guard_input.gd

@@ -0,0 +1,38 @@
+extends RefCounted
+## Regression tests for the first-person mouse-look path and non-blocking HUD.
+
+const GameManager := preload("res://src/game/game_manager.gd")
+const GuardController := preload("res://src/game/guard_controller.gd")
+const Hud := preload("res://src/game/ui/hud.gd")
+
+func test_mouse_look_rotates_yaw_and_pitch() -> bool:
+	var root := Node3D.new()
+	var gm: Node = GameManager.new()
+	var guard: GuardController = gm.call("_build_guard")
+	guard._ready()
+	var yaw0 := guard.rotation.y
+	var pitch0 := guard.head.rotation.x
+	guard._apply_mouse_look(Vector2(100, 50))
+	var a := TestUtils.check(guard.rotation.y < yaw0 - 0.1, "horizontal motion yaws the guard")
+	var b := TestUtils.check(guard.head.rotation.x < pitch0 - 0.1, "vertical motion pitches the head")
+	guard._apply_mouse_look(Vector2(0, 100000))
+	var c := TestUtils.check(absf(rad_to_deg(guard.head.rotation.x)) <= 80.01,
+		"pitch stays clamped")
+	guard.free()
+	gm.free()
+	root.free()
+	return a and b and c
+
+func test_hud_does_not_capture_mouse_input() -> bool:
+	var hud: Hud = Hud.new()
+	var root := hud.get_child(0) as Control
+	var a := TestUtils.check(root != null and root.mouse_filter == Control.MOUSE_FILTER_IGNORE,
+		"full-screen HUD root ignores mouse input")
+	var labels := hud.find_children("*", "Label", true, false)
+	var blocking := 0
+	for node in labels:
+		if (node as Control).mouse_filter != Control.MOUSE_FILTER_IGNORE:
+			blocking += 1
+	var b := TestUtils.check(blocking == 0, "HUD labels do not swallow mouse motion")
+	hud.free()
+	return a and b

src/test/tests/test_tutorial.gd

@@ -0,0 +1,49 @@
+extends RefCounted
+## Deterministic headless tests for the first-shift tutorial state machine.
+
+const Tutorial := preload("res://src/game/tutorial.gd")
+
+func test_tutorial_advances_only_on_the_expected_action() -> bool:
+	var tutorial := Tutorial.new()
+	tutorial.start()
+	var a := TestUtils.check(tutorial.current()["id"] == "arrive", "starts at arrival")
+	var b := TestUtils.check(not tutorial.advance("wheel_opened"), "wrong action is ignored")
+	var c := TestUtils.check(tutorial.advance("moved"), "movement advances")
+	var d := TestUtils.check(tutorial.current()["id"] == "focus", "moves to focus")
+	var e := TestUtils.check(tutorial.advance("cycled"), "target cycling advances")
+	var f := TestUtils.check(tutorial.current()["id"] == "wheel", "moves to the action wheel")
+	return a and b and c and d and e and f
+
+func test_tutorial_runs_all_beats_and_completes() -> bool:
+	var tutorial := Tutorial.new()
+	tutorial.start()
+	var events := ["moved", "cycled", "wheel_opened", "inspected",
+		"polite_direction", "formal_warning", "radio_submitted", "review_opened"]
+	var ok := true
+	for event in events:
+		ok = ok and tutorial.advance(event)
+	ok = ok and tutorial.is_complete()
+	ok = ok and not tutorial.is_skipped()
+	ok = ok and tutorial.progress() == Vector2i(Tutorial.BEATS.size(), Tutorial.BEATS.size())
+	return TestUtils.check(ok, "all eight beats complete in order")
+
+func test_tutorial_accepts_body_camera_for_warning() -> bool:
+	var tutorial := Tutorial.new()
+	tutorial.start()
+	for event in ["moved", "cycled", "wheel_opened", "inspected", "polite_direction"]:
+		tutorial.advance(event)
+	var a := TestUtils.check(tutorial.advance("body_camera"), "body camera satisfies warning")
+	var b := TestUtils.check(tutorial.current()["id"] == "radio", "advances to radio")
+	return a and b
+
+func test_tutorial_skip_and_restart() -> bool:
+	var tutorial := Tutorial.new()
+	tutorial.start()
+	var a := TestUtils.check(tutorial.advance("moved"), "one beat completed")
+	tutorial.skip()
+	var b := TestUtils.check(tutorial.is_complete() and tutorial.is_skipped(), "skip completes tutorial")
+	var c := TestUtils.check(not tutorial.advance("moved"), "completed tutorial is inert")
+	tutorial.restart()
+	var d := TestUtils.check(not tutorial.is_complete() and not tutorial.is_skipped(), "restart clears flags")
+	var e := TestUtils.check(tutorial.current()["id"] == "arrive", "restart returns to beat one")
+	return a and b and c and d and e

tools/npc_pipeline.py

@@ -16,7 +16,7 @@ path must be absolute):
     python3 tools/npc_pipeline.py palette   # derive outfit colours -> palette.json
     python3 tools/npc_pipeline.py audit
 
-Contract (frozen in docs/plan-graphics-v0.6.md + ADR-0013):
+Contract (frozen in ADR-0013 and docs/blender-assets.md):
 
   * scene root "Rig" with a skinned mesh and an armature
   * bones: Head, HipL/R, KneeL/R, ShoulderL/R, ElbowL/R, HandL/R

tools/openrouter_judge.py

@@ -0,0 +1,127 @@
+"""Pick affordable OpenRouter vision models for the screenshot judges.
+
+The model catalogue is fetched from OpenRouter (no auth needed) and filtered to
+models that accept image input and advertise `response_format`/structured output.
+The ranking uses the advertised per-token prices, so it follows the account's
+current catalogue instead of relying on one hard-coded model name. If the
+catalogue cannot be fetched, a small known-good list keeps QA working offline.
+"""
+
+from __future__ import annotations
+
+import os
+import urllib.error
+import urllib.request
+
+MODELS_URL = "https://openrouter.ai/api/v1/models"
+DEFAULT_MODEL = "auto"
+
+# Used only when the catalogue is unavailable. Ordered by price/known quality.
+FALLBACK_MODELS = [
+    "z-ai/glm-5.3-flash",
+    "qwen/qwen3.7-flash",
+    "google/gemma-3-4b-it",
+    "openai/gpt-4.1-nano",
+    "google/gemini-2.5-flash-lite",
+]
+
+
+def fetch_models(timeout: int = 30) -> list[dict]:
+    """Return the OpenRouter model catalogue, or [] when it is unreachable."""
+    req = urllib.request.Request(MODELS_URL, headers={"Accept": "application/json"})
+    try:
+        with urllib.request.urlopen(req, timeout=timeout) as resp:
+            payload = __import__("json").loads(resp.read().decode("utf-8"))
+    except (OSError, ValueError, urllib.error.HTTPError):
+        return []
+    return list(payload.get("data") or [])
+
+
+def _price(model: dict) -> float:
+    pricing = model.get("pricing") or {}
+    try:
+        prompt = float(pricing.get("prompt") or 0.0)
+        completion = float(pricing.get("completion") or 0.0)
+        image = float(pricing.get("image") or 0.0)
+    except (TypeError, ValueError):
+        return float("inf")
+    # A judge request is image-heavy and emits a short JSON verdict.
+    return prompt + image + completion * 0.25
+
+
+def vision_candidates(catalog: list[dict], limit: int = 6) -> list[str]:
+    """Cheap, image-capable models that can return structured JSON."""
+    ranked: list[tuple[float, str]] = []
+    for model in catalog:
+        model_id = str(model.get("id") or "")
+        if not model_id or model_id.startswith("~") or ":batch" in model_id:
+            continue
+        architecture = model.get("architecture") or {}
+        inputs = architecture.get("input_modalities") or []
+        outputs = architecture.get("output_modalities") or []
+        if "image" not in inputs or "text" not in outputs:
+            continue
+        params = model.get("supported_parameters") or []
+        # Our request uses response_format={"type": "json_object"}; models that
+        # only advertise structured_outputs may reject that envelope.
+        if "response_format" not in params:
+            continue
+        price = _price(model)
+        if price <= 0.0 or price == float("inf"):
+            continue
+        ranked.append((price, model_id))
+    ranked.sort()
+    out: list[str] = []
+    for _price_value, model_id in ranked:
+        if model_id not in out:
+            out.append(model_id)
+        if len(out) >= max(1, limit):
+            break
+    return out
+
+
+def resolve_models(requested: str = DEFAULT_MODEL, *, catalog: list[dict] | None = None,
+                   limit: int = 6) -> list[str]:
+    """Resolve ``auto``/an explicit model to a fallback-ordered model list.
+
+    `GIG_LINE_JUDGE_MODEL` overrides the automatic choice for reproducible runs;
+    an explicit CLI `--model` still wins.
+    """
+    requested = str(requested or "").strip()
+    if requested and requested != DEFAULT_MODEL:
+        return [requested]
+    env_model = os.environ.get("GIG_LINE_JUDGE_MODEL", "").strip()
+    if env_model:
+        return [env_model]
+    models = vision_candidates(catalog if catalog is not None else fetch_models(), limit)
+    if not models:
+        models = FALLBACK_MODELS[:max(1, limit)]
+    return models
+
+
+def is_auth_error(exc: BaseException) -> bool:
+    text = str(exc)
+    return "HTTP 401" in text or "HTTP 403" in text or "API key not valid" in text
+
+
+def call_with_fallback(models: list[str], make_body, call, attempts: int = 2):
+    """Try each model, retrying provider errors, and return (model, response).
+
+    Authentication errors abort immediately: switching models cannot repair a
+    bad key. Model/provider errors move to the next candidate.
+    """
+    last: BaseException | None = None
+    for model in models:
+        body = make_body(model)
+        for attempt in range(max(1, attempts)):
+            try:
+                return model, call(body)
+            except (ValueError, OSError) as exc:
+                last = exc
+                if is_auth_error(exc):
+                    raise
+                if attempt + 1 >= max(1, attempts):
+                    break
+    if last is not None:
+        raise last
+    raise ValueError("no judge model was available")

tools/scene_concepts.py

@@ -38,6 +38,7 @@ from PIL import Image, ImageFilter, ImageOps, ImageStat
 
 import asset_pipeline
 import generate_textures
+import openrouter_judge
 
 ROOT = Path(__file__).resolve().parent.parent
 RAW_DIR = ROOT / "assets" / "textures" / "ai" / "v2" / "raw"
@@ -46,7 +47,7 @@ CONCEPT_DIR = ROOT / "docs" / "screens" / "concepts"
 REALISM_DIR = ROOT / "docs" / "screens" / "realism"
 
 DEFAULT_MODEL = "openai/gpt-5-image-mini"
-DEFAULT_JUDGE_MODEL = "google/gemini-2.5-flash-lite"
+DEFAULT_JUDGE_MODEL = openrouter_judge.DEFAULT_MODEL
 OPENROUTER_CHAT_URL = "https://openrouter.ai/api/v1/chat/completions"
 
 SCENE_W, SCENE_H = 1280, 720
@@ -758,25 +759,32 @@ def _call_openrouter(body: dict, timeout: int = 180) -> dict:
         raise ValueError(f"OpenRouter HTTP {exc.code}: {exc.read().decode('utf-8', 'replace')[:300]}")
 
 
-def judge_capture(model: str, target: Path, capture: Path, attempts: int = 2,
+def judge_capture(models, target: Path, capture: Path, attempts: int = 2,
                   repeats: int = 1) -> dict:
     """Vision-judge one capture; retry transient errors, average repeat scores.
 
+    `models` is a fallback-ordered list from `openrouter_judge.resolve_models`.
     A single score from a small vision model swings by ±1-2, so `repeats` runs
     are averaged and the spread is kept (`score_range`) for the report.
     """
+    if isinstance(models, str):
+        models = [models]
     runs = []
     error = None
+    used = set()
     for _ in range(max(1, repeats)):
-        for _attempt in range(attempts):
+        try:
-            try:
+            model, payload = openrouter_judge.call_with_fallback(
-                runs.append(parse_realism_response(_call_openrouter(
+                models, lambda selected: build_realism_request(selected, target, capture),
-                    build_realism_request(model, target, capture))))
+                _call_openrouter, attempts=attempts)
-                break
+            used.add(model)
-            except (ValueError, OSError) as exc:
+            runs.append(parse_realism_response(payload))
-                error = exc
+        except (ValueError, OSError) as exc:
+            if openrouter_judge.is_auth_error(exc):
+                raise
+            error = exc
     if not runs:
-        return {"scores": {}, "fixes": [f"judge failed: {error}"]}
+        return {"scores": {}, "fixes": [f"judge failed: {error}"], "model": ""}
     keys = {key for run in runs for key in run["scores"]}
     scores = {}
     spread = {}
@@ -790,7 +798,7 @@ def judge_capture(model: str, target: Path, capture: Path, attempts: int = 2,
             if fix not in fixes:
                 fixes.append(fix)
     return {"scores": scores, "score_range": spread, "runs": len(runs),
-            "fixes": fixes[:5]}
+            "model": ", ".join(sorted(used)), "fixes": fixes[:5]}
 
 
 def cmd_realism(args) -> int:
@@ -800,10 +808,14 @@ def cmd_realism(args) -> int:
     if not sets:
         print(f"no capture sets under {_rel(run)}", file=sys.stderr)
         return 2
+    judge_models = []
     if args.judge:
         _load_env_file()
-    report = {"run": _rel(run), "judge_model": args.model if args.judge else None,
+        judge_models = openrouter_judge.resolve_models(args.model)
-              "sets": {}}
+        print(f"judge models: {', '.join(judge_models)}", file=sys.stderr)
+    report = {"run": _rel(run),
+              "judge_model": (judge_models[0] if judge_models else None),
+              "judge_fallbacks": judge_models, "sets": {}}
     for capture_set in sets:
         rows = {}
         for capture in sorted(capture_set.glob("*.png")):
@@ -815,8 +827,15 @@ def cmd_realism(args) -> int:
             row = {"target": _rel(target), "metrics": cap_m, "target_metrics": tgt_m,
                    "metric_gap": metric_gap(cap_m, tgt_m)}
             if args.judge:
-                row["judge"] = judge_capture(args.model, target, capture,
+                try:
-                                             repeats=args.repeats)
+                    row["judge"] = judge_capture(judge_models, target, capture,
+                                                 repeats=args.repeats)
+                except ValueError as exc:
+                    if openrouter_judge.is_auth_error(exc):
+                        print(f"error: OpenRouter authentication failed: {exc}",
+                              file=sys.stderr)
+                        return 2
+                    raise
             rows[capture.stem] = row
         report["sets"][capture_set.name] = rows
     json_path = next_free_path(run / "report.json")
@@ -975,7 +994,9 @@ def build_parser():
     real = sub.add_parser("realism")
     real.add_argument("--run", required=True)
     real.add_argument("--judge", action="store_true")
-    real.add_argument("--model", default=DEFAULT_JUDGE_MODEL)
+    real.add_argument("--model", default=DEFAULT_JUDGE_MODEL,
+                      help="OpenRouter model id, or 'auto' to pick the cheapest "
+                           "available image+JSON model with fallbacks")
     real.add_argument("--repeats", type=int, default=1,
                       help="average N judge runs per shot (scores are noisy)")
     real.set_defaults(handler=cmd_realism)

tools/screen_designs.py

@@ -51,6 +51,7 @@ from pathlib import Path
 from PIL import Image, ImageChops, ImageDraw, ImageFilter, ImageOps, ImageStat
 
 import generate_textures
+import openrouter_judge
 
 ROOT = Path(__file__).resolve().parent.parent
 ## Runtime reference art (ADR-0014); docs/screens/designs/ is the reference-only
@@ -68,7 +69,7 @@ ASPECT = 16 / 9
 DEFAULT_MODEL = "openai/gpt-5-image-mini"
 
 # Vision model used by `judge`. Cheap, multimodal, and good at "same screen?".
-DEFAULT_JUDGE_MODEL = "google/gemini-2.5-flash-lite"
+DEFAULT_JUDGE_MODEL = openrouter_judge.DEFAULT_MODEL
 OPENROUTER_CHAT_URL = "https://openrouter.ai/api/v1/chat/completions"
 
 # Shared art direction, appended to every prompt so the generated frames read
@@ -965,6 +966,10 @@ def judge(args):
     refs = {screen["name"]: screen["ref"]
             for screen in SCREENS if screen["ref"]}
     by_name = {screen["name"]: screen for screen in SCREENS}
+    models = [args.model]
+    if not args.dry_run:
+        models = openrouter_judge.resolve_models(args.model)
+        print(f"judge models: {', '.join(models)}", file=sys.stderr)
     results = []
     for capture in sorted(SCREENSHOTS_DIR.glob("*.png")):
         if args.only and args.only not in capture.name:
@@ -982,23 +987,36 @@ def judge(args):
                             "match": None, "confidence": 0.0,
                             "differences": ["missing reference design; run generate"]})
             continue
-        body = build_judge_request(args.model, by_name[design_name],
-                                   capture, reference)
         if args.dry_run:
+            body = build_judge_request(args.model, by_name[design_name],
+                                       capture, reference)
             results.append({
                 "capture": capture.name, "screen": design_name, "match": None,
                 "confidence": 0.0, "model": body["model"], "class": "unknown",
                 "differences": [f"dry run: {len(body['messages'][0]['content'])} parts"],
             })
             continue
-        # Providers occasionally answer a valid key with a transient HTTP 400;
-        # one retry keeps a whole judge run from dying on a single hiccup.
         try:
-            verdict = parse_judge_response(_call_openrouter(body))
+            model, payload = openrouter_judge.call_with_fallback(
+                models,
+                lambda selected: build_judge_request(
+                    selected, by_name[design_name], capture, reference),
+                _call_openrouter)
         except ValueError as exc:
-            print(f"retrying {capture.name}: {exc}", file=sys.stderr)
+            if openrouter_judge.is_auth_error(exc):
-            verdict = parse_judge_response(_call_openrouter(body))
+                print(f"error: OpenRouter authentication failed: {exc}",
+                      file=sys.stderr)
+                return 2
+            print(f"error judging {capture.name}: {exc}", file=sys.stderr)
+            results.append({
+                "capture": capture.name, "screen": design_name, "match": None,
+                "confidence": 0.0, "model": "",
+                "class": "unknown", "differences": [f"judge failed: {exc}"],
+            })
+            continue
+        verdict = parse_judge_response(payload)
         verdict.update({"capture": capture.name, "screen": design_name,
+                        "model": model,
                         "class": classify(verdict, args.fail_confidence)})
         results.append(verdict)
 
@@ -1047,7 +1065,9 @@ def build_parser():
 
     judge_cmd = commands.add_parser(
         "judge", help="ask a vision model whether captures match the designs")
-    judge_cmd.add_argument("--model", default=DEFAULT_JUDGE_MODEL)
+    judge_cmd.add_argument("--model", default=DEFAULT_JUDGE_MODEL,
+                           help="OpenRouter model id, or 'auto' to pick the cheapest "
+                                "available image+JSON model with fallbacks")
     judge_cmd.add_argument("--json", action="store_true")
     judge_cmd.add_argument("--dry-run", action="store_true",
                            help="print requests instead of calling the API")

tools/test_openrouter_judge.py

@@ -0,0 +1,89 @@
+import os
+import unittest
+from unittest import mock
+
+import openrouter_judge as oj
+
+
+def _model(model_id, prompt, completion, *, image=True, response_format=True, batch=False):
+    return {
+        "id": model_id,
+        "architecture": {
+            "input_modalities": ["text", "image"] if image else ["text"],
+            "output_modalities": ["text"],
+        },
+        "supported_parameters": ["response_format"] if response_format else ["temperature"],
+        "pricing": {"prompt": str(prompt), "completion": str(completion)},
+    }
+
+
+class ModelSelectionTests(unittest.TestCase):
+    def test_candidates_are_image_json_models_sorted_by_price(self):
+        catalog = [
+            _model("expensive/model", 0.10, 0.40),
+            _model("cheap/model", 0.01, 0.02),
+            _model("text-only", 0.001, 0.001, image=False),
+            _model("no-json", 0.001, 0.001, response_format=False),
+            _model("batch/model:batch", 0.0001, 0.0001),
+        ]
+        self.assertEqual(oj.vision_candidates(catalog), ["cheap/model", "expensive/model"])
+
+    def test_explicit_model_wins_over_auto_and_env(self):
+        with mock.patch.dict(os.environ, {"GIG_LINE_JUDGE_MODEL": "env/model"}):
+            self.assertEqual(oj.resolve_models("explicit/model", catalog=[]),
+                             ["explicit/model"])
+
+    def test_auto_uses_env_override(self):
+        with mock.patch.dict(os.environ, {"GIG_LINE_JUDGE_MODEL": "env/model"}):
+            self.assertEqual(oj.resolve_models("auto", catalog=[]), ["env/model"])
+
+    def test_auto_uses_catalog_and_falls_back_offline(self):
+        catalog = [_model("cheap/model", 0.01, 0.02)]
+        self.assertEqual(oj.resolve_models("auto", catalog=catalog), ["cheap/model"])
+        self.assertEqual(oj.resolve_models("auto", catalog=[]), oj.FALLBACK_MODELS[:6])
+
+
+class FallbackTests(unittest.TestCase):
+    def test_fallback_switches_model_after_provider_error(self):
+        seen = []
+
+        def call(body):
+            seen.append(body["model"])
+            if body["model"] == "bad/model":
+                raise ValueError("OpenRouter HTTP 400: provider rejected image")
+            return {"ok": True}
+
+        model, payload = oj.call_with_fallback(
+            ["bad/model", "good/model"], lambda m: {"model": m}, call, attempts=1)
+        self.assertEqual(model, "good/model")
+        self.assertEqual(payload, {"ok": True})
+        self.assertEqual(seen, ["bad/model", "good/model"])
+
+    def test_auth_error_does_not_try_another_model(self):
+        seen = []
+
+        def call(body):
+            seen.append(body["model"])
+            raise ValueError("OpenRouter HTTP 401: API key not valid")
+
+        with self.assertRaises(ValueError):
+            oj.call_with_fallback(["one", "two"], lambda m: {"model": m}, call)
+        self.assertEqual(seen, ["one"])
+
+    def test_transient_error_retries_same_model(self):
+        seen = []
+
+        def call(body):
+            seen.append(body["model"])
+            if len(seen) == 1:
+                raise ValueError("OpenRouter HTTP 500")
+            return {"ok": True}
+
+        model, _ = oj.call_with_fallback(
+            ["one"], lambda m: {"model": m}, call, attempts=2)
+        self.assertEqual(model, "one")
+        self.assertEqual(seen, ["one", "one"])
+
+
+if __name__ == "__main__":
+    unittest.main()