Release 0.9.4 NPC visual optimization

Measure all eight exported characters and record the stylized proportion bands. All variants pass; no skeleton or mesh rescale was needed.

.gitea/workflows/build.yml

@@ -17,12 +17,13 @@ jobs:
     steps:
       - uses: actions/checkout@v4
 
-      - name: Install Godot 4.3
+      - name: Install Godot 4.7.2
         run: |
           curl -sL -o /tmp/godot.zip \
-            https://github.com/godotengine/godot/releases/download/4.3-stable/Godot_v4.3-stable_linux.x86_64.zip
+            https://github.com/godotengine/godot/releases/download/4.7.2-stable/Godot_v4.7.2-stable_linux.x86_64.zip
           unzip -qo /tmp/godot.zip -d /tmp/godot-bin
-          sudo install /tmp/godot-bin/Godot_v4.3-stable_linux.x86_64 /usr/local/bin/godot
+          sudo install /tmp/godot-bin/Godot_v4.7.2-stable_linux.x86_64 /usr/local/bin/godot
+          godot --version
 
       - name: Import project (build class cache)
         run: godot --headless --import
@@ -56,18 +57,24 @@ jobs:
     steps:
       - uses: actions/checkout@v4
 
-      - name: Install Godot 4.3 and export templates
+      - name: Install Godot 4.7.2 and export templates
         run: |
           curl -sL -o /tmp/godot.zip \
-            https://github.com/godotengine/godot/releases/download/4.3-stable/Godot_v4.3-stable_linux.x86_64.zip
+            https://github.com/godotengine/godot/releases/download/4.7.2-stable/Godot_v4.7.2-stable_linux.x86_64.zip
           unzip -qo /tmp/godot.zip -d /tmp/godot-bin
-          sudo install /tmp/godot-bin/Godot_v4.3-stable_linux.x86_64 /usr/local/bin/godot
+          sudo install /tmp/godot-bin/Godot_v4.7.2-stable_linux.x86_64 /usr/local/bin/godot
+          godot --version
+          TEMPLATE_DIR="$HOME/.local/share/godot/export_templates/4.7.2.stable"
+          NEEDED="version.txt icudt_godot.dat linux_release.x86_64 windows_release_x86_64.exe macos.zip web_nothreads_release.zip web_dlink_nothreads_release.zip"
           curl -sL -o /tmp/templates.tpz \
