# MEMORY

Session memory for durable decisions, state, and gotchas. Keep concise, remove obsolete entries.

## Decisions

- **TV Studio shares the Hollywood location (2026-11-03, owner clarification):** the Late Night TV
  Studio venue is **the same** El Capitan Entertainment Centre block at 6840 Hollywood Blvd (the
  building houses *Jimmy Kimmel Live!*), restaged for a late-night arrival with a bulb canopy, black
  sedan and barrier line. `VENUE_SPECS["tv_studio"]` is a 30.0 m variant of the 29.6 m Hollywood
  facade. One reference board (`docs/screens/refs/hollywood/`) serves both venues; do not create a
  separate TV Studio photo board or treat it as a distinct real site.
- **Hollywood reference board (2026-11-03):** five Wikimedia photos live in
  `docs/screens/refs/hollywood/` with `SIDECAR.md` (licences: CC BY 2.0 x2, CC BY 3.0, PD x2),
  cropped/re-encoded to <=1600 px JPEG q85 with EXIF stripped, foreground crowd cropped out of the
  facade shot. The board is linked from `docs/hollywood-boulevard-map.md` and the CC BY files are
  credited in `CREDITS.md`. Gotchas: the Commons API needs a descriptive User-Agent and rate-limits
  rapid thumbnail downloads (HTTP 429) - fetch all metadata in one `titles=A|B|C` query and space
  the downloads. `check_docs` requires each image to be linked from its folder `README.md`, so each
  venue folder needs both `README.md` (board) and `SIDECAR.md` (provenance).
- **Joke Shop reference board (2026-11-03):** three photos in `docs/screens/refs/joke-shop/` (PD x2
  by Gary Minnaert 2006, CC BY 2.0 by Tony Mariotti 2020) covering the hillside/canopy block, the
  frontage with palms and the signature-band/curtain detail. `The Comedy Store.jpg` (CC BY-SA 3.0)
  from the old link list was deliberately skipped: the PD frames cover the same evidence and no
  share-alike review was needed. The CC BY file requests a dofollow link, recorded in its sidecar
  and CREDITS.
- **Imagery evidence model (2026-11-03):** `TODO.md` now separates three image sources that must
  not be mixed: licensed real-location photos (evidence of what a place looks like), generated
  concept boards (art-direction proposals with model/prompt/spend provenance), and build captures
  (proof the build matches). Per-venue boards go under `docs/screens/refs/<venue|block>/` with a
  `SIDECAR.md` per folder (photo table: file, subject, view, URL, author, licence, date, purpose,
  shipped; plus redactions, derived-decision log and a table referencing the generated boards used
  in the three-up). Generated frames stay in `docs/screens/concepts/`, never in `refs/`, and stay
  out of `assets/` until picked, cropped, credited and audited. Every workstream now
  ends with a capture step that updates `README.md` plus the matching docs page, verified with
  `tools/check_screenshots.sh` and `python3 tools/check_docs.py`.
- **Collider coverage gate (2026-11-03):** `WorldBuilder` sets `library_prop` metadata on every
  node in `library_nodes`, and `NON_BLOCKING_LIBRARY` (`marquee`, `wall_lantern`, `handrail`,
  `double_door`) documents the mounted/decorative pieces that intentionally publish no
  walk-blocking body. `test_world.gd` verifies placed props have `Collision` + `Shape` +
  `Avoidance` in all three venues, and that library dressing has a body unless exempt. Both
  were mutation-checked (removing `_add_prop_collision` fails 3 tests; dropping `handrail` from
  the exemption list fails with the node name). Suite is 275/275. Add the metadata when adding a
  new library placement, or the coverage test will report it.
- **3D review gates (2026-11-03):** `tools/test_blender_assets.py` now gates texel density
  (all five character slots present, 40–400 px/m authored, ≥250 px/m effective fabric), and
  `tools/test_model_review.py` gates scorecard coverage (every `CHARACTERS`/`GEAR`/`PROPS` entry
  needs a row in `docs/3d-model-review.md`, characters need a verdict). Python tooling is 116
  tests. Collider-proxy coverage is still an open gate. Remember CI only runs the Godot suite;
  the Python tests are local (`cd tools && python3 -m unittest discover -p 'test_*.py'`).
- **Pose capture is blocked (2026-11-03):** `src/test/capture_npc_pose.gd` stages idle/walk/sit
  poses for the pose/weight review, but the saved frames show the rest pose while the same run
  logs `rig_y=-0.339`, `leg0=-1.357` and a rotated `HipL` bone quaternion at capture time.
  Verified meanwhile: one skinned mesh bound to one `Skeleton3D`; hiding it removes the body;
  direct `set_bone_pose_rotation` on HipL/KneeL/Spine/ShoulderL/ElbowL/Head changes rendered
  pixels; a bone *position* offset moves the head; a standalone probe running the same
  `_animate()` sequence renders the crouch. A staged in-game `film` frame also showed the arms
  Standalone SceneTree probes (avatar under `root`, under a `Node3D` stage, created
  mid-`_process`) all render the seated crouch, and a `SubViewport` + `RenderingServer.force_draw()`
  probe does too (window probes diff ~2,200-2,360; offscreen 602 at +2/+6/+12 frames, including a
  re-created avatar). So the rig, the animation math and the offscreen path are sound; only
  `capture_npc_pose.gd` still saves rest frames, which makes its phase/camera/force-draw ordering
  the defect. A headless test locks the proxy→bone contract
  (`test_pose_reaches_the_skeleton_bones`, suite 273). Rebuild the harness from the verified
  recipe in `docs/3d-model-review.md` instead of iterating on the current phase machine.
