security-game/MEMORY.md

# MEMORY

Session memory for durable decisions, gotchas, and commands. Implementation history lives in
`DONE.md`, user-facing changes in `CHANGELOG.md`, the live task list in `TODO.md`, and the
canonical implemented-features list in `docs/development-status.md`.

## Decisions

- **Local-only reference override (2026-11-03, owner):** development-only photo research ignores
  the licence gate. Downloads live in `tmp/research/` (gitignored): DDG image search, street-view
  frames, neighbouring buildings — never committed, never shipped. Promotion into
  `docs/screens/refs/` always passes the sidecar licence + privacy gate and `CREDITS.md`.
- **AI-assisted asset review loop (2026-11-04):** head/face shape decisions use a concept +
  judge loop — generate a target concept (`generate_textures.generate_image`, Seedream) and use
  `tools/describe_image.py` as the vision judge, iterating on the mesh until the judge's specific
  fixes converge. This is what picked the MakeHuman head over the procedural displacement head
  (`_head_proto` oscillates between "decorated egg" and "spiky wedges" at ~3/5 on the coarse
  sphere). Review page: `docs/screens/head-review/README.md`; methodology note:
  `docs/3d-model-review.md` §AI-driven head rework.
- **Project agent skills (2026-11-03):** two tracked skills live in `.agents/skills/`:
  `gig-line-blender-asset-contract` and `gig-line-release-qa`. They are guidance only,
  add no runtime dependency and are referenced from `tools/README.md`. The third-party
  `blender-skills` pack remains gitignored.
- **TV Studio shares the Hollywood location (owner):** the Late Night TV Studio is the same El
  Capitan Entertainment Centre block at 6840 Hollywood Blvd (which houses *Jimmy Kimmel Live!*),
  restaged for a late-night arrival. `VENUE_SPECS["tv_studio"]` is a 30.0 m variant of the 29.6 m
  Hollywood facade. One reference board serves both venues; never create a separate TV Studio board.
- **Jimmy Kimmel Live = starting point:** the Hollywood first shift and the TV Studio arrival both
  begin at the El Capitan block. Stated in `docs/venues.md#hollywood-boulevard` and `docs/gameplay.md`.
- **Street-view limitation:** Google Street View panoramas need a Google API key or manual browser
  capture, so the local reference sets use DDG street-level photos instead.
- **Image-recitation filter:** Gemini image models reject well-known branded facades (Comedy Store
  wall) as generation anchors (`IMAGE_RECITATION`). Workaround: anchor on a less-branded frame of
  the same block, or generate text-only when the reference adds no geometry.
- **OpenRouter image-to-image:** `/v1/images` is text-to-image only; the working path is
  `POST /v1/chat/completions` with a `content` array carrying a base64 `image_url`. Response
  images arrive as `message.images[].image_url.url` (fallback: a data URI inside the message text).
  Implemented in `generate_textures.generate_image(reference_path=...)` and
  `scene_concepts.py generate/anchor`; provenance sidecars are `.refgen.json`.
- **Facade/venue material picks (2026-11-03):** the Masonic/El Capitan facade uses the
  photo-anchored `limestone_ashlar` field (warm tint `Color(0.85, 0.81, 0.74)`) with `stone_steps`
  for trim; the Joke Shop uses `dark_stucco`; the marquee canopy/sign box stay `black_metal` by
  design (fictional "GIG LINE" marquee, not the red El Capitan Theatre marquee next door). The
  TV Studio reuses `masonic_facade`. Committed Comedy Store refs were removed in favour of the
  local-only `tmp/research/comedy-store/` set; the three-up board's photo panel is a historical
  public-domain frame.
- **Godot 4.7.2 `--import` gotcha:** with a stale `.godot/` cache, new image files never import
  (no `.import` created) and `preload()` of the new texture fails every dependent script with the
  misleading `Could not resolve external class member "spec"`. Fix: import in a scratch copy with
  `.godot/` removed, then copy back the `.png.import` and `.godot/imported/*.ctex/.md5`.