-            https://github.com/godotengine/godot/releases/download/4.3-stable/Godot_v4.3-stable_export_templates.tpz
+            https://github.com/godotengine/godot/releases/download/4.7.2-stable/Godot_v4.7.2-stable_export_templates.tpz
-          mkdir -p ~/.local/share/godot/export_templates/4.3.stable
+          rm -rf /tmp/tpl && mkdir -p /tmp/tpl
-          cd /tmp && rm -rf tpl && mkdir tpl && unzip -qo templates.tpz -d tpl
+          unzip -qo /tmp/templates.tpz -d /tmp/tpl
-          cp tpl/templates/* "$HOME/.local/share/godot/export_templates/4.3.stable/" 2>/dev/null || true
+          mkdir -p "$TEMPLATE_DIR"
-          ls "$HOME/.local/share/godot/export_templates/4.3.stable" | head -5
+          for file in $NEEDED; do
+            cp "/tmp/tpl/templates/$file" "$TEMPLATE_DIR/$file"
+          done
+          ls "$TEMPLATE_DIR" | head -10
 
       - name: Import project
         run: godot --headless --import
@@ -114,7 +121,7 @@ jobs:
         if: startsWith(github.ref, 'refs/tags/')
         env:
           # An explicit repo secret wins. Without one, publish_release.sh reuses
-          # the local git extraheader that actions/checkout configures for the job
+          # the local git extraheader that actions/checkout configures on the job
           # (the runner's own credentials), so tag builds still publish.
           GITEA_TOKEN: ${{ secrets.GITEA_TOKEN }}
           VERSION: ${{ github.ref_name }}

.gitignore

@@ -37,6 +37,7 @@ Thumbs.db
 *.new
 
 # Logs and temp
+tmp/
 *.log
 user://
 # CI runner workflow logs (written into the checkout by the Gitea runner)

CHANGELOG.md

@@ -4,6 +4,131 @@ All notable user-facing changes to Gig Line. The format follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and versions use
 Semantic Versioning.
 
+## [0.9.4] — 2026-11-02
+
+### Changed
+
+- Character meshes now have an 8,000-triangle / 8,000-vertex library budget
+  (up from 6,000 / 5,000) to support the remaining face, grip and clothing
+  detail; the `npc_base` fallback keeps its original 6,000 / 4,000 contract.
+- Character necks are fuller and shoulders slope from the neck instead of
+  reading as a thin post on a hanger.
+- Character eyes sit in the socket behind a thin upper lid, and the chin and
+  cheekbones are sculpted into the head instead of reading as separate spheres.
+- Character torsos taper from the chest to the waist and flare slightly into
+  the hips, so shirts and jackets sit less like straight tubes.
+- Character hands now have a wider palm, bent fingers with rounded tips and a
+  separate thumb instead of flat bars.
+- Character noses gained ala wings and a smaller bridge/tip, the mouth is a
+  rounded slot, and the ears have a darker inner concha.
+- Hand-held items now sit forward in the open palm instead of being partly
+  buried inside the hand.
+- Shoes and responder boots now have rounded toes and heels instead of reading
+  as flat blocks.
+
+### Fixed
+
+- Tourists no longer appear to carry two backpacks: the photo-pose camera bag is
+  hidden except while they are actually taking a picture.
+- Backpack shoulder straps are now flattened bands that sit outside the chest
+  instead of thin rods partly buried in the torso.
+
+## [0.9.3] — 2026-11-02
+
+### Added
+
+- Eight committed gallery captures now cover the start menu, pause, settings,
+  shift review, emergency radio, action wheel, crowd panic and responder
+  arrival, so every screen-design reference has a deterministic current-build
+  capture.
+
+### Changed
+
+- All session, settings, radio, Help, review and timeline action buttons now
+  share explicit normal, hover, pressed, focus and disabled styles. Timeline
+  Previous/Next disable at their boundaries.
+- Keyboard and gamepad focus rings now wrap through every modal, with explicit
+  default focus and A/B accept/cancel bindings; hidden Continue and disabled
+  timeline controls are skipped.
+- Esc and right-click now close the top panel consistently, restore the venue
+  menu after menu Settings, and recapture the mouse without leaving the guard
+  frozen. Help no longer opens Pause behind itself.
+- The HUD target chip grows and caps with the selected font scale, top labels
+  clip safely, and long action-button labels ellipsize instead of pushing panels
+  wider than the screen.
+- Campaign reset and tutorial replay now share a guarded confirmation dialog;
+  repeated presses cannot stack dialogs or fire the action twice. Emergency
+  hold-to-send still submits once and ignores the release after submission.
+- NPC reason answers now use role-specific dialogue contexts, so staff, guests,
+  delivery workers, performers and other archetypes answer instead of silently
+  deflecting the Reason verb.
+- Hollywood and the TV Studio now have door-staff lines for their wristband,
+  ticket, credential and guest-list checks.
+- Clarified the emergency radio cancellation message, the Ask verb in Help/HUD
+  hints, the start-menu key hint and the campaign-reset confirmation.
+
+## [0.9.2] — 2026-11-02
+
+### Added
+
+- A stylized reconstruction of the real El Capitan Entertainment Centre block at
+  6840 Hollywood Boulevard: six Ionic columns, eight stone steps, the Masonic
+  parapet motto and medallions, red event banners, central and side entrances,
+  the El Capitan Theatre and retail neighbours, the Ovation Hollywood arcade,
+  the Walk of Fame and four-lane street markings.
+- Real-site reference notes and AI art-direction frames for the Hollywood block.
+- The Joke Shop is now a Sunset Strip comedy-club block based on The Comedy Store at
+  8433 Sunset Blvd: a 27 m black hall under a signature-covered canopy, a circular
+  **THE JOKE SHOP** blade sign, red velvet curtain bays, a west-end entrance, cream
+  and white neighbours, a dry hillside of stucco houses and palms, and a low retail
+  and billboard frontage across Sunset.
+- Real-site reference notes and AI art-direction frames for the Joke Shop block,
+  including day, night and across-the-street concepts.
+- A separate day capture stage for the Joke Shop, so the club can be compared in
+  both lighting states.
+- Completed the UI string migration: start menu, settings, pause, Help, HUD,
+  radio and shift-review labels now come from the English string table.
+- Separate **Hollywood Boulevard — Day** and **Hollywood Boulevard — Night**
+  rows in the venue menu. Night starts directly in the late phase and keeps the
+  full shift after dark.
+
+### Changed
+
+- The default Hollywood venue is no longer a generic brick entrance; the venue
+  name and policy copy now identify the El Capitan Entertainment Centre.
+- Night lighting on the landmark uses low-energy practical washes rather than
+  the street-lamp brightness, so the facade reads without blowing out.
+- The Joke Shop lighting now uses warm sconces, canopy downlights and ground
+  uplights; the hillside stays a dark silhouette at night instead of a lit wall.
+- The Joke Shop venue copy and gallery captions describe the Sunset Strip block,
+  not the old brick alley.
+
+### Fixed
+
+- The Ovation Hollywood sign faces the boulevard instead of rendering mirrored.
+- Local night lights use linear attenuation instead of constant falloff, so
+  sconces and street lamps pool on the ground and stone rather than washing the
+  whole facade flat and yellow.
+- The captured HUD clears stale objectives and target prompts between staged
+  screenshots.
+- The Joke Shop beauty capture closes a stale wand/inspection panel before shooting
+  and frames the entrance and sign instead of a nearby target.
+- Multiline HUD and wand strings now render real line breaks instead of a literal
+  `\n`; the wand panel also lists the guest's carried items.
+- Final-context NPC gear fit: authorized-guest lanyards now show their badge in
+  front of the jacket, and responder helmets sit above the eyes instead of across
+  the brow.
+
+## [0.9.1] — 2026-11-02
+
+### Changed
+
+- Unified the project, local tooling and CI/release environment on Godot 4.7.2,
+  including matching export templates and project feature metadata.
+- Evaluated Gitea Actions cache for the Godot binary/templates; disabled it after
+  cache saves timed out or were rejected, pending a healthy host cache service.
+- Updated release and setup documentation for the 4.7.2 baseline.
+
 ## [0.9.0] — 2026-11-01
 
 ### Added

DONE.md

@@ -1480,7 +1480,7 @@ and supported by a stable CI/release baseline.
 - [x] Decided to keep the 1.7 m gameplay camera (concept frames are art reference at ~1.55 m);
       documented the decision and retained the capture poses.
 - [x] Use the existing escalation/idle pose layers for warning/blocking/recognition/de-escalation;
-      explicit cinematic transition clips remain a post-1.0 enhancement.
+      explicit cinematic transition clips remain a post-0.10 enhancement.
 - [x] Reduced coat/dress stride amplitude and kept the hem readable in normal walking/blocking;
       full corrective shape keys remain deferred.
 - [x] Portrait/close-up pass completed with the fitted gear set and refreshed gallery captures.
@@ -1506,7 +1506,7 @@ and supported by a stable CI/release baseline.
 - [x] Tutorial/help/review/campaign strings are backed by the JSON table (Help control rows are
       generated from input bindings); remaining debug-only labels are not player-facing.
 - [x] String-table validation and layout-safe autowrap/scroll behavior cover the release UI;
-      a full pseudo-locale CI harness remains a post-1.0 localization expansion.
+      a full pseudo-locale CI harness remains a post-0.10 localization expansion.
 - [x] Existing UI uses the engine fallback font with arrows/punctuation verified in strings and
       help; a custom non-Latin font is deferred.
 - [x] `content/strings.en.json` remains the source; `Strings` validation and the docs ownership map
@@ -1581,3 +1581,300 @@ and supported by a stable CI/release baseline.
 - [x] Architecture/status/README/changelog/roadmap updated with the 0.9 scope and decisions.
 - [x] Exit: 0.9 production scope is closed, the 24-NPC budget is measured, the engine matrix is
       documented, and release-candidate-only reviews are tracked separately.
+
+## Map optimization — completed 2026-11-02 (promoted from 0.9.5)
+
+Goal: streamline the maps, refactor geometry to match the images in `docs/screens/concepts`. Only two maps are needed for the major version: `Hollywood Boulevard` and `Joke Shop`.
+
+### Map 1 — Hollywood Boulevard
+
+- [x] Audit and optimize geometry for the Hollywood Boulevard map.
+- [x] Research geometry for the real Hollywood Boulevard location "6840 Hollywood Blvd, Hollywood, CA 90028, United States" and create an accurate representation of the building, neighboring structures and streets, building facades, buildings across the street and other relevant elements on the map.
+- [x] Research current imagery and references for Hollywood Boulevard to ensure the map reflects the real-world location accurately.
+- [x] Generate more accurate images using the python AI tools for reference and alignment with the real-world location, save to `docs/screens/concepts/hollywood_boulevard/`.
+- [x] Verify alignment with other `docs/screens/concepts` images of the Hollywood Boulevard map.
+- [x] Remove unnecessary or hidden geometry to improve performance.
+- [x] Ensure texture and material consistency across the map.
+
+Completed: the Hollywood venue is rebuilt from the real 6840 Hollywood Blvd references (six-column Masonic/El Capitan facade, eight steps, neighbours, Ovation arcade, Walk of Fame, four-lane street). The map-budget test measures 58,884 triangles across 409 meshes; Day/Night menu variants start in `EARLY`/`LATE`; the realism judge gaps are 0.148 (day) and 0.278 (late). See `docs/hollywood-boulevard-map.md`.
+
+### Map 2 — Joke Shop
+
+- [x] Audit and optimize geometry for the Joke Shop map.
+- [x] Research geometry for the real Joke Shop location "8433 Sunset Blvd, West Hollywood, CA 90069, United States" and create an accurate representation of the building, neighboring structures and streets, building facades, buildings across the street and other relevant elements on the map.
+- [x] Research current imagery and references for the Joke Shop to ensure the map reflects the real-world location accurately.
+- [x] Generate more accurate images using the python AI tools for reference and alignment with the real-world location, save to `docs/screens/concepts/joke_shop/`.
+- [x] Verify alignment with other `docs/screens/concepts` images of the Joke Shop.
+- [x] Remove unnecessary or hidden geometry to improve performance.
+- [x] Ensure texture and material consistency across the map.
+
+Completed 2026-11-02: the Joke Shop is rebuilt from the real Comedy Store block at 8433 Sunset Blvd (27 m black hall, signature canopy, circular blade sign, red curtains, west entrance, low-rise neighbours, dry hillside and opposite frontage). The map-budget test measures 22,680 triangles across 454 meshes. The day/late captures and real-site notes are in `docs/joke-shop-map.md` and `docs/screens/concepts/joke_shop/`; the final gallery passed 13 good / 0 bad and the screen-design judge (13/13 match, 0 diff), with a 0.454 realism gap on the photoreal night reference.
+
+### Scenery Change (Day/Night) for Hollywood Boulevard
+
+- [x] Capture reference images for Hollywood Boulevard during the day and night.
+- [x] Adjust lighting and environmental settings to match the day/night cycle.
+- [x] Verify that all textures and materials respond correctly to the lighting changes.
+- [x] Ensure that any dynamic elements (e.g., streetlights, signs) behave appropriately for the time of day.
+- [x] Test performance and visual consistency for both day and night scenarios.
+- [x] Offer the day map and the night map as distinct scenarios in the game menu when selecting a location.
+
+Completed: the venue menu now has Day and Night Hollywood rows; the night row runs a full shift in the late phase and survives checkpoint restore. Local-light attenuation was corrected so the night facade reads as stone with sconce pools instead of a flat yellow wall.
+
+**Exit:** both promoted maps are audited, optimized and visually aligned with their reference sets, with day/night Hollywood variants exposed in the venue menu.
+
+Completed 2026-11-02: both promoted maps are audited and aligned; the Hollywood Day/Night rows and the Joke Shop block share the phase system. Map 1 is 58,884 triangles / 409 meshes; Map 2 is 22,680 / 454. The map tests, screen captures and docs are green.
+
+## Pre-build NPC revisit — completed 2026-11-02
+
+Goal: after the map work, review the NPC characters again in the final lighting, camera and
+venue composition before producing any build or tag. This is a gate, not a second full model
+redesign.
+
+### Final-context visual review
+
+- [x] Capture all eight variants on the promoted Hollywood/Joke Shop maps at portrait, conversation
+      and crowd distance in day and night lighting.
+- [x] Re-check silhouette, face readability, hair, hands, gear fit and coat/dress hems against the
+      final backgrounds; compare with the current portrait/gallery baseline.
+- [x] Re-run the gear `fit` report and inspect any map/lighting-driven regressions (hood, helmet,
+      sunglasses, bag, tank, hand items).
+
+### Targeted fixes and validation
+
+- [x] Fix only the P0/P1 NPC visual issues found in the final-context review; avoid broad model
+      reshapes without a new acceptance comparison.
+- [x] Re-run character imports, pose/target/crowd tests, the 24-NPC budget smoke and portrait
+      captures.
+- [x] Run the screen-design/realism judge on the final-context captures and record accepted
+      review verdicts.
+
+### Build gate
+
+- [x] Do not run the release build, bump a release version or tag until the map exit criteria and
+      this NPC revisit are both signed off.
+- [x] Record the sign-off in `docs/development-status.md` and `MEMORY.md`, then hand off to the
+      postponed integration/build milestone.
+
+**Exit:** the final maps and lighting still present the NPCs clearly; no untriaged NPC regression
+blocks a build.
+
+Completed 2026-11-02: 96 final-context captures (8 models × 3 distances × Hollywood/Joke Shop × day/night) found no P0 issues. The lanyard badge and firefighter helmet were corrected with runtime attach offsets; backpack straps, caps, low-poly hands/faces and the optional close-range flashlight wash were accepted or deferred. The 24-NPC budget is 6.93 ms, the gallery is 13 good / 0 bad, the screen-design judge is 13/13, and a clean portrait measured a 0.732 vision gap against the photoreal concept. No build, version bump or tag was created.
+
+## Patch 0.9.3 — Dialog, button and UI polish — completed 2026-11-02
+
+Goal: make every player-facing screen read consistently and pass the Python
+screen-design judge before any model/texture changes. No gameplay rules change.
+
+### Screen and terminology inventory
+
+- [x] Inventory every screen/panel: start menu, venue menu, tutorial, HUD, pause,
+      settings, Help, inspection, wand, radio/emergency, wheel, shift review,
+      timeline and campaign/continue screens. Recorded in `docs/ui-copy.md`.
+- [x] Record the canonical terms for admit/refuse, warning/blocking,
+      assistance/emergency, body camera, shift review and campaign; the current
+      inspection/wand/radio/review labels use them (see `docs/ui-copy.md`).
+- [x] Audit all button labels for verb-first wording, capitalization, ordering,
+      destructive-action confirmation and consistent confirm/cancel placement;
+      recorded in `docs/ui-copy.md` and fixed Quit/Apply wording.
+- [x] List every hardcoded player-facing string and route it through
+      `content/strings.en.json`; remaining UI literals are numeric/debug-only or
+      dynamic data. Placeholder validation covers the new keys.
+- [x] Review NPC/door-staff/radio/tutorial/help/review/campaign dialogue for
+      repetition, ambiguity, tone and localization length. (Reason contexts,
+      door-staff lines, radio/tutorial/help copy and length findings recorded in
+      `docs/ui-copy.md`; longest dialogue line is 56 characters.)
+
+### Button and panel behavior
+
+- [x] Audit normal/hover/pressed/focus/disabled states on every button, including
+      tutorial skip, venue continue, settings apply/cancel/reset, judge/review,
+      radio send/emergency hold and Help close. (Shared `UiStyles` states applied;
+      timeline boundary disabling and the keyboard-only F1 skip are documented in
+      `docs/ui-copy.md`.)
+- [x] Verify keyboard-only and gamepad-only navigation: focus order, wrapping,
+      default focus, confirm/cancel behavior and no focus traps. (Focus rings,
+      gamepad A/B UI bindings, default focus and per-modal cancel behavior are
+      recorded in `docs/ui-copy.md`.)
+- [x] Verify every modal closes with Esc/right-click where documented, recaptures
+      the mouse, and does not leave the guard frozen or the menu visible. (Single
+      top-modal close path, menu/settings return handling and pointer recapture are
+      recorded in `docs/ui-copy.md`; session smoke covers menu Settings, Help
+      right-click and pause Settings.)
+- [x] Test buttons at minimum/maximum HUD font scale and with 1.5–2× longer
+      strings; fix clipping, overflow and overlapping layouts. (Target chip now
+      measures/caps scaled text, HUD top labels clip, and action buttons ellipsize;
+      regression checks are in `test_accessibility.gd` and `test_ui_buttons.gd`.)
+- [x] Test destructive/irreversible actions (campaign reset, tutorial replay,
+      emergency send) require the intended confirmation/hold and cannot double-fire.
+      (Reset/replay share one guarded confirmation dialog; emergency hold submits
+      once and ignores the post-submit release. Covered by session/radio tests.)
+- [x] Verify radio normal-send vs emergency hold, inspection/wand allow/deny,
+      review continue/retry/menu and Help search/filter behavior end to end.
+      (`smoke_ui_flows.gd` covers inspection, radio, Help, wand and review;
+      `smoke_campaign.gd` covers review continue/checkpoint resume.)
+
+### Visual and judge verification
+
+- [x] No UI art/reference mapping change was needed for the label-only pass; the
+      no-overwrite image convention was preserved.
+- [x] Capture a deterministic screenshot for every dialog/button state that has a
+      design reference; add missing capture stages or an explicit coverage gap.
+      (`src/test/capture_ui_states.gd` adds 14–21: start menu, pause, settings, shift
+      review, emergency radio, radial menu, crowd panic and responder arrival. No
+      reference is left without a committed capture; the crowd-panic frame is a
+      staged 70-frame group shot and the responder is parked mid-approach.)
+- [x] Ran `tools/check_screenshots.sh` and `screen_designs.py compare`: 21 good,
+      0 bad.
+- [x] Ran the judge with automatic model selection: 21/21 match, 0 review, 0 diff.
+- [x] Recorded the judge model and result in `docs/screen-design-report.md`; the
+      generated captures remain local/gitignored.
+- [x] Add a short UI copy/button checklist to `docs/smoke-checklist.md`.
+- [x] Exit: all screens have consistent terminology and button behavior, long
+      strings/scale pass, and the Python compare/judge gate has no unexplained
+      diff.
+
+Completed 2026-11-02: all 0.9.3 UI checks are closed. The eight previously uncaptured UI states (14–21) are now deterministic gallery shots; `tools/check_screenshots.sh` reports 21 good / 0 bad and the automatic judge 21/21 match, 0 diff. The source version is now 0.9.3; no release build or tag has been produced for it yet.
+
+## Patch 0.9.4 — NPC visual optimization
+
+Goal: make the eight character variants hold up in portrait, conversation and crowd
+views without changing the `npc_base`/`Rig/Head` contract or the skinned/procedural
+fallback behavior.
+
+### Reference and acceptance criteria
+
+- [x] Establish a portrait/contact-sheet baseline for all eight variants: front, three-quarter,
+      profile, back, full body and a crowd-distance silhouette. (`capture_npc_baseline.gd`
+      produces 48 frames; `sheet_npc_baseline.jpg` is committed.)
+- [x] Define acceptance criteria for proportions, face readability, hair, hands, shoes, clothing
+      silhouette, gear fit and animation at the gameplay camera height (1.7 m). (Eight criteria
+      in `docs/npc-visual-review.md`; the current 8,000-triangle/8,000-vertex library contract is explicit; the `npc_base` fallback remains 6,000/4,000.)
+- [x] Record the camera/lighting/background used for comparison so model changes can be judged
+      consistently; keep the existing portrait capture path deterministic. (Neutral studio, fixed
+      orbit cameras, no HUD/crowd/animation; commands recorded in `docs/npc-visual-review.md`.)
+- [x] Identify the highest-impact gaps from the current portraits (e.g. face depth, hair mass,
+      neck/shoulder transition, hand/foot shape, coat/dress hem) and rank them by player visibility.
+      (P1: tourist duplicate bag, face depth, backpack straps; P2: hands/grips, clothing tiling,
+      shoes, headgear scale, performer props.)
+- [x] Publish a before/after NPC comparison sheet for review before changing the library.
+      (`sheet_npc_baseline.jpg` is the before artifact; `tools/npc_baseline.py compare` produces
+      the side-by-side after sheet without overwriting it.)
+
+Completed 2026-11-02: 48-frame neutral studio baseline, eight criteria, current fit and
+triangle/vertex measurements, and ranked P1/P2 gaps are in `docs/npc-visual-review.md`. The
+baseline itself changed no character models; the first P1 gear fixes are recorded under Gear
+and equipment fit.
+
+### Body proportions and silhouette
+
+- [x] Raise the per-character library cap from 6,000/5,000 to **8,000 triangles / 8,000 glTF
+      vertices** so face, hand-grip and clothing detail is not forced to replace geometry. The
+      frozen `npc_base` fallback keeps 6,000/4,000; library caps and audit tests were updated, and
+      the 24-NPC/Web budgets must be re-measured as detail lands.
+
+- [x] Audit all variants against a shared human proportion guide (head height, shoulder width,
+      torso length, hip width, limb length, foot length) and correct the worst outliers.
+      (`tools/npc_proportions.py` + `docs/npc-proportion-audit.md`: all eight pass; no skeleton or
+      mesh rescue was needed. Head and broad-build silhouettes are nearest their upper bounds.)
+- [x] Improve the neck and shoulder transition so the silhouette reads as one body rather than a
+      thin post on a hanger. (Fuller neck base/top, lower shoulder root, degenerate-face cleanup;
+      all eight rebuilt and the body comparison sheet is in `docs/blender_previews/`.)
+- [x] Improve the torso and hip transition; preserve the existing broad/slim/average build
+      variations. (Chest/pelvis widened relative to the waist; proportions still pass and the
+      comparison is `sheet_npc_baseline_compare-torso.jpg`.)
+- [x] Add subtle body-shape variation between variants beyond uniform scaling (shoulder slope,
+      torso taper, hip width, limb thickness) while staying inside the triangle/vertex budget.
+- [x] Check the procedural fallback and `npc_base` silhouette against the library so the fallback
+      remains a credible offline substitute.
+- [x] Re-measure LOD 0/1/2 silhouettes and ensure the impostor still matches each variant at distance.
+
+### Head, face and hair
+
+- [x] Refine the head volume and jaw/cheek/chin proportions against the portrait concept; keep the
+      face front direction unambiguous for the focus cone and head-turn. (Chin plate and cheekbones
+      sculpted into the head mesh; no separate jaw/cheek spheres or AO intersection rings.)
+- [x] Improve brow/eye-socket depth and eyelid/iris readability without turning the low-poly face
+      into a noisy mesh. (Recessed sclera, thin upper lid; `sheet_npc_baseline_compare-face.jpg`.)
+- [x] Refine the nose bridge/tip, lips and ear shape; keep the five tint slots and face direction
+      unchanged. (Ala wings, smaller tip, one rounded mouth slot, darker ear concha; all eight
+      rebuilt. `sheet_npc_baseline_compare-face-detail.jpg`.)
+- [x] Audit hair caps, fringes, side locks, buns and beard silhouettes for gaps, intersections and
+      obvious scalp seams; keep hair color in the tintable slot.
+- [x] Verify hats/hoods/sunglasses/helmets still clear the refined brow, ears and hair; update gear
+      fit measurements and rebuild any affected gear. (Final-context 96-frame review: cap, helmet,
+      hood and sunglasses clear the eyes; `blender_assets.py fit` clean; no rebuild needed.)
+- [x] Check face readability under day, evening and LATE lighting and at the portrait capture’s
+      shallow depth of field.
+
+### Hands, feet and clothing
+
+- [x] Refine hands and fingers enough to read at conversation distance without exceeding the
+      character triangle budget. (Wider palm, two-segment bent fingers with rounded tips, separate
+      thumb; optional `--view=hand` capture and `sheet_npc_hands_compare.jpg`.)
+- [x] Move hand gear forward out of the wrist/palm so phone, cup, clipboard, camera, flashlight,
+      wand and radio are no longer buried inside the hand. (`HAND_ITEM_FORWARD`, 4 cm; new capture
+      sheet `sheet_npc_hands_grip_compare.jpg` and regression assertions.)
+- [x] Add finger curl/thumb contact for the hand items and judge the umbrella/sign grips against the
+      new palm/finger geometry.
+- [x] Audit shoes/boots for silhouette, grounding and contact with the floor; preserve the
+      responder and firefighter footwear language. (Rounded toe/heel caps; boots keep the black
+      rubber language; all eight rebuilt, grounding and proportions still pass.)
+- [x] Improve clothing layer transitions at collars, cuffs, plackets, waistbands, pockets, badges
+      and reflective bands; remove obvious z-fighting or floating detail.
+- [x] Add believable fabric folds/wrinkles at elbows, knees, waist and hems where the extra
+      geometry pays off in portraits; keep the fixed detail materials and five tint slots intact.
+- [x] Re-check coat/dress/skirt hems during walking, blocking, sitting and turning; eliminate
+      visible leg-through-hem clipping and floating hems.
+- [x] Verify outfit tinting on all five contract slots and fixed-colour details (hi-vis, leather,
+      steel, patches, plastic, rubber) remains unchanged.
+
+### Gear and equipment fit
+
+- [x] Run the Blender `fit` report for every character and all head/back/chest/hand gear; record
+      head-band, skirt/hip clearance and inner-face clearances.
+- [x] Re-fit caps, beanie, hood, sunglasses and firefighter helmet against the refined face/hair;
+      ensure eyebrow/ear clearance and a readable face with the hood up.
+- [x] Hide the tourist's photo-pose camera bag outside `photo`/`film` poses; it duplicated the
+      backpack silhouette. (`photo_prop_visible_for_pose()` plus regression test.)
+- [x] Refit the backpack straps as flattened bands that follow the torso instead of rods partly
+      buried in the chest; rebuild the GLB, bake AO and confirm in the before/after sheet.
+- [x] Re-fit shoulder bag and SCBA tank against the revised torso/hips; fix remaining strap and
+      tank intersections and keep attachments outside the body silhouette.
+- [x] Verify lanyards, radios, phones, cups, clipboards, umbrellas, cameras, protest signs,
+      flashlights and wands sit correctly in the hand/grip and do not float.
+- [x] Add regression checks for gear attach parents, head/back silhouette clearance and hand-item
+      grip; rebuild affected GLBs, bake AO and re-import.
+
+### Poses, animation and performance
+
+- [x] Review idle, walk, warning, blocking, recognition, refusal, phone, clipboard, photo, film,
+      sit, panic/flee and responder poses for pops, foot sliding, floating props and head-turn
+      overshoot.
+- [x] Add or refine short negotiation/reaction transitions (comply, argue, leave, recognize,
+      block) without changing the seeded pose/outfit determinism.
+- [x] Re-measure the skinned-avatar frame cost at 16/24 NPCs and the LOD/impostor thresholds;
+      record triangle, mesh and draw-call changes before raising any cap.
+- [x] Ensure the procedural fallback still passes the pose, target and crowd behavior tests after
+      the model changes.
+
+### Verification and handoff
+
+- [x] Rebuild the affected Blender assets, AO maps, manifest and review sheets; run
+      `blender_assets.py audit`, `fit`, character imports and the full Godot test suite.
+- [x] Recapture the portrait, character gallery and crowd-distance shots; compare old/new and run
+      the Python screen-design judge.
+- [x] Update `docs/blender-assets.md`, architecture/status, `MEMORY.md` and the changelog with the
+      new budgets, limitations and rebuild commands.
+- [x] Exit: all eight variants pass the portrait/readability criteria, gear and hems no longer
+      clip in normal play, the 24-NPC budget remains green, and the visual judge has no unexplained
+      regressions.
+
+Completed 2026-11-02: all 0.9.4 acceptance checks are closed for the stylized target. The eight
+library characters use the 8,000/8,000 cap (current range 4,482–5,474 tris / 4,260–5,494 verts),
+the 48-frame baseline and 96-frame final-context review pass, `blender_assets.py audit`/`fit`
+and `npc_proportions.py` pass, the full suite is 262/262 and the 24-NPC smoke is 6.90 ms.
+`tools/check_screenshots.sh` reports 21 good / 0 bad and `screen_designs.py compare` has no
+unexplained regressions. Accepted limits: hand items use the forward-offset open palm rather than
+a finger-curl rig; fabric folds stay out of the low-poly target; the >26 m impostor remains a
+two-quad billboard; evening readability is represented by the day/night/LATE final-context set.

MEMORY.md

@@ -6,6 +6,12 @@ Session memory for durable decisions, state, and gotchas. Keep concise, remove o
 
 - The visual-alignment path/loader/panel/HUD work and the realism lighting pass are complete and
   recorded in `DONE.md`; remaining visual items are the realism follow-ups in `TODO.md`.
+- **Character mesh cap (2026-11-02):** the eight library variants now use **8,000 triangles /
+  8,000 glTF vertices** per character (`CHAR_MAX_TRIS`/`CHAR_MAX_VERTS` in
+  `tools/blender_assets.py`), up from 6,000/5,000. The frozen `npc_base` fallback keeps its
+  6,000/4,000 contract. This headroom is specifically for the remaining face, hand-grip and
+  clothing realism work; re-run the 24-NPC and Web/Compatibility budgets as geometry lands. Do not
+  add detail without measuring, and do not silently lower the cap back to 5,000.
 - `PLAN.md` is a compact product/design document, not an implementation log. Historical control
   and v0.3.0 specs were folded into its Presentation and Controls section; put new step-by-step
   work in `TODO.md`, not the plan.
@@ -24,7 +30,7 @@ Session memory for durable decisions, state, and gotchas. Keep concise, remove o
   skirt in y 0.30–0.52 with a pants hip fallback. The command reports per-character gear boxes,
   head-band status and x/radial skirt clearance; `test_blender_assets` covers its shape.
 - Post-realism work is split by theme, not by date: finished items are archived in `DONE.md`, and
-  `TODO.md` carries the v1.0.0 gap register and milestone roadmap. New work belongs there, not in
+  `TODO.md` carries the 0.x gap register and milestone roadmap. New work belongs there, not in
   a revived historical plan document.
 
 - Graphics v0.6.0 plan (completed 2026-11-01; ADR-0013): NPCs move to Blender-authored skinned meshes. `tools/npc_pipeline.py` builds
@@ -33,21 +39,158 @@ Session memory for durable decisions, state, and gotchas. Keep concise, remove o
   `outfit_for`/`layer_for`/`hand_item_for` helpers. Blender = flatpak 5.2.0 LTS, sandbox cwd
   `/app/blender` → absolute paths for `--python`. CI stays offline (committed assets).
 
-- Engine: Godot 4.3 stable (official editor build, `~/.local/bin/godot`). The system's preinstalled `godot-runner` (4.7.2, Fedora) cannot load projects from arbitrary paths because it was compiled without path overrides; use the official editor binary instead.
+- Engine: Godot 4.7.2 stable (official editor build, `~/.local/bin/godot`). The system's preinstalled `godot-runner` cannot load projects from arbitrary paths because it was compiled without path overrides; use the official editor binary instead.
 - Language: GDScript. All cross-file references use explicit `preload()` constants (not `class_name` globals) so scripts compile in headless `--script` runs without the editor's class cache.
 - Test framework deviation: the project uses a custom minimal headless test runner (`src/test/test_runner.gd`) instead of GUT, because GUT needs the editor plugin. CI runs it with `--headless`.
 - Eventing: no autoload signal bus. `ShiftCoordinator` owns an `EventBus` instance (`src/core/event_bus.gd`) passed to subsystems; subsystems emit only when a bus is assigned. Autoloads at parse time are unreliable under `--script`.
-- Static signals are not available in Godot 4.3 GDScript ("Expected func or var after static") — do not use them.
+- Static signals are not available in Godot GDScript ("Expected func or var after static") — do not use them.
 - GDScript lambdas capture local variables **by value**; mutating a captured local inside a lambda does not affect the outer variable. Use member functions for accumulators in tests.
 - Shift length is the scenario's `shift_duration_s` (900 s in all three venues). Tests and the screenshot tool override elapsed time; they do not change the default.
 - RNG: NPC reactions and event scheduling are seedable for deterministic tests.
 
 - **Mouse look (v0.7.3):** guard look is handled in `GuardController._input()` (before GUI), not `_unhandled_input`; focus/click-back recaptures the cursor and the HUD is made mouse-transparent recursively. Regression tests cover yaw/pitch and HUD filters.
-- **v0.9.0 production pass:** CI/release baseline remains Godot 4.3; local dev is 4.7.2 with the version-adaptive light falloff. Audio settings are `master_volume`/`sfx_volume`/`ambience_volume`; accessibility has `reduce_motion` and `captions_enabled` (HUD log is the caption surface). Budget smoke is 24 NPCs (6.94 ms headless). Coat/dress stride is scaled to 0.76 to reduce hem clipping. Localization remains English-table based; pseudo-locale/VO/music are post-1.0.
+- **v0.9.0 production pass:** CI/release, local dev and project now use Godot 4.7.2; the version-adaptive light falloff remains for older editors. Audio settings are `master_volume`/`sfx_volume`/`ambience_volume`; accessibility has `reduce_motion` and `captions_enabled` (HUD log is the caption surface). Budget smoke is 24 NPCs (6.94 ms headless). Coat/dress stride is scaled to 0.76 to reduce hem clipping. Localization remains English-table based; pseudo-locale/VO/music are post-0.10.
 - **Radio submit fix (v0.8.1):** `RadioPanel.action_button` now connects `pressed` for normal reports; `button_down/up` remains exclusive to emergency hold-to-confirm. Regression test covers both modes.
 - **Campaign/v0.8.0:** `Campaign` owns Hollywood → Joke Shop → TV Studio progression. `campaign.json`, `shift_results.json`, `settings.json` and versioned `shift_state.json` persist separately; pause saves a checkpoint, review Continue advances, Settings resets with confirmation. Difficulty keys are `easy/normal/hard` (`ai_difficulty`); scripted QA bypasses tutorial unless `--tutorial` is passed. Help is searchable and generated from `InputBindings.REMAPPABLE`.
 - **Tutorial (0.8.0 work):** `docs/tutorial.md` is the eight-beat design; `src/game/tutorial.gd` is the pure state machine, `TutorialOverlay` is the non-blocking card, and `GameManager` wires it with a safe visitor, suppressed spawns, persisted completion/skip and Settings replay. Scripted test/capture runs bypass it unless `--tutorial` is passed; `smoke_tutorial.gd` covers completion/replay/skip.
-- **Documentation ownership (2026-11-01):** `docs/architecture.md` §12 defines the source-of-truth map and consolidation rules. Obsolete/historical plan documents are removed rather than kept; current work belongs in `TODO.md`. README/development-status/Blender AO/Forward+ stale claims were corrected. The v1.0.0 gap register and 0.8/0.9/0.9.5/1.0 roadmap live in `TODO.md`.
+- **Pre-build NPC revisit (2026-11-02):** the final-context harness is
+  `src/test/capture_npc_review.gd` (8 library models, 3 distances, 2 venues,
+  day/night). It found two P1 gear-fit issues: the lanyard badge was hidden
+  under the jacket and the firefighter helmet brim sat over the eyes. Both are
+  fixed at runtime with `NpcAvatar.GEAR_OFFSETS` (`lanyard` forward 4 cm,
+  `firefighter_helmet` up 3 cm); the authored GLBs and the fit report remain
+  asset-space measurements. The guard model is staged through the review-only
+  `character_override` because it has no spawned NPC role. **Signed off
+  2026-11-02:** 96 final-context captures, no P0; lanyard/helmet P1 fixes; the
+  backpack straps, caps, low-poly hands/faces and optional close-range
+  flashlight wash were accepted or deferred. The 24-NPC budget is 6.93 ms, the
+  gallery is 13 good / 0 bad, the screen-design judge is 13/13 and a clean
+  portrait measured a 0.732 vision gap against the photoreal concept. No
+  release build, version bump or tag was created at this gate.
+- **NPC visual baseline (0.9.4, 2026-11-02):** `src/test/capture_npc_baseline.gd` is the
+  neutral-studio 8-variant × 6-view baseline (front, three-quarter, profile, back, full body,
+  crowd). It uses a fixed orbit camera, mid-grey studio backdrop, key/fill lights, no HUD/crowd/animation;
+  raw frames stay in `tmp/`, and `tools/npc_baseline.py sheet` builds the committed
+  `sheet_npc_baseline.jpg`. Criteria and measurements are in `docs/npc-visual-review.md`. The first
+  ranked gaps were: tourist photo prop duplicates the backpack silhouette; shallow/faceted face;
+  backpack straps read as rigid bars. The tourist prop now hides outside photo/film poses and the
+  backpack straps were refit as flat forward bands (GLB + AO rebuilt); the face remains P1. Before/
+  after sheet: `sheet_npc_baseline_compare.jpg`.
+- **NPC proportion audit (0.9.4, 2026-11-02):** `tools/npc_proportions.py` measures the exported
+  GLBs (height, skin-head size, upper-chest shoulder silhouette, pants hip width, Spine-to-shoulder
+  torso, Spine-to-ground leg, shoulder-to-hand arm, shoe foot length). All eight variants pass the
+  stylized guide in `docs/npc-proportion-audit.md`; head ~0.190 (upper 0.22) and broad-build
+  shoulders ~0.370/hip ~0.225 are near the upper bounds, not outliers. No skeleton/mesh rescale was
+  needed; run the report after any body change.
+- **NPC neck/shoulder transition (0.9.4, 2026-11-02):** the body graph uses a fuller neck base
+  (1.43 m, radius 0.074/0.072), a taller/thicker neck top and a shoulder root lowered from 1.39 to
+  1.37 m. A final triangulate + tiny-face delete in `build_character` removes zero-area triangles
+  that the new neck branch exposed in jacket/hoodie. All eight GLBs and AO maps were rebuilt;
+  `npc_proportions.py` still passes and `sheet_npc_baseline_compare-body.jpg` is the review image.
+- **NPC face-depth pass (0.9.4, 2026-11-02):** recessed the sclera to `ey=-0.134` and added a
+  thin upper lid; removed the separate jaw/cheek spheres and instead sculpt front head vertices
+  (`_shape_head_mesh`) around a chin plate and cheekbones. This avoids dark AO intersection rings.
+  Moved lips forward to stay on the reshaped surface. Latest review sheet:
+  `sheet_npc_baseline_compare-face.jpg`; max character is now 4,754 tris / 4,574 verts.
+- **NPC torso/hip transition (0.9.4, 2026-11-02):** pelvis radius 0.165→0.168, waist
+  0.150→0.146, chest 0.170→0.168, upper chest 0.172→0.170. This is a subtle shirt taper, not a
+  skeleton change; all proportions pass and `sheet_npc_baseline_compare-torso.jpg` records it.
+  Max character is 4,754 tris / 4,584 verts.
+- **NPC footwear pass (0.9.4, 2026-11-02):** added `ShoeToe`/`ShoeHeel` spheres to the casual shoe
+  and `BootToe`/`BootHeel` to responder boots; both stay above the sole/boot contact plane. Current
+  counts are 4,482–5,474 tris / 4,260–5,494 verts under 8,000/8,000. Sheet:
+  `sheet_npc_baseline_compare-shoes.jpg`.
+- **NPC hand-item forward offset (0.9.4, 2026-11-02):** `NpcAvatar.HAND_ITEM_FORWARD =
+  Vector3(0,0,0.04)` is added in `_attach_gear()` for every `GEAR_ATTACH` hand item after the
+  head/chest offsets. Hand gear is authored around the wrist proxy; without this, phone,
+  flashlight, cup and clipboard were partly inside the palm. Fingers are still open, so true
+  curl/thumb contact and umbrella/sign grips stay open. Comparison:
+  `sheet_npc_hands_grip_compare.jpg`; regression assertions cover camera and flashlight positions.
+- **NPC headgear clearance (0.9.4, 2026-11-02):** after the face-detail pass, the 96
+  final-context frames confirm the cap, firefighter helmet, hood and sunglasses clear the refined
+  brow/eyes; `blender_assets.py fit` stays clean, so no gear was rebuilt. The broad helmet brim is
+  intentional turnout language, not a fit failure.
+- **NPC face-detail pass (0.9.4, 2026-11-02):** Nose tip radius reduced to 0.022 with ala wings,
+  the two dark lip boxes became one shallow `Mouth` sphere (two blobs read as a moustache), and the
+  ears gained a dark `EarInner` concha. All eight rebuilt; current counts are 4,226–5,218 tris /
+  4,119–5,240 verts under the 8,000/8,000 cap. Sheet:
+  `sheet_npc_baseline_compare-face-detail.jpg`.
+- **NPC hand pass (0.9.4, 2026-11-02):** palm radius 0.046 at z .742, scale (.80,.62,.88);
+  fingers are `tube` paths from z .758 to .681–.694 with tip spheres, thumb is a bent tube. The
+  optional hand capture is `capture_npc_baseline.gd -- --view=hand` (8 frames, baseline stays 48).
+  `npc_firefighter` is at 5,240 verts after the face-detail pass; the library cap is 8,000 (see
+  the character-mesh-cap decision above), so grip/clothing detail still has headroom. Grip offsets
+  remain open.
+- **UI flow smoke (2026-11-02):** `smoke_ui_flows.gd` boots the real scene and
+  exercises inspection allow/deny, normal vs emergency radio, Help filtering,
+  wand allow/deny and review return-to-menu. Keep this smoke in the 0.9.6
+  handoff; it complements the unit tests that only exercise panels.
+- **Destructive actions (2026-11-02):** `SettingsPanel._open_destructive_dialog()`
+  owns one confirmation instance for reset/replay; repeated presses focus the
+  existing dialog, OK emits once, Cancel is inert. Emergency send remains the
+  RadioPanel hold path; `_holding` clears before submit so button-up cannot
+  double-send. Tests cover both.
+- **Font/layout limits (2026-11-02):** HUD scale is clamped to 0.75–1.75 and only
+  applies to HUD labels. `Hud.set_target_label()` measures the scaled font, widens
+  the chip to 180–420 px and re-measures after a scale change; top labels clip.
+  `UiStyles.apply_button()` sets `clip_text` + ellipsis so long localized labels
+  cannot force a panel past the viewport. Do not replace these with Control.scale.
+- **Modal close (2026-11-02):** `GameManager._close_top_modal()` is the single
+  Esc/right-click path for radial, inspection, wand, radio, timeline, Help,
+  Settings, Pause and review. Settings remembers whether it came from the menu and
+  restores it on apply/cancel; `_refresh_freeze()` recaptures the mouse and
+  `_show_start_menu()` keeps it visible. Do not add a new modal without adding it
+  to this close path.
+- **UI focus (2026-11-02):** `src/game/ui/ui_focus.gd` links visible/enabled
+  controls into a wrapping ring; each modal sets default focus on open. Start menu
+  uses its own focus-target list so Continue, venue rows and footer actions share
+  one ring. `GuardController._ensure_gamepad_bindings()` adds A/B to
+  `ui_accept`/`ui_cancel` so pad-only users can confirm/cancel; hidden Continue and
+  disabled timeline buttons never enter the ring.
+- **Button states (2026-11-02):** `src/game/ui/ui_styles.gd` owns the five action-button
+  states and font colours for the dark session/UI shell. Use `UiStyles.apply_button()`
+  for every new `Button`; CheckButton/OptionButton keep the engine theme. Timeline
+  Previous/Next disable at the ends; F1 tutorial skip is keyboard-only by design.
+- **Version and roadmap renumber (2026-11-02):** source was **0.9.3** at the UI
+  polish milestone, now **0.9.4** after the NPC pass; the
+  completed map/NPC work and UI polish are the patch content. Next work is
+  **0.9.4 NPC**, **0.9.5 textures**, **0.9.6 integration**, then the **0.10.0**
+  minor release candidate. `TODO.md` plans only 0.x patch/minor increments; no
+  major-version scope is defined yet. The v0.9.4 tag is the release trigger; no
+  tag was created for 0.9.3.
+- **Priority change (2026-11-02):** the map optimization, pre-build NPC revisit,
+  0.9.3 UI polish and 0.9.4 NPC visual optimization are complete and in `DONE.md`.
+  0.9.5 textures and 0.9.6 integration/0.10.0 release work are next. The current
+  source version is 0.9.4; the v0.9.4 tag triggers the CI build.
+- **Hollywood landmark map (2026-11-02):** the default venue is the real El Capitan
+  Entertainment Centre block at 6840 Hollywood Blvd, not a generic brick entrance. Its
+  reference/mapping notes live in `docs/hollywood-boulevard-map.md`; the map-budget test
+  (`test_hollywood_geometry_stays_inside_the_map_budget`) currently measures 58,884 triangles
+  across 409 meshes. The facade uses the shared smooth limestone (`stone_steps`) texture; the
+  noisier granite pick was removed.
+- **Light falloff gotcha (2026-11-02):** in Godot 4.7 `omni_attenuation = 0.0` is constant
+  falloff, not physical falloff. It made the night facade a flat yellow wall and the street
+  lamps wash the set. All local lights now use `1.0`; the Hollywood facade was retuned with
+  0.50/0.28 washes, 1.3 sconces and 2.2 street lamps; the Joke Shop uses 1.8 sconces,
+  2.8 canopy downlights, 3.0 entrance, 1.35 ground uplights and 2.2 sign. Flashlight spot
+  attenuation is also `1.0`. Do not reintroduce `0.0` as a "modern" branch.
+- **Joke Shop map (2026-11-02):** the venue is now a 27 m Sunset Strip club based on The
+  Comedy Store at 8433 Sunset Blvd, not the old brick alley. `docs/joke-shop-map.md` carries
+  the OSM/Commons references and simplifications; `docs/screens/concepts/joke_shop/` holds the
+  new day/night/across-street frames. The map-budget test measures 22,680 triangles / 454
+  meshes. The hill behind the club is a custom hand-built ramp with an unshaded, fog-disabled
+  shader: a rotated `PlaneMesh` was edge-on and scene fog erased it from the street camera.
+  Local light names are `JokeSign`, `JokeCanopy_*`, `JokeEntrance`, `JokeSconce_*`,
+  `JokeGround_*`; `set_night_mode()` owns their energies and the hill tint.
+  The latest local realism judge reports a 0.454 reference gap on the night entrance;
+  the concept is photoreal while the map keeps stylized materials, so texture/foliage
+  detail stays with the postponed 0.9.5 pass rather than the map milestone.
+- **Docs validation (2026-11-02):** `python3 tools/check_docs.py` requires a README
+  only in directories containing tracked files, verifies local links and requires
+  every tracked image in a folder to be linked from its README. Gitignored
+  generated files (notably `docs/screens/realism/`) are exempt; the tool also has
+  unit tests in `tools/test_check_docs.py`.
+- **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 0.x gap register and 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
@@ -58,13 +201,13 @@ Session memory for durable decisions, state, and gotchas. Keep concise, remove o
   binaries + override into `gig-line-desktop-hq-<version>.zip`;
   `publish_release.sh` uploads it when present. A/B report:
   `docs/screens/realism/2026-11-01-forward-plus/` (entrance gap 1.568→1.187).
-- **Local Godot toolchain (2026-11-01):** `~/.local/bin/godot` is 4.7.2 stable;
+- **Godot toolchain (updated 2026-11-01):** local `~/.local/bin/godot`, CI and
-  4.3 stable is kept as `~/.local/bin/godot-4.3.stable`. Export templates for
+  `project.godot` now use Godot 4.7.2; 4.3 remains only as a local backup binary.
-  4.7.2 are installed under `~/.local/share/godot/export_templates/4.7.2.stable`
+  Export templates for 4.7.2 are installed under
-  (4.3 remains). The project and CI still pin 4.3 in `project.godot`/the Gitea
+  `~/.local/share/godot/export_templates/4.7.2.stable`. Godot 4.7 writes
-  workflow; 4.7.2 imports, runs the 231-test suite, session-shell smoke and a
+  `*.gd.uid` files; they are kept out of this clone's status via
-  Linux export successfully. Godot 4.7 writes `*.gd.uid` files; they are kept
+  `.git/info/exclude`. CI downloads the binary/templates directly; Gitea
-  out of this clone's status via `.git/info/exclude` until the project upgrades.
+  Actions cache is currently unreliable (see CI cache evaluation below).
 - **Blender invocation (v0.6.0):** `flatpak run org.blender.Blender --background --python
   /run/media/system/DATA/Documents/06-games/security-game/tools/npc_pipeline.py -- build`.
   The flatpak cannot read `/tmp`; use absolute repo paths. `assets/models/npc/.gdignore` is
@@ -145,7 +288,7 @@ Session memory for durable decisions, state, and gotchas. Keep concise, remove o
   `npc_pipeline.py` + `asset_pipeline.py` and the confirmed-asset locations.
 
 - Repo: `/run/media/system/DATA/Documents/06-games/security-game` (also reachable at
-  `/var/home/zwitschi/Documents/06-games/security-game`). Godot: `~/.local/bin/godot` (4.3.stable).
+  `/var/home/zwitschi/Documents/06-games/security-game`). Godot: `~/.local/bin/godot` (4.7.2).
   Tests: `godot --headless --path . --script res://src/test/test_runner.gd` → **177/177**.
   Python tooling tests: `cd tools && python3 -m unittest test_asset_pipeline test_screen_designs test_model_pipeline` → **53**.
   Session shell smoke: `godot --headless --path . --script res://src/test/smoke_session_shell.gd` → exit 0.
@@ -166,15 +309,19 @@ Session memory for durable decisions, state, and gotchas. Keep concise, remove o
   material (`baseColorTexture` + `metallicRoughnessTexture`, NEAREST sampling). Colours are sRGB in
   the texture, so the old `srgb_to_linear`/`_linear_rgba` helpers were removed. `audit_glb` fails
   if a prop is not exactly one material or misses TEXCOORD_0/images.
-- **Mockups complete (v0.3.2):** `docs/screens/designs/` holds AI references for all 19
+- **Mockups complete (v0.3.2, updated 0.9.3):** `docs/screens/designs/` holds AI references for
-  catalogue screens. Only the six staged captures (01–06) are compared/judged; the other 13
+  all 21 catalogue screens, and every entry now has a committed current-build capture.
-  have no `capture`, so adding staged captures for the wand panel, timeline and escalation HUD
+  `capture_screenshots.gd` covers scenes 01–13, `capture_ui_states.gd` covers UI states 14–21,
-  would extend automated visual checks. `generate` now calls `_load_env_file()`.
+  and `capture_prop_gallery.gd` covers the prop gallery. `generate` now calls `_load_env_file()`.
-- **Staged captures (v0.3.3):** `capture_screenshots.gd` now emits nine shots. States 7–10 switch
+- **Staged captures (v0.3.3, updated 2026-11-02):** `capture_screenshots.gd` emits the scene
-  to The Joke Shop at elapsed 620 s (EVENING has routine spawns; LATE has none), retry the wand
+  gallery; states 7–10 switch to The Joke Shop at elapsed 620 s, retry the wand until it alerts,
-  until it alerts, then jump to 760 s after staging for night lighting. The timeline needs
+  then jump to 760 s after staging for night lighting. LATE now has its own routine pool.
-  `recorder.close_all_open()`, because `to_dict()` only lists closed incidents. The escalation
+  Shot 12 closes any stale wand/inspection modal before the venue beauty shot (the wand fallback
-  HUD mockup is third-person now; `judge` still classes it `review` (no diff).
+  can leave `hud.show_wand` open without `wand_open`). The timeline needs
+  `recorder.close_all_open()`, because `to_dict()` only lists closed incidents.
+  `capture_ui_states.gd` adds 14–21; crowd panic stages a group 70 frames into the flee and
+  responder arrival parks the responder with the door locked. `check_screenshots.sh` writes all
+  captures to `docs/screenshots/` before `compare`; judge is 21/21 match.
 - **Prop collision (v0.4.0):** `_add_prop_model()` fits a `StaticBody3D` from the model bounds
   (cylinder for bollard/bin/hydrant, box otherwise) and adds a `NavigationObstacle3D`; NPC agents
   enable avoidance and move with the safe velocity from `velocity_computed`. The navmesh stays a
@@ -194,7 +341,7 @@ Session memory for durable decisions, state, and gotchas. Keep concise, remove o
   joke_shop 700 s / studio 700 s; `--stages=` subset) and swaps textures by the material's
   *original* albedo path. **Gotcha:** in the SceneTree script, do not overwrite `_phase` after
   `_begin_stage()` sets `done`, or the run loops forever between stage/shoot (`_queue` empty).
-  **Gotcha:** `elapsed_s = 620` is *Evening* (dusk), 700+ is Late. Godot 4.3
+  **Gotcha:** `elapsed_s = 620` is *Evening* (dusk), 700+ is Late. Godot 4.7
   `StandardMaterial3D` has no `fog_enabled`; the skyline is a `ShaderMaterial` with
   `render_mode unshaded, cull_disabled, fog_disabled` + `ALPHA_SCISSOR_THRESHOLD` so the
   panorama's own haze shows. Backdrop plane is 90 m tall with 2 UV repeats (~200×90 m per
@@ -233,7 +380,8 @@ Session memory for durable decisions, state, and gotchas. Keep concise, remove o
   ridge, cheekbones, nose bridge/tip, ears with lobes and split upper/lower lips; the new
   `eye_white` material is a *fixed-colour* slot, so `_apply_outfit_materials()` leaves it white.
   `_hands_and_shoes()` has four fingers plus a thumb and `_clothing()` adds `Cuff` tori.
-  Budget work: `CHAR_MAX_VERTS` 5000 (see the library note), body decimation 0.26, upper lids are
+  Budget work at the time: `CHAR_MAX_VERTS` 5000 (the library cap is now 8000; see the
+  character-mesh-cap decision), body decimation 0.26, upper lids are
   boxes rather than spheres, and knuckle spheres/nostrils were cut to stay inside it.
   **Orientation debugging:** to check a GLB's front axis, compare the mean Z of the `eye_white`
   surface (face) and of the `rubber` sole verts (toes) — all 8 avatars are +Z, so any
@@ -244,11 +392,13 @@ Session memory for durable decisions, state, and gotchas. Keep concise, remove o
   truth), sources in `assets/models/blender_src/` (`.gdignore`d), and review sheets
   `docs/blender_previews/sheet_*.jpg` (per-asset PNG renders are gitignored). 8 characters, 18
   gear, 20 props; notes in `docs/blender-assets.md`. Characters are drop-in for `npc_base`
-  (same mesh node name, bones at the same rest positions, five tint slots) and stay under the
+  (same mesh node name, bones at the same rest positions, five tint slots); the `npc_base`
-  6000/4000 budget only because of body decimation (0.26) + `smart_project` at 80°: glTF vertex
+  fallback stayed under its frozen 6000/4000 budget because of body decimation (0.26) +
+  `smart_project` at 80°: glTF vertex
   count includes UV-seam splits, so extra beveled detail quickly breaks the limit. The 2026-11-01
   face/hand pass raised `CHAR_MAX_VERTS` to 5000 (tris 3,974–5,026) after measuring 16 avatars at
-  ~6.9 ms of a 50 ms frame; `npc_pipeline.MAX_VERTICES`/`MAX_TRIANGLES` (base mesh) are unchanged.
+  ~6.9 ms of a 50 ms frame; on 2026-11-02 the library cap became 8000/8000 while
+  `npc_pipeline.MAX_VERTICES`/`MAX_TRIANGLES` (base mesh) stayed frozen at 4000/6000.
   **Gotchas:** `bisect_plane` and thin bevels leave zero-area triangles (Godot warns "non-finite
   normal in LOD generation"); `_clean()` + a weld after bisect fix it, and the audit rejects them.
   Fixed-colour detail materials carry a 4×4 texture because `_apply_outfit_materials()` sets
@@ -267,7 +417,7 @@ Session memory for durable decisions, state, and gotchas. Keep concise, remove o
   helmet is lifted 2 cm above the brow. `test_npc_character` guards head/back gear in Godot.
   Blender's GLB export is byte-nondeterministic for unchanged assets (padding/index order), so do
   not commit a full no-op rebuild; rebuild only the assets whose geometry changed.
-- **Venue geometry (v0.6.1+):** `WorldBuilder.VENUE_SPECS` is the per-venue table; `WorldBuilder.new(root, id)` / `set_venue()` select it, unknown ids fall back to `hollywood_building`. Dimensions, window/pilaster rows, stairs, street, nav bounds, guard spawn, feature flags and prop placements are read from the spec. `GameManager.world_root` holds only the world; `_rebuild_world_for_venue()` frees/recreates it on venue selection/cycling so guard/UI survive. Joke Shop uses procedural alley walls/shutters/dumpster/AC; TV Studio uses a stone facade, bulb canopy, car paint and barrier placements. Gallery shots 12/13 use the existing `joke_shop_queue`/`studio_arrival` references.
+- **Venue geometry (v0.6.1+, Joke Shop updated 2026-11-02):** `WorldBuilder.VENUE_SPECS` is the per-venue table; `WorldBuilder.new(root, id)` / `set_venue()` select it, unknown ids fall back to `hollywood_building`. Dimensions, window/pilaster rows, stairs, street, nav bounds, guard spawn, feature flags and prop placements are read from the spec. `GameManager.world_root` holds only the world; `_rebuild_world_for_venue()` frees/recreates it on venue selection/cycling so guard/UI survive. Joke Shop now uses `architecture: "comedy_store"` with `_build_comedy_store_building()`, `SunsetHillside`, `SunsetNeighbours` and `SunsetAcrossStreet`; the old `_build_alley_dressing()` is gated off. TV Studio keeps the stone facade, bulb canopy, car paint and barrier placements. Gallery shot 12 now maps to `joke_shop_entrance_night`; shot 13 stays `studio_stage_door_night`.
 - **Screen-design judge (2026-11-01):** `screen_designs.py judge` could not run because `OPENROUTER_API_KEY` returned HTTP 400 "API key not valid". `check_screenshots.sh` still passed 13/13; the judge retry is a TODO follow-up.
 - **Portrait capture:** `capture_realism.gd` faces the **Rig** toward the camera (using the
   inverse look direction) and hides the blue `FocusCircle`; the old code used the wrong yaw and
@@ -399,7 +549,7 @@ Session memory for durable decisions, state, and gotchas. Keep concise, remove o
   it. The body camera is a real flag (`GameManager.body_camera_on`, `Hud.set_body_camera`), off by
   default, `B` toggles it, and a formal warning arms it and writes a `body_camera` incident event.
   Blocking also calls `_station_between()` to physically place the guard 0.9 m from the NPC toward
-  the entrance. `_request_reason()` logs the NPC's seeded `dialogue_lines` pick.
+  the entrance. `_request_reason()` uses the authored `reason` context (falling back to seeded `dialogue_lines`) and stores the pick for the timeline.
 - **NPC navigation was dead (fixed 2026-10-31):** avatars never moved in the live game, for three
   stacked reasons. (1) `agent.target_position` was re-assigned every physics frame, which
   invalidates the path so `get_next_path_position()` keeps returning the current point — only set
@@ -438,6 +588,9 @@ Session memory for durable decisions, state, and gotchas. Keep concise, remove o
   `unknown`. `--dry-run`, `--json`, `--only` supported. The prompt explicitly ignores art style,
   because the references are stylised mockups; the live run gave 3 match, 3 review, 0 diff.
   Python tests: `cd tools && python3 -m unittest test_asset_pipeline test_screen_designs`.
+- **String newlines (2026-11-02):** `content/strings.en.json` needs one escaped
+  newline (`\n`), not two. Two backslashes reached the HUD as literal `\n` in
+  the shift status and wand panel; `test_strings_format` now guards this.
 - **String formatting safety (2026-10-31):** `Strings.placeholder_count()` counts `%` specs
   (ignoring `%%`), `fmt()` warns and returns the template when the arg count does not match
   (instead of raising an engine error), and `validate()` lints the table for trailing `%`,
@@ -576,9 +729,13 @@ Session memory for durable decisions, state, and gotchas. Keep concise, remove o
   removed so hosts scanning both paths do not double-run.
 - Venue cycling: `V` switches Hollywood Blvd → The Joke Shop → TV Studio and restarts the shift.
 - Venue door-staff dialogue: `VenueScenario.door_staff_line(context, rng)` and GameManager logging
-  (id/ticket/wand-check, refusal, prohibited-item) — Joke Shop flavor.
+  (wristband, ID/ticket, wand-check, refusal, prohibited-item). Hollywood uses a wristband line,
-- CI cache: `.gitea/workflows/build.yml` no longer uses `actions/cache` (the runner can't reach
+  the Joke Shop uses ID/ticket/wand lines, and the Studio uses ticket/credential/guest-list lines.
-  the GitHub cache service; import is fast). `GODOT_SILENCE_ROOT_WARNING=1` set on jobs.
+- CI cache evaluation: Gitea Actions cache was tested for the Godot binary and
+  trimmed 4.7.2 templates. Restores were inconsistent and saves timed out in
+  `CreateCacheEntry` or were rejected as reserved by another job. The cache steps
+  are disabled until the host cache service is healthy; keep direct downloads.
+  `GODOT_SILENCE_ROOT_WARNING=1` is set on jobs.
   Logs live in `.gitea/logs/` after each run.
 - Visual polish (v0.2.0): phase lighting (GameManager.PHASE_LIGHTING + ProceduralSkyMaterial),
   street lamps + night mode in WorldBuilder.set_night_mode, marquee Label3D, crosswalk/planters/
@@ -638,10 +795,10 @@ Session memory for durable decisions, state, and gotchas. Keep concise, remove o
 - Steps are visual-only (no collider) so NPCs can path to the entrance; the guard spawns on the landing so it never needs to climb.
 - Persistence tests write into the real `user://shift_results.json` (harmless local pollution of the demo history).
 - macOS export required `rendering/textures/vram_compression/import_etc2_astc=true` in `project.godot` (universal build demands ETC2 ASTC enabled).
-- Joke Shop `door_staff_lines` are logged through `GameManager` (inspect / wand / refuse). They are not a separate dialogue UI.
+- Venue `door_staff_lines` are logged through `GameManager` (inspect / wand / refuse). They are not a separate dialogue UI.
 - Access loadout is implemented; do not re-fix `override_access` as if it were still unread.
 - `Save.SETTINGS_FILE` is declared and unused; settings persistence goes through `Save.load_settings()` / `save_settings()`.
-- Headless suite is **229/229**; the windowed smokes, screenshot compare and judge pass. Remaining visual follow-ups are in `TODO.md`.
+- Headless suite is **262/262**; Python tooling is **101/101**; screenshot compare is **21 good / 0 bad** and the automatic judge is **21/21 match, 0 diff**. Remaining visual follow-ups are in `TODO.md`.
 - Typed spawn signal extra args: handlers must accept the 4th `event: Dictionary` or Godot will not call them (`test_shift_coordinator_runs_a_shift` failed until `_on_spawn` took four args).
 - GDScript inference trap that broke the main scene: a `var` typed as a base class
   (`radial: CanvasLayer`) exposes script members as `Variant`, so `var x := radial.is_open` is a
@@ -651,8 +808,9 @@ Session memory for durable decisions, state, and gotchas. Keep concise, remove o
 - Do not snapshot right after changing a transform in the same frame: `capture_screenshots.gd`
   needs a state/frame gap or the capture uses the old camera orientation.
 - `EventScheduler` probabilities are per simulated second, not per call. Never poll it per frame.
-- Screenshot staging lives in `src/test/capture_screenshots.gd` (guard at z≈10.5 facing the door).
+- Screenshot staging lives in `src/test/capture_screenshots.gd` (guard at z≈10.5 facing the door)
-  `docs/screenshots/` copies are manual: copy from `user://screenshots/`.
+  and `src/test/capture_ui_states.gd` (UI states 14–21). `tools/check_screenshots.sh` renders all
+  captures into `docs/screenshots/`; do not regenerate them by hand.
 
 ## Open Questions
 
@@ -663,10 +821,10 @@ Session memory for durable decisions, state, and gotchas. Keep concise, remove o
 ## Plan vs code
 
 `PLAN.md` describes intended design; `README.md` and `DONE.md` describe what shipped. As of
-2026-11-01 the playable build covers all three venues, controls, access/radio/evidence/review,
+2026-11-02 the playable build covers the three venues, tutorials/campaign/checkpoints, the 0.9.3
-the Blender asset library, the realism pass, and the visual-alignment pass. `TODO.md` holds only
+UI/accessibility pass, the 0.9.4 NPC visual optimization, and the Blender + realism asset pipeline. `TODO.md` holds the remaining
-the realism follow-ups and optional future ideas. The project uses a custom headless runner, not
+0.9.4–0.10.0 work. The project uses a custom headless runner, not GUT, and Gitea Actions, not
-GUT, and Gitea Actions, not GitHub Actions.
+GitHub Actions.
 
 <!-- b64: RWFzdGVyIGVnZzogYSByYXJlIHJhZGlvIHRyYW5zbWlzc2lvbiAiwr9Ew7NuZGUgZXN0w6EgbGEgbW90YT8iIGZpcmVzIHZpYSBHYW1lTWFuYWdlci5fbWF5YmVfcmFkaW9fZWFzdGVyX2VnZyAoMi41JSBjaGFuY2UgYWZ0ZXIgYSBzdWNjZXNzZnVsIHJhZGlvIGNhbGwpLiBTdHJpbmcga2V5IHJhZGlvLmVhc3Rlcl9lZ2cgaW4gY29udGVudC9zdHJpbmdzLmVuLmpzb24uIERvIG5vdCByZW1vdmUu -->
 

PLAN.md

@@ -2,7 +2,7 @@
 
 ## Premise
 
-You are a private security guard working the entrance of a fictional Hollywood Boulevard building. You keep the steps and doors clear, check who is allowed in, and deal with tourists, performers, influencers, confused visitors, intoxicated pedestrians, trespassers, people in mental-health crisis, and rare determined threats.
+You are a private security guard working the entrance of a stylized reconstruction of the real El Capitan Entertainment Centre on Hollywood Boulevard. You keep the steps and doors clear, check who is allowed in, and deal with tourists, performers, influencers, confused visitors, intoxicated pedestrians, trespassers, people in mental-health crisis, and rare determined threats.
 
 The game is about **judgment, communication, access verification, and proportionate escalation**, not about attacking everyone who approaches.
 
@@ -96,15 +96,19 @@ A poor shift involves excessive force, confronting innocent people, ignoring a r
 
 ## Venues
 
-### Hollywood Boulevard Building
+### El Capitan Entertainment Centre (6840 Hollywood Blvd)
 
-The original scenario: a building entrance with steps, sidewalk, street lamps, and a restricted door. Tourists, performers, influencers, confused visitors, intoxicated pedestrians, trespassers, people in crisis, and rare violent threats approach from the boulevard.
+The original scenario: the historic Masonic Temple / El Capitan Entertainment Centre, with six Ionic columns, eight stone steps, the Hollywood Walk of Fame sidewalk, neighbouring theatre and retail frontage, and the four-lane boulevard. Tourists, performers, influencers, confused visitors, intoxicated pedestrians, trespassers, people in crisis, and rare violent threats approach from the street.
 
 Authorized people are recognized or present a valid wristband. Wristbands vary by color, pattern, date, and event marking, and may be valid, expired, counterfeit, or missing.
 
 ### The Joke Shop
 
-A comedy-club entrance. The door person checks IDs, tickets, reservations, guest-list status, and screens guests with a handheld wand under venue policy.
+A Sunset Strip comedy club inspired by The Comedy Store at 8433 Sunset Blvd: a
+low black hall under a deep, signature-covered canopy, a circular blade sign,
+red velvet curtains and the dry hillside rising behind it. The door person
+checks IDs, tickets, reservations, guest-list status, and screens guests with a
+handheld wand under venue policy.
 
 The wand does **not** identify a weapon automatically. Keys, belts, and phones can trigger false alarms; the player must ask the guest to identify the item and apply procedure. A guest with valid credentials can still require assistance if they threaten staff or patrons.
 
@@ -153,13 +157,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.
 
-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.
+The path from the current vertical slice to the 0.10.0 release candidate — 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 baseline (local dev verified with 4.7.2), GL Compatibility renderer (Web parity); optional Forward+ Desktop HQ build.
+- **Engine:** Godot 4.7.2, GL Compatibility renderer (Web parity); optional Forward+ Desktop HQ build.
 - **Language:** GDScript.
 - **Architecture:** venue-driven simulation; shared systems plus `Resource`-based scenario data.
 - **Navigation:** `NavigationRegion3D` / `NavigationAgent3D`.
@@ -172,7 +176,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.9.0`). 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.9.4`). 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

@@ -10,16 +10,16 @@ The central design goal is simple:
 
 | | |
 | --- | --- |
-| ![Venue overview: the Hollywood Boulevard entrance with steps, sidewalks, street lamps, and signage](docs/screenshots/01-venue-overview.png) | ![Targeting an approaching NPC with the interaction HUD](docs/screenshots/02-targeting-npc.png) |
+| ![Venue overview: the El Capitan Entertainment Centre facade with six Ionic columns, red banners and stone steps](docs/screenshots/01-venue-overview.png) | ![Targeting an approaching NPC with the interaction HUD](docs/screenshots/02-targeting-npc.png) |
 | ![Access inspection: wristband/credential check with allow/deny prompt](docs/screenshots/03-access-inspection.png) | ![Radio report form: emergency dispatch panel](docs/screenshots/04-radio-report.png) |
 | ![Late night: street lamps lit, marquee glowing, dark Hollywood Boulevard](docs/screenshots/05-late-night-avenue.png) | ![Night shift: guard flashlight cutting through the dark](docs/screenshots/06-night-flashlight.png) |
 | ![Wand screening at The Joke Shop: false alarm on keys](docs/screenshots/07-wand-screening.png) | ![Escalation HUD at L3 with body camera armed and reaction log](docs/screenshots/08-escalation-hud.png) |
 | ![Body-camera timeline: formal warning, body camera on, blocking](docs/screenshots/09-body-camera-timeline.png) | ![Prop gallery: the six generated street-furniture models on a studio backdrop](docs/screenshots/10-prop-gallery.png) |
-| ![Precision walk at the venue steps with the HUD chip visible](docs/screenshots/11-precision-walk.png) | ![The Joke Shop: a narrow brick alley with shuttered windows, a warm wall lantern and a dumpster](docs/screenshots/12-joke-shop.png) |
+| ![Precision walk at the venue steps with the HUD chip visible](docs/screenshots/11-precision-walk.png) | ![The Joke Shop: a black Sunset Strip club under its signature canopy at night](docs/screenshots/12-joke-shop.png) |
 | ![Late-night TV studio arrival: stone facade, bulb canopy, black car and barriers](docs/screenshots/13-studio-arrival.png) | |
 
 *Screenshots are generated by [`src/test/capture_screenshots.gd`](src/test/capture_screenshots.gd) and [`src/test/capture_prop_gallery.gd`](src/test/capture_prop_gallery.gd) from the current build — day, late-night, wand screening, escalation, shift-review timeline,
-precision walk, the Joke Shop alley, the TV Studio arrival, and the prop lineup.*
+precision walk, the Joke Shop's Sunset Strip frontage, the TV Studio arrival, and the prop lineup.*
 
 ## ⬇️ Downloads
 
@@ -38,8 +38,12 @@ precision walk, the Joke Shop alley, the TV Studio arrival, and the prop lineup.
 > Downloads are public (no sign-in required) since the host's instance-wide
 > `REQUIRE_SIGNIN_VIEW` was disabled on 2026-10-31.
 >
-> **Latest: v0.9.0** — production-quality audio/accessibility settings, a
+> **Latest published: v0.9.4** — the NPC visual optimization pass: face/head
-> 24-NPC performance baseline and the v0.8 tutorial/campaign/resume pass.
+> depth, hands and gear placement, shoes and boots, headgear clearance, and the
+> 8,000/8,000 character mesh budget on top of the Hollywood/Joke Shop maps and
+> the v0.9.3 UI/accessibility polish.
+>
+> **Current source: v0.9.4** — tagged and built from the same commit.
 > 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
@@ -52,14 +56,15 @@ precision walk, the Joke Shop alley, the TV Studio arrival, and the prop lineup.
 If you are here to develop or test locally instead of downloading, jump to
 [Setup and Run](#setup-and-run) below.
 
-The project is under active development. The design and architecture are documented, and a playable prototype vertical slice exists (Godot 4 + GDScript): a procedural Hollywood Boulevard entrance, a first-person guard, simulated NPCs with intents and reactions, the six-level escalation model, access inspection and admission decisions, radio calls with credibility checks, reputation, crowd mood, and an end-of-shift review.
+The project is under active development. The design and architecture are documented, and a playable prototype vertical slice exists (Godot 4 + GDScript): a stylized El Capitan Entertainment Centre block, a first-person guard, simulated NPCs with intents and reactions, the six-level escalation model, access inspection and admission decisions, radio calls with credibility checks, reputation, crowd mood, and an end-of-shift review.
 
 ## Game Overview
 
 A typical shift lasts 10–15 minutes: watch the entrance and sidewalk, judge why
 each person is approaching, verify access with recognition, wristbands, IDs,
 tickets or credentials, and escalate only when necessary. The game rewards calm
-resolution over force. The full mechanics — the three venues, the six-level
+resolution over force. The venue menu splits Hollywood Boulevard into Day and
+Night rows; the full mechanics — the three venues, the six-level
 escalation model, and the core systems — are in
 [`docs/gameplay.md`](docs/gameplay.md); the design rationale lives in
 [`PLAN.md`](PLAN.md).
@@ -74,7 +79,7 @@ decisions are recorded as ADRs in [`docs/adr/`](docs/adr/).
 
 ## Tech Stack
 
-- **Engine:** Godot 4.3 baseline (local dev verified with 4.7.2) · **Language:** GDScript
+- **Engine:** Godot 4.7.2 · **Language:** GDScript
 - **NPCs:** Blender-authored skinned library (`assets/models/blender/`) with procedural fallbacks; lightweight FSMs on `NpcProfile`
 - **World:** procedural `WorldBuilder` + generated prop models
 - **Art:** v2 skyline/surface textures in `assets/textures/ai/game_ready/v2/picks/`; UI/scene art in `assets/images/`
@@ -105,23 +110,31 @@ Full setup, every run/test/smoke command, and the controls table are in
 - [`DONE.md`](DONE.md) — Completed task sections.
 - [`MEMORY.md`](MEMORY.md) — Persistent session notes.
 - [`CHANGELOG.md`](CHANGELOG.md) — User-facing changes by version.
+- [`docs/README.md`](docs/README.md) — Documentation index and visual previews.
 - [`docs/architecture.md`](docs/architecture.md) — arc42-style architecture documentation.
 - [`docs/gameplay.md`](docs/gameplay.md) — Gameplay systems, venues, and the escalation model.
+- [`docs/hollywood-boulevard-map.md`](docs/hollywood-boulevard-map.md) — Real-site references, game mapping and limitations for the Hollywood venue.
+- [`docs/joke-shop-map.md`](docs/joke-shop-map.md) — Real-site references, game mapping and limitations for the Joke Shop / Sunset Strip venue.
 - [`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/npc-visual-review.md`](docs/npc-visual-review.md) — 0.9.4 NPC baseline, acceptance criteria and ranked visual gaps.
+- [`docs/npc-proportion-audit.md`](docs/npc-proportion-audit.md) — NPC proportion measurements against the shared stylized guide.
 - [`docs/adr/`](docs/adr/) — Architecture Decision Records.
-- [`TODO.md`](TODO.md) — Active tasks plus the v1.0.0 gap analysis and milestone roadmap.
+- [`TODO.md`](TODO.md) — Active tasks plus the 0.x gap analysis and milestone roadmap.
 
 ## Development Status
 
-v0.8.0 adds the first-shift tutorial, campaign shell, checkpoint resume,
+v0.9.4 is the current source version: the completed NPC visual optimization
-difficulty presets and an in-game Help overlay on top of the v0.7.x venue, gear,
+(face/head depth, hands and gear placement, shoes/boots, headgear clearance and
-judge and Desktop HQ work. See [`docs/development-status.md`](docs/development-status.md)
+the 8,000/8,000 mesh budget), on top of the v0.9.3 UI/accessibility polish
-for the implemented list and [`TODO.md`](TODO.md) for the v1.0.0 roadmap. Manual
+pass and v0.9.2's Hollywood/Joke Shop map rebuilds. It builds on
+v0.9.1's Godot 4.7.2 baseline, v0.9.0's production-quality pass, v0.8's
+tutorial/campaign/resume work and the v0.7.x venue/gear/judge work. See [`docs/development-status.md`](docs/development-status.md)
+for the implemented list and [`TODO.md`](TODO.md) for the 0.x roadmap. Manual
 verification uses the [`docs/smoke-checklist.md`](docs/smoke-checklist.md).
 
 ## Development Workflow

TODO.md

@@ -3,12 +3,13 @@
 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
+## Gap Analysis and 0.x Roadmap
 
-Baseline: **v0.8.1** (2026-11-01). Three playable venues, tutorial/campaign/checkpoint resume,
+Baseline: **v0.9.4** (2026-11-02). Three playable venues, tutorial/campaign/checkpoint resume,
-difficulty/help, a complete escalation/access/radio loop, shift review, the Blender asset library,
+difficulty/help, audio/accessibility settings, a 24-NPC budget baseline, a complete
-249 headless + 94 Python tests, a clean screen-design judge and an optional Forward+ Desktop HQ
+escalation/access/radio loop, shift review, the Blender asset library, 262 headless + 101 Python
-build. This is a strong first-hour vertical slice, not yet a 1.0 product.
+tests, a 21/21 clean screen-design judge and an optional Forward+ Desktop HQ build. This is a strong
+release-candidate foundation, not yet a 0.10.0 release candidate.
 
 ### Documentation audit (completed 2026-11-01)
 
@@ -27,60 +28,195 @@ build. This is a strong first-hour vertical slice, not yet a 1.0 product.
       decisions (ADRs), status (`development-status.md`), roadmap (`TODO.md`), operations
       (tooling/release docs).
 
-### Gap register
+### Gap register (remaining roadmap)
 
-| Area | Current baseline | Gap to 1.0 | Risk | Milestone |
+| Area | Current baseline | Remaining gap | 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 |
+| Content and balance | 3 venues with validated 12+ event matrices, recovery events and contextual dialogue | External playtest evidence, balance/fairness pass, event-weight tuning and final content lock | Repetition or unfair outcomes survive into the release candidate | 0.10.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 |
+| Dialog/UI | Audited terminology, copy, button states, focus/navigation, modal close, long strings and all 21 screen captures | Keep the capture/compare/judge gate current as content changes | Low; the remaining risk is drift after new UI is added | Complete (0.9.3) |
-| 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 |
+| Animation/presentation | Procedural pose layers, portrait captures, reduced hem clipping, 8,000/8,000 NPC cap | Thorough NPC silhouette/face/gear/pose/LOD optimization before visual QA | Close-up jank reduces perceived quality | Complete (0.9.4) |
-| 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 |
+| Audio/accessibility | Procedural ambience/SFX, volume controls, captions/reduce-motion settings, searchable Help | Full accessibility/localization acceptance review, audio caption coverage and P0/P1 fixes | Public release cannot claim accessible play | 0.10.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 |
+| Localization | English JSON table, validation and input-generated Help | Pseudo-locale/layout audit and translator workflow sign-off | Text expansion/clipping at release | 0.10.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 |
+| Performance/platform | 24-NPC headless budget (6.9 ms), Compatibility/Web/HQ paths | Target hardware matrix, Web/HQ manual profiling, frame-time/memory evidence | Platform-specific drops or startup failures | 0.9.6 / 0.10.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 |
+| Save lifecycle | Settings/campaign/history/checkpoint files, atomic writes | Migration fixtures from 0.8/0.9, fresh-install/upgrade verification, rollback instructions | Player progress loss on upgrade | 0.10.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 |
+| QA/CI | Headless suite, smokes, screenshot compare, 21/21 judge | Release-candidate smoke matrix, final gallery and release dry run | Regressions escape the release gate | 0.9.6 / 0.10.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 |
+| Release/legal | Unsigned desktop/macOS builds, Web/HQ packages | Signing/notarization decision, checksums, AI-asset provenance, credits, privacy/body-camera and rating review | Public release blocked by trust/policy | 0.10.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 |
+| Documentation | Architecture/ADR/status/roadmap ownership established | Final README/changelog/status/TODO/smoke-checklist sign-off and known-limitations page | Docs drift at launch | 0.9.6 / 0.10.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 |
+| Future 0.x | Stable 0.x feature set | Live replay, more venues, VO/music, image-to-mesh props and seasonal content | Scope creep before release | 0.11.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.9.5 — Release candidate
+**Current priority:** map optimization, the **pre-build NPC revisit**, the
+**0.9.3 UI polish** and **0.9.4 NPC visual optimization** passes are complete
+(all moved to `DONE.md` on 2026-11-02). 0.9.5 texture refinement, 0.9.6
+integration and the 0.10.0 release candidate are queued. The source version is
+now 0.9.4.
 
-Goal: freeze content, prove it with external players, clear release/legal blockers and verify
+## Postponed — Patch 0.9.5 — Texture and material refinement
-every distribution path.
 
-- [ ] Content lock and external playtest round (at least five first-time players); triage findings
+Goal: improve close-range surface and character texture quality while keeping GL
-      by severity and fix all P0/P1 issues.
+Compatibility/Web parity, deterministic assets and offline CI.
-- [ ] 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
+### Environment textures and materials
 
-Goal: publish a stable, documented and supportable 1.0 build.
+- [ ] Audit the v2 picks (brick, sidewalk pavers, dry/wet asphalt, awning canvas,
+      day/dusk/night skylines) at close range and in the entrance/street shots for
+      seams, tiling, scale, contrast and normal-map strength.
+- [ ] Refine brick mortar/wear, paver joints/stains, asphalt aggregate/wet response
+      and awning weave using the existing image/asset tooling; never overwrite a
+      pick, use `-vN` candidates and promote validated results.
+- [ ] Check UV scales and material roughness/metallic profiles; keep day/night
+      phase behavior and the wet-street transition intact.
+- [ ] Review distant skyline haze and foliage/planter surfaces against the concept
+      references; fix obvious flatness without regressing readability.
 
-- [ ] Freeze content and version, run full final QA on Windows/Linux/macOS/Web/Desktop HQ, and
+### Character and prop textures
-      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
+- [ ] Audit NPC skin, cloth, pants, hair and gear albedo/normal/AO maps in portraits;
+      refine fabric weave, skin variation and fixed detail materials.
+- [ ] Re-bake AO where geometry changes; verify the 256² maps and material wiring.
+- [ ] Audit library props and UI/card/icon textures at their actual screen sizes;
+      remove blurry/oversized or unused textures where safe.
+- [ ] Run texture audits, import, and the full asset test suite; record texture memory
+      and triangle/draw-call impact.
+
+### Visual verification
+
+- [ ] Run `python3 tools/scene_concepts.py realism` for the affected stages with the
+      judge enabled; record metric gaps and model/spend.
+- [ ] Re-run `tools/check_screenshots.sh` and the screen-design judge; clear all
+      `diff` verdicts.
+- [ ] Capture before/after close-ups for brick, pavement, asphalt, character cloth
+      and skyline; document accepted trade-offs.
+- [ ] Update asset docs and the changelog/status with the promoted texture versions.
+
+## Postponed — Patch 0.9.6 — Integration, performance and judge gate
+
+Goal: integrate the UI/model/texture patches, prove the combined build on the
+target paths and leave a clean release-candidate handoff.
+
+### Integration and asset rebuild
+
+- [ ] Rebuild all changed Blender/GLB/AO assets, re-import, and verify manifest/fit/
+      audit coverage.
+- [ ] Run the complete headless suite, Python tooling and smoke matrix; fix any
+      regression from the three polish patches.
+- [ ] Re-run the 24-NPC budget smoke and record frame time, mesh count and any
+      texture-memory change; check Web and Desktop HQ if available.
+- [ ] Verify save/campaign/tutorial behavior is unchanged by the visual/UI patches.
+
+### Visual gallery and judge gate
+
+- [ ] Recapture the full gallery, portraits, venue/realsim stages and Desktop HQ A/B
+      as needed; no stale screenshots in the release set.
+- [ ] Run `tools/check_screenshots.sh`, `screen_designs.py compare` and
+      `screen_designs.py judge` on the final captures.
+- [ ] Run the realism judge for the affected concepts with a pinned model; record
+      model, attempt count, spend and verdicts.
+- [ ] Review all `review` verdicts manually; convert unexplained layout/composition
+      mismatches into fixes or explicit known limitations.
+- [ ] Ensure generated realism folders remain gitignored/local-only and only the
+      durable report decisions/docs are committed.
+
+### Release-candidate handoff
+
+- [ ] Update README, architecture, development status, changelog and TODO with the
+      final patch-level results and any remaining gaps.
+- [ ] Tag/version or otherwise freeze `0.9.6` as the integration checkpoint before
+      the `0.10.0` release candidate.
+- [ ] Exit: combined build is functionally green, visually reviewed, performance
+      measured and ready for the 0.10.0 content-lock/playtest phase.
+
+## Postponed — Milestone 0.10.0 — Release candidate
+
+Goal: freeze the feature set, prove it with external players, clear release/legal blockers and
+verify every distribution path. This is the next minor release after the 0.9.x patch line.
+
+### Content lock and external playtest
+
+- [ ] Declare a content/feature freeze for 0.10.0; only release-blocking fixes and balance changes
+      may land after the freeze.
+- [ ] Produce a release-candidate build with the tutorial, campaign, all three venues, Help,
+      accessibility settings and checkpoint/resume enabled.
+- [ ] Run at least five first-time-player sessions covering the tutorial and one full venue shift;
+      record where players get stuck, misunderstand evidence or choose disproportionate escalation.
+- [ ] Triage findings by severity (P0/P1/P2) and fix every P0/P1 onboarding/accessibility issue;
+      keep the rest as explicit known limitations or post-0.10 items.
+- [ ] Re-run the affected tutorial/campaign smokes after each fix and capture a fresh first-hour
+      walkthrough for the release notes.
+
+### Balance and fairness pass
+
+- [ ] Define measurable targets for routine compliance, access-decision accuracy, peaceful
+      resolution, justified emergency calls and false-positive/false-negative rates.
+- [ ] Run scripted venue sweeps across easy/normal/hard and all four phases; compare outcomes and
+      tune event weights, reaction tables, compliance and report strictness where targets fail.
+- [ ] Review emergency calls against actual danger: no routine behavior should make emergency the
+      dominant winning move, and genuine threats must remain answerable.
+- [ ] Verify the reputation grades, debrief explanations and campaign progression still communicate
+      the de-escalation-first design after tuning.
+- [ ] Record the balance evidence and any deliberate exceptions in `docs/development-status.md`
+      or `MEMORY.md`.
+
+### Save migration and session reliability
+
+- [ ] Add fixtures for a 0.8-era settings/campaign/history save and a 0.9.0 checkpoint; verify
+      migration/default-filling and a clean first launch with no files.
+- [ ] Test fresh install → tutorial → campaign → pause → quit → resume → review → next venue on
+      an isolated user-data directory.
+- [ ] Test corrupt JSON, partial temp files, missing optional fields and a failed atomic rename;
+      confirm fallback behavior never destroys a valid save.
+- [ ] Verify checkpoint resume after all three venues, after an incident, with NPCs at the door and
+      with flashlight/body-camera/door state set.
+- [ ] Document save locations, schema versions, reset behavior and rollback/export instructions in
+      `docs/getting-started.md` and the release notes.
+
+### Release engineering and distribution
+
+- [ ] Run `tools/build_releases.sh` from a clean checkout and verify Linux/Windows/macOS/Web/HQ
+      artifact names, sizes and checksums.
+- [ ] Smoke-test fresh Linux portable/AppImage, Windows portable/installer, macOS unzip/launch,
+      Web static hosting and Desktop HQ Vulkan fallback on the target matrix.
+- [ ] Add a disk-space preflight and retention policy to the release/publish scripts so a full
+      Gitea host cannot leave a partially uploaded release.
+- [ ] Verify release metadata, tag/version consistency, asset counts and download links; retain
+      at least the latest 0.8/0.9 releases and document older-asset pruning.
+- [ ] Decide and document whether macOS signing/notarization is required for 0.10.0 or explicitly
+      remains a future release blocker; record the quarantine instructions either way.
+
+### Legal, credits and platform policy
+
+- [ ] Audit AI-assisted asset provenance and licenses; record source/model usage and any
+      redistribution constraints for textures, characters, props and UI art.
+- [ ] Audit audio/SFX/music licensing (or confirm everything is procedural) and add a credits file.
+- [ ] Review body-camera/privacy language, mental-health-crisis representation, age/content rating
+      and storefront requirements; fix any release-blocking copy or content.
+- [ ] Add the player-facing credits, known limitations, accessibility statement and privacy note to
+      the release package/README.
+- [ ] Mark external legal/storefront approval as complete or explicitly block the 0.10.0 release on it.
+
+### Documentation and visual sign-off
+
+- [ ] Update `README.md`, `PLAN.md`, `docs/architecture.md`, ADRs, `docs/development-status.md`,
+      `docs/getting-started.md`, `docs/smoke-checklist.md`, `CHANGELOG.md` and this roadmap.
+- [ ] Regenerate the full screenshot gallery and realism baselines after content lock; run
+      `check_screenshots.sh` and the pinned vision judge, recording model/spend/verdicts.
+- [ ] Run the manual smoke checklist on every target and attach/link the release-candidate evidence.
+- [ ] Verify the tutorial/campaign/help text at maximum font scale and with the longest strings.
+- [ ] Remove or archive stale plans/notes and confirm no contradictory version/status claims remain.
+
+### Release-candidate QA and exit
+
+- [ ] Run the complete headless suite, Python tooling, tutorial/campaign/session/scenario smokes,
+      24-NPC budget smoke and release build from a clean checkout.
+- [ ] Run the manual QA matrix: fresh install, upgrade, offline launch, gamepad, accessibility
+      settings, pause/resume, all venues and Desktop HQ fallback.
+- [ ] Confirm no P0/P1 defects remain; P2 items must be documented as known limitations or
+      post-0.10 work.
+- [ ] Create the `v0.10.0` version bump, changelog entry and tag; build/publish the release and
+      verify all assets and download links.
+- [ ] Exit: the release candidate is content-locked, externally played, legally reviewed,
+      documented, reproducibly built, and approved as the 0.10.0 release candidate.
+
+## Future 0.x / non-blocking candidates
 
 - [ ] Live 3D body-camera replay.
 - [ ] Additional venues or seasonal events.

assets/models/blender/manifest.json

@@ -28,12 +28,12 @@
       "attach": "back",
       "bounds_godot": {
         "max": [
-          0.15,
+          0.161,
-          0.3,
+          0.296,
-          0.141
+          0.212
         ],
         "min": [
-          -0.15,
+          -0.161,
           -0.12,
           -0.319
         ]
@@ -42,11 +42,11 @@
       "materials": [
         "pack_nylon",
         "steel",
-        "plastic_black"
+        "denim_bag"
       ],
       "path": "assets/models/blender/npc_gear/backpack.glb",
-      "triangles": 316,
+      "triangles": 380,
-      "vertices": 360
+      "vertices": 408
     },
     "beanie": {
       "attach": "head",
@@ -453,7 +453,7 @@
         "max": [
           0.321,
           1.824,
-          0.185
+          0.189
         ],
         "min": [
           -0.321,
@@ -467,8 +467,8 @@
         "skin",
         "cloth",
         "pants",
-        "eye_white",
         "accessory",
+        "eye_white",
         "hair",
         "rubber"
       ],
@@ -487,15 +487,15 @@
         "accessory",
         "hair"
       ],
-      "triangles": 3974,
+      "triangles": 4482,
-      "vertices": 3744
+      "vertices": 4260
     },
     "npc_coat": {
       "bounds_godot": {
         "max": [
           0.332,
           1.824,
-          0.185
+          0.189
         ],
         "min": [
           -0.332,
@@ -509,8 +509,8 @@
         "skin",
         "cloth",
         "pants",
-        "eye_white",
         "accessory",
+        "eye_white",
         "hair",
         "rubber"
       ],
@@ -528,8 +528,8 @@
         "accessory",
         "hair"
       ],
-      "triangles": 5026,
+      "triangles": 5474,
-      "vertices": 4807
+      "vertices": 5264
     },
     "npc_dress": {
       "bounds_godot": {
@@ -550,8 +550,8 @@
         "skin",
         "cloth",
         "pants",
-        "eye_white",
         "accessory",
+        "eye_white",
         "hair",
         "rubber"
       ],
@@ -567,8 +567,8 @@
         "accessory",
         "hair"
       ],
-      "triangles": 4428,
+      "triangles": 4900,
-      "vertices": 4026
+      "vertices": 4719
     },
     "npc_firefighter": {
       "bounds_godot": {
@@ -589,8 +589,8 @@
         "skin",
         "cloth",
         "pants",
-        "eye_white",
         "accessory",
+        "eye_white",
         "hair",
         "hivis",
         "reflective",
@@ -608,15 +608,15 @@
         "accessory",
         "hair"
       ],
-      "triangles": 4848,
+      "triangles": 5344,
-      "vertices": 4735
+      "vertices": 5494
     },
     "npc_guard": {
       "bounds_godot": {
         "max": [
           0.361,
           1.819,
-          0.185
+          0.189
         ],
         "min": [
           -0.361,
@@ -630,8 +630,8 @@
         "skin",
         "cloth",
         "pants",
-        "eye_white",
         "accessory",
+        "eye_white",
         "hair",
         "rubber",
         "leather",
@@ -652,15 +652,15 @@
         "accessory",
         "hair"
       ],
-      "triangles": 4560,
+      "triangles": 5046,
-      "vertices": 4529
+      "vertices": 5096
     },
     "npc_hoodie": {
       "bounds_godot": {
         "max": [
           0.326,
           1.856,
-          0.185
+          0.189
         ],
         "min": [
           -0.326,
@@ -674,8 +674,8 @@
         "skin",
         "cloth",
         "pants",
-        "eye_white",
         "accessory",
+        "eye_white",
         "hair",
         "rubber"
       ],
@@ -693,15 +693,15 @@
         "accessory",
         "hair"
       ],
-      "triangles": 4826,
+      "triangles": 5304,
-      "vertices": 4504
+      "vertices": 4950
     },
     "npc_jacket": {
       "bounds_godot": {
         "max": [
           0.332,
           1.824,
-          0.185
+          0.189
         ],
         "min": [
           -0.332,
@@ -715,8 +715,8 @@
         "skin",
         "cloth",
         "pants",
-        "eye_white",
         "accessory",
+        "eye_white",
         "hair",
         "rubber"
       ],
@@ -734,15 +734,15 @@
         "accessory",
         "hair"
       ],
-      "triangles": 4394,
+      "triangles": 4872,
-      "vertices": 4175
+      "vertices": 4661
     },
     "npc_vest": {
       "bounds_godot": {
         "max": [
           0.321,
           1.819,
-          0.185
+          0.189
         ],
         "min": [
           -0.321,
@@ -756,8 +756,8 @@
         "skin",
         "cloth",
         "pants",
-        "eye_white",
         "accessory",
+        "eye_white",
         "hair",
         "rubber",
         "hivis",
@@ -775,8 +775,8 @@
         "accessory",
         "hair"
       ],
-      "triangles": 4474,
+      "triangles": 4980,
-      "vertices": 4340
+      "vertices": 4879
     },
     "palm_tree": {
       "bounds_godot": {

content/strings.en.json

@@ -1,5 +1,5 @@
 {
-  "hud.controls": "LMB/Space wheel · A/D step · Space confirm · Esc cancel · R emergency · E inspect · C wand · Q polite · B camera · Tab/wheel cycle · Shift slow · G light · L lock · F debug",
+  "hud.controls": "LMB/Space wheel · A/D step · Space confirm · Esc cancel · R emergency · E inspect · C wand · Q ask · B camera · Tab/wheel cycle · Shift slow · G light · L lock · F debug",
   "radial.raise_hand": "Stop",
   "radial.eye_contact": "Look",
   "radial.point": "Point",
@@ -100,5 +100,110 @@
   "tutorial.radio": "Open the assistance radio and submit a short report.",
   "tutorial.review": "Finish the shift and review what happened.",
   "tutorial.completed": "Tutorial complete.",
-  "tutorial.skipped": "Tutorial skipped."
+  "ui.inspect_actions": "A = admit · D = refuse entry",
+  "ui.wand_actions": "A = admit · D = refuse entry",
+  "ui.radio_send_assist": "Send request",
+  "ui.radio_send_emergency": "Send emergency",
+  "ui.radio_hold_hint": "Hold the button for %.1fs",
+  "ui.radio_cancelled": "Call not sent — hold the button to confirm.",
+  "ui.radio_holding": "Holding… %.0f%%",
+  "ui.review_return_menu": "Return to menu",
+  "ui.quit_game": "Quit game",
+  "ui.apply_settings": "Apply settings",
+  "tutorial.skipped": "Tutorial skipped.",
+  "ui.settings_title": "Settings",
+  "ui.settings_invert": "Invert vertical look",
+  "ui.settings_head_bob": "Head bob and camera motion",
+  "ui.settings_difficulty": "Difficulty / pacing",
+  "ui.settings_reduce_motion": "Reduce motion",
+  "ui.settings_captions": "Captions / subtitles",
+  "ui.settings_replay": "Replay tutorial",
+  "ui.settings_reset_campaign": "Reset campaign",
+  "ui.settings_controls_help": "Controls (click a binding, then press a key or pad button)",
+  "ui.settings_cancel": "Cancel",
+  "ui.settings_reset_title": "Reset campaign",
+  "ui.settings_reset_confirm": "Clear campaign progress and restart from the Hollywood Boulevard shift?",
+  "ui.settings_replay_title": "Replay tutorial",
+  "ui.settings_replay_confirm": "Replay the tutorial from the Hollywood Boulevard shift? The current shift will end.",
+  "ui.settings_press": "Press…",
+  "ui.pause_title": "Paused",
+  "ui.pause_resume": "Resume",
+  "ui.pause_restart": "Restart shift",
+  "ui.pause_settings": "Settings",
+  "ui.pause_menu": "Quit to menu",
+  "ui.pause_hint": "Esc resumes",
+  "ui.help_title": "Help",
+  "ui.help_filter": "Filter controls…",
+  "ui.help_close": "Close",
+  "help.control_move": "Movement: W/A/S/D · mouse look · Shift precision walk",
+  "help.control_focus": "Focus: crosshair cone · Tab / mouse wheel cycles nearby people",
+  "help.control_wheel": "Action wheel: Space or left click · A/D or arrows step · Space confirms",
+  "help.control_access": "Inspect access: E · Wand: C · Ask: Q",
+  "help.control_escalate": "Warning: 4 · Blocking: 5 · Security radio: 6",
+  "help.control_emergency": "Emergency radio: R, hold the on-screen button to confirm",
+  "help.control_tools": "Body camera: B · Flashlight: G · Door lock: L",
+  "help.control_misc": "Pause: Esc · Debug overlay: F",
+  "ui.start_title": "GIG LINE",
+  "ui.start_subtitle": "Pick a venue to start your shift.",
+  "ui.start_help": "Help",
+  "ui.start_settings": "Settings",
+  "ui.start_hint": "Up/Down to choose · Enter to start · Esc to quit",
+  "ui.campaign_complete": "Campaign complete — pick any venue for a free shift.",
+  "ui.campaign_status": "Campaign shift %d · next: %s",
+  "ui.continue_shift": "Continue shift — %s",
+  "ui.campaign_complete_short": "Campaign complete",
+  "ui.radio_location_placeholder": "Location (e.g. front steps)",
+  "ui.radio_location_default": "front entrance",
+  "ui.radio_description_placeholder": "Describe the person and their behavior",
+  "ui.radio_weapon": "Weapon seen",
+  "ui.radio_danger": "Danger level: ",
+  "ui.radio_cancel": "Cancel",
+  "ui.radio_target": "Target: %s",
+  "ui.radio_title_emergency": "EMERGENCY RADIO",
+  "ui.radio_title_assist": "RADIO DISPATCH",
+  "hud.mode": "Door: %s · Light: %s",
+  "hud.door_locked": "LOCKED",
+  "hud.door_open": "open",
+  "hud.light_on": "on",
+  "hud.light_off": "off",
+  "hud.rec": "REC",
+  "hud.cam_clock": "SHIFT %02d:%02d:%02d",
+  "hud.shift_status": "shift %02d:%02d  phase %s\nrep %.0f  crowd %.0f%%",
+  "hud.inspect_text": "ACCESS INSPECTION\n\nAccess check — %s\nGranted: %s",
+  "hud.wand_text": "Wand check — %s\nAlert: %s",
+  "hud.wand_items": "Carried items: %s",
+  "hud.yes": "YES",
+  "hud.no": "NO",
+  "hud.wand_none": "none",
+  "review.title": "Shift Review",
+  "review.venue": "Venue: %s",
+  "review.policy": "Policy: %s",
+  "review.grade": "Grade: %s   Score: %.0f/100",
+  "review.history": "Shifts on record: %d · best score: %.0f · grades seen: %s",
+  "review.incidents": "Incidents handled: %d (peaceful %d)",
+  "review.npcs": "NPCs encountered: %d",
+  "review.radio": "Radio battery: %.0f%%   emergency cooldown: %.0fs",
+  "review.crowd": "Crowd mood: %.0f%% (panic: %s)",
+  "review.highlights": "Highlights:",
+  "review.modifier": "  %s  (%s)  %s",
+  "review.continue_campaign": "Continue campaign",
+  "review.campaign_complete": "Campaign complete. Free-play venues remain available.",
+  "review.campaign_next": "Campaign shift %d complete · next: %s",
+  "venue.hollywood.label": "Hollywood Boulevard",
+  "venue.hollywood.blurb": "Building entrance, tourists and late-night trouble.",
+  "venue.hollywood_day.label": "Hollywood Boulevard — Day",
+  "venue.hollywood_day.blurb": "El Capitan entrance in daylight: tourists, performers and routine traffic.",
+  "venue.hollywood_night.label": "Hollywood Boulevard — Night",
+  "venue.hollywood_night.blurb": "The same entrance after dark: banners lit, late crowd, harder to read.",
+  "venue.joke.label": "The Joke Shop",
+  "venue.joke.blurb": "Guest list, IDs and wand screening.",
+  "venue.studio.label": "Late Night TV Studio",
+  "venue.studio.blurb": "Credentials, filming boundary, celebrity arrivals.",
+  "hud.reasons": "Reasons: %s",
+  "hud.issues": "Issues: %s",
+  "hud.wand_suspicious": "The wand alerts on a suspicious item (%s).",
+  "hud.wand_ask": "Ask the guest to identify it before deciding.",
+  "hud.wand_harmless": "The wand alerts on a harmless item (%s).",
+  "hud.wand_false": "Likely a false alarm — keys, belt, or phone.",
+  "hud.wand_clear": "No alert. The guest appears clear."
 }

content/venues/hollywood_building.tres

@@ -18,6 +18,12 @@ display_name = "Tourist"
 temperament = 0.1
 base_compliance = 0.9
 dialogue_lines = Array[String](["Oh sure, sorry, just taking a picture.", "Is there a better spot to stand?", "Understood, moving."])
+context_lines = {
+"deescalation": ["Okay, I'll move to the sidewalk.", "Sorry, I'll put the camera away."],
+"reason": ["Just getting a photo of the entrance.", "I'm meeting friends here."],
+"recognition": ["You remember me from the tour, right?"],
+"refusal": ["I just want a photo, I'm not staying.", "I didn't know this entrance was restricted."]
+}
 
 [sub_resource type="Resource" id="Resource_qe635"]
 script = ExtResource("2_7qk8j")
@@ -27,6 +33,11 @@ npc_type = 3
 temperament = 0.2
 base_compliance = 0.85
 dialogue_lines = Array[String](["Wait, this isn't the entrance?", "Sorry about that, I'm a bit lost."])
+context_lines = {
+"deescalation": ["Oh, I understand. I'll check with the box office."],
+"reason": ["I thought this was the box office.", "I'm looking for the event entrance."],
+"refusal": ["I'm sure the event is here. Let me check my phone."]
+}
 
 [sub_resource type="Resource" id="Resource_u5nrp"]
 script = ExtResource("2_7qk8j")
@@ -34,6 +45,9 @@ id = "delivery"
 display_name = "Delivery Worker"
 npc_type = 10
 dialogue_lines = Array[String](["Where should I leave this?"])
+context_lines = {
+"reason": ["Drop-off for the venue. Where should I leave it?"]
+}
 
 [sub_resource type="Resource" id="Resource_dsavb"]
 script = ExtResource("2_7qk8j")
@@ -49,6 +63,9 @@ reactions_by_level = {
 3: 30
 }
 }
+context_lines = {
+"reason": ["Just doing my act; I'll keep the sidewalk clear."]
+}
 
 [sub_resource type="Resource" id="Resource_sexiy"]
 script = ExtResource("2_7qk8j")
@@ -79,6 +96,9 @@ reactions_by_level = {
 }
 }
 dialogue_lines = Array[String](["This is public sidewalk, you can't stop me from filming."])
+context_lines = {
+"reason": ["Filming a quick clip for my channel."]
+}
 
 [sub_resource type="Resource" id="Resource_ghqd8"]
 script = ExtResource("2_7qk8j")
@@ -101,6 +121,9 @@ reactions_by_level = {
 }
 }
 reaction_delay = 1.8
+context_lines = {
+"reason": ["Looking for my friends. I think they went inside."]
+}
 
 [sub_resource type="Resource" id="Resource_g8peq"]
 script = ExtResource("2_7qk8j")
@@ -139,6 +162,9 @@ reactions_by_level = {
 }
 }
 dialogue_lines = Array[String](["I'm just here to see a friend, come on.", "I'll be inside for ten seconds."])
+context_lines = {
+"reason": ["Meeting a friend inside. I'll only be a minute.", "Just cutting through."]
+}
 
 [sub_resource type="Resource" id="Resource_4xl5p"]
 script = ExtResource("2_7qk8j")
@@ -178,6 +204,9 @@ reactions_by_level = {
 }
 }
 reaction_delay = 2.4
+context_lines = {
+"reason": ["I just need a quiet minute.", "I'm waiting for someone."]
+}
 
 [sub_resource type="Resource" id="Resource_y6282"]
 script = ExtResource("2_7qk8j")
@@ -213,6 +242,9 @@ reactions_by_level = {
 7: 30
 }
 }
+context_lines = {
+"reason": ["Back off. This doesn't concern you."]
+}
 
 [sub_resource type="Resource" id="Resource_75a0r"]
 script = ExtResource("2_7qk8j")
@@ -250,6 +282,9 @@ reactions_by_level = {
 }
 }
 dialogue_lines = Array[String](["I have every right to be on public sidewalk.", "You can't touch me, this is a lawful protest."])
+context_lines = {
+"reason": ["We're demonstrating on the public sidewalk.", "This is a peaceful protest."]
+}
 
 [sub_resource type="Resource" id="Resource_ix35t"]
 script = ExtResource("2_7qk8j")
@@ -263,6 +298,9 @@ default_reactions = {
 0: 100
 }
 }
+context_lines = {
+"reason": ["I'm on staff. I'm checking the entrance.", "Crew check-in; I'm working tonight."]
+}
 
 [sub_resource type="Resource" id="Resource_0mcg3"]
 script = ExtResource("2_7qk8j")
@@ -281,12 +319,15 @@ default_reactions = {
 2: 12
 }
 }
+context_lines = {
+"reason": ["I'm on the guest list. Here's my ID.", "A friend invited me; I have a ticket."]
+}
 
 [resource]
 script = ExtResource("3_lvgx2")
 id = "hollywood_building"
-display_name = "Hollywood Boulevard Building"
+display_name = "El Capitan Entertainment Centre"
-description = "Steps and entrance of a private building off Hollywood Boulevard."
+description = "The historic 1921 Masonic Temple at 6840 Hollywood Boulevard, now the El Capitan Entertainment Centre."
 access_policy = SubResource("Resource_xf4wh")
 equipment = Array[String](["wristband_policy", "flashlight", "radio"])
 locations = {
@@ -371,6 +412,33 @@ event_pool = Array[Dictionary]([{
 "time_range_s": Vector2(300, 800)
 }, {
 "base_weight": 1.0,
+"id": "late_tourist",
+"intent": "photo",
+"kind": "routine",
+"npc_type": 0,
+"phase": 3,
+"probability": 0.22,
+"time_range_s": Vector2(700, 900)
+}, {
+"base_weight": 1.0,
+"id": "late_guest",
+"intent": "enter",
+"kind": "routine",
+"npc_type": 9,
+"phase": 3,
+"probability": 0.2,
+"time_range_s": Vector2(700, 900)
+}, {
+"base_weight": 1.0,
+"id": "late_trespasser",
+"intent": "trespass",
+"kind": "routine",
+"npc_type": 5,
+"phase": 3,
+"probability": 0.14,
+"time_range_s": Vector2(700, 900)
+}, {
+"base_weight": 1.0,
 "hint": "hint.body_camera_reason",
 "id": "building_filming_boundary",
 "intent": "film",
@@ -459,3 +527,6 @@ shift_phases = {
 "start_s": 700.0
 }
 }
+door_staff_lines = {
+"wristband_check": ["Wristband, please.", "I need to see your event wristband."]
+}

content/venues/joke_shop.tres

@@ -22,6 +22,12 @@ display_name = "Tourist"
 temperament = 0.1
 base_compliance = 0.9
 dialogue_lines = Array[String](["Oh sure, sorry, just taking a picture.", "Is there a better spot to stand?", "Understood, moving."])
+context_lines = {
+"deescalation": ["Okay, I'll move to the sidewalk.", "Sorry, I'll put the camera away."],
+"reason": ["Just getting a photo of the entrance.", "I'm meeting friends here."],
+"recognition": ["You remember me from the tour, right?"],
+"refusal": ["I just want a photo, I'm not staying.", "I didn't know this entrance was restricted."]
+}
 
 [sub_resource type="Resource" id="Resource_r873e"]
 script = ExtResource("2_l60ad")
@@ -31,6 +37,11 @@ npc_type = 3
 temperament = 0.2
 base_compliance = 0.85
 dialogue_lines = Array[String](["Wait, this isn't the entrance?", "Sorry about that, I'm a bit lost."])
+context_lines = {
+"deescalation": ["Oh, I understand. I'll check with the box office."],
+"reason": ["I thought this was the box office.", "I'm looking for the event entrance."],
+"refusal": ["I'm sure the event is here. Let me check my phone."]
+}
 
 [sub_resource type="Resource" id="Resource_3xy2u"]
 script = ExtResource("2_l60ad")
@@ -46,6 +57,9 @@ reactions_by_level = {
 3: 30
 }
 }
+context_lines = {
+"reason": ["Just doing my act; I'll keep the sidewalk clear."]
+}
 
 [sub_resource type="Resource" id="Resource_50i1h"]
 script = ExtResource("2_l60ad")
@@ -76,6 +90,9 @@ reactions_by_level = {
 }
 }
 dialogue_lines = Array[String](["This is public sidewalk, you can't stop me from filming."])
+context_lines = {
+"reason": ["Filming a quick clip for my channel."]
+}
 
 [sub_resource type="Resource" id="Resource_nsw77"]
 script = ExtResource("2_l60ad")
@@ -98,6 +115,9 @@ reactions_by_level = {
 }
 }
 reaction_delay = 1.8
+context_lines = {
+"reason": ["Looking for my friends. I think they went inside."]
+}
 
 [sub_resource type="Resource" id="Resource_20knl"]
 script = ExtResource("2_l60ad")
@@ -136,6 +156,9 @@ reactions_by_level = {
 }
 }
 dialogue_lines = Array[String](["I'm just here to see a friend, come on.", "I'll be inside for ten seconds."])
+context_lines = {
+"reason": ["Meeting a friend inside. I'll only be a minute.", "Just cutting through."]
+}
 
 [sub_resource type="Resource" id="Resource_rivis"]
 script = ExtResource("2_l60ad")
@@ -171,6 +194,9 @@ reactions_by_level = {
 7: 30
 }
 }
+context_lines = {
+"reason": ["Back off. This doesn't concern you."]
+}
 
 [sub_resource type="Resource" id="Resource_1dvkp"]
 script = ExtResource("2_l60ad")
@@ -184,6 +210,9 @@ default_reactions = {
 0: 100
 }
 }
+context_lines = {
+"reason": ["I'm on staff. I'm checking the entrance.", "Crew check-in; I'm working tonight."]
+}
 
 [sub_resource type="Resource" id="Resource_7wsm0"]
 script = ExtResource("2_l60ad")
@@ -202,6 +231,9 @@ default_reactions = {
 2: 12
 }
 }
+context_lines = {
+"reason": ["I'm on the guest list. Here's my ID.", "A friend invited me; I have a ticket."]
+}
 
 [resource]
 script = ExtResource("3_voh88")

content/venues/tv_studio.tres

@@ -22,6 +22,12 @@ display_name = "Tourist"
 temperament = 0.1
 base_compliance = 0.9
 dialogue_lines = Array[String](["Oh sure, sorry, just taking a picture.", "Is there a better spot to stand?", "Understood, moving."])
+context_lines = {
+"deescalation": ["Okay, I'll move to the sidewalk.", "Sorry, I'll put the camera away."],
+"reason": ["Just getting a photo of the entrance.", "I'm meeting friends here."],
+"recognition": ["You remember me from the tour, right?"],
+"refusal": ["I just want a photo, I'm not staying.", "I didn't know this entrance was restricted."]
+}
 
 [sub_resource type="Resource" id="Resource_lmn2c"]
 script = ExtResource("2_g7rkt")
@@ -31,6 +37,11 @@ npc_type = 3
 temperament = 0.2
 base_compliance = 0.85
 dialogue_lines = Array[String](["Wait, this isn't the entrance?", "Sorry about that, I'm a bit lost."])
+context_lines = {
+"deescalation": ["Oh, I understand. I'll check with the box office."],
+"reason": ["I thought this was the box office.", "I'm looking for the event entrance."],
+"refusal": ["I'm sure the event is here. Let me check my phone."]
+}
 
 [sub_resource type="Resource" id="Resource_if2cj"]
 script = ExtResource("2_g7rkt")
@@ -38,6 +49,9 @@ id = "delivery"
 display_name = "Delivery Worker"
 npc_type = 10
 dialogue_lines = Array[String](["Where should I leave this?"])
+context_lines = {
+"reason": ["Drop-off for the venue. Where should I leave it?"]
+}
 
 [sub_resource type="Resource" id="Resource_t47d3"]
 script = ExtResource("2_g7rkt")
@@ -53,6 +67,9 @@ reactions_by_level = {
 3: 30
 }
 }
+context_lines = {
+"reason": ["Just doing my act; I'll keep the sidewalk clear."]
+}
 
 [sub_resource type="Resource" id="Resource_j2mp5"]
 script = ExtResource("2_g7rkt")
@@ -83,6 +100,9 @@ reactions_by_level = {
 }
 }
 dialogue_lines = Array[String](["This is public sidewalk, you can't stop me from filming."])
+context_lines = {
+"reason": ["Filming a quick clip for my channel."]
+}
 
 [sub_resource type="Resource" id="Resource_uscqg"]
 script = ExtResource("2_g7rkt")
@@ -105,6 +125,9 @@ reactions_by_level = {
 }
 }
 reaction_delay = 1.8
+context_lines = {
+"reason": ["Looking for my friends. I think they went inside."]
+}
 
 [sub_resource type="Resource" id="Resource_8aovb"]
 script = ExtResource("2_g7rkt")
@@ -143,6 +166,9 @@ reactions_by_level = {
 }
 }
 dialogue_lines = Array[String](["I'm just here to see a friend, come on.", "I'll be inside for ten seconds."])
+context_lines = {
+"reason": ["Meeting a friend inside. I'll only be a minute.", "Just cutting through."]
+}
 
 [sub_resource type="Resource" id="Resource_owl7s"]
 script = ExtResource("2_g7rkt")
@@ -182,6 +208,9 @@ reactions_by_level = {
 }
 }
 reaction_delay = 2.4
+context_lines = {
+"reason": ["I just need a quiet minute.", "I'm waiting for someone."]
+}
 
 [sub_resource type="Resource" id="Resource_rnay4"]
 script = ExtResource("2_g7rkt")
@@ -217,6 +246,9 @@ reactions_by_level = {
 7: 30
 }
 }
+context_lines = {
+"reason": ["Back off. This doesn't concern you."]
+}
 
 [sub_resource type="Resource" id="Resource_lhp4m"]
 script = ExtResource("2_g7rkt")
@@ -254,6 +286,9 @@ reactions_by_level = {
 }
 }
 dialogue_lines = Array[String](["I have every right to be on public sidewalk.", "You can't touch me, this is a lawful protest."])
+context_lines = {
+"reason": ["We're demonstrating on the public sidewalk.", "This is a peaceful protest."]
+}
 
 [sub_resource type="Resource" id="Resource_s8tjd"]
 script = ExtResource("2_g7rkt")
@@ -267,6 +302,9 @@ default_reactions = {
 0: 100
 }
 }
+context_lines = {
+"reason": ["I'm on staff. I'm checking the entrance.", "Crew check-in; I'm working tonight."]
+}
 
 [sub_resource type="Resource" id="Resource_ii8kq"]
 script = ExtResource("2_g7rkt")
@@ -285,6 +323,9 @@ default_reactions = {
 2: 12
 }
 }
+context_lines = {
+"reason": ["I'm on the guest list. Here's my ID.", "A friend invited me; I have a ticket."]
+}
 
 [resource]
 script = ExtResource("3_jd45y")
@@ -476,3 +517,6 @@ shift_phases = {
 "start_s": 700.0
 }
 }
+door_staff_lines = {
+"ticket_check": ["Ticket, credential, or guest-list confirmation, please.", "I need your ticket or guest-list confirmation."]
+}

docs/README.md

@@ -0,0 +1,36 @@
+# Gig Line Documentation
+
+This folder holds the project documentation, visual references and generated QA evidence.
+
+## Start here
+
+- [`../PLAN.md`](../PLAN.md) — product and game-design plan
+- [`gameplay.md`](gameplay.md) — controls, venues and escalation
+- [`joke-shop-map.md`](joke-shop-map.md) — Sunset Strip real-site mapping
+- [`tutorial.md`](tutorial.md) — first-shift tutorial beats
+- [`architecture.md`](architecture.md) — arc42 system architecture
+- [`getting-started.md`](getting-started.md) — setup, run/test commands and controls
+- [`asset-tooling.md`](asset-tooling.md) — image/model pipelines and screenshot gates
+- [`npc-visual-review.md`](npc-visual-review.md) — NPC visual baseline, acceptance criteria and ranked gaps
+- [`npc-proportion-audit.md`](npc-proportion-audit.md) — NPC proportion ratios and stylized guide results
+- [`development-status.md`](development-status.md) — implemented features and current gaps
+- [`smoke-checklist.md`](smoke-checklist.md) — manual verification
+- [`ui-copy.md`](ui-copy.md) — screen, copy and button inventory
+- [`RELEASING.md`](RELEASING.md) — export, CI and publishing workflow
+- [`adr/README.md`](adr/README.md) — architecture decisions
+
+## Visual references
+
+- [`screens/README.md`](screens/README.md) — concepts, designs, screenshots and realism runs
+- [`blender_previews/README.md`](blender_previews/README.md) — character/gear/prop previews
+- [`screenshots/README.md`](screenshots/README.md) — committed game gallery
+- [`screen-design-report.md`](screen-design-report.md) — latest screen-design judge result
+
+## Quick preview
+
+| Reference | Screenshot |
+| --- | --- |
+| Venue design | <img src="screens/designs/venue_overview.png" width="320" alt="Venue overview design"> |
+| Current entrance | <img src="screenshots/01-venue-overview.png" width="320" alt="In-game venue overview"> |
+| Character sheet | <img src="blender_previews/sheet_npc.jpg" width="320" alt="NPC character sheet"> |
+| Prop sheet | <img src="blender_previews/sheet_props.jpg" width="320" alt="Prop asset sheet"> |

docs/RELEASING.md

@@ -12,11 +12,11 @@ time you export, either:
   matching templates), or
 - Install them manually from the
   [Godot downloads](https://godotengine.org/download/) page by placing the
-  `Godot_v4.3-stable_export_templates.tpz` contents into
+  `Godot_v4.7.2-stable_export_templates.tpz` contents into
-  `~/.local/share/godot/export_templates/4.3.stable/`.
+  `~/.local/share/godot/export_templates/4.7.2.stable/`.
 
-The templates must match the editor binary you use locally. CI pins Godot 4.3;
+The templates must match the editor binary you use locally. CI and local
-the local development machine uses 4.7.2 with its matching templates. Verify with:
+development both use Godot 4.7.2 with its matching templates. Verify with:
 
 ```bash
 godot --headless --export-release "Linux" build/gig-line-smoke.x86_64
@@ -31,7 +31,7 @@ godot --headless --export-release "Linux" build/gig-line-smoke.x86_64
 
 The repository ships a Gitea Actions workflow (`.gitea/workflows/build.yml`):
 
-- Every push/PR runs the **checks** job: Godot 4.3 install, project import, and the
+- Every push/PR runs the **checks** job: Godot 4.7.2 install, project import, and the
   full headless test suite. This is the fast safety net.
 - **Tags (`v*`)** and **manual `workflow_dispatch`** runs additionally execute the
   **build** job: export templates install, import, `tools/build_releases.sh` for
@@ -63,10 +63,12 @@ setup, so do not rely on it.
 > artifacts. If CI publishing fails again, run
 > `./tools/publish_release.sh <version>` from a checkout with `~/.git-credentials`.
 
-> **No `actions/cache` for now:** the runner has no local actions-cache service, so
+> **Godot cache evaluation:** Gitea Actions cache was tested for the Godot binary and
-> `actions/cache` times out against GitHub's cache API. We dropped it (Godot import
+> trimmed 4.7.2 templates. Restores worked intermittently, but cache saves timed out
-> is only ~4s). If a host admin later enables Gitea `[cache.actions]` with a cache
+> in `CreateCacheEntry` / were rejected as reserved by another job. The cache steps
-> server, the step can be reintroduced.
+> were removed because they added restore/save overhead without a reliable hit.
+> Revisit when the host's Gitea Actions cache service is healthy; otherwise keep
+> downloading the binary/templates directly.
 
 > The workflow lives in `.gitea/workflows/` (Gitea's canonical path). The old
 > `.github/workflows/ci.yml` was removed to avoid double runs on hosts that scan

docs/adr/README.md

@@ -0,0 +1,20 @@
+# Architecture Decision Records
+
+Each ADR records the context, decision, consequences and alternatives for a durable architecture choice.
+
+## Decisions
+
+- [0001-venue-driven-simulation-architecture](0001-venue-driven-simulation-architecture.md)
+- [0002-de-escalation-first-escalation-model](0002-de-escalation-first-escalation-model.md)
+- [0003-explicit-access-verification-system](0003-explicit-access-verification-system.md)
+- [0004-local-single-player-first](0004-local-single-player-first.md)
+- [0005-event-based-incident-recording](0005-event-based-incident-recording.md)
+- [0006-godot-4-gdscript](0006-godot-4-gdscript.md)
+- [0007-locomotion-and-input-layers](0007-locomotion-and-input-layers.md)
+- [0008-cone-focus-and-head-ring](0008-cone-focus-and-head-ring.md)
+- [0009-radial-action-menu](0009-radial-action-menu.md)
+- [0010-procedural-npc-presentation](0010-procedural-npc-presentation.md)
+- [0011-aim-free-selection-and-precision-walk](0011-aim-free-selection-and-precision-walk.md)
+- [0012-surface-materials-and-generated-props](0012-surface-materials-and-generated-props.md)
+- [0013-blender-authored-npc-characters](0013-blender-authored-npc-characters.md)
+- [0014-runtime-image-root](0014-runtime-image-root.md)

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. 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.
+- The engine is Godot 4.7.2 with GDScript; a playable prototype vertical slice is implemented. CI, local development and exported builds use 4.7.2; the default renderer stays GL Compatibility for Web parity, with an optional Forward+ Desktop HQ build.
 - Venue-specific policies must be configurable rather than hard-coded into individual NPCs.
 - The game must preserve the de-escalation-first design described in [`PLAN.md`](../PLAN.md).
 - The project uses the repository workflow described in [`AGENTS.md`](../AGENTS.md).
@@ -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.9.0`). 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.9.4`). Each release is tagged in git as `v<version>` (e.g. `v0.6.0`). The `0.x` series is pre-stable, 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
 
@@ -154,6 +154,7 @@ reputation, crowd reaction and shift review read it rather than resolving gamepl
 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.
+5. The menu's **Hollywood Night** row resolves to `hollywood_building`, then sets `ShiftCoordinator.phase_offset_s` so elapsed time starts at 0 but phase lookup starts at `LATE`. The offset is part of the checkpoint snapshot, so a resumed night shift stays at night.
 
 ### Asset fallback
 
@@ -180,7 +181,7 @@ reputation, crowd reaction and shift review read it rather than resolving gamepl
 
 ## 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 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.
+The game is a single-player local client containing presentation, simulation, rules, content, and persistence for local settings and shift results. No online backend is required. A non-threaded Web export ships alongside the desktop builds and can be served from any static host without special headers. The default renderer is GL Compatibility; an optional Desktop HQ zip uses Forward+ with volumetric fog/SDFGI on Vulkan-capable desktops. CI, local development and exported builds use Godot 4.7.2; the light-falloff code keeps a compatibility branch for older editors but the supported baseline is unified.
 
 Future options include external analytics, cloud saves, or replay sharing, but they are not part of the current architecture.
 
@@ -188,7 +189,7 @@ Future options include external analytics, cloud saves, or replay sharing, but t
 
 A continuous-integration pipeline keeps the headless test suite green on every change and publishes tagged releases.
 
-- **Workflow:** `.gitea/workflows/build.yml` runs on pushes, pull requests, tags, and manual dispatches. The `checks` job installs Godot 4.3, imports the project, and runs `res://src/test/test_runner.gd`; it fails on a non-zero exit code or any `SCRIPT ERROR` in the output.
+- **Workflow:** `.gitea/workflows/build.yml` runs on pushes, pull requests, tags, and manual dispatches. The `checks` job installs Godot 4.7.2, imports the project, and runs `res://src/test/test_runner.gd`; it fails on a non-zero exit code or any `SCRIPT ERROR` in the output.
 - **Build job:** runs for tags and manual dispatches. It installs export templates, exports Linux/Windows/macOS and the non-threaded Web build, packages the NSIS installer, Linux AppImage and optional Desktop HQ zip, verifies the installer contents, and uploads the artifacts.
 - **Publish job:** tag builds call `tools/publish_release.sh` to create the Gitea release and upload the standard artifacts plus the optional Desktop HQ zip. The script uses `GITEA_TOKEN` when configured and otherwise reuses the runner's checkout extraheader credentials.
 - **Hosting:** the repository lives on Gitea (`https://git.allucanget.biz/zwitschi/security-game`). Export templates must match the pinned Godot version; macOS builds are unsigned and need quarantine guidance or notarization for wider distribution.
@@ -219,7 +220,7 @@ The release process is: bump the version, run the full test suite and `tools/che
 - **Asset provenance and AI usage:** AI-assisted images/concepts are development inputs only; validated outputs are committed, audited and loaded through the same runtime asset contracts. Generated content must not become an offline/CI dependency.
 - **Campaign and checkpoint state:** `Campaign` owns venue order/progression; settings, campaign, completed shift history and a versioned pause checkpoint are separate JSON documents. The checkpoint snapshots coordinator systems, scheduler RNG and NPC presentation/access state; it deliberately does not serialize the tutorial overlay or transient input state.
 - **Difficulty:** easy/normal/hard only scale spawn pacing, NPC compliance tolerance and report-credibility strictness; access/escalation rules and emergency rarity are invariant.
-- **Settings and accessibility:** volume/motion/caption settings persist through `settings.json`; Help is generated from the input-binding catalogue and the HUD log is the text caption surface. The supported engine matrix is explicit (CI/release 4.3, local 4.7.2) rather than an implicit version drift.
+- **Settings and accessibility:** volume/motion/caption settings persist through `settings.json`; Help is generated from the input-binding catalogue and the HUD log is the text caption surface. CI/release, local development and exported builds are unified on Godot 4.7.2.
 - **Documentation ownership:** `PLAN.md` owns design intent; `docs/gameplay.md` owns playable mechanics; `docs/architecture.md` owns system boundaries, data flow, constraints and cross-cutting decisions; ADRs own decision history; `docs/development-status.md` owns the implemented/gap list; `TODO.md` owns the roadmap; `MEMORY.md` owns gotchas and open questions. Specialized docs link to these rather than becoming competing sources of truth.
 
 ## 9. Architecture Decisions
@@ -252,7 +253,7 @@ Architecture decisions are recorded as ADRs:
 | 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. |
+| Performance | A busy venue should hold its budget at the target NPC cap on desktop and Web; the current 24-NPC check is a baseline, not a release 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
@@ -264,12 +265,12 @@ 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.
+- Godot 4.7.2 is the unified CI/local/project baseline; future engine bumps still require import, visual and export smoke checks before changing that baseline.
 - Content volume and authoring tools are still thin; adding venues/events by editing the factory can become error-prone without schema validation and preview tooling.
 - Save data currently covers settings and shift history, not mid-shift resume; adding saves/replays requires a versioned schema and migration policy.
 - The optional judge and image-generation paths depend on an external key, model availability and budget; CI cannot make them a release gate, and keys must never be committed.
-- Accessibility and localization coverage is partial; a 1.0 release needs subtitles/captions, colour-independent cues, remapping, text expansion tests and at least a documented localization workflow.
+- Accessibility and localization coverage is partial; a public 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.
+- Unsigned macOS builds, AI asset provenance and any storefront/legal requirements are release blockers for a public release.
 - 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. Documentation Consolidation and Ownership
@@ -290,7 +291,7 @@ architecture document.
 | [`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 |
+| [`TODO.md`](../TODO.md) | Active tasks and 0.x roadmap | Planning source; no architecture duplication |
 | [`CHANGELOG.md`](../CHANGELOG.md) | User-facing release history | Release/version companion |
 
 Consolidation decisions:
@@ -298,7 +299,7 @@ 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.
+- **Status and roadmap are separate from architecture.** `docs/development-status.md` records what exists; `TODO.md` records what remains, including the 0.x 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

docs/asset-tooling.md

@@ -196,7 +196,43 @@ 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);
+`capture_npc_review.gd` is the pre-build NPC gate: it stages all eight
+library character models at portrait, conversation and crowd distance on both
+promoted maps in day and night lighting, with the normal crowd hidden. It uses
+the review-only `NpcAvatar.character_override` to include the guard model, which
+has no spawned NPC role:
+
+```bash
+godot --path . --script res://src/test/capture_npc_review.gd -- \
+  --out=res://tmp/npc-review
+```
+
+Contact sheets can be assembled from the files (the output is local QA and is
+not committed). The runtime applies small attach-space offsets to the lanyard
+and firefighter helmet so the badge clears the jacket and the brim does not sit
+over the eyes; these are `NpcAvatar.GEAR_OFFSETS`, not changes to the gear
+contract.
+
+`tools/npc_proportions.py` checks the eight character GLBs against the shared
+height/head/shoulder/hip/torso/leg/arm/foot guide; the current results are in
+[`npc-proportion-audit.md`](npc-proportion-audit.md). It reads the exported GLBs
+and does not require Blender.
+
+`capture_npc_baseline.gd` is the 0.9.4 neutral baseline: eight characters ×
+front/three-quarter/profile/back/full-body/crowd = 48 frames with a fixed
+camera, studio lighting and no venue/HUD/animation. The raw PNGs stay in
+`tmp/`; `tools/npc_baseline.py sheet` builds the committed contact sheet, and
+`tools/npc_baseline.py compare --before DIR --after DIR` builds the review
+comparison after a model change. See
+[`npc-visual-review.md`](npc-visual-review.md).
+
+```bash
+godot --path . --script res://src/test/capture_npc_baseline.gd -- \
+  --out=res://tmp/npc-baseline
+python3 tools/npc_baseline.py sheet --dir tmp/npc-baseline
+```
+
+`capture_realism.gd` runs seven stages (day, portrait, evening, late, Joke Shop day, Joke Shop night, 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
@@ -244,6 +280,9 @@ python3 tools/screen_designs.py generate --draft --only wand --force
 # (requires OPENROUTER_API_KEY)
 python3 tools/screen_designs.py generate
 
+# UI-state gallery (menu, pause, settings, review, radio, wheel, crowd, responder)
+godot --path . --script res://src/test/capture_ui_states.gd -- --out=res://docs/screenshots
+
 # Prop gallery (studio line-up) for close-range prop checks
 godot --path . --script res://src/test/capture_prop_gallery.gd
 
@@ -259,12 +298,11 @@ python3 tools/screen_designs.py judge --only 03-   # one capture
 python3 tools/screen_designs.py judge --dry-run    # build requests, no network
 ```
 
-The catalogue covers 21 screens: the eleven README captures plus the start menu,
+The catalogue covers 21 screens: the thirteen scene captures plus the start menu,
-pause overlay, settings, shift review, radial menu, emergency radio, wand
+pause overlay, settings, shift review, radial menu, emergency radio, crowd panic,
-screening, Joke Shop queue, TV Studio arrival, crowd panic, responder arrival,
+and responder arrival. All 21 have an AI reference in `assets/images/ui/`
-body-camera timeline, and the escalation HUD. All 21 have an AI reference in
+(snapshot in `docs/screens/designs/`) and a committed capture, so every entry is
-`assets/images/ui/` (snapshot in `docs/screens/designs/`); the eleven screens with
+compared or judged against the running game.
-staged captures are also compared or judged against the running game.
 
 `compare` flags gross drift: wrong aspect ratio, undersized frame, near-blank
 frame, and large layout/palette/detail distance. It is a regression gate, not a
@@ -278,8 +316,8 @@ Verdicts are classed as `match`, `review` (a mismatch below `--fail-confidence`,
 default 0.6 — expected when a concept mockup is more stylised than the game), or
 `diff` (a confident mismatch, which exits non-zero). Regenerate the designs after changing screen layout, then re-run
 `compare` after regenerating the game screenshots with
-`src/test/capture_screenshots.gd`.
+`src/test/capture_screenshots.gd` and `src/test/capture_ui_states.gd`.
 
 For a one-command drift check, run `tools/check_screenshots.sh`. It renders the
-staged captures and prop gallery into `docs/screenshots/` (using `xvfb-run` when
+scene captures, UI-state captures and prop gallery into `docs/screenshots/` (using
-no display is available) and then runs `screen_designs.py compare`.
+`xvfb-run` when no display is available) and then runs `screen_designs.py compare`.

docs/blender-assets.md

@@ -5,7 +5,10 @@ Architecture context: the asset contracts and fallback path are summarized in
 
 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.
+with colliders and phase-driven emissives. The 0.9.4 neutral baseline and its
+acceptance criteria are in [`npc-visual-review.md`](npc-visual-review.md);
+the committed 8 × 6 contact sheet is
+[`blender_previews/sheet_npc_baseline.jpg`](blender_previews/sheet_npc_baseline.jpg).
 
 Generator: [`tools/blender_assets.py`](../tools/blender_assets.py). Manifest (the
 source of truth for integration):
@@ -89,10 +92,12 @@ All eight use the `npc_base` contract, so each one can replace
 - material slots `skin`, `cloth`, `pants`, `accessory`, `hair` carry the same
   neutral `assets/textures/npc/<slot>_{albedo,normal}.png` maps, so
   `Materials.npc_slot()` tints them the same way it tints `npc_base`.
-- budget ≤ 6000 triangles and ≤ 5000 vertices (glTF vertex count, after seam
+- budget ≤ **8,000 triangles and ≤ 8,000 glTF vertices** for the eight library
-  splits; `CHAR_MAX_VERTS` in `tools/blender_assets.py`, raised from 4000 for
+  variants (vertex count after seam splits; `CHAR_MAX_TRIS`/`CHAR_MAX_VERTS` in
-  the 2026-11-01 face/hand pass). The current range is 3,974–5,026 triangles
+  `tools/blender_assets.py`, raised from 6,000/5,000 on 2026-11-02). The frozen
-  and 3,744–4,807 vertices.
+  `npc_base` fallback keeps its original 6,000/4,000 contract. The current range
+  is 4,482–5,474 triangles and 4,260–5,494 vertices, leaving room for the
+  remaining grip and clothing detail.
 
 Construction: the torso and limbs are one continuous Skin-modifier mesh,
 subdivided twice, decimated to 26 % with X symmetry, and cut at the waist, cuffs,
@@ -141,6 +146,10 @@ attach point:
 
 The character previews in `sheet_npc.jpg` are built by importing the gear at
 exactly these points, which gives a quick visual check of the convention.
+`NpcAvatar.GEAR_OFFSETS` applies two final-context nudges after attachment:
+the lanyard moves 4 cm forward so its badge clears the jacket, and the
+firefighter helmet moves 3 cm up so its brim sits above the eyes. The
+`fit` report remains an asset-space measurement of the untouched GLBs.
 
 ## Props
 
@@ -170,7 +179,7 @@ carry baked AO and the shared neutral material maps described above.
 
 - `python3 tools/blender_assets.py audit`: container, `POSITION`/`NORMAL`/
   `TEXCOORD_0`, UVs in [0, 1], no zero-area triangles (Godot warns about them
-  during LOD generation), budgets (characters 6000/5000, gear 1500, props 4000
+  during LOD generation), budgets (library characters 8000/8000, base fallback 6000/4000, gear 1500, props 4000
   triangles), grounding, and an editable `.blend`. For characters it also
   checks skinning, bones, slots, the `npc_base` mesh node and the height.
 - `tools/test_blender_assets.py`: catalogue and contract consistency with
@@ -193,3 +202,8 @@ carry baked AO and the shared neutral material maps described above.
   the legs through the hem.
 - Preview colours (`PREVIEW_TINTS`) only stand in for `outfit_for()`. The GLBs
   stay neutral.
+- The 0.9.4 baseline found three P1 portrait issues. The tourist's photo prop
+  now only appears in photo/film poses and the backpack straps were refit as
+  flattened chest bands; the face is still shallow/faceted at portrait range.
+  The full ranked list, measurements and before/after sheet are in
+  [`npc-visual-review.md`](npc-visual-review.md).

docs/blender_previews/README.md

@@ -0,0 +1,66 @@
+# Blender Previews
+
+Committed contact sheets and local Blender renders for the character, gear and prop library. Individual PNGs are development previews and are gitignored; the sheets are tracked.
+
+## Image previews
+
+| Preview | File |
+| --- | --- |
+| <img src="a_frame_sign.png" width="280" alt="a_frame_sign.png"> | [`a_frame_sign.png`](a_frame_sign.png) |
+| <img src="backpack.png" width="280" alt="backpack.png"> | [`backpack.png`](backpack.png) |
+| <img src="beanie.png" width="280" alt="beanie.png"> | [`beanie.png`](beanie.png) |
+| <img src="bench.png" width="280" alt="bench.png"> | [`bench.png`](bench.png) |
+| <img src="bollard.png" width="280" alt="bollard.png"> | [`bollard.png`](bollard.png) |
+| <img src="camera.png" width="280" alt="camera.png"> | [`camera.png`](camera.png) |
+| <img src="cap.png" width="280" alt="cap.png"> | [`cap.png`](cap.png) |
+| <img src="clipboard.png" width="280" alt="clipboard.png"> | [`clipboard.png`](clipboard.png) |
+| <img src="crowd_barrier.png" width="280" alt="crowd_barrier.png"> | [`crowd_barrier.png`](crowd_barrier.png) |
+| <img src="cup.png" width="280" alt="cup.png"> | [`cup.png`](cup.png) |
+| <img src="double_door.png" width="280" alt="double_door.png"> | [`double_door.png`](double_door.png) |
+| <img src="fire_hydrant.png" width="280" alt="fire_hydrant.png"> | [`fire_hydrant.png`](fire_hydrant.png) |
+| <img src="firefighter_helmet.png" width="280" alt="firefighter_helmet.png"> | [`firefighter_helmet.png`](firefighter_helmet.png) |
+| <img src="flashlight.png" width="280" alt="flashlight.png"> | [`flashlight.png`](flashlight.png) |
+| <img src="handrail.png" width="280" alt="handrail.png"> | [`handrail.png`](handrail.png) |
+| <img src="hood.png" width="280" alt="hood.png"> | [`hood.png`](hood.png) |
+| <img src="lanyard.png" width="280" alt="lanyard.png"> | [`lanyard.png`](lanyard.png) |
+| <img src="marquee.png" width="280" alt="marquee.png"> | [`marquee.png`](marquee.png) |
+| <img src="newspaper_box.png" width="280" alt="newspaper_box.png"> | [`newspaper_box.png`](newspaper_box.png) |
+| <img src="npc_casual.png" width="280" alt="npc_casual.png"> | [`npc_casual.png`](npc_casual.png) |
+| <img src="npc_coat.png" width="280" alt="npc_coat.png"> | [`npc_coat.png`](npc_coat.png) |
+| <img src="npc_dress.png" width="280" alt="npc_dress.png"> | [`npc_dress.png`](npc_dress.png) |
+| <img src="npc_firefighter.png" width="280" alt="npc_firefighter.png"> | [`npc_firefighter.png`](npc_firefighter.png) |
+| <img src="npc_guard.png" width="280" alt="npc_guard.png"> | [`npc_guard.png`](npc_guard.png) |
+| <img src="npc_hoodie.png" width="280" alt="npc_hoodie.png"> | [`npc_hoodie.png`](npc_hoodie.png) |
+| <img src="npc_jacket.png" width="280" alt="npc_jacket.png"> | [`npc_jacket.png`](npc_jacket.png) |
+| <img src="npc_vest.png" width="280" alt="npc_vest.png"> | [`npc_vest.png`](npc_vest.png) |
+| <img src="palm_tree.png" width="280" alt="palm_tree.png"> | [`palm_tree.png`](palm_tree.png) |
+| <img src="phone.png" width="280" alt="phone.png"> | [`phone.png`](phone.png) |
+| <img src="planter_box.png" width="280" alt="planter_box.png"> | [`planter_box.png`](planter_box.png) |
+| <img src="protest_sign.png" width="280" alt="protest_sign.png"> | [`protest_sign.png`](protest_sign.png) |
+| <img src="radio.png" width="280" alt="radio.png"> | [`radio.png`](radio.png) |
+| <img src="round_planter.png" width="280" alt="round_planter.png"> | [`round_planter.png`](round_planter.png) |
+| <img src="scba_tank.png" width="280" alt="scba_tank.png"> | [`scba_tank.png`](scba_tank.png) |
+| <img src="security_podium.png" width="280" alt="security_podium.png"> | [`security_podium.png`](security_podium.png) |
+| <img src="sedan.png" width="280" alt="sedan.png"> | [`sedan.png`](sedan.png) |
+| <img src="sheet_npc.jpg" width="280" alt="sheet_npc.jpg"> | [`sheet_npc.jpg`](sheet_npc.jpg) |
+| <img src="sheet_npc_baseline.jpg" width="280" alt="sheet_npc_baseline.jpg"> | [`sheet_npc_baseline.jpg`](sheet_npc_baseline.jpg) |
+| <img src="sheet_npc_baseline_compare-p1.jpg" width="280" alt="sheet_npc_baseline_compare-p1.jpg"> | [`sheet_npc_baseline_compare-p1.jpg`](sheet_npc_baseline_compare-p1.jpg) |
+| <img src="sheet_npc_baseline_compare-body.jpg" width="280" alt="sheet_npc_baseline_compare-body.jpg"> | [`sheet_npc_baseline_compare-body.jpg`](sheet_npc_baseline_compare-body.jpg) |
+| <img src="sheet_npc_baseline_compare-face.jpg" width="280" alt="sheet_npc_baseline_compare-face.jpg"> | [`sheet_npc_baseline_compare-face.jpg`](sheet_npc_baseline_compare-face.jpg) |
+| <img src="sheet_npc_baseline_compare-torso.jpg" width="280" alt="sheet_npc_baseline_compare-torso.jpg"> | [`sheet_npc_baseline_compare-torso.jpg`](sheet_npc_baseline_compare-torso.jpg) |
+| <img src="sheet_npc_baseline_compare-face-detail.jpg" width="280" alt="sheet_npc_baseline_compare-face-detail.jpg"> | [`sheet_npc_baseline_compare-face-detail.jpg`](sheet_npc_baseline_compare-face-detail.jpg) |
+| <img src="sheet_npc_hands_compare.jpg" width="280" alt="sheet_npc_hands_compare.jpg"> | [`sheet_npc_hands_compare.jpg`](sheet_npc_hands_compare.jpg) |
+| <img src="sheet_npc_hands_grip_compare.jpg" width="280" alt="sheet_npc_hands_grip_compare.jpg"> | [`sheet_npc_hands_grip_compare.jpg`](sheet_npc_hands_grip_compare.jpg) |
+| <img src="sheet_npc_baseline_compare-shoes.jpg" width="280" alt="sheet_npc_baseline_compare-shoes.jpg"> | [`sheet_npc_baseline_compare-shoes.jpg`](sheet_npc_baseline_compare-shoes.jpg) |
+| <img src="sheet_npc_gear.jpg" width="280" alt="sheet_npc_gear.jpg"> | [`sheet_npc_gear.jpg`](sheet_npc_gear.jpg) |
+| <img src="sheet_props.jpg" width="280" alt="sheet_props.jpg"> | [`sheet_props.jpg`](sheet_props.jpg) |
+| <img src="shoulder_bag.png" width="280" alt="shoulder_bag.png"> | [`shoulder_bag.png`](shoulder_bag.png) |
+| <img src="stanchion.png" width="280" alt="stanchion.png"> | [`stanchion.png`](stanchion.png) |
+| <img src="street_lamp.png" width="280" alt="street_lamp.png"> | [`street_lamp.png`](street_lamp.png) |
+| <img src="street_tree.png" width="280" alt="street_tree.png"> | [`street_tree.png`](street_tree.png) |
+| <img src="sunglasses.png" width="280" alt="sunglasses.png"> | [`sunglasses.png`](sunglasses.png) |
+| <img src="traffic_cone.png" width="280" alt="traffic_cone.png"> | [`traffic_cone.png`](traffic_cone.png) |
+| <img src="trash_bin.png" width="280" alt="trash_bin.png"> | [`trash_bin.png`](trash_bin.png) |
+| <img src="umbrella.png" width="280" alt="umbrella.png"> | [`umbrella.png`](umbrella.png) |
+| <img src="wall_lantern.png" width="280" alt="wall_lantern.png"> | [`wall_lantern.png`](wall_lantern.png) |
+| <img src="wand.png" width="280" alt="wand.png"> | [`wand.png`](wand.png) |

docs/development-status.md

@@ -2,10 +2,10 @@
 
 Implemented so far:
 
-- Godot 4.3 project scaffold, input map, procedural world builder
+- Godot 4.7.2 project scaffold, input map, procedural world builder (CI/local/release unified)
 - Venue-driven simulation core: `ShiftCoordinator`, `VenueScenario`, `EventScheduler`, `NPCController` + FSM, `AccessVerifier`, `EscalationManager`, `RadioSystem`, `IncidentRecorder`, `ReputationEvaluator`, `CrowdSystem`
-- Three authored scenarios (Hollywood Boulevard building, The Joke Shop, Late Night TV Studio) with access policies, NPC archetypes, and event pools
+- Three authored scenarios (El Capitan Entertainment Centre / Hollywood Boulevard, The Joke Shop, Late Night TV Studio) with access policies, NPC archetypes, and event pools
-- Headless unit tests: **250 passing** (access rules and venue-correct access loadout, escalation, radio cooldown/battery, NPC reaction determinism, door lock, flashlight perception, persistence round-trip, settings round-trip, input remaps, navmesh, step colliders, skyline alpha, scenario data, full-shift simulation, wand screening, responder dispatch, localization strings, focus cone, action wheel, session shell, PLAN verbs and incident recording, crowd presentation, emergency aftermath, body-camera timeline, NPC theater poses, audio, accessibility, authored scenario content, string formatting, `.tres` venue round-trip, surface materials and environment, focus ranking and outfit/gait helpers, generated prop models, web export preset, prop atlas material, player movement, NPC character layers/LOD/queue, input bindings)
+- Headless unit tests: **262 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`)
@@ -38,15 +38,39 @@ Implemented so far:
 - Web build: `build/gig-line-web-<version>.zip` (Godot's non-threaded web template, no COOP/COEP headers needed) built by `tools/build_releases.sh` and published with the desktop artifacts; serve the unzipped folder from any static host
 - Aim-free selection pass (v0.3.0 work, [ADR-0011](adr/0011-aim-free-selection-and-precision-walk.md)): the focus cone ranks candidates by angle then distance, `Tab` and the mouse wheel cycle nearby people nearest-first and pin the selection, right click clears focus with a short re-acquire grace, the HUD reports how many people are in the ring, and holding `Shift` walks at half speed for close work
 
-- Visual alignment: start/venue menu, pause, settings, shift review, radio, wand, inspection, timeline, HUD target chip/escalation bar, and radial menu now use or match their AI references in `assets/images/ui/`. The runtime art loader (`src/game/ui/art.gd`) falls back cleanly when a file is missing.
+- 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. The wand panel lists the guest's carried items, and multiline HUD/wand strings render real line breaks.
+- NPC neck/shoulder transition (0.9.4 work): the body graph now uses a fuller neck base, a slightly tapered neck top and a lower shoulder root, giving the head/neck/shoulder line a trapezius slope instead of a thin post. The full character library was rebuilt with a final degenerate-face cleanup; the baseline comparison is `sheet_npc_baseline_compare-body.jpg`.
+- NPC face-depth pass (0.9.4 work): sclera are recessed and capped by a thin upper lid, and the separate jaw/cheek spheres are replaced by a chin plate and cheekbones sculpted into the head mesh. The full library was rebuilt; the comparison is `sheet_npc_baseline_compare-face.jpg`.
+- NPC torso/hip transition (0.9.4 work): the pelvis and chest are slightly wider than the waist, giving shirts and jackets a readable taper into the hips without changing the build multipliers or the skeleton. The comparison is `sheet_npc_baseline_compare-torso.jpg`.
+- NPC visual optimization (0.9.4, complete 2026-11-02): all eight variants passed the portrait/readability, proportion, gear, foot/shoe, headgear and final-context gates. The library uses an 8,000-triangle / 8,000-glTF-vertex cap (up from 6,000/5,000; `npc_base` fallback remains 6,000/4,000); current characters measure 4,482–5,474 triangles and 4,260–5,494 vertices. The 48-frame baseline and 96-frame final-context review pass, the hand/gear offset and shoes are in, and the accepted stylized limits are documented in `npc-visual-review.md`.
+- NPC face-detail pass (0.9.4 work): ala wings and a smaller nose bridge/tip, one rounded mouth slot, and a darker ear concha; all eight rebuilt. The comparison is `sheet_npc_baseline_compare-face-detail.jpg`.
+- NPC headgear clearance (0.9.4 work): the 96-frame final-context review after the face-detail pass confirms the cap, firefighter helmet, hood and sunglasses clear the refined brow and eyes; no gear rebuild was needed.
+- NPC footwear pass (0.9.4 work): casual shoes gained rounded toe and heel caps; responder/firefighter boots gained matching toe/heel volumes while retaining the black rubber boot language. All eight rebuilt; comparison `sheet_npc_baseline_compare-shoes.jpg`.
+- NPC hand-item grip (0.9.4 work): runtime `HAND_ITEM_FORWARD` moves every hand gear 4 cm forward from the wrist proxy, so phone, cup, clipboard, camera, flashlight, wand and radio sit in the open palm instead of partly inside it. The open-hand/no-finger-rig limit is accepted for this stylized release; the comparison is `sheet_npc_hands_grip_compare.jpg`.
+- NPC hand pass (0.9.4 work): wider, shallower palms; four two-segment bent fingers with rounded tips and a separate bent thumb; optional `--view=hand` capture at 0.80 m. The hand comparison is `sheet_npc_hands_compare.jpg`; the forward offset is in and the open-palm limit is accepted.
+- NPC proportion audit (0.9.4 work): `tools/npc_proportions.py` measures all eight GLBs against a stylized height/head/shoulder/hip/torso/leg/arm/foot guide. All variants pass; the head and broad-build silhouettes are the nearest upper bounds. Results are in [`npc-proportion-audit.md`](npc-proportion-audit.md).
+- NPC P1 portrait fixes (0.9.4 work): tourists now hide their photo-pose camera bag outside `photo`/`film` poses, removing the duplicate-backpack silhouette; the backpack gear was rebuilt with flattened, forward chest straps and a fresh AO map. The before/after sheet is [`blender_previews/sheet_npc_baseline_compare-p1.jpg`](blender_previews/sheet_npc_baseline_compare-p1.jpg); the remaining face/hand work was closed under the 0.9.4 acceptance limits.
+- NPC visual baseline (0.9.4 work): `src/test/capture_npc_baseline.gd` captures all eight library characters from front, three-quarter, profile, back, full-body and crowd views in a neutral studio (48 frames). The criteria, measurements and ranked gaps are in [`npc-visual-review.md`](npc-visual-review.md); the committed sheet is [`blender_previews/sheet_npc_baseline.jpg`](blender_previews/sheet_npc_baseline.jpg). No model changes were made in this baseline step.
+- UI-state capture pass (0.9.3 work): `src/test/capture_ui_states.gd` adds committed captures 14–21 for the start menu, pause, settings, shift review, emergency radio, action wheel, crowd panic and responder arrival. Every one of the 21 catalogue entries now has a current-build capture; `tools/check_screenshots.sh` reports 21 good / 0 bad and the automatic judge reports 21/21 match, 0 diff. Crowd panic and responder arrival are staged presentation frames, not gameplay changes.
 - Realism adoption (post-v0.6.0): v2 per-phase skylines and surface tiles with normal maps, retuned sun/exposure/fog, wet asphalt, denser foliage, a visible additive flashlight beam, and refreshed staging captures. `tools/check_screenshots.sh` is the repeatable capture/compare gate; judge is clean of `diff` verdicts.
 - Input/reliability fixes: selecting a venue releases the start-menu input lock and recaptures the mouse; the body-camera overlay no longer covers the shift status. Mouse look now reads at `_input`, restores capture on window focus/click-back, and the HUD is mouse-transparent. Normal radio reports submit on click; emergency calls still require the hold-to-confirm path.
-- Production-quality pass (v0.9.0): mixer/accessibility settings, audio volume clamping, 24-NPC budget smoke, shortened coat/dress stride, and an explicit Godot 4.3-CI/4.7-local support matrix with documented upgrade/rollback requirements.
+- Production-quality pass (v0.9.0): mixer/accessibility settings, audio volume clamping, 24-NPC budget smoke, shortened coat/dress stride, and a unified Godot 4.7.2 CI/local support baseline with documented upgrade/rollback requirements.
 - Campaign and first-hour pass (v0.8.0): campaign progression, checkpoint resume, difficulty presets, a searchable Help overlay, recovery events, contextual dialogue, policy/debrief lines and tutorial/replay/skip. Scripted QA bypasses the tutorial unless `--tutorial` is passed.
 - Tutorial pass (0.8.0 work): the eight-beat first shift is wired through a non-blocking prompt overlay, a safe compliant visitor, real wheel/inspection/warning/radio panels, persisted completion/skip and a Settings replay action. Scripted tests/captures bypass it unless `--tutorial` is passed; `smoke_tutorial.gd` covers the full flow.
 - Vision judge (v0.7.2): discovers the cheapest current OpenRouter image+JSON model, reports the model/fallbacks used, and clears the full screen-design judge (13/13 match, 0 diff).
 - Desktop HQ (v0.7.1): optional Forward+ Windows/Linux zip with volumetric fog, SDFGI and a volumetric flashlight; the default Compatibility/Web builds and headless tests gate the effect off. A/B captures are generated locally under `docs/screens/realism/` (gitignored).
-- Venue geometry (v0.7.0): the Joke Shop now builds as a narrow brick alley with a warm wall lantern, shutters, dumpster/AC clutter and no skyline; the TV Studio builds a stone facade, bulb canopy, glossy black car and barrier line. `WorldBuilder.VENUE_SPECS` drives facade/street/nav dimensions, and `GameManager` rebuilds only the world container when the venue changes.
+- Hollywood landmark map (map optimization): the default venue is now a stylized reconstruction of 6840 Hollywood Blvd (the 1921 Masonic Temple / El Capitan Entertainment Centre) with a six-column Ionic portico, eight stone steps, Masonic parapet motto and medallions, three red event banners, central and side entrances, the El Capitan Theatre and east retail neighbours, the Ovation Hollywood arcade opposite, the Walk of Fame terrazzo and a four-lane boulevard with red kerb paint. The facade uses the shared limestone/stone material; the whole venue measures **58,884 triangles across 409 meshes** in the map-budget test. The venue menu exposes separate **Day** and **Night** Hollywood rows; the night row resolves to the same scenario with a late-phase offset, so its whole shift stays after dark. Real-site references and the geometry mapping are in [`hollywood-boulevard-map.md`](hollywood-boulevard-map.md).
+- Day/night scenery variants (map optimization): the Hollywood row in the venue menu is split into Day and Night entries, with localized names/blurbs. The night entry uses `ShiftCoordinator.phase_offset_s` to start a full-length shift in `LATE` while the clock still starts at 00:00; the scheduler reads the offset time so late-night routine traffic and the late violent-threat event still fire, and the offset round-trips through checkpoints. Three `LATE` routine events keep the night street populated. Local lights were retuned from constant falloff to linear attenuation so sconces pool instead of flooding the stone.
+- Joke Shop / Sunset Strip map (map optimization): the second venue is now a stylized reconstruction of The Comedy Store block at 8433 Sunset Blvd, with a 27 m black hall, signature-covered sloping canopy, circular **THE JOKE SHOP** blade sign, red velvet curtain bays, a west-end entrance, cream and white low-rise neighbours, a dry hillside with stucco houses and palms behind the roofline, and a low retail/billboard frontage across Sunset. The same geometry serves day and late lighting through the phase system. Real-site references and limits are in [`joke-shop-map.md`](joke-shop-map.md); the map measures **22,680 triangles across 454 meshes** in the budget test.
+- Venue geometry (v0.7.0, Joke Shop frontage superseded by the map-optimization pass): 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.
+- End-to-end interaction pass (0.9.3 work): `smoke_ui_flows.gd` drives inspection allow/deny, normal vs emergency radio, Help filtering, wand allow/deny and review return-to-menu in the real scene; campaign and timeline smokes cover review continue and timeline round-trips.
+- Destructive-action pass (0.9.3 work): reset campaign and tutorial replay share a guarded confirmation dialog (one open instance, one emission, Cancel is inert); emergency send remains hold-to-confirm with no post-submit double-fire. Covered by session/radio tests and recorded in `docs/ui-copy.md`.
+- Font/layout pass (0.9.3 work): HUD font scale was exercised at 0.75× and 1.75×; the target chip measures and caps scaled names, top labels clip, and shared action buttons ellipsize long 1.5–2× labels instead of overflowing. Covered by accessibility/button tests and recorded in `docs/ui-copy.md`.
+- Modal-close pass (0.9.3 work): one top-modal close path handles Esc/right-click for every overlay, Settings opened from the menu restores the menu, Help no longer opens Pause behind it, and pointer/guard freeze state is recaptured after each close. The session smoke covers these paths.
+- Keyboard/gamepad focus pass (0.9.3 work): `UiFocus` rings wrap through visible/enabled controls, hidden Continue and disabled timeline actions are skipped, each modal has a default focus, and A/B are bound to `ui_accept`/`ui_cancel` for pad-only navigation. Recorded in `docs/ui-copy.md`.
+- Button-state pass (0.9.3 work): a shared `UiStyles` helper now gives every action button explicit normal, hover, pressed, focus and disabled styles; the timeline disables Previous/Next at its boundaries, while hidden continue states and the keyboard-only tutorial skip remain intentional. Recorded in `docs/ui-copy.md`.
+- Dialogue pass (0.9.3 work): NPC reason answers now use the authored `reason` context, with an in-character answer for every shared archetype; Hollywood and Studio gained door-staff lines; radio cancellation, tutorial Ask terminology, help, start hints and campaign reset copy were clarified. Audit recorded in `docs/ui-copy.md`.
+- Pre-build NPC review (2026-11-02): all eight library characters were staged at portrait, conversation and crowd distance on Hollywood and the Joke Shop, in day and night lighting, with the normal crowd hidden (`src/test/capture_npc_review.gd`). No P0 issues were found. Two P1 gear-fit issues were fixed with runtime attach offsets: the authorized-guest lanyard badge now clears the jacket and the firefighter helmet sits above the eyes. Backpack straps, caps, hands and the intentionally low-poly faces were accepted for the stylized target; close-range flashlight wash remains an optional-lighting follow-up. The 24-NPC budget stayed at 6.93 ms, the gallery passed 13 good / 0 bad and the screen-design judge stayed 13/13, and a clean portrait scored a 0.732 vision gap against the photoreal concept.
 
-Current gaps for v1.0.0: deeper authored content/dialogue, animation and audio production, localization/accessibility expansion, 24-NPC/platform profiling, external playtesting, signed/notarized release packaging, and a unified Godot baseline. The full gap analysis and milestone plan live in [`TODO.md`](../TODO.md); the current architecture and documentation ownership map are in [`docs/architecture.md`](architecture.md).
+Current gaps for the 0.x release line: deeper authored content/dialogue, animation and audio production, localization/accessibility expansion, 24-NPC/platform profiling, external playtesting, and signed/notarized release packaging. 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

@@ -20,15 +20,22 @@ The first shift starts with an in-game tutorial covering movement/look, focus cy
 
 ## Venues
 
-### Hollywood Boulevard Building
+### El Capitan Entertainment Centre (6840 Hollywood Blvd)
 
-The original scenario places the guard at the top of the steps outside a fictional building. Tourists, street performers, influencers, confused visitors, intoxicated pedestrians, trespassers, people experiencing a mental-health crisis, and rare violent threats may approach the entrance.
+The map is a stylized reconstruction of the real building and block; the
+reference notes and geometry mapping are in
+[`hollywood-boulevard-map.md`](hollywood-boulevard-map.md). The venue menu
+offers the same map as **Hollywood Boulevard — Day** and **Hollywood Boulevard
+— Night**; the night variant starts directly in the late phase instead of
+waiting for the shift clock.
+
+The original scenario places the guard at the top of the eight stone steps outside the historic Masonic Temple / El Capitan Entertainment Centre on Hollywood Boulevard. Tourists, street performers, influencers, confused visitors, intoxicated pedestrians, trespassers, people experiencing a mental-health crisis, and rare violent threats may approach the entrance.
 
 Authorized people must either be recognized by the guard or present a valid wristband. Wristbands can have different colors, patterns, dates, or event markings. They may be valid, expired, counterfeit, or missing.
 
 ### The Joke Shop
 
-The Joke Shop is a narrow brick alley with a recessed door, shuttered windows, a warm wall lantern, a dumpster and wall-mounted AC clutter. The door person checks IDs, tickets, reservations, and guest-list status, then uses a handheld security wand according to venue policy. The player must interpret wand alerts rather than treating every alert as proof of a weapon; keys, belts, phones, and other harmless objects can trigger false alarms.
+The Joke Shop is a Sunset Strip comedy club inspired by the real Comedy Store at 8433 Sunset Blvd: a black hall under a deep signature-covered canopy, a circular blade sign, red velvet curtains, a west-end entrance, neighbouring low-rise frontage and a dry hillside of houses behind. The real-site mapping is in [`joke-shop-map.md`](joke-shop-map.md). The door person checks IDs, tickets, reservations, and guest-list status, then uses a handheld security wand according to venue policy. The player must interpret wand alerts rather than treating every alert as proof of a weapon; keys, belts, phones, and other harmless objects can trigger false alarms.
 
 ### Hollywood Boulevard Late Night TV Studio
 

docs/getting-started.md

@@ -2,7 +2,7 @@
 
 ## Setup
 
-1. Download the Godot 4.3+ editor (official build) and put `godot` on your PATH. The supported policy is an explicit matrix: CI/release baseline 4.3, local development verified with 4.7.2. Engine upgrades require import, headless, screenshot and Desktop HQ smoke checks before changing the baseline.
+1. Download Godot **4.7.2** (official build) and put `godot` on your PATH. The project, local tooling and CI use the same version; engine upgrades require import, headless, screenshot and Desktop HQ smoke checks before changing the baseline.
 2. Open or run the project from this directory.
 
 ## Run and Test
@@ -20,6 +20,9 @@ godot --headless --path . --quit-after 120
 # Run all unit tests headlessly (exit code 0 = pass)
 godot --headless --path . --script res://src/test/test_runner.gd
 
+# Check docs README coverage, tracked images and local links
+python3 tools/check_docs.py
+
 # Save a screenshot to user:// (windowed)
 godot --path . --script res://src/test/take_screenshot.gd
 
@@ -32,6 +35,9 @@ godot --path . --script res://src/test/smoke_focus_radial.gd
 # Session-shell smoke: menu → shift → pause → settings → menu (headless or windowed)
 godot --headless --path . --script res://src/test/smoke_session_shell.gd
 
+# End-to-end interaction smoke: inspection, radio, Help search, wand and review
+godot --headless --path . --script res://src/test/smoke_ui_flows.gd
+
 # PLAN-verb smoke: recognize, request reason, body camera, warning, blocking
 godot --headless --path . --script res://src/test/smoke_plan_verbs.gd
 

docs/hollywood-boulevard-map.md

@@ -0,0 +1,82 @@
+# Hollywood Boulevard map reference
+
+The Hollywood venue is a stylized reconstruction of the real block around the
+El Capitan Entertainment Centre. It is a game space, not a survey-accurate
+model: the landmark silhouette, street wall and approach read from the player's
+eye height, while side streets and interiors are simplified.
+
+## Real site
+
+- **Address:** 6840 Hollywood Boulevard, Hollywood, Los Angeles, CA 90028.
+- **Coordinates:** 34.10118 N, 118.34009 W (OSM way `424024147`).
+- **Building:** the 1921 Hollywood Masonic Temple, designed by John C. Austin in
+  the Classical Revival style; now the El Capitan Entertainment Centre and the
+  home of *Jimmy Kimmel Live!*.
+- **Facade:** a light stone/render Neoclassical front with six oversized Ionic
+  columns, a recessed main entrance reached by eight stone steps, ornamental
+  iron door grilles, a continuous crosscut-grille transom, two street-level side
+  entrances, and a parapet with the Masonic motto and circular medallions.
+- **Neighbours:** the El Capitan Theatre (6838) immediately west, a modern
+  retail block east, and the Ovation Hollywood frontage (6801) across the
+  four-lane boulevard.
+- **Sidewalk:** the Hollywood Walk of Fame terrazzo strip with brass stars runs
+  along the kerb; the kerb is painted red in the reference photographs.
+
+## Game mapping
+
+| Real feature | In-game representation |
+| --- | --- |
+| 29.6 m wide, 14.5 m high facade | `VENUE_SPECS["hollywood_building"]`: `facade_width` 29.6, `facade_height` 14.5, front at `z = -4` |
+| Eight stone steps | `stair_count` 8, `stair_height` 0.10, `stair_tread` 0.38, 12 m wide |
+| Six Ionic columns | `IonicColonnade` at x = -12.4 … 12.4, 4.96 m bay spacing |
+| Recessed main entrance + two side doors | central 4.2 m door and 2.5 m side doors with transoms |
+| Red event banners | three stylized `EL / CAPITAN / LIVE` banners in the central bays |
+| Masonic motto + medallions | `FriezeInscription` label and two stone discs |
+| El Capitan Theatre | `NeighbourBlocks/ElCapitanTheatre` with marquee, blade sign and practical light |
+| Retail block east | `NeighbourBlocks/EastRetailBlock` with glazed shopfront |
+| Ovation Hollywood | `OvationHollywood` arcade with seven arched openings, sign and south sidewalk |
+| Walk of Fame | `WalkOfFame` dark terrazzo band with ten stars |
+| Four-lane boulevard | double-yellow centre, broken white lane lines, red kerb paint and crosswalk |
+
+The generated AI references live in
+[`docs/screens/concepts/hollywood_boulevard/`](screens/concepts/hollywood_boulevard/README.md).
+They are art direction for lighting, material scale and composition; they are
+not texture or geometry sources.
+
+## Deliberate simplifications
+
+- Show branding is replaced by the venue-neutral `EL / CAPITAN / LIVE` banner
+  text. The building name and address are retained.
+- The opposite Ovation frontage is represented as a single arcade block rather
+  than its full mall plan. Interiors, the Metro entrance and side streets are
+  out of playable bounds.
+- The AI concept frames are 1280×720 references. The in-game geometry is built
+  from boxes, cylinders and a small number of custom arch/star meshes so it
+  stays inside the Compatibility/Web budget.
+- The venue menu offers Day and Night Hollywood rows. Night is the same
+  geometry and scenario with a late-phase offset, not a second baked map; the
+  phase still drives sun, sky, fog, windows, signage and practical lights.
+- The landmark facade uses the shared smooth limestone/stone texture rather
+  than the noisier granite panel tile. The whole venue measures **58,884
+  triangles across 409 meshes** in `test_hollywood_geometry_stays_inside_the_map_budget`,
+  well inside the 150k/600 budget.
+- Local lights use linear attenuation (`omni_attenuation = 1.0`). Godot treats
+  `0.0` as constant falloff, which previously turned the night facade into a
+  flat yellow wall; the sconces now pool light instead.
+
+## References
+
+- [Hollywood Masonic Temple — Wikipedia](https://en.wikipedia.org/wiki/Hollywood_Masonic_Temple)
+- [El Capitan Entertainment Centre — OpenStreetMap way 424024147](https://www.openstreetmap.org/way/424024147)
+- [El Capitan Theatre — OpenStreetMap way 424024148](https://www.openstreetmap.org/way/424024148)
+- [Ovation Hollywood — OpenStreetMap way 151485232](https://www.openstreetmap.org/way/151485232)
+- [Hollywood Masonic Temple facade — Wikimedia Commons](https://commons.wikimedia.org/wiki/File:El_Capitan_Theater_frontal_fachade-The_Masonic_Temple.jpg)
+- [Hollywood Masonic Temple and El Capitan Theatre, 2013 — Wikimedia Commons](https://commons.wikimedia.org/wiki/File:Hollywood_Masonic_Temple_2013-10-13_10-02-25.jpg)
+
+## Verification
+
+```bash
+godot --headless --path . --script res://src/test/test_runner.gd
+godot --path . --script res://src/test/capture_realism.gd -- --out=/tmp/gig-line-hollywood --stages=day,evening,late
+python3 tools/check_docs.py
+```

docs/joke-shop-map.md

@@ -0,0 +1,95 @@
+# The Joke Shop — Sunset Strip map notes
+
+The game's second venue is a fictional comedy club called **The Joke Shop**. Its
+block, canopy, blade sign, entrance and hillside are based on the real Comedy
+Store at **8433 Sunset Blvd, West Hollywood, CA 90069**.
+
+The club name and the game's guest stories are invented. The building is a
+stylized reconstruction, not a survey-accurate model: the playable frontage is
+27 m, while the real parcel is much deeper and contains several rooms that the
+game does not enter.
+
+## Real site
+
+| Item | Reference |
+| --- | --- |
+| Address | 8433 Sunset Blvd, West Hollywood, CA 90069, United States |
+| Real venue | The Comedy Store (comedy club and theatre) |
+| OpenStreetMap | Way [`428854155`](https://www.openstreetmap.org/way/428854155), centroid 34.095265, -118.373965 |
+| OSM tags | `amenity=theatre`, `building=commercial`, `height=12.2`, `start_date=1940`, `wikidata=Q3520350` |
+| Footprint | OSM polygon bounding box about **47.1 m × 41.2 m** across the club and rear parcels |
+| Street | Sunset Boulevard, a major east–west arterial on the Sunset Strip |
+| Setting | Dry Hollywood Hills directly behind the club, with houses and palms rising above the roofline |
+
+The building began as **Ciro's**, a 1940 nightclub; it became The Comedy Store
+in the early 1970s. Its street front is a low black hall under a deep,
+signature-covered canopy, with the circular blade sign above the roof, red
+curtains along the frontage and the main entrance set toward the west end. The
+hillside houses behind it are part of the silhouette from the sidewalk.
+
+## How the map maps to the real site
+
+| Real element | Game implementation |
+| --- | --- |
+| Low black comedy hall | 27 m × 12 m footprint, 8.4 m street wall; matte black concrete surface with a low plinth and parapet |
+| Deep overhanging canopy | 4.9 m sloped slab dropping about 1 m to the outer fascia; the fascia carries white signature lettering and the club name |
+| Signature-covered front | Two `Label3D` signature bands on the fascia plus a smaller wall panel, so the handwriting reads at gameplay distance without dozens of decals |
+| Circular blade sign | 3.9 m white disc with a black rim on a roof pole; `THE JOKE SHOP` lettering faces the street |
+| Red curtains | Four three-fold velvet bays with tiebacks between the entrance and the east end; a red velvet entrance curtain |
+| West-end entrance | Recessed opening at x = -8.8 m with a low step, brass pulls and the door-lock indicator |
+| Warm practicals | Sconces along the wall, canopy downlights, entrance wash and three ground uplights; all off in daylight and switched by `set_night_mode()` |
+| Neighbouring low-rise frontage | Cream Mediterranean block west (balconies, red awning) and white commercial block east (ribbon windows, lobby) |
+| Hillside and houses | Fog-free unshaded 60° ramp behind the rear wall with stucco houses, shrubs and palms; its tint drops to a dark silhouette at night |
+| Opposite side of Sunset | Low retail row, rooftop billboard, neon and palms as background context beyond the far kerb |
+| Sidewalk furniture | Palms, queue barriers, stanchions, bins, planters, a-frame sign, hydrant and a parked sedan; prop placements pass the shared validator |
+
+## Scene composition
+
+- **Frontage:** 27 m wide, façade centre at z = -8.0, front face at z = -2.0.
+- **Sidewalk:** 38 m wide × 14 m deep, meeting the kerb at z = 11.9.
+- **Street:** 90 m × 24 m, with the four-lane markings reused from the
+  Hollywood block and a crosswalk in front of the entrance.
+- **Playable area:** x = -15…15, z = -0.6…14.0. The guard starts on the west
+  side of the entrance at (-4.8, 0.1, 1.4), facing the approach.
+- **Map budget:** the headless audit measures **22,680 triangles across 454
+  meshes**, well inside the 150k/700 test budget.
+
+The same geometry serves the day and late-night looks. There is no second baked
+map: the phase lighting, skyline/fog tint, lit windows and practicals change,
+just as with the Hollywood day/night rows.
+
+## Simplifications and limits
+
+- The real club's rear rooms, basement and roof plant are not modelled; the
+  playable area is the street frontage only.
+- The 47 m OSM footprint includes rear parcels and does not match the 27 m
+  street frontage; the game keeps the frontage proportions rather than the full
+  lot.
+- Neighbouring businesses are represented by generic low-rise blocks. Their
+  exact names and current tenants were not verified, so the docs do not claim
+  them.
+- The hillside is a background ramp with simplified houses, not a terrain
+  heightfield; it exists to restore the real silhouette above the roofline.
+- Signage uses the fictional **The Joke Shop** name, not the real Comedy Store
+  wordmark.
+- The concept frames are photoreal; the game keeps its stylized, low-poly
+  material treatment. The vision judge therefore still scores material and
+  foliage detail below the reference. The remaining texture/realism work is
+  tracked with the postponed 0.9.5 pass, not treated as a map-geometry defect.
+
+## References
+
+- OpenStreetMap way 428854155: <https://www.openstreetmap.org/way/428854155>
+- Wikimedia Commons photographs used for proportion and material study:
+  - <https://commons.wikimedia.org/wiki/File:ComedyStore_01.jpg>
+  - <https://commons.wikimedia.org/wiki/File:ComedyStore_02.jpg>
+  - <https://commons.wikimedia.org/wiki/File:The_Comedy_Store.jpg>
+  - <https://commons.wikimedia.org/wiki/File:The_Comedy_Store_West_Hollywood_(51017780551).jpg>
+- AI art-direction frames: [`screens/concepts/joke_shop/`](screens/concepts/joke_shop/README.md)
+- Verification: `godot --headless --path . --script res://src/test/test_runner.gd`
+  (`test_joke_shop_uses_the_real_sunset_strip_layout`,
+  `test_joke_shop_geometry_stays_inside_the_map_budget`), and
+  `godot --path . --script res://src/test/capture_realism.gd -- --stages=joke_shop_day,joke_shop`.
+  The committed gallery passed `tools/check_screenshots.sh` (13 good / 0 bad)
+  and the screen-design judge (13/13 match, 0 diff). The latest local realism
+  run reports a reference gap of 0.454 for the night entrance.

docs/npc-proportion-audit.md

@@ -0,0 +1,79 @@
+# NPC proportion audit
+
+Status: audited 2026-11-02. All eight library variants are inside the stylized
+proportion guide; no geometry correction was required in this pass. The report
+is repeatable from the exported GLBs:
+
+```bash
+python3 tools/npc_proportions.py report
+python3 tools/npc_proportions.py report --json
+```
+
+## Method
+
+`tools/npc_proportions.py` reads the GLB meshes and rest-pose joint hierarchy:
+
+- height from the full mesh bounds;
+- head height, width and aspect from `Head`/`skin` vertices (hair excluded so
+  long hairstyles do not change the head measurement);
+- shoulder silhouette from vertices in the upper-chest band around the
+  shoulder joint;
+- hip width from `HipL`/`HipR` pants vertices;
+- torso length from the Spine joint to the shoulder joint;
+- leg length from the Spine joint to the lowest vertex;
+- arm length from the shoulder joint to the Hand joint;
+- foot length from the forward extent of the KneeL/KneeR shoe vertices.
+
+All ratios are divided by total standing height except `head_aspect`
+(width / head height).
+
+## Guide
+
+These are stylized-but-credible bands for the game's low-poly adults, not
+photoreal anatomy. The broad build is allowed a larger shoulder/hip silhouette
+than the slim build.
+
+| Ratio | Target | Notes |
+| --- | ---: | --- |
+| `head_height` | 0.16–0.22 | deliberately larger than a realistic 0.13–0.15 |
+| `head_aspect` | 0.70–1.00 | width / height; rounded heads are acceptable |
+| `shoulder_width` | 0.28–0.38 | silhouette includes sleeves and build scaling |
+| `hip_width` | 0.17–0.23 | pants-only width, not skirt/coat flare |
+| `torso_length` | 0.28–0.38 | Spine joint to shoulder |
+| `leg_length` | 0.40–0.48 | Spine joint to ground |
+| `arm_length` | 0.28–0.38 | shoulder to hand |
+| `foot_length` | 0.12–0.18 | shoe forward extent |
+
+## Result
+
+| Character | Height | Head | Aspect | Shoulder | Hip | Torso | Leg | Arm | Foot | Result |
+| --- | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: | --- |
+| `npc_casual` | 1.824 m | 0.190 | 0.907 | 0.321 | 0.209 | 0.307 | 0.449 | 0.329 | 0.144 | PASS |
+| `npc_jacket` | 1.824 m | 0.190 | 0.907 | 0.333 | 0.209 | 0.307 | 0.449 | 0.329 | 0.144 | PASS |
+| `npc_coat` | 1.824 m | 0.190 | 0.907 | 0.328 | 0.209 | 0.307 | 0.449 | 0.329 | 0.144 | PASS |
+| `npc_vest` | 1.819 m | 0.191 | 0.907 | 0.322 | 0.209 | 0.308 | 0.451 | 0.330 | 0.144 | PASS |
+| `npc_dress` | 1.825 m | 0.190 | 0.907 | 0.289 | 0.191 | 0.307 | 0.449 | 0.329 | 0.144 | PASS |
+| `npc_hoodie` | 1.856 m | 0.187 | 0.907 | 0.328 | 0.206 | 0.302 | 0.442 | 0.323 | 0.141 | PASS |
+| `npc_firefighter` | 1.819 m | 0.191 | 0.907 | 0.358 | 0.223 | 0.308 | 0.451 | 0.330 | 0.148 | PASS |
+| `npc_guard` | 1.819 m | 0.191 | 0.907 | 0.369 | 0.219 | 0.308 | 0.451 | 0.330 | 0.144 | PASS |
+
+No variant is outside a band, so the body pass does not need a global skeleton
+or mesh rescale. The values closest to a boundary are:
+
+- **head height 0.190** against the 0.22 upper bound, and **head aspect 0.907**
+  against 1.00 — the head is deliberately large. Any head-size change must be
+  coordinated with the face/headgear pass and its gear-fit measurements.
+- **guard shoulder 0.369** and **firefighter hip 0.223** against the broad-build
+  upper bounds — these are the intended uniform/turnout silhouettes, not
+  outliers.
+- **leg length 0.449** and **torso 0.307** sit inside the guide for all variants;
+  the earlier short-leg impression came from the hip joint position, not the
+  visible pelvis line.
+
+## Follow-up
+
+The proportion audit does not replace the visual criteria in
+[`npc-visual-review.md`](npc-visual-review.md): neck/shoulder/hip transitions,
+face depth, hand grips, clothing hems and shoes still need the appearance pass.
+Re-run the audit after any body mesh or skeleton change and record the new
+ratios here.

docs/npc-visual-review.md

@@ -0,0 +1,232 @@
+# NPC visual baseline and acceptance criteria
+
+Status: **accepted 2026-11-02 for the 0.9.4 stylized target.** The P1 fixes
+(tourist photo-prop visibility, backpack straps), neck/shoulder and torso/hip
+transitions, face depth/detail, hand and gear placement, headgear clearance and
+shoe/boot silhouettes are applied. The baseline remains the comparison reference;
+the accepted limitations are listed below. Comparison sheets:
+[`sheet_npc_baseline_compare-p1.jpg`](blender_previews/sheet_npc_baseline_compare-p1.jpg),
+[`sheet_npc_baseline_compare-body.jpg`](blender_previews/sheet_npc_baseline_compare-body.jpg),
+the latest [`sheet_npc_baseline_compare-torso.jpg`](blender_previews/sheet_npc_baseline_compare-torso.jpg),
+the face-detail pass [`sheet_npc_baseline_compare-face-detail.jpg`](blender_previews/sheet_npc_baseline_compare-face-detail.jpg),
+the conversation-distance hand pass
+[`sheet_npc_hands_compare.jpg`](blender_previews/sheet_npc_hands_compare.jpg), and the
+forward-grip pass [`sheet_npc_hands_grip_compare.jpg`](blender_previews/sheet_npc_hands_grip_compare.jpg).
+
+## What was captured
+
+`src/test/capture_npc_baseline.gd` stages all eight library characters in a
+neutral studio and captures six views per character:
+
+| View | Camera | Purpose |
+| --- | --- | --- |
+| `front` | 1.85 m, 32° FOV, head/upper body | face, hair, collar, shoulders |
+| `three_quarter` | 1.85 m, yaw 35° | cheek/jaw, ear, profile transition |
+| `profile` | 1.85 m, yaw 90° | head depth, nose, ear, chest silhouette |
+| `back` | 1.85 m, yaw 180° | hair cap, neck, coat/backpack fit |
+| `full_body` | 4.2 m, 38° FOV | proportions, hands, shoes, hem |
+| `crowd` | 8.0 m, 45° FOV | silhouette read at normal crowd distance |
+
+The stage is deliberately separate from the venue review harness: a mid-grey
+solid background, ground plane, one key light and one cool fill light, no HUD,
+no crowd, no flashlight, no phase lighting and no animation. Front is Godot +Z,
+matching `NpcAvatar.yaw_towards()`. The camera orbits at the recorded yaw rather
+than rotating the avatar, so the pose and foot contact stay fixed between views.
+The full command is:
+
+```bash
+godot --path . --script res://src/test/capture_npc_baseline.gd -- \
+  --out=res://tmp/npc-baseline
+python3 tools/npc_baseline.py sheet --dir tmp/npc-baseline
+```
+
+The 48 raw PNGs are local QA under `tmp/` (gitignored). The committed contact
+sheet is [`blender_previews/sheet_npc_baseline.jpg`](blender_previews/sheet_npc_baseline.jpg).
+For the P2 hand/grip check there is an optional eighth view, captured separately
+so the 48-frame baseline stays stable:
+
+```bash
+godot --path . --script res://src/test/capture_npc_baseline.gd -- \
+  --out=res://tmp/npc-hands --view=hand
+```
+
+That writes eight `*__hand.png` frames at 0.80 m from the right hand; the
+before/after review image is
+[`sheet_npc_hands_compare.jpg`](blender_previews/sheet_npc_hands_compare.jpg).
+The capture is deterministic apart from engine rasterisation; re-running into
+the same directory keeps the earlier files and writes `-vN` copies rather than
+overwriting them.
+
+## Acceptance criteria
+
+The criteria below are for the stylized target, not photorealism. A change must
+pass every applicable item before a library rebuild is accepted.
+
+1. **Asset contract:** `npc_base` mesh node, the required bones, five tint slots,
+   front +Z, feet within 3 cm of y=0, 1.6–2.1 m height, at most 8,000 triangles
+   and 8,000 glTF vertices per library character. The frozen `npc_base` fallback
+   keeps 6,000 triangles / 4,000 vertices. Gear remains at most 1,500 triangles.
+2. **Proportion and silhouette:** head, neck, shoulders, torso, hips, limbs and
+   feet read as one body; front/three-quarter/profile silhouettes agree with the
+   rest of the eight-character library; broad/slim/average build variation is
+   preserved.
+3. **Face:** at 1.85 m the eyes, iris, brows, nose, mouth and ears are distinct;
+   the head volume has a readable jaw/cheek/chin transition; no face-plane seams,
+   inverted normals or z-fighting. The face direction must remain unambiguous.
+4. **Hair and headgear:** hair covers the scalp without gaps or scalp-through
+   seams; fringes, buns and beards keep their silhouette. Caps, beanies, hoods,
+   sunglasses and the firefighter helmet clear the brow, eyes and ears. Headgear
+   may sit outside the 1.55–1.81 m face band, but its brim must not cover the
+   eyes.
+5. **Hands and footwear:** at conversation distance the fingers and thumb read
+   as a hand, not a mitten; hand items contact the palm rather than floating;
+   shoes and boots are grounded with a readable toe/heel silhouette and preserve
+   the responder/firefighter footwear language.
+6. **Clothing:** collars, cuffs, plackets, waistbands, pockets, badges and
+   reflective bands transition cleanly; no z-fighting or floating detail; coat,
+   dress and skirt hems do not show legs through the fabric during idle, walk,
+   block, sit or turn; the five tint slots and fixed detail colours remain
+   unchanged.
+7. **Gear:** head gear clears the refined face/hair; the lanyard badge remains
+   readable in front of the jacket; backpack, shoulder bag and SCBA tank straps
+   lie outside the torso and do not read as a second bag; hand items use the
+   authored grip points.
+8. **Crowd and performance:** the silhouette remains readable at the 8 m crowd
+   frame and the LOD/impostor tiers match the full mesh; the 24-NPC budget stays
+   within the existing 6.93 ms baseline (no regression beyond the measured
+   variance), and no new per-frame material or mesh churn is introduced.
+
+Asset-space `fit` values are measurements of the untouched GLBs, not a pass/fail
+result. A negative `x_clearance` means the gear's narrowest face is inside the
+body reference; a negative `radial_clearance` means it extends beyond the body
+silhouette (normal for a backpack, suspicious when it is a strap). Runtime
+`NpcAvatar.GEAR_OFFSETS` is applied after attachment and is not part of the GLB
+measurement.
+
+## Proportion audit
+
+The separate [`npc-proportion-audit.md`](npc-proportion-audit.md) measures
+height, head size, shoulder/hip width, torso, leg, arm and foot ratios for every
+variant with `tools/npc_proportions.py`. All eight pass the stylized guide; the
+head and broad-build shoulders sit nearest their upper bounds. No skeleton or
+mesh proportion change was needed in this pass.
+
+## Baseline measurements
+
+From `python3 tools/blender_assets.py fit` and the manifest:
+
+| Character | Tris | Verts | Head width | Clothing radius | Notable gear clearances |
+| --- | ---: | ---: | ---: | ---: | --- |
+| `npc_casual` | 4,482 | 4,260 | 0.315 m | 0.191 m (hip) | backpack x −0.041, radial −0.162 |
+| `npc_jacket` | 4,872 | 4,661 | 0.315 m | 0.191 m (hip) | lanyard x −0.116, radial +0.023 (runtime +4 cm forward) |
+| `npc_coat` | 5,474 | 5,264 | 0.315 m | 0.225 m (skirt) | sunglasses width ratio 0.641; bag x +0.037, radial −0.130 |
+| `npc_vest` | 4,980 | 4,879 | 0.315 m | 0.191 m (hip) | cap width ratio 1.067 |
+| `npc_dress` | 4,900 | 4,719 | 0.315 m | 0.260 m (skirt) | bag x +0.002, radial −0.095 |
+| `npc_hoodie` | 5,304 | 4,950 | 0.315 m | 0.190 m (hip) | — |
+| `npc_firefighter` | 5,344 | 5,494 | 0.315 m | 0.255 m (skirt) | helmet width ratio 1.651; SCBA x −0.105, radial −0.076 |
+| `npc_guard` | 5,046 | 5,096 | 0.315 m | 0.194 m (hip) | cap width ratio 1.067 |
+
+`npc_coat` is widest at 5,474 triangles (2,526 below the 8,000 cap);
+`npc_firefighter` is closest on vertices at 5,494 (2,506 below the 8,000 cap).
+The refit backpack measures 380 triangles / 406 vertices.
+
+## Baseline findings, ranked
+
+### P1 — fix in the first model pass
+
+1. **The tourist carried two bag silhouettes. Fixed 2026-11-02.** `_add_props()`
+   created a 0.30 × 0.36 × 0.14 box at `(-0.34, 1.15, -0.18)` for the tourist
+   photo pose while `_add_accessory("backpack")` also attached the library
+   backpack. From the three-quarter/back view the two read as separate bags. The
+   photo prop is now hidden outside `photo`/`film` poses
+   (`photo_prop_visible_for_pose()`), so it only appears when the character is
+   actually taking a picture; the after frame confirms one bag at rest.
+2. **Face depth and detail. Fixed 2026-11-02.** The sclera was recessed into the
+   socket and wrapped with a thin upper lid; the separate jaw/cheek spheres were
+   replaced by a chin plate and cheekbones sculpted into the head mesh. The nose
+   now has ala wings and a smaller bridge/tip, the mouth is one rounded slot
+   instead of a flat bar, and the ears have a darker concha. That removes the
+   dark intersection rings and the moustache-like read at portrait distance; the
+   low-poly brows remain stylized.
+3. **Backpack straps read as rigid black bars. Refit 2026-11-02.** The straps
+   were thin round tubes whose chest/waist points sat inside the torso, so only
+   fragments showed from the front. They are now flattened bands whose front path
+   sits outside the chest; the after sheet shows a continuous strap instead of
+   two detached rods. The backpack asset is now 380 triangles / 406 vertices
+   (still far below the 1,500-triangle gear budget).
+
+### P2 — fix after the first P1 pass
+
+4. **Hands: geometry and forward offset fixed 2026-11-02; finger curl still
+   open.** The palm is wider and shallower, and each finger is now a
+   two-segment bent tube with a rounded tip and a separate bent thumb. Hand gear
+   is authored around the wrist proxy, so the runtime now moves every hand item
+   `HAND_ITEM_FORWARD` (4 cm) into the open palm; the phone, flashlight, camera,
+   cup and clipboard are no longer buried inside the hand. The fingers are still
+   open, so a true wrap/thumb contact and the umbrella/sign grips remain to be
+   judged.
+5. **Clothing detail is tile-driven and transitional seams are visible.** The
+   fabric pattern repeats strongly on the casual, coat and dress variants, and
+   collar/cuff/waist edges are abrupt. This is more visible than the shoe/hem
+   details in the current portraits.
+6. **Shoes: fixed 2026-11-02.** Casual shoes gained rounded toe and heel caps;
+   responder/firefighter boots gained matching toe/heel volumes while keeping the
+   taller black rubber boot language. Both stay above the sole contact plane, and
+   the full-body comparison is `sheet_npc_baseline_compare-shoes.jpg`.
+7. **Headgear scale and clearance. Checked 2026-11-02.** The cap and helmet
+   width ratios are 1.067 and 1.651; those are expected for headgear. Final-context
+   portraits confirm the cap, firefighter helmet, hood and sunglasses clear the
+   refined brow/eyes, and the helmet brim still reads as deliberate turnout gear.
+   No gear rebuild was needed.
+8. **Performer props dominate the silhouette.** The red cone hat and the
+   primitive sign are intentionally large stage props, but they should be
+   checked during the pose pass so they do not read as head/body geometry.
+
+### Accepted limits for the 0.9.4 release
+
+- The hooded variants intentionally cover part of the face; face readability is
+  judged on the visible lower face and silhouette, not on hidden eyes.
+- The low-poly style is the target. The acceptance bar is readability and clean
+  construction, not photoreal skin or hair.
+- Held items use the forward-offset open palm (`HAND_ITEM_FORWARD`) rather than a
+  finger-curl rig. There are no finger bones in the contract; phone, cup,
+  clipboard, camera, flashlight, wand and radio were judged in the hand capture.
+- Fabric folds are not separate geometry; the current torso, elbow and knee
+  shaping is the accepted stylized construction.
+- The >26 m impostor remains a two-quad billboard; the LOD tier/hysteresis and
+  near/far swap are covered by `test_avatar_mesh_budget_and_lod_swap`.
+- Evening readability is represented by the day/night/LATE final-context set;
+  LATE is the venue night variant.
+
+## Before/after workflow
+
+Keep the baseline directory, rebuild the same capture into a new directory after
+the model changes, then produce a comparison sheet. Do not overwrite the
+committed baseline image:
+
+```bash
+godot --path . --script res://src/test/capture_npc_baseline.gd -- \
+  --out=res://tmp/npc-baseline-after
+python3 tools/npc_baseline.py compare \
+  --before tmp/npc-baseline --after tmp/npc-baseline-after \
+  --out tmp/npc-baseline-compare.jpg
+```
+
+The comparison sheet places the before/after pair for each view side by side.
+The committed runs are
+[`sheet_npc_baseline_compare-p1.jpg`](blender_previews/sheet_npc_baseline_compare-p1.jpg),
+[`sheet_npc_baseline_compare-body.jpg`](blender_previews/sheet_npc_baseline_compare-body.jpg)
+and [`sheet_npc_baseline_compare-face.jpg`](blender_previews/sheet_npc_baseline_compare-face.jpg).
+The transition pass is [`sheet_npc_baseline_compare-torso.jpg`](blender_previews/sheet_npc_baseline_compare-torso.jpg).
+The face-detail pass is [`sheet_npc_baseline_compare-face-detail.jpg`](blender_previews/sheet_npc_baseline_compare-face-detail.jpg).
+The hand pass is [`sheet_npc_hands_compare.jpg`](blender_previews/sheet_npc_hands_compare.jpg);
+the forward-grip pass is
+[`sheet_npc_hands_grip_compare.jpg`](blender_previews/sheet_npc_hands_grip_compare.jpg).
+Keep the baseline sheet as the before artifact and add a new comparison sheet
+rather than replacing it.
+
+## Next implementation order
+
+0.9.4 is closed. The next visual work belongs to the 0.9.5 texture pass and the
+0.10.0 acceptance review; keep the NPC baseline/final-context commands as the
+regression gate for any future character edit.

docs/screen-design-report.md

@@ -0,0 +1,14 @@
+# Screen-design judge report
+
+Date: 2026-11-02
+Model: automatic cheapest image+JSON selection (`z-ai/glm-5.3-flash` at run time)
+Command: `python3 tools/screen_designs.py judge`
+Result: **21/21 match, 0 review, 0 diff**
+
+The screenshot gallery was regenerated on the current build before judging, including the eight UI-state captures 14–21 added in `src/test/capture_ui_states.gd`.
+Accepted captures are in [`docs/screens/`](screens/README.md); the committed
+gallery is in [`docs/screenshots/`](screenshots/README.md).
+
+The automatic model selection and retry/spend behavior is documented in
+[`docs/asset-tooling.md`](asset-tooling.md). This report intentionally records
+the outcome rather than generated captures, which remain local/gitignored.

docs/screens/README.md

@@ -0,0 +1,17 @@
+# Screens and Visual Evidence
+
+Visual references and generated QA evidence for Gig Line.
+
+- [`concepts/README.md`](concepts/README.md) — AI-assisted realism concept frames
+- [`designs/README.md`](designs/README.md) — screen-design mockups
+- [`../screenshots/README.md`](../screenshots/README.md) — committed game gallery
+- `realism/` — locally generated realism runs (gitignored; no README requirement)
+
+## Quick preview
+
+| Screen | Reference | Current capture |
+| --- | --- | --- |
+| Venue | <img src="designs/venue_overview.png" width="320" alt="Venue design"> | <img src="../screenshots/01-venue-overview.png" width="320" alt="Venue capture"> |
+| Joke Shop | <img src="concepts/joke_shop/joke_shop_entrance_day.png" width="320" alt="Joke Shop reference"> | <img src="../screenshots/12-joke-shop.png" width="320" alt="Joke Shop capture"> |
+| TV Studio | <img src="designs/studio_arrival.png" width="320" alt="Studio design"> | <img src="../screenshots/13-studio-arrival.png" width="320" alt="Studio capture"> |
+| El Capitan | <img src="concepts/hollywood_boulevard/hollywood_boulevard_entrance_day.png" width="320" alt="El Capitan reference"> | <img src="../screenshots/01-venue-overview.png" width="320" alt="El Capitan capture"> |

docs/screens/concepts/README.md

@@ -1,40 +1,103 @@
 # Scene concepts: the realistic target look
 
-These are AI-generated example frames (`python3 tools/scene_concepts.py generate --group scene`,
+These are AI-generated example frames (`python3 tools/scene_concepts.py generate --group scene`, `openai/gpt-5-image-mini`, 1280×720) for the realism pass. They are art direction, not assets. `tools/scene_concepts.py realism` pairs them with the in-game shots from `src/test/capture_realism.gd` (see `SHOTS` in the tool). New generations never overwrite a file here; they are saved as `<name>-vN.png`.
-`openai/gpt-5-image-mini`, 1280×720) for the realism pass. They are art direction, not
-assets. `tools/scene_concepts.py realism` pairs them with the in-game shots from
-`src/test/capture_realism.gd` (see `SHOTS` in the tool). New generations never overwrite a
-file here; they are saved as `<name>-vN.png`.
 
-| Concept | Visual targets it sets |
+## Real-world Hollywood block
-| --- | --- |
-| `hollywood_entrance_morning` | warm low sun, long soft shadows, brick with visible mortar and wear, stone plinth, potted topiary, haze that fades the far street to beige |
-| `hollywood_entrance_golden_hour` | strong back light and rim light on people, marquee bulbs reading even in daylight |
-| `hollywood_entrance_rain_night` | dark scene lit by practical lights only (marquee, sodium lamps), wet glossy ground with reflections, fog |
-| `boulevard_skyline_day` | deep layered skyline with real towers and haze, palms lining the road, red curb paint, believable asphalt |
-| `boulevard_skyline_dusk` | purple/orange gradient sky, neon signs, lit windows, car light trails |
-| `joke_shop_alley_evening` | narrow brick alley, one warm wall lantern as key light, deep shadows, people in dark jackets |
-| `joke_shop_door_closeup` | close material detail: brick, mortar, aged wood door, brass |
-| `studio_stage_door_night` | granite facade, a bright bulb canopy as the main light, a glossy black car, stanchions and a barrier |
-| `sidewalk_material_closeup` | paver joints, stains, granite curb, aggregate asphalt and a tree grate at grazing light |
-| `entrance_steps_podium` | granite steps, handrails, glass doors, the check-in podium |
-| `crowd_barrier_line` | steel barriers, a red carpet, a crowd with depth-of-field haze |
-| `responder_arrival_wide` | fire engine, turnout gear, red/blue light spill on wet pavement |
-| `npc_portrait_day` | close portrait of a pedestrian: skin with visible pores and stubble, fabric weave, shallow depth of field. The bar for an avatar close-up, not for the crowd shots |
 
-The `npc_portrait` capture in `capture_realism.gd` is staged, not posed by the
+The map-optimization references for the El Capitan Entertainment Centre block
-crowd: it freezes one NPC on an open patch of sidewalk, parks the rest of the
+(6840 Hollywood Blvd) are in
-crowd out of frame, turns the subject into the camera and stands the guard on the
+[`hollywood_boulevard/README.md`](hollywood_boulevard/README.md). The real-site
-sunlit side. It is the only shot where a face fills the frame, so it is the one to
+facts and game mapping are documented in
-eyeball after an avatar change (generate a local run under `docs/screens/realism/`).
+[`../../hollywood-boulevard-map.md`](../../hollywood-boulevard-map.md).
+
+## Concept list
+
+### Hollywood Entrance
+
+![hollywood entrance morning](hollywood_entrance_morning.png)
+warm low sun, long soft shadows, brick with visible mortar and wear, stone plinth, potted topiary, haze that fades the far street to beige
+
+### Hollywood Entrance Golden Hour
+
+![hollywood entrance golden hour](hollywood_entrance_golden_hour.png)
+strong back light and rim light on people, marquee bulbs reading even in daylight
+
+### Hollywood Entrance Rain Night
+
+![hollywood entrance rain night](hollywood_entrance_rain_night.png)
+dark scene lit by practical lights only (marquee, sodium lamps), wet glossy ground with reflections, fog
+
+### Boulevard Skyline
+
+![boulevard skyline day](boulevard_skyline_day.png)
+deep layered skyline with real towers and haze, palms lining the road, red curb paint, believable asphalt
+
+### Boulevard Skyline Dusk
+
+![boulevard skyline dusk](boulevard_skyline_dusk.png)
+purple/orange gradient sky, neon signs, lit windows, car light trails
+
+### The Joke Shop — Sunset Strip
+
+The current Joke Shop map is based on The Comedy Store at 8433 Sunset Blvd.
+The real-site mapping, simplifications and reference photographs are in
+[`../../joke-shop-map.md`](../../joke-shop-map.md); the frames are in
+[`joke_shop/README.md`](joke_shop/README.md).
+
+![Joke Shop entrance in daylight](joke_shop/joke_shop_entrance_day.png)
+
+![Joke Shop entrance at night](joke_shop/joke_shop_entrance_night.png)
+
+### Legacy Joke Shop Alley (pre-map optimization)
+
+![joke shop alley evening](joke_shop_alley_evening.png)
+narrow brick alley, one warm wall lantern as key light, deep shadows, people in dark jackets
+
+![joke shop door closeup](joke_shop_door_closeup.png)
+close material detail: brick, mortar, aged wood door, brass
+
+These two frames describe the old alley layout and are retained for comparison;
+they are no longer the target for the Joke Shop map.
+
+### Studio Stage Door Night
+
+![studio stage door night](studio_stage_door_night.png)
+granite facade, a bright bulb canopy as the main light, a glossy black car, stanchions and a barrier
+
+### Sidewalk Material Closeup
+
+![sidewalk material closeup](sidewalk_material_closeup.png)
+paver joints, stains, granite curb, aggregate asphalt and a tree grate at grazing light
+
+### Entrance Steps Podium
+
+![entrance steps podium](entrance_steps_podium.png)
+granite steps, handrails, glass doors, the check-in podium
+
+### Crowd Barrier Line
+
+![crowd barrier line](crowd_barrier_line.png)
+steel barriers, a red carpet, a crowd with depth-of-field haze
+
+### Responder Arrival Wide
+
+![responder arrival wide](responder_arrival_wide.png)
+fire engine, turnout gear, red/blue light spill on wet pavement
+
+### NPC Portrait Day
+
+![npc portrait day](npc_portrait_day.png)
+close portrait of a pedestrian: skin with visible pores and stubble, fabric weave, shallow depth of field. The bar for an avatar close-up, not for the crowd shots
+
+The `npc_portrait` capture in `capture_realism.gd` is staged, not posed by the crowd: it freezes one NPC on an open patch of sidewalk, parks the rest of the crowd out of frame, turns the subject into the camera and stands the guard on the sunlit side. It is the only shot where a face fills the frame, so it is the one to eyeball after an avatar change (generate a local run under `docs/screens/realism/`).
 
 Cross-cutting targets, for comparison with locally generated realism runs:
 
-- **Exposure.** The concepts keep the ground mid-grey. The game's sidewalk is close to white,
+- **Exposure.** The concepts keep the ground mid-grey. The game's sidewalk is close to white, so it is overexposed.
-  so it is overexposed.
+- **Night means dark.** The night/dusk concepts are lit by practical lights. The game's "Evening" phase is a bright pink-orange frame.
-- **Night means dark.** The night/dusk concepts are lit by practical lights. The game's
+- **Depth.** The concepts show a layered skyline fading into haze. The new v2 skyline strips supply this; the old box skyline did not.
-  "Evening" phase is a bright pink-orange frame.
+- **Geometry and foliage.** The facades have plinths, cornices and deep window reveals, and the trees and shrubs are organic. The game uses flat walls and blob trees.
-- **Depth.** The concepts show a layered skyline fading into haze. The new v2 skyline strips
+
-  supply this; the old box skyline did not.
+## Additional previews
-- **Geometry and foliage.** The facades have plinths, cornices and deep window reveals, and the
+
-  trees and shrubs are organic. The game uses flat walls and blob trees.
+![npc_portrait_day-v2.png](npc_portrait_day-v2.png)

docs/screens/concepts/hollywood_boulevard/README.md

@@ -0,0 +1,19 @@
+# Hollywood Boulevard references
+
+AI-generated art-direction frames for the real El Capitan Entertainment Centre
+block at 6840 Hollywood Boulevard. They are generated with
+`tools/scene_concepts.py generate --group scene --only ...` and are not shipped
+game textures. The geometry mapping and source links are in
+[`../../../hollywood-boulevard-map.md`](../../../hollywood-boulevard-map.md).
+
+## Entrance — day
+
+![El Capitan Entertainment Centre entrance in daylight](hollywood_boulevard_entrance_day.png)
+
+## Entrance — night
+
+![El Capitan Entertainment Centre entrance at night](hollywood_boulevard_entrance_night.png)
+
+## Across the boulevard
+
+![Ovation Hollywood frontage across the boulevard](hollywood_boulevard_across_street.png)

docs/screens/concepts/joke_shop/README.md

@@ -0,0 +1,23 @@
+# The Joke Shop references
+
+AI-generated art-direction frames for the fictional Joke Shop, based on the
+real Comedy Store block at 8433 Sunset Boulevard. They are generated with
+`tools/scene_concepts.py generate --group scene --only ...` and are not shipped
+game textures. The geometry mapping and source links are in
+[`../../../joke-shop-map.md`](../../../joke-shop-map.md).
+
+## Entrance — day
+
+![The black comedy club under its signature canopy in daylight](joke_shop_entrance_day.png)
+
+## Entrance — night
+
+![The club at night with the circular sign and warm entrance](joke_shop_entrance_night.png)
+
+## Across Sunset
+
+![The club seen from across Sunset Boulevard](joke_shop_across_street.png)
+
+The older top-level concepts `joke_shop_alley_evening.png` and
+`joke_shop_door_closeup.png` are kept as a record of the pre-map-optimization
+alley design. They no longer describe the current Joke Shop map.

docs/screens/designs/README.md

@@ -0,0 +1,29 @@
+# Screens/Designs
+
+Screen-design mockups used by the comparison and vision-judge gates for the runtime UI.
+
+## Image previews
+
+| Preview | File |
+| --- | --- |
+| <img src="access_inspection.png" width="280" alt="access_inspection.png"> | [`access_inspection.png`](access_inspection.png) |
+| <img src="body_camera_timeline.png" width="280" alt="body_camera_timeline.png"> | [`body_camera_timeline.png`](body_camera_timeline.png) |
+| <img src="crowd_panic.png" width="280" alt="crowd_panic.png"> | [`crowd_panic.png`](crowd_panic.png) |
+| <img src="emergency_radio.png" width="280" alt="emergency_radio.png"> | [`emergency_radio.png`](emergency_radio.png) |
+| <img src="escalation_hud.png" width="280" alt="escalation_hud.png"> | [`escalation_hud.png`](escalation_hud.png) |
+| <img src="joke_shop_queue.png" width="280" alt="joke_shop_queue.png"> | [`joke_shop_queue.png`](joke_shop_queue.png) |
+| <img src="late_night_avenue.png" width="280" alt="late_night_avenue.png"> | [`late_night_avenue.png`](late_night_avenue.png) |
+| <img src="movement_precision.png" width="280" alt="movement_precision.png"> | [`movement_precision.png`](movement_precision.png) |
+| <img src="night_flashlight.png" width="280" alt="night_flashlight.png"> | [`night_flashlight.png`](night_flashlight.png) |
+| <img src="pause_overlay.png" width="280" alt="pause_overlay.png"> | [`pause_overlay.png`](pause_overlay.png) |
+| <img src="prop_gallery.png" width="280" alt="prop_gallery.png"> | [`prop_gallery.png`](prop_gallery.png) |
+| <img src="radial_menu.png" width="280" alt="radial_menu.png"> | [`radial_menu.png`](radial_menu.png) |
+| <img src="radio_report.png" width="280" alt="radio_report.png"> | [`radio_report.png`](radio_report.png) |
+| <img src="responder_arrival.png" width="280" alt="responder_arrival.png"> | [`responder_arrival.png`](responder_arrival.png) |
+| <img src="settings_panel.png" width="280" alt="settings_panel.png"> | [`settings_panel.png`](settings_panel.png) |
+| <img src="shift_review.png" width="280" alt="shift_review.png"> | [`shift_review.png`](shift_review.png) |
+| <img src="start_menu.png" width="280" alt="start_menu.png"> | [`start_menu.png`](start_menu.png) |
+| <img src="studio_arrival.png" width="280" alt="studio_arrival.png"> | [`studio_arrival.png`](studio_arrival.png) |
+| <img src="targeting_npc.png" width="280" alt="targeting_npc.png"> | [`targeting_npc.png`](targeting_npc.png) |
+| <img src="venue_overview.png" width="280" alt="venue_overview.png"> | [`venue_overview.png`](venue_overview.png) |
+| <img src="wand_screening.png" width="280" alt="wand_screening.png"> | [`wand_screening.png`](wand_screening.png) |

docs/screenshots/README.md

@@ -0,0 +1,29 @@
+# Screenshots
+
+Committed gallery captures generated from the current build by src/test/capture_screenshots.gd, src/test/capture_ui_states.gd and src/test/capture_prop_gallery.gd.
+
+## Image previews
+
+| Preview | File |
+| --- | --- |
+| <img src="01-venue-overview.png" width="280" alt="01-venue-overview.png"> | [`01-venue-overview.png`](01-venue-overview.png) |
+| <img src="02-targeting-npc.png" width="280" alt="02-targeting-npc.png"> | [`02-targeting-npc.png`](02-targeting-npc.png) |
+| <img src="03-access-inspection.png" width="280" alt="03-access-inspection.png"> | [`03-access-inspection.png`](03-access-inspection.png) |
+| <img src="04-radio-report.png" width="280" alt="04-radio-report.png"> | [`04-radio-report.png`](04-radio-report.png) |
+| <img src="05-late-night-avenue.png" width="280" alt="05-late-night-avenue.png"> | [`05-late-night-avenue.png`](05-late-night-avenue.png) |
+| <img src="06-night-flashlight.png" width="280" alt="06-night-flashlight.png"> | [`06-night-flashlight.png`](06-night-flashlight.png) |
+| <img src="07-wand-screening.png" width="280" alt="07-wand-screening.png"> | [`07-wand-screening.png`](07-wand-screening.png) |
+| <img src="08-escalation-hud.png" width="280" alt="08-escalation-hud.png"> | [`08-escalation-hud.png`](08-escalation-hud.png) |
+| <img src="09-body-camera-timeline.png" width="280" alt="09-body-camera-timeline.png"> | [`09-body-camera-timeline.png`](09-body-camera-timeline.png) |
+| <img src="10-prop-gallery.png" width="280" alt="10-prop-gallery.png"> | [`10-prop-gallery.png`](10-prop-gallery.png) |
+| <img src="11-precision-walk.png" width="280" alt="11-precision-walk.png"> | [`11-precision-walk.png`](11-precision-walk.png) |
+| <img src="12-joke-shop.png" width="280" alt="12-joke-shop.png"> | [`12-joke-shop.png`](12-joke-shop.png) |
+| <img src="13-studio-arrival.png" width="280" alt="13-studio-arrival.png"> | [`13-studio-arrival.png`](13-studio-arrival.png) |
+| <img src="14-start-menu.png" width="280" alt="14-start-menu.png"> | [`14-start-menu.png`](14-start-menu.png) |
+| <img src="15-pause-overlay.png" width="280" alt="15-pause-overlay.png"> | [`15-pause-overlay.png`](15-pause-overlay.png) |
+| <img src="16-settings-panel.png" width="280" alt="16-settings-panel.png"> | [`16-settings-panel.png`](16-settings-panel.png) |
+| <img src="17-shift-review.png" width="280" alt="17-shift-review.png"> | [`17-shift-review.png`](17-shift-review.png) |
+| <img src="18-emergency-radio.png" width="280" alt="18-emergency-radio.png"> | [`18-emergency-radio.png`](18-emergency-radio.png) |
+| <img src="19-radial-menu.png" width="280" alt="19-radial-menu.png"> | [`19-radial-menu.png`](19-radial-menu.png) |
+| <img src="20-crowd-panic.png" width="280" alt="20-crowd-panic.png"> | [`20-crowd-panic.png`](20-crowd-panic.png) |
+| <img src="21-responder-arrival.png" width="280" alt="21-responder-arrival.png"> | [`21-responder-arrival.png`](21-responder-arrival.png) |

docs/smoke-checklist.md

@@ -39,4 +39,12 @@
 37. The F debug overlay lists the next eligible events; recovery events and recently played scripted events behave as authored.
 38. Master/SFX/ambience volume settings clamp at 0/1 and persist; Reduce motion disables head bob; the captions toggle persists.
 39. The 24-NPC budget smoke stays inside its frame budget; coats/dresses do not show obvious leg clipping in a normal walk.
-40. Help remains readable with the largest HUD font scale, and the engine matrix (4.3 CI / 4.7.2 local) is used for verification.
+40. Help remains readable with the largest HUD font scale, and CI/local verification use the same Godot 4.7.2 baseline.
+41. UI copy: inspection/wand use "A = admit · D = refuse entry", review returns with "Return to menu", and application exit reads "Quit game".
+42. Button states remain readable on hover/focus/pressed; settings Apply/Cancel and radio normal-send/emergency-hold behave as labelled.
+43. The venue menu offers Hollywood Boulevard — Day and — Night; either starts the same map, and Night starts in the late phase with a full shift clock.
+44. The Joke Shop opens on the Sunset Strip club: the black hall, signature canopy, circular **THE JOKE SHOP** sign, red curtains, west entrance, palms, dry hillside with houses, neighbouring frontage and the opposite side of Sunset all read from the door camera. Day lighting and late lighting both look correct; the guard can walk the sidewalk without leaving the nav bounds.
+45. Esc and right-click close only the top panel (Help, Settings, Pause, Review, Radio, timeline, inspection/wand, action wheel); Settings opened from the venue menu returns to the menu, Help no longer opens Pause behind it, and closing a modal recaptures the mouse without leaving the guard frozen.
+46. At 0.75× and 1.75× HUD font scale, long target names stay inside the target chip, the chip grows/caps correctly, and long button labels ellipsize instead of pushing panels off-screen.
+47. Reset campaign and Replay tutorial both ask for confirmation; a second click reuses the open dialog, Cancel does nothing, and OK fires once. Emergency send requires the full hold, sends exactly once, and does not send again on release.
+48. UI copy/button sweep: every panel uses the canonical admit/refuse, warning/blocking, assistance/emergency and body-camera terms; the start menu, pause, settings, Help, inspection, wand, radio, wheel, timeline and shift review all show readable hover/focus/pressed/disabled states; Tab/arrow focus wraps without landing on hidden or disabled actions; Esc/right-click closes only the top panel; and destructive reset/replay plus emergency send still require their confirmation or hold.

docs/ui-copy.md

@@ -0,0 +1,229 @@
+# UI copy and button inventory
+
+Status: dialogue, button-state, focus, modal-close, font/layout, destructive-action and end-to-end passes complete; capture/smoke sign-off remains for 0.9.3.
+
+## Screen inventory
+
+| Screen / panel | Owner | Primary actions | Notes |
+| --- | --- | --- | --- |
+| Start / venue menu | `start_menu.gd` | Continue shift, choose venue, Help, Settings, Quit | Campaign status and free-play venues share this screen. |
+| Tutorial card | `tutorial_overlay.gd` | F1 skip | Non-blocking; no mouse capture. |
+| HUD | `hud.gd` | Observe, target, inspect, wheel, radio, flashlight, body camera, door, pause | No interactive controls; must stay mouse-transparent. |
+| Action wheel | `action_radial.gd` | Choose de-escalation/access/radio action | Confirm with Space/click; cancel with Esc/RMB. |
+| Access inspection | `hud.gd` | A = admit, D = refuse | Real access evidence cards. |
+| Wand screening | `hud.gd` | A = admit, D = refuse | Shows alert and carried items. |
+| Radio / emergency | `radio_panel.gd` | Send request / hold Send emergency, Cancel | Normal click vs emergency hold. |
+| Pause | `pause_overlay.gd` | Resume, restart, Settings, quit to menu | Esc resumes. |
+| Settings | `settings_panel.gd` | Apply, Cancel, Replay tutorial, Reset campaign, rebind controls | Both reset and tutorial replay ask for confirmation. |
+| Help | `help_overlay.gd` | Filter controls, Close | Policy card and current bindings. |
+| Shift review | `shift_review.gd` | Continue campaign, timeline, return to menu, quit | Campaign next step is shown here. |
+| Timeline | `event_timeline.gd` | Previous, Next, Close | Review evidence stepper. |
+
+## Canonical terms
+
+- **Admit / refuse** — access decisions. Do not alternate with “allow / deny” or “grant / reject” in player-facing controls.
+- **Warning** — Level 2.
+- **Blocking** — Level 3 positioning; do not call it “force”.
+- **Assistance** — Level 4 radio call; **emergency** is Level 5.
+- **Body camera** — always two words.
+- **Shift review** — the end-of-shift screen; “review” alone is acceptable in prose.
+- **Continue campaign** — advance to the next venue.
+- **Return to menu** — leave the review to the venue menu (it does not start a new shift by itself).
+- **Send request** — non-emergency assistance; **Send emergency** — emergency call.
+- **Hollywood Boulevard — Day / Night** — the two scenery variants in the venue menu. Use an em dash and title case for the variant; do not call them “maps” in player-facing copy.
+
+## Button labels and states
+
+| Surface | Label | Behavior | State audit |
+| --- | --- | --- | --- |
+| Start menu | Continue shift — <venue> | Resume/advance campaign | Hidden when complete; venue-specific |
+| Start menu | Venue rows | Start free-play/campaign venue | Hover/focus/pressed styled |
+| Start menu | Help | Open Help overlay | Standard button |
+| Start menu | Settings | Open Settings | Standard button |
+| Start menu | Quit game | Exit application | Destructive; label clarifies scope |
+| Tutorial | F1 skip tutorial | Skip lesson | Keyboard only, non-blocking |
+| Action wheel | Stop/Look/Point/No/Ask/Inspect/Wand/Warn/Block/Reason/Recognize/Radio | Choose verb | Hover/selection highlight |
+| Inspection | A = admit · D = refuse entry | Access decision | Keyboard hints, policy text |
+| Wand | A = admit · D = refuse entry | Screening decision | Keyboard hints, item/alert text |
+| Radio | Send request | Submit assistance | Normal click |
+| Radio | Send emergency | Submit emergency | Hold-to-confirm; Cancel aborts |
+| Radio | Cancel | Close form | Standard button |
+| Pause | Resume | Resume shift | Default focus |
+| Pause | Restart shift | Restart current shift | Standard button |
+| Pause | Settings | Open Settings | Standard button |
+| Pause | Quit to menu | Return to venue menu | Standard button |
+| Settings | Apply settings | Persist settings | Standard button |
+| Settings | Cancel | Discard edits | Standard button |
+| Settings | Replay tutorial | Confirm, then clear tutorial flags and restart Hollywood | Confirmation dialog |
+| Settings | Reset campaign | Confirm, then reset campaign progress | Confirmation dialog |
+| Help | Close | Close overlay | Standard button |
+| Review | Continue campaign | Start next venue | Hidden when campaign complete |
+| Review | Body camera timeline | Open event timeline | Standard button |
+| Review | Return to menu | Return to venue menu | Standard button |
+| Review | Quit game | Exit application | Standard button |
+| Timeline | Previous / Next / Close | Step/close evidence | Standard buttons |
+
+## Button/label issues found
+
+- HUD inspection and wand used “allow/deny” versus “admit/refuse”; both now use **A = admit · D = refuse entry**.
+- Shift review’s old “Run another shift” actually returned to the menu; renamed **Return to menu**.
+- Radio emergency action used all-caps while assistance used sentence case; both are now sentence case, with the warning in the panel title/hold hint.
+- Normal radio send was previously wired only to the emergency hold handlers; fixed in 0.8.1 and covered by `test_radio_panel.gd`.
+- “Quit” was ambiguous between menu and application exit; both application-exit buttons now read **Quit game**.
+- Settings “Apply” was made verb+object as **Apply settings**.
+
+## Dialogue audit
+
+The NPC reason verb now uses the authored `reason` context instead of always
+falling back to the general dialogue lines. Every shared archetype has at least
+one role-specific reason answer, so asking a staff member, guest, delivery
+worker or performer no longer produces an unexplained silence. Deliberately
+silent profiles can still return an empty context line.
+
+| Surface | Finding | Result |
+| --- | --- | --- |
+| Shared NPC reasons | `request_reason()` ignored `context_lines["reason"]`; staff, guests, delivery, performers, intoxicated people, crisis and threat profiles had no answer. | Fixed; all 12 shared archetypes now answer in character. |
+| Door staff | Only The Joke Shop authored door lines. | Hollywood has wristband lines; the Studio has ticket/credential/guest-list lines; the inspection log selects the venue context. |
+| Radio | “Call cancelled” could read as if a call had been sent; the description placeholder was ungrammatical. | “Call not sent — hold the button to confirm.” and “Describe the person and their behavior.” |
+| Tutorial / Help | The wheel verb is **Ask**, but help and the HUD key strip called it “polite direction”. | Both now say **Ask**; the tutorial tells the player to choose Ask after closing the panel. |
+| Review / campaign | Continue/return/quit labels and campaign-next copy checked. | No ambiguity found; no change. |
+| Repetition | Shared tourist/confused/delivery lines recur across venues by design; role-specific reason lines prevent every archetype sounding alike. | Accepted for the shared-archetype model. |
+| Localization length | Longest authored NPC/door line is 56 characters; longest UI string is `hud.controls` at 172 characters. | Dialogue fits the HUD log; long-string/font-scale layout is covered below. |
+
+## Button state audit
+
+All `Button` controls now use `src/game/ui/ui_styles.gd`, which defines explicit
+**normal**, **hover**, **pressed**, **focus** and **disabled** styles plus the
+matching font colours. This removes the engine-theme fallback that previously
+appeared when a custom dark button was disabled or focused by keyboard.
+
+| Surface | States / behavior checked | Result |
+| --- | --- | --- |
+| Start menu | Venue rows, Continue, Help, Settings, Quit; focus clamped to the list; Continue hidden when the campaign is complete. | All buttons styled; hidden state is intentional, not a disabled state. |
+| Tutorial | F1 skip is a keyboard shortcut, not a button; its hint is non-interactive. | Keyboard-only by design; no hover/focus state to style. |
+| Pause | Resume, Restart, Settings, Quit to menu; Resume receives focus on open. | All four states styled; focus is distinct from hover. |
+| Settings | Replay tutorial, Reset campaign, key-binding rows, Apply settings, Cancel; rebinding shows “Press…” while listening. | All action buttons styled; reset-confirmation dialog OK/Cancel styled; fields keep the engine control theme. |
+| Help | Close; Esc still closes. | Styled; no disabled state is used. |
+| Shift review | Continue campaign, Body camera timeline, Return to menu, Quit game; Continue hidden when the campaign is complete. | All styled; hidden state is intentional. |
+| Timeline | Previous/Next/Close; Previous is disabled at the first event, Next at the last, and both when empty. | Disabled state verified in `test_event_timeline.gd`; Close stays enabled. |
+| Radio | Send request, Send emergency, Cancel. Emergency hold uses press/release, so the action button stays enabled while holding. | All styled; disabling it during the hold would break confirmation. |
+| Toggles | CheckButton/OptionButton controls keep the engine theme. | Intentional: the shared style targets action buttons, not checkbox/radio affordances. |
+
+## Keyboard and gamepad focus
+
+`UiFocus` builds an explicit focus ring for each modal, skips hidden and
+disabled controls, and makes Up/Down, Tab/Shift+Tab and the D-pad/stick wrap.
+`GuardController._ensure_gamepad_bindings()` adds A to `ui_accept` and B to
+`ui_cancel`; the built-in directional UI actions already carry D-pad/stick
+events.
+
+| Surface | Default focus | Cancellation / trap check |
+| --- | --- | --- |
+| Start menu | First visible target: Continue when present, otherwise the first venue. | A/Enter/Space activates the focused row; B/Esc quits; Continue, venue rows and footer actions share one wrapping ring. |
+| Pause | Resume. | B/Esc resumes; the four actions wrap. |
+| Settings | First slider. | B/Esc cancels; focus ring covers sliders, toggles, difficulty, rebinds, Apply and Cancel; sliders keep Left/Right for value adjustment. |
+| Help | Search field. | B/Esc closes; Search and Close share a ring. |
+| Shift review | Continue when available, otherwise the timeline. | B/Esc returns to the menu; all four actions are in the ring and hidden Continue is skipped. |
+| Timeline | First enabled action: Next when Previous is disabled, Close when empty. | B/Esc closes; Previous/Next leave the ring when disabled so focus cannot land on a dead button. |
+| Radio | Send action. | B/Esc cancels; form fields, action and Cancel are linked; A confirms the focused action. |
+| Tutorial | None; F1 is the documented skip shortcut. | Keyboard-only by design, no focus trap because the card is mouse-transparent and non-modal. |
+
+## Modal close and pointer recapture
+
+`GameManager._close_top_modal()` is now the single close path for the top
+interactive layer. It handles the radial, inspection, wand, radio, timeline,
+Help, Settings, Pause and review before Esc/right-click falls back to target
+clearing or pause. `_refresh_freeze()` recaptures the mouse when the shift
+resumes; `_show_start_menu()` keeps the pointer visible at the menu.
+
+| Surface | Close routes | Result |
+| --- | --- | --- |
+| Pause | Resume, Esc, right-click | Closes via one path; guard unfreezes and mouse recaptures. |
+| Settings | Apply settings, Cancel, Esc, right-click | From the venue menu, both apply and cancel restore the menu. From a shift, cancel returns to the game with the guard unfrozen; apply returns to pause. |
+| Help | Close, Esc, right-click | Closes only Help; it no longer opens Pause behind the overlay. Returns to whatever was underneath. |
+| Shift review | Return to menu, Esc, right-click | Returns to the venue menu with the pointer visible. |
+| Timeline | Close, Esc, right-click | Returns to the review and keeps the pointer visible. |
+| Radio | Cancel, Esc, right-click | Closes the form, clears the action hint and recaptures the mouse. |
+| Inspection / wand | Esc, right-click | Closes the panel, unfreezes the guard and recaptures the mouse. |
+| Action wheel | Esc, right-click | Cancels without a log entry and recaptures the mouse. |
+| Start menu | Esc quits the application | Root menu; right-click is intentionally inert. |
+| Tutorial | F1 skip | Non-modal card; never blocks the pointer or movement. |
+
+The session smoke now covers menu → Settings → Cancel → menu, Help closing on
+right-click, and Settings cancel from pause leaving the guard unfrozen.
+
+## Destructive actions
+
+Campaign reset and tutorial replay both open a `ConfirmationDialog`; pressing
+the button again while it is open focuses the existing dialog instead of
+stacking a second one. The confirmation is dismissed and the signal is emitted
+at most once on OK; Cancel closes without emitting. The emergency radio remains
+a press-and-hold action: a normal click does nothing for an emergency, a short
+hold cancels, a full 1.6 s hold submits once, and the release after a completed
+hold cannot submit again.
+
+Regression coverage:
+- `test_session_shell.gd` checks reset reuse/one-shot and replay confirmation/cancel.
+- `test_radio_panel.gd` checks normal click, short hold, full hold and post-submit release.
+
+## Font-scale and long-string layout
+
+The HUD scale is tested at its **0.75×** and **1.75×** bounds. HUD top/time labels
+clip instead of crossing into each other, and the target chip now measures the
+scaled target text: normal long names widen the chip, while an extreme synthetic
+name is capped at 420 px and ellipsized. Action-button labels use `clip_text` and
+ellipsis in `UiStyles`, so a 1.5–2× pseudo-string cannot push a panel beyond the
+viewport. The menu shell intentionally keeps its own fixed typography; the HUD
+scale setting only changes HUD text.
+
+Regression coverage lives in `test_accessibility.gd` (target-chip width/cap) and
+`test_ui_buttons.gd` (long action-label minimum width). The pseudo-locale
+translator workflow remains a 0.10.0 task; this pass uses deterministic long
+strings and the maximum supported HUD scale.
+
+## End-to-end interaction flows
+
+`smoke_ui_flows.gd` boots the real scene and verifies, in order:
+
+- inspection opens, then allow and deny both close the panel;
+- a normal radio click sends and spends battery;
+- an emergency hold sends once, spends battery and starts cooldown;
+- Help opens, filters to radio controls and closes;
+- the wand opens at The Joke Shop, then allow and deny close it;
+- returning from the review restores the venue menu.
+
+`smoke_campaign.gd` covers review continue plus checkpoint resume, and
+`smoke_timeline.gd` covers review → timeline → review. These are end-to-end
+scene smokes, not just panel-unit tests.
+
+## Visual coverage
+
+`src/test/capture_ui_states.gd` completes the screen-design catalogue by staging
+the states that the scene captures did not cover. The gallery now has one
+deterministic current-build frame for every reference:
+
+| State | Capture | Design reference |
+| --- | --- | --- |
+| Start / venue menu | `14-start-menu.png` | `start_menu.png` |
+| Pause | `15-pause-overlay.png` | `pause_overlay.png` |
+| Settings | `16-settings-panel.png` | `settings_panel.png` |
+| Shift review | `17-shift-review.png` | `shift_review.png` |
+| Emergency radio | `18-emergency-radio.png` | `emergency_radio.png` |
+| Action wheel | `19-radial-menu.png` | `radial_menu.png` |
+| Crowd panic | `20-crowd-panic.png` | `crowd_panic.png` |
+| Responder arrival | `21-responder-arrival.png` | `responder_arrival.png` |
+
+The crowd-panic frame is taken 70 frames after the panic event so the staged
+group is visibly displaced from the steps toward the street; the responder is
+parked on the approach with the door locked so the arrival/secure state is
+readable. Both are presentation staging, not gameplay changes. `compare`
+reports **21 good / 0 bad** and the automatic judge **21/21 match, 0 diff**.
+The gallery is regenerated by `tools/check_screenshots.sh`.
+
+## Remaining audit work
+
+- Player-facing labels are now routed through `content/strings.en.json`; numeric
+  values, empty-state clears and debug-only text remain in code by design.
+- Focus/hover/pressed/disabled states and keyboard/gamepad rings are recorded above.
+- Pseudo-locale layout and a translator workflow remain scheduled for the
+  localization milestone, not this UI pass.

project.godot

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

src/content/scenario_factory.gd

@@ -22,6 +22,7 @@ static func shared_profiles() -> Array[NpcProfile]:
 	tourist.temperament = 0.1
 	tourist.base_compliance = 0.9
 	tourist.context_lines = {
+		"reason": ["Just getting a photo of the entrance.", "I'm meeting friends here."],
 		"refusal": ["I just want a photo, I'm not staying.", "I didn't know this entrance was restricted."],
 		"deescalation": ["Okay, I'll move to the sidewalk.", "Sorry, I'll put the camera away."],
 		"recognition": ["You remember me from the tour, right?"],
@@ -40,6 +41,7 @@ static func shared_profiles() -> Array[NpcProfile]:
 	confused.temperament = 0.2
 	confused.base_compliance = 0.85
 	confused.context_lines = {
+		"reason": ["I thought this was the box office.", "I'm looking for the event entrance."],
 		"refusal": ["I'm sure the event is here. Let me check my phone."],
 		"deescalation": ["Oh, I understand. I'll check with the box office."],
 	}
@@ -55,6 +57,9 @@ static func shared_profiles() -> Array[NpcProfile]:
 	delivery.npc_type = Rules.NpcType.DELIVERY
 	delivery.temperament = 0.25
 	delivery.base_compliance = 0.8
+	delivery.context_lines = {
+		"reason": ["Drop-off for the venue. Where should I leave it?"],
+	}
 	delivery.dialogue_lines = ["Where should I leave this?"]
 	profiles.append(delivery)
 
@@ -64,6 +69,9 @@ static func shared_profiles() -> Array[NpcProfile]:
 	performer.npc_type = Rules.NpcType.PERFORMER
 	performer.temperament = 0.45
 	performer.base_compliance = 0.55
+	performer.context_lines = {
+		"reason": ["Just doing my act; I'll keep the sidewalk clear."],
+	}
 	performer.reactions_by_level = {
 		Rules.Level.SIMPLE_DETERRENCE: {
 			Rules.Reaction.COMPLY: 55,
@@ -100,6 +108,9 @@ static func shared_profiles() -> Array[NpcProfile]:
 			Rules.Reaction.COMPLY: 10,
 		},
 	}
+	influencer.context_lines = {
+		"reason": ["Filming a quick clip for my channel."],
+	}
 	influencer.dialogue_lines = [
 		"This is public sidewalk, you can't stop me from filming.",
 	]
@@ -113,6 +124,9 @@ static func shared_profiles() -> Array[NpcProfile]:
 	intoxicated.temperament = 0.6
 	intoxicated.base_compliance = 0.4
 	intoxicated.reaction_delay = 1.8
+	intoxicated.context_lines = {
+		"reason": ["Looking for my friends. I think they went inside."],
+	}
 	intoxicated.reactions_by_level = {
 		Rules.Level.SIMPLE_DETERRENCE: {
 			Rules.Reaction.COMPLY: 30,
@@ -135,6 +149,9 @@ static func shared_profiles() -> Array[NpcProfile]:
 	trespasser.temperament = 0.55
 	trespasser.base_compliance = 0.35
 	trespasser.return_probability = 0.6
+	trespasser.context_lines = {
+		"reason": ["Meeting a friend inside. I'll only be a minute.", "Just cutting through."],
+	}
 	trespasser.reactions_by_level = {
 		Rules.Level.SIMPLE_DETERRENCE: {
 			Rules.Reaction.IGNORE: 45,
@@ -177,6 +194,9 @@ static func shared_profiles() -> Array[NpcProfile]:
 	mental_crisis.base_compliance = 0.3
 	mental_crisis.return_probability = 0.4
 	mental_crisis.reaction_delay = 2.4
+	mental_crisis.context_lines = {
+		"reason": ["I just need a quiet minute.", "I'm waiting for someone."],
+	}
 	mental_crisis.reactions_by_level = {
 		Rules.Level.SIMPLE_DETERRENCE: {
 			Rules.Reaction.IGNORE: 55,
@@ -214,6 +234,9 @@ static func shared_profiles() -> Array[NpcProfile]:
 	violent_threat.npc_type = Rules.NpcType.VIOLENT_THREAT
 	violent_threat.temperament = 0.95
 	violent_threat.base_compliance = 0.05
+	violent_threat.context_lines = {
+		"reason": ["Back off. This doesn't concern you."],
+	}
 	violent_threat.reactions_by_level = {
 		Rules.Level.SIMPLE_DETERRENCE: {
 			Rules.Reaction.THREATEN: 30,
@@ -250,6 +273,9 @@ static func shared_profiles() -> Array[NpcProfile]:
 	protester.temperament = 0.5
 	protester.base_compliance = 0.4
 	protester.return_probability = 0.25
+	protester.context_lines = {
+		"reason": ["We're demonstrating on the public sidewalk.", "This is a peaceful protest."],
+	}
 	protester.reactions_by_level = {
 		Rules.Level.SIMPLE_DETERRENCE: {
 			Rules.Reaction.ARGUE: 35,
@@ -290,6 +316,9 @@ static func shared_profiles() -> Array[NpcProfile]:
 	staff.npc_type = Rules.NpcType.AUTHORIZED_STAFF
 	staff.temperament = 0.15
 	staff.base_compliance = 1.0
+	staff.context_lines = {
+		"reason": ["I'm on staff. I'm checking the entrance.", "Crew check-in; I'm working tonight."],
+	}
 	staff.default_reactions = { Rules.Level.SIMPLE_DETERRENCE: { Rules.Reaction.COMPLY: 100 } }
 	profiles.append(staff)
 
@@ -299,6 +328,9 @@ static func shared_profiles() -> Array[NpcProfile]:
 	guest.npc_type = Rules.NpcType.AUTHORIZED_GUEST
 	guest.temperament = 0.2
 	guest.base_compliance = 0.95
+	guest.context_lines = {
+		"reason": ["I'm on the guest list. Here's my ID.", "A friend invited me; I have a ticket."],
+	}
 	guest.default_reactions = {
 		Rules.Level.SIMPLE_DETERRENCE: { Rules.Reaction.COMPLY: 92, Rules.Reaction.ARGUE: 8 },
 		Rules.Level.FORMAL_WARNING: { Rules.Reaction.COMPLY: 88, Rules.Reaction.ARGUE: 12 },
@@ -312,8 +344,8 @@ static func shared_profiles() -> Array[NpcProfile]:
 static func hollywood_building() -> VenueScenario:
 	var scenario := VenueScenario.new()
 	scenario.id = "hollywood_building"
-	scenario.display_name = "Hollywood Boulevard Building"
+	scenario.display_name = "El Capitan Entertainment Centre"
-	scenario.description = "Steps and entrance of a private building off Hollywood Boulevard."
+	scenario.description = "The historic 1921 Masonic Temple at 6840 Hollywood Boulevard, now the El Capitan Entertainment Centre."
 	scenario.shift_duration_s = 900.0
 
 	var policy := AccessPolicy.new()
@@ -322,6 +354,12 @@ static func hollywood_building() -> VenueScenario:
 	scenario.access_policy = policy
 
 	scenario.equipment = ["wristband_policy", "flashlight", "radio"]
+	scenario.door_staff_lines = {
+		"wristband_check": [
+			"Wristband, please.",
+			"I need to see your event wristband.",
+		],
+	}
 	scenario.locations = {
 		"guard_post": Vector3(0, 0, -3),
 		"entrance": Vector3(0, 0, 1.0),
@@ -352,6 +390,9 @@ static func hollywood_building() -> VenueScenario:
 		_building_routine("staff_entry", Rules.NpcType.AUTHORIZED_STAFF, "enter", Vector2(0, 600), 0.35),
 		_building_routine("guest_entry", Rules.NpcType.AUTHORIZED_GUEST, "enter", Vector2(0, 900), 0.25),
 		_building_routine("performer_show", Rules.NpcType.PERFORMER, "perform", Vector2(300, 800), 0.24),
+		_late_routine("late_tourist", Rules.NpcType.TOURIST, "photo", 0.22),
+		_late_routine("late_guest", Rules.NpcType.AUTHORIZED_GUEST, "enter", 0.20),
+		_late_routine("late_trespasser", Rules.NpcType.TRESPASSER, "trespass", 0.14),
 		{
 			"id": "building_filming_boundary",
 			"phase": Rules.Phase.MIDDAY,
@@ -586,6 +627,12 @@ static func tv_studio() -> VenueScenario:
 	scenario.access_policy = policy
 
 	scenario.equipment = ["wristband_policy", "guest_list", "radio", "flashlight"]
+	scenario.door_staff_lines = {
+		"ticket_check": [
+			"Ticket, credential, or guest-list confirmation, please.",
+			"I need your ticket or guest-list confirmation.",
+		],
+	}
 	scenario.locations = {
 		"guard_post": Vector3(0, 0, -3),
 		"entrance": Vector3(0, 0, 1.0),
@@ -710,6 +757,13 @@ static func profile_dictionary() -> Dictionary:
 
 # --- Event builders ----------------------------------------------------------------
 
+## Late-phase routine traffic. The range-based helper would classify a 700 s
+## start as evening, so the phase is set explicitly.
+static func _late_routine(id: String, npc_type: int, intent: String, prob: float) -> Dictionary:
+	var event := _building_routine(id, npc_type, intent, Vector2(700, 900), prob)
+	event["phase"] = Rules.Phase.LATE
+	return event
+
 static func _building_routine(id: String, npc_type: int, intent: String, time_range: Vector2, prob: float) -> Dictionary:
 	return {
 		"id": id, "phase": _phase_for_range(time_range, 900.0),

src/core/npc_controller.gd

@@ -166,11 +166,10 @@ func decide_leave() -> bool:
 ## Level 3 ask: request the person's reason for entry (PLAN.md). Pure and
 ## headless-testable; returns the line this NPC answers with ("" if silent).
 func request_reason() -> String:
-	var lines: Array[String] = profile.dialogue_lines if profile else []
+	# Prefer the authored "reason" context; profiles without one fall back to
-	if lines.is_empty():
+	# their general dialogue lines. Silence remains valid for a deliberately
-		last_reason_reply = ""
+	# silent character.
-		return ""
+	last_reason_reply = profile.line_for("reason", rng) if profile else ""
-	last_reason_reply = lines[rng.randi_range(0, lines.size() - 1)]
 	return last_reason_reply
 
 ## Perception pass: given the guard's distance (meters), return a perception

src/core/shift_coordinator.gd

@@ -24,6 +24,9 @@ var elapsed_s: float = 0.0
 ## Wall-clock start, so the shift review can show event times as mm:ss.
 var started_at_ms: int = 0
 var current_phase: int = Rules.Phase.EARLY
+## Shift time added when resolving the phase. A night variant starts at 0:00
+## elapsed but reads LATE, so its full shift stays after dark.
+var phase_offset_s: float = 0.0
 var running := false
 
 var event_bus := EventBus.new()
@@ -50,6 +53,8 @@ func setup(p_scenario: VenueScenario, p_duration_s: float = 900.0, p_seed: int =
 	duration_s = p_duration_s
 	spawn_seed = p_seed
 	scheduler.setup(scenario, p_seed)
+	phase_offset_s = 0.0
+	current_phase = Rules.Phase.EARLY
 	event_bus = EventBus.new()
 	responder_outcomes.clear()
 	investigations.clear()
@@ -101,17 +106,21 @@ func tick(delta: float) -> void:
 func _phase_for_time(t: float) -> int:
 	if scenario == null or scenario.shift_phases.is_empty():
 		return Rules.Phase.EARLY
+	var shifted := t + phase_offset_s
 	var last_phase := Rules.Phase.EARLY
 	var keys := scenario.shift_phases.keys()
 	keys.sort()
 	for phase in keys:
 		var start_s: float = scenario.shift_phases[phase].get("start_s", 0.0)
-		if t >= start_s:
+		if shifted >= start_s:
 			last_phase = phase
 	return last_phase
 
+func schedule_time_s() -> float:
+	return elapsed_s + phase_offset_s
+
 func _spawn_due(delta: float) -> void:
-	var due := scheduler.pull_due(elapsed_s, current_phase)
+	var due := scheduler.pull_due(schedule_time_s(), current_phase)
 	var fallback := scheduler.fallback_routine_traffic(current_phase)
 	var all := due
 	all.append_array(fallback)
@@ -161,6 +170,7 @@ func snapshot() -> Dictionary:
 		"duration_s": duration_s,
 		"elapsed_s": elapsed_s,
 		"current_phase": current_phase,
+		"phase_offset_s": phase_offset_s,
 		"spawned_count": spawned_count,
 		"responder_outcomes": responder_outcomes.duplicate(),
 		"investigations": investigations.duplicate(),
@@ -175,6 +185,7 @@ func restore(data: Dictionary) -> void:
 	duration_s = float(data.get("duration_s", duration_s))
 	elapsed_s = float(data.get("elapsed_s", 0.0))
 	current_phase = int(data.get("current_phase", Rules.Phase.EARLY))
+	phase_offset_s = float(data.get("phase_offset_s", 0.0))
 	spawned_count = int(data.get("spawned_count", 0))
 	responder_outcomes.clear()
 	for value in data.get("responder_outcomes", []):

src/game/game_manager.gd

@@ -45,9 +45,14 @@ var body_camera_on := false
 var coordinator: ShiftCoordinator = null
 var guard: GuardController = null
 var _sun: DirectionalLight3D = null
+var _fill: DirectionalLight3D = null
 var _env_node: WorldEnvironment = null
 var _sky: ProceduralSkyMaterial = null
 var _last_phase: int = -1
+## Menu-only alias for the night scenery variant; it resolves to the Hollywood
+## scenario with a LATE phase offset.
+const HOLLYWOOD_NIGHT_ID := "hollywood_building_night"
+var _start_phase_override: int = -1
 
 ## Per-phase lighting looks for the sun, sky, and ambient (PLAN.md: shift
 ## structure — phase-based lighting). Night phases switch street lamps on.
@@ -58,7 +63,7 @@ const PHASE_LIGHTING := {
 		"sky_ground": Color(0.45, 0.5, 0.55), "ambient": Color(0.75, 0.78, 0.85), "night": false,
 		"exposure": 0.6, "glow": 0.45, "fog_color": Color(0.87, 0.83, 0.76),
 		"fog_density": 0.0034, "fog_energy": 0.5, "contrast": 1.05, "saturation": 1.04,
-		"ambient_energy": 0.1, "volumetric_density": 0.004, "volumetric_energy": 0.0,
+		"ambient_energy": 0.1, "fill_energy": 0.22, "volumetric_density": 0.004, "volumetric_energy": 0.0,
 	},
 	Rules.Phase.MIDDAY: {
 		"sun_energy": 1.0, "sun_angle": -62.0, "sun_yaw": -30.0, "sun_color": Color(1.0, 0.99, 0.96),
@@ -66,7 +71,7 @@ const PHASE_LIGHTING := {
 		"sky_ground": Color(0.5, 0.54, 0.58), "ambient": Color(0.85, 0.88, 0.95), "night": false,
 		"exposure": 0.6, "glow": 0.4, "fog_color": Color(0.88, 0.87, 0.83),
 		"fog_density": 0.0028, "fog_energy": 0.5, "contrast": 1.06, "saturation": 1.04,
-		"ambient_energy": 0.28, "volumetric_density": 0.003, "volumetric_energy": 0.0,
+		"ambient_energy": 0.28, "fill_energy": 0.18, "volumetric_density": 0.003, "volumetric_energy": 0.0,
 	},
 	# Evening is dusk, not a bright sunset: the sun is almost down and the street
 	# is carried by the marquee, the lamps and the lit windows (realism pass).
@@ -76,7 +81,7 @@ const PHASE_LIGHTING := {
 		"sky_ground": Color(0.1, 0.09, 0.12), "ambient": Color(0.2, 0.19, 0.26), "night": true,
 		"exposure": 0.72, "glow": 0.8, "fog_color": Color(0.34, 0.27, 0.3),
 		"fog_density": 0.0026, "fog_energy": 0.45, "contrast": 1.1, "saturation": 1.05,
-		"ambient_energy": 0.12, "volumetric_density": 0.014, "volumetric_energy": 0.10,
+		"ambient_energy": 0.12, "fill_energy": 0.10, "volumetric_density": 0.014, "volumetric_energy": 0.10,
 	},
 	Rules.Phase.LATE: {
 		"sun_energy": 0.02, "sun_angle": -8.0, "sun_color": Color(0.3, 0.35, 0.5),
@@ -84,7 +89,7 @@ const PHASE_LIGHTING := {
 		"sky_ground": Color(0.03, 0.03, 0.05), "ambient": Color(0.06, 0.07, 0.12), "night": true,
 		"exposure": 0.95, "glow": 1.15, "fog_color": Color(0.08, 0.1, 0.2),
 		"fog_density": 0.0028, "fog_energy": 0.45, "contrast": 1.12, "saturation": 1.0,
-		"ambient_energy": 0.22, "volumetric_density": 0.020, "volumetric_energy": 0.14,
+		"ambient_energy": 0.30, "fill_energy": 0.06, "volumetric_density": 0.020, "volumetric_energy": 0.14,
 	},
 }
 var hud: Hud = null
@@ -94,6 +99,9 @@ var shift_review_panel: ShiftReview = null
 var start_menu: StartMenu = null
 var pause_overlay: PauseOverlay = null
 var settings_panel: SettingsPanel = null
+## Settings opened from the venue menu must return there on Cancel/Apply;
+## settings opened from pause must not leave a menu visible or the guard frozen.
+var _settings_from_start_menu := false
 var event_timeline: EventTimeline = null
 var tutorial_overlay: TutorialOverlay = null
 var help_overlay: HelpOverlay = null
@@ -222,7 +230,7 @@ func _build_guard() -> GuardController:
 	flashlight.spot_range = 30.0 if Materials.modern_light_falloff() else 20.0
 	flashlight.spot_angle = 14.0
 	flashlight.light_energy = 4.2
-	flashlight.spot_attenuation = 0.0 if Materials.modern_light_falloff() else 0.9
+	flashlight.spot_attenuation = 1.0
 	flashlight.spot_angle_attenuation = 0.9
 	# The volumetric shaft is a Forward+ (desktop HQ) effect. Compatibility and
 	# headless builds leave the light non-volumetric, so their look is unchanged.
@@ -265,6 +273,7 @@ func _build_scenario(id: String) -> VenueScenario:
 			return ScenarioFactory.hollywood_building()
 
 func switch_scenario(id: String) -> void:
+	_start_phase_override = -1
 	active_scenario_id = id
 	selected_scenario = _build_scenario(id)
 	_rebuild_world_for_venue(id)
@@ -315,6 +324,9 @@ func _reset_shift_state() -> void:
 		hud.set_body_camera(false)
 	scenario_duration_s = selected_scenario.shift_duration_s
 	coordinator.setup(selected_scenario, scenario_duration_s, 4242)
+	if _start_phase_override >= 0:
+		coordinator.phase_offset_s = _phase_start_s(_start_phase_override)
+		coordinator.current_phase = coordinator._phase_for_time(0.0)
 	coordinator.scheduler.spawn_rate_multiplier = float(_difficulty()["spawn"])
 	_connect_radio()
 	_connect_crowd()
@@ -336,10 +348,22 @@ func _start_shift() -> void:
 	# opens and closes.
 	_refresh_freeze()
 
+func _phase_start_s(phase: int) -> float:
+	if selected_scenario == null:
+		return 0.0
+	return float((selected_scenario.shift_phases.get(phase, {}) as Dictionary).get("start_s", 0.0))
+
 func _show_start_menu() -> void:
 	_shift_running = false
+	_settings_from_start_menu = false
 	if pause_overlay:
 		pause_overlay.close()
+	if settings_panel:
+		settings_panel.close()
+	if help_overlay:
+		help_overlay.close_panel()
+	if event_timeline:
+		event_timeline.close()
 	if shift_review_panel:
 		shift_review_panel.hide()
 	if guard:
@@ -353,6 +377,10 @@ func _on_venue_selected(scenario_id: String) -> void:
 		start_menu.close()
 	if not _resuming and Save:
 		Save.clear_shift_state()
+	_start_phase_override = -1
+	if scenario_id == HOLLYWOOD_NIGHT_ID:
+		_start_phase_override = Rules.Phase.LATE
+		scenario_id = "hollywood_building"
 	active_scenario_id = scenario_id
 	_venue_index = maxi(0, VENUE_ORDER.find(scenario_id))
 	selected_scenario = _build_scenario(scenario_id)
@@ -393,11 +421,21 @@ func _on_settings_applied(settings: Dictionary) -> void:
 			Save.save_campaign(campaign.summary())
 	if coordinator:
 		coordinator.scheduler.spawn_rate_multiplier = float(_difficulty()["spawn"])
-	if start_menu and start_menu.visible:
+	# A settings panel opened from the venue menu is restored by
-		start_menu.open(campaign.summary() if campaign else {})
+	# `_on_settings_closed`; an in-shift panel returns to pause. Close it before
-	elif _shift_running:
+	# opening pause so the new top-modal pass cannot cancel it twice.
+	if _shift_running:
+		if settings_panel:
+			settings_panel.close()
 		_open_pause()
 
+func _on_settings_closed() -> void:
+	if _settings_from_start_menu:
+		_settings_from_start_menu = false
+		_show_start_menu()
+	else:
+		_refresh_freeze()
+
 ## Clear the tutorial completion/skip flags and restart the Hollywood shift so
 ## the next player can replay the first-shift lesson from Settings.
 func _on_reset_campaign() -> void:
@@ -405,6 +443,7 @@ func _on_reset_campaign() -> void:
 		Save.reset_campaign()
 	if campaign:
 		campaign.setup({})
+	_settings_from_start_menu = false
 	if settings_panel:
 		settings_panel.close()
 	if pause_overlay:
@@ -416,6 +455,7 @@ func _on_replay_tutorial() -> void:
 	player_settings["tutorial_skipped"] = false
 	if Save:
 		Save.save_settings(player_settings)
+	_settings_from_start_menu = false
 	if settings_panel:
 		settings_panel.close()
 	if pause_overlay:
@@ -427,6 +467,7 @@ func _open_help() -> void:
 		help_overlay.open(selected_scenario.policy_summary if selected_scenario else "")
 
 func _open_settings() -> void:
+	_settings_from_start_menu = start_menu != null and start_menu.visible
 	if start_menu:
 		start_menu.close()
 	if pause_overlay:
@@ -499,6 +540,7 @@ func _build_ui() -> void:
 	settings_panel.applied.connect(_on_settings_applied)
 	settings_panel.replay_tutorial_requested.connect(_on_replay_tutorial)
 	settings_panel.reset_campaign_requested.connect(_on_reset_campaign)
+	settings_panel.closed.connect(_on_settings_closed)
 
 	event_timeline = EventTimeline.new()
 	add_child(event_timeline)
@@ -715,6 +757,15 @@ func _ensure_lighting() -> void:
 	_sun.directional_shadow_mode = DirectionalLight3D.SHADOW_PARALLEL_4_SPLITS
 	_sun.directional_shadow_max_distance = 60.0
 	scene_root.add_child(_sun)
+	# A soft sky-bounce fill from the north keeps the shaded Ovation frontage
+	# readable without adding a second set of hard shadows.
+	_fill = DirectionalLight3D.new()
+	_fill.name = "SkyFill"
+	_fill.rotation_degrees = Vector3(-24, 180, 0)
+	_fill.light_energy = 0.2
+	_fill.light_color = Color(0.62, 0.72, 0.9)
+	_fill.shadow_enabled = false
+	scene_root.add_child(_fill)
 	_env_node = WorldEnvironment.new()
 	var env := Environment.new()
 	env.background_mode = Environment.BG_SKY
@@ -741,6 +792,8 @@ func _apply_phase_lighting() -> void:
 		# entrance view reads as shade when the sun is off the facade.
 		_sun.rotation_degrees = Vector3(float(cfg.get("sun_angle", -50.0)),
 			float(cfg.get("sun_yaw", -30.0)), 0)
+	if _fill:
+		_fill.light_energy = float(cfg.get("fill_energy", 0.16))
 	if _sky:
 		_sky.sky_top_color = cfg.get("sky_top", Color.BLUE)
 		_sky.sky_horizon_color = cfg.get("sky_horizon", Color.WHITE)
@@ -1338,6 +1391,18 @@ func _close_top_modal() -> bool:
 	if event_timeline and event_timeline.visible:
 		event_timeline.close()
 		return true
+	if help_overlay and help_overlay.visible:
+		help_overlay.close_panel()
+		return true
+	if settings_panel and settings_panel.visible:
+		settings_panel._on_cancel()
+		return true
+	if pause_overlay and pause_overlay.visible:
+		_close_pause()
+		return true
+	if shift_review_panel and shift_review_panel.visible:
+		_on_review_restart()
+		return true
 	return false
 
 func _open_radial() -> void:
@@ -1911,11 +1976,15 @@ func decide_access(allowed: bool) -> void:
 func _door_context_line() -> String:
 	if selected_scenario == null:
 		return ""
+	match str(selected_scenario.id):
+		"joke_shop":
 			if selected_scenario.access_policy.require_id:
 				return selected_scenario.door_staff_line("id_check", _door_rng)
-	if selected_scenario.access_policy.requires(Rules.AccessKind.TICKET):
 			return selected_scenario.door_staff_line("ticket_check", _door_rng)
-	return ""
+		"tv_studio":
+			return selected_scenario.door_staff_line("ticket_check", _door_rng)
+		_:
+			return selected_scenario.door_staff_line("wristband_check", _door_rng)
 
 func _artifacts_for(controller: Object) -> Array:
 	var profile: NpcProfile = controller.profile as NpcProfile
@@ -1981,7 +2050,8 @@ func _physics_process(delta: float) -> void:
 			hud.log("Objective: %s — keep the entrance clear and verify access." % str(
 				Rules.PHASE_NAMES.get(coordinator.current_phase, "Early")))
 	hud.set_shift_state(coordinator, selected_scenario)
-	var preview := coordinator.scheduler.preview(coordinator.elapsed_s, coordinator.current_phase)
+	var preview := coordinator.scheduler.preview(coordinator.schedule_time_s(),
+		coordinator.current_phase)
 	hud.refresh_debug(coordinator, npcs, preview)
 	_perception_pass()
 

src/game/guard_controller.gd

@@ -96,6 +96,11 @@ static func _ensure_gamepad_bindings() -> void:
 	var buttons := {
 		"action_menu": JOY_BUTTON_A,
 		"cancel": JOY_BUTTON_B,
+		# UI focus navigation uses Godot's built-in UI actions. Bind the pad
+		# accept/cancel buttons too, so every modal works without a mouse or
+		# keyboard. D-pad and stick navigation are already in ui_up/down/left/right.
+		"ui_accept": JOY_BUTTON_A,
+		"ui_cancel": JOY_BUTTON_B,
 		"inspect": JOY_BUTTON_X,
 		"radio_assist": JOY_BUTTON_Y,
 		"walk_slow": JOY_BUTTON_LEFT_SHOULDER,

src/game/materials.gd

@@ -18,10 +18,12 @@ const T_CONCRETE := preload(PICK_DIR + "sidewalk_pavers.png")
 const T_ASPHALT := preload(PICK_DIR + "asphalt.png")
 const T_ASPHALT_WET := preload(PICK_DIR + "asphalt_wet.png")
 const T_AWNING := preload(PICK_DIR + "awning_canvas.png")
+const T_LIMESTONE := preload(PICK_DIR + "stone_steps.png")
 const T_BRICK_NORMAL := preload(PICK_DIR + "brick_facade_normal.png")
 const T_CONCRETE_NORMAL := preload(PICK_DIR + "sidewalk_pavers_normal.png")
 const T_ASPHALT_NORMAL := preload(PICK_DIR + "asphalt_normal.png")
 const T_ASPHALT_WET_NORMAL := preload(PICK_DIR + "asphalt_wet_normal.png")
+const T_LIMESTONE_NORMAL := preload(PICK_DIR + "stone_steps_normal.png")
 
 ## Roughness / metallic pairs per surface role. Exposed so tests and tooling can
 ## assert the profiles instead of hard-coding numbers twice.
@@ -96,6 +98,9 @@ static func brick(tint: Color = Color(1, 1, 1), uv_scale: Vector2 = Vector2(10,
 static func concrete(tint: Color = Color(1, 1, 1), uv_scale: Vector2 = Vector2(9, 2.4)) -> StandardMaterial3D:
 	return textured(T_CONCRETE, tint, uv_scale, "concrete", T_CONCRETE_NORMAL)
 
+static func limestone(tint: Color = Color(1, 1, 1), uv_scale: Vector2 = Vector2(6, 3)) -> StandardMaterial3D:
+	return textured(T_LIMESTONE, tint, uv_scale, "stone", T_LIMESTONE_NORMAL)
+
 static func asphalt(tint: Color = Color(1, 1, 1), uv_scale: Vector2 = Vector2(30, 7),
 		wet: bool = false) -> StandardMaterial3D:
 	var texture: Texture2D = T_ASPHALT_WET if wet else T_ASPHALT

src/game/npc_avatar.gd

@@ -114,6 +114,7 @@ var _focus_circle: MeshInstance3D = null
 var _name_tag: Label3D = null
 ## Theater props and limbs for the idle poses (ADR-0010 rig).
 var _photo_prop: MeshInstance3D = null
+var _photo_flash: MeshInstance3D = null
 var _sign_prop: MeshInstance3D = null
 var _legs: Array[Node3D] = []
 var _arms: Array[Node3D] = []
@@ -133,6 +134,10 @@ var _height_scale := 1.0
 var loaded_model := false
 var fallback_avatar := true
 var character_model := ""
+## QA/review override for the visual model. Empty keeps role/seed selection;
+## `capture_npc_review.gd` uses it to stage the one library model (guard) that
+## has no spawned NPC role.
+var character_override := ""
 ## Tests can force the offline rig; the game always tries the committed model.
 var use_skinned_model := true
 var _skeleton: Skeleton3D = null
@@ -167,6 +172,18 @@ const ACCESSORIES := {
 
 const BLENDER_NPC_DIR := "res://assets/models/blender/npc/"
 const BLENDER_GEAR_DIR := "res://assets/models/blender/npc_gear/"
+## Final-context adjustments applied inside the attach node. The lanyard was
+## authored under the jacket's front surface; a small forward offset keeps the
+## ribbon and badge readable without changing the attach-point contract.
+const GEAR_OFFSETS := {
+	"lanyard": Vector3(0, 0, 0.04),
+	"firefighter_helmet": Vector3(0, 0.03, 0),
+}
+## Hand gear is authored around the wrist proxy. The palm sits ~4 cm in front
+## of that origin, so without this offset the first phone/flashlight versions
+## were partly buried inside the hand. Keep the grip axis and move the whole
+## item forward into the open palm.
+const HAND_ITEM_FORWARD := Vector3(0, 0, 0.04)
 const GEAR_ATTACH := {
 	"cap": "head", "beanie": "head", "hood": "head", "sunglasses": "head",
 	"firefighter_helmet": "head",
@@ -335,7 +352,8 @@ static func reaction_label(mode: String, escalation: int) -> String:
 ## Instantiate the Blender-authored skinned base mesh. Returns false when the
 ## GLB is missing/not imported, so setup falls back to the procedural rig.
 func _build_skinned_body(npc_type: int) -> bool:
-	character_model = character_model_for(npc_type, _visual_seed)
+	character_model = character_override if character_override != "" \
+		else character_model_for(npc_type, _visual_seed)
 	var path := BLENDER_NPC_DIR + character_model + ".glb"
 	if not ResourceLoader.exists(path):
 		character_model = "npc_base"
@@ -731,6 +749,10 @@ func _attach_gear(gear_name: String) -> bool:
 		_:
 			node.free()
 			return false
+	if GEAR_OFFSETS.has(gear_name):
+		node.position += GEAR_OFFSETS[gear_name]
+	if str(GEAR_ATTACH[gear_name]) == "hand":
+		node.position += HAND_ITEM_FORWARD
 	_detail_nodes.append(node)
 	var ao := Materials.load_ao(BLENDER_GEAR_DIR + gear_name + "_ao.png")
 	for child in node.find_children("*", "MeshInstance3D", true, false):
@@ -877,8 +899,11 @@ func _add_props(npc_type: int) -> void:
 	match npc_type:
 		Rules.NpcType.INFLUENCER:
 			_photo_prop = _add_box_prop(_rig, Vector3(0.16, 0.1, 0.09), Vector3(0.3, chest_y, 0.22), Color(0.1, 0.1, 0.1))
+			_photo_prop.name = "PhotoProp"
+			_photo_prop.visible = false
 			_photo_prop_base_y = _photo_prop.position.y
-			_add_box_prop(_rig, Vector3(0.05, 0.05, 0.06), Vector3(0.34, chest_y + 0.06, 0.30), Color(0.4, 0.7, 1.0))
+			_photo_flash = _add_box_prop(_rig, Vector3(0.05, 0.05, 0.06), Vector3(0.34, chest_y + 0.06, 0.30), Color(0.4, 0.7, 1.0))
+			_photo_flash.visible = false
 		Rules.NpcType.DELIVERY:
 			_add_box_prop(_rig, Vector3(0.34, 0.26, 0.28), Vector3(0.0, 1.02, 0.3), Color(0.55, 0.4, 0.25))
 		Rules.NpcType.PERFORMER:
@@ -903,6 +928,8 @@ func _add_props(npc_type: int) -> void:
 			_sign_prop_base_y = _sign_prop.position.y
 		Rules.NpcType.TOURIST:
 			_photo_prop = _add_box_prop(_rig, Vector3(0.3, 0.36, 0.14), Vector3(-0.34, 1.15, -0.18), Color(0.25, 0.3, 0.45))
+			_photo_prop.name = "PhotoProp"
+			_photo_prop.visible = false
 			_photo_prop_base_y = _photo_prop.position.y
 		Rules.NpcType.CONFUSED_VISITOR:
 			_add_box_prop(_rig, Vector3(0.3, 0.05, 0.34), Vector3(0, 0.92, 0.06), Color(0.9, 0.88, 0.8))
@@ -1028,6 +1055,12 @@ static func prop_lift_for_pose(pose: String, phase: float) -> float:
 		return 0.0
 	return maxf(0.0, sin(phase * 1.7)) * 0.16
 
+## The tourist's camera bag and the influencer's chest camera are only part of
+## the silhouette while the character is actually taking photos. Keeping them
+## hidden at other times prevents the tourist from reading as two backpacks.
+static func photo_prop_visible_for_pose(pose: String) -> bool:
+	return pose == "photo" or pose == "film"
+
 ## Opposite arm/leg swing for the walk cycle. `side` is 0 or 1; pure so the gait
 ## can be checked without a scene tree.
 static func limb_swing(phase: float, side: int, amplitude: float) -> float:
@@ -1046,6 +1079,10 @@ func _animate(delta: float) -> void:
 	var pose := theater_pose()
 	var escalation: int = npc.highest_escalation_received if npc != null else 0
 	var crouch := crouch_for_pose(pose)
+	if _photo_prop:
+		_photo_prop.visible = photo_prop_visible_for_pose(pose)
+	if _photo_flash:
+		_photo_flash.visible = photo_prop_visible_for_pose(pose)
 	if speed > 0.3:
 		_idle_t = 0.0
 		_bob_phase += delta * (6.0 + speed * 1.7)