- **3D review baseline (2026-11-03):** `docs/3d-model-review.md` records the first skill-guided
  measurements: 46/46 assets clean, library 59,012 tris, characters 4,482–5,474 tris (68–69% of
  the 8,000 caps), `npc_base` only 1,204/2,488, 24-NPC 6.94 ms, and authored texel density
  64–122 px/m (fabric effective 287–440 after the 4× repeat). That is below the skill's 128–256
  background tier but the slot maps are neutral and tinted at runtime, so it is a recorded decision
  point, not a defect. Added `blender_assets.py texels` (stdlib, per-slot px/m from GLB UV/world
  area, fabric reported twice) and `inspect --json --out` (the glTF importer's INFO log is captured
  in `stats.import_log`; Blender's startup banner still pollutes stdout). Baseline/review captures
  run fine under `xvfb-run` into `tmp/`.
- **3D model re-evaluation first (2026-11-03):** `TODO.md` is re-planned around a new unversioned
  `3D model re-evaluation` track, ahead of character and local-map work, because the crowd-variant
  roster would otherwise multiply whatever the existing models get wrong. It scores all 8
  characters, 18 gear, 20+6 props and the three venues in `docs/3d-model-review.md`, fixes ranked
  P0/P1 only, and must not change the `npc_base` contract, renderer or 0.10.0 candidate. The MIT
  Blender skill pack is now routed through `AGENTS.md` §Local Blender skills; skill advice loses
  to the project contract, and there is no Blender MCP here (headless flatpak scripts instead).
  MEMORY is ~960 lines with dated historical entries; trimming it is a tracked maintenance task.
- **GLB intake inspection (`blender_assets.py inspect`, 2026-11-03):** runs inside Blender, clears
  parents and applies object transforms, then reports tris/budget, raw and seam-split verts,
  Godot-space bounds (height/feet for characters), bones, materials, UVs, skinning and
  animations as `issues` (contract failures, exit 1) or `warnings`. `--json`/`--category` exist
  for intake scripts. Gotchas: the glTF importer creates an `Icosphere` mesh used as
  `pose_bone.custom_shape`, which must be excluded or it dominates bounds; a parented import
  needs `parent_clear(CLEAR_KEEP_TRANSFORM)` before `transform_apply`; Blender is Z-up so bounds
  and bone rests are converted to `(x, z, -y)`. On project assets its counts match `audit`
  exactly, but `audit` stays the stdlib/CI release gate and `inspect` never adapts a file.

- **Blender Skills Pack installed locally (2026-11-03):** the MIT `blender-skills` pack
  (v1.3.0, 94 skills + a shared `references/` folder) is installed at
  `.agents/skills/blender-skills/` for Blender asset work. `.agents/` is gitignored and
  `.agents/.gdignore` keeps Godot's scanner out, so it never ships, exports or affects tests.
  Skills link shared docs as `../references/<file>.md`, so keep the pack flat when updating:
  `cp -a <pack>/.claude/skills/. .agents/skills/blender-skills/`. Pi gates project
  `.agents/skills` behind project trust, so the trust prompt must be accepted before the
  skills load.

- **Priority order (2026-11-03):** `TODO.md` now leads with the unversioned **Character
  development** and **Local map development** tracks, then the versioned 0.10.0 release
  candidate and later releases. Do not attach a placeholder version to an unversioned track;
  assign one only when its scope enters a release. Character development is generator-first
  (ADR-0015); local map development evaluates OSM/3D data, licensed reference imagery,
  AI-assisted composition and development-only Gaussian splatting.
- **Commit/build discipline (2026-11-03):** commit each coherent verified change as it lands, not
  only at milestone end, and push shareable commits. Every major, minor and patch version requires
  a `CHANGELOG.md` entry, a local `tools/build_releases.sh` build and artifact/checksum
  verification before tagging. CI tag builds are the second gate, not a substitute.
- **Gaussian splatting / photo-derived maps (unversioned local track):** expanded in
  `TODO.md` "Gaussian splatting evaluation". Accepted photo channels are team captures,
  permissioned user/volunteer photos and clearly licensed downloads; every set needs a
  provenance/consent sidecar. Sparse web photos are reference/training supplements, not a splat
  source. Five enhancement paths are ranked (reference/QA, texture bake, mesh proxy, distant
  backdrop, single-facade user-photo supplement). Splats stay offline/development-only until the
  ADR proves licence, privacy, Godot Compatibility/Web cost and mesh-based collision; no runtime
  splat dependency in 0.10.0.

- **NPC model variety decision (2026-11-03, ADR-0015):** CC0 is acceptable for shipped
  assets; CC-BY only with attribution in `CREDITS.md`; no service assets with redistribution
  restrictions. The **procedural generator is the primary path**. Four crowd-variety specs were
  prototyped with the existing builder (`npc_crowd_a` bun/slim/sunglasses, `npc_crowd_b`
  bald/broad/beard/shoulder bag, `npc_crowd_c` coat/umbrella, `npc_crowd_d` hood/cup); all audit
  clean at 4,550–5,258 tris / 4,356–5,086 verts. Prototype assets stay in
  `tmp/npc-research/generator_proto/`; do not add them to the current release candidate.
  **Quaternius is a reference, not a shipped base:** welding brings `Casual_Hoodie` from 12,518
  to 3,199 verts and a 0.75 decimate to 2,423 verts / 4,654 tris, and its Idle/Walk clips read
  well, but the T-pose 62-bone realistic rig/proportions do not match the arm-down 13-bone
  contract. A contract rebuild is a no-go without a body proportion warp; a second
  rig/animation path needs its own ADR. **MakeHuman is deferred** to a separate local pipeline:
  the CC0 base is 19,158 verts / 36,972 tris and decimates to 3,780 / 6,468 at 0.35, but needs
  retopology, a custom rig and project clothing. Research previews are committed under
  `docs/blender_previews/sheet_npc_{sources_research,crowd_prototypes}.jpg`; the CC-BY entries
  (CesiumMan/RiggedFigure, © Cesium) are attributed in `CREDITS.md` and are development-only.

- **0.10.0 balance protocol:** `docs/balance-acceptance.md` defines targets and
  denominator/cohort rules for the 36 venue/difficulty/phase cells, seeds 1–100,
  access/emergency error rates and matched calm vs emergency-first comparisons.
  These are acceptance criteria, not measured results; sweeps/playtests remain open.
  Inspection found `_read_npc_truth()` is type-derived, not behavior-derived;
  the pending emergency fairness review must cover this oracle mismatch rather
  than treating internal truth as independent evidence.

- 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.
- Editable Blender sources under `assets/models/blender_src/` are gitignored and untracked
  (46 `.blend` files removed from the index on 2026-11-01); the `.gdignore` marker stays tracked.
- `screen_designs.py judge` default `google/gemini-2.5-flash-lite` worked on 2026-11-01
  (7 match / 4 review / 0 diff); `--model` remains available.
- `capture_realism.gd` parses `--portrait-type=N`; it was documented but ignored before the gear
  pass. Portrait captures need the requested NPC type to have spawned, otherwise the stage can
  finish with an empty frame; use the Blender character previews (`render --only npc_coat`) for
  deterministic gear checks.
- Headgear: the firefighter helmet was lifted 2 cm after the brow/face pass; cap and hood were
  visually checked on `npc_vest`/`npc_hoodie`. The beanie is unused and shares the cap shell.
- Gear fit is measured with `python3 tools/blender_assets.py fit` (stdlib, reads the GLBs):
  head width uses skin vertices weighted to Head in y 1.55–1.81; clothing radius is the cloth
  skirt in y 0.30–0.52 with a pants hip fallback. The command reports per-character gear boxes,
  head-band status and x/radial skirt clearance; `test_blender_assets` covers its shape.
- Post-realism work is split by theme, not by date: finished items are archived in `DONE.md`, and
  `TODO.md` carries the 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
  `assets/models/generated/npc_base.glb`; `NpcAvatar` keeps the procedural `_build_body()`
  fallback. Preserve `Rig/Head`, the limb node names, and the seed-deterministic
  `outfit_for`/`layer_for`/`hand_item_for` helpers. Blender = flatpak 5.2.0 LTS, sandbox cwd
  `/app/blender` → absolute paths for `--python`. CI stays offline (committed assets).

- Engine: Godot 4.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 GDScript ("Expected func or var after static") — do not use them.
- GDScript lambdas capture local variables **by value**; mutating a captured local inside a lambda does not affect the outer variable. Use member functions for accumulators in tests.
- Shift length is the scenario's `shift_duration_s` (900 s in all three venues). Tests and the screenshot tool override elapsed time; they do not change the default.
- RNG: NPC reactions and event scheduling are seedable for deterministic tests.

- **Mouse look (v0.7.3):** guard look is handled in `GuardController._input()` (before GUI), not `_unhandled_input`; focus/click-back recaptures the cursor and the HUD is made mouse-transparent recursively. Regression tests cover yaw/pitch and HUD filters.
- **v0.9.0 production pass:** CI/release, local dev and project now use Godot 4.7.2; the version-adaptive light falloff remains for older editors. Audio settings are `master_volume`/`sfx_volume`/`ambience_volume`; accessibility has `reduce_motion` and `captions_enabled` (HUD log is the caption surface). Budget smoke is 24 NPCs (6.94 ms headless). Coat/dress stride is scaled to 0.76 to reduce hem clipping. Localization remains English-table based; pseudo-locale/VO/music are post-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.
- **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.94 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 texture resolution (0.9.5, 2026-11-02):** `tools/npc_pipeline.py` now generates 256²
  albedo/normal/ORM maps instead of 128² (AI shirt/trousers are resized to 256). The base and all
  eight library GLBs plus AO maps were rebuilt; texture files total ~0.5 MB, eight GLBs ~5.75 MB,
  and the 24-NPC smoke is 6.94 ms.
- **0.9.5 texture/UI audit (2026-11-02):** all 21 screen-art textures are
  1280×720 and referenced by their screens; access cards are 256×128 and HUD
  icons 64×64, with no oversized or unused runtime texture. The 24-NPC smoke now
  reports **168 meshes / 131,616 triangles / 6.94 ms** (50 ms budget). Compressed
  payloads are picks **24.55 MB**, UI art **22.67 MB**, NPC maps **0.48 MB**.
  Legacy root textures remain only for `generate_textures.py` and the asset test.
- **Environment surface audit (0.9.5, 2026-11-02):** `capture_realism.gd` gained
  `surfaces` (Hollywood pavers/asphalt/limestone/facade) and `surfaces_joke`
  (neighbour awning, canopy, pavers) stages with the HUD hidden. The Walk of Fame
  band now uses `T_CONCRETE` as dark terrazzo; the neighbour awning uses a neutral
  tint (`0.62`) and 4× UV so the red/cream stripes survive; the skyline shader
  fades its lower 42 m toward a per-phase haze colour. Brick/asphalt picks needed
  no replacement. No seams or broken UV scales found.
- **NPC fabric UV/AO (0.9.5, 2026-11-02):** cloth/pants use
  `Materials.NPC_FABRIC_UV_SCALE = Vector3(4,4,1)`, and `NpcAvatar` skips the baked per-character
  AO on those two slots. The 256² AO was magnifying into large blotches; the fabric now reads as a
  fine weave. Skin/hair/gear keep baked AO. Test `test_fabric_uv_scale_avoids_the_baked_ao_pattern`
  guards this. Current suite is 272/272.
- **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, **0.9.4** after the NPC pass, now **0.9.5** after the texture
  and material pass, and **0.9.6** as the integration checkpoint. Next work is
  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.6` 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, 0.9.4 NPC visual optimization, 0.9.5 texture/material pass and
  0.9.6 integration are complete and in `DONE.md`. 0.10.0 release-candidate work
  is next. The source version is 0.10.0-rc.1.
- **0.10.0-rc.1 build (2026-11-03):** clean worktree `a9658ec` produced five
  artifacts (Linux 161.5 MB, Windows 197.2 MB, macOS 148.0 MB, Web 97.8 MB, HQ
  241.6 MB); Web/HQ include player docs, SHA-256 manifests are local, Linux/HQ
  launch headless and Web files serve HTTP 200. Not published: external playtest,
  AI/legal approval, macOS signing and the Windows/macOS matrix are still open.
- **Release/legal blockers (0.10.0 work, 2026-11-03):** macOS remains unsigned
  (quarantine instructions only); AI image provider terms/commercial rights and
  external storefront/rating approval are not cleared; external playtests and the
  full hardware matrix are pending. `CREDITS.md`, `PRIVACY.md`, `docs/accessibility.md`
  and `docs/known-limitations.md` record these explicitly rather than claiming
  approval. Do not tag 0.10.0 as final until these are accepted or cleared.
- **Save migration (0.10.0 work, 2026-11-03):** fixtures in `src/test/fixtures/saves/`
  cover 0.8 settings/campaign/history and a 0.9.0 checkpoint. `_load_json` uses
  `JSON.new().parse()` so corrupt player files fall back silently instead of
  logging a parse error; atomic writes leave the old file intact when the temp
  path cannot be written. The migration suite is 9 tests; total 272.
- **0.9.6 integration (2026-11-03):** no gameplay/content changes. A clean
  detached worktree at `f5b8ef2` rebuilt Linux/Windows/macOS/Web/HQ without the
  dirty tree's ignored `tmp/`/`build/` payload; the in-repo build was 1.6–3.1 GB
  per artifact because those folders were packed, so always build release
  artifacts from a clean checkout/worktree. Verification: 263/263 tests,
  101/101 Python, 14 smokes, 24-NPC 6.90 ms / 168 meshes / 131,616 triangles,
  gallery 21/0, screen judge 21/21, realism judge overall 2.1 / gap 0.291.
- **Release v0.9.6 (2026-11-03):** commit `4bb2896` tagged `v0.9.6`; Gitea
  Actions run 1296 passed checks and the full build and published seven assets
  (Linux, Windows, macOS, NSIS setup, AppImage, Web, Desktop HQ). Release page:
  `https://git.allucanget.biz/zwitschi/security-game/releases/tag/v0.9.6`. This is
  the integration checkpoint before 0.10.0; do not reuse the tag.
- **Release v0.9.5 (2026-11-02):** commit `4bc6390` tagged `v0.9.5`; Gitea Actions run
  922 passed checks and the full build and published seven assets (Linux, Windows,
  macOS, NSIS setup, AppImage, Web, Desktop HQ). Release page:
  `https://git.allucanget.biz/zwitschi/security-game/releases/tag/v0.9.5`. Do not
  reuse the tag; future fixes need a new patch tag.
- **Release v0.9.4 (2026-11-02):** commit `a57b86c` tagged `v0.9.4`; Gitea Actions
  run 916 passed checks and the full build and published seven assets (Linux,
  Windows, macOS, NSIS setup, AppImage, Web, Desktop HQ). Release page:
  `https://git.allucanget.biz/zwitschi/security-game/releases/tag/v0.9.4`. Do not
  reuse the tag; future fixes need a new patch tag.
- **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 0.9.5 texture 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
  volumetric fog/SDFGI and `light_volumetric_fog_energy`, and
  `Materials.modern_light_falloff()` compensates for Godot 4.7's much harsher
  local-light falloff. LATE volumetric density is 0.020 with flashlight
  volumetric energy 3.0. `tools/build_releases.sh` packages the Linux/Windows
  binaries + override into `gig-line-desktop-hq-<version>.zip`;
  `publish_release.sh` uploads it when present. A/B report:
  `docs/screens/realism/2026-11-01-forward-plus/` (entrance gap 1.568→1.187).
- **Godot toolchain (updated 2026-11-01):** local `~/.local/bin/godot`, CI and
  `project.godot` now use Godot 4.7.2; 4.3 remains only as a local backup binary.
  Export templates for 4.7.2 are installed under
  `~/.local/share/godot/export_templates/4.7.2.stable`. Godot 4.7 writes
  `*.gd.uid` files; they are kept out of this clone's status via
  `.git/info/exclude`. CI downloads the binary/templates directly; Gitea
  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
  required, otherwise Godot's editor tries to import the committed `.blend` and hangs during
  `--import` (also add `.gdignore` to local build/squashfs folders when scanning is slow).
- **Skinned NPC integration (v0.6.0):** `NpcAvatar._build_skinned_body()` loads
  `npc_base.glb` and keeps `_build_body()` as fallback (`use_skinned_model=false` in tests).
  Bone pose rotation is the **absolute local orientation**, not an offset from rest: compose with
  `get_bone_rest(i).basis` or the whole body snaps to a broken pose. Proxies named Hip/Knee/
  Shoulder/Elbow/Hand + Head marker preserve the old animation math; `Rig/Head` is the marker.
  Five material slots are tinted via `SurfaceMaterials.npc_slot()`; keep `_rig.scale` uniform on
  the skinned path. Budget: 16 avatars = **144 meshes**, ~6.9 ms headless.
- **NPC facing (fixed after v0.5.0):** the avatar's visual front is **+Z** (procedural eyes
  and the Blender model's face). Godot `look_at()` aims **-Z**, which made every NPC walk
  backwards. Use `NpcAvatar.yaw_towards(dir)` and set `rotation.y`; do not call `look_at()` on
  avatars. Head-turn offsets use `+basis.z` for the same reason. Covered by
  `test_yaw_faces_the_movement_direction`.

- **Image root (ADR-0014, 2026-11-01):** `assets/images/` is the runtime root for composed
  interface/scene art (`ui/`, `scenes/`); tiled PBR textures stay under `assets/textures/`;
  `docs/screens/designs/` and `docs/screens/concepts/` stay reference-only; QA captures stay in
  `docs/screenshots/`. When a mockup becomes runtime art, copy/process it into `assets/images/`
  with a new name (no overwrites) and keep a fallback in code.
  **Mockup copies:** 21 design references live in `assets/images/ui/`; `docs/screens/designs/`
  remains the reference-only copy. `tools/screen_designs.py` reads/writes the runtime root.

## Handoff — historical snapshot (2026-11-01; superseded by Current State / Plan vs code)

- **Status (2026-11-01, after the venue-geometry pass):** v0.7.0 was released at that point. Post-v0.6.0 the
  realism pass, the visual-alignment pass and the NPC face/hand pass all landed. Headless
  **272/272**, Python tooling **108/108**, `tools/check_screenshots.sh` **21 good / 0 bad**,
  `screen_designs.py compare` 11 good / 0 bad, `scene_concepts.py audit` all GOOD,
  `blender_assets.py audit` exit 0, `smoke_npc_budget` OK (16 avatars, 6.94 ms of 50 ms).
  `PLAN.md` is compact; README/architecture track the current controls, asset pipeline, CI and
  release artifacts. The historical notes below remain useful for implementation gotchas; for
  current tasks use `TODO.md`.

- **Phase 2 — AI texturing (this agent, DONE 2026-11-01).** Phase 1 assets were
  already in the tree (untracked) and are preserved. Generated six seamless AI
  clothing albedos into `assets/textures/npc/ai/{shirt,trousers,jacket,vest,
  coat,dress}.png` (512×512, `--role tile`, gpt-5-image-mini; audit 6 good).
  **Gotcha:** `asset_pipeline.py generate` defaults to `GEN_SIZE=2048`, which
  gpt-5-image-mini rejects (HTTP 400); pass `--request-size 1024` for 1:1 roles.
  `generate --role tile` already applies `make_seamless`, so a separate
  `seamless` pass is redundant. Added to `tools/npc_pipeline.py`: `prepare`
  (layers AI shirt→cloth, trousers→pants albedos at 256px) and `palette`
  (writes `assets/textures/npc/palette.json` via `model_pipeline.dominant_colors`).
  `write_slot_textures()` now skips the albedo for slots with an AI override
  (normal/ORM stay procedural). Blender `build` re-run: GLB audit ok, 1204 tris /
  2488 verts, AI albedo embedded for cloth+pants. Phase 2 completed and shipped with
  the v0.6.0 asset library.
  **Import concurrency:** a parallel agent is running
  `timeout 300 godot --headless --editor --quit --path .` and then checks
  `assets/models/generated/npc_base.glb.import` — treat that as the canonical
  import. My own `godot --headless --path . --import` hung with no output past
  the engine banner (two Godot instances contended on `.godot`); I killed the
  orphan (PID 2482934). Do not run a second import while that `--editor --quit`
  is active.
  Next: Phase 3 (`NpcAvatar._load_model` + slot tinting) consumes
  `palette.json` and the GLB; Phase 2's capture/judge item is blocked on that.

- **Git hygiene + tooling (2026-11-01):** dev asset folders are now gitignored
  and untracked: `assets/models/concepts/`, `assets/models/npc/` (Blender
  sources), `assets/textures/npc/ai/` (raw AI fabrics), and the raw
  `assets/textures/ai/*` outputs (only `assets/textures/ai/game_ready/` stays).
  Kept in the repo: `assets/textures/npc/*_{albedo,normal,orm}.png` +
  `palette.json`, `assets/models/generated/*` (props + npc_base.glb), and the
  authored `assets/textures/*` set. `tools/asset_pipeline.py generate` gained
  `--variants N` — generates N alternatives saved as `<stem>-1..N.png` (N=1
  keeps the unsuffixed path). Python tooling tests still pass (exit 0).

- **Screenshots + docs (2026-11-01):** regenerated the eleven README captures
  (`capture_screenshots.gd` + `capture_prop_gallery.gd`) — ten changed, the
  prop gallery is byte-identical (props unchanged). README gained an NPC
  character-model subsection, a "Confirmed game assets" section (linked
  `game_ready` textures, generated models, NPC maps), and refreshed
  dev-status / not-yet lines; `docs/architecture.md` Level 2 now lists
  `npc_pipeline.py` + `asset_pipeline.py` and the confirmed-asset locations.

- 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.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.
  Windowed control smoke: `godot --path . --script res://src/test/smoke_focus_radial.gd` → exit 0
  (now also covers wheel cycling and right-click clearing).
- `main` is in sync with origin. **v0.2.2** tags the session-shell + world-follow-up commit;
  CI builds the portable binaries, NSIS installer, and AppImage on the tag push.
- **v0.3.0 (2026-10-31, working tree):** rendering pass (`src/game/materials.gd`, phase-driven
  environment), generated `.glb` props (`tools/model_pipeline.py`, `assets/models/generated/`),
  aim-free selection with wheel cycling and Shift precision walk (ADR-0011/0012), and a **Web**
  export target. `export_presets.cfg` gains a `Web` preset with `variant/thread_support=false`
  (static hosting, no COOP/COEP); `tools/build_releases.sh` exports `build/web/` and zips it to
  `build/gig-line-web-<ver>.zip`, and `publish_release.sh` uploads it. Covered by
  `src/test/tests/test_web_export.gd`.
- **Prop atlas (v0.3.1):** `model_pipeline.atlas_for()` builds a per-prop power-of-two PNG with
  one 8×8 cell per palette role, plus a metallic/roughness atlas (G=roughness, B=metallic). The
  GLB merges all parts into one primitive with constant per-vertex UVs (cell centre) and a single
  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, updated 0.9.3):** `docs/screens/designs/` holds AI references for
  all 21 catalogue screens, and every entry now has a committed current-build capture.
  `capture_screenshots.gd` covers scenes 01–13, `capture_ui_states.gd` covers UI states 14–21,
  and `capture_prop_gallery.gd` covers the prop gallery. `generate` now calls `_load_env_file()`.