- **Blender skills pack (local aid):** MIT `blender-skills` at `.agents/skills/blender-skills/`
  (94 skills + shared `references/`), gitignored, kept out of Godot's scanner by
  `.agents/.gdignore`. Keep the pack flat when updating (`cp -a <pack>/.claude/skills/. ...`).
  Pi gates project `.agents/skills` behind project trust.
- **Gaussian splatting (unversioned):** offline/development-only until an ADR proves licence,
  privacy, Compatibility/Web cost and mesh collision. Accepted photo channels: team captures,
  permissioned user/volunteer photos, clearly licensed downloads; every set needs a
  provenance/consent sidecar. No runtime splat dependency in 0.10.0.
- **0.10.0 balance protocol:** `docs/release-qa.md#balance-acceptance` defines targets/denominators for the
  36 venue/difficulty/phase cells, seeds 1–100, and access/emergency error rates. Gotcha:
  `_read_npc_truth()` is type-derived, not behaviour-derived; the emergency-fairness review must
  account for that oracle mismatch.
- **Blender MCP is optional (2026-11-04):** setup and safe part workflow are in
  `docs/asset-tooling.md#optional-interactive-blender-mcp`. The headless flatpak scripts remain authoritative; MCP is
  never a build/CI/test/runtime dependency, and anything MCP touched must pass the
  CLI audit/fit gates.
- **Character mesh cap (2026-11-05):** all characters use 24,000 tris / 24,000 glTF vertices
  (`CHAR_MAX_TRIS`/`CHAR_MAX_VERTS` in `tools/blender_assets.py`; `npc_pipeline.MAX_TRIANGLES`/
  `MAX_VERTICES`). The required 13 core bones stay, optional extra bones are allowed, and the
  low-poly `npc_base` fallback remains the shipped fallback. The raise funds the Quaternius base bake and
  the 12-variant clothing detail. Measure the 24-NPC/Web budget after
  any geometry change; never silently lower the cap without a new decision.
- **Quaternius is the NPC base (2026-11-05, owner):** ADR-0017 supersedes the generator-first
  sourcing decision. The CC0 Quaternius Ultimate Modular character pack is the primary NPC mesh
  and animation source. Stage 1 bakes a proportion-warped, 13-core-contract `npc_base` so
  `NpcAvatar`, gear and animations keep working; the 62-joint/24-clip source rig is authoring
  input, not a runtime dependency. If the warp fails the silhouette gate, Stage 2 needs a new ADR
  for a 62-joint runtime, not a hybrid. The MakeHuman head and procedural `npc_base` remain
  tested fallbacks until the Quaternius rollout ships. Quaternius source: CC0, attribution in
  `CREDITS.md`; the three researched GLBs and licence notes are kept in
  `tmp/npc-research/quaternius/`. MPFB/MakeHuman body work is closed; do not add new work there.
- **Engine baseline:** Godot 4.7.2 stable (official editor `~/.local/bin/godot`). The system's
  `godot-runner` cannot load arbitrary project paths (compiled without path overrides); use the
  official editor binary.
- **GDScript/architecture:** cross-file references use explicit `preload()` constants (not
  `class_name`) so scripts compile in headless `--script` runs; the test runner is a custom minimal
  harness (not GUT, which needs the editor plugin); no autoload signal bus — `ShiftCoordinator`
  owns the `EventBus` instance passed to subsystems.
- **Skinned NPCs (v0.6.0):** `NpcAvatar._build_skinned_body()` loads `npc_base.glb`; procedural
  `_build_body()` is the fallback. Bone pose rotation is the **absolute local orientation**, not an
  offset — compose with `get_bone_rest(i).basis` or the body snaps to a broken pose. Five tint
  slots via `SurfaceMaterials.npc_slot()`; keep `_rig.scale` uniform on the skinned path.
- **NPC facing:** the avatar's visual front is **+Z**; Godot `look_at()` aims **-Z** (made NPCs
  walk backwards). Use `NpcAvatar.yaw_towards(dir)` and set `rotation.y`; never `look_at()` on
  avatars. Head-turn offsets use `+basis.z` for the same reason.
- **Release blockers (still open):** macOS unsigned, AI image provider terms/commercial rights not
  cleared, storefront/rating approval pending, external playtests and full hardware matrix pending.
  Recorded in `CREDITS.md`, `PRIVACY.md`, `docs/accessibility.md`, `docs/known-limitations.md`.

## Gotchas / Known Issues

- **Two character builders — do not confuse them.** `tools/blender_assets.py` is the real builder
  for the **eight library characters, 18 gear pieces and props** (it has the 0.9.4 face/hand
  sculpting in `_face()`/`_hands_and_shoes()`); `tools/npc_pipeline.py` builds **only**
  `assets/models/generated/npc_base.glb`, the frozen plain-primitive fallback. Reading
  `npc_pipeline.py` to judge the library's face/hand detail is wrong.
- **Pose capture fixed (2026-11-04):** the harness was missing `set_physics_process(false)`/
  `set_process(false)` on the avatar, so the FSM (`_advance_fsm` + `_move_toward_target`) ran every
  tick, reset `arrived`/velocity and made `theater_pose()` revert to idle/rest. Disabling both fixes
  it (sit vs idle diff 5.63, walk vs idle 2.29). The earlier "moving the `Rig` child does not
  render" probe was a red herring — it set the position inside `_shoot()` in the same frame as
  `root.get_texture().get_image()`, so it never rendered a frame. Lesson: pose/portrait harnesses
  must freeze the avatar's process/physics before driving `_animate()`.
- Capture/pose harness gotchas: scripts that read captured-mouse input must run windowed
  (`smoke_props.gd`); the NPC FSM rewrites `rotation.y` every physics tick, so pose/portrait
  captures set the yaw after `set_physics_process(false)`; `visible=false` does not keep the crowd
  out of a portrait frame (park the rest of the crowd away instead).