- **Staged captures (v0.3.3, updated 2026-11-02):** `capture_screenshots.gd` emits the scene
  gallery; states 7–10 switch to The Joke Shop at elapsed 620 s, retry the wand until it alerts,
  then jump to 760 s after staging for night lighting. LATE now has its own routine pool.
  Shot 12 closes any stale wand/inspection modal before the venue beauty shot (the wand fallback
  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
  flat plane, so avoidance (not a baked mesh) routes guests around props. Placements live in
  `PROP_PLACEMENTS` with `placement_problems()` validation; variants come from `variant_for(index)`.
  `smoke_props.gd` must be windowed because the guard reads captured-mouse input.
- **Realism pass (2026-11-01, completed + adopted):** `tools/scene_concepts.py`
  (`list`/`generate`/`process`/`promote`/`audit`/`realism`) never overwrites an image
  (`next_free_path` adds `-vN`; `process` skips existing unless `--new`; `promote` keeps an
  existing pick). Raw AI output: `assets/textures/ai/v2/raw/` (gitignored). Candidate pool:
  `assets/textures/ai/game_ready/v2/` (gitignored) and the **tracked runtime assets** are
  `.../v2/picks/{skyline_day,skyline_dusk,skyline_night,brick_facade,sidewalk_pavers,asphalt,
  asphalt_wet,awning_canvas}.png` (+ `_normal`). Concepts `docs/screens/concepts/` (committed,
  `.gdignore`, targets in its README). Runs `docs/screens/realism/<run>/` (PNG captures
  gitignored; `report.{json,md}` + `sheet.jpg` committed).
  `src/test/capture_realism.gd` runs five stages (day 0 s / evening 620 s / late 760 s /
  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.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
  repeat, near the 2:1 panorama aspect). Legacy `assets/textures/skyline.png` is no longer
  loaded but stays on disk for the `test_world` asset check.
  **Phase look:** day sun 0.62 / exposure 0.6 / ambient 0.22; evening sun 0.12 / exposure
  0.72 / dark violet sky; late exposure 0.95 / ambient 0.10 with the wet asphalt street and a
  bright skyline tint (1.5) so the night windows read. Stripes: `stripe_period()` (detrended
  autocorrelation) + `align_stripes()` (resample to whole periods) replace the edge crossfade
  for `awning_canvas`; `audit_striped_tile()` compares the wrap step with the harshest interior
  step.
  **Judge:** the default `google/gemini-2.5-flash-lite` mostly works but intermittently answers
  HTTP 400 "API key not valid" (one shot of ten on 2026-11-01); re-run or pass
  `--model google/gemini-2.5-flash` when it does. Scores are noisy (±1–2), so
  `realism --repeats 3` averages and `summarize()` reports a like-for-like mean over the shots
  every set captured. Final: overall 0.8→1.0, backdrop 0.6→1.6, metric gap 0.444→0.348.
  `screen_designs.py judge` gained one retry for the same transient 400.
  **Character portrait capture (2026-11-01):** `capture_realism.gd` has a `portrait` stage
  (`npc_portrait` -> concept `npc_portrait_day`) because crowd shots cannot judge avatars. It
  freezes one NPC, parks the rest of the crowd 140 m away (a passer-by otherwise blocks the
  frame), moves the subject to an open sidewalk patch, turns it into the camera and stands the
  guard on the sunlit side. Needed because the NPC FSM re-writes `rotation.y` every physics tick
  (so the yaw must be set after `set_physics_process(false)`), the venue's morning sun leaves a
  face in shadow from most angles, and `visible = false` does not keep the crowd out of frame.
  `--portrait-type=N` forces a role; hooded roles (trespasser/violent/crisis) are skipped.
  **Flashlight (2026-11-01, final):** a *tight* `SpotLight3D` on `Head`: `spot_range` 20,
  `spot_angle` 14, `light_energy` 4.2, `spot_attenuation` 0.9, forward `rotation_degrees = 0`,
  starts invisible. A fake additive light shaft was tried twice (cylinder with a UV ramp, then a
  vertical-fade `ShaderMaterial`) and **rejected both times**: on GL Compatibility a first-person
  camera inside the cone renders it as a filled disc and the far ring shows, so
  `Materials.light_beam()` and the beam mesh are gone. Regression guard:
  `test_flashlight_aims_a_tight_forward_spot` in `src/test/tests/test_door_and_flashlight.gd`
  (lamp on the head, aims straight, cone ≤ 20°, starts off). Night captures are staged in LATE
  (`elapsed_s` 760), not dusk.
  **NPC detail pass (2026-11-01):** `_face()` now builds sclera + iris + upper lid per eye, brow
  ridge, cheekbones, nose bridge/tip, ears with lobes and split upper/lower lips; the new
  `eye_white` material is a *fixed-colour* slot, so `_apply_outfit_materials()` leaves it white.
  `_hands_and_shoes()` has four fingers plus a thumb and `_clothing()` adds `Cuff` tori.
  Budget work 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
  "they walk backwards" symptom is a yaw bug, not an export flip.
- **Blender asset library (v0.6.0, integrated 2026-11-01):**
  `tools/blender_assets.py` (`build`/`render` in Blender; `audit`/`sheet`/`list` stdlib) writes
  `assets/models/blender/{npc,npc_gear,props}/*.glb`, `manifest.json` (integration source of
  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); the `npc_base`
  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; 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
  `albedo_color = WHITE` on unknown slots. Cycles CPU render ≈ 3 s/asset; Godot import of the
  library is clean.
  **Integration:** `NpcAvatar.character_model_for()` selects a variant by role/seed; only the
  five contract slots are tinted (detail materials untouched; `npc_vest` keeps its fixed hivis
  vest, firefighter/guard get dark uniform tints). Gear is attached at head/back/chest/hand and
  falls back to primitives; `npc_hoodie` skips the extra hood gear. `WorldBuilder` prefers
  `assets/models/blender/props/` for the six replacements and the new street dressing, fits the
  same colliders/obstacles, and collects library emissives for `set_night_mode()`.
  `LIBRARY_TRIANGLE_BUDGET` = 60k (current ~27,986). Library props are excluded from
  `PROP_PLACEMENTS` only when they need dedicated slots (door/marquee/sedan/handrail/lantern).
  **Gear fit (v0.6.1):** `fit` measures head width (0.315 m), skirt/hip radius and gear bounds;
  sunglasses are 0.202 m, the bag's body inner face is 0.262 m (coat 0.225, dress 0.260), and the
  helmet is lifted 2 cm above the brow. `test_npc_character` guards head/back gear in Godot.
  Blender's GLB export is byte-nondeterministic for unchanged assets (padding/index order), so do
  not commit a full no-op rebuild; rebuild only the assets whose geometry changed.
- **Venue geometry (v0.6.1+, 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
  left the focus disc over the face. An explicit `--portrait-type=N` now overrides the hooded
  skip, but the day roster spawns none of types 5-7, so a hooded close-up is deferred.
- **v0.6.0 environment pass:** `tools/bake_ao.py` bakes 256² AO maps per library asset
  (`<name>_ao.png`, red channel) and `Materials.apply_ao()`/`SurfaceMaterials` wire them in;
  `tools/make_normal_maps.py` derives tangent normals for the 1024² brick/concrete/asphalt
  textures. Forward+ boots on desktop but is rejected for v0.6.0 (project-wide renderer, Web
  must stay GL Compatibility). Headless 222/222, Python 69/69.
- **Prop pipeline (done):** audit enforces 400 tris / 600 verts, ground contact, UV range, no
  degenerate tris, one material. `capture_prop_gallery.gd` writes `10-prop-gallery.png` (3x2 studio
  line-up, back row on a platform) and the `prop_gallery` catalogue entry compares it.
- **NPC character pass (v0.5.0):** Rig is articulated (`Rig/Hip* -> Knee`, `Shoulder -> Elbow ->
  Hand`); `outfit_for` adds layer/hair_style/hand_item; `_idle_layer` drives phone/clipboard/crossed
  and escalation gestures; `_reaction_tag` shows `!!`, `?!`, `!`, `?`; `apply_lod` swaps to a
  billboard impostor at 26 m (hysteresis 1.5 m); GameManager `_refresh_queue` assigns queue offsets.
  Perf: 16 avatars = 534 meshes, ~6.9 ms headless.
- **Player movement (v0.5.0):** **W was inverted** (`get_axis(forward, back)` is negative for W and
  the code multiplied it directly); now `forward * -input_dir.y`. Step-up uses test_move + a raised
  copy (0.32 m). Guard emits footstep/landed/precision_changed; GameManager forwards them to
  AudioFeedback and the HUD. Gamepad actions are added at runtime by
  `GuardController._ensure_gamepad_bindings`; remaps persist via `Save` `input_bindings` and are
  applied by `InputBindings.apply` (key/button events only). Windowed `smoke_movement.gd` guards it.
- **Scheduled TODO pass complete:** only the optional Future ideas remain (live replay, extra
  venues, voice audio, image-to-mesh). Grounding facts: the
  NPC rig is rigid capsules with a whole-limb swing, and `guard_controller.gd` uses one `accel`
  value. Each task should get its own windowed smoke or capture where it changes feel/looks.
- **Backlog complete:** every planned TODO section is done and moved to `DONE.md`; `TODO.md`
  now only lists optional future ideas (live 3D replay, NPC LOD, more venues, real audio, prop
  atlas, AI mockups for the new catalogue entries, image-to-mesh props). GUT was consciously not
  adopted (custom runner covers it without an editor plugin).
- Do not re-open `override_access`. Do not bind wand to `W`. Do not remove the radio easter egg.

## UI / Presentation Decisions

- Runtime UI/scene art is loaded through `src/game/ui/art.gd` (`assets/images/ui/` then `scenes/`); missing files return null so panels keep procedural fallbacks.
- Screen mockups with baked-in controls are used as backdrops plus an opaque `ArtPanel` cover, not as clickable full-screen skins.
- Radio, wand, inspection, and body-camera timeline panels use their reference art as backdrops; forms sit on transparent, padded panels over the covered mockup controls.
- HUD target names use a boxed chip under the crosshair; escalation has a five-segment bar below the text label. The body-camera REC/clock block starts at y=92 on the right so it clears the shift/rep/crowd text.
- Staged captures in `docs/screenshots/` are committed and were regenerated on 2026-11-03 with the full `tools/check_screenshots.sh` run (21 good / 0 bad, 13 PNGs changed). Re-run the whole script, never a partial capture, before replacing them. The README, `docs/README.md` quick preview, `docs/screenshots/README.md` and `docs/blender_previews/README.md` now carry captioned galleries; the previews README is curated by hand (all tracked sheets linked, local per-asset PNGs described as untracked).
- `tools/check_screenshots.sh` is the repeatable capture+compare smoke; both capture scripts accept `--out=res://docs/screenshots`. Judge verdicts on the staged set were 7 match / 4 review / 0 diff.
- Venue selection used to leave `guard.input_locked` true and the mouse visible; `_start_shift()` must call `_refresh_freeze()` after starting the clock.

## Current State

- **v0.3.0 pass (2026-10-31, historical; shipped):** rendering, generated prop models, screen
  catalogue, aim-free selection. See ADR-0011 (selection) and ADR-0012 (materials/props).
  - `src/game/materials.gd` (`SurfaceMaterials`) is now the single source of surface
    recipes + `configure_environment()`. `GameManager.PHASE_LIGHTING` gained
    `exposure/glow/fog_color/fog_density/fog_energy/contrast/saturation/ambient_energy`.
    Renderer is **GL Compatibility**, so SSAO/SSIL are unavailable; glow+fog+ACES are used
    instead and unsupported settings are ignored rather than gated in code.
  - World: scaled brick (uv 22,10), framed windows with per-window night emission
    (`i % 3 != 2` lit), stone base course, door trim/handles, curb, lane dashes (the old
    loop had `Vector3(i * 0.0, …)` and stacked every dash at x=0), street lamps use the
    metal profile. The two flat planters that clipped the steps were removed.
  - `tools/model_pipeline.py` builds `assets/models/generated/*.glb` (bollard, bench,
    trash_bin, planter_box, newspaper_box, fire_hydrant) from box/cylinder specs;
    `WorldBuilder._add_prop_model()` loads them with a procedural fallback and records
    `loaded_models` / `fallback_props`. **Gotcha:** glTF `baseColorFactor` is LINEAR —
    writing sRGB made every prop pastel; `srgb_to_linear()` is applied in `build_glb`.
    **Gotcha:** a new/changed `.glb` needs `godot --headless --path . --import` before
    `ResourceLoader.exists()` / `load()` sees it (test_generated_props fails otherwise).
  - `model_pipeline.py concept` (OpenRouter, reads repo `.env`) writes per-prop concept
    sheets to `assets/models/concepts/`; `dominant_colors()` centre-crops and weights by
    saturation (a grey studio backdrop otherwise wins), `assign_roles()` maps colours by
    hue/value. Delete a concept file to fall back to the catalogue palette.
  - NPC avatars: `outfit_for(type, seed)` (pure) gives shirt/trousers/hair/skin +
    accessory (cap, hood, backpack, sunglasses, lanyard) and height scale; `_arms` and
    `_legs` now swing (`limb_swing`) while walking. Keep `Rig/Head` named for focus.
  - Selection: `NpcFocus.rank_indices` (angle then distance) — `pick_index` = first.
    `GuardController.cycle_target(direction)` walks nearest-first `nearby_candidates()` and
    sets `target_pinned`, which makes `_update_target()` skip the cone. `clear_target()`
    sets `focus_suppress_s = 0.75` so the cone does not instantly re-acquire the person.
    New input actions `walk_slow` (Shift), `cycle_target_next` / `cycle_target_prev`
    (wheel down / up). Right click with nothing open clears focus (Esc still pauses).
  - HUD: `nearby_label` + `set_nearby_hint(count)` show `hud.nearby`; `hud.controls` and
    `hud.targeting` mention the wheel and Shift.
  - `tools/screen_designs.py`: catalogue now 19 screens (added wand_screening,
    joke_shop_queue, studio_arrival, crowd_panic, responder_arrival,
    body_camera_timeline, escalation_hud), new `list` command, `generate --only/--force`
    (existing designs are kept by default so a draft run cannot clobber AI mockups),
    and `judge --dry-run` no longer raises `KeyError: 'class'`.
  - Screenshot tool leak: `capture_screenshots.gd` intermittently prints
    `ObjectDB instances leaked at exit`. Verified against a `git worktree` of HEAD~ — the
    baseline leaks more often (3/3 vs 1/3), so it is a pre-existing quit-timing artifact,
    not a regression. Normal boots are clean.

- Access artifacts: `src/core/access_loadout.gd` builds from event `override_access` + venue policy.
  Spawn signal is now `(profile, intent, npc_id, event)`. Recognition is not auto-attached to every
  guest. `AccessVerifier.verify(..., already_screened=false)` so Joke Shop scoring uses
  `controller.screened`. Joke Shop/Studio gained `sidewalk`/`steps_end` waypoints. Wand venues roll
  `carried_items` per spawn (seeded). Tests in `src/test/tests/test_access_loadout.gd`.
- Wand shortcut is **`C`**, not `W` (`W` is walk). `radio_emergency` input map no longer includes W.
  `hud.controls` / `hud.screen_first` updated.
- Control pass (historical; smoke-tested): cone focus via `src/game/npc_focus.gd`,
  accel/decel, gravity only airborne, `input_locked` freeze, Esc no longer on the guard.
  `NpcAvatar` in group `npc`; neck/hair/eyes/shoes; blue focus circle + `Label3D` name; `set_focus_visual`.
  `src/game/ui/action_radial.gd` doughnut (LMB/Space open, A/D/arrows, Space/click confirm, Esc/RMB
  cancel). Crosshair CanvasLayer. Emergency still `R` only. Number keys 1–6 when the wheel is closed.
- Named input actions now exist and are used: `action_menu`, `confirm`, `cancel` (Esc + RMB),
  `inspect` (E), `wand` (C). The old unused `interact` action was removed.
- Runtime fixes from the smoke: `Head` is +1.6 above the guard root (root sits on the floor); guard
  spawns in front of the door facing the street; building volume moved to z ∈ [-8,-4] so the door,
  awning, and marquee are visible; step treads rise toward the door; `ShiftCoordinator` pulls the
  event scheduler once per simulated second (was every physics frame → >1200 NPCs in seconds);
  `GameManager.MAX_LIVE_NPCS = 16` caps live avatars.
- **Session shell (2026-10-31, historical):** the game boots into `StartMenu`
  (`src/game/ui/start_menu.gd`, layer 20) instead of a live shift. `GameManager._on_venue_selected()`
  builds the scenario and calls `_start_shift()`; `_shift_running` gates input and `_refresh_freeze()`.
  Esc with nothing open now pauses (`PauseOverlay`, layer 18) → resume / restart / settings /
  quit-to-menu. `SettingsPanel` (layer 22) writes `look_sensitivity` + `hud_font_scale` through
  `Save.save_settings()` → `user://settings.json`; `Save.load_settings()` merges over
  `Save.DEFAULT_SETTINGS` on boot and `GameManager._apply_settings()` pushes them into the guard/HUD.
  Shift review "Run another shift" now calls `_show_start_menu()` (not a silent restart). `V` stays a
  debug venue bind. Smoke: `src/test/smoke_session_shell.gd` (menu → shift → pause → settings → menu).
- **World follow-ups closed (2026-10-31):** skyline backdrop restored with `T_SKYLINE`
  (`assets/textures/skyline.png`, regenerated RGBA with a transparent sky) and an
  `TRANSPARENCY_ALPHA_SCISSOR` unshaded material (`_skyline_mat`); steps + landing are a
  `StaticBody3D` with per-tread `BoxShape3D` colliders; marquee `font_size` 160 / outline 24; focus
  circle (blue disc in front of the face) + name tag 48px; `NpcAvatar.ephemeral`/`lifetime_s` despawns routine traffic
  (authored events stay). Guard spawn height verified on the landing (guard_y=0.84).
- **PLAN verbs (2026-10-31, historical):** the radial has 12 slices
  (`Stop, Look, Point, No, Ask, Inspect, Wand, Warn, Block, Reason, Recognize, Radio`).
  `eye_contact` reuses the Level 1 reaction table via `_apply_interaction`. Recognition is a player
  decision: `NPCController.player_recognized` + `IncidentRecorder.add_access_evidence`, and
  `GameManager._artifacts_for()` prepends a `RECOGNITION` artifact only after the player declares
  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()` 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
  it when the target changes. (2) Nav path points sit on the navmesh plane (y=0) while bodies stand
  at y≈0.5, so a 3D "are we there" test always looked 0.5 m away and the horizontal direction was
  zero — compare horizontally. (3) `path[0]` is the old start point, so picking any point "far
  enough away" can pick the point behind you and oscillate — pick the first point that is
  **closer to the goal** than the current position. `_nav_try_frames`/`_move_direct` fallback is
  still there.
- **Crowd reactions listen on the EventBus:** `CrowdSystem.apply_event()` emits
  `event_bus.crowd_changed`; its own `changed` signal is never emitted. `GameManager._connect_crowd()`
  therefore connects to `coordinator.event_bus.crowd_changed` (reconnect after every
  `coordinator.setup()`, which recreates both crowd and event bus).
- **Crowd presentation:** `NpcAvatar.start_rubberneck(at)` (idle bystanders away from the door stop
  and face the incident for 12 s) and `start_flee(from)` (panic: walk away at 2.4 m/s, then free
  themselves). Someone `awaiting_interaction` within 3 m of the door is "engaged" and does not
  rubberneck. Use `position` (not `global_position`) for that distance check so it also works in
  headless tests outside the tree.
- **Perf:** a busy 16-NPC entrance measured ~1.2 ms/frame (824 fps with vsync off, 800 samples),
  so LOD/culling is not warranted at `MAX_LIVE_NPCS = 16`. Re-measure before raising the cap.
- **Incident recording was dead:** `IncidentRecorder.start_incident()` was never called, so every
  `add_event`/`add_access_evidence` silently no-opped and the review always showed 0 incidents.
  `_begin_incident()` now starts one per focused NPC (`has_open_incident()` guard), verbs call
  `_ensure_incident()`, and `ShiftCoordinator._finish_shift()` closes leftovers as `unresolved`
  before building the review.
- **Editor-ready venues (2026-10-31):** `tools/export_venues.gd` (a SceneTree script) saves the
  three factory scenarios to `content/venues/<id>.tres` with `ResourceSaver`; the `.tres` files
  round-trip through `ResourceLoader` (events, profiles, policy, shift phases, door lines,
  locations). `test_venue_resources.gd` also fails if the exported files are missing or stale
  relative to the factory, so re-run the export after changing `ScenarioFactory`.
- **Vision judge (2026-10-31):** `python3 tools/screen_designs.py judge` sends the capture plus
  its concept mockup to a vision model (`DEFAULT_JUDGE_MODEL = google/gemini-2.5-flash-lite`,
  override with `--model`; `openai/gpt-4o-mini` also works). Reads the repo `.env` via
  `_load_env_file()` (never overrides real env). Verdicts are classed `match` / `review`
  (mismatch below `--fail-confidence`, default 0.6) / `diff` (confident mismatch → exit 1) /
  `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 `%`,
  unsupported conversions, and mixed positional/sequential placeholders. Tests cover all three
  plus a formatting pass over every placeholder key with type-correct dummy args.
- **Authored scenario content (2026-10-31):** events can now carry `hint` (a string key logged
  when the avatar spawns), `extra_spawns` (celebrity arrivals pull in tourists/influencers via
  `_spawn_npc` with `kind: routine`), and `refuses_screening` (copied to
  `NPCController.refuses_screening`; `_toggle_wand_screening` logs `wand.refused`, records a
  `wand_refused` event, applies a small prop hit, and does not open the panel). `film_boundary`
  is a new intent that maps to `steps_end` so the influencer stands past the posted line.
- **Accessibility (2026-10-31):** escalation text is `"<name>  [###--] L3/5"` via
  `Hud.escalation_meter(level)` (pure, tested) so the cue survives grayscale. HUD font scale uses
  `add_theme_font_size_override` on the core labels (`set_font_scale`), **not** `Control.scale`,
  which pushed the right-anchored clock label off-screen. Settings load before `_build_ui()`, so
  `_ready()` re-applies player settings after the HUD exists.
- **Audio (2026-10-31):** `AudioFeedback.start_crowd_bed()` builds a 4 s looping `AudioStreamWAV`
  (one-pole-filtered noise + 68/103 Hz drone, seeded) and `set_crowd_level(mood)` maps 0..1 to
  -34..-12 dB. `play_radio_open/close` push short filtered-noise bursts. All procedural; with a
  dummy (headless) audio server the calls are no-ops. `_free_player()` returns null when `_ready`
  has not run (tests), and callers handle null.
- **NPC theater (2026-10-31):** `NpcAvatar.theater_pose()` maps `intent` + `arrived` to
  idle/sit/photo/film/perform. Pure helpers `crouch_for_pose`, `prop_lift_for_pose`,
  `sway_for_pose` keep the math testable. Sit lowers the rig by 0.34 and swings the legs forward
  (negative X pitch; positive looked like kneeling). `_photo_prop` is set for influencer/tourist
  cameras, `_sign_prop` for protester/performer boards; their base Y values are captured at build
  time so the animation offsets from rest.
- **Body-camera timeline (2026-10-31):** `src/game/ui/event_timeline.gd` flattens
  `review.incidents.incidents[].events` into one time-ordered list (`flatten`), formats each row
  with `describe`, and steps with Left/Right or the buttons. `ShiftCoordinator.started_at_ms`
  gives the review an absolute start for mm:ss stamps. `GameManager._open_timeline` hides the
  review dim (two stacked overlays made the screen nearly black) and `_timeline_from_review`
  restores it on close. Smoke: `src/test/smoke_timeline.gd`.
- **Radio dispatch was dead after the first shift:** `coordinator.setup()` builds a new
  `RadioSystem`, so the `responder_arrived` connection made in `_ready` was lost on every venue
  switch/restart (responders never resolved anything). `_connect_radio()` now re-wires it next to
  `_connect_crowd()` after every setup. Same class of bug as the crowd signal.
- **Emergency aftermath:** `ShiftCoordinator.responder_outcomes` / `investigations` feed the review.
  `evacuation` (emergency call, low danger, no weapon) locks the door, makes every NPC flee, marks
  them `leave_requested`, and applies a `security_failure` hit. An emergency placed while
  `current_npc_truth` has no weapon and `danger_level <= 1` appends an investigation note, records
  `investigation_opened`, and applies `false_report` -6.
- **Skyline backdrop (2026-10-31):** `PlaneMesh` defaults to a **horizontal** XZ plane — set
  `mesh.orientation = PlaneMesh.FACE_Z` or the "backdrop" renders as a band overhead. The skyline
  is now a ring of four 400x60 planes at 200 m (center y=30, so building bases meet the ground),
  `TEXTURE_FILTER` default, `TRANSPARENCY_ALPHA_SCISSOR` with threshold **0.5** (0.3 left faint
  mip dashes across the sky), unshaded with a lifted albedo (`Color(2.6,2.7,3.0)`) so it is not
  pure black. Ground is 500x500 so no sky gap shows under the buildings. The `skyline.png` import
  needs `mipmaps/generate=true`.
- **Asset gotcha:** `assets/textures/game_ready/` is *not* imported (no `.import`). Use the
  imported `assets/textures/skyline.png` path. Untracked duplicate folder should not be referenced.
- Host sign-in follow-up is **done**: `REQUIRE_SIGNIN_VIEW = false` in `/etc/gitea/app.ini`
  (backup `app.ini.bak-*` alongside), Gitea restarted; anonymous repo page/API return 200 and
  release assets download in full. Reverse by setting it back to `true` and restarting.
- **Release publishing was broken since v0.2.2 (fixed 2026-10-31):** `publish_release.sh`
  only built `AUTH` in the `GITEA_TOKEN` branch; the `~/.git-credentials` branch set `CRED`
  and then used unbound `${AUTH[@]}` under `set -u`, so every API call failed and the tag
  job ended "could not create or find release". The repo also has **no** `GITEA_TOKEN`
  secret (`/actions/secrets` is empty) and the runner has no git credentials. Fixes: the
  script sets `AUTH=(-u "$CRED")`; the workflow falls back to `github.token`
  (`secrets.GITEA_TOKEN || github.token`) — but `github.token` is **not** provided by this
  Gitea/act runner, so the env dump showed no token and the v0.2.10 tag build failed again.
  Final fix: `publish_release.sh` falls back to the **local git extraheader** that
  `actions/checkout` writes (`git config --local --get-regexp '^http\..*\.extraheader$'`),
  which carries the runner's basic-auth credentials for the same server. Verified locally by
  adding that extraheader and publishing v0.2.10 (all five artifacts). **v0.2.9 and v0.2.10
  are published**; v0.2.4–v0.2.8 tags have no artifacts. Verify the CI path on the next tag.
- **CI publishing verified (2026-10-31):** tagging v0.2.12 produced a release with all five
  artifacts automatically (no repo secret), confirming the checkout-extraheader fallback.
- **Host access (2026-10-31):** `root@192.168.88.30` now works from this workstation (key auth),
  host name `gitea`, Gitea 28.2.0. Maintenance applied: `apt-get clean`, journald capped to
  `SystemMaxUse=300M` (`/etc/systemd/journald.conf.d/99-size.conf`, journal ~133M), disk at
  ~7.6G free of 16G.
- **Host disk resolved (2026-10-31):** the Gitea VM root filesystem was expanded from 7.8G to
  16G (`/dev/mapper/pve-vm--500--disk--0`, now ~7.8G free). The pruned **v0.2.0** and **v0.2.9**
  releases were restored from the local `build/` artifacts and verified (4 and 5 assets).
  `git.allucanget.biz` runs on this host as user `zwitschi`; root@192.168.88.30 is **not**
  reachable from this workstation (publickey denied; password auth closes the banner), so host
  maintenance must go through a `zwitschi` login with sudo.
- **Host disk full (2026-10-31, historical):** the v0.2.11 tag build created release id 27 and logged the
  uploads, but they failed with `HTTP 500 Attachments.Save: write … no space left on device`
  (`/dev/mapper/pve-vm--500--disk--0`, 7.8G, 100%, 0 free). `git push` then failed too
  ("unpacker error"). Unblocked by deleting the superseded **v0.2.0** and **v0.2.9** releases
  via the API (~565 MB of assets), then publishing v0.2.11 locally with the fixed script
  (verified 5 assets). Remaining ~150 MB is tight — the next release needs host cleanup on
  192.168.88.30: `sudo journalctl --vacuum-size=100M` (journal 837 MB), `sudo apt-get clean`
  (91 MB), clear `/var/lib/gitea/data/attachments/tmp`. SSH works as `zwitschi`; `sudo -n`
  needs a password. **Releases now:** v0.2.11, v0.2.10, v0.2.1 (5 assets each); v0.2.0 and
  v0.2.9 entries were pruned. PLAN.md + ADRs 0007–0010 still describe the intended UX.
- **Release v0.2.1 is LIVE** (2026-10-31): CI run 1110 built the NSIS installer + AppImage
  and published — installers/AppImage are on the releases page. Releasing = bump version → tag → push.
- NSIS gotchas (validated in a local ubuntu:24.04 docker repro): makensis uses `-D` defines
  (never `/D`), resolves relative `-DICON`/`-DARTIFACT` against the **script directory** so CI
  passes `$PWD`-absolute paths; installed exe must be space-free (`gig-line.exe`); ICO must be
  classic BMP entries (ImageMagick `icon:auto-resize=48,32,16`; PIL emits PNG-compressed ICOs NSIS
  cannot load).
- appimagetool runs system `appstreamcli` if present (strict, exit 3 on warnings) — project
  metadata now passes `--pedantic`.
- Distribution facts (verified via Gitea API + host creds): repo is **public**, account is
  admin; `v0.2.1` has all 5 assets; the installers were initially missing from the release
  because `publish_release.sh` uploaded only portables — now fixed (uploads installer +
  AppImage; falls back to `~/.git-credentials` when no `GITEA_TOKEN`).
- Host sign-in: instance `[service] REQUIRE_SIGNIN_VIEW=true` blocks anonymous browse/download
  (not a repo/API setting). `~/.git-credentials` holds the Gitea creds (basic-auth usable);
  `.env` only holds `OPENROUTER_API_KEY`.
- **Release v0.2.0 was LIVE**: pushing the `v0.2.0` tag made Gitea Actions run the build job
  and publish automatically (host has the `GITEA_TOKEN` secret). Tag page and `/releases` are
  public (HTTP 200). Caveat: anonymous **asset downloads** redirect to login on this host
  (host setting — tracked in TODO). Future releases = bump `config/version`, `git tag vX.Y.Z`,
  push. No local token needed.
- Core simulation, three scenarios, v0.2.1 installers/AppImage, first-person prototype (inspect/wand/radio, shift review, Tab targeting, V venue cycle) are on local `main`. Tagged v0.2.1 was 57 tests; this working tree is **74/74**.
- NPC avatars now walk to per-intent waypoints (`VenueScenario.waypoint_for_intent`): enter/trespass/deliver/arrive → entrance, photo/film/perform/wander/roam → sidewalk, sit → steps_end. `NpcAvatar.setup` takes an explicit `door_position`.
- Returning-trespasser behavior: `NpcProfile.return_probability` (trespasser 0.6, mental-crisis 0.4, others 0). `NPCController._maybe_schedule_return()` moves a directed-away NPC to `LOITERING_DISTANT`; `tick_return(delta)` fires after 20-60s and transitions back to `APPROACH`. `NpcAvatar._advance_fsm` re-targets the door on return.
- Perception pass: `NPCController.perceive_guard(distance)` returns `{noticed, band, reaction}` with bands `unaware` (>6m), `aware` (2-6m), `near` (<2m). Near + temperament ≥0.6 → ARGUE, else COMPLY. `GameManager._perception_pass()` feeds real guard distance each physics tick and logs first-time notice.
- Responder dispatch: `RadioSystem` tracks `pending_calls` and decrements `arrival_delay_s` in `tick`; emits `responder_arrived` when a call's delay elapses. `RadioSystem.responder_outcome(call)` maps danger/weapons → command/restraint/evacuation/arrest. `GameManager._on_responder_arrived` spawns a `RESPONDER` avatar at the entrance and logs the outcome. HUD shows an emergency-radio cooldown label via `_update_radio_cooldown`.
- Wand screening (Joke Shop): `WandScreener` classifies carried items as prohibited vs false-alarm vs clear. `NpcProfile.carried_items` is filled at spawn on wand venues. `GameManager` binds **`C`** to `_toggle_wand_screening` and `A`/`D` to `decide_wand` while inspect/wand is open. `decide_access` still blocks admission until `controller.screened` is true, and `verify` now takes that flag. Door-staff lines log through GameManager.
- Design change (2026-10-31): the selectable dialogue tone-of-voice system was **removed**.
  `Rules.Tone`/`TONE_NAMES`, `NpcProfile.tone_modifiers`, and the tone param on
  `NPCController.roll_reaction/apply_player_action` no longer exist; `NpcProfile.dialogue_lines`
  is a flat `Array[String]`; `GameManager` uses `_apply_interaction(level, action_name)`;
  the `T` key is gone. HUD `tone_label` removed and `hud.tone_prefix` string deleted from JSON.
- Polish/accessibility: venue cycling (`V` cycles `VENUE_ORDER` and restarts the shift), aim-free
  targeting (`Tab` cycles nearby NPCs within `NEARBY_RADIUS`), color-coded escalation indicator
  (`Hud.set_escalation`), procedural audio (`AudioFeedback` node generates sine tones for
  confirm/radio/escalation/deny), and a centralized `Strings` table (`src/core/strings.gd`, `lookup`/`fmt`)
  backed by `content/strings.en.json`. NOTE: `Strings.get` was renamed to `Strings.lookup` because
  `get` collides with `Object.get`.
- Newly added: LATE shift phase (start 700s) with a reachability test; PROTESTER archetype + events + colors; CALL_SOMEONE reaction; `DoorState` core class + `L` binding + visual indicator; flashlight (`G`, SpotLight3D, perception bonus at evening/late); persistence wired (`Save.save_shift_result` on shift end, history + best score on the review screen); `NavigationRegion3D` flat navmesh + `NavigationAgent3D` NPC paths (steps now visual-only); strings moved to `res://content/strings.en.json` (41 keys, loader keeps `lookup`/`fmt`); `export_presets.cfg` (Linux/Windows/macOS) + `tools/build_releases.sh` + `docs/RELEASING.md`; README Downloads section.
- Run tests: `godot --headless --path . --script res://src/test/test_runner.gd`
- Boot check: `godot --headless --path . --quit-after 120`
- Screenshot tools: `godot --path . -s res://src/test/take_screenshot.gd` (single shot to `user://screenshot.png`); `godot --path . -s res://src/test/capture_screenshots.gd` (staged README gallery shots to `user://screenshots/`, copied to `docs/screenshots/`).
- Release build verified locally: export templates for 4.3 installed at `~/.local/share/godot/export_templates/4.3.stable/`; `./tools/build_releases.sh` produced Linux/Windows/macOS artifacts for 0.1.0 in `build/` and the Linux binary passed a headless smoke test. Publishing to Gitea still needs a token (see `tools/publish_release.sh`, `docs/RELEASING.md`).
- CI: the repo now carries a **Gitea Actions** workflow at `.gitea/workflows/build.yml` (checks on
  push/PR; full export + artifact upload + optional release publish on tags and `workflow_dispatch`).
  A repo secret `GITEA_TOKEN` is required for tag releases. The old `.github/workflows/ci.yml` was
  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
  (wristband, ID/ticket, wand-check, refusal, prohibited-item). Hollywood uses a wristband line,
  the Joke Shop uses ID/ticket/wand lines, and the Studio uses ticket/credential/guest-list lines.
- 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/
  trees, NPC per-seed variation. capture_screenshots.gd shoots day + fast-forwarded LATE night
  (6 shots in docs/screenshots/). Version bumped to 0.2.0; binaries rebuilt.
- Assets pipeline: `python3 tools/generate_textures.py` produces all authored PNGs under
  `assets/textures/` (≤1024px, pow2); regenerate after changing the script, then run
  `godot --headless --import` before tests. 57 headless tests guard the pipeline.
- General image pipeline: `python3 tools/asset_pipeline.py` defaults to
  `openai/gpt-5-image-mini`, requests supported 1:1/3:2 sources, then fits each role's target.
  It provides crop, resize, tile edge blending, alpha-glyph recoloring, and role-aware audits.
  Screenshot auditing checks 1280x720 minimum, 16:9 aspect, and contrast; visual composition
  remains a manual check. Python tools require Pillow from `requirements-tools.txt`.
- AI texture mode: `python3 tools/generate_textures.py --ai` generates textures via the
  OpenRouter image API (`POST https://openrouter.ai/api/v1/images`, model
  `bytedance-seed/seedream-4.5` by default, base64 PNG in `data[].b64_json`). Requires
  `OPENROUTER_API_KEY` (a gitignored `.env` in the repo root holds it locally; source it
  with `set -a && . ./.env && set +a`). `--prompt`/`--name`/`--model`/`--size` override the
  default batch. Output is downscaled to ≤1024px. NOTE: seedream rejects sizes below
  3,686,400 px (1920×1920), so the script requests `GEN_SIZE=2048` and downscales — do not
  lower `GEN_SIZE` below 1920. Verified end-to-end 2026-10-31 (3 textures generated).
  Legacy `--ai` remains on Seedream 4.5 and still ignores `background: transparent`; do not
  use it for alpha-dependent assets. Gemini 3.1 Flash Image advertised broad ratios but the
  current provider rejected authentication. The validated role-aware model is GPT-5 Image Mini.
- Runtime assets: all 15 loaded world/HUD/card textures now live in
  `assets/textures/ai/game_ready/`; each passes role audit. Generated tile edges are blended,
  icon alpha masks are recolored white where needed, and the vignette uses the existing
  deterministic generator because the API returned an empty transparent image. The six
  `docs/screenshots/` captures were regenerated after wiring and pass screenshot audit.
- Detailed graphics: textured facade/awning/skyline, humanoid NPC rigs + props + walk bob +
  attention head-turn, inspection artifact cards, mode icons, escalation vignette, body-cam
  overlay (REC + shift clock). Screenshot set regenerated (`docs/screenshots/`, day + night).
- Polish: wand scan cooldown (`WAND_COOLDOWN_S` + `wand.recharge` message).
- NOTE: collaborators occasionally add uncommitted work to this shared tree (e.g. the radio
  easter egg); check `git status` before committing and leave foreign changes untouched unless asked.

- Screen-design references (`tools/screen_designs.py`, tests in `tools/test_screen_designs.py`):
  `generate` turns the screen descriptions in `docs/` (README captions, ADRs 0007–0010,
  PLAN, architecture) into reference images under `docs/screens/designs/` — `--draft`
  draws offline Pillow wireframes, `--ai` generates realistic 3D scenes / in-game UI via
  OpenRouter (default model `openai/gpt-5-image-mini`). Screens are tagged `scene` or
  `ui`; prompts get a shared art-direction suffix, and requests use a 3:2 landscape
  source cropped to 16:9 (not a square centre-crop). `compare` checks `docs/screenshots/*.png` for aspect/size/
  blank-frame and coarse layout/palette/detail drift. Drift distances are warnings, not
  failures: a mockup never matches a real render, so semantic composition is a follow-up
  vision-model judge (tracked in TODO).

## Known Issues / Notes

- Reference cycles are fixed: `FSM` holds its owner via `WeakRef`, `ShiftCoordinator` is
  `RefCounted`, and persistence tests free the `Save` node — the suite exits with no
  "resources still in use" warnings (was ~13). If a future subsystem introduces a cycle,
  repeat the WeakRef pattern.
- Shift length: `GameManager` uses the scenario's `shift_duration_s` (900s ≈ 10-15 min);
  tests and the screenshot tool override elapsed time directly.
- Headless (dummy renderer) logs "Parameter m is null" from `mesh_get_surface_count`; it does not occur with a real GL driver and does not affect logic.
- Steps have per-tread colliders (`_build_steps()` adds a `StaticBody3D` with one `BoxShape3D`
  per tread), so the guard and NPCs walk up the entrance; the guard spawns on the landing.
- 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).
- 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 **272/272**; Python tooling is **108/108**; 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
  parse error. Type it as the script type (`ActionRadial`) or annotate the local explicitly.
  `--check-only --script` cannot see the `Save` autoload; use a real boot (`--quit-after 180`) to
  verify a full-scene compile.
- 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)
  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