- Blender: `bisect_plane` and thin bevels leave zero-area triangles (Godot "non-finite normal in
  LOD generation"); `_clean()` + a weld after bisect fixes them and the audit rejects them.
- Image models have per-model size floors/caps (Seedream needs 1920+; `GEN_SIZE=2048`, do not
  lower; gpt-5-image-mini caps lower). `generate_image` applies model-specific sizing; concept
  generation defaults to `--request-size 1536`.
- Local photo research tooling: DDG rate-limits by IP (HTTP 202) — the `refcollect.py` token bucket
  (0.5 req/s, burst 3) plus retry/backoff handles it; some DDG frames are AVIF mislabeled
  `.png`/`.jpg` (convert with ffmpeg; `refcollect.py sheet` skips unreadable). Commons API needs a
  descriptive User-Agent and rate-limits thumbnail downloads (fetch all metadata in one
  `titles=A|B|C` query).
- Frozen decisions: do not re-open `override_access`; do not bind wand to `W`; do not remove the
  radio easter egg.
- GDScript: no static signals; lambdas capture locals **by value** (mutating a captured local does
  not affect the outer variable — use member functions for accumulators).
- Reference cycles: `FSM` holds its owner via `WeakRef`, `ShiftCoordinator` is `RefCounted`; if a
  new subsystem introduces a cycle, repeat the WeakRef pattern.
- Headless (dummy renderer) logs `Parameter m is null` from `mesh_get_surface_count` — benign, does
  not occur with a real GL driver.
- macOS export requires `rendering/textures/vram_compression/import_etc2_astc=true` (universal
  build demands ETC2 ASTC).
- Typed spawn signal: handlers must accept the 4th `event: Dictionary` arg or Godot will not call
  them.
- GDScript inference trap: a `var` typed as a base class (`radial: CanvasLayer`) exposes script
  members as `Variant`; type it as the script type (`ActionRadial`). `--check-only --script`
  cannot see the `Save` autoload — use a real boot (`--quit-after 180`) to verify 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.
- Light falloff: `omni_attenuation = 0.0` is **constant**, not physical, falloff in Godot 4.7 —
  all local lights use `1.0`.
- glTF `baseColorFactor` is LINEAR — writing sRGB makes props pastel; `srgb_to_linear()` is applied
  in `build_glb`. A new/changed `.glb` needs `godot --headless --import` before `load()` sees it.
- **Rebuilding a character GLB also requires re-baking its AO** (`tools/bake_ao.py -- --only
  <name>`). `blender_assets.py build` writes the GLB only; the old `<name>_ao.png` then maps onto
  the new geometry and produces large dark cheek/jaw blotches. Bake the AO, re-import, and refresh
  the stale `.godot` cache (scratch-copy import) before judging a face/body change.
- `Save.SETTINGS_FILE` is declared and unused; settings persist through
  `load_settings()`/`save_settings()`.
- Crowd reactions emit `event_bus.crowd_changed`; `GameManager._connect_crowd()` must reconnect
  after every `coordinator.setup()` (same class of bug as the radio-dispatch reconnect).
- Packaging: NSIS uses `-D` defines (never `/D`) and resolves relative defines against the script
  directory (pass `$PWD`-absolute paths); installed exe must be space-free; ICO must be classic
  BMP entries (PIL emits PNG-compressed ICOs NSIS can't load). appimagetool runs system
  `appstreamcli` — pass `--pedantic`.
- Credentials: `~/.git-credentials` holds the Gitea creds; `.env` holds only `OPENROUTER_API_KEY`.
- `assets/textures/game_ready/` is not imported (no `.import`) — use the imported
  `assets/textures/skyline.png` path.
- Godot 4.7 writes `*.gd.uid` files — kept out of `git status` via `.git/info/exclude`.
- Collaborators occasionally leave uncommitted work in the shared tree; check `git status` before
  committing and leave foreign changes untouched.

## Commands

- Tests: `godot --headless --path . --script res://src/test/test_runner.gd`
- Boot check: `godot --headless --path . --quit-after 120`
- Single screenshot: `godot --path . -s res://src/test/take_screenshot.gd`
- Staged gallery: `tools/check_screenshots.sh` (re-run the whole script, never a partial capture)
- Blender build: `flatpak run org.blender.Blender --background --python tools/npc_pipeline.py -- build`
  (flatpak cwd is `/app/blender` and cannot read `/tmp` — use absolute repo paths; `.gdignore`
  markers keep Godot from importing `.blend`/`tmp`)
- Textures: `python3 tools/generate_textures.py` (then `godot --headless --import`); AI mode
  `python3 tools/generate_textures.py --ai`; general pipeline `python3 tools/asset_pipeline.py`
- Character checks: `python3 tools/blender_assets.py inspect|audit|fit`,
  `python3 tools/npc_proportions.py`
- Docs: `python3 tools/check_docs.py` (every tracked image must be linked from its folder README)
- Head/part pipeline: `python3 tools/npc_parts.py build|extract|assemble|inspect|sheet|compare`
  (Blender subcommands run under flatpak). Head sources: `build_character(head="face"|"proto"|"mh")`.
- Reference research: `python3 tools/refcollect.py search <q> --slug <block> --limit N`
  (local-only), `tools/refboard.py` (Commons), `tools/three_up.py compose/rows`,
  `tools/scene_concepts.py generate/anchor/realism`

## Open Questions

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

## Handoff

### 2026-11-05 — NPC plan pivot and tmp cleanup

**What changed:** the NPC character direction was rewritten around the researched CC0
Quaternius character. ADR-0017 supersedes the generator-first decision in ADR-0015. `PLAN.md`,
`TODO.md`, `MEMORY.md`, `README.md`, `CREDITS.md`, the architecture/asset/review docs and the
docs index now point to the Quaternius base. The old MPFB/MakeHuman body tracks were closed and
their plans removed from `TODO.md`; the MakeHuman head and procedural `npc_base` remain tested
fallbacks only.

**Cleanup:** `tmp/` was reduced from ~2.9 GB to 4.7 MB. Removed the MPFB/MakeHuman scripts,
review renders, map scratch output and logs. Kept only the three researched Quaternius GLBs,
the Quaternius mirror HTML/README/licence, `prototype_quaternius.py`, and a local
`tmp/npc-research/quaternius/README.md` with hashes and re-download links. Do not delete that
folder while the migration is active.

**Implementation status:** planning and documentation only. No character GLB, code, manifest,
AO map or test was changed. The 12 shipped NPC GLBs still use the old procedural bodies.

**Next task (start here):** `TODO.md` → *Quaternius NPC base migration* → §1 Intake and
canonical base. First concrete step: inventory the four meshes, 62 joints, 24 clips and
material names in each of the three GLBs, then build a welded, grounded, animation-free
`quaternius_base.glb` at 1.81 m with front on Blender −Y.

**Main risk:** the source is a 62-joint T-pose with realistic proportions (research measured
~0.96 m hip, ~1.68 m arm span, ~0.153 m shoulder offset), while the runtime contract is an
arm-down 13-core rig with a 0.62 m hip and 0.27 m wrist targets. The Stage 1 proportion warp is
the make-or-break step. Judge the Quaternius result directly; do not reuse the old MPFB arm
warp. If the warp fails the silhouette/gear gate, stop and write the Stage 2 62-joint ADR.

**Key paths:**
- Source GLBs: `tmp/npc-research/quaternius/{Casual,Casual_Hoodie,Worker}.glb`
- Source hashes and inventory: `docs/npc-model-sourcing.md`
- Decision: `docs/adr/0017-quaternius-npc-base.md`
- Contract: `docs/architecture.md#character-and-gear-asset-contract`
- Runtime selector/fallback: `src/game/npc_avatar.gd`, `assets/models/blender/`
- Current library builder/fallback: `tools/blender_assets.py`, `tools/npc_pipeline.py`,
  `assets/models/generated/npc_base.glb`

**Useful checks:** `python3 tools/check_docs.py`; `pytest -q tools/tests`;
`python3 tools/blender_assets.py audit|fit`; Blender headless:
`flatpak run org.blender.Blender --background --python "$PWD/tools/blender_assets.py" -- inspect --category npc --file "$PWD/<file>.glb"`.
This session ran `check_docs` and `git diff --check` after the doc rewrite; Python tests were
last green at 167/167. Godot tests were not rerun because no runtime file changed.

**Commit:** `2c90743 Rewrite NPC plans around the Quaternius base`. Working tree clean.

## Current State

The playable build covers the three venues, tutorial/campaign/checkpoints, the 0.9.3–0.9.6
polish/texture/integration passes and the Blender + realism asset pipeline (see `DONE.md` and
`CHANGELOG.md`). The 12-character library (realistic face + four crowd variants) and the
Comedy Store map rebuild are complete. **Priority (2026-11-05, owner):** 1) the **Quaternius NPC
base migration** (bake the CC0 Quaternius character to the runtime contract), 2) the 3D model and
map improvements, 3) ship it all together in the **0.10.0 minor**. The 0.9.7/0.9.8
character patches are published; `TODO.md` is the priority source. The active implementation is
the Quaternius base migration (ADR-0017); planning/docs were rewritten and `tmp/` cleaned on
2026-11-05, but no character GLB has been rebuilt yet. Test counts as of 2026-11-05: Python
167/167 (last run), Godot 277/277 (last run before the docs-only pivot), `check_docs` OK.

<!-- b64: RWFzdGVyIGVnZzogYSByYXJlIHJhZGlvIHRyYW5zbWlzc2lvbiAiwr9Ew7NuZGUgZXN0w6EgbGEgbW90YT8iIGZpcmVzIHZpYSBHYW1lTWFuYWdlci5fbWF5YmVfcmFkaW9fZWFzdGVyX2VnZyAoMi41JSBjaGFuY2UgYWZ0ZXIgYSBzdWNjZXNzZnVsIHJhZGlvIGNhbGwpLiBTdHJpbmcga2V5IHJhZGlvLmVhc3Rlcl9lZ2cgaW4gY29udGVudC9zdHJpbmdzLmVuLmpzb24uIERvIG5vdCByZW1vdmUu -->