- Whether the responder avatar should be playable/controllable or purely scripted.
- Localization target languages beyond English.
- macOS notarization approach for broad distribution.

## Plan vs code

`PLAN.md` describes intended design; `README.md` and `DONE.md` describe what shipped. As of
2026-11-03 the playable build covers the three venues, tutorials/campaign/checkpoints, the 0.9.3
UI/accessibility pass, the 0.9.4 NPC visual optimization, the 0.9.5 texture/material pass, the
0.9.6 integration checkpoint, and the Blender + realism asset pipeline. `TODO.md` holds the remaining
0.9.6–0.10.0 work. The project uses a custom headless runner, not GUT, and Gitea Actions, not
GitHub Actions.

<!-- b64: RWFzdGVyIGVnZzogYSByYXJlIHJhZGlvIHRyYW5zbWlzc2lvbiAiwr9Ew7NuZGUgZXN0w6EgbGEgbW90YT8iIGZpcmVzIHZpYSBHYW1lTWFuYWdlci5fbWF5YmVfcmFkaW9fZWFzdGVyX2VnZyAoMi41JSBjaGFuY2UgYWZ0ZXIgYSBzdWNjZXNzZnVsIHJhZGlvIGNhbGwpLiBTdHJpbmcga2V5IHJhZGlvLmVhc3Rlcl9lZ2cgaW4gY29udGVudC9zdHJpbmdzLmVuLmpzb24uIERvIG5vdCByZW1vdmUu -->

## Uncommitted Workstreams

- **None (2026-11-03).** The 0.9.6 integration checkpoint is committed, tagged
  `v0.9.6` and published with seven assets; the workspace is clean apart from
  local/gitignored realism and capture output. Keep the rule from `AGENTS.md`: check `git status`
  before committing, and never revert another contributor's in-flight files.