Overhaul the head source: weld + relax the decimated MakeHuman head into one clean manifold shell

.agents/skills/gig-line-blender-asset-contract/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: gig-line-blender-asset-contract
-description: Use when adding, rebuilding, auditing or fixing any Gig Line Blender-authored character, NPC base, gear, prop or venue geometry. Covers the 13-bone npc_base contract, five tint slots, triangle/vertex budgets, gear attach space, 256² texture/AO rules, headless flatpak Blender commands, and the inspect/audit/fit/proportion/capture gates. Do not use for pure GDScript/UI work or release publishing.
+description: Use when adding, rebuilding, auditing or fixing any Gig Line Blender-authored character, NPC base, gear, prop or venue geometry. Covers the required 13 core bones (optional extra bones allowed), five tint slots, 16,000/16,000 character budgets, gear attach space, 256² texture/AO rules, headless flatpak Blender commands, optional MCP guidance, and the inspect/audit/fit/proportion/capture gates. Do not use for pure GDScript/UI work or release publishing.
 compatibility: Gig Line repository checkout. Godot 4.7.2 on PATH; Blender 5.2 LTS via the org.blender.Blender flatpak for build/bake/render. Audit, fit, inspect and proportion checks are stdlib-only.
 metadata:
   project: Gig Line
@@ -21,9 +21,10 @@ Use this skill for any change that touches:
 - Blender-authored venue/prop geometry
 
 The project contract and measured gates override any generic Blender advice.
-There is **no Blender MCP** in this project. Blender runs headless through the
-flatpak CLI; the `blender-skills` pack is optional, local guidance only, and
-gitignored.
+Blender MCP is optional interactive tooling; the headless flatpak CLI remains
+authoritative and CI never needs Blender or MCP. The `blender-skills` pack is
+optional, local guidance only, and gitignored. Setup and safety are in
+`docs/asset-tooling.md#optional-interactive-blender-mcp`.
 
 ## Read first
 
@@ -47,11 +48,11 @@ and resolve the source of truth before editing assets.
 | Area | Rule |
 | --- | --- |
 | Mesh root | `npc_base` mesh node, skinned under `Rig`; preserve the limb node names. |
-| Bones | 13 contract bones: `Head`, `HipL/R`, `KneeL/R`, `ShoulderL/R`, `ElbowL/R`, `HandL/R`, `Spine`, `Neck` (parent/helper bones must not change the contract). |
+| Bones | The 13 required core bones: `Head`, `HipL/R`, `KneeL/R`, `ShoulderL/R`, `ElbowL/R`, `HandL/R`, `Spine`, `Neck`. Optional extra bones (fingers, face, toes) are allowed; they must not move the core rest positions or break animation proxies. |
 | Tint slots | `skin`, `cloth`, `pants`, `accessory`, `hair`. |
 | Orientation | Front is Blender −Y / Godot +Z; feet grounded near y = 0; metres. |
-| Library budget | **8,000 triangles / 8,000 glTF vertices** per character (`CHAR_MAX_TRIS`/`CHAR_MAX_VERTS`). |
-| Frozen fallback | `npc_base` keeps **6,000 tris / 4,000 verts**. Do not silently raise or lower it. |
+| Character budget | **16,000 triangles / 16,000 glTF vertices** per character (`CHAR_MAX_TRIS`/`CHAR_MAX_VERTS`). |
+| Frozen fallback | `npc_base` remains the low-poly fallback; it shares the 16,000/16,000 cap but is not required to use it. Do not silently lower the cap. |
 | Gear budget | **1,500 triangles** per gear piece; authored in attach-point space. |
 | Prop budget | **4,000 triangles** per prop. |
 | Gear attach | Use the catalogued attach points; verify with `fit`. Runtime `GEAR_OFFSETS` (lanyard forward, firefighter helmet up) and `HAND_ITEM_FORWARD` are intentional, not asset-contract changes. |
@@ -113,8 +114,7 @@ only the specialists the task needs:
 - budget/LOD/collision: `asset-optimization`, `lod-pipeline`, `collision-proxy`
 - final review: `qa-review`
 
-Translate any MCP instruction into a change to `tools/*.py` or a headless CLI
-run. Never add an MCP dependency to the build, CI or runtime.
+If MCP is available, use it for interactive part exploration only; mirror the result into a scripted change or local `.blend`, then re-export and run the CLI audit/fit gates. Never make the build, CI, tests or runtime depend on MCP. Setup: `docs/asset-tooling.md#optional-interactive-blender-mcp`.
 
 ### 4. Build or bake
 
@@ -167,7 +167,7 @@ At minimum:
 - `npc_proportions.py` passes the stylized guide.
 - `npc_pipeline.py audit` passes if the base/textures changed.
 - texel density is inside the authored/fabric bands.
-- No character exceeds 8,000/8,000; gear/prop caps hold.
+- No character exceeds 16,000/16,000; gear/prop caps hold.
 - 24-NPC budget and Web/Compatibility path remain green.
 - Contract tests, headless suite, capture gates and docs check pass.
 - The diff contains only the intended assets, tools, tests and docs.
@@ -197,12 +197,14 @@ gates run, and any accepted limit.
 
 - [`references/asset-contract.md`](references/asset-contract.md) — full contract,
   inventory, file locations and provenance rules.
+- `docs/asset-tooling.md#optional-interactive-blender-mcp` — optional MCP installation, connection, safety and
+  part-workflow instructions.
 - [`references/verification.md`](references/verification.md) — command matrix,
   capture gates, expected results and acceptance criteria.
 
 ## Do not
 
-- Add an MCP server, Blender dependency or API call to the build/runtime.
+- Make the build, CI, tests or runtime depend on MCP, Blender or API calls.
 - Change the bone/tint/contract to make a generic asset fit.
 - Rewrite committed baselines or overwrite existing images.
 - Commit `.blend` sources, raw captures or generated AI inputs.

.agents/skills/gig-line-blender-asset-contract/references/asset-contract.md

@@ -17,7 +17,7 @@ This is a working summary. The authoritative sources remain
 
 ## Skeleton and geometry
 
-The contract skeleton has 13 bones:
+The required contract skeleton has 13 core bones:
 
 ```text
 Head, Spine, Neck,
@@ -28,6 +28,9 @@ ElbowL, ElbowR,
 HandL, HandR
 ```
 
+Optional extra bones (fingers, face controls, toes) are allowed if they do not
+move these core rest positions and do not break `NpcAvatar`'s animation proxies.
+
 Requirements:
 
 - `npc_base` mesh node exists and is skinned under `Rig`.
@@ -56,8 +59,7 @@ skin, cloth, pants, accessory, hair
 
 | Asset | Limit |
 | --- | --- |
-| Library character | 8,000 triangles / 8,000 glTF vertices |
-| `npc_base` fallback | 6,000 triangles / 4,000 vertices |
+| Character (library and base fallback) | 16,000 triangles / 16,000 glTF vertices |
 | Gear piece | 1,500 triangles |
 | Prop | 4,000 triangles |
 | Library prop/venue total | must stay inside the venue tests and library budget |

.agents/skills/gig-line-blender-asset-contract/references/verification.md

@@ -24,6 +24,7 @@ Blender must be absolute.
 | NPC base | `python3 tools/npc_pipeline.py audit` | exit 0, contract bones/slots/maps |
 | Proportions | `python3 tools/npc_proportions.py report` | all eight inside the stylized guide |
 | Single incoming GLB | `flatpak run org.blender.Blender --background --python "$PWD/tools/blender_assets.py" -- inspect --file "$PWD/path.glb" --category <cat> --json` | contract result and measurements |
+| Part GLB (local) | `flatpak run org.blender.Blender --background --python "$PWD/tools/npc_parts.py" -- inspect --file "$PWD/tmp/npc-parts/<variant>/<part>.glb"` | measurements; a part GLB is not a shipped asset |
 | Prop audit | `python3 tools/model_pipeline.py audit` | exit 0 when generated props changed |
 | Texture audit | `python3 tools/asset_pipeline.py audit assets/textures/ai/game_ready` | exit 0 when textures changed |
 
@@ -98,6 +99,12 @@ without measuring.
 
 ## Visual review criteria
 
+The part pipeline (`tools/npc_parts.py`) builds/extracts head/face/hand parts under
+`tmp/npc-parts/<variant>/`; these are local working files and are **not shipped**. Only the
+assembled character GLBs, AO/maps, the manifest and the review sheets are committed. An
+assembled GLB still goes through `blender_assets.py inspect`/`audit`/`fit` before any part is
+accepted. The `npc_base.blend` fallback is frozen: never save prototype detail into it.
+
 For each changed variant, inspect at least:
 
 - 2 m portrait: eyes, mouth, ears, neck/shoulder, hair/headgear clearance.

.agents/skills/gig-line-release-qa/SKILL.md

@@ -20,7 +20,7 @@ publishing, and the full visual/QA gate. For a Blender/asset rebuild, use
 1. `AGENTS.md` — release procedure and verification rules.
 2. `TODO.md` — current milestone, blockers and release exit criteria.
 3. `docs/RELEASING.md` — build/publish commands, artifact list, macOS policy.
-4. `docs/smoke-checklist.md` — manual QA matrix.
+4. `docs/release-qa.md` — manual QA matrix and balance protocol.
 5. `docs/development-status.md`, `CHANGELOG.md`, `README.md` — current claims.
 6. `MEMORY.md` — release gotchas, especially the clean-worktree rule.
 

.agents/skills/gig-line-release-qa/references/qa-gates.md

@@ -93,7 +93,7 @@ python3 tools/screen_designs.py judge --model auto
 ```
 
 Record model, confidence/verdict summary, `diff` count and any manual review.
-`docs/screen-design-report.md` is the durable record.
+`docs/ui-copy.md#screen-design-judge-report` is the durable record.
 
 ## 6. Realism judge (when visual assets/lighting changed)
 

AGENTS.md

@@ -17,11 +17,13 @@ The project should be developed in small, reviewable steps. Agents must keep pla
 - `CHANGELOG.md` — The version history of user-facing changes. Keep an entry for each patch, minor, and major version.
 - `docs/development-status.md` — The implemented-features list and what is not yet implemented. Update it whenever a feature lands, is renamed, or is removed.
 - `docs/architecture.md` — The arc42-style architecture documentation (goals, constraints, building blocks, runtime views, decisions, risks).
-- `docs/gameplay.md` — Gameplay systems, venues, and the escalation model.
-- `docs/asset-tooling.md` — Asset pipelines, model tools, and screenshot gates.
+- `docs/gameplay.md` — Gameplay systems, tutorial, venues and the escalation model.
+- `docs/venues.md` — Real-site evidence, game mapping and venue simplifications.
+- `docs/asset-tooling.md` — Asset pipelines, model tools, optional Blender MCP and screenshot gates.
+- `docs/blender-assets.md` — Blender library operation and asset roles.
 - `docs/npc-model-sourcing.md` — Character-source evaluation, licence rules and the character-development plan.
 - `docs/getting-started.md` — Setup, run/test commands, and the controls table.
-- `docs/smoke-checklist.md` — The manual smoke-test checklist.
+- `docs/release-qa.md` — The manual smoke checklist and balance-acceptance protocol.
 - `docs/adr/` — Architecture Decision Records.
 
 ## Priority and Versioning
@@ -88,15 +90,17 @@ specialists the task needs:
 
 ### Project rules that override a skill
 
-1. **The project contract wins.** `npc_base` mesh node, the 13 contract bones at their rest
-   positions, five tint slots, front on Blender −Y / Godot +Z, grounded feet, 8,000
-   triangles / 8,000 glTF vertices per character, 1,500 per gear, 4,000 per prop. A skill
+1. **The project contract wins.** `npc_base` mesh node, the 13 required core bones at their rest
+   positions, five tint slots, front on Blender −Y / Godot +Z, grounded feet, 16,000
+   triangles / 16,000 glTF vertices per character, 1,500 per gear, 4,000 per prop. Optional
+   extra bones (fingers, face, toes) are allowed if they do not move the core rest positions. A skill
    may recommend another topology, naming or budget scheme; do not adopt it unless the
    change is explicitly planned and the contract, tests and docs are updated together.
-2. **There is no Blender MCP here.** The skills assume MCP tools; this project runs Blender
-   as headless flatpak scripts (`tools/blender_assets.py`, `tools/npc_pipeline.py`). Translate
-   MCP steps into script changes or CLI runs. Never add an MCP dependency to the build, CI or
-   runtime.
+2. **Blender MCP is optional interactive tooling.** The headless flatpak scripts
+   (`tools/blender_assets.py`, `tools/npc_pipeline.py`) remain authoritative. MCP may be used
+   for local part exploration; setup and safety are in [`docs/asset-tooling.md#optional-interactive-blender-mcp`](docs/asset-tooling.md#optional-interactive-blender-mcp).
+   Never add an MCP dependency to the build, CI, tests or runtime, and always re-run the CLI
+   audit/fit gates on anything MCP touched.
 3. **CI stays offline and skill-free.** Skills are local guidance only; every gate must still
    work from a fresh checkout with committed `.glb`/`.png`/`.tres` files and Godot.
 4. **No new asset source without the licence gate.** Skills may suggest reference packs or

CHANGELOG.md

@@ -4,6 +4,16 @@ All notable user-facing changes to Gig Line. The format follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and versions use
 Semantic Versioning.
 
+## [0.9.8] — 2026-11-04
+
+### Fixed
+
+- Characters no longer detach at the wrist: the wrist and hand now track the same
+  bone, the hand was raised to meet the forearm, and the sleeve cuff follows the
+  hand instead of the elbow.
+- Seated and walking poses no longer collapse the hip/thigh or pinch the knee:
+  the thigh and shin are rigid to their bones with a short blend at the knee.
+
 ## [0.9.7] — 2026-11-04
 
 ### Added

CREDITS.md

@@ -40,6 +40,15 @@ kept outside version control.
 The CC-BY preview images are included only as development evidence. Any future
 shipped derivative of CesiumMan or RiggedFigure must keep the attribution above.
 
+### MakeHuman head source
+
+The decimated head used by the character head prototype is derived from the
+MakeHuman / MPFB base mesh, **CC0** (`assets/models/blender_src/makehuman_head.glb`;
+source `tmp/npc-research/makehuman/base.obj` with its bundled
+`LICENSE.md`/`LICENSE.ASSETS.md`). It is retargeted, decimated and re-weighted by
+project scripts; the exported character GLBs remain project assets. See ADR-0015
+and `docs/npc-model-sourcing.md`.
+
 The venue geometry is authored procedurally in `src/game/world_builder.gd` as a
 stylized reconstruction. The Joke Shop is a fictional stand-in for the real
 Sunset Strip block; the game does not claim endorsement by, or an exact replica

DONE.md

@@ -1343,7 +1343,7 @@ venues, and see enough authored variety that a second shift does not feel like a
 - [x] Write the tutorial beat sheet: menu → movement/look → focus and target cycling → action
       wheel → access inspection → polite direction → formal warning/body camera → radio →
       shift review. Eight beats and a safe compliant visitor are specified in
-      [`docs/tutorial.md`](docs/tutorial.md).
+      [`docs/gameplay.md#first-shift-tutorial`](docs/gameplay.md#first-shift-tutorial).
 - [x] Add a tutorial state machine independent of the normal shift FSM. `Tutorial` in
       `src/game/tutorial.gd` owns the eight beats, accepts only the current beat's action,
       supports skip/restart and has deterministic headless tests. GameManager/UI wiring starts
@@ -1544,7 +1544,7 @@ and supported by a stable CI/release baseline.
 
 - [x] Existing scenario-content, tutorial and campaign smokes cover the venue/action/review paths;
       the 0.9.5 release candidate adds the external first-hour pass.
-- [x] `docs/getting-started.md` and `docs/smoke-checklist.md` list tutorial, campaign/checkpoint,
+- [x] `docs/getting-started.md` and `docs/release-qa.md#manual-smoke-checklist` list tutorial, campaign/checkpoint,
       session, scenario, audio, crowd, emergency, movement and performance smokes.
 - [x] Current gallery/judge baselines are green; the 0.9.5 release candidate refreshes the final
       gallery after content lock.
@@ -1589,7 +1589,7 @@ Goal: streamline the maps, refactor geometry to match the images in `docs/screen
 - [x] Remove unnecessary or hidden geometry to improve performance.
 - [x] Ensure texture and material consistency across the map.
 
-Completed: the Hollywood venue is rebuilt from the real 6840 Hollywood Blvd references (six-column Masonic/El Capitan facade, eight steps, neighbours, Ovation arcade, Walk of Fame, four-lane street). The map-budget test measures 58,884 triangles across 409 meshes; Day/Night menu variants start in `EARLY`/`LATE`; the realism judge gaps are 0.148 (day) and 0.278 (late). See `docs/hollywood-boulevard-map.md`.
+Completed: the Hollywood venue is rebuilt from the real 6840 Hollywood Blvd references (six-column Masonic/El Capitan facade, eight steps, neighbours, Ovation arcade, Walk of Fame, four-lane street). The map-budget test measures 58,884 triangles across 409 meshes; Day/Night menu variants start in `EARLY`/`LATE`; the realism judge gaps are 0.148 (day) and 0.278 (late). See `docs/venues.md#hollywood-boulevard`.
 
 ### Map 2 — Joke Shop
 
@@ -1601,7 +1601,7 @@ Completed: the Hollywood venue is rebuilt from the real 6840 Hollywood Blvd refe
 - [x] Remove unnecessary or hidden geometry to improve performance.
 - [x] Ensure texture and material consistency across the map.
 
-Completed 2026-11-02: the Joke Shop is rebuilt from the real Comedy Store block at 8433 Sunset Blvd (27 m black hall, signature canopy, circular blade sign, red curtains, west entrance, low-rise neighbours, dry hillside and opposite frontage). The map-budget test measures 22,680 triangles across 454 meshes. The day/late captures and real-site notes are in `docs/joke-shop-map.md` and `docs/screens/concepts/joke_shop/`; the final gallery passed 13 good / 0 bad and the screen-design judge (13/13 match, 0 diff), with a 0.454 realism gap on the photoreal night reference.
+Completed 2026-11-02: the Joke Shop is rebuilt from the real Comedy Store block at 8433 Sunset Blvd (27 m black hall, signature canopy, circular blade sign, red curtains, west entrance, low-rise neighbours, dry hillside and opposite frontage). The map-budget test measures 22,680 triangles across 454 meshes. The day/late captures and real-site notes are in `docs/venues.md#the-joke-shop` and `docs/screens/concepts/joke_shop/`; the final gallery passed 13 good / 0 bad and the screen-design judge (13/13 match, 0 diff), with a 0.454 realism gap on the photoreal night reference.
 
 ### Scenery Change (Day/Night) for Hollywood Boulevard
 
@@ -1720,9 +1720,9 @@ screen-design judge before any model/texture changes. No gameplay rules change.
 - [x] Ran `tools/check_screenshots.sh` and `screen_designs.py compare`: 21 good,
       0 bad.
 - [x] Ran the judge with automatic model selection: 21/21 match, 0 review, 0 diff.
-- [x] Recorded the judge model and result in `docs/screen-design-report.md`; the
+- [x] Recorded the judge model and result in `docs/ui-copy.md#screen-design-judge-report`; the
       generated captures remain local/gitignored.
-- [x] Add a short UI copy/button checklist to `docs/smoke-checklist.md`.
+- [x] Add a short UI copy/button checklist to `docs/release-qa.md#manual-smoke-checklist`.
 - [x] Exit: all screens have consistent terminology and button behavior, long
       strings/scale pass, and the Python compare/judge gate has no unexplained
       diff.
@@ -1768,7 +1768,7 @@ and equipment fit.
 
 - [x] Audit all variants against a shared human proportion guide (head height, shoulder width,
       torso length, hip width, limb length, foot length) and correct the worst outliers.
-      (`tools/npc_proportions.py` + `docs/npc-proportion-audit.md`: all eight pass; no skeleton or
+      (`tools/npc_proportions.py` + `docs/npc-visual-review.md#proportion-audit`: all eight pass; no skeleton or
       mesh rescue was needed. Head and broad-build silhouettes are nearest their upper bounds.)
 - [x] Improve the neck and shoulder transition so the silhouette reads as one body rather than a
       thin post on a hanger. (Fuller neck base/top, lower shoulder root, degenerate-face cleanup;

MEMORY.md

@@ -19,7 +19,7 @@ canonical implemented-features list in `docs/development-status.md`.
   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/hollywood-boulevard-map.md` and `docs/gameplay.md`.
+  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
@@ -54,13 +54,19 @@ canonical implemented-features list in `docs/development-status.md`.
   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/balance-acceptance.md` defines targets/denominators for the
+- **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.
-- **Character mesh cap:** eight library variants use 8,000 tris / 8,000 glTF vertices
-  (`CHAR_MAX_TRIS`/`CHAR_MAX_VERTS` in `tools/blender_assets.py`); the frozen `npc_base` fallback
-  keeps 6,000/4,000. Measure after any geometry change; never silently lower the cap back to 5,000.
+- **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-04):** all characters use 16,000 tris / 16,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. Measure the 24-NPC/Web budget after
+  any geometry change; never silently lower the cap without a new decision.
 - **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.
@@ -178,10 +184,10 @@ canonical implemented-features list in `docs/development-status.md`.
 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-04, owner):** 1) release the finished procedural character development as
-the **0.9.7 patch**, 2) finish the MakeHuman character + the 3D model and map improvements,
-3) re-evaluate the 3D models, 4) ship it all together in the **0.10.0 minor** — `TODO.md` is the
-priority source. Test counts as of 2026-11-04: Godot 277/277,
-Python 161/161, `check_docs` OK.
+Comedy Store map rebuild are complete. **Priority (2026-11-04, owner):** 1) the **Blender NPC
+model overhaul** (head/face/hands, local part pipeline), 2) finish the MakeHuman character + 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. Test counts as of 2026-11-04:
+Godot 277/277, Python 162/162, `check_docs` OK.
 
 <!-- b64: RWFzdGVyIGVnZzogYSByYXJlIHJhZGlvIHRyYW5zbWlzc2lvbiAiwr9Ew7NuZGUgZXN0w6EgbGEgbW90YT8iIGZpcmVzIHZpYSBHYW1lTWFuYWdlci5fbWF5YmVfcmFkaW9fZWFzdGVyX2VnZyAoMi41JSBjaGFuY2UgYWZ0ZXIgYSBzdWNjZXNzZnVsIHJhZGlvIGNhbGwpLiBTdHJpbmcga2V5IHJhZGlvLmVhc3Rlcl9lZ2cgaW4gY29udGVudC9zdHJpbmdzLmVuLmpzb24uIERvIG5vdCByZW1vdmUu -->

PLAN.md

@@ -194,7 +194,7 @@ Primary decisions: [ADR-0007](docs/adr/0007-locomotion-and-input-layers.md), [AD
 
 ## Versioning and Delivery
 
-`config/version` in `project.godot` is the single version source (currently `0.10.0-rc.1`). Releases are tagged `v<version>`; the CI pipeline builds and publishes the standard artifacts plus the optional Desktop HQ zip. Version bumps follow [Semantic Versioning](https://semver.org/): every major, minor and patch increment needs a changelog entry, a local `tools/build_releases.sh` build, and artifact/checksum verification before tagging. Unversioned development tracks do not receive a version until their scope enters a release. See [`docs/RELEASING.md`](docs/RELEASING.md) and [`README.md`](README.md) for commands.
+`config/version` in `project.godot` is the single version source (currently `0.9.8`). Releases are tagged `v<version>`; the CI pipeline builds and publishes the standard artifacts plus the optional Desktop HQ zip. Version bumps follow [Semantic Versioning](https://semver.org/): every major, minor and patch increment needs a changelog entry, a local `tools/build_releases.sh` build, and artifact/checksum verification before tagging. Unversioned development tracks do not receive a version until their scope enters a release. See [`docs/RELEASING.md`](docs/RELEASING.md) and [`README.md`](README.md) for commands.
 
 ## Design Direction
 

README.md

@@ -33,14 +33,15 @@ Versions are assigned only when a track's scope is accepted into a release. Ever
 > Downloads are public (no sign-in required) since the host's instance-wide
 > `REQUIRE_SIGNIN_VIEW` was disabled on 2026-10-31.
 >
-> **Latest published: v0.9.6** — the integration checkpoint: the 0.9.5 texture
-> and material refinement (256² NPC maps, a four-times fabric weave without baked
-> AO blotches, repaired Walk of Fame/awning surfaces and per-phase skyline haze)
-> is packaged with the v0.9.4 NPC visual optimization, the Hollywood/Joke Shop
-> maps and the v0.9.3 UI/accessibility polish, with the full gallery, smoke matrix
-> and Web/Desktop HQ build re-verified.
+> **Latest published: v0.9.8** — the character-development patch: the
+> 12-character library, realistic face pass, four crowd-variety variants and the
+> wrist/hip/knee deformation fixes. Previous 0.9.x patches added the
+> Hollywood/Joke Shop maps, UI/accessibility polish, NPC visual optimization,
+> texture/material refinement and integration checkpoint.
 >
-> **Current source: v0.10.0-rc.1** — the release-candidate source; the final tag is pending external playtest and legal review.
+> **Current source: v0.9.8** — tagged from the same commit. The 0.10.0
+> development track remains gated on the NPC overhaul, MakeHuman/local-map work
+> and release approvals.
 > Releases are built automatically when a `vX.Y.Z` tag is pushed
 > (see [`docs/RELEASING.md`](docs/RELEASING.md)); manual builds use
 > `./tools/build_releases.sh`. Installer/AppImage packaging runs in the same pipeline
@@ -165,9 +166,7 @@ Full setup, every run/test/smoke command, and the controls table are in
 - [`CHANGELOG.md`](CHANGELOG.md) — User-facing changes by version.
 - [`docs/architecture.md`](docs/architecture.md) — arc42-style architecture documentation.
 - [`docs/gameplay.md`](docs/gameplay.md) — Gameplay systems, venues, and the escalation model.
-- [`docs/hollywood-boulevard-map.md`](docs/hollywood-boulevard-map.md) — Real-site references, game mapping and limitations for the Hollywood venue.
-- [`docs/joke-shop-map.md`](docs/joke-shop-map.md) — Real-site references, game mapping and limitations for the Joke Shop / Sunset Strip venue.
-- [`docs/tutorial.md`](docs/tutorial.md) — First-shift tutorial beats and rules.
+- [`docs/venues.md`](docs/venues.md) — Real-site references, game mapping and limitations for Hollywood, the Joke Shop and the TV Studio.
 - [`docs/asset-tooling.md`](docs/asset-tooling.md) — Asset pipelines, model tools, and screenshot gates.
 - [`tools/README.md`](tools/README.md) — Tool inventory, categories, test commands and AI-skill evaluation.
 - [`.agents/skills/gig-line-blender-asset-contract`](.agents/skills/gig-line-blender-asset-contract/SKILL.md) — tracked AI skill for Blender/NPC/gear asset work.
@@ -176,29 +175,26 @@ Full setup, every run/test/smoke command, and the controls table are in
 - [`docs/development-status.md`](docs/development-status.md) — Implemented features and what's next.
 - [`docs/accessibility.md`](docs/accessibility.md) — Accessibility features, known gaps and statement.
 - [`docs/known-limitations.md`](docs/known-limitations.md) — Release-candidate blockers and accepted limitations.
-- [`docs/smoke-checklist.md`](docs/smoke-checklist.md) — Manual smoke-test checklist.
+- [`docs/release-qa.md`](docs/release-qa.md) — Manual smoke checklist and release-candidate balance protocol.
 - [`CREDITS.md`](CREDITS.md) — Credits, AI/reference provenance and licensing notes.
 - [`PRIVACY.md`](PRIVACY.md) — Local-only data, save files and development API use.
 - [`docs/blender-assets.md`](docs/blender-assets.md) — Blender asset library: characters, gear, props, attach points.
 - [`docs/npc-visual-review.md`](docs/npc-visual-review.md) — 0.9.4 NPC baseline, acceptance criteria and ranked visual gaps; 0.9.5 texture comparison is in [`docs/blender_previews/sheet_texture_refinement_0.9.5.jpg`](docs/blender_previews/sheet_texture_refinement_0.9.5.jpg).
-- [`docs/npc-proportion-audit.md`](docs/npc-proportion-audit.md) — NPC proportion measurements against the shared stylized guide.
 - [`docs/adr/`](docs/adr/) — Architecture Decision Records.
 
 ## Development Status
 
-v0.10.0-rc.1 is the current release-candidate source: the 0.9.6 integration
-checkpoint plus save-migration hardening and release tooling, on top of the 0.9.5
-texture refinement (256² NPC maps, a 4× fabric weave with baked-AO removal, repaired
-Walk of Fame/awning surfaces and per-phase skyline haze), on top of the v0.9.4
-NPC visual optimization and the v0.9.3 UI/accessibility polish pass. It builds on
-v0.9.2's Hollywood/Joke Shop map rebuilds, v0.9.1's Godot 4.7.2 baseline,
-v0.9.0's production-quality pass, v0.8's
-tutorial/campaign/resume work and the v0.7.x venue/gear/judge work. The active
-planning priorities are the unversioned character and local-map development tracks;
-the 0.10.0 release candidate is the next versioned release. See
+v0.9.8 is the current source version: the character-development patch with the
+12-character library, realistic face and crowd variants, pose/deformation fixes
+and save-migration/release hardening. It sits on the 0.9.6 integration
+checkpoint, 0.9.5 texture refinement, 0.9.4 NPC visual optimization, 0.9.3
+UI/accessibility polish, 0.9.2 Hollywood/Joke Shop maps and the 0.9.x engine
+baseline. The active priorities are the Blender NPC head/face/hand overhaul,
+MakeHuman body intake and the 3D model/map re-evaluation; the 0.10.0 release
+candidate follows those tracks. See
 [`docs/development-status.md`](docs/development-status.md) for the implemented list
 and [`TODO.md`](TODO.md) for the priority-ordered roadmap. Manual verification uses
-the [`docs/smoke-checklist.md`](docs/smoke-checklist.md).
+[`docs/release-qa.md`](docs/release-qa.md).
 
 ## Credits, Privacy and Accessibility
 

TODO.md

@@ -3,15 +3,167 @@
 Work is grouped by theme. Each item should be small enough to complete and verify on its own;
 see `AGENTS.md` for the workflow and `MEMORY.md` for the decisions behind these plans.
 
-**Priority order (2026-11-04, owner):** 1) release the finished procedural character development
-as the **0.9.7 patch**, 2) finish the MakeHuman character + the 3D model and map improvements,
-3) re-evaluate the 3D models, 4) ship all of it together in the **0.10.0 minor**. See `AGENTS.md`
-§Priority and Versioning and §Local Blender skills.
+**Priority order (2026-11-04, owner):** 1) **Blender NPC model overhaul** — head, face and hands
+with a local part pipeline; 2) finish the MakeHuman character + the 3D model and map improvements;
+3) ship it together in the **0.10.0 minor**. The 0.9.7/0.9.8 character patches are published. See
+`AGENTS.md` §Priority and Versioning and §Local Blender skills.
 
 The MIT Blender skill pack lives locally at `.agents/skills/blender-skills/` (gitignored). Every
 3D workstream below names the skills to load; they are guidance only, and the project contract,
 `blender_assets.py audit`/`fit`/`inspect` and the capture gates stay authoritative.
 
+## Blender NPC model overhaul (top priority)
+
+Goal: replace the sphere-and-primitive face and hand construction with a local, part-based
+development pipeline that can build, inspect and compare the **head/face** and **hands** separately
+before assembling them into the shipped character. Prioritise face readability at portrait
+distance, then hand silhouette and gear contact. Preserve the `npc_base` contract, the 13 core-bone rig (optional extra bones allowed),
+five tint slots, 16,000/16,000 character cap, optional extra bones beyond the required 13, and the Compatibility/Web path.
+
+*Skill route: `character-artist`, `retopology`, `sculpting`, `rigging`, `uv-workflow`,
+`texture-workflow`, `materials`, `lookdev`, `asset-optimization`, `qa-review`.*
+
+**Current state:** `assets/models/npc/` contains the tracked frozen `npc_base.blend` and its
+gitignored `.blend1`; the 12 production characters are assembled procedurally by
+`tools/blender_assets.py` from `_shape_head_mesh`, `_face`, `_hair` and `_hands_and_shoes`.
+There is no per-part source asset library yet. The MakeHuman body prototype and its temporary
+head/hand swap live under `tmp/npc-research/` and are not the shipped path. This overhaul supplies
+the reusable head/face and hand parts that both the procedural characters and the MakeHuman body
+can consume.
+
+This workstream supersedes the face/head and hands items in §C until the prototypes are approved;
+the rest of §C remains the broad review checklist.
+
+### 1. Baseline and acceptance
+
+- [x] Inventory the real starting point: the frozen `assets/models/npc/npc_base.blend`, the 12
+      generated character GLBs/AO maps, the current `_face`/`_hands_and_shoes` builders and the
+      temporary MakeHuman head/hand swap. Recorded tris/verts, head subdivision, material slots,
+      UV layout and the exact locations of eye/mouth/finger geometry in
+      `docs/3d-model-review.md` §Baseline inventory.
+- [x] Define measurable acceptance: face front/three-quarter/profile at 1.5 m and 1.85 m; hands
+      open and gripping at 0.8 m; silhouette, eye/mouth readability, ear/nose/jaw planes, finger
+      separation and gear contact. Keep the 16,000/16,000 cap; optional extra bones are allowed, but the required 13 core bones and rest positions must not move.
+      Recorded in `docs/3d-model-review.md` §Overhaul acceptance criteria.
+- [x] Confirm the identity boundary: `npc_base.blend` is the frozen fallback and must not absorb
+      prototype detail unless a separate contract decision approves it.
+      Recorded in `docs/3d-model-review.md` §Baseline inventory and
+      `docs/blender-assets.md` §Frozen fallback boundary.
+- [x] Choose a local working-set layout: `tmp/npc-parts/<variant>/` (gitignored) for part `.blend`
+      and preview GLBs; only the assembled character GLBs, AO/maps, manifest and review sheets are
+      committed. Do not add a new committed `.blend` source tree without a docs/ADR decision.
+      Recorded in `docs/3d-model-review.md` §Working-set layout and
+      `docs/asset-tooling.md` §Recommended part-workflow.
+
+### 2. Local part pipeline
+
+- [x] Add `tools/npc_parts.py` with a small, documented CLI:
+      `extract` (pull the current head/hands for comparison), `build --part head|face|hand_l|hand_r`,
+      `assemble --variant <name>`, `inspect`, `compare` and `sheet`. It reuses the existing
+      builder helpers (`blender_assets.py` `_face`/`_hands_and_shoes`/`_shape_head_mesh`); no
+      second face/hand implementation. Verified end-to-end: built `head`/`face`/`hand_l`/`hand_r`,
+      extracted `hand_l` from the shipped GLB, assembled `npc_casual` (contract inspect: no issues).
+- [x] Keep the part pipeline local-only and headless: flatpak Blender for authoring, stdlib/Pillow
+      for inspection and sheets. No Blender MCP dependency, no new runtime dependency, no CI
+      Blender step.
+- [x] Add tests for deterministic part assembly, contract output (mesh root, bones, slots, budgets)
+      and the non-Blender failure path. `tools/tests/test_npc_parts.py` covers the part-name set,
+      the clean Blender-required error path, sheet/compare error paths and a real-PNG sheet. The
+      assembled prototype passes `inspect` (npc_base, 14 bones, skinned, no issues).
+- [x] Consider optional Blender MCP for interactive part exploration and document setup/safety.
+      (`docs/asset-tooling.md#optional-interactive-blender-mcp` covers addon/client setup, Pi `pi mcp add`, flatpak networking,
+      viewport/`bpy` workflow and the rule that headless audit/fit remains authoritative; MCP is
+      not a build/CI/runtime dependency.)
+- [x] Document the commands, working-set paths and "part source is not a shipped asset" rule in
+      `docs/asset-tooling.md`, `docs/blender-assets.md` and
+      `.agents/skills/gig-line-blender-asset-contract/references/verification.md`.
+
+### 3. Head and face prototype
+
+### 3. Head and face prototype
+
+- [x] Build one `npc_casual` head/face prototype as a connected head shell plus intentional feature
+      geometry — not a sphere with floating facial balls. Use loop-based eye sockets/lids, a
+      readable nose bridge/tip/ala, a mouth with upper/lower lip volumes, ears with concha depth,
+      and brow/cheek/jaw planes that survive the 256² AO bake.
+      Outcome (AI-judged, 2026-11-04): the displacement shell oscillated egg/spiky at ~3/5; the
+      judge picked the **decimated MakeHuman head**. That head is now built as `_makehuman_head`
+      (`build_character(head="mh")`, `npc_parts.py build --part head_mh`): committed CC0 source
+      `assets/models/blender_src/makehuman_head.glb` + project sclera/iris/lids/brows/mouth;
+      assembled `npc_casual` passes `inspect` (14 bones, no issues). Remaining polish: weld the
+      eye/brow pieces into the head shell and add a skull-conforming hair cap (owner-gated rollout).
+- [x] Compare two or three subdivision/loop variants at 1.85 m front/three-quarter/profile and a
+      1.5 m portrait. Pick the variant that reads best before changing all 12 characters; keep the
+      rejected variants local.
+      Compared `head_proto` at seg 24 (670 verts), 48 (1,558 verts) and 64 (2,470 verts) at 1.85 m
+      and 1.5 m, front/three-quarter/profile. Vision-judged: **s48 wins** — s24 is too faceted
+      (nose/lips melt, jagged silhouette), s64 is visually identical to s48 at both distances
+      (extra ~900 verts wasted). Rejected variants stay in `tmp/npc-parts/`.
+- [-] Verify head weights stay on the Head bone, headgear clearance still passes `fit`, and the
+      face does not bake recessed creases into dark AO patches.
+      Weight check done: `npc_parts.py assemble --head-proto` passes `inspect` (npc_base, 14 bones,
+      skinned, no issues) and the head join is weighted 100% Head by construction
+      (`rigid=lambda p: "Head"`). Headgear clearance and the AO no-blotch check are pending the
+      §5 rollout (the `fit`/`bake_ao` tools read the committed assets; the ad-hoc AO bake on the
+      imported GLB came out black and is superseded by the proper `.blend`-source bake). Flag: the
+      prototype ears reach x ±0.162 vs the 0.1575 head-radius reference, so headgear may clip and
+      must be re-measured at rollout.
+- [ ] Get owner sign-off on the one-variant prototype, then roll the approved head/face into the
+      other 11 variants one asset family at a time, with a before/after sheet per batch.
+      **Blocked on owner sign-off.** Sign-off material is ready: the s48 prototype vs the current
+      `_face` at 1.85 m front/three-quarter/profile
+      (`docs/blender_previews/sheet_head_proto_before_after.jpg`); the s24/s48/s64 comparison table
+      is in `docs/3d-model-review.md`. Rollout waits for the owner's go/no-go.
+
+### 4. Hands and grip prototype
+
+- [x] Build separate left/right hand parts with a connected palm, four multi-segment fingers, a
+      thumb, knuckles and rounded tips. Support an open palm and a relaxed grip; preserve the
+      current `HAND_ITEM_FORWARD` behaviour for phone/cup/clipboard/camera/flashlight/wand/radio.
+      `npc_parts.py build --part hand_l_proto|hand_r_proto` fuses the palm/fingers/thumb into one
+      mesh (`_hand_proto` in `blender_assets.py`, remove-doubles at 6 mm). Vision-judged at 0.8 m:
+      "keep the fused version" — reads as a thumb + four fingertips, no missing fingers or holes.
+      Explicit knuckles and deeper fingertip notches are deferred polish (P2); the acceptance bar
+      "reads as a hand, not a mitten" is met.
+- [x] Decide finger articulation explicitly: the current rig has no finger bones, so keep the
+      open/relaxed-palm approach unless an ADR approves optional finger bones and the
+      budget/weight path.
+      Decided 2026-11-04: keep the open palm + `HAND_ITEM_FORWARD` (no finger bones). Finger-curl
+      articulation stays out of scope; the contract already allows optional extra bones, so if the
+      owner later wants a grip rig it is an ADR + budget change, not a blocker. (Recorded in
+      `MEMORY.md`; re-confirmed here.)
+- [-] Verify all hand gear at 0.8 m (contact, clipping, direction) and capture open/grip hand
+      close-ups for the review sheet.
+      Open close-up captured (0.8 m). Gear contact is unchanged by construction: `_hand_proto`
+      reuses the same palm geometry and the same `HAND_ITEM_FORWARD`/Hand-proxy attach, so the
+      existing `fit` hand-gear clearances carry over. The grip close-up + gear-in-hand context
+      needs the §5 assembly (hand_proto swapped into the character), so it is verified there.
+- [ ] Roll the approved hands into all 12 variants only after the one-variant hand sheet passes.
+
+### 5. Assembly and rollout
+
+- [ ] Integrate the approved parts into `build_character` with deterministic joins, weights, UVs and
+      AO. The final output remains one `npc_base` skinned mesh under the existing 13-core armature;
+      optional extra bones are allowed but the core rest positions stay fixed;
+      no second rig, no material-slot rename.
+- [ ] Keep the MakeHuman body prototype consumable with the same approved head/hands; do not let it
+      grow a second face/hand implementation while the part pipeline is being proven.
+- [ ] Rebuild only the changed character GLBs, AO maps and manifest entries; never run a no-op full
+      library rebuild. Commit one asset family per change.
+- [ ] Re-run `blender_assets.py audit`/`fit`/`inspect`, `npc_proportions.py`, the 24-NPC budget,
+      Godot and Python tests, the 48-frame baseline and the 96-frame final-context review.
+
+### 6. QA, docs and exit
+
+- [ ] Capture front/three-quarter/profile head comparisons and open/grip hand comparisons; add
+      durable sheets to `docs/blender_previews/` and link them from the review docs.
+- [ ] Update `docs/3d-model-review.md`, `docs/npc-visual-review.md`,
+      `docs/known-limitations.md`, `MEMORY.md` and the project skills with the accepted limits and
+      the new part workflow.
+- [ ] Exit: head/face and hands are approved on one prototype, rolled out across all 12 variants,
+      all contract/budget/capture gates pass, the local part pipeline is documented, and no
+      runtime dependency or skeleton contract changed.
+
 ## Fix the Rig pose harness
 
 Goal: `src/test/capture_npc_pose.gd` reports a pose but saves rest frames; the root cause is
@@ -47,11 +199,11 @@ an active track; ADR-0015 (CC0 / CC-BY with attribution) still governs every int
 ### Intake and adaptation
 
 - [x] `adapt` path added to `tools/blender_assets.py` (`adapt --file <in> --out <out>
-      [--target-tris 8000]`): imports the GLB, applies transforms, grounds the feet, welds seam
-      splits and decimates to the budget, then exports. The five tint slots + 13-bone rig stay a
-      manual step (recorded in the command doc).
+      [--target-tris 16000]`): imports the GLB, applies transforms, grounds the feet, welds seam
+      splits and decimates to the budget, then exports. The five tint slots + 13-core rig
+      (optional extra bones allowed) stay a manual step (recorded in the command doc).
 - [x] `audit` stays the final gate; `test_adapt_requires_blender` covers the non-Blender error
-      path (161/161 Python).
+      path (162/162 Python).
 - [x] Adapter commands + go/no-go documented in `docs/asset-tooling.md` §Intake adaptation.
 
 ### MPFB / MakeHuman body pipeline
@@ -62,17 +214,23 @@ an active track; ADR-0015 (CC0 / CC-BY with attribution) still governs every int
       x ±0.53 / y 0–1.82 / z −0.12…+0.35, one neutral material, UVs present, unskinned. The
       body (no rig) is the input for the rigging step; the script + mesh stay in `tmp/` (CC0, not
       committed).
-- [x] Rig strategy decided (owner): **retarget the body to the 13-bone contract**.
+- [x] Rig strategy decided (owner): **retarget the body to the 13-core contract; optional extra bones are allowed**.
       `tmp/npc-research/makehuman_retarget.py` rotates the A-pose arms down (−38°/+38°), scales the
       arms 1.63× to the contract 0.70 m length, welds the split vertices, smooth-shades, adds the
       contract armature + `_auto_weights`, paints the five slot regions (hair/cloth/pants/accessory/
-      skin) and exports `makehuman_retargeted.glb`. **Contract passes:** 6,444 / 8,000 tris,
-      7,726 / 8,000 verts, 14 bones (13 + Hips), skinned, arm-down, grounded, five slots, no issues.
+      skin) and exports `makehuman_retargeted.glb`. **Contract passes:** 6,444 / 16,000 tris,
+      7,726 / 16,000 verts, 14 bones (13 + Hips), skinned, arm-down, grounded, five slots, no issues.
       Vision-reviewed: arms hang down and the silhouette + slot regions read, but the 1.63× arm warp
       distorts the deltoid/shoulder (spiky/warped), the decimated hands are blocky, and the slot
       boundaries are rough — these are the refinement steps below.
-- [ ] Re-run `inspect`/`audit`/`fit`/proportions and the 24-NPC budget after each intake; keep the
-      procedural generator as the fallback until a MakeHuman variant ships.
+- [x] Head/hands/feet swap (`makehuman_final.py`): cut the decimated MakeHuman head/hands/feet and
+      joined the project's `_face`/`_hair`/`_hands_and_shoes`, then re-weighted/re-UV'd. Contract
+      passes: 6,407 / 16,000 tris, 6,651 / 16,000 verts, 14 bones, skinned, five slots, no issues.
+      Vision-reviewed: the head now reads as a realistic face, the hands as detailed fingers and
+      the shoes as attached. Remaining (manual retopology): a 1.63× arm-scale warp still distorts
+      the deltoid/shoulder, stray hand blobs linger at the hips, shirt/shirt seams are rough, and
+      the head-neck junction has a shadow gap. The procedural generator stays the shipped fallback
+      until these are cleaned in an editor session.
 
 ## 3D model and local map re-evaluation
 
@@ -146,9 +304,9 @@ licence-free zone only.
       (`elcapitan`, `hollywood-block`, `jimmy-kimmel-stage`, `jimmy-kimmel-entrance`,
       `comedy-store`).
 - [x] Record which local frames changed a decision: added the frame→decision mapping to
-      `docs/hollywood-boulevard-map.md` (recent `elcapitan-2026` geosearch → 2009 frame stays the
+      `docs/venues.md#hollywood-boulevard` (recent `elcapitan-2026` geosearch → 2009 frame stays the
       geometry reference; `jimmy-kimmel-entrance/07.jpg` → the four entrance concepts) and
-      `docs/joke-shop-map.md` (`comedy-store/` → the four concept pairs + map plan;
+      `docs/venues.md#the-joke-shop` (`comedy-store/` → the four concept pairs + map plan;
       `comedy-store-hillside/` → the day-concept anchor that clears the image-recitation filter).
       Frames stay gitignored; only the provenance notes are committed.
 
@@ -192,11 +350,16 @@ licence-free zone only.
 - [x] Hands/grip review: the hands ARE detailed — `tools/blender_assets.py._hands_and_shoes()`
       builds a wider shallower palm, four two-segment bent fingers with rounded tips and a thumb;
       gear contact is the open palm plus the `HAND_ITEM_FORWARD` (0.04 m) offset. Decision: **keep
-      the open palm + forward offset; a finger-curl rig stays out of scope** — there are no finger
-      bones in the 13-bone contract, so a curl rig is a contract decision, not a modelling tidy-up.
-      Recorded as ranked gap #6 (accept; revisit only if face work opens the budget).
-- [ ] Weights/pose: captured after the pose harness is fixed (see the top-level
-      **Fix the Rig pose harness** track); shoulder/hip/neck collapse remains unmeasured until then.
+      the open palm + forward offset; a finger-curl rig stays out of scope** — the current rig has
+      no finger bones, so a curl rig is a contract decision, not a modelling tidy-up. Optional
+      extra finger bones are now allowed by the cap/contract extension, but require an ADR and
+      weight/budget verification. Recorded as ranked gap #6 (accept; revisit only if face work
+      opens the budget).
+- [x] Weights/pose evidence captured and vision-reviewed, and the P1s fixed: wrist/hand
+      detachment (wrist + hand now 100% `Hand`, hand raised, sleeve cuff follows the hand),
+      hip/thigh collapse + knee pinch (thigh/shin rigid with a short knee blend). Vision-verified:
+      hip fix clean, knee crease minor residual. The guard hip-pouch clip and the residual knee
+      crease remain as 0.10.0 refinements.
 - [x] UV/texel density: measured (64–122 px/m authored, 287–440 px/m effective fabric on the 4×
       repeat; table in `docs/3d-model-review.md`). Decision: **accept as-is** — the maps are
       neutral/runtime-tinted (not painted skin), so density controls only subtle weave/noise, and
@@ -316,8 +479,8 @@ licence-free zone only.
       `tools/three_up.py compose` renders labelled strips into `docs/screens/boards/` (caption
       sidecar per board, `rows` emits README rows). Boards committed: El Capitan day, El Capitan
       night, Joke Shop day. Tests in `tools/test_three_up.py`.
-- [x] Link each committed board from `docs/hollywood-boulevard-map.md` and
-      `docs/joke-shop-map.md`.
+- [x] Link each committed board from `docs/venues.md#hollywood-boulevard` and
+      `docs/venues.md#the-joke-shop`.
 - [ ] Use the generated concept lighting and palette as the target for the `lighting`/`lookdev`
       pass, and record the deviations that stay accepted.
 - [ ] After the pass, regenerate the venue captures and update README plus both venue documents.
@@ -345,10 +508,10 @@ and never ship a generated or downloaded image without provenance.
       log and the generated-board reference table. Linked from `docs/screens/README.md`.)
 - [x] Hollywood board: five licence-cleared photos (facade day, blade sign, 1922 elevation,
       Ovation across street, premiere staging) with a sidecar and per-image purpose, linked from
-      `docs/hollywood-boulevard-map.md` and credited in `CREDITS.md`. Cropped the foreground crowd
+      `docs/venues.md#hollywood-boulevard` and credited in `CREDITS.md`. Cropped the foreground crowd
       out of the facade shot; EXIF stripped. (`docs/screens/refs/hollywood/`.)
 - [x] Joke Shop board: three licence-cleared photos (hillside/canopy block, frontage with palms,
-      canopy signature band) with a sidecar, linked from `docs/joke-shop-map.md` and credited in
+      canopy signature band) with a sidecar, linked from `docs/venues.md#the-joke-shop` and credited in
       `CREDITS.md`. The CC BY-SA `The Comedy Store.jpg` from the old link list was deliberately not
       used; the public-domain frames cover the same evidence. (`docs/screens/refs/joke-shop/`.)
       **Removed 2026-11-03:** the committed Comedy Store photo board was replaced by the local-only
@@ -356,7 +519,7 @@ and never ship a generated or downloaded image without provenance.
 - [x] TV Studio: no separate board — the venue is the same El Capitan Entertainment Centre block as
       the Hollywood day shift, restaged for a late-night arrival. The Hollywood board covers both
       venues and the premiere-staging photo is the arrival evidence; the reuse is now stated in
-      `docs/hollywood-boulevard-map.md`, `docs/gameplay.md`, `PLAN.md` and
+      `docs/venues.md#hollywood-boulevard`, `docs/gameplay.md`, `PLAN.md` and
       `docs/development-status.md`.
 - [x] Fill the Hollywood gaps that have a clean licence: El Capitan Theatre neighbour and marquee,
       Walk of Fame terrazzo band, star close-up, and a night street-lighting context frame (cropped
@@ -425,7 +588,7 @@ still apply; the map pipeline has its own exit in M.
 - [x] ODbL audit: OpenStreetMap is used as **reference only** (hand-built geometry informed by
       OSM ways + Commons photos), so the shipped geometry is not an ODbL derived database and no
       share-alike obligation attaches. Attribution is still kept via the OSM way links in
-      `docs/hollywood-boulevard-map.md` / `docs/joke-shop-map.md`. If derived OSM geometry ever
+      `docs/venues.md#hollywood-boulevard` / `docs/venues.md#the-joke-shop`. If derived OSM geometry ever
       ships, it needs the attribution + share-alike review in a separate ADR.
 - [x] OSM extract workflow: no offline extract is required while OSM is reference-only. If the
       pipeline later imports footprints, pin an Overpass query + extract date and record it in a
@@ -524,13 +687,13 @@ Nothing is committed until the licence gate on any promoted reference and the ma
 pass. The current `_build_comedy_store_building()` stays as the fallback.*
 
 - [x] Extract the real proportions and reconcile: vision-read `tmp/research/comedy-store/` frames
-      via `tools/describe_image.py` and recorded the reconciled table in `docs/joke-shop-map.md`
+      via `tools/describe_image.py` and recorded the reconciled table in `docs/venues.md#the-joke-shop`
       §Measured proportions. Key finding: the game facade is proportionally **taller** than the
       real (3.2:1 vs ~6:1) — the main shape-language deviation; canopy pitch, blade-sign diameter,
       entrance and roofline all match closely. Curtain-bay count is crop-dependent (3–7), so 7 is
       accepted as a readable stylization.
 - [x] Rank the shape-language gaps and write the top-five fix list (measurements from the
-      proportions pass, §`docs/joke-shop-map.md`):
+      proportions pass, §`docs/venues.md#the-joke-shop`):
       1. **Facade height** — game 8.4 m vs real ~5.5–6 m (≈3.2:1 vs ~6:1 ratio). **Fixed
          2026-11-03:** `facade_height` lowered to 6.0 m; the wall now reads as a low single-storey
          hall with the canopy capping the top (vision-verified).
@@ -556,7 +719,7 @@ pass. The current `_build_comedy_store_building()` stays as the fallback.*
       top-five list.
 - [x] Gates after the rebuild: Godot 277/277 (map budget 26,828 tris / 580 meshes under 150k/700;
       navigation/collider tests pass), `tools/check_screenshots.sh` 21 good / 0 bad; the three-up
-      board and `docs/joke-shop-map.md` were refreshed.
+      board and `docs/venues.md#the-joke-shop` were refreshed.
 - [ ] Update `docs/development-status.md`, `docs/asset-tooling.md` and `CHANGELOG.md` when the
       rebuild lands; record any accepted deviations from the reference.
 
@@ -598,7 +761,7 @@ pass. The current `_build_comedy_store_building()` stays as the fallback.*
 ### M. Local map QA and exit
 
 - [x] Compare the block against screenshots/map docs and keep the stylized fallback: the three-up
-      boards (photo | concept | capture) and `docs/joke-shop-map.md` record the evidence chain;
+      boards (photo | concept | capture) and `docs/venues.md#the-joke-shop` record the evidence chain;
       the procedural `_build_comedy_store_building()` remains the fallback.
 - [x] Budget/navigation/collider + day/night captures: Godot 277/277 (Joke Shop 26,828 tris /
       580 meshes under 150k/700; navmesh, step collider and prop-collider tests pass),
@@ -606,7 +769,7 @@ pass. The current `_build_comedy_store_building()` stays as the fallback.*
 - [x] Gallery + before/after: the Joke Shop day gallery frame and three-up board were recaptured
       after each facade change; the photo/concept/capture strip is the before/after record.
 - [x] `tools/check_screenshots.sh` re-run (21/0) and the Joke Shop three-up board refreshed.
-- [x] Docs: `docs/joke-shop-map.md` (mapping, measured proportions, simplifications),
+- [x] Docs: `docs/venues.md#the-joke-shop` (mapping, measured proportions, simplifications),
       `docs/asset-tooling.md` (`describe_image.py`) and `docs/development-status.md` updated.
       `CHANGELOG.md` is untouched (unversioned track; no release).
 - [x] Exit: **one local block (the Comedy Store) is reconstructed with reference-derived facades
@@ -747,7 +910,7 @@ first; this minor contains the model/map work.
 
 - [x] Define measurable targets for routine compliance, access-decision accuracy, peaceful
       resolution, justified emergency calls and false-positive/false-negative rates.
-      (`docs/balance-acceptance.md` defines cohorts, denominators, 36 matrix cells,
+      (`docs/release-qa.md#balance-acceptance` defines cohorts, denominators, 36 matrix cells,
       seeds, thresholds and matched emergency-first comparisons. Documentation verified;
       targets are not measured results.)
 - [ ] Run scripted venue sweeps across easy/normal/hard and all four phases; compare outcomes and
@@ -842,7 +1005,7 @@ first; this minor contains the model/map work.
 ### Documentation and visual sign-off
 
 - [ ] Update `README.md`, `PLAN.md`, `docs/architecture.md`, ADRs, `docs/development-status.md`,
-      `docs/getting-started.md`, `docs/smoke-checklist.md`, `CHANGELOG.md` and this roadmap.
+      `docs/getting-started.md`, `docs/release-qa.md#manual-smoke-checklist`, `CHANGELOG.md` and this roadmap.
 - [ ] Regenerate the full screenshot gallery and realism baselines from the release-candidate
       build (not the dev tree) after content lock; run `check_screenshots.sh` and the pinned vision
       judge, recording model/spend/verdicts, and refresh the README and venue-doc images.
@@ -879,12 +1042,14 @@ variants, the four crowd-variety characters and the per-role pools — as a **pa
 - [x] Rig pose harness fixed and the weights/pose evidence captured (see the top track).
 - [x] Character work done: 12-character library, realistic face, crowd variants, per-role pools,
       24-NPC budget 6.94 ms (152,464 tris / 168 meshes).
-- [ ] Run the full QA matrix and a local release build for 0.9.7; bump `config/version`, write the
-      `CHANGELOG.md` entry, tag and publish per the Release Procedure.
+- [x] QA + local build for 0.9.7: Godot 277/277, Python 161/161, audit 49 OK, fit/proportions
+      12/12, release smoke matrix green, gallery 21/0, clean worktree build (Linux 172 MB,
+      Windows 206 MB, macOS 159 MB, Web 111 MB, HQ 266 MB), checksums verified, Linux binary
+      launches headless. Tagged `v0.9.7` (CI build/publish follows).
 
-**Exit:** a 0.9.7 patch ships the 12-character library (face realism + crowd variety) with the
-pose harness fixed; the runtime contract is unchanged. The MakeHuman body and the map rebuild are
-not in this patch.
+**Exit:** met — 0.9.7 ships the 12-character library (face realism + crowd variety) with the pose
+harness fixed; the runtime contract is unchanged. The MakeHuman body and the map rebuild are not
+in this patch (they target 0.10.0).
 
 ## Roadmap dependencies and risks
 

assets/models/blender/manifest.json

@@ -466,8 +466,8 @@
         "accessory",
         "hair"
       ],
-      "triangles": 5038,
-      "vertices": 4756
+      "triangles": 5034,
+      "vertices": 4607
     },
     "npc_coat": {
       "bounds_godot": {
@@ -507,8 +507,8 @@
         "accessory",
         "hair"
       ],
-      "triangles": 6030,
-      "vertices": 5802
+      "triangles": 6046,
+      "vertices": 5645
     },
     "npc_crowd_a": {
       "bounds_godot": {
@@ -547,8 +547,8 @@
         "accessory",
         "hair"
       ],
-      "triangles": 5200,
-      "vertices": 4734
+      "triangles": 5284,
+      "vertices": 4908
     },
     "npc_crowd_b": {
       "bounds_godot": {
@@ -587,8 +587,8 @@
         "accessory",
         "hair"
       ],
-      "triangles": 4734,
-      "vertices": 4353
+      "triangles": 4812,
+      "vertices": 4550
     },
     "npc_crowd_c": {
       "bounds_godot": {
@@ -627,8 +627,8 @@
         "accessory",
         "hair"
       ],
-      "triangles": 5674,
-      "vertices": 5440
+      "triangles": 5690,
+      "vertices": 5510
     },
     "npc_crowd_d": {
       "bounds_godot": {
@@ -667,8 +667,8 @@
         "accessory",
         "hair"
       ],
-      "triangles": 5814,
-      "vertices": 5300
+      "triangles": 5810,
+      "vertices": 5444
     },
     "npc_dress": {
       "bounds_godot": {
@@ -706,8 +706,8 @@
         "accessory",
         "hair"
       ],
-      "triangles": 5456,
-      "vertices": 5128
+      "triangles": 5540,
+      "vertices": 5073
     },
     "npc_firefighter": {
       "bounds_godot": {
@@ -747,8 +747,8 @@
         "accessory",
         "hair"
       ],
-      "triangles": 5900,
-      "vertices": 5902
+      "triangles": 5888,
+      "vertices": 5785
     },
     "npc_guard": {
       "bounds_godot": {
@@ -791,8 +791,8 @@
         "accessory",
         "hair"
       ],
-      "triangles": 5602,
-      "vertices": 5684
+      "triangles": 5670,
+      "vertices": 5671
     },
     "npc_hoodie": {
       "bounds_godot": {
@@ -832,8 +832,8 @@
         "accessory",
         "hair"
       ],
-      "triangles": 5860,
-      "vertices": 5492
+      "triangles": 5864,
+      "vertices": 5325
     },
     "npc_jacket": {
       "bounds_godot": {
@@ -873,8 +873,8 @@
         "accessory",
         "hair"
       ],
-      "triangles": 5428,
-      "vertices": 5071
+      "triangles": 5432,
+      "vertices": 5225
     },
     "npc_vest": {
       "bounds_godot": {
@@ -914,8 +914,8 @@
         "accessory",
         "hair"
       ],
-      "triangles": 5536,
-      "vertices": 5375
+      "triangles": 5532,
+      "vertices": 5195
     },
     "palm_tree": {
       "bounds_godot": {

docs/3d-model-review.md

@@ -6,7 +6,7 @@ Blender skill guidance says the targets are, the ranked candidate gaps, and the
 still need the project owner. Nothing here re-opens the accepted 0.9.4 limits by itself.
 
 Related documents: [`npc-visual-review.md`](npc-visual-review.md) (accepted 0.9.4 limits and
-before/after sheets), [`npc-proportion-audit.md`](npc-proportion-audit.md) (proportion guide),
+before/after sheets), [`npc-visual-review.md`](npc-visual-review.md#proportion-audit) (proportion guide),
 [`blender-assets.md`](blender-assets.md) (asset contract), [`asset-tooling.md`](asset-tooling.md)
 (commands).
 
@@ -24,9 +24,10 @@ severity, explicit verdict) rather than an opinion pass:
 | Props, gear, foliage | `prop-artist`, `hard-surface`, `vegetation-artist` | Silhouette read, bevel/chamfer language, collision proxies, carded foliage |
 | Look and verdict | `lookdev`, `qa-review` | Day/night beauty captures, ship / ship-with-notes / no-ship verdict |
 
-Project contract and gates stay authoritative; see `AGENTS.md` §Local Blender skills. The skills
-assume Blender MCP, which this project does not use: everything below came from the headless
-`tools/blender_assets.py` / `tools/npc_pipeline.py` pipelines plus the Godot capture harnesses.
+Project contract and gates stay authoritative; see `AGENTS.md` §Local Blender skills. Blender MCP
+is optional interactive tooling (see [`asset-tooling.md#optional-interactive-blender-mcp`](asset-tooling.md#optional-interactive-blender-mcp)); this review's evidence
+came from the headless `tools/blender_assets.py` / `tools/npc_pipeline.py` pipelines plus the
+Godot capture harnesses, so it remains reproducible without MCP.
 
 ## What was captured and measured (2026-11-03)
 
@@ -63,14 +64,14 @@ with the runtime 4× fabric repeat).
 | `npc_crowd_b` | 4,734 / 4,353 | 1.809 / +0.000 | 7 | 107–118 | 434–439 | Contract pass; crowd prototype |
 | `npc_crowd_c` | 5,674 / 5,440 | 1.824 / +0.000 | 7 | 76–83 | 317 | Contract pass; crowd prototype |
 | `npc_crowd_d` | 5,814 / 5,300 | 1.856 / +0.000 | 7 | 92–106 | 377–381 | Contract pass; crowd prototype |
-| `npc_base` (fallback) | 1,204 / 2,488 | 1.836 / +0.000 | 5 | 70.1–72.9 | 4× on fabric | Contract pass; far below its 6,000/4,000 cap |
+| `npc_base` (fallback) | 1,204 / 2,488 | 1.836 / +0.000 | 5 | 70.1–72.9 | 4× on fabric | Contract pass; compact fallback under the 16,000/16,000 cap |
 
 Blender-side `inspect` counts can differ by ±1 vertex from the glTF accessor count in `audit`
 (normal-split rounding); both are recorded and neither changes a verdict.
 
 Readings:
 
-- Every character is inside 8,000/8,000 with the farthest at 5,474 tris (68% of budget) and 5,494
+- Every character is inside 16,000/16,000 with the farthest well below the new cap and 5,494
   verts (69%), so there is headroom for targeted topology detail without a cap change.
 - Surface area tracks clothing volume: the firefighter coat is the largest body (4.28 m²) and has
   the lowest authored density; `npc_casual` is the smallest (2.44 m²) and the highest.
@@ -82,6 +83,196 @@ Readings:
 - Material counts 7–11 per character are fixed detail slots (eyes, rubber, hivis, reflective,
   leather, metal), not extra tint slots.
 
+## Baseline inventory (2026-11-04)
+
+Recorded for the Blender NPC model overhaul track: the exact starting point before the local
+part pipeline is built. `npc_base.blend` is the frozen fallback; the 12 characters are assembled
+procedurally by `tools/blender_assets.py`; the MakeHuman prototypes live under `tmp/npc-research/`
+and are not the shipped path.
+
+### `assets/models/npc/npc_base.blend` (frozen fallback)
+
+- Mesh `npc_base`: **652 verts / 642 tris**, five material slots in order
+  `pants, cloth, skin, hair, accessory`.
+- Armature: **14 bones** — `Hips, Spine, Neck, Head, ShoulderL/R, ElbowL/R, HandL/R, HipL/R, KneeL/R`
+  (the required 13 core bones plus the `Hips` root).
+- It is the compact fallback, not the prototype host; the overhaul must not absorb prototype
+  detail into it unless a separate contract decision approves it.
+
+### 12 generated character GLBs
+
+`audit` counts (glTF accessor; Blender `inspect` can differ ±1 on normal-split rounding):
+
+| Character | Tris | Verts | | Character | Tris | Verts |
+| --- | ---: | ---: | --- | --- | ---: | ---: |
+| `npc_casual` | 5,034 | 4,607 | | `npc_firefighter` | 5,888 | 5,785 |
+| `npc_jacket` | 5,432 | 5,225 | | `npc_guard` | 5,670 | 5,671 |
+| `npc_coat` | 6,046 | 5,645 | | `npc_crowd_a` | 5,284 | 4,908 |
+| `npc_vest` | 5,532 | 5,195 | | `npc_crowd_b` | 4,812 | 4,550 |
+| `npc_dress` | 5,540 | 5,073 | | `npc_crowd_c` | 5,690 | 5,510 |
+| `npc_hoodie` | 5,864 | 5,325 | | `npc_crowd_d` | 5,810 | 5,444 |
+
+All well under the 16,000/16,000 cap; the largest is `npc_coat` at 38% of the tri budget, so
+head/face/hand detail has ample headroom.
+
+### Procedural builders (current geometry locations)
+
+Coordinates are Blender metres, Z-up; face front is −Y / Godot +Z; `s` = ±1 side, `w` = build
+width scale.
+
+- **Head** — `_face` + `_shape_head_mesh`: `sphere(Head, 0.155, (0, 0, 1.635), seg=24, rings=16,
+  scale=(0.92, 1.0, 1.12))`. Forward-only sculpt (brow at z 1.695, cheek at z 1.612, jaw/chin at
+  z 1.565); recessed creases rejected because they bake as dark AO patches.
+- **Eyes** — sclera `sphere(0.019, (0.052s, −0.134, 1.664), scale=(1.25, 0.62, 0.85))`;
+  iris `sphere(0.0105, (0.052s, −0.141, 1.664), scale=(1.0, 0.55, 1.0))`; upper lid at z +0.014,
+  lower lid at z −0.012; brow box at (0.052s, −0.143, 1.699).
+- **Nose** — bridge `cyl(0.016→0.022, (0, −0.145, 1.652))`, tip `sphere(0.022, (0, −0.162, 1.615))`,
+  wings `sphere(0.012, (0.016s, −0.160, 1.606))`.
+- **Mouth** — slot `sphere(0.028, (0, −0.158, 1.583), scale=(1.0, 0.28, 0.12))`, lower lip
+  `sphere(0.012, (0, −0.156, 1.578))`.
+- **Ears** — `sphere(0.036, (0.143s, 0.008, 1.63), scale=(0.42, 1.0, 1.35))` + lobe + inner concha.
+- **Hands** — `_hands_and_shoes`: palm `sphere(0.046, (0.275·s·w, −0.012, 0.762),
+  scale=(0.80, 0.62, 0.88))`; four fingers base (…, 0.778) → tips z 0.701–0.714; thumb
+  (…, 0.778 → 0.760 → 0.738). No finger bones; open palm + `HAND_ITEM_FORWARD` only.
+
+### UV layout
+
+- Five tint slots (`skin, hair, accessory, cloth, pants`) at 256² each; fixed detail slots
+  (`eye_white`, rubber, hivis, reflective, leather, metal) are the extra material slots.
+- Authored texel density 64–122 px/m (below the background tier 128–256), fabric effective
+  287–440 px/m via the 4× repeat; runtime tint carries the look. This is a recorded note until a
+  portrait shows texture starvation.
+
+### MakeHuman prototypes (not shipped; `tmp/npc-research/makehuman/`)
+
+| File | Verts / tris | Bones | Slots | Note |
+| --- | ---: | ---: | --- | --- |
+| `makehuman_body.glb` | 19,320 / 6,444 | 0 | `skin_proto` | CC0 intake, unskinned, 1.82 m grounded |
+| `makehuman_retargeted.glb` | 7,062 / 6,444 | 14 | 5 tint | arm-down + contract rig, deltoid warp remains |
+| `makehuman_final.glb` | 6,651 / 6,407 | 14 | 8 (incl. `skin.001`, `eye_white`, `rubber`) | project head/hands/shoes swapped; duplicate `skin.001` |
+
+The "Icosphere" the inspector lists alongside these GLBs is the glTF importer's
+bone-display helper (a `pose_bone.custom_shape`), not part of the asset; `inspect_glb` already
+excludes it from measurements. The real cleanup for `makehuman_final.glb` is the duplicate
+`skin.001` material and the manual deltoid retopology.
+
+## Overhaul acceptance criteria (measurable)
+
+Defined 2026-11-04 for the local part pipeline. A prototype must pass every applicable item
+before it is rolled out to the other variants; the bar is the stylized low-poly target, not
+photorealism.
+
+### Face (one-variant prototype first)
+
+Capture `front` (yaw 0°), `three_quarter` (yaw 35°) and `profile` (yaw 90°) at **1.5 m** and
+**1.85 m** (32° FOV), matching `capture_npc_baseline.gd` (a new 1.5 m portrait capture is added
+for this). Pass conditions:
+
+- **Eyes** — sclera + iris + both lids distinct at 1.85 m; at 1.5 m the iris is a readable dark
+  dot against the white sclera, not a floating oval; no socket ring or lid seam.
+- **Mouth** — the mouth line and lower-lip volume read at both distances; no moustache-like
+  shadow from a floating dark slot.
+- **Nose** — bridge, tip and ala planes read in three-quarter and profile; no nose-wing seam or
+  inverted normal at the base.
+- **Ears** — concha depth + lobe read in profile; not a flat disc.
+- **Jaw/cheek/chin** — front and profile show a jaw transition and cheek/chin planes; no faceted
+  plane seams, inverted normals or z-fighting.
+- **Silhouette** — front/three-quarter/profile agree; face direction is unambiguous.
+- **AO** — the 256² bake stays clean: no recessed crease baking into a dark patch.
+
+### Hands (one-variant prototype first)
+
+Capture an **open palm** and a **relaxed grip** at **0.8 m** (`--view=hand` plus a new grip
+capture). Pass conditions:
+
+- **Open palm** — four fingers and a thumb read as a hand, not a mitten; at least two of the four
+  finger gaps are readable.
+- **Grip** — the palm plus curled fingers silhouette reads; no finger-through-palm clipping.
+- **Gear contact** — phone, cup, clipboard, camera, flashlight, wand and radio contact the palm
+  at 0.8 m with `HAND_ITEM_FORWARD` unchanged; no floating or hand-through-item clipping.
+
+### Contract (both, every prototype)
+
+- 16,000 triangles / 16,000 glTF vertices per character; gear stays at 1,500.
+- Optional extra bones are allowed; the required 13 core bones and their rest positions must not
+  move; the `npc_base` mesh node name and the five tint slots stay unchanged.
+
+### Measurement gates
+
+`blender_assets.py inspect`/`audit`/`fit`, `npc_proportions.py`, the 24-NPC budget, Godot + Python
+tests, the 48-frame baseline and the 96-frame pose/context review all stay authoritative; the new
+face/hands captures are the visual bar for this track.
+
+### Working-set layout
+
+Part sources and preview GLBs live under `tmp/npc-parts/<variant>/` (gitignored by the root
+`tmp/` rule); only the assembled character GLBs, AO/maps, the manifest and the review sheets are
+committed. No new committed `.blend` source tree is added without a docs/ADR decision — the
+frozen `npc_base.blend` stays the only tracked `.blend`.
+
+### Head prototype (in progress 2026-11-04)
+
+`tools/npc_parts.py build --part head_proto` is the first connected-shell attempt: a seg-48
+head sphere is displaced (not floating spheres) into eye sockets with an orbital rim, a nose
+bridge/tip/ala, upper/lower lip volumes, and extruded ears with a concha recess; the eyeballs
+stay separate. Local renders live under `tmp/npc-parts/npc_casual/head_proto_*.png`.
+
+Iteration log (vision-judged, profile view):
+
+1. Initial displacement too subtle — read as a "ball with props".
+2. Nose + ear visible in profile but the cranium still read as a "ball with a nose".
+3. Added face-plane flatten + jaw/chin taper; taper read, but "~90% sphere".
+4. Stronger flatten + nose + chin; nose now reads, jawline still dissolves into the skull.
+5. Fixed an ear-displacement sign bug (the ± side loop cancelled the helix); the ear now
+   protrudes (x ±0.155 vs the ±0.139 shell) but reads as a soft blob.
+
+Current state (prototype built, ~3/5 vision read): the nose, mouth notch, chin bump and ear bulge
+all read; the centre-profile measurement confirms the relief is objective — nose tip −0.192,
+brow −0.150, chin −0.149, jaw step −0.11, forehead −0.126→−0.078. The remaining polish (a flatter
+forehead, a defined ear helix/lobe, a jawline that steps to the neck) is folded into the §3.2
+variant comparison; the neck is part of `_skin_body`, so the standalone head always lacks it.
+
+### AI-driven head rework (2026-11-04)
+
+The head was reworked against an AI-generated target concept (front + profile, saved under
+`tmp/npc-parts/head_concept_*.png`) and judged with `describe_image.py` across several iterations.
+The displacement-on-sphere approach oscillates between "decorated egg" (too subtle) and
+"spiky wedges" (too aggressive) and settles at ~3/5 — the coarse s48 sphere cannot resolve the
+nose/lip/chin relief cleanly.
+
+The judge then compared the displacement head against the **decimated MakeHuman head**
+(extracted from `makehuman_retargeted.glb`, 2,009 verts / 1,573 tris, saved as
+`tmp/npc-parts/makehuman_head.glb`) and returned a decisive result: **ship the MakeHuman head** —
+it keeps the nose/chin/jaw landmarks at a fraction of the cost, while the procedural head's
+"clean ellipse outline instantly screams procedural sphere".
+
+**Conclusion:** the next head asset is the MakeHuman head shape (1,573 tris) plus the project's
+separate eye/mouth/brow pieces for readability, not the displacement shell. The displacement
+`_head_proto` stays local as a rejected variant.
+
+**Built (2026-11-04):** `_makehuman_head` in `blender_assets.py` imports the committed
+`assets/models/blender_src/makehuman_head.glb` (CC0, attributed in `CREDITS.md`), collapses it to
+one skin slot, bisects + caps the ragged neck, and adds the project sclera/iris/lids/brows/mouth
+at the MakeHuman landmarks. `build_character(name, head="mh")` assembles it; the result passes
+`inspect` (14 bones, skinned, no issues). The judge reads the face ~3.5/5; remaining polish is
+welding the added eye/brow pieces into the head shell and a skull-conforming hair cap.
+
+### Head subdivision comparison (2026-11-04)
+
+Three `head_proto` variants at UV-sphere segments 24/48/64 were rendered at 1.85 m and 1.5 m in
+front/three-quarter/profile and judged side by side:
+
+| Variant | Verts / tris | 1.85 m | 1.5 m | Verdict |
+| --- | ---: | --- | --- | --- |
+| s24 | 670 / 1,168 | lumpy, nose/lips melt into the chin | jagged silhouette, no mouth | reject |
+| s48 | 1,558 / 2,944 | eyes/brows/nose/lips read cleanly | features resolve cleanly | **pick** |
+| s64 | 2,470 / 4,768 | visually identical to s48 | indistinguishable from s48 | reject (wasted verts) |
+
+The chosen s48 is the `head_proto` default; the rejected s24/s64 stay local under
+`tmp/npc-parts/`. A before/after sign-off sheet (current `_face` vs s48, 1.85 m
+front/three-quarter/profile) is
+[`blender_previews/sheet_head_proto_before_after.jpg`](blender_previews/sheet_head_proto_before_after.jpg).
+
 ## Scorecard skeleton
 
 Verdicts use `qa-review` semantics: **P0** (blocker: wrong scale, broken normals, budget fail),
@@ -93,18 +284,18 @@ yet reviewed; this document is the place to fill it.
 | Character | Silhouette | Face @1.85 m | Hands/grip | Weights/pose | Cloth/hair | LOD | Verdict |
 | --- | --- | --- | --- | --- | --- | --- | --- |
 | *(pose captured 2026-11-04: see "Pose evidence" below)* | | | | | | | |
-| `npc_casual` | accept (0.9.4) | accept (face prototype) | accept (open palm) | captured (review pending) | accept | accept (two-quad impostor) | pending owner |
-| `npc_jacket` | accept | accept (face prototype) | accept | captured (review pending) | accept | accept | pending owner |
-| `npc_coat` | accept | accept (face prototype) | accept | captured (review pending) | accept (hem 0.76 stride) | accept | pending owner |
-| `npc_vest` | accept | accept (face prototype) | accept | captured (review pending) | accept | accept | pending owner |
-| `npc_dress` | accept; performer props dominate | accept (face prototype) | accept | captured (review pending) | accept | accept | pending owner |
-| `npc_hoodie` | accept (hooded criterion) | accept (lower face only) | accept | captured (review pending) | accept | accept | pending owner |
-| `npc_firefighter` | accept | accept (face prototype) | accept | captured (review pending) | accept | accept | pending owner |
-| `npc_guard` | accept | accept (face prototype) | accept | captured (review pending) | accept | accept | pending owner |
-| `npc_crowd_a` | accept | accept (face prototype) | accept | captured (review pending) | accept | accept | crowd prototype |
-| `npc_crowd_b` | accept | accept (face prototype) | accept | captured (review pending) | accept (beard) | accept | crowd prototype |
-| `npc_crowd_c` | accept | accept (face prototype) | accept | captured (review pending) | accept (coat hem) | accept | crowd prototype |
-| `npc_crowd_d` | accept | accept (face prototype) | accept | captured (review pending) | accept | accept | crowd prototype |
+| `npc_casual` | accept (0.9.4) | accept (face prototype) | accept (open palm) | fixed (wrist/hand + hip/knee) | accept | accept (two-quad impostor) | pending owner |
+| `npc_jacket` | accept | accept (face prototype) | accept | fixed (wrist/hand + hip/knee) | accept | accept | pending owner |
+| `npc_coat` | accept | accept (face prototype) | accept | fixed (wrist/hand + hip/knee) | accept (hem 0.76 stride) | accept | pending owner |
+| `npc_vest` | accept | accept (face prototype) | accept | fixed (wrist/hand + hip/knee) | accept | accept | pending owner |
+| `npc_dress` | accept; performer props dominate | accept (face prototype) | accept | fixed (wrist/hand + hip/knee) | accept | accept | pending owner |
+| `npc_hoodie` | accept (hooded criterion) | accept (lower face only) | accept | fixed (wrist/hand + hip/knee) | accept | accept | pending owner |
+| `npc_firefighter` | accept | accept (face prototype) | accept | fixed (wrist/hand + hip/knee) | accept | accept | pending owner |
+| `npc_guard` | accept | accept (face prototype) | accept | fixed (wrist/hand + hip/knee) | accept | accept | pending owner |
+| `npc_crowd_a` | accept | accept (face prototype) | accept | fixed (wrist/hand + hip/knee) | accept | accept | crowd prototype |
+| `npc_crowd_b` | accept | accept (face prototype) | accept | fixed (wrist/hand + hip/knee) | accept (beard) | accept | crowd prototype |
+| `npc_crowd_c` | accept | accept (face prototype) | accept | fixed (wrist/hand + hip/knee) | accept (coat hem) | accept | crowd prototype |
+| `npc_crowd_d` | accept | accept (face prototype) | accept | fixed (wrist/hand + hip/knee) | accept | accept | crowd prototype |
 
 ### Gear (18)
 
@@ -254,7 +445,7 @@ owner review decides.
    brow ridge, a fuller lower lip and both eyelids (upper + lower); recessed creases (nasolabial,
    temple, chin cleft) were rejected because they bake as dark AO patches. Vision-reviewed: the new
    face reads cleaner and more realistic than the old (set-in eyes, brow break, lip volume, no
-   faceting); tris 4,482 → 5,038 (still under 8,000). The other seven variants keep the old face
+   faceting); tris 4,482 → 5,038 (still under 16,000). The other seven variants keep the old face
    until this prototype is approved.
 2. **No pose/weight evidence (unknown).** Idle, walk, sit, block and turn deformation has never been
    captured as a review set, so shoulder/hip/neck collapse is unmeasured. Cheap to add and it

docs/README.md

@@ -4,9 +4,9 @@ This folder holds the project documentation, visual references and generated QA
 
 ## Current priorities
 
-1. [3D model and local map re-evaluation](../TODO.md#3d-model-and-local-map-re-evaluation) — asset scorecard and fixes, plus OpenStreetMap/3D data, licensed reference imagery, photoreal facades, AI-assisted composition and map/Gaussian-splatting evaluation.
-2. [Character development](../TODO.md#character-development) — crowd, age, build, hair and outfit variety; generator-first, with the frozen NPC contract.
-3. [0.10.0 release candidate](../TODO.md#milestone-0100--release-candidate) — versioned release hardening after the unversioned development tracks.
+1. [Blender NPC model overhaul](../TODO.md#blender-npc-model-overhaul-top-priority) — part-based head/face/hands pipeline and 16,000-budget contract.
+2. [MakeHuman and 3D model/map improvements](../TODO.md#makehuman-character-pipeline) — body intake, asset re-evaluation and local map reconstruction.
+3. [0.10.0 release candidate](../TODO.md#milestone-0100--3d-model-and-map-improvements-minor) — versioned release hardening after the unversioned development tracks.
 
 ## Start here
 
@@ -18,16 +18,13 @@ This folder holds the project documentation, visual references and generated QA
 - [`asset-tooling.md`](asset-tooling.md) — image/model pipelines and screenshot gates
 - [`../tools/README.md`](../tools/README.md) — tool inventory, categories and test runner
 - [`gameplay.md`](gameplay.md) — controls, venues and escalation
-- [`joke-shop-map.md`](joke-shop-map.md) — Sunset Strip real-site mapping
-- [`tutorial.md`](tutorial.md) — first-shift tutorial beats
+- [`venues.md`](venues.md) — Hollywood, Joke Shop and TV Studio real-site mapping
 - [`npc-visual-review.md`](npc-visual-review.md) — NPC visual baseline, acceptance criteria and ranked gaps
-- [`npc-proportion-audit.md`](npc-proportion-audit.md) — NPC proportion ratios and stylized guide results
 - [`3d-model-review.md`](3d-model-review.md) — 3D model re-evaluation: measurements, scorecard and ranked gaps
 - [`development-status.md`](development-status.md) — implemented features, current gaps and active planning
 - [`accessibility.md`](accessibility.md) — accessibility statement and known gaps
 - [`known-limitations.md`](known-limitations.md) — release-candidate blockers and accepted limits
-- [`smoke-checklist.md`](smoke-checklist.md) — manual verification
-- [`balance-acceptance.md`](balance-acceptance.md) — release-candidate balance targets and evidence protocol
+- [`release-qa.md`](release-qa.md) — manual smoke checklist and balance-acceptance protocol
 - [`../CREDITS.md`](../CREDITS.md) — credits and asset provenance
 - [`../PRIVACY.md`](../PRIVACY.md) — privacy note
 - [`ui-copy.md`](ui-copy.md) — screen, copy and button inventory
@@ -39,7 +36,7 @@ This folder holds the project documentation, visual references and generated QA
 - [`screens/README.md`](screens/README.md) — concepts, designs, screenshots and realism runs
 - [`blender_previews/README.md`](blender_previews/README.md) — character/gear/prop previews
 - [`screenshots/README.md`](screenshots/README.md) — committed game gallery
-- [`screen-design-report.md`](screen-design-report.md) — latest screen-design judge result
+- [`ui-copy.md`](ui-copy.md#screen-design-judge-report) — screen/button inventory and latest judge result
 
 ## Quick preview
 

docs/accessibility.md

@@ -28,5 +28,5 @@ Known gaps:
   review is still a 0.10.0 release-review item.
 
 Test evidence and the manual checklist live in
-[`smoke-checklist.md`](smoke-checklist.md); settings and save behaviour are
+[`release-qa.md`](release-qa.md#manual-smoke-checklist); settings and save behaviour are
 documented in [`getting-started.md`](getting-started.md).

docs/adr/0015-npc-model-variety-sourcing.md

@@ -70,3 +70,14 @@ measured. None was a drop-in; the full results are in
   polygon count, no rig in the base mesh and a separate authoring dependency.
 - **Use Mixamo or Ready Player Me.** Rejected: service terms are not a simple
   free/open-source redistribution basis for shipped meshes.
+
+## Amendment 2026-11-04
+
+- The character budget is raised to **16,000 triangles / 16,000 glTF vertices** per character.
+  The required 13 core bones remain; optional extra bones (fingers, face, toes) are allowed if
+  they do not move the core rest positions. The low-poly fallback remains the fallback, not a
+  second contract.
+- MakeHuman is now an active local development pipeline (body retarget plus project-owned
+  head/hands), while the procedural library remains the shipped path and CI fallback.
+- Blender MCP is optional interactive tooling only; it is not a build, CI, test or runtime
+  dependency. Setup is in [`docs/asset-tooling.md#optional-interactive-blender-mcp`](../asset-tooling.md#optional-interactive-blender-mcp).

docs/architecture.md

@@ -37,7 +37,7 @@ This document follows the structure of the arc42 architecture documentation temp
 - **MINOR** — new venues, NPC archetypes, systems, or features that are backward compatible.
 - **PATCH** — bug fixes and small polish that do not change behavior.
 
-The single source of truth for the version is `config/version` in `project.godot` (currently `0.10.0-rc.1`). Each release is tagged in git as `v<version>` (e.g. `v0.6.0`). The `0.x` series is pre-stable, so MINOR bumps may introduce breaking changes while the prototype is still stabilizing. `tools/build_releases.sh` and `tools/publish_release.sh` read the version from `project.godot`, so bumping it there is the only required step before a release. The full bump checklist lives in [`RELEASING.md`](RELEASING.md).
+The single source of truth for the version is `config/version` in `project.godot` (currently `0.9.8`). Each release is tagged in git as `v<version>` (e.g. `v0.6.0`). The `0.x` series is pre-stable, so MINOR bumps may introduce breaking changes while the prototype is still stabilizing. `tools/build_releases.sh` and `tools/publish_release.sh` read the version from `project.godot`, so bumping it there is the only required step before a release. The full bump checklist lives in [`RELEASING.md`](RELEASING.md).
 
 ## 3. Context and Scope
 
@@ -128,6 +128,82 @@ Contracts that keep the pipeline replaceable:
 - UI/scene art is loaded through `UiArt` with a null/neutral fallback; composed images live in `assets/images/`, not in the docs reference tree (ADR-0014).
 - CI stays offline: only committed `.glb`/`.png`/`.tres` and Godot are needed; optional AI/Blender steps are reproducible development tools.
 
+### Character and gear asset contract
+
+The runtime NPC contract is intentionally narrow. It is enforced by
+`tools/blender_assets.py audit`, the GLB `inspect` path and the GDScript tests:
+
+| Contract | Rule |
+| --- | --- |
+| Mesh node | `npc_base`, skinned under an armature imported as `Skeleton3D`. |
+| Core bones | `Head`, `HipL/R`, `KneeL/R`, `ShoulderL/R`, `ElbowL/R`, `HandL/R`, `Spine`, `Neck` at the frozen rest positions. Optional extra bones (fingers, face, toes) are allowed if they do not move the core rest positions or break `NpcAvatar` proxies. |
+| Tint slots | `skin`, `cloth`, `pants`, `accessory`, `hair`; fixed detail materials keep their authored colours. |
+| Orientation | Blender −Y / Godot +Z front, feet grounded near `y = 0`, metre scale. |
+| Budget | 16,000 triangles / 16,000 glTF vertices per character; 1,500 per gear piece; 4,000 per prop. The low-poly `npc_base` remains a fallback, not a second contract. |
+| Textures | 256² albedo + normal + packed ORM per slot; cloth/pants use the 4× `NPC_FABRIC_UV_SCALE` and skip per-character baked AO, while skin/hair/gear keep AO. |
+| Gear attach | Authored in attach-point space: head `Rig/Head` (0, 1.62, 0), back (0, 1.10, 0), chest (0, 1.30, 0), hand (±0.27, 0.78, 0.02); grip 5 cm below the origin. `GEAR_OFFSETS` and `HAND_ITEM_FORWARD` are runtime fit corrections, not authored-geometry changes. |
+| Fallback chain | Library variant → `npc_base.glb` → procedural `NpcAvatar` mesh. Committed GLBs and maps must keep CI offline and Blender-free. |
+
+Asset types and their consumers:
+
+- Library characters, gear and props: `assets/models/blender/**`, generated by
+  `tools/blender_assets.py`; loaded by `NpcAvatar`/`WorldBuilder` with
+  generated/procedural fallbacks.
+- Frozen base: `assets/models/generated/npc_base.glb`, generated by
+  `tools/npc_pipeline.py`; the procedural avatar remains the last-resort path.
+- Maps: `assets/textures/npc/*_{albedo,normal,orm}.png` and baked AO maps; the
+  mesh budgets and material wiring are checked by `audit`/`fit`/`texels` and the
+  headless suite.
+- Editable `.blend` sources are development-only; only exported GLBs, AO/maps,
+  manifests and committed review sheets are runtime/repository assets.
+
+### Venue implementation contract
+
+The three venues are authored by `WorldBuilder.VENUE_SPECS` and rebuilt through
+the `World` container when the venue changes; the guard, UI and checkpoint state
+survive. Venue data is content, while the following runtime rules are fixed:
+
+| Venue | Real reference | Game implementation | Budget |
+| --- | --- | --- | --- |
+| Hollywood Boulevard | 6840 Hollywood Blvd / 1921 Masonic Temple | Six-column Masonic facade, eight steps, Walk of Fame, boulevard, Ovation arcade and neighbours | 58,884 tris / 409 meshes |
+| The Joke Shop | Fictional stand-in for 8433 Sunset Blvd | 27 m black hall, signature canopy, circular blade sign, red curtain bays, west entrance, hillside and neighbours | 25,828 tris / 518 meshes |
+| Late Night TV Studio | Same El Capitan block as Hollywood | Reuses the Masonic facade and steps with bulb canopy, car, barriers and studio-arrival staging | shares the Hollywood block; TV spec is a 30.0 m variant |
+
+Venue rules:
+
+- Coordinates are Godot metres; the guard's front is +Z. `VENUE_SPECS` owns
+  facade dimensions, street/nav bounds, guard spawn, feature flags and prop
+  placements; tests enforce the map budgets.
+- Collision and navigation remain mesh-based. Props that block walking need a
+  `StaticBody3D` plus `NavigationObstacle3D`; the marquee, handrail, lantern and
+  door are documented non-blocking exceptions.
+- Day/night is a phase offset on one geometry/scenario, not a second baked map.
+  The venue menu's Night row starts in `LATE` while the checkpoint stores the
+  offset.
+- Real-site references are evidence for shape/materials, not shipped assets.
+  Licensed boards live under `docs/screens/refs/` with sidecars; local-only
+  research stays in `tmp/research/` and is never committed.
+- The stylized geometry remains the runtime fallback if a future data-backed
+  block or facade kit fails budget, navigation, visual or provenance gates.
+
+### Persistence and save contract
+
+Persistence is local-only under Godot's `user://` directory. The architecture
+owns the schema; operational locations and reset/rollback steps live in
+[`getting-started.md`](getting-started.md#save-data-and-migration).
+
+| File | Contents | Compatibility |
+| --- | --- | --- |
+| `settings.json` | Camera/HUD/bindings/difficulty/audio/accessibility/tutorial flags | Schema-less compatible growth; missing keys merge from `Save.DEFAULT_SETTINGS`. |
+| `campaign.json` | Campaign index, completed venues, difficulty, shift number, last grade | Missing fields fall back to safe campaign defaults. |
+| `shift_results.json` | Completed-shift review history (array) | Append-only; unknown fields are ignored by readers. |
+| `shift_state.json` | Resumable checkpoint: version `1`, venue, guard/door/flashlight/body-camera state, coordinator snapshot, NPC rows | Versioned; unknown/missing state falls back rather than blocking boot. |
+
+Writes go to a `.tmp` file and are renamed after the complete JSON is written.
+Corrupt or partial files are ignored on load; a failed replace leaves the prior
+valid file intact. The checkpoint deliberately excludes the tutorial overlay and
+transient input state.
+
 ### Character development tooling
 
 Characters have two authored sources and one procedural fallback. The eight-variant
@@ -141,10 +217,10 @@ GLBs and maps.
 
 | Tool | Role | Committed artifact | Verification gate |
 | --- | --- | --- | --- |
-| `tools/npc_pipeline.py` | Builds the skinned base avatar, five-slot material maps, palette and AI-fabric preparation (`prepare`/`palette`) | `npc_base.glb`, `assets/textures/npc/*_{albedo,normal,orm}.png`, `palette.json` | `audit_glb` against the frozen 6,000-triangle / 4,000-vertex base contract |
-| `tools/blender_assets.py` | Builds/renders the library: 8 characters, 18 gear pieces, 20 props, plus `manifest.json`; stdlib `audit`/`fit`/`sheet`/`list` | `assets/models/blender/{npc,npc_gear,props}/*.glb` | Library cap 8,000 tris / 8,000 verts per character, 1,500 per gear, 4,000 per prop; grounding, UV, degenerate-triangle, attach-fit and manifest coverage checks |
+| `tools/npc_pipeline.py` | Builds the skinned base avatar, five-slot material maps, palette and AI-fabric preparation (`prepare`/`palette`) | `npc_base.glb`, `assets/textures/npc/*_{albedo,normal,orm}.png`, `palette.json` | `audit_glb` against the 16,000-triangle / 16,000-vertex base contract (13 core bones required; extras allowed) |
+| `tools/blender_assets.py` | Builds/renders the library: 8 characters, 18 gear pieces, 20 props, plus `manifest.json`; stdlib `audit`/`fit`/`sheet`/`list` | `assets/models/blender/{npc,npc_gear,props}/*.glb` | Character cap 16,000 tris / 16,000 verts, 1,500 per gear, 4,000 per prop; grounding, UV, degenerate-triangle, attach-fit and manifest coverage checks |
 | `tools/bake_ao.py` | Bakes per-asset AO maps | `<asset>_ao.png` (256²) | Wired through `Materials.apply_ao()`/`SurfaceMaterials`; cloth/pants opt out (see below) |
-| `tools/npc_proportions.py` | Measures exported GLB rest pose (height, head, shoulders, hips, torso, limbs, feet) against the stylized guide | report / JSON in `docs/npc-proportion-audit.md` | All eight variants must stay inside the guide after a body change |
+| `tools/npc_proportions.py` | Measures exported GLB rest pose (height, head, shoulders, hips, torso, limbs, feet) against the stylized guide | report / JSON in `docs/npc-visual-review.md#proportion-audit` | All eight variants must stay inside the guide after a body change |
 | `tools/npc_baseline.py` | Assembles neutral-baseline sheets and before/after comparisons | `docs/blender_previews/sheet_npc_baseline*.jpg` | Human review against `docs/npc-visual-review.md` |
 | `src/test/capture_npc_baseline.gd` | Fixed-camera studio baseline, 8 variants × 6 views | local `tmp/` frames | Neutral silhouette/face/gear review |
 | `src/test/capture_npc_review.gd` | Final-context gate: 8 variants × 2 venues × day/night × 3 distances = 96 frames, crowd hidden, review-only `character_override` for the guard | local `tmp/` frames | Pre-build acceptance gate for gear fit and venue lighting |
@@ -162,14 +238,14 @@ Runtime contracts that must survive any character change:
 - Cloth/pants use `Materials.NPC_FABRIC_UV_SCALE` (4×) and skip the baked per-character AO;
   skin/hair/gear keep AO. Do not reintroduce the blotchy cloth AO.
 - `apply_lod()` swaps to an impostor at 26 m; the 24-NPC budget smoke (6.94 ms, 168 meshes,
-  131,616 triangles) is the performance gate. Changing either triangle cap requires
+  152,464 triangles) is the performance gate. Changing either triangle cap requires
   re-measuring that smoke and the Web/Compatibility path.
 - Rebuild only the assets whose geometry changed (Blender GLB export is byte-nondeterministic),
   then run `godot --headless --path . --import`; never commit a no-op full rebuild.
 
 Evidence and detailed contracts live in [`blender-assets.md`](blender-assets.md),
 [`npc-visual-review.md`](npc-visual-review.md) and
-[`npc-proportion-audit.md`](npc-proportion-audit.md); command-level usage is in
+[`npc-visual-review.md#proportion-audit`](npc-visual-review.md#proportion-audit); command-level usage is in
 [`asset-tooling.md`](asset-tooling.md).
 
 ### Local map development tooling (planned)
@@ -359,17 +435,21 @@ architecture document.
 | Document | Canonical role | Relationship to this architecture |
 | --- | --- | --- |
 | [`PLAN.md`](../PLAN.md) | Product/design intent, pillars, venues and success criteria | Design source; architecture realizes it |
-| [`docs/gameplay.md`](gameplay.md) | Playable loop, escalation, venue mechanics | Runtime/behavioral view |
+| [`docs/gameplay.md`](gameplay.md) | Playable loop, escalation, tutorial, venue mechanics | Runtime/behavioral view |
+| [`docs/venues.md`](venues.md) | Real-site evidence, mapping decisions and deliberate simplifications | Runtime venues' evidence companion to §5 |
 | [`docs/architecture.md`](architecture.md) | System boundaries, data flow, constraints, deployment, cross-cutting decisions, quality risks | Single architecture source |
 | [`docs/adr/`](adr/) | Immutable decision records with context and consequences | Decision history linked from §9 |
-| [`docs/asset-tooling.md`](asset-tooling.md) | Build/audit/capture commands and pipeline usage | Operational appendix to the pipeline section |
-| [`docs/blender-assets.md`](blender-assets.md) | Blender character/gear/prop contracts and attach points | Detailed asset contract appendix |
-| [`docs/npc-visual-review.md`](npc-visual-review.md) | NPC baseline views, acceptance criteria and ranked visual gaps | Visual-QA appendix to the character tooling section |
-| [`docs/npc-proportion-audit.md`](npc-proportion-audit.md) | Measured proportions against the stylized guide | Measurement appendix to the character tooling section |
-| [`docs/npc-model-sourcing.md`](npc-model-sourcing.md) | Character-source evaluation, licence rules and the character-development plan | Supports the character tooling section and ADR-0015 |
+| [`docs/asset-tooling.md`](asset-tooling.md) | Build/audit/capture commands, optional Blender MCP and pipeline usage | Operational appendix to the pipeline section |
+| [`docs/blender-assets.md`](blender-assets.md) | Blender library art direction, roles, layout and checks | Operational asset appendix; contract lives here in §5 |
+| [`docs/npc-visual-review.md`](npc-visual-review.md) | NPC baseline views, acceptance criteria, visual gaps and proportion audit | Visual-QA appendix to the character tooling section |
+| [`docs/3d-model-review.md`](3d-model-review.md) | Scorecard, measurements and ranked asset gaps | Working review companion to §5 |
+| [`docs/npc-model-sourcing.md`](npc-model-sourcing.md) | Character-source evaluation and licence/prototype outcome | Supports the character tooling section and ADR-0015 |
 | [`docs/getting-started.md`](getting-started.md) | Setup, commands, controls | Developer onboarding |
 | [`docs/RELEASING.md`](RELEASING.md) | Release checklist and CI/publishing steps | Deployment appendix to §7 |
-| [`docs/smoke-checklist.md`](smoke-checklist.md) | Manual verification script | QA appendix to §10 |
+| [`docs/release-qa.md`](release-qa.md) | Manual smoke checklist and balance protocol | QA appendix to §10 |
+| [`docs/accessibility.md`](accessibility.md) | Accessibility features, statement and known gaps | Player-facing quality statement |
+| [`docs/known-limitations.md`](known-limitations.md) | Release blockers and accepted limitations | Player/release-facing risk statement |
+| [`docs/ui-copy.md`](ui-copy.md) | Screen/button inventory, copy audit and screen-judge report | Presentation appendix |
 | [`docs/development-status.md`](development-status.md) | Implemented features and current gaps | Status companion to the roadmap |
 | [`TODO.md`](../TODO.md) | Priority-ordered active tasks, unversioned development tracks and versioned roadmap | Planning source; no architecture duplication |
 | [`CHANGELOG.md`](../CHANGELOG.md) | User-facing release history | Release/version companion |

docs/asset-tooling.md

@@ -189,7 +189,7 @@ Caveats:
 `adapt` is the mechanical first half of an external-mesh intake (MakeHuman,
 MPFB, downloaded GLB): import, apply transforms, ground the feet, weld seam
 splits, decimate to the character budget, and export a GLB. It does **not** map
-the five tint slots or rebuild the 13-bone `npc_base` armature — those stay a
+the five tint slots or rebuild the 13-core-bone `npc_base` armature (optional extra bones are allowed) — those stay a
 manual `retopology`/`rigging` step with a recorded second-rig contract if the
 source rig cannot be retargeted:
 
@@ -198,8 +198,8 @@ flatpak run org.blender.Blender --background \
   --python "$PWD/tools/blender_assets.py" -- adapt \
   --file "$PWD/tmp/npc-research/makehuman_base.glb" \
   --out "$PWD/tmp/npc-research/makehuman_adapted.glb" \
-  --target-tris 8000
-# prints: adapted makehuman_adapted.glb: 36972 -> 8000 tris (bones=N, meshes=1)
+  --target-tris 16000
+# prints: adapted makehuman_adapted.glb: 36972 -> 16000 tris (bones=N, meshes=1)
 ```
 
 Run `inspect` on the adapted GLB before and after, and keep the procedural
@@ -300,24 +300,11 @@ python3 tools/blender_assets.py texels --only npc_coat
 
 ## Local map development (planned)
 
-The local map workstreams (**H–M**) in [`TODO.md`](../TODO.md#3d-model-re-evaluation)
-are not implemented yet; there are no map-generation commands to run. The planned
-pipeline will evaluate:
-
-- offline OpenStreetMap extracts for footprints and licence-compatible 3D building
-  massing (OSM Buildings, Overture, CityGML/LOD1–2);
-- downloaded reference imagery from Wikimedia Commons, own/team photography or
-  other clearly licensed sources, with author/licence/attribution and privacy
-  redaction recorded per set;
-- AI-assisted composition boards for palette, facade rhythm and material study,
-  with model/prompt/output provenance and human acceptance;
-- Gaussian splatting as a development-only capture/reference/texture/proxy tool,
-  version-pinned offline and outside CI, until an ADR proves runtime safety.
-
-No online map/photo/splat service is a build or play dependency. Committed map
-assets will need provenance sidecars, ODbL/photo-licence review and the same
-`WorldBuilder` venue-budget/navigation/collider gates as the current stylized
-geometry. The detailed task plan and exit criteria live in `TODO.md`.
+The local map workstreams (H–M) in [`TODO.md`](../TODO.md#3d-model-re-evaluation) are
+planned, not implemented; there are no map-generation commands yet. The runtime
+contract, provenance rules, budget/navigation gates and fallback are in
+[`architecture.md#venue-implementation-contract`](architecture.md#venue-implementation-contract).
+The detailed pipeline/task list lives in `TODO.md`.
 
 ## Confirmed game assets
 
@@ -343,6 +330,162 @@ python3 tools/model_pipeline.py audit
 python3 tools/npc_pipeline.py audit
 ```
 
+## Optional interactive Blender MCP
+
+Status: **optional interactive tooling, not a build dependency.** Blender MCP is
+useful for exploring a local part scene, moving the viewport and iterating on a
+head/hand mesh without a manual UI walkthrough. The authoritative asset
+pipeline remains the headless CLI plus `audit`/`fit`/`inspect`; CI, tests and
+release builds must continue to work with no Blender process and no MCP server.
+
+This project does not vend the third-party addon or pin a runtime MCP
+dependency. Install it outside the repository and keep generated scenes under
+`tmp/`.
+
+### What it adds
+
+With Blender MCP connected, an agent can:
+
+- query the current scene and object data;
+- run small `bpy` snippets through the MCP bridge;
+- capture a viewport screenshot for visual checks;
+- inspect or modify a local part scene before exporting a GLB.
+
+It does **not** replace:
+
+- `python3 tools/blender_assets.py audit/fit/inspect`;
+- `python3 tools/npc_proportions.py`;
+- the Godot capture and smoke gates;
+- the project's licence/provenance review.
+
+### Prerequisites
+
+- Blender 5.2 LTS, installed as the `org.blender.Blender` flatpak (the project
+  standard).
+- An MCP-capable client.
+- The upstream [BlenderMCP addon](https://github.com/ahujasid/blender-mcp)
+  (`addon.py`) and its MCP server.
+- `uv`/`uvx` if you use the server's `uvx blender-mcp` launcher; a local install
+  of the server package is equally valid.
+
+Check the upstream README for the current package/addon version and any command
+changes before installing. Do not copy the addon into this repository.
+
+### Setup
+
+#### 1. Install the Blender addon
+
+1. Download or clone the upstream BlenderMCP project.
+2. In Blender: **Edit → Preferences → Add-ons → Install from Disk**, select
+   `addon.py` from that checkout.
+3. Enable **Interface: Blender MCP**.
+4. Open the 3D View sidebar (N panel), find the **BlenderMCP** tab, and click
+   **Connect to MCP server**. The default server listens on
+   `localhost:9876`.
+
+The addon must be running inside the Blender process that has the scene open.
+Starting a second Blender instance does not connect the first one.
+
+#### 2. Configure the MCP client
+
+For Pi, add the server at user scope so it is not committed into the project:
+
+```bash
+pi mcp add blender -- uvx blender-mcp
+pi mcp list
+```
+
+Then start/reload Pi and use `/mcp` to inspect the connection. Other clients
+use their normal MCP server configuration. A generic JSON example:
+
+```json
+{
+  "mcpServers": {
+    "blender": {
+      "command": "uvx",
+      "args": ["blender-mcp"]
+    }
+  }
+}
+```
+
+For a client with a different config schema, use the equivalent server command
+and keep the server name `blender`. Restart/reload the client after adding it,
+then request the tool list and run a harmless `get_scene_info` before editing.
+
+#### 3. Connect through the flatpak
+
+Start Blender through the project's normal flatpak command, open the local part
+scene, and connect from the sidebar. If the client cannot reach the addon:
+
+- confirm the addon panel says connected;
+- confirm the client is launching the MCP server, not just a shell;
+- check port `9876` is not occupied;
+- if the flatpak sandbox is blocking localhost networking, grant network
+  permission only for this interactive use, for example:
+  `flatpak override --user --share=network org.blender.Blender`
+  (review the permission change afterwards; do not add it to CI or build
+  scripts).
+- restart both the MCP client and Blender after changing the addon or config.
+
+### Recommended part-workflow
+
+The headless part pipeline is `tools/npc_parts.py` (see
+[`blender-assets.md#local-part-pipeline`](blender-assets.md#local-part-pipeline)). It builds,
+extracts, assembles, inspects and sheets the reusable head/face and hand parts and reuses the
+`blender_assets.py` builders, so there is no second face/hand implementation. The MCP steps below
+remain optional interactive exploration; the headless commands stay the build and audit path.
+
+1. Create a local scene, for example
+   `tmp/npc-parts/npc_casual/head.blend`, or open a copy of an exported part GLB.
+   Never save over the tracked `assets/models/npc/npc_base.blend`.
+2. Ask the MCP client for `get_scene_info`, then inspect the object/bone/mesh
+   names it reports.
+3. Use `execute_blender_code` for small, reversible edits. Prefer adding a new
+   object or modifier over deleting existing geometry; keep a backup copy.
+4. Use `get_viewport_screenshot` after camera/material changes to check the
+   head/face/hand before exporting.
+5. Export a **local** GLB under `tmp/npc-parts/`, not directly into
+   `assets/models/`.
+6. Run the normal gates on the exported file:
+
+   ```bash
+   flatpak run org.blender.Blender --background \
+     --python "$PWD/tools/blender_assets.py" -- \
+     inspect --file "$PWD/tmp/npc-parts/head.glb" --category npc --json
+   python3 tools/blender_assets.py audit
+   python3 tools/blender_assets.py fit
+   python3 tools/npc_proportions.py report
+   ```
+
+7. Only after the part is reviewed and the contract passes should it be
+   assembled into a character and rebuilt through the headless pipeline.
+
+### Safety and project rules
+
+- MCP is **not** part of `project.godot`, the build, CI, tests, release packages
+  or runtime.
+- Do not commit `.blend` part scenes, MCP configuration, API keys or generated
+  previews. The working set stays in `tmp/`; a part GLB is not a shipped asset.
+- Do not use MCP to bypass the contract, budgets, AO/UV rules or licence gate.
+- The 13 core bones must remain at their rest positions; extra optional bones
+  are allowed only if `NpcAvatar` and the audit/tests still pass.
+- Prefer scripted headless changes for reproducible work; MCP is for the
+  interactive exploration and review that is awkward in a one-shot script.
+- If MCP is unavailable, use the headless CLI and document the manual step; never
+  make the project depend on MCP being present.
+
+### Troubleshooting
+
+| Symptom | Check |
+| --- | --- |
+| Client cannot find `blender` | MCP client config path/schema; restart client; confirm server command exists |
+| `Connection refused` | Addon **Connect to MCP server** pressed; Blender still running; port 9876 |
+| Tools return stale scene data | Refresh scene/object query after edits; restart the connection if needed |
+| Flatpak cannot reach localhost | Check flatpak network permission; grant only for interactive use |
+| Changes look wrong in export | Re-import the GLB with `inspect`; check transforms, scale, UVs and materials |
+| Contract audit fails | Fix the mesh/bones first; do not edit the audit expectations around a broken asset |
+
 ## Realism pass: scene concepts, skylines and textures
 
 The skyline, surface tiles and phase lighting were rebuilt against AI concept frames. The
@@ -406,7 +549,7 @@ contract.
 
 `tools/npc_proportions.py` checks the eight character GLBs against the shared
 height/head/shoulder/hip/torso/leg/arm/foot guide; the current results are in
-[`npc-proportion-audit.md`](npc-proportion-audit.md). It reads the exported GLBs
+[`npc-visual-review.md`](npc-visual-review.md#proportion-audit). It reads the exported GLBs
 and does not require Blender.
 
 `capture_npc_pose.gd` is the pose/deformation harness for the 3D re-evaluation: idle,

docs/blender-assets.md

@@ -35,6 +35,60 @@ captures in `docs/screenshots/`.
   doors, stair handrails and a dark sedan. Today's in-game props are primitive
   boxes, and the trees are cones.
 
+## Frozen fallback boundary
+
+`assets/models/npc/npc_base.blend` is the tracked, frozen plain-primitive
+fallback. Prototype head/face/hand detail from the local part pipeline must not
+be saved into it; a separate contract decision (ADR or owner sign-off) is
+required before any prototype detail is absorbed. Working scenes live under
+`tmp/npc-parts/` (gitignored) and are exported as local GLBs for review, never
+directly over the tracked `.blend`. The same rule already appears in
+[`asset-tooling.md#recommended-part-workflow`](asset-tooling.md#recommended-part-workflow).
+
+## Local part pipeline
+
+The overhaul uses `tools/npc_parts.py` to build, extract, assemble, inspect and sheet the
+reusable head/face and hand parts before they are rolled into the 12 characters. It reuses the
+`blender_assets.py` builders (no second face/hand implementation) and stays local-only/headless.
+Part sources and preview GLBs live under `tmp/npc-parts/<variant>/`; they are **not shipped
+assets** — only the assembled character GLBs, AO/maps, the manifest and the review sheets are
+committed.
+
+```bash
+# Build one part fresh from the current builders (head|face|hand_l|hand_r)
+flatpak run org.blender.Blender --background \
+  --python "$PWD/tools/npc_parts.py" -- build --part face --variant npc_casual \
+  --out "$PWD/tmp/npc-parts/npc_casual/face.glb"
+# Pull the current shipped head/hands out of the built character GLB (comparison)
+flatpak run org.blender.Blender --background \
+  --python "$PWD/tools/npc_parts.py" -- extract --part hand_l --variant npc_casual \
+  --out "$PWD/tmp/npc-parts/npc_casual/hand_l.glb"
+# Assemble a variant (currently rebuilds the procedural character)
+flatpak run org.blender.Blender --background \
+  --python "$PWD/tools/npc_parts.py" -- assemble --variant npc_casual \
+  --out "$PWD/tmp/npc-parts/npc_casual/assembled.glb"
+# Inspect a part or assembled GLB (Blender import view)
+flatpak run org.blender.Blender --background \
+  --python "$PWD/tools/npc_parts.py" -- inspect --file "$PWD/tmp/npc-parts/npc_casual/face.glb"
+# Contact sheet / before-after comparison (outside Blender; stdlib + Pillow)
+python3 tools/npc_parts.py sheet --dir tmp/npc-parts/npc_casual \
+  --out docs/blender_previews/sheet_parts.jpg
+python3 tools/npc_parts.py compare --before DIR --after DIR --out sheet.jpg
+```
+
+`build --part head` produces the bare head shell; `build --part face` is the shell plus
+nose/eyes/mouth/ears; `build --part hand_l|hand_r` are the left/right hand geometry. `extract`
+pulls the current shipped geometry out of the built character GLB by vertex group (`Head` for
+`head`/`face`, `HandL`/`HandR` for the hands), so it shows what is actually shipped rather than
+what the builders would emit fresh. The assembled GLB must still pass
+`blender_assets.py inspect`/`audit`/`fit` before any part is accepted.
+
+## Optional MCP
+
+Blender MCP can be used for interactive head/face/hand part exploration, but it
+is not required. The headless commands below remain the build and audit path;
+see [`asset-tooling.md#optional-interactive-blender-mcp`](asset-tooling.md#optional-interactive-blender-mcp) for installation, connection and safety.
+
 ## Running it
 
 ```bash
@@ -85,35 +139,10 @@ render about 2.5 min.
 
 ## Characters
 
-All eight use the `npc_base` contract, so each one can replace
-`npc_base.glb` without code changes:
-
-- mesh node `npc_base` under an armature that imports as `Skeleton3D`
-- bones `Head`, `HipL/R`, `KneeL/R`, `ShoulderL/R`, `ElbowL/R`, `HandL/R`
-  (plus `Hips`, `Spine`, `Neck`) at the **same rest positions as `npc_base`**.
-  `test_character_joints_line_up_with_npc_base` checks this within 1 cm, so the
-  animation proxies in `_build_skinned_body()` stay valid.
-- material slots `skin`, `cloth`, `pants`, `accessory`, `hair` carry the same
-  neutral `assets/textures/npc/<slot>_{albedo,normal}.png` maps at 256², so
-  `Materials.npc_slot()` tints them the same way it tints `npc_base`. Cloth and
-  pants repeat the weave 4× (`NPC_FABRIC_UV_SCALE`) and intentionally skip the
-  per-character baked AO; skin, hair and fixed gear keep it.
-- budget ≤ **8,000 triangles and ≤ 8,000 glTF vertices** for the eight library
-  variants (vertex count after seam splits; `CHAR_MAX_TRIS`/`CHAR_MAX_VERTS` in
-  `tools/blender_assets.py`, raised from 6,000/5,000 on 2026-11-02). The frozen
-  `npc_base` fallback keeps its original 6,000/4,000 contract. The current range
-  is 4,482–5,474 triangles and 4,260–5,494 vertices, leaving room for the
-  remaining grip and clothing detail.
-
-Construction: the torso and limbs are one continuous Skin-modifier mesh,
-subdivided twice, decimated to 26 % with X symmetry, and cut at the waist, cuffs,
-sleeves and neck so the material borders are clean edge loops. The head is a
-separate part carrying the face detail: brow ridge, sclera/iris/upper-lid per eye,
-cheekbones, a nose with a bridge and tip, ears with lobes, and upper and lower
-lips. Hands have four fingers plus a thumb; sleeves end in a cuff ring.
-Hair, shoes and clothing layers are separate parts. Weights come from distance to
-the bone segments, limited by body region. Parts that should stay rigid (head,
-hands, shoes) get a single bone.
+All library variants share the [character and gear asset contract](architecture.md#character-and-gear-asset-contract):
+`npc_base` mesh node, required 13 core bones (optional extras allowed), five
+tint slots, +Z visual front, 16,000/16,000 character budget and the same 256²
+slot-map/AO rules. Role selection and look notes:
 
 | Character | `layer_for()` / look | Suggested roles | Preview gear |
 | --- | --- | --- | --- |
@@ -140,22 +169,8 @@ the role's `TYPE_COLORS`.
 
 ## Gear attach points
 
-Gear is authored in attach-point space, so the origin of each GLB is its
-attach point:
-
-| Attach | Godot parent / position | Gear |
-| --- | --- | --- |
-| `head` | `Rig/Head` marker (0, 1.62, 0) | cap, hood, sunglasses, firefighter_helmet |
-| `back` | `Rig` at (0, 1.10, 0), spine centre; items sit behind the body (Blender +Y = Godot −Z) | backpack, shoulder_bag, scba_tank |
-| `chest` | `Rig` at (0, 1.30, 0), sternum | lanyard |
-| `hand` | Hand proxy (±0.27, 0.78, 0.02); grip 5 cm below the origin | phone, cup, clipboard, umbrella, camera, protest_sign, flashlight, wand, radio |
-
-The character previews in `sheet_npc.jpg` are built by importing the gear at
-exactly these points, which gives a quick visual check of the convention.
-`NpcAvatar.GEAR_OFFSETS` applies two final-context nudges after attachment:
-the lanyard moves 4 cm forward so its badge clears the jacket, and the
-firefighter helmet moves 3 cm up so its brim sits above the eyes. The
-`fit` report remains an asset-space measurement of the untouched GLBs.
+Gear is authored in attach-point space; the exact contract and runtime fit offsets are in
+[`architecture.md#character-and-gear-asset-contract`](architecture.md#character-and-gear-asset-contract).
 
 ## Props
 
@@ -185,7 +200,7 @@ carry baked AO and the shared neutral material maps described above.
 
 - `python3 tools/blender_assets.py audit`: container, `POSITION`/`NORMAL`/
   `TEXCOORD_0`, UVs in [0, 1], no zero-area triangles (Godot warns about them
-  during LOD generation), budgets (library characters 8000/8000, base fallback 6000/4000, gear 1500, props 4000
+  during LOD generation), budgets (characters 16000/16000, gear 1500, props 4000
   triangles), grounding, and an editable `.blend`. For characters it also
   checks skinning, bones, slots, the `npc_base` mesh node and the height.
 - `tools/tests/test_blender_assets.py`: catalogue and contract consistency with

docs/blender_previews/README.md

@@ -21,11 +21,12 @@ capture harnesses.
 | [![sheet_npc_gear.jpg](sheet_npc_gear.jpg)](sheet_npc_gear.jpg) <br> `sheet_npc_gear.jpg` | Eighteen gear pieces authored in attach space: caps, hood, helmet, bags, tanks, lanyards and handheld items. |
 | [![sheet_npc_hands_compare.jpg](sheet_npc_hands_compare.jpg)](sheet_npc_hands_compare.jpg) <br> `sheet_npc_hands_compare.jpg` | Hand pass: wider palms, segmented fingers and a separate thumb. |
 | [![sheet_npc_hands_grip_compare.jpg](sheet_npc_hands_grip_compare.jpg)](sheet_npc_hands_grip_compare.jpg) <br> `sheet_npc_hands_grip_compare.jpg` | Grip pass: the forward hand-item offset that puts props in the palm. |
+| [![sheet_head_proto_before_after.jpg](sheet_head_proto_before_after.jpg)](sheet_head_proto_before_after.jpg) <br> `sheet_head_proto_before_after.jpg` | Head overhaul sign-off: current `_face` vs the s48 connected-shell prototype at 1.85 m front/three-quarter/profile. |
 | [![sheet_npc_sources_research.jpg](sheet_npc_sources_research.jpg)](sheet_npc_sources_research.jpg) <br> `sheet_npc_sources_research.jpg` | External character-source evaluation (CC0/CC-BY) for the roster research. |
 | [![sheet_props.jpg](sheet_props.jpg)](sheet_props.jpg) <br> `sheet_props.jpg` | Twenty street and venue props with baked maps, ground contact and collider footprints. |
 | [![sheet_texture_refinement_0.9.5.jpg](sheet_texture_refinement_0.9.5.jpg)](sheet_texture_refinement_0.9.5.jpg) <br> `sheet_texture_refinement_0.9.5.jpg` | 0.9.5 texture refinement before/after: pavers, awning stripes and NPC fabric. |
 
 The acceptance criteria for these sheets are in [`../npc-visual-review.md`](../npc-visual-review.md),
-the measurements in [`../npc-proportion-audit.md`](../npc-proportion-audit.md) and
+the measurements in [`../npc-visual-review.md#proportion-audit`](../npc-visual-review.md#proportion-audit) and
 [`../3d-model-review.md`](../3d-model-review.md), and the asset contract in
 [`../blender-assets.md`](../blender-assets.md).

docs/development-status.md

@@ -1,97 +1,46 @@
 # Development Status
 
-Current planning priorities are the unversioned **3D model and local map re-evaluation** and
-**Character development** tracks in [`TODO.md`](../TODO.md); none is part of the implemented list
-below yet. The re-evaluation scores the existing characters, gear, props and
-venues against the locally installed Blender skill guidance before the roster expands. The 0.10.0
-release candidate remains the next versioned release.
+Baseline: **v0.9.8** (2026-11-04). This page lists what the build currently
+supports and what remains; it is not a release history. Completed work lives in
+[`DONE.md`](../DONE.md), user-facing changes in [`CHANGELOG.md`](../CHANGELOG.md),
+and the active order/gaps in [`TODO.md`](../TODO.md).
 
-Implemented so far:
+## Implemented
 
-- 3D re-evaluation — facade and prop pass (unversioned, 2026-11-03): the Masonic/El Capitan facade uses the photo-anchored `limestone_ashlar` field and warm-tinted stone; the TV Studio reuses `masonic_facade` (same Jimmy Kimmel starting point); the Joke Shop canopy signature band is white over black, the red curtain bays are seven tied-back hourglass drapes, and the hall wall uses `dark_stucco`. The `fire_hydrant` was rebuilt with a bolted flange, bonnet cap nut and larger outlets; `bollard` gained a flared base collar and `newspaper_box` a recessed window slot and door seam. A venue light-falloff gate asserts physical attenuation, and `tools/describe_image.py` adds free-form vision review alongside the structured judges. The scorecard, measurements and accepted limits are in [`3d-model-review.md`](3d-model-review.md).
-- Godot 4.7.2 project scaffold, input map, procedural world builder (CI/local/release unified)
-- Venue-driven simulation core: `ShiftCoordinator`, `VenueScenario`, `EventScheduler`, `NPCController` + FSM, `AccessVerifier`, `EscalationManager`, `RadioSystem`, `IncidentRecorder`, `ReputationEvaluator`, `CrowdSystem`
-- Three authored scenarios (El Capitan Entertainment Centre / Hollywood Boulevard, The Joke Shop, Late Night TV Studio) with access policies, NPC archetypes, and event pools
-- Headless unit tests: **277 passing** (access rules and venue-correct access loadout, escalation, radio cooldown/battery, NPC reaction determinism, door lock, flashlight perception, persistence round-trip, settings round-trip, input remaps, navmesh, step colliders, skyline alpha, scenario data, full-shift simulation, wand screening, responder dispatch, localization strings, focus cone, action wheel, session shell, PLAN verbs and incident recording, crowd presentation, emergency aftermath, body-camera timeline, NPC theater poses, audio, accessibility, authored scenario content, string formatting, `.tres` venue round-trip, surface materials and environment, focus ranking and outfit/gait helpers, generated prop models, web export preset, prop atlas material, player movement, NPC character layers/LOD/queue, input bindings, venue light-falloff gate, prop collider coverage)
-- Simulation extras: protester archetype, CALL_SOMEONE reaction, door lock/secure mechanic (visual indicator), flashlight with night perception bonus, LATE shift phase reaching the violent-threat event
-- First-person prototype with interaction HUD, access inspection, wand screening, radio report form (incl. emergency hold-to-confirm), dispatched responder avatars, aim-free targeting, venue cycling between all three scenarios, color-coded escalation feedback, procedural audio cues, navigation-mesh NPC paths, JSON-backed localized strings, persisted shift history, debug overlay, and shift review
-- Control pass: focus cone on NPC heads with a billboarded blue circle in front of the face and name, action wheel (LMB/Space) with de-escalation-first slices, mouse-look freeze while a panel is open, acceleration-based walking, and named input actions (`action_menu`, `confirm`, `cancel`, `inspect`, `wand`)
-- Session shell: venue start menu (keyboard + mouse), Esc pause overlay (resume / restart / settings / quit to menu), settings panel with mouse-look sensitivity and HUD font scale persisted to `user://settings.json`, and "Run another shift" returning to the venue menu
-- World presentation: skyline backdrop rendered with an alpha material, walkable step and landing colliders, larger marquee text, and larger focus circle / name tag
-- Routine traffic despawns after a while at its waypoint so the crowd cap no longer fills with idle standers
-- PLAN verbs: eye contact (distinct Level 1 cue), recognizing a person as a player decision recorded as access evidence, a body-camera flag that a formal warning arms (and `B` toggles), blocking that physically stations the guard between the person and the door, and a Level 3 request-reason ask answered from the NPC's `dialogue_lines`
-- Incidents are now actually opened on focus and closed at shift end, so player actions, access evidence, escalation levels, and unresolved interactions reach the review (previously every recorded event was dropped)
-- Crowd presentation: aggressive behavior and responder arrivals make idle bystanders stop and face the incident; panic sends people away from the door (and they leave the scene). A busy 16-NPC entrance measured ~1.2 ms/frame, so no LOD/culling was needed at the current cap
-- Distant skyline ring: four alpha-scissored planes at 200 m read as a hazy city on the horizon (the baked backdrop used to show as a black slab), with a larger ground plane so the buildings meet the street
-- Flashlight aims straight ahead and lights the person/door being checked instead of the ground in front of the guard
-- Emergency aftermath: the `evacuation` outcome locks the door and clears the entrance, an emergency call that the situation did not justify opens an investigation and applies the false-report hit, and the shift review names the responder outcome and any investigations
-- Body-camera timeline: the shift review opens a text timeline of every recorded incident event (time, person, action/outcome) that you step through with the arrow keys or buttons. No live 3D replay yet
-- NPC theater: seated guests sit on the steps with bent legs, influencers and tourists raise a camera prop while photographing, performers sway their sign, and filming visitors pan slowly — all once they reach their intent's waypoint
-- Audio: a looping procedural crowd bed (filtered murmur) whose volume follows `CrowdSystem.mood`, plus radio open/close crackle. All generated at runtime, no audio assets, and safe with a dummy audio server
-- Accessibility: the escalation cue shows a shape meter plus the numeric level (`Escalation: Blocking [###--] L3/5`) so it reads in grayscale, and the HUD font scale from settings is applied at boot by resizing fonts (not Control.scale, which broke the right-aligned layout)
-- Editor-ready venues: `tools/export_venues.gd` writes `content/venues/<id>.tres` from `ScenarioFactory`, and the `.tres` files load back with events, profiles, policy, phases, door lines, and locations intact (the factory stays the source of truth)
-- Localization safety: `Strings.fmt` validates the placeholder count before formatting and fails safe (warns, returns the template) instead of raising an engine error, `Strings.placeholder_count` ignores `%%`, and `Strings.validate()` lints the table for trailing `%`, unsupported conversions, and mixed positional/sequential placeholders
-- Authored scenario content: Joke Shop reservation-without-ID, borrowed/mismatched ID, a guest who refuses the wand screen, and a late arrival during a performance; Studio filming-boundary repeats and a celebrity arrival that draws a small crowd; Building events that point the player at the body camera and request-reason verbs
-- Visual polish pass (v0.2.0): phase-based lighting (sun/sky/ambient per shift phase), street lamps with night-mode bulbs and omni lights, glowing marquee signage, crosswalk, planters and low-poly street trees, NPC height/brightness variety, denser routine traffic — day and late-night screenshot sets
-- Assets pass: authored textures in `assets/textures/` (brick facade, concrete, asphalt, awning, skyline, vignette, HUD icons, access-card art) generated by `tools/generate_textures.py`, soft sun shadows, humanoid NPC rigs with archetype props + procedural walk bob and attention head-turn, inspection artifact cards, escalation vignette, mode icons, and a body-camera overlay (REC + shift clock)
-- Rendering pass (v0.3.0 work, [ADR-0012](adr/0012-surface-materials-and-generated-props.md)): one material module with roughness/metallic profiles per surface, ACES tonemapping, glow, aerial fog and colour grading driven by the shift phase, correctly scaled brick, framed facade windows that light up at night, door trim and handles, a curb and lane dashes, and the glowing marquee/lamp bulbs. NPCs gained per-role clothing palettes, caps/hoods/backpacks/sunglasses/lanyards, hands and shoes, and an arm/leg walk swing
-- NPC characters (v0.5.0): articulated limb rigs, layered outfits, hand items, face/hair variety, idle behaviour (phone, clipboard, crossed arms, look-around), escalation gestures, readable reaction symbols, door-queue offsets, and three LOD tiers with a billboard impostor
-- Player movement (v0.5.0): separate acceleration/braking, step-up assist, head bob and landing dip (toggleable), precision-walk FOV/chip/tick, surface-aware footsteps, gamepad support, and persistent key/button remapping in settings
-- Prop collision and placement (v0.4.0): every prop fits a static collider from its mesh bounds and publishes a navigation obstacle, so the guard and guests cannot walk through benches, bins, or bollards; placements are grouped into zones with a validator, and deterministic variants add rotation, scale, and small clutter
-- Prop atlas (v0.3.1): `tools/model_pipeline.py` packs each prop's palette into one power-of-two colour atlas plus a metallic/roughness atlas and emits a single material with per-vertex UVs, so a prop is one draw material rather than one per part; `audit` enforces the contract
-- Generated prop models (v0.3.0 work): `tools/model_pipeline.py` builds bollards, benches, bins, planters, newspaper boxes and a hydrant as `.glb` props with per-part materials, loaded by `WorldBuilder` with a procedural fallback; the optional AI concept step (`model_pipeline.py concept`) supplies per-prop colour palettes
-- Environment pass (v0.6.0): 1024² brick/concrete/asphalt with derived tangent normal maps, 256² baked AO maps for every Blender character/gear/prop, and library props whose bulbs/LEDs/sign faces follow the day/night phase
-- NPC characters + library (v0.6.0): `NpcAvatar` loads one of 8 Blender-authored skinned variants (role/seed selected) with five tintable material slots, `Rig/Head` focus anchor, and attach-point gear; `npc_base.glb` and the procedural rig remain fallbacks. `tools/blender_assets.py` builds/audits the character, gear, and 20-prop library; `WorldBuilder` loads the replacements and new street dressing (lamp, trees, palms, planters, barriers, podium, doors, marquee, sedan, handrail) with colliders, navigation obstacles, and phase-driven emissives
-- Web build: `build/gig-line-web-<version>.zip` (Godot's non-threaded web template, no COOP/COEP headers needed) built by `tools/build_releases.sh` and published with the desktop artifacts; serve the unzipped folder from any static host
-- Aim-free selection pass (v0.3.0 work, [ADR-0011](adr/0011-aim-free-selection-and-precision-walk.md)): the focus cone ranks candidates by angle then distance, `Tab` and the mouse wheel cycle nearby people nearest-first and pin the selection, right click clears focus with a short re-acquire grace, the HUD reports how many people are in the ring, and holding `Shift` walks at half speed for close work
+| Area | Current capability |
+| --- | --- |
+| Core shift | Venue menu → 15-minute shift → events, incidents, review and campaign continuation. Pause/restart/settings/quit, checkpoint resume and campaign persistence are implemented. |
+| Venues | Hollywood Boulevard (Masonic Temple / El Capitan block), The Joke Shop (Sunset Strip stand-in), and the Late Night TV Studio (same El Capitan block, arrival staging). Day/Night is a phase offset on one map, not a second bake. |
+| NPCs | 12-character Blender library (8 variants + 4 crowd variants), five tint slots, 13 required core bones with optional extras, gear attach points, procedural fallback, LOD/impostor tier and a 24-NPC budget smoke. |
+| Interaction | Focus cone/aim-free cycling, action wheel, gestural deterrence, reason/recognize, inspection, wand screening, blocking, body camera, assistance/emergency radio, responder arrival and text timeline. |
+| Access and escalation | Six escalation levels, venue access policies, artifact validity/recognition, door lock, crowd reactions, investigation/false-report handling and shift review. |
+| UI/input | Keyboard/mouse and gamepad bindings, focus rings, default modal focus, single top-modal close path, shared button states, font scaling, long-string handling, searchable Help and 21 committed UI/game captures. |
+| Audio/accessibility | Procedural crowd bed and radio cues, master/SFX/ambience volumes, reduced motion, captions, colour-independent escalation cue, hold-to-confirm emergency and guarded destructive actions. |
+| Persistence | Separate settings, campaign, shift-history and versioned checkpoint files; default-filling migration, atomic writes and corrupt/partial-file fallback. Save locations and rollback are documented in [`getting-started.md`](getting-started.md#save-data-and-migration). |
+| Assets | Blender character/gear/prop library with AO and manifests; 256² NPC maps with 4× fabric weave; image/texture pipelines, reference boards and three-up boards; environment/realism capture tools. |
+| Build/release | Godot 4.7.2 Compatibility/Web default plus optional Forward+ Desktop HQ. Gitea checks/build/publish, seven release assets, checksums, preflight/rollback and clean-worktree release discipline. |
 
-- Visual alignment: start/venue menu, pause, settings, shift review, radio, wand, inspection, timeline, HUD target chip/escalation bar, and radial menu now use or match their AI references in `assets/images/ui/`. The runtime art loader (`src/game/ui/art.gd`) falls back cleanly when a file is missing. The wand panel lists the guest's carried items, and multiline HUD/wand strings render real line breaks.
-- NPC neck/shoulder transition (0.9.4 work): the body graph now uses a fuller neck base, a slightly tapered neck top and a lower shoulder root, giving the head/neck/shoulder line a trapezius slope instead of a thin post. The full character library was rebuilt with a final degenerate-face cleanup; the baseline comparison is `sheet_npc_baseline_compare-body.jpg`.
-- NPC face-depth pass (0.9.4 work): sclera are recessed and capped by a thin upper lid, and the separate jaw/cheek spheres are replaced by a chin plate and cheekbones sculpted into the head mesh. The full library was rebuilt; the comparison is `sheet_npc_baseline_compare-face.jpg`.
-- NPC torso/hip transition (0.9.4 work): the pelvis and chest are slightly wider than the waist, giving shirts and jackets a readable taper into the hips without changing the build multipliers or the skeleton. The comparison is `sheet_npc_baseline_compare-torso.jpg`.
-- Release v0.9.6 (2026-11-03): the tagged commit `4bb2896` passed Gitea Actions run 1296 (checks + full build) and published seven artifacts (Linux, Windows, macOS, NSIS setup, AppImage, Web and Desktop HQ). Release page: <https://git.allucanget.biz/zwitschi/security-game/releases/tag/v0.9.6>.
-- Release candidate (0.10.0-rc.1, 2026-11-03): clean worktree `a9658ec` built Linux 161.5 MB, Windows 197.2 MB, macOS 148.0 MB, Web 97.8 MB and Desktop HQ 241.6 MB. The Web/HQ archives contain `CREDITS.md`, `PRIVACY.md`, `docs/accessibility.md` and `docs/known-limitations.md`; SHA-256 checksums were generated, the Linux and HQ binaries launched headless, and the Web index/wasm/pck/docs served with HTTP 200. The candidate is not published: external playtest, AI-provider/legal approval, macOS signing and the Windows/macOS target matrix remain open blockers.
-- Save migration and reliability (0.10.0 work): committed 0.8-era settings/campaign/history fixtures and a 0.9.0 checkpoint. The loader default-fills old settings, keeps campaign progress and validates checkpoints for all three venues with an open incident, NPC rows, door, flashlight and body-camera state. Corrupt and partial files fall back to defaults; a blocked atomic replace leaves the prior valid file intact. `_load_json` uses the non-logging JSON parser; save locations and rollback are documented in `getting-started.md`. Suite is 277/277;
-Python tooling is 161/161 after the GLB `inspect` intake coverage.
-- Integration checkpoint (0.9.6 work): the clean worktree at `f5b8ef2` rebuilt all five release packages and the Desktop HQ zip without ignored `tmp/`/`build/` content (Linux 161.5 MB, Windows 197.1 MB, macOS 148.0 MB, Web 97.8 MB, HQ 241.5 MB). The Web zip contains `index.html`, `index.wasm` and `index.pck`; the HQ zip contains `override.cfg` and launches headless with the Forward+ override. Current verification: Godot 263/263, Python 101/101, 14 smokes green, 24-NPC budget 6.90 ms / 168 meshes / 131,616 triangles, gallery 21 good / 0 bad, screen judge 21/21 match with 0 review/diff, and a pinned realism judge (`z-ai/glm-5.3-flash`, one pass per shot) at mean overall 2.1 and Pillow gap 0.291. No new gameplay or content changes.
-- Release v0.9.5 (2026-11-02): the tagged commit `4bc6390` passed Gitea Actions run 922 (checks + full build) and published seven artifacts (Linux, Windows, macOS, NSIS setup, AppImage, Web and Desktop HQ). Release page: <https://git.allucanget.biz/zwitschi/security-game/releases/tag/v0.9.5>.
-- Release v0.9.4 (2026-11-02): the tagged commit `a57b86c` passed the Gitea checks and full build and published seven artifacts (Linux, Windows, macOS, NSIS setup, AppImage, Web and Desktop HQ). Release page: <https://git.allucanget.biz/zwitschi/security-game/releases/tag/v0.9.4>.
-- Environment texture pass (0.9.5 work): `capture_realism.gd` now has hidden-HUD `surfaces`/`surfaces_joke` close-up stages. The Walk of Fame band uses the paver texture as dark terrazzo, the neighbour awning keeps its cream stripe, and the skyline shader blends its lower 42 m toward a per-phase haze colour. Brick, asphalt, limestone and paver UV scales/profiles passed without replacement.
-- Texture/prop audit (0.9.5 work): all 21 screen-art textures are 1280×720 and referenced; access cards are 256×128 and HUD icons 64×64. No oversized or unused runtime texture was found; the legacy root textures remain only as the texture-generator/asset-test fallback. The 24-NPC smoke now reports 168 meshes, 131,616 triangles and 6.94 ms (50 ms budget); compressed payload is 24.55 MB of surface picks, 22.67 MB of screen art and 0.48 MB of NPC maps.
-- NPC texture pass (0.9.5 work): the NPC base and all eight library characters now use 256² albedo/normal/ORM maps instead of 128². Cloth and pants use `NPC_FABRIC_UV_SCALE` (4× weave) and skip the baked per-character AO, removing the large blotchy patches in portraits; skin, hair and gear keep baked AO. The base and eight GLBs plus AO maps were rebuilt; the 24-NPC smoke remains green.
-- Texture visual verification (0.9.5 work): the nine-stage realism run used `z-ai/glm-5.3-flash` once per shot; mean `after` scores were overall 1.8, lighting 2.3, materials 1.8, texture detail 1.2, backdrop 2.0 and characters 1.2, with a Pillow metric gap of 0.306. The judge remains an optional review aid, not a CI gate. The committed before/after close-up sheet is [`blender_previews/sheet_texture_refinement_0.9.5.jpg`](blender_previews/sheet_texture_refinement_0.9.5.jpg); it records that the paver/Walk of Fame and NPC fabric repairs are visible, while asphalt, limestone and skyline picks held without a replacement. `tools/check_screenshots.sh` passed 21 good / 0 bad and the screen-design judge passed 21/21 match with 0 review.
-- NPC visual optimization (0.9.4, complete 2026-11-02): all eight variants passed the portrait/readability, proportion, gear, foot/shoe, headgear and final-context gates. The library uses an 8,000-triangle / 8,000-glTF-vertex cap (up from 6,000/5,000; `npc_base` fallback remains 6,000/4,000); current characters measure 4,482–5,474 triangles and 4,260–5,494 vertices. The 48-frame baseline and 96-frame final-context review pass, the hand/gear offset and shoes are in, and the accepted stylized limits are documented in `npc-visual-review.md`.
-- NPC face-detail pass (0.9.4 work): ala wings and a smaller nose bridge/tip, one rounded mouth slot, and a darker ear concha; all eight rebuilt. The comparison is `sheet_npc_baseline_compare-face-detail.jpg`.
-- NPC face realism pass (2026-11-03/04): all eight variants now use the `seg=24/rings=16` head with a subtle brow ridge, a fuller lower lip and both eyelids (recessed creases were rejected because they bake as dark AO patches). Vision-reviewed as cleaner/more realistic than the 0.9.4 face; characters measure 5,038–5,900 tris / 4,756–5,902 verts (still under 8,000). `sheet_npc_baseline.jpg` was refreshed.
-- Crowd-variety roster (character development, 2026-11-04): four new variants — `npc_crowd_a` (slim/bun/sunglasses), `npc_crowd_b` (broad/bald/beard/shoulder bag), `npc_crowd_c` (coat/umbrella), `npc_crowd_d` (slim/hood/cup) — built with the realistic face and wired into `CHARACTER_POOLS` so the routine crowd roles (tourist, confused visitor, intoxicated) pick them by seed instead of cloning `npc_casual`. The 24-NPC smoke is now 152,464 tris / 168 meshes / 6.94 ms (under the 50 ms budget).
-- NPC headgear clearance (0.9.4 work): the 96-frame final-context review after the face-detail pass confirms the cap, firefighter helmet, hood and sunglasses clear the refined brow and eyes; no gear rebuild was needed.
-- NPC footwear pass (0.9.4 work): casual shoes gained rounded toe and heel caps; responder/firefighter boots gained matching toe/heel volumes while retaining the black rubber boot language. All eight rebuilt; comparison `sheet_npc_baseline_compare-shoes.jpg`.
-- NPC hand-item grip (0.9.4 work): runtime `HAND_ITEM_FORWARD` moves every hand gear 4 cm forward from the wrist proxy, so phone, cup, clipboard, camera, flashlight, wand and radio sit in the open palm instead of partly inside it. The open-hand/no-finger-rig limit is accepted for this stylized release; the comparison is `sheet_npc_hands_grip_compare.jpg`.
-- NPC hand pass (0.9.4 work): wider, shallower palms; four two-segment bent fingers with rounded tips and a separate bent thumb; optional `--view=hand` capture at 0.80 m. The hand comparison is `sheet_npc_hands_compare.jpg`; the forward offset is in and the open-palm limit is accepted.
-- NPC proportion audit (0.9.4 work): `tools/npc_proportions.py` measures all eight GLBs against a stylized height/head/shoulder/hip/torso/leg/arm/foot guide. All variants pass; the head and broad-build silhouettes are the nearest upper bounds. Results are in [`npc-proportion-audit.md`](npc-proportion-audit.md).
-- NPC P1 portrait fixes (0.9.4 work): tourists now hide their photo-pose camera bag outside `photo`/`film` poses, removing the duplicate-backpack silhouette; the backpack gear was rebuilt with flattened, forward chest straps and a fresh AO map. The before/after sheet is [`blender_previews/sheet_npc_baseline_compare-p1.jpg`](blender_previews/sheet_npc_baseline_compare-p1.jpg); the remaining face/hand work was closed under the 0.9.4 acceptance limits.
-- NPC visual baseline (0.9.4 work): `src/test/capture_npc_baseline.gd` captures all eight library characters from front, three-quarter, profile, back, full-body and crowd views in a neutral studio (48 frames). The criteria, measurements and ranked gaps are in [`npc-visual-review.md`](npc-visual-review.md); the committed sheet is [`blender_previews/sheet_npc_baseline.jpg`](blender_previews/sheet_npc_baseline.jpg). No model changes were made in this baseline step.
-- UI-state capture pass (0.9.3 work): `src/test/capture_ui_states.gd` adds committed captures 14–21 for the start menu, pause, settings, shift review, emergency radio, action wheel, crowd panic and responder arrival. Every one of the 21 catalogue entries now has a current-build capture; `tools/check_screenshots.sh` reports 21 good / 0 bad and the automatic judge reports 21/21 match, 0 diff. Crowd panic and responder arrival are staged presentation frames, not gameplay changes.
-- Realism adoption (post-v0.6.0): v2 per-phase skylines and surface tiles with normal maps, retuned sun/exposure/fog, wet asphalt, denser foliage, a tight additive flashlight spot with no beam geometry, and refreshed
-staging captures. `tools/check_screenshots.sh` is the repeatable capture/compare gate; judge is clean of `diff` verdicts.
-- Input/reliability fixes: selecting a venue releases the start-menu input lock and recaptures the mouse; the body-camera overlay no longer covers the shift status. Mouse look now reads at `_input`, restores capture on window focus/click-back, and the HUD is mouse-transparent. Normal radio reports submit on click; emergency calls still require the hold-to-confirm path.
-- Production-quality pass (v0.9.0): mixer/accessibility settings, audio volume clamping, 24-NPC budget smoke, shortened coat/dress stride, and a unified Godot 4.7.2 CI/local support baseline with documented upgrade/rollback requirements.
-- Campaign and first-hour pass (v0.8.0): campaign progression, checkpoint resume, difficulty presets, a searchable Help overlay, recovery events, contextual dialogue, policy/debrief lines and tutorial/replay/skip. Scripted QA bypasses the tutorial unless `--tutorial` is passed.
-- Tutorial pass (0.8.0 work): the eight-beat first shift is wired through a non-blocking prompt overlay, a safe compliant visitor, real wheel/inspection/warning/radio panels, persisted completion/skip and a Settings replay action. Scripted tests/captures bypass it unless `--tutorial` is passed; `smoke_tutorial.gd` covers the full flow.
-- Vision judge (v0.7.2): discovers the cheapest current OpenRouter image+JSON model, reports the model/fallbacks used, and clears the full screen-design judge (13/13 match, 0 diff).
-- Desktop HQ (v0.7.1): optional Forward+ Windows/Linux zip with volumetric fog, SDFGI and a volumetric flashlight; the default Compatibility/Web builds and headless tests gate the effect off. A/B captures are generated locally under `docs/screens/realism/` (gitignored).
-- Hollywood landmark map (map optimization): the default venue is now a stylized reconstruction of 6840 Hollywood Blvd (the 1921 Masonic Temple / El Capitan Entertainment Centre) with a six-column Ionic portico, eight stone steps, Masonic parapet motto and medallions, three red event banners, central and side entrances, the El Capitan Theatre and east retail neighbours, the Ovation Hollywood arcade opposite, the Walk of Fame terrazzo and a four-lane boulevard with red kerb paint. The facade uses the shared limestone/stone material; the whole venue measures **58,884 triangles across 409 meshes** in the map-budget test. The venue menu exposes separate **Day** and **Night** Hollywood rows; the night row resolves to the same scenario with a late-phase offset, so its whole shift stays after dark. Real-site references and the geometry mapping are in [`hollywood-boulevard-map.md`](hollywood-boulevard-map.md).
-- Day/night scenery variants (map optimization): the Hollywood row in the venue menu is split into Day and Night entries, with localized names/blurbs. The night entry uses `ShiftCoordinator.phase_offset_s` to start a full-length shift in `LATE` while the clock still starts at 00:00; the scheduler reads the offset time so late-night routine traffic and the late violent-threat event still fire, and the offset round-trips through checkpoints. Three `LATE` routine events keep the night street populated. Local lights were retuned from constant falloff to linear attenuation so sconces pool instead of flooding the stone.
-- Joke Shop / Sunset Strip map (map optimization): the second venue is now a stylized reconstruction of The Comedy Store block at 8433 Sunset Blvd, with a 27 m black hall, signature-covered sloping canopy, circular **THE JOKE SHOP** blade sign, seven tied-back red velvet curtain drapes, a west-end entrance, cream and white low-rise neighbours, a dry hillside with stucco houses and palms behind the roofline, and a low retail/billboard frontage across Sunset. The same geometry serves day and late lighting through the phase system. Real-site references and limits are in [`joke-shop-map.md`](joke-shop-map.md); the map measures **25,828 triangles across 518 meshes** in the budget test.
-- Venue geometry (v0.7.0, Joke Shop frontage superseded by the map-optimization pass): the TV Studio is the same El Capitan block restaged for a late-night arrival — a stone facade, bulb canopy, glossy black car and barrier line. `WorldBuilder.VENUE_SPECS` drives facade/street/nav dimensions, and `GameManager` rebuilds only the world container when the venue changes.
-- Gear fit (post-v0.6.0): Blender gear is measured against the avatar head/skirt silhouette and the checks run in both the Python tooling and the headless suite. Sunglasses, the shoulder bag and the firefighter helmet were fitted to the new faces; the Influencer portrait and gallery were recaptured with a before/after report.
-- End-to-end interaction pass (0.9.3 work): `smoke_ui_flows.gd` drives inspection allow/deny, normal vs emergency radio, Help filtering, wand allow/deny and review return-to-menu in the real scene; campaign and timeline smokes cover review continue and timeline round-trips.
-- Destructive-action pass (0.9.3 work): reset campaign and tutorial replay share a guarded confirmation dialog (one open instance, one emission, Cancel is inert); emergency send remains hold-to-confirm with no post-submit double-fire. Covered by session/radio tests and recorded in `docs/ui-copy.md`.
-- Font/layout pass (0.9.3 work): HUD font scale was exercised at 0.75× and 1.75×; the target chip measures and caps scaled names, top labels clip, and shared action buttons ellipsize long 1.5–2× labels instead of overflowing. Covered by accessibility/button tests and recorded in `docs/ui-copy.md`.
-- Modal-close pass (0.9.3 work): one top-modal close path handles Esc/right-click for every overlay, Settings opened from the menu restores the menu, Help no longer opens Pause behind it, and pointer/guard freeze state is recaptured after each close. The session smoke covers these paths.
-- Keyboard/gamepad focus pass (0.9.3 work): `UiFocus` rings wrap through visible/enabled controls, hidden Continue and disabled timeline actions are skipped, each modal has a default focus, and A/B are bound to `ui_accept`/`ui_cancel` for pad-only navigation. Recorded in `docs/ui-copy.md`.
-- Button-state pass (0.9.3 work): a shared `UiStyles` helper now gives every action button explicit normal, hover, pressed, focus and disabled styles; the timeline disables Previous/Next at its boundaries, while hidden continue states and the keyboard-only tutorial skip remain intentional. Recorded in `docs/ui-copy.md`.
-- Dialogue pass (0.9.3 work): NPC reason answers now use the authored `reason` context, with an in-character answer for every shared archetype; Hollywood and Studio gained door-staff lines; radio cancellation, tutorial Ask terminology, help, start hints and campaign reset copy were clarified. Audit recorded in `docs/ui-copy.md`.
-- Pre-build NPC review (2026-11-02): all eight library characters were staged at portrait, conversation and crowd distance on Hollywood and the Joke Shop, in day and night lighting, with the normal crowd hidden (`src/test/capture_npc_review.gd`). No P0 issues were found. Two P1 gear-fit issues were fixed with runtime attach offsets: the authorized-guest lanyard badge now clears the jacket and the firefighter helmet sits above the eyes. Backpack straps, caps, hands and the intentionally low-poly faces were accepted for the stylized target; close-range flashlight wash remains an optional-lighting follow-up. The 24-NPC budget stayed at 6.94 ms, the gallery passed 13 good / 0 bad and the screen-design judge stayed 13/13, and a clean portrait scored a 0.732 vision gap against the photoreal concept.
+## Current verification baseline
 
-Current gaps for the 0.x release line: deeper authored content/dialogue, animation and audio production, localization/accessibility expansion, 24-NPC/platform profiling, external playtesting, and signed/notarized release packaging. The full gap analysis and milestone plan live in [`TODO.md`](../TODO.md); the current architecture and documentation ownership map are in [`docs/architecture.md`](architecture.md).
+- Godot headless suite: **277 passing**
+- Python tooling tests: **162 passing**
+- Asset audits: `blender_assets.py audit` / `fit`, `npc_pipeline.py audit` and
+  `npc_proportions.py` pass for the committed library.
+- 24-NPC smoke: 168 meshes, 152,464 triangles, 6.94 ms (50 ms budget).
+- Screenshot gate: 21 good / 0 bad; screen-design judge 21/21 match.
+- Release baseline: v0.9.8 is published; the 0.10.0 release candidate remains
+  gated on external playtest, legal/storefront, signing and platform-matrix work.
+
+## Known gaps
+
+- External first-time-player sessions and balance sweeps are not completed.
+- The NPC head/face/hand overhaul and MakeHuman body pipeline are planned, not
+  shipped.
+- Accessibility/localization acceptance, target-hardware profiling, macOS
+  signing/notarization and AI/storefront legal approval remain open.
+- Live 3D replay, recorded VO/music, more venues and seasonal content are future
+  work.
+
+See [`TODO.md`](../TODO.md) for the ordered task list and
+[`known-limitations.md`](known-limitations.md) for the current release blockers.
+Architecture and ownership are in [`architecture.md`](architecture.md).

docs/gameplay.md

@@ -16,7 +16,7 @@ A typical shift lasts 10–15 minutes. The first-person camera stays at the game
 
 The game rewards calm resolutions rather than aggressive behavior. Emergency assistance and armed responders are rare last-resort systems with meaningful consequences.
 
-The first shift starts with an in-game tutorial covering movement/look, focus cycling, the action wheel, access inspection, polite direction, formal warning/body camera, radio and shift review. Its beat sheet is in [`tutorial.md`](tutorial.md). After that a short campaign runs Hollywood → Joke Shop → TV Studio; progress, difficulty and a pause-safe checkpoint are persisted locally. Help (from the venue menu) explains the controls and the current venue policy.
+The first shift starts with an in-game tutorial covering movement/look, focus cycling, the action wheel, access inspection, polite direction, formal warning/body camera, radio and shift review. See the tutorial section below. After that a short campaign runs Hollywood → Joke Shop → TV Studio; progress, difficulty and a pause-safe checkpoint are persisted locally. Help (from the venue menu) explains the controls and the current venue policy.
 
 ## Venues
 
@@ -24,7 +24,7 @@ The first shift starts with an in-game tutorial covering movement/look, focus cy
 
 The map is a stylized reconstruction of the real building and block; the
 reference notes and geometry mapping are in
-[`hollywood-boulevard-map.md`](hollywood-boulevard-map.md). The venue menu
+[`venues.md`](venues.md#hollywood-boulevard). The venue menu
 offers the same map as **Hollywood Boulevard — Day** and **Hollywood Boulevard
 — Night**; the night variant starts directly in the late phase instead of
 waiting for the shift clock.
@@ -35,7 +35,7 @@ Authorized people must either be recognized by the guard or present a valid wris
 
 ### The Joke Shop
 
-The Joke Shop is a Sunset Strip comedy club inspired by the real Comedy Store at 8433 Sunset Blvd: a black hall under a deep signature-covered canopy, a circular blade sign, red velvet curtains, a west-end entrance, neighbouring low-rise frontage and a dry hillside of houses behind. The real-site mapping is in [`joke-shop-map.md`](joke-shop-map.md). The door person checks IDs, tickets, reservations, and guest-list status, then uses a handheld security wand according to venue policy. The player must interpret wand alerts rather than treating every alert as proof of a weapon; keys, belts, phones, and other harmless objects can trigger false alarms.
+The Joke Shop is a Sunset Strip comedy club inspired by the real Comedy Store at 8433 Sunset Blvd: a black hall under a deep signature-covered canopy, a circular blade sign, red velvet curtains, a west-end entrance, neighbouring low-rise frontage and a dry hillside of houses behind. The real-site mapping is in [`venues.md`](venues.md#the-joke-shop). The door person checks IDs, tickets, reservations, and guest-list status, then uses a handheld security wand according to venue policy. The player must interpret wand alerts rather than treating every alert as proof of a weapon; keys, belts, phones, and other harmless objects can trigger false alarms.
 
 ### Hollywood Boulevard Late Night TV Studio
 
@@ -68,3 +68,51 @@ An off-duty law-enforcement officer or armed emergency responder may arrive duri
 - **Crowd reaction:** Aggressive behavior, visible weapons, and emergency response can create panic or attract a crowd.
 - **Reputation:** Peaceful resolutions, accurate reports, low property damage, and justified calls improve performance; unnecessary confrontations and false reports reduce it.
 - **Shift review:** The player receives feedback on access decisions, escalation choices, public complaints, injuries, and security outcomes.
+
+## First-shift tutorial
+
+Status: implemented for v0.8.0. The tutorial teaches the real controls and the real
+inspection/wheel/radio panels; it is not a fake UI or a separate combat mode.
+Scripted test/capture runs bypass it unless `--tutorial` is passed; a windowed
+smoke covers completion, replay and skip.
+
+### Rules
+
+- One short, safe, compliant visitor. No emergency, threat, crowd panic or random
+  event can interrupt the tutorial.
+- Prompts advance on the performed action, not on a timer. The player can keep
+  moving/looking while a prompt is visible.
+- The tutorial is skippable at any point (F1). Completion and skip are both
+  persisted separately; a skipped tutorial can be replayed from Settings.
+- The tutorial state machine is independent of the shift FSM. It observes the
+  same actions as normal play and must be deterministic for tests.
+
+### Beat sheet
+
+| # | Beat | Prompt | Advances when | Notes |
+| --- | --- | --- | --- | --- |
+| 1 | Arrive | "Walk forward and look around. The entrance is behind you." | The guard has moved at least 1 m and looked away/returned | Start at the normal guard post, facing the street. |
+| 2 | Focus | "Look at the visitor. Press Tab or the mouse wheel to cycle targets." | A target is acquired and explicitly cycled | The visitor waits at the foot of the steps; no other guest is required. |
+| 3 | Wheel | "Open the action wheel with Space or left click." | The radial wheel opens on the visitor | The wheel is the real de-escalation-first wheel. |
+| 4 | Inspect | "Choose Inspect and read the access evidence." | The inspection panel is opened and the policy result is visible | Use a valid wristband so the tutorial can teach both evidence and a safe admit/deny decision. |
+| 5 | Direction | "Close the panel and give a polite direction." | A Level 1 polite-direction action is applied | The visitor complies; there is no escalation requirement. |
+| 6 | Warning | "Give a formal warning if the visitor persists. It arms the body camera." | A Level 2 warning is applied or the body camera is switched on | Show the REC overlay and the escalation cue. |
+| 7 | Radio | "Open the assistance radio and submit a short report." | The assistance report is submitted successfully | A non-emergency assistance call; no responder is required to resolve the tutorial. |
+| 8 | Review | "Finish the shift and review what happened." | The shift review opens | The tutorial ends; the real review remains available for inspection. |
+
+### Visitor script
+
+- Display name: `Visitor`.
+- Intent: `enter` (approaches the door, then waits for interaction).
+- Access: valid wristband evidence; the policy result should be unambiguous.
+- Behavior: compliant at every escalation level; never becomes a threat, never
+  joins a crowd and never triggers an emergency.
+- Failure handling: if the player denies admission incorrectly, the tutorial
+  explains the evidence but does not fail the run; the visitor remains safe and
+  the review records the decision.
+
+### Persistence and replay
+
+Settings gain `tutorial_completed` and `tutorial_skipped`. A first launch starts
+the tutorial after venue selection. Skipping sets `tutorial_skipped`; Settings/
+Help offers "Replay tutorial", which clears both flags for the next shift.

docs/getting-started.md

@@ -74,31 +74,25 @@ XDG_DATA_HOME=/tmp/gigline-campaign godot --path . --fixed-fps 60 --script res:/
 
 The unit test runner is the project's own lightweight harness (no editor plugin required) so CI can run it without the editor.
 
-## Save Data and Migration
+## Save Data
 
-The game keeps four small JSON files in Godot's `user://` directory, which is
-`~/.local/share/godot/app_userdata/Gig Line/` on Linux,
-`%APPDATA%\Godot\app_userdata\Gig Line\` on Windows and
-`~/Library/Application Support/Godot/app_userdata/Gig Line/` on macOS:
+The game writes four JSON files in Godot's `user://` directory:
 
-| File | Contents |
+| Platform | Location |
 | --- | --- |
-| `settings.json` | Camera, HUD, binding, difficulty, audio, accessibility and tutorial flags. Missing keys are filled from the current defaults; there is no schema version because the field set grew compatibly. |
-| `campaign.json` | Campaign index, completed venues, difficulty, shift number and last grade. Older files with missing fields open at the safe defaults. |
-| `shift_results.json` | Completed-shift review history, appended as an array. |
-| `shift_state.json` | Resumable mid-shift checkpoint, version `1`. It stores the venue, guard/door/flashlight/body-camera state, coordinator snapshot and NPC rows. |
+| Linux | `~/.local/share/godot/app_userdata/Gig Line/` |
+| Windows | `%APPDATA%\Godot\app_userdata\Gig Line\` |
+| macOS | `~/Library/Application Support/Godot/app_userdata/Gig Line/` |
 
-Writes go to a sibling `.tmp` file and are renamed only after the complete JSON
-is written. A corrupt or partial file is ignored on load, so the player gets
-defaults rather than a crash and a valid old file is not overwritten by a failed
-replace. The migration fixtures used by the tests live in
-`src/test/fixtures/saves/`.
+Files: `settings.json`, `campaign.json`, `shift_results.json` and the versioned
+`shift_state.json` checkpoint. The schema, migration/default-filling rules,
+atomic-write behavior and checkpoint contents are in
+[`architecture.md#persistence-and-save-contract`](architecture.md#persistence-and-save-contract).
 
 For a clean first launch, delete the four files (or the whole `Gig Line` user
 directory). Settings' **Reset campaign** clears campaign progress separately.
-To back up or move a profile, copy those files while the game is closed; to roll
-back, restore the previous copies. Shift history is diagnostic and is not
-required to resume a checkpoint.
+To back up or move a profile, copy the files while the game is closed; restore
+them to roll back. Shift history is diagnostic and not required to resume.
 
 ## Controls
 

docs/hollywood-boulevard-map.md

@@ -1,122 +0,0 @@
-# Hollywood Boulevard map reference
-
-The Hollywood venue is a stylized reconstruction of the real block around the
-El Capitan Entertainment Centre. It is a game space, not a survey-accurate
-model: the landmark silhouette, street wall and approach read from the player's
-eye height, while side streets and interiors are simplified.
-
-## Real site
-
-- **Address:** 6840 Hollywood Boulevard, Hollywood, Los Angeles, CA 90028.
-- **Coordinates:** 34.10118 N, 118.34009 W (OSM way `424024147`).
-- **Building:** the 1921 Hollywood Masonic Temple, designed by John C. Austin in
-  the Classical Revival style; now the El Capitan Entertainment Centre and the
-  home of *Jimmy Kimmel Live!*. This is the game's **starting point**: the first
-  shift (Hollywood) and the late-night TV Studio arrival both begin at this
-  building, where the Kimmel stage and studio occupy the interior behind the
-  six-column facade.
-- **Facade:** a light stone/render Neoclassical front with six oversized Ionic
-  columns, a recessed main entrance reached by eight stone steps, ornamental
-  iron door grilles, a continuous crosscut-grille transom, two street-level side
-  entrances, and a parapet with the Masonic motto and circular medallions.
-- **Neighbours:** the El Capitan Theatre (6838) immediately west, a modern
-  retail block east, and the Ovation Hollywood frontage (6801) across the
-  four-lane boulevard.
-- **Sidewalk:** the Hollywood Walk of Fame terrazzo strip with brass stars runs
-  along the kerb; the kerb is painted red in the reference photographs.
-
-### Late Night TV Studio venue
-
-The game's third venue is **the same block**, not a separate real site. The building houses
-*Jimmy Kimmel Live!*, so the "Late Night TV Studio" scenario restages 6840 Hollywood Blvd as a
-studio arrival: the same stone facade and steps, plus a bulb-lit canopy, a glossy black car at the
-kerb, a barrier/stanchion line and an audience queue. The Kimmel stage/audience and the entrance
-marquee are researched as local-only reference sets under
-`tmp/research/jimmy-kimmel-stage/` and `tmp/research/jimmy-kimmel-entrance/` (gitignored); the
-photo-anchored entrance concepts live in
-[`screens/concepts/hollywood_boulevard/README.md`](screens/concepts/hollywood_boulevard/README.md). `VENUE_SPECS["tv_studio"]` is a variant of the
-Hollywood spec (30.0 m facade instead of 29.6 m, arrival staging instead of the day-time banners),
-and it shares this block's reference board rather than owning one.
-
-## Game mapping
-
-| Real feature | In-game representation |
-| --- | --- |
-| 29.6 m wide, 14.5 m high facade | `VENUE_SPECS["hollywood_building"]`: `facade_width` 29.6, `facade_height` 14.5, front at `z = -4` |
-| Eight stone steps | `stair_count` 8, `stair_height` 0.10, `stair_tread` 0.38, 12 m wide |
-| Six Ionic columns | `IonicColonnade` at x = -12.4 … 12.4, 4.96 m bay spacing |
-| Recessed main entrance + two side doors | central 4.2 m door and 2.5 m side doors with transoms |
-| Red event banners | three stylized `EL / CAPITAN / LIVE` banners in the central bays |
-| Masonic motto + medallions | `FriezeInscription` label and two stone discs |
-| El Capitan Theatre | `NeighbourBlocks/ElCapitanTheatre` with marquee, blade sign and practical light |
-| Retail block east | `NeighbourBlocks/EastRetailBlock` with glazed shopfront |
-| Ovation Hollywood | `OvationHollywood` arcade with seven arched openings, sign and south sidewalk |
-| Walk of Fame | `WalkOfFame` dark terrazzo band with ten stars |
-| Four-lane boulevard | double-yellow centre, broken white lane lines, red kerb paint and crosswalk |
-| TV Studio arrival staging | `VENUE_SPECS["tv_studio"]`: same six-column Masonic facade and eight steps (reuses `masonic_facade`), plus `bulb_canopy`, `sedan`, `handrail` and barrier placements instead of the day-time marquee |
-
-The generated AI references live in
-[`docs/screens/concepts/hollywood_boulevard/`](screens/concepts/hollywood_boulevard/README.md).
-They are art direction for lighting, material scale and composition; they are
-not texture or geometry sources.
-
-## Deliberate simplifications
-
-- Show branding is replaced by the venue-neutral `EL / CAPITAN / LIVE` banner
-  text. The building name and address are retained.
-- The opposite Ovation frontage is represented as a single arcade block rather
-  than its full mall plan. Interiors, the Metro entrance and side streets are
-  out of playable bounds.
-- The AI concept frames are 1280×720 references. The in-game geometry is built
-  from boxes, cylinders and a small number of custom arch/star meshes so it
-  stays inside the Compatibility/Web budget.
-- The venue menu offers Day and Night Hollywood rows. Night is the same
-  geometry and scenario with a late-phase offset, not a second baked map; the
-  phase still drives sun, sky, fog, windows, signage and practical lights.
-- The landmark facade uses the shared smooth limestone/stone texture rather
-  than the noisier granite panel tile. The whole venue measures **58,884
-  triangles across 409 meshes** in `test_hollywood_geometry_stays_inside_the_map_budget`,
-  well inside the 150k/600 budget.
-- Local lights use linear attenuation (`omni_attenuation = 1.0`). Godot treats
-  `0.0` as constant falloff, which previously turned the night facade into a
-  flat yellow wall; the sconces now pool light instead.
-- The masonic facade field uses the `limestone_ashlar` pick: a seamless ashlar
-  tile generated reference-anchored on the 2009 facade photo (CC BY 2.0),
-  768 px over ~4.6 m of wall (~167 px/m), so the wall carries course joints and
-  per-block value variation instead of flat plaster.
-- Night balance: the event banners carry a warm self-light and the marquee sign
-  face + bulbs brighten after dark (registered with `_marquee_emissive`), so the
-  facade reads as practical-lights-only rather than a flat lit wall. The marquee
-  canopy stays black metal by design — the fictional "GIG LINE" marquee, not the
-  red El Capitan Theatre marquee next door.
-
-## References
-
-The committed, license-cleared photo board for this block — with the provenance sidecar and the
-decisions each photo informed — is in
-[`screens/refs/hollywood/README.md`](screens/refs/hollywood/README.md). The three-up boards
-(real photo | generated concept | current capture) live in
-[`screens/boards/README.md`](screens/boards/README.md) and make the remaining facade-realism gap
-visible: the capture panel still shows flat material bands where the photo has limestone value
-variation, joint lines and reveal depth.
-
-- [Hollywood Masonic Temple — Wikipedia](https://en.wikipedia.org/wiki/Hollywood_Masonic_Temple)
-- [El Capitan Entertainment Centre — OpenStreetMap way 424024147](https://www.openstreetmap.org/way/424024147)
-- [El Capitan Theatre — OpenStreetMap way 424024148](https://www.openstreetmap.org/way/424024148)
-- [Ovation Hollywood — OpenStreetMap way 151485232](https://www.openstreetmap.org/way/151485232)
-- [Hollywood Masonic Temple facade — Wikimedia Commons](https://commons.wikimedia.org/wiki/File:El_Capitan_Theater_frontal_fachade-The_Masonic_Temple.jpg)
-- Local frames that changed a decision (gitignored, never committed):
-  - `tmp/research/elcapitan-2026/` (recent Commons geosearch) → established that no recent photo
-    frames the El Capitan facade straight-on in daylight, so the 2009 CC BY frame stays the
-    geometry reference.
-  - `tmp/research/jimmy-kimmel-entrance/07.jpg` → the photo anchor for the four Jimmy Kimmel
-    entrance concepts (day/night × gemini/gpt), confirming the starting-point building.
-- [Hollywood Masonic Temple and El Capitan Theatre, 2013 — Wikimedia Commons](https://commons.wikimedia.org/wiki/File:Hollywood_Masonic_Temple_2013-10-13_10-02-25.jpg)
-
-## Verification
-
-```bash
-godot --headless --path . --script res://src/test/test_runner.gd
-godot --path . --script res://src/test/capture_realism.gd -- --out=/tmp/gig-line-hollywood --stages=day,evening,late
-python3 tools/check_docs.py
-```

docs/joke-shop-map.md

@@ -1,122 +0,0 @@
-# The Joke Shop — Sunset Strip map notes
-
-The game's second venue is a fictional comedy club called **The Joke Shop**. Its
-block, canopy, blade sign, entrance and hillside are based on the real Comedy
-Store at **8433 Sunset Blvd, West Hollywood, CA 90069**.
-
-The club name and the game's guest stories are invented. The building is a
-stylized reconstruction, not a survey-accurate model: the playable frontage is
-27 m, while the real parcel is much deeper and contains several rooms that the
-game does not enter.
-
-## Real site
-
-| Item | Reference |
-| --- | --- |
-| Address | 8433 Sunset Blvd, West Hollywood, CA 90069, United States |
-| Real venue | The Comedy Store (comedy club and theatre) |
-| OpenStreetMap | Way [`428854155`](https://www.openstreetmap.org/way/428854155), centroid 34.095265, -118.373965 |
-| OSM tags | `amenity=theatre`, `building=commercial`, `height=12.2`, `start_date=1940`, `wikidata=Q3520350` |
-| Footprint | OSM polygon bounding box about **47.1 m × 41.2 m** across the club and rear parcels |
-| Street | Sunset Boulevard, a major east–west arterial on the Sunset Strip |
-| Setting | Dry Hollywood Hills directly behind the club, with houses and palms rising above the roofline |
-
-The building began as **Ciro's**, a 1940 nightclub; it became The Comedy Store
-in the early 1970s. Its street front is a low black hall under a deep,
-signature-covered canopy, with the circular blade sign above the roof, red
-curtains along the frontage and the main entrance set toward the west end. The
-hillside houses behind it are part of the silhouette from the sidewalk.
-
-## Measured proportions (vision-extracted from the local frames, 2026-11-03)
-
-`tools/describe_image.py` was used to read the gitignored `tmp/research/comedy-store/` frames
-(the harness cannot display images directly). Two frames disagreed on crop-dependent details, so
-the ranges below are the reconciled reading; the game spec is a deliberate compression.
-
-| Feature | Reference reading | Game spec | Reconciliation |
-| --- | --- | --- | --- |
-| Street frontage | ~35–40 m wide, parapet ~5.5–6 m (≈6:1 width:height), rounded corner | 27 m × 6.0 m | Facade height lowered 8.4 → 6.0 m (2026-11-03); width still compressed for the playable block |
-| Canopy | ~4–4.5 m projection, tilts forward noticeably | 4.9 m at 11° | Close; the forward pitch is confirmed |
-| Fascia band | black, 30–40 cm deep, marquee-bulb string | black `SignatureCanopy` fascia + `CanopySignatures` + bulbs | Matches; signatures now white |
-| Circular blade sign | ~3–4 m diameter white disc, red serif wordmark, pole-mounted | 3.9 m white disc, black wordmark, pole | Diameter matches; the game wordmark is black (fictional `THE JOKE SHOP`) |
-| Red curtain bays | 3–5 visible depending on frame, floor-length, tied-back mid-bay | 7 tied-back drapes | Count is crop-dependent; 7 is a readable stylization, not a defect |
-| Entrance | west end, recessed at the rounded corner | west end at x = -8.8, recessed | Matches |
-| Roofline | taller dark mass rises behind the right half | `RoofPlant` box at x = 5.5 | Matches |
-
-## How the map maps to the real site
-
-| Real element | Game implementation |
-| --- | --- |
-| Low black comedy hall | 27 m × 12 m footprint, 6.0 m street wall; matte black concrete surface with a low plinth and parapet |
-| Deep overhanging canopy | 4.9 m sloped slab dropping about 1 m to the outer fascia; the fascia carries white signature lettering and the club name |
-| Signature-covered front | Two `Label3D` signature bands on the fascia plus a smaller wall panel, so the handwriting reads at gameplay distance without dozens of decals |
-| Circular blade sign | 3.9 m white disc with a black rim on a roof pole; `THE JOKE SHOP` lettering faces the street |
-| Red curtains | Seven tied-back velvet drapes between the entrance and the east end — each cinched into an hourglass with a scalloped hem and dark recess between bays; a red velvet entrance curtain |
-| West-end entrance | Recessed opening at x = -8.8 m with a low step, brass pulls and the door-lock indicator |
-| Warm practicals | Sconces along the wall, canopy downlights, entrance wash and three ground uplights; all off in daylight and switched by `set_night_mode()` |
-| Neighbouring low-rise frontage | Cream Mediterranean block west (balconies, red awning) with a stepped-back 5–6 storey pink hotel tower behind it (`WestHotelTower`, the Ramada Plaza mass); white commercial block east (ribbon windows, lobby) |
-| Hillside and houses | Fog-free unshaded 60° ramp behind the rear wall with stucco houses, shrubs and palms; its tint drops to a dark silhouette at night |
-| Opposite side of Sunset | Low retail row, rooftop billboard, neon and palms as background context beyond the far kerb |
-| Sidewalk furniture | Palms, queue barriers, stanchions, bins, planters, a-frame sign, hydrant and a parked sedan; prop placements pass the shared validator |
-
-## Scene composition
-
-- **Frontage:** 27 m wide, façade centre at z = -8.0, front face at z = -2.0.
-- **Sidewalk:** 38 m wide × 14 m deep, meeting the kerb at z = 11.9.
-- **Street:** 90 m × 24 m, with the four-lane markings reused from the
-  Hollywood block and a crosswalk in front of the entrance.
-- **Playable area:** x = -15…15, z = -0.6…14.0. The guard starts on the west
-  side of the entrance at (-4.8, 0.1, 1.4), facing the approach.
-- **Map budget:** the headless audit measures **25,828 triangles across 518
-  meshes**, well inside the 150k/700 test budget.
-
-The same geometry serves the day and late-night looks. There is no second baked
-map: the phase lighting, skyline/fog tint, lit windows and practicals change,
-just as with the Hollywood day/night rows.
-
-## Simplifications and limits
-
-- The real club's rear rooms, basement and roof plant are not modelled; the
-  playable area is the street frontage only.
-- The 47 m OSM footprint includes rear parcels and does not match the 27 m
-  street frontage; the game keeps the frontage proportions rather than the full
-  lot.
-- Neighbouring businesses are represented by generic low-rise blocks (plus the
-  stepped-back `WestHotelTower` mass behind the west block, standing in for the
-  Ramada Plaza). Their exact names and current tenants were not verified, so the
-  docs do not claim them.
-- The real club's west street corner is rounded (radius ~3–4 m); the game keeps
-  a hard 90° corner as a stylized-reconstruction simplification.
-- The hillside is a background ramp with simplified houses, not a terrain
-  heightfield; it exists to restore the real silhouette above the roofline.
-- Signage uses the fictional **The Joke Shop** name, not the real Comedy Store
-  wordmark.
-- The concept frames are photoreal; the game keeps its stylized, low-poly
-  material treatment. The vision judge therefore still scores material and
-  foliage detail below the reference. The remaining texture/realism work is
-  tracked with the postponed 0.9.5 pass, not treated as a map-geometry defect.
-
-## References
-
-The old committed Comedy Store photo board was removed on 2026-11-03 in favour of a local-only
-research set under `tmp/research/comedy-store/` (owner override: development reference, never
-committed, no licence gate). The three-up board (real photo | generated concept | current capture)
-is in [`screens/boards/README.md`](screens/boards/README.md); its photo panel is a historical
-public-domain frame, and the current block reference now lives in the gitignored research folder.
-
-- OpenStreetMap way 428854155: <https://www.openstreetmap.org/way/428854155>
-- AI art-direction frames: [`screens/concepts/joke_shop/`](screens/concepts/joke_shop/README.md)
-- Local frames that changed a decision (gitignored, never committed):
-  - `tmp/research/comedy-store/` facade/street/strip/visitor frames → the four
-    `comedy_store_*` photo-anchored concept pairs and the map-recreation plan.
-  - `tmp/research/comedy-store-hillside/` (public-domain hillside frame) → the photo anchor for
-    `joke_shop_entrance_day-v2.png` (a less-branded frame that clears the image-recitation filter).
-- The hall wall uses the `dark_stucco` pick (1024 px, matte charcoal grain) instead of the grey
-  paver tile, so the black stucco reads as the real club's flat plaster rather than masonry.
-- Verification: `godot --headless --path . --script res://src/test/test_runner.gd`
-  (`test_joke_shop_uses_the_real_sunset_strip_layout`,
-  `test_joke_shop_geometry_stays_inside_the_map_budget`), and
-  `godot --path . --script res://src/test/capture_realism.gd -- --stages=joke_shop_day,joke_shop`.
-  The committed gallery passed `tools/check_screenshots.sh` (13 good / 0 bad)
-  and the screen-design judge (13/13 match, 0 diff). The latest local realism
-  run reports a reference gap of 0.454 for the night entrance.

docs/npc-model-sourcing.md

@@ -1,336 +1,65 @@
-# NPC model sourcing and expansion plan
+# NPC Model Sourcing
 
-Status: **direction chosen 2026-11-03.** The procedural generator is the primary
-path, the Quaternius CC0 pack is a reviewed reference/prototype, and MakeHuman is
-deferred to a separate local development pipeline. No downloaded source model is
-committed to the game or included in a release; the committed research preview
-sheets carry the required attribution. Local evaluation files live under
-`tmp/npc-research/` (gitignored). The decision is recorded in
-[ADR-0015](adr/0015-npc-model-variety-sourcing.md).
+This page records the source evaluation behind [ADR-0015](adr/0015-npc-model-variety-sourcing.md).
+The shipped path is the project-owned Blender/procedural library; external sources
+remain references or local prototypes unless a later ADR accepts them.
 
-This page records the free/open-source character sources that were reviewed, how
-they behave when imported into the existing Blender tooling, and the options for
-creating a larger NPC model library. The runtime contract and current library are
-documented in [`blender-assets.md`](blender-assets.md) and
-[`npc-visual-review.md`](npc-visual-review.md).
+## Evaluation
 
-## Why this review exists
+The library needs variety beyond the original eight silhouettes while preserving
+the `npc_base` contract: mesh node, 13 required core bones (optional extras
+allowed), five tint slots, −Y/+Z front, grounded feet and the 16,000/16,000
+character budget.
 
-The library has eight skinned characters, and `NpcAvatar.character_model_for()`
-reuses them across role families. That is enough for a release candidate, but
-crowds repeat the same faces, builds and outfits. Three venues, a 24-NPC budget
-and close-up portraits make that repetition visible.
-
-Any expansion must preserve the existing integration contract:
-
-- mesh node `npc_base` under a `Skeleton3D`;
-- bones `Head`, `HipL/R`, `KneeL/R`, `ShoulderL/R`, `ElbowL/R`, `HandL/R` plus
-  `Hips`, `Spine`, `Neck` at the contract rest positions;
-- five tint slots (`skin`, `cloth`, `pants`, `accessory`, `hair`);
-- front on Blender −Y / Godot +Z, feet near the floor, 1.6–2.1 m height;
-- at most 8,000 triangles and 8,000 glTF vertices per character;
-- gear attach points at head, back, chest and hand.
-
-The existing `audit` command is the gate. A source that looks good in a preview
-but fails `audit` is not usable without an adaptation step.
-
-## What was evaluated
-
-Blender 5.2.0 LTS (Flatpak) imported each file in background mode. Measurements
-below come from the imported scene, because external GLBs often carry node
-transforms that the project's audit (which reads accessor-local bounds) does not
-apply. "Vertices" are the imported, seam-split counts that matter for the glTF
-budget, not the source file's vertex count.
-
-| Source | Licence | Files checked | Geometry / rig | Height | Verdict |
-| --- | --- | --- | --- | --- | --- |
-| **Quaternius Ultimate Modular Men / Women** (mirrored GLB pack) | CC0 1.0 | `Casual_Hoodie.glb`, `Worker.glb`, `Casual.glb` | 5,240–6,424 tris; 10,534–12,968 verts; 62 bones; 24 animations; 4 skinned meshes on one armature | 1.80–1.87 m | **Best silhouette/outfit match.** Fails the contract: wrong bone names/rest positions, no tint slots, no `npc_base` node, vertex budget exceeded. |
-| **Kenney Blocky Characters 2.0** | CC0 1.0 | full pack (18 characters), `character-a.glb`, `character-f.glb` | 72 tris; 143 verts; static, no armature; one texture atlas per character | 2.7 m imported (needs 0.67× scale) | **Not a close-up character.** Useful as a crowd/impostor LOD or placeholder, but cannot be driven by the skeleton and has no separate face/clothing slots. |
-| **Khronos CesiumMan** | CC BY 4.0 (© Cesium) | `CesiumMan.glb` | 4,672 tris; 3,273 verts; 19-bone walk rig; 1 material/texture; 1 animation | 1.45 m | **Technical retarget test only.** One outfit and one look, wrong rig, short; works as a skinning/pose reference. Attribution is required. |
-| **Khronos RiggedFigure** | CC BY 4.0 (© Cesium) | `RiggedFigure.glb` | 256 tris; 370 verts; 19-bone walk rig; no UVs; 1 animation | 1.48 m | **Rig smoke test only.** A mannequin with no usable surface detail. |
-| **MakeHuman core base mesh / MPFB** | Core assets CC0 1.0; application AGPL/GPL | `makehuman/data/3dobjs/base.obj` | 19,158 verts; 18,486 polygons; 36,972 tris; no rig in the base mesh | ~16.9 model units before scaling | **Best body-shape diversity, highest pipeline cost.** Needs scaling, decimation/retopology and a generated rig. The MakeHuman/MPFB tool itself is not bundled. |
-
-Local review sheet (front views, not committed):
-`tmp/npc-research/previews/contact_sheet.jpg`.
-
-Rejected without downloading: Mixamo and Ready Player Me. Both are useful
-services, but their terms are not a simple free/open-source redistribution basis
-for shipped character meshes. Sketchfab, Poly Pizza and OpenGameArt can contain
-excellent CC0 work, but each asset needs a case-by-case licence and provenance
-check; they are not a consistent library source.
-
-### Measured contract failures
-
-Every example fails the unmodified `audit` contract:
-
-| Check | Quaternius | Kenney | CesiumMan | RiggedFigure | MakeHuman base |
-| --- | --- | --- | --- | --- | --- |
-| `npc_base` mesh node | no | no | no | no | no |
-| Required 13 bones | no (62 different names) | no rig | no (19 different names) | no (19 different names) | no rig |
-| Five tint slots | no | no | no | no | no |
-| ≤ 8,000 tris | yes | yes | yes | yes | no |
-| ≤ 8,000 verts | no (10.5–13k) | yes | yes | yes | no (19k) |
-| Feet on floor | yes | yes (2.7 m scale) | yes (−11 mm) | yes | no (needs scaling) |
-| Height 1.6–2.1 m | yes | no (2.7 m) | no (1.45 m) | no (1.48 m) | needs scale |
-| Skinned / UV mapped | yes / yes | no / yes | yes / yes | yes / no | no / no |
-
-The practical conclusion is that **there is no drop-in download**. External
-sources need a deliberate intake step, and the expensive part is not decimation:
-it is rebuilding or retargeting the skeleton and material slots without breaking
-the animation proxies and gear placement.
-
-The table uses Blender-imported world bounds. The stdlib `audit` reads accessor-local
-bounds and ignores node transforms, so an unapplied external GLB can fail floor/height
-checks even when the imported scene looks correct. The intake step must apply
-transforms before it measures and exports.
-
-## Options
-
-### Option A — extend the procedural generator
-
-Add more variation to `tools/blender_assets.py` rather than importing models:
-body builds, height ranges, head/face shapes, hair and facial hair, outfit
-layers, and more `CHARACTERS` specs. This keeps a single owned style, needs no
-third-party licence review, and stays inside the existing builder/audit flow.
-
-- **Strengths:** lowest integration risk, deterministic, no new dependencies.
-- **Limits:** the current face and clothing vocabulary is intentionally simple;
-  more variants may still read as the same model with a different coat.
-- **Best for:** a quick 4–8 variant expansion and filling obvious role gaps.
-
-### Option B — Quaternius CC0 intake with a contract adapter
-
-Use Quaternius meshes as silhouette/outfit donors and adapt them to the project
-contract. The visible result is a different body/clothing language from the
-current library, so the adapter must also normalise head/hand style or rebuild
-those parts.
-
-- **Strengths:** best free outfit/hair variety, animations included, CC0,
-  already close to game proportions, front axis and floor contact.
-- **Work:** weld/decimate to the vertex budget, remap materials to the five
-  slots, rebuild the armature at the contract rest positions, transfer weights,
-  repose/normalise proportions, rename the mesh node, export, audit and compare
-  in the acceptance harness.
-- **Main risk:** retargeting a 62-bone T-pose rig to the 13-bone arm-down
-  contract. Hip/knee rest heights differ substantially (Quaternius upper leg
-  starts near 0.96 m; the contract hip starts near 0.62 m), so a naive
-  nearest-bone weight transfer can produce a good still image and bad walk
-  poses. Prototype one character before committing to a roster.
-- **Best for:** a larger, visibly different library if the prototype passes the
-  portrait and walk gates.
-
-### Option C — MakeHuman/MPFB body-shape pipeline
-
-Generate a range of ages, builds and body shapes from the CC0 MakeHuman base
-mesh, then replace the head/hands and dress them with project-owned clothing.
-This is the strongest answer to "everyone has the same body", but requires an
-offline authoring step, decimation/retopology and a custom rig/weight step. It
-should be treated as a later pipeline project, not a quick content drop.
-
-## Decision and prototype outcome
-
-The project owner reviewed this page on 2026-11-03. The decision is:
-
-1. **CC0 is acceptable** for shipped character assets. CC-BY is acceptable only
-   with attribution in `CREDITS.md`; service assets whose terms restrict
-   redistribution remain excluded.
-2. **Extend the procedural generator** as the primary path, starting with
-   crowd-variety looks.
-3. **Prototype Quaternius** as a secondary source. It is not approved for
-   shipping yet; the contract-retarget result below is a no-go for the current
-   skeleton.
-4. **Use crowd variety** as the first visual goal, not role-specific costumes.
-5. **Evaluate MakeHuman for a later, separate local development pipeline.** It
-   is not part of the normal build, CI or release flow.
-6. **Commit the research previews with attribution.** The CC-BY entries are
-   listed in `CREDITS.md` and remain development-only.
-
-### Quaternius prototype
-
-The prototype used `Casual_Hoodie.glb`:
-
-- **Geometry budget is not the blocker.** Imported: 12,518 vertices / 6,206
-  triangles. After welding seam splits: 3,199 vertices / 6,206 triangles. After
-  a 0.75 decimate: 2,423 vertices / 4,654 triangles, comfortably inside the
-  library budget.
-- **Animation quality is attractive.** The imported Idle and Walk clips read
-  well at game distance, and the model brings 24 animations.
-- **The contract rest pose is the blocker.** The source is a T-pose 62-bone rig
-  with realistic proportions: upper leg starts near 0.96 m, arm span is about
-  1.68 m, and the shoulder joint sits near x = 0.153 m. The project contract is
-  an arm-down 13-bone rig with a hip near 0.62 m, a shoulder near x = 0.27 m and
-  a hand near z = 0.78 m. Rebuilding the contract armature around this mesh would
-  either distort the body substantially or require a full proportion warp.
-- **Decision:** do not retarget Quaternius to the contract now. Keep it as a
-  silhouette/style reference and, if a second rig path is ever wanted, prototype
-  it as its own animation path (its own skeleton, AnimationPlayer clips and
-  per-model gear offsets) rather than forcing it into `npc_base`. That is a
-  separate architecture decision, not an asset conversion.
-
-Preview: [`blender_previews/sheet_npc_sources_research.jpg`](blender_previews/sheet_npc_sources_research.jpg).
-
-### Generator crowd prototype
-
-Four proposed crowd specs were built with the existing generator in a temporary
-output directory. All four audit clean and stay inside the character budget:
-
-| Prototype | Look | Tris / verts | Gear |
-| --- | --- | --- | --- |
-| `npc_crowd_a` | slim, bun, sunglasses | 4,644 / 4,356 | sunglasses |
-| `npc_crowd_b` | broad, bald, beard | 4,550 / 4,453 | shoulder bag |
-| `npc_crowd_c` | average, short hair, long coat | 5,118 / 5,086 | umbrella |
-| `npc_crowd_d` | slim, short hair, hood up | 5,258 / 4,907 | cup |
-
-They vary build, head silhouette, hair/beard and outer layer while keeping the
-existing face language. They are **not in the shipped catalogue**; production
-integration belongs to the roster/runtime work under the unversioned `Character
-development` section, after the current release candidate.
-
-Preview: [`blender_previews/sheet_npc_crowd_prototypes.jpg`](blender_previews/sheet_npc_crowd_prototypes.jpg).
-
-### MakeHuman local-pipeline evaluation
-
-The CC0 base mesh is 19,158 vertices / 18,486 polygons (36,972 triangles after
-triangulation), with 21,334 UV coordinates but no normals, material groups or
-rig. Scaling it to 1.82 m and decimating to 0.35 produced 3,780 vertices / 6,468
-triangles, which fits the geometry budget but is a collapse-decimation result,
-not production topology.
-
-MakeHuman is therefore **feasible only as a separate local body-shape pipeline**.
-The boundary for that future work is:
-
-Intake prototype (2026-11-04): `tmp/npc-research/makehuman_intake.py` scales the
-CC0 base to 1.82 m, grounds it, triangulates and decimates to **3,790 verts /
-6,444 tris**, then exports `tmp/npc-research/makehuman/makehuman_body.glb` (body
-only, one neutral material, UVs present, no rig). The body is the input for the
-contract-rig/retopology step; the script and mesh stay under `tmp/` and are never
-committed.
-
-Retarget prototype (2026-11-04): `tmp/npc-research/makehuman_retarget.py` rotates
-the A-pose arms down (−38°/+38°) and scales them **1.63×** to the contract 0.70 m
-arm, welds the split vertices, smooth-shades, adds the 13-bone contract armature
-with the project's distance-to-bone `_auto_weights`, paints the five slot regions,
-renames the mesh to `npc_base`, and exports `makehuman_retargeted.glb` — **6,444 /
-8,000 tris, 7,726 / 8,000 verts**, 14 bones, skinned, arm-down, grounded, five
-slots, no contract issues. The proportion warp (1.63× arms) is the same class of
-issue that blocked Quaternius; here it is accepted, but the vision review shows
-it distorts the deltoid/shoulder, the decimated hands are blocky, and the slot
-boundaries are rough — refinement work (arm-scale falloff, project head/hands,
-weight tuning) is the next step.
-
-The arm-scale falloff (1.0 at the shoulder tapering to 1.63 at the fingertip) was
-added, then the arm threshold was raised to x > 0.22 and a rotation falloff was
-added — the deltoid/shoulder junction is now smooth (no spiky triangles or
-arm/torso gaps). Remaining visual defects: the decimated MakeHuman head reads
-dark/featureless, the hands are flat claw-like, and the feet are detached/spiked
-— these are fixed by swapping in the project's `_face`/`_hands_and_shoes`/shoe
-parts, the next step.
-
-- MPFB/MakeHuman is installed and run by a contributor, never by CI or the game
-  build.
-- Generated bodies and intermediate exports stay in `tmp/` (gitignored); the
-  CC0 base mesh is not committed.
-- The contributor scales to 1.8–1.9 m, decimates or retopologises to roughly
-  6–7k triangles, and checks the silhouette against `npc-visual-review.md`.
-- The body gets the contract armature, weights, project-owned head/hands,
-  clothing and gear; it must pass `blender_assets.py audit` and `fit`.
-- Only the final CC0-derived GLB and its provenance note are committed. The
-  application code and any non-CC0 assets stay outside the repository.
-
-This is deferred; it is not part of the current crowd-variety work.
-
-## Provisional NPC roster
-
-The design rule stays: clothes, props and behaviour carry the read; a model must
-not label a person as "the threat". The roster therefore adds ordinary adults
-across age, build and style, not costumes that telegraph the outcome.
-
-| Look family | Current | Proposed additions | Variation axes |
-| --- | --- | --- | --- |
-| Everyday | `npc_casual`, `npc_jacket`, `npc_coat`, `npc_hoodie`, `npc_dress` | `npc_crowd_a` (bun/slim), `npc_crowd_b` (bald/broad), `npc_crowd_c` (coat/umbrella), `npc_crowd_d` (hood/cup) | build, height, hair, facial hair, outer layer, accessory |
-| Workwear | `npc_vest`, `npc_guard` | later: second hi-vis build, venue-security build | build, height, headwear, badge/radio gear |
-| Responder | `npc_firefighter` | later: paramedic/medical responder only if the design supports it | turnout vs medical kit, build, helmet |
-| Crowd/LOD | none | optional Kenney blocky or a decimated library variant for distant crowds | silhouette and palette only |
-
-A first target is **12 library characters** (the current eight plus the four
-crowd prototypes), not twenty. That is enough to break the clone effect without
-doubling the portrait QA matrix. `character_model_for()` becomes a pool per role
-family with a deterministic seed choice; the current two-way alternation for
-guests, trespassers and threats is the template.
-
-## Implementation plan
-
-The actionable tasks live in `TODO.md` under the `Character development` section. The workstreams
-are:
-
-1. **Decision and licence gate.** Complete: ADR-0015, the CC0/CC-BY rule and the
-   committed preview sheets.
-2. **Generator crowd variants.** Complete as a prototype (four specs, clean
-   audit, review sheet). Production integration is pending the current release candidate.
-3. **Quaternius intake.** The contract-retarget prototype is a no-go. Keep the
-   source as a reference; a second-rig/animation path would need its own ADR.
-4. **Roster build and runtime.** Add the four approved specs to `CHARACTERS`,
-   build and commit their GLBs, update the manifest, and extend the role pools.
-5. **QA and integration.** Run the 24-NPC budget, portrait baseline, gear fit,
-   headless suite and release build. Record provenance and any accepted limits.
-   Only then update `CHANGELOG.md` and `docs/development-status.md`.
-
-### Adapter notes
-
-- Apply node transforms before measuring or exporting. CesiumMan imports with a
-  Z-up root and an `Icosphere` helper object; exclude helpers, not just the mesh
-  names, when measuring.
-- Weld duplicate seam vertices before decimating. Quaternius' 12k imported
-  vertices are mostly UV/normal splits; the underlying surface is much smaller,
-  but the glTF budget counts the splits after export.
-- Decimate to a target below 8,000 tris/verts, then re-unwrap only if the
-  existing UVs cannot survive the material remap. The current library uses
-  smart projection at 80° to keep islands large.
-- Map materials by semantic role, not by source name. A source "Purple" or
-  "Worker_Vest" needs an explicit mapping to `cloth`, `pants`, `skin`, `hair` or
-  `accessory`; do not rely on colour heuristics.
-- Keep the face direction unambiguous. The front is Blender −Y; verify it with
-  a capture, not by guessing from the source file.
-- For any future external-rig path, do not silently add a second skeleton format
-  to `NpcAvatar`. Record the per-model skeleton, animation source and gear
-  offsets as an explicit contract.
-
-## Review outcome
-
-The project owner answered the review questions on 2026-11-03:
-
-| Question | Answer |
-| --- | --- |
-| Are third-party CC0 characters acceptable? | Yes. |
-| Which direction? | Prototype Quaternius and extend the procedural generator. |
-| Which looks first? | Crowd variety. |
-| Should MakeHuman be pursued? | Evaluate it for a later, separate local development pipeline. |
-| Commit the previews? | Yes, with CC-BY attribution. |
-
-## Downloaded example provenance
-
-Source models were downloaded on 2026-11-03 and kept out of version control. The two
-research preview sheets are committed under `docs/blender_previews/`; the CC-BY
-attribution is recorded in `CREDITS.md`.
-
-| File | Source | SHA-256 |
+| Source | Licence | Result |
 | --- | --- | --- |
-| `quaternius/Casual_Hoodie.glb` | `raw.githubusercontent.com/LuanDucate/Ducz.CharacterCreator/HEAD/public/models/Male/Casual_Hoodie.glb` (Quaternius CC0) | `f5b722199f7628b24550989af4230f65d5230727df9c326fd2b3e360effe5249` |
-| `quaternius/Worker.glb` | same mirror, `Male/Worker.glb` | `8d0f454336c2effc5c08f63a177af3a82d1a7af025ca9588b40e4c90c4703534` |
-| `quaternius/Casual.glb` | same mirror, `Female/Casual.glb` | `bc2d84fba249ebaa0629cb9d133ad37234196e4b8004aa205a6397abed04e05c` |
-| `kenney_blocky_characters.zip` | `kenney.nl/assets/blocky-characters` | `5e123859aa0c1598342b600c6db197024a1d63eb9ec531398b310725f589887e` |
-| `khronos/CesiumMan.glb` | `github.com/KhronosGroup/glTF-Sample-Assets` | `b7001eaeea8254bd44773bcd247e78696d94169388fbb2a1800fc69434e777d9` |
-| `khronos/RiggedFigure.glb` | same repository | `d6be85417d3e256861ee733eea6916093a7af7c79c16366181fd8abcaeb38cf5` |
-| `makehuman/base.obj` | `github.com/makehumancommunity/makehuman/blob/master/makehuman/data/3dobjs/base.obj` | `8e761e6624b8f54536409135d1636da63b32486a90d4897f84e121d144f6fb4c` |
+| Quaternius Ultimate Modular | CC0 | Good silhouette/decimation material, but a 62-bone T-pose realistic rig and different proportions; not a drop-in. Kept as a reference/prototype. |
+| Kenney Blocky Characters | CC0 | No matching rig; style is much blockier than the project look. |
+| Khronos CesiumMan / RiggedFigure | CC BY 4.0 | Different bone names/rest pose and no five-slot materials; not a drop-in. |
+| MakeHuman / MPFB base | CC0 | Useful body-shape base, but requires retopology, a custom rig, clothing and part integration. Active local pipeline, not the shipped path. |
 
-Source terms:
+The contract mismatch is the expensive part, not decimation: retargeting a
+different rig or rebuilding slots/weights can distort the body and invalidate
+gear placement. Any future second-rig path needs its own ADR and animation/gear
+offsets.
 
-- Quaternius packs are CC0 1.0 according to the pack page and the mirror's
-  credits. The mirror is a convenience download; the original pack page is
-  <https://quaternius.com/packs/ultimatemodularcharacters.html>.
-- Kenney Blocky Characters 2.0 is CC0 1.0; the pack's `License.txt` is included
-  in the download.
-- CesiumMan and RiggedFigure are CC BY 4.0, © 2017 Cesium. If any derivative is
-  committed or shipped, the attribution must be added to `CREDITS.md`.
-- MakeHuman core assets are CC0 per `LICENSE.ASSETS.md`; the application source
-  is AGPL and is not bundled.
+## Decision and outcome
+
+- Extend the project-owned procedural generator as the primary shipped path
+  (12-character library, crowd variants, role pools).
+- Keep Quaternius as a studied reference, not a shipped base.
+- MakeHuman is a local development pipeline for body-shape diversity; it must
+  consume the same head/hand parts as the procedural library and never become a
+  CI/build dependency.
+- Record CC0/CC-BY provenance; CC-BY previews require attribution in
+  [`CREDITS.md`](../CREDITS.md).
+
+## MakeHuman prototype notes
+
+The local prototype (`tmp/npc-research/`, never committed) scaled the base to
+1.82 m, grounded it, triangulated/decimated it and retargeted it to the 13-core
+armature. The first retarget measured **6,444 / 16,000 tris and**
+**7,726 / 16,000 verts**, 14 bones, skinned, arm-down, five slots. It exposed
+the expected issues: a 1.63× arm-scale warp at the deltoid/shoulder, blocky
+decimated hands, rough slot boundaries and a head/neck shadow gap. The later
+project head/hands swap reduced this to **6,407 / 16,000 tris and**
+**6,651 / 16,000 verts**, but manual shoulder/neck retopology and part cleanup
+remain before it can be considered shippable.
+
+The head/face/hand overhaul in [`TODO.md`](../TODO.md) is the prerequisite: the
+MakeHuman body should reuse the approved local head/hand parts rather than
+forking a second face implementation.
+
+## Provenance rules
+
+- CC0 preferred; CC-BY only with attribution in `CREDITS.md`; no service asset
+  whose terms restrict redistribution.
+- Downloaded research and generated previews stay in `tmp/`/gitignored folders;
+  only final audited assets and committed review sheets enter the repository.
+- Record source URL, licence, author, date and what decision the reference
+  informed. Never treat a generated concept as licensed map/model data.
+
+Measurements, visual decisions and accepted limits are in
+[`3d-model-review.md`](3d-model-review.md) and
+[`npc-visual-review.md`](npc-visual-review.md). Commands are in
+[`asset-tooling.md`](asset-tooling.md).

docs/npc-proportion-audit.md

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

docs/npc-visual-review.md

@@ -71,9 +71,9 @@ The criteria below are for the stylized target, not photorealism. A change must
 pass every applicable item before a library rebuild is accepted.
 
 1. **Asset contract:** `npc_base` mesh node, the required bones, five tint slots,
-   front +Z, feet within 3 cm of y=0, 1.6–2.1 m height, at most 8,000 triangles
-   and 8,000 glTF vertices per library character. The frozen `npc_base` fallback
-   keeps 6,000 triangles / 4,000 vertices. Gear remains at most 1,500 triangles.
+   front +Z, feet within 3 cm of y=0, 1.6–2.1 m height, at most 16,000 triangles
+   and 16,000 glTF vertices per character. The required 13 core bones stay fixed;
+   optional extra bones are allowed. Gear remains at most 1,500 triangles.
 2. **Proportion and silhouette:** head, neck, shoulders, torso, hips, limbs and
    feet read as one body; front/three-quarter/profile silhouettes agree with the
    rest of the eight-character library; broad/slim/average build variation is
@@ -113,11 +113,83 @@ measurement.
 
 ## Proportion audit
 
-The separate [`npc-proportion-audit.md`](npc-proportion-audit.md) measures
-height, head size, shoulder/hip width, torso, leg, arm and foot ratios for every
-variant with `tools/npc_proportions.py`. All eight pass the stylized guide; the
-head and broad-build shoulders sit nearest their upper bounds. No skeleton or
-mesh proportion change was needed in this pass.
+Status: audited 2026-11-02. All eight library variants are inside the stylized
+proportion guide; no geometry correction was required in this pass. The report
+is repeatable from the exported GLBs:
+
+```bash
+python3 tools/npc_proportions.py report
+python3 tools/npc_proportions.py report --json
+```
+
+### Method
+
+`tools/npc_proportions.py` reads the GLB meshes and rest-pose joint hierarchy:
+
+- height from the full mesh bounds;
+- head height, width and aspect from `Head`/`skin` vertices (hair excluded so
+  long hairstyles do not change the head measurement);
+- shoulder silhouette from vertices in the upper-chest band around the
+  shoulder joint;
+- hip width from `HipL`/`HipR` pants vertices;
+- torso length from the Spine joint to the shoulder joint;
+- leg length from the Spine joint to the lowest vertex;
+- arm length from the shoulder joint to the Hand joint;
+- foot length from the forward extent of the KneeL/KneeR shoe vertices.
+
+All ratios are divided by total standing height except `head_aspect`
+(width / head height).
+
+### Guide
+
+These are stylized-but-credible bands for the game's low-poly adults, not
+photoreal anatomy. The broad build is allowed a larger shoulder/hip silhouette
+than the slim build.
+
+| Ratio | Target | Notes |
+| --- | ---: | --- |
+| `head_height` | 0.16–0.22 | deliberately larger than a realistic 0.13–0.15 |
+| `head_aspect` | 0.70–1.00 | width / height; rounded heads are acceptable |
+| `shoulder_width` | 0.28–0.38 | silhouette includes sleeves and build scaling |
+| `hip_width` | 0.17–0.23 | pants-only width, not skirt/coat flare |
+| `torso_length` | 0.28–0.38 | Spine joint to shoulder |
+| `leg_length` | 0.40–0.48 | Spine joint to ground |
+| `arm_length` | 0.28–0.38 | shoulder to hand |
+| `foot_length` | 0.12–0.18 | shoe forward extent |
+
+### Result
+
+| Character | Height | Head | Aspect | Shoulder | Hip | Torso | Leg | Arm | Foot | Result |
+| --- | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: | --- |
+| `npc_casual` | 1.824 m | 0.190 | 0.907 | 0.321 | 0.209 | 0.307 | 0.449 | 0.329 | 0.144 | PASS |
+| `npc_jacket` | 1.824 m | 0.190 | 0.907 | 0.333 | 0.209 | 0.307 | 0.449 | 0.329 | 0.144 | PASS |
+| `npc_coat` | 1.824 m | 0.190 | 0.907 | 0.328 | 0.209 | 0.307 | 0.449 | 0.329 | 0.144 | PASS |
+| `npc_vest` | 1.819 m | 0.191 | 0.907 | 0.322 | 0.209 | 0.308 | 0.451 | 0.330 | 0.144 | PASS |
+| `npc_dress` | 1.825 m | 0.190 | 0.907 | 0.289 | 0.191 | 0.307 | 0.449 | 0.329 | 0.144 | PASS |
+| `npc_hoodie` | 1.856 m | 0.187 | 0.907 | 0.328 | 0.206 | 0.302 | 0.442 | 0.323 | 0.141 | PASS |
+| `npc_firefighter` | 1.819 m | 0.191 | 0.907 | 0.358 | 0.223 | 0.308 | 0.451 | 0.330 | 0.148 | PASS |
+| `npc_guard` | 1.819 m | 0.191 | 0.907 | 0.369 | 0.219 | 0.308 | 0.451 | 0.330 | 0.144 | PASS |
+
+No variant is outside a band, so the body pass does not need a global skeleton
+or mesh rescale. The values closest to a boundary are:
+
+- **head height 0.190** against the 0.22 upper bound, and **head aspect 0.907**
+  against 1.00 — the head is deliberately large. Any head-size change must be
+  coordinated with the face/headgear pass and its gear-fit measurements.
+- **guard shoulder 0.369** and **firefighter hip 0.223** against the broad-build
+  upper bounds — these are the intended uniform/turnout silhouettes, not
+  outliers.
+- **leg length 0.449** and **torso 0.307** sit inside the guide for all variants;
+  the earlier short-leg impression came from the hip joint position, not the
+  visible pelvis line.
+
+### Follow-up
+
+The proportion audit does not replace the visual criteria in
+[`npc-visual-review.md`](npc-visual-review.md): neck/shoulder/hip transitions,
+face depth, hand grips, clothing hems and shoes still need the appearance pass.
+Re-run the audit after any body mesh or skeleton change and record the new
+ratios here.
 
 ## Baseline measurements
 
@@ -134,8 +206,8 @@ From `python3 tools/blender_assets.py fit` and the manifest:
 | `npc_firefighter` | 5,344 | 5,494 | 0.315 m | 0.255 m (skirt) | helmet width ratio 1.651; SCBA x −0.105, radial −0.076 |
 | `npc_guard` | 5,046 | 5,096 | 0.315 m | 0.194 m (hip) | cap width ratio 1.067 |
 
-`npc_coat` is widest at 5,474 triangles (2,526 below the 8,000 cap);
-`npc_firefighter` is closest on vertices at 5,494 (2,506 below the 8,000 cap).
+`npc_coat` is widest at 5,474 triangles (well below the 16,000 cap);
+`npc_firefighter` is closest on vertices at 5,494 (well below the 16,000 cap).
 The refit backpack measures 380 triangles / 406 vertices.
 
 ## Baseline findings, ranked

docs/release-qa.md

@@ -1,11 +1,69 @@
-# Release-candidate balance acceptance
+# Release QA and Balance
+
+Manual verification and the 0.10.0 balance protocol. The executable command
+matrix is in the release runbook/skill; this page owns the human smoke checks and
+the measurable balance targets. Architecture owns the gates themselves; gameplay
+owns the mechanics.
+
+## Manual smoke checklist
+
+1. `godot --path .` starts the game on the venue menu without script errors.
+2. Choosing a venue (click or ↑/↓ + Enter) starts that venue's shift and hides the menu.
+3. The guard moves and looks around; the building, steps, and sidewalk are visible.
+4. The guard's camera sits at eye height and the guard stands on the landing, not inside the building.
+5. Walking into the steps carries the guard up onto the landing (steps have colliders).
+6. The skyline backdrop shows silhouettes against the sky, not an opaque black slab.
+7. The `GIG LINE` marquee is readable from the sidewalk.
+8. NPCs spawn and approach the entrance during the first minutes.
+9. Looking at an NPC inside the focus cone shows a blue focus circle in front of the face, the person's name, and the HUD target line.
+10. `Space` or left click opens the action wheel; `A`/`D` highlight a slice, `Space` confirms it, `Esc`/right click cancels without a log entry.
+11. `E`/`C` open the inspection/wand panels from the wheel and freeze movement until they close; walking never fires the wand.
+12. Pressing `Q` produces a reaction log entry and reputation feedback.
+13. `E` opens access inspection showing venue-correct artifacts and policy result; `A`/`D` record a decision.
+14. `6` opens the assistance form; submitting shows dispatch feedback.
+15. `R` opens the emergency form; the button must be held ~1.6s or the call cancels.
+16. `G` toggles the flashlight (indicator appears in the HUD); `L` toggles the door lock (indicator turns red when locked).
+17. `F` toggles the debug overlay with NPC states and shift stats.
+18. The wheel's `Look` slice is eye contact (Level 1) and logs as its own action.
+19. `Reason` asks why the person is there and logs their `dialogue_lines` reply.
+20. `Recognize` records the guard's recognition as access evidence; pressing it twice says so.
+21. `Warn` turns the body camera on (REC overlay appears); `B` toggles it manually.
+22. `Block` moves the guard between the person and the door.
+23. The shift review reports the incident count, including interactions left unresolved.
+24. Escalating on someone (or a responder arriving) makes idle bystanders stop and face the incident.
+25. Repeated alarms panic the crowd and nearby people clear away from the door instead of standing around.
+26. `Esc` with nothing open pauses the shift; resume / restart / settings / quit-to-menu all work, and settings changes persist across a restart.
+27. NPCs route around the building using the navigation mesh (no stuck-at-wall behavior during a smoke run).
+28. An unjustified emergency call (calm person, no weapon) logs an investigation and costs reputation.
+29. After an evacuation outcome the door is locked and NPCs are leaving the entrance.
+30. The shift review's "Body camera timeline" button steps through the recorded events (Left/Right or the buttons) and Esc returns to the review.
+31. The escalation label shows a `[###--] L3/5` shape meter as well as the level name, and stays readable in grayscale.
+32. Changing "HUD font scale" in Settings resizes the HUD text and persists across a restart.
+33. When the shift timer reaches 0, the shift review screen shows grade, policy, incident summary, responder outcomes, investigations, and persisted shift history; campaign Continue starts the next venue.
+34. On a fresh profile the tutorial starts on Hollywood, advances through its eight beats, and F1 skips it; Settings Replay tutorial restarts it.
+35. Pausing saves a checkpoint: returning to the menu and choosing Continue resumes elapsed time, NPCs, incidents, door/flashlight state and campaign position.
+36. Settings difficulty changes spawn pacing/compliance/report strictness while escalation rules stay the same; Help filters controls and shows the venue policy.
+37. The F debug overlay lists the next eligible events; recovery events and recently played scripted events behave as authored.
+38. Master/SFX/ambience volume settings clamp at 0/1 and persist; Reduce motion disables head bob; the captions toggle persists.
+39. The 24-NPC budget smoke stays inside its frame budget; coats/dresses do not show obvious leg clipping in a normal walk.
+40. Help remains readable with the largest HUD font scale, and CI/local verification use the same Godot 4.7.2 baseline.
+41. UI copy: inspection/wand use "A = admit · D = refuse entry", review returns with "Return to menu", and application exit reads "Quit game".
+42. Button states remain readable on hover/focus/pressed; settings Apply/Cancel and radio normal-send/emergency-hold behave as labelled.
+43. The venue menu offers Hollywood Boulevard — Day and — Night; either starts the same map, and Night starts in the late phase with a full shift clock.
+44. The Joke Shop opens on the Sunset Strip club: the black hall, signature canopy, circular **THE JOKE SHOP** sign, red curtains, west entrance, palms, dry hillside with houses, neighbouring frontage and the opposite side of Sunset all read from the door camera. Day lighting and late lighting both look correct; the guard can walk the sidewalk without leaving the nav bounds.
+45. Esc and right-click close only the top panel (Help, Settings, Pause, Review, Radio, timeline, inspection/wand, action wheel); Settings opened from the venue menu returns to the menu, Help no longer opens Pause behind it, and closing a modal recaptures the mouse without leaving the guard frozen.
+46. At 0.75× and 1.75× HUD font scale, long target names stay inside the target chip, the chip grows/caps correctly, and long button labels ellipsize instead of pushing panels off-screen.
+47. Reset campaign and Replay tutorial both ask for confirmation; a second click reuses the open dialog, Cancel does nothing, and OK fires once. Emergency send requires the full hold, sends exactly once, and does not send again on release.
+48. UI copy/button sweep: every panel uses the canonical admit/refuse, warning/blocking, assistance/emergency and body-camera terms; the start menu, pause, settings, Help, inspection, wand, radio, wheel, timeline and shift review all show readable hover/focus/pressed/disabled states; Tab/arrow focus wraps without landing on hidden or disabled actions; Esc/right-click closes only the top panel; and destructive reset/replay plus emergency send still require their confirmation or hold.
+
+## Balance acceptance
 
 These are the acceptance targets for the 0.10.0 balance pass, not measured results.
 No reaction tables, event weights or scoring rules were changed to set them. The
 [roadmap](../TODO.md) tracks the sweeps and external playtests still needed.
 [Gameplay](gameplay.md) owns the mechanics; this page owns their balance-test protocol.
 
-## Test matrix and evidence
+### Test matrix and evidence
 
 Run Hollywood, Joke Shop and TV Studio on easy, normal and hard, in Early,
 Midday, Evening and Late: **36 cells**. Use seeds 1–100 for each cell and retain
@@ -37,7 +95,7 @@ cell. Use at least **100 eligible cases per metric per cell**; if the schedule
 provides fewer, add a separately labelled forced-case sample. Report zero eligible
 cases as **N/A**, never as 100% success. Keep scheduled and forced results separate.
 
-## Targets
+### Targets
 
 Percentages below apply to each matrix cell, not only a pooled average. Scripted
 access/report cases use complete evidence and are held to exact correctness;
@@ -71,7 +129,7 @@ after an accepted emergency call). Separately test depleted battery and active
 cooldown cases for safe containment/assistance; do not silently drop them from the
 evidence or claim the initially-available-radio target covers them.
 
-## Scoring and emergency dominance
+### Scoring and emergency dominance
 
 Compare the calm policy with an emergency-first policy on the same routine events
 and seeds. Each comparison starts with fresh radio, crowd and reputation state.
@@ -87,7 +145,7 @@ the incident remains answerable and the debrief explains the outcome without an
 unjustified-call investigation. Also compare assistance/containment routes where
 appropriate; emergency need not be mandatory for every difficult interaction.
 
-## Implementation cautions and sign-off
+### Implementation cautions and sign-off
 
 - `NPCController.roll_reaction()` samples per-level weights. Difficulty adds
   +12/0/−8 to the `COMPLY` weight before normalization; `base_compliance` alone

docs/screen-design-report.md

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

docs/screens/concepts/README.md

@@ -15,13 +15,13 @@ The map-optimization references for the El Capitan Entertainment Centre block
 (6840 Hollywood Blvd) are in
 [`hollywood_boulevard/README.md`](hollywood_boulevard/README.md). The real-site
 facts and game mapping are documented in
-[`../../hollywood-boulevard-map.md`](../../hollywood-boulevard-map.md).
+[`../../venues.md`](../../venues.md#hollywood-boulevard).
 
 ## The Joke Shop — Sunset Strip
 
 The current Joke Shop map is based on The Comedy Store at 8433 Sunset Blvd.
 The real-site mapping and simplifications are in
-[`../../joke-shop-map.md`](../../joke-shop-map.md); the frames are in
+[`../../venues.md`](../../venues.md#the-joke-shop); the frames are in
 [`joke_shop/README.md`](joke_shop/README.md).
 
 ![Joke Shop entrance in daylight](joke_shop/joke_shop_entrance_day.png)

docs/screens/concepts/hollywood_boulevard/README.md

@@ -4,7 +4,7 @@ AI-generated art-direction frames for the real El Capitan Entertainment Centre
 block at 6840 Hollywood Boulevard. They are generated with
 `tools/scene_concepts.py generate --group scene --only ...` and are not shipped
 game textures. The geometry mapping and source links are in
-[`../../../hollywood-boulevard-map.md`](../../../hollywood-boulevard-map.md).
+[`../../../venues.md`](../../../venues.md#hollywood-boulevard).
 
 ## Entrance — day
 

docs/screens/concepts/joke_shop/README.md

@@ -4,7 +4,7 @@ AI-generated art-direction frames for the fictional Joke Shop, based on the
 real Comedy Store block at 8433 Sunset Boulevard. They are generated with
 `tools/scene_concepts.py generate --group scene --only ...` and are not shipped
 game textures. The geometry mapping and source links are in
-[`../../../joke-shop-map.md`](../../../joke-shop-map.md).
+[`../../../venues.md`](../../../venues.md#the-joke-shop).
 
 ## Entrance — day, photo-anchored
 

docs/screens/head-review/README.md

@@ -0,0 +1,59 @@
+# Head rework — review page (2026-11-04)
+
+This page is the review checkpoint for the NPC head rework. The goal was to replace the
+sphere-and-floating-primitive face with a head that has real nose / chin / jaw landmarks at
+portrait distance.
+
+## What changed
+
+The original procedural face is a head sphere plus separate nose, mouth, ear and eye primitives.
+The new head uses the **decimated MakeHuman head** (CC0, 1,573 tris) as the base shape and keeps
+the project's separate eyeballs, brow and mouth pieces on top. An AI judge was used to drive the
+decision: it scored the procedural rework at ~3/5 and then picked the MakeHuman head as the
+clearer silhouette.
+
+| | Source | Tris (head) | Read |
+| --- | --- | --- | --- |
+| **Before** | procedural `_face` (sphere + primitives) | ~1,900 | flat face, slit eyes |
+| **After** | overhauled MakeHuman head + project eyes/brows/mouth | ~1,880 | smooth nose/chin/jaw landmarks |
+
+The head source was overhauled 2026-11-04: the blocky decimated MakeHuman head was welded
+(merge-by-distance) and Laplacian-relaxed into one clean manifold shell (`makehuman_head.glb`,
+1,548 tris skin), then the project eyes/brows/mouth were added.
+
+## AI-generated target concept
+
+The rework was guided by two generated concept frames (front + profile, `bytedance-seed/seedream-4.5`).
+
+![concept](sheet_concept.jpg)
+
+## 1.85 m comparison (top = current, bottom = new)
+
+Left to right: front, three-quarter, profile.
+
+![1.85 m comparison](sheet_compare_1.85.jpg)
+
+## New head at 1.5 m (portrait)
+
+![1.5 m portrait](sheet_head_1.5.jpg)
+
+## Contract and checks
+
+- `blender_assets.py inspect` on the assembled `npc_casual` with the new head: **14 bones,
+  skinned, no issues**.
+- Source: `assets/models/blender_src/makehuman_head.glb` (CC0, attributed in `CREDITS.md`).
+- Python 167/167, Godot 277/277, `check_docs` OK.
+
+## Remaining polish (known, not blockers)
+
+1. The hair cap still reads as a stepped block instead of hugging the skull.
+2. The brows weld to the face but can read as a slightly separate bar.
+3. The neck underside cap is plain; it is hidden by the body neck in the assembled character.
+4. The head skin is 1.5k tris (smooth but low-poly); a retopology pass could add resolution if a
+   portrait shows faceting.
+
+## Decision needed
+
+Approve or reject the MakeHuman-head direction. If approved, the next step is rolling it into the
+other 11 variants (one asset family at a time) with a before/after sheet per batch, and re-running
+the 24-NPC budget + AO bake.

docs/screens/refs/README.md

@@ -76,8 +76,8 @@ committed here is the redacted copy, not the original.
 ## How the folder is used
 
 - Build the venue **three-up boards** (photo | concept | current capture) for the review verdicts.
-- Link the board from the venue map document (`docs/hollywood-boulevard-map.md`,
-  `docs/joke-shop-map.md`) and from the local-map block notes.
+- Link the board from the venue map document (`docs/venues.md#hollywood-boulevard`,
+  `docs/venues.md#the-joke-shop`) and from the local-map block notes.
 - Cite the sidecar when a texture, proportion or signage decision is derived from a photo.
 - Refresh the board when a venue change makes an old reference misleading, and note the change in
   the sidecar.

docs/screens/refs/SIDECAR-TEMPLATE.md

@@ -34,7 +34,7 @@ attribution string for CC BY / CC BY-SA in the `Author` or a note below.
 
 | Decision | Evidence | Where it landed |
 | --- | --- | --- |
-| e.g. six-column spacing kept at 2.4 m | photo 1, measured against door width | `docs/hollywood-boulevard-map.md` |
+| e.g. six-column spacing kept at 2.4 m | photo 1, measured against door width | `docs/venues.md#hollywood-boulevard` |
 | e.g. banner red sampled to `#8a1f24` | photo 1 + photo 2 | `docs/screens/refs/hollywood/` notes, facade kit |
 
 ## Generated boards used with this set

docs/screens/refs/hollywood/SIDECAR.md

@@ -51,10 +51,10 @@ before use.
 
 | Decision | Evidence | Where it landed |
 | --- | --- | --- |
-| Six Ionic columns, ~2.4 m spacing, 8 steps | facade photo measured against the door width | `docs/hollywood-boulevard-map.md` geometry notes |
+| Six Ionic columns, ~2.4 m spacing, 8 steps | facade photo measured against the door width | `docs/venues.md#hollywood-boulevard` geometry notes |
 | Masonic parapet motto and medallions | 1922 elevation + facade photo | `WorldBuilder` facade, `docs/screenshots/01-venue-overview.png` |
 | Three vertical event banners | facade photo | facade banners and the day/night capture set |
-| Red carpet + barrier staging narrows the sidewalk | premiere photo | `docs/hollywood-boulevard-map.md` event staging notes |
+| Red carpet + barrier staging narrows the sidewalk | premiere photo | `docs/venues.md#hollywood-boulevard` event staging notes |
 | Across-street height and plaza opening | Ovation photo | opposite frontage massing |
 | TV Studio arrival staging (bulb canopy, car, barriers) | premiere staging photo | `VENUE_SPECS["tv_studio"]` and the Late Night TV Studio venue docs |
 | Terrazzo band width, star size/spacing | terrazzo + star close-up photos | `WalkOfFame` band geometry and the paver material |

docs/screenshots/README.md

@@ -29,6 +29,6 @@ README, the gameplay docs and the screenshot gate; do not edit them by hand.
 | 21 | [Responder arrival](21-responder-arrival.png) | A responder at the locked door |
 
 The captures are 1280×720 PNGs. Reference designs and the judge report live in
-[`../screens/`](../screens/README.md) and [`../screen-design-report.md`](../screen-design-report.md);
+[`../screens/`](../screens/README.md) and [`../ui-copy.md#screen-design-judge-report`](../ui-copy.md#screen-design-judge-report);
 the re-evaluation's pose and review sheets are under
 [`../blender_previews/`](../blender_previews/README.md).

docs/smoke-checklist.md

@@ -1,50 +0,0 @@
-# Smoke Test Checklist
-
-1. `godot --path .` starts the game on the venue menu without script errors.
-2. Choosing a venue (click or ↑/↓ + Enter) starts that venue's shift and hides the menu.
-3. The guard moves and looks around; the building, steps, and sidewalk are visible.
-4. The guard's camera sits at eye height and the guard stands on the landing, not inside the building.
-5. Walking into the steps carries the guard up onto the landing (steps have colliders).
-6. The skyline backdrop shows silhouettes against the sky, not an opaque black slab.
-7. The `GIG LINE` marquee is readable from the sidewalk.
-8. NPCs spawn and approach the entrance during the first minutes.
-9. Looking at an NPC inside the focus cone shows a blue focus circle in front of the face, the person's name, and the HUD target line.
-10. `Space` or left click opens the action wheel; `A`/`D` highlight a slice, `Space` confirms it, `Esc`/right click cancels without a log entry.
-11. `E`/`C` open the inspection/wand panels from the wheel and freeze movement until they close; walking never fires the wand.
-12. Pressing `Q` produces a reaction log entry and reputation feedback.
-13. `E` opens access inspection showing venue-correct artifacts and policy result; `A`/`D` record a decision.
-14. `6` opens the assistance form; submitting shows dispatch feedback.
-15. `R` opens the emergency form; the button must be held ~1.6s or the call cancels.
-16. `G` toggles the flashlight (indicator appears in the HUD); `L` toggles the door lock (indicator turns red when locked).
-17. `F` toggles the debug overlay with NPC states and shift stats.
-18. The wheel's `Look` slice is eye contact (Level 1) and logs as its own action.
-19. `Reason` asks why the person is there and logs their `dialogue_lines` reply.
-20. `Recognize` records the guard's recognition as access evidence; pressing it twice says so.
-21. `Warn` turns the body camera on (REC overlay appears); `B` toggles it manually.
-22. `Block` moves the guard between the person and the door.
-23. The shift review reports the incident count, including interactions left unresolved.
-24. Escalating on someone (or a responder arriving) makes idle bystanders stop and face the incident.
-25. Repeated alarms panic the crowd and nearby people clear away from the door instead of standing around.
-26. `Esc` with nothing open pauses the shift; resume / restart / settings / quit-to-menu all work, and settings changes persist across a restart.
-27. NPCs route around the building using the navigation mesh (no stuck-at-wall behavior during a smoke run).
-28. An unjustified emergency call (calm person, no weapon) logs an investigation and costs reputation.
-29. After an evacuation outcome the door is locked and NPCs are leaving the entrance.
-30. The shift review's "Body camera timeline" button steps through the recorded events (Left/Right or the buttons) and Esc returns to the review.
-31. The escalation label shows a `[###--] L3/5` shape meter as well as the level name, and stays readable in grayscale.
-32. Changing "HUD font scale" in Settings resizes the HUD text and persists across a restart.
-33. When the shift timer reaches 0, the shift review screen shows grade, policy, incident summary, responder outcomes, investigations, and persisted shift history; campaign Continue starts the next venue.
-34. On a fresh profile the tutorial starts on Hollywood, advances through its eight beats, and F1 skips it; Settings Replay tutorial restarts it.
-35. Pausing saves a checkpoint: returning to the menu and choosing Continue resumes elapsed time, NPCs, incidents, door/flashlight state and campaign position.
-36. Settings difficulty changes spawn pacing/compliance/report strictness while escalation rules stay the same; Help filters controls and shows the venue policy.
-37. The F debug overlay lists the next eligible events; recovery events and recently played scripted events behave as authored.
-38. Master/SFX/ambience volume settings clamp at 0/1 and persist; Reduce motion disables head bob; the captions toggle persists.
-39. The 24-NPC budget smoke stays inside its frame budget; coats/dresses do not show obvious leg clipping in a normal walk.
-40. Help remains readable with the largest HUD font scale, and CI/local verification use the same Godot 4.7.2 baseline.
-41. UI copy: inspection/wand use "A = admit · D = refuse entry", review returns with "Return to menu", and application exit reads "Quit game".
-42. Button states remain readable on hover/focus/pressed; settings Apply/Cancel and radio normal-send/emergency-hold behave as labelled.
-43. The venue menu offers Hollywood Boulevard — Day and — Night; either starts the same map, and Night starts in the late phase with a full shift clock.
-44. The Joke Shop opens on the Sunset Strip club: the black hall, signature canopy, circular **THE JOKE SHOP** sign, red curtains, west entrance, palms, dry hillside with houses, neighbouring frontage and the opposite side of Sunset all read from the door camera. Day lighting and late lighting both look correct; the guard can walk the sidewalk without leaving the nav bounds.
-45. Esc and right-click close only the top panel (Help, Settings, Pause, Review, Radio, timeline, inspection/wand, action wheel); Settings opened from the venue menu returns to the menu, Help no longer opens Pause behind it, and closing a modal recaptures the mouse without leaving the guard frozen.
-46. At 0.75× and 1.75× HUD font scale, long target names stay inside the target chip, the chip grows/caps correctly, and long button labels ellipsize instead of pushing panels off-screen.
-47. Reset campaign and Replay tutorial both ask for confirmation; a second click reuses the open dialog, Cancel does nothing, and OK fires once. Emergency send requires the full hold, sends exactly once, and does not send again on release.
-48. UI copy/button sweep: every panel uses the canonical admit/refuse, warning/blocking, assistance/emergency and body-camera terms; the start menu, pause, settings, Help, inspection, wand, radio, wheel, timeline and shift review all show readable hover/focus/pressed/disabled states; Tab/arrow focus wraps without landing on hidden or disabled actions; Esc/right-click closes only the top panel; and destructive reset/replay plus emergency send still require their confirmation or hold.

docs/tutorial.md

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

docs/ui-copy.md

@@ -227,3 +227,18 @@ The gallery is regenerated by `tools/check_screenshots.sh`.
 - Focus/hover/pressed/disabled states and keyboard/gamepad rings are recorded above.
 - Pseudo-locale layout and a translator workflow remain scheduled for the
   localization milestone, not this UI pass.
+
+## Screen-design judge report
+
+Date: 2026-11-02
+Model: automatic cheapest image+JSON selection (`z-ai/glm-5.3-flash` at run time)
+Command: `python3 tools/screen_designs.py judge`
+Result: **21/21 match, 0 review, 0 diff**
+
+The screenshot gallery was regenerated on the current build before judging, including the eight UI-state captures 14–21 added in `src/test/capture_ui_states.gd`.
+Accepted captures are in [`docs/screens/`](screens/README.md); the committed
+gallery is in [`docs/screenshots/`](screenshots/README.md).
+
+The automatic model selection and retry/spend behavior is documented in
+[`docs/asset-tooling.md`](asset-tooling.md). This report intentionally records
+the outcome rather than generated captures, which remain local/gitignored.

docs/venues.md

@@ -0,0 +1,148 @@
+# Venues
+
+The game uses two physical Hollywood blocks across three playable venue rows:
+
+- **Hollywood Boulevard** — the 6840 Hollywood Blvd / El Capitan Entertainment
+  Centre block, in day and night rows.
+- **The Joke Shop** — a fictional comedy club based on the Sunset Strip block
+  around 8433 Sunset Blvd.
+- **Late Night TV Studio** — the same El Capitan block restaged as a studio
+  arrival.
+
+The runtime implementation contract (facade specs, map budgets, navigation,
+colliders, phase behavior and fallback) lives in
+[`architecture.md`](architecture.md#venue-implementation-contract). This page
+keeps the real-site evidence, mapping decisions and deliberate simplifications.
+
+## Hollywood Boulevard
+
+### Real site
+
+- **Address:** 6840 Hollywood Boulevard, Hollywood, Los Angeles, CA 90028.
+- **Coordinates:** 34.10118 N, 118.34009 W; OpenStreetMap way `424024147`.
+- **Building:** the 1921 Hollywood Masonic Temple by John C. Austin, now the El
+  Capitan Entertainment Centre and the home of *Jimmy Kimmel Live!*. It is the
+  game's starting point for both the Hollywood shift and the TV Studio arrival.
+- **Facade:** light stone/render Neoclassical front, six oversized Ionic
+  columns, a recessed entrance up eight stone steps, ornamental door grilles,
+  a crosscut transom, two side entrances, and the Masonic parapet motto and
+  medallions.
+- **Neighbours:** the El Capitan Theatre immediately west, a modern retail block
+  east, and the Ovation Hollywood frontage across the four-lane boulevard.
+- **Sidewalk:** the Walk of Fame terrazzo strip with brass stars; red-painted
+  kerb in the reference photographs.
+
+### Game mapping
+
+| Real feature | In-game representation |
+| --- | --- |
+| 29.6 m wide, 14.5 m high facade | `VENUE_SPECS["hollywood_building"]`, front at `z = -4` |
+| Eight stone steps | 8 steps, 0.10 m rise, 0.38 m tread, 12 m wide |
+| Six Ionic columns | `IonicColonnade`, 4.96 m bay spacing |
+| Central + two side doors | 4.2 m central door, 2.5 m side doors with transoms |
+| Red event banners | three stylized `EL / CAPITAN / LIVE` banners |
+| Masonic motto + medallions | `FriezeInscription` and two stone discs |
+| El Capitan Theatre / east retail | library-neighbour blocks with marquee/blade or glazed shopfront |
+| Ovation Hollywood | arcade with seven arched openings, sign and south sidewalk |
+| Walk of Fame | dark terrazzo band with ten stars |
+| Four-lane boulevard | double-yellow centre, broken white lanes, red kerb, crosswalk |
+| TV Studio arrival | same six-column facade/eight steps plus bulb canopy, sedan, handrail and barriers |
+
+The generated references in
+[`screens/concepts/hollywood_boulevard/`](screens/concepts/hollywood_boulevard/README.md)
+are art direction for lighting, material scale and composition; they are not
+texture or geometry sources.
+
+### Late Night TV Studio
+
+The third venue is **not a separate real site**. It reuses the El Capitan block
+and restages it as a studio arrival: the same stone facade and steps, plus a
+bulb-lit canopy, glossy black car, barrier/stanchion line and audience queue.
+`VENUE_SPECS["tv_studio"]` is a 30.0 m variant of the Hollywood spec with the
+arrival staging; it shares this block's reference board.
+
+## The Joke Shop
+
+### Real site
+
+| Item | Reference |
+| --- | --- |
+| Address | 8433 Sunset Blvd, West Hollywood, CA 90069 |
+| Real venue | The Comedy Store (comedy club and theatre) |
+| OpenStreetMap | Way [`428854155`](https://www.openstreetmap.org/way/428854155), centroid 34.095265, -118.373965 |
+| Tags | `amenity=theatre`, `building=commercial`, `height=12.2`, `start_date=1940`, `wikidata=Q3520350` |
+| Footprint | OSM polygon about 47.1 m × 41.2 m across the club and rear parcels |
+| Street | Sunset Boulevard on the Sunset Strip |
+| Setting | Dry Hollywood Hills with houses and palms above the roofline |
+
+The building began as **Ciro's** (1940) and became The Comedy Store in the
+early 1970s. Its street front is a low black hall under a deep,
+signature-covered canopy, with a circular blade sign above the roof, red
+curtains along the frontage and the main entrance set toward the west end.
+
+### Game mapping
+
+| Real element | Game implementation |
+| --- | --- |
+| Low black comedy hall | 27 m × 12 m footprint, 6.0 m street wall, matte black concrete, low plinth and parapet |
+| Deep overhanging canopy | 4.9 m sloped slab at 11°, white signature fascia band and club name |
+| Signature-covered front | two `Label3D` signature bands plus a wall panel |
+| Circular blade sign | 3.9 m white disc on a roof pole, black `THE JOKE SHOP` wordmark |
+| Red curtains | seven tied-back velvet drapes with scalloped hems and dark recesses |
+| West-end entrance | recessed at x = -8.8 m, low step, brass pulls, door-lock indicator |
+| Practicals | sconces, canopy downlights, entrance wash, ground uplights; off by day, switched at night |
+| Neighbours | cream Mediterranean block with red awning; `WestHotelTower` mass behind; white commercial block east |
+| Hillside | fog-free unshaded ramp with stucco houses, shrubs and palms; dark silhouette at night |
+| Opposite Sunset | low retail row, rooftop billboard, neon and palms beyond the far kerb |
+| Street dressing | palms, barriers, stanchions, bins, planters, A-frame, hydrant and parked sedan |
+
+Key proportions are reconciled in the map budget and `VENUE_SPECS`; the full
+measured table is retained in the 3D review history. The playable frontage is
+27 m, the facade centre is at z = -8.0 and the front face at z = -2.0. The
+sidewalk is 38 m × 14 m, meeting the kerb at z = 11.9; the street is 90 m × 24 m.
+The guard starts west of the entrance at (-4.8, 0.1, 1.4), facing the approach.
+
+## Deliberate simplifications
+
+- Both blocks are stylized reconstructions, not survey models; show branding is
+  replaced by venue-neutral/fictional text while addresses and landmark
+  silhouettes are retained.
+- Interiors, basements, side streets, the Metro entrance and the Comedy Store's
+  rear rooms are out of playable bounds.
+- The Ovation frontage is one arcade block, not the full mall plan; neighbouring
+  businesses are generic low-rise masses and no current tenant is claimed.
+- The Joke Shop's rounded west corner is kept as a hard 90° corner; its hillside
+  is a background ramp with simplified houses, not a terrain heightfield.
+- Geometry uses boxes, cylinders and a small set of custom arch/star meshes to
+  stay inside the Compatibility/Web budget; concept frames are photoreal and the
+  runtime keeps a stylized material treatment.
+- Day/night is a phase offset on one geometry/scenario, not a second baked map.
+  The night row starts in `LATE` while the checkpoint stores the offset.
+
+## References
+
+- [Hollywood Masonic Temple — Wikipedia](https://en.wikipedia.org/wiki/Hollywood_Masonic_Temple)
+- [El Capitan Entertainment Centre — OpenStreetMap way 424024147](https://www.openstreetmap.org/way/424024147)
+- [El Capitan Theatre — OpenStreetMap way 424024148](https://www.openstreetmap.org/way/424024148)
+- [Ovation Hollywood — OpenStreetMap way 151485232](https://www.openstreetmap.org/way/151485232)
+- [Hollywood Masonic Temple facade — Wikimedia Commons](https://commons.wikimedia.org/wiki/File:El_Capitan_Theater_frontal_fachade-The_Masonic_Temple.jpg)
+- [Hollywood Masonic Temple and El Capitan Theatre, 2013 — Wikimedia Commons](https://commons.wikimedia.org/wiki/File:Hollywood_Masonic_Temple_2013-10-13_10-02-25.jpg)
+- [Comedy Store — OpenStreetMap way 428854155](https://www.openstreetmap.org/way/428854155)
+- Committed photo boards: [`screens/refs/hollywood/`](screens/refs/hollywood/README.md),
+  [`screens/refs/joke-shop/`](screens/refs/joke-shop/README.md); three-up boards
+  are in [`screens/boards/`](screens/boards/README.md).
+- Local-only research (never committed): `tmp/research/elcapitan-2026/`,
+  `tmp/research/jimmy-kimmel-entrance/`, `tmp/research/comedy-store/` and
+  `tmp/research/comedy-store-hillside/`. These are evidence for decisions, not
+  shipped assets.
+
+## Verification
+
+```bash
+godot --headless --path . --script res://src/test/test_runner.gd
+godot --path . --script res://src/test/capture_realism.gd -- --out=/tmp/gig-line-venues --stages=day,evening,late,joke_shop_day,joke_shop
+python3 tools/check_docs.py
+```
+
+The map-budget tests and the venue light-falloff gate are part of the headless
+suite; the screenshot/realism gates are optional review evidence.

project.godot

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

tools/blender_assets.py

@@ -53,13 +53,14 @@ MANIFEST = OUT_DIR / "manifest.json"
 SLOTS = ["skin", "cloth", "pants", "accessory", "hair"]
 BONES = ["Head", "HipL", "HipR", "KneeL", "KneeR", "ShoulderL", "ShoulderR",
          "ElbowL", "ElbowR", "HandL", "HandR"]
-# The eight library variants may use more geometry than the frozen npc_base
-# fallback (6000 tris / 4000 verts). Raised to 8000/8000 on 2026-11-02 so the
-# remaining face, hand-grip and clothing work is not forced to replace detail.
-# The glTF vertex count is after UV-seam splits; each avatar is still one
-# skinned mesh, and `smoke_npc_budget.gd` must confirm the 24-NPC frame time.
-CHAR_MAX_TRIS = 8000
-CHAR_MAX_VERTS = 8000
+# Character cap raised to 16000/16000 on 2026-11-04 for the head/face/hand
+# overhaul and possible MakeHuman parts. The required 13 core bones stay, but
+# optional extra bones (fingers, face, toes) are allowed; they must not move the
+# core rest positions. The glTF vertex count is after UV-seam splits; each
+# avatar is still one skinned mesh, and `smoke_npc_budget.gd` must confirm the
+# 24-NPC frame time before accepting the increase.
+CHAR_MAX_TRIS = 16000
+CHAR_MAX_VERTS = 16000
 GEAR_MAX_TRIS = 1500
 PROP_MAX_TRIS = 4000
 
@@ -566,7 +567,7 @@ def _skin_body(spec):
             ((0.20 * s * w, 0, 1.37), 0.080 * t * sleeve, 0.074 * t * sleeve),  # shoulder
             ((0.27 * s * w, 0, 1.23), 0.058 * t * sleeve, 0.058 * t * sleeve),  # upper arm
             ((0.275 * s * w, 0.005, 1.06), 0.046 * t * sleeve, 0.048 * t * sleeve),  # elbow
-            ((0.275 * s * w, -0.01, 0.80), 0.034 * t, 0.030 * t),  # wrist
+            ((0.275 * s * w, -0.01, 0.78), 0.034 * t, 0.030 * t),  # wrist
         ]
         edges += [(3, base), (base, base + 1), (base + 1, base + 2), (base + 2, base + 3)]
         hb = len(nodes)
@@ -666,13 +667,27 @@ def _auto_weights(obj, layout, rigid=None):
                 groups[bone].add([v.index], 1.0, "REPLACE")
                 continue
         if abs(p.x) > 0.19 and p.z > 0.74 and p.z < 1.42:
-            allowed = ["Spine", f"Shoulder{side}", f"Elbow{side}", f"Hand{side}"]
-            if abs(p.x) > 0.23:
-                allowed.remove("Spine")
+            if p.z < 0.82:
+                # Wrist: track the Hand bone fully so the forearm-end moves with
+                # the rigid hand (the old Hand+Elbow blend left a visible gap at
+                # the wrist when the hand rotated).
+                allowed = [f"Hand{side}"]
+            else:
+                allowed = ["Spine", f"Shoulder{side}", f"Elbow{side}", f"Hand{side}"]
+                if abs(p.x) > 0.23:
+                    allowed.remove("Spine")
         elif p.z < 0.80:
-            allowed = ["Hips", f"Hip{side}", f"Knee{side}"]
-            if p.z < 0.66:
-                allowed.remove("Hips")
+            # Legs: keep the shin rigid to the knee and the thigh rigid to the
+            # hip, with a short blend only at the knee joint, so deep flexion
+            # (seated) no longer collapses the thigh or pinches the knee.
+            if p.z < 0.28:
+                allowed = [f"Knee{side}"]
+            elif p.z < 0.34:
+                allowed = [f"Hip{side}", f"Knee{side}"]
+            elif p.z < 0.62:
+                allowed = [f"Hip{side}"]
+            else:
+                allowed = ["Hips", f"Hip{side}"]
         elif p.z > 1.40:
             allowed = ["Spine", "Neck", "Head"]
         else:
@@ -840,6 +855,198 @@ def _face(mats, spec):
     return parts
 
 
+def _head_proto(mats, spec, subdiv=48):
+    """Connected head shell with sculpted sockets, nose, lips, ears and brow/cheek/jaw.
+
+    The model-overhaul prototype: the skin features are displaced out of one
+    head mesh instead of floating spheres, so the face is a single connected
+    surface with loop-based eye sockets and protruding nose/lip/ear volumes. The
+    eyeballs (sclera/iris/lids) stay separate — they are not skin. Blender Z-up,
+    face front −Y. `subdiv` is the UV-sphere u-segments (24/48/64 variants); s48
+    is the chosen default after the 1.5 m/1.85 m comparison.
+    """
+    skin, acc, hair = mats["skin"], mats["accessory"], mats["hair"]
+    white = material("eye_white", textured_solid=True)
+    rings = max(14, subdiv // 2 + 2)
+    head = sphere("HeadShell", 0.155, (0, 0, 1.635), skin, seg=subdiv, rings=rings,
+                  scale=(0.88, 0.95, 1.18))
+    _shape_head_mesh(head)  # brow ridge + cheekbone + jaw/chin planes
+    bm = bmesh.new()
+    bm.from_mesh(head.data)
+
+    # Pass 1: skull shape — flatten the face plane and taper the jaw/chin.
+    for v in bm.verts:
+        x, y, z = v.co
+        if y < -0.03 and 1.42 < z < 1.80:
+            v.co.y = -0.13 + (y + 0.13) * 0.05  # flatten the forward bulge
+        if y < -0.03 and z > 1.70:
+            v.co.y += (z - 1.70) * 0.45  # forehead slopes back to the crown
+        if z < 1.58:
+            taper = max(0.0, 1.0 - (1.58 - z) / 0.12)
+            v.co.x *= 1.0 - 0.16 * taper  # narrow the lower face
+
+    # Pass 2: features on the flattened face.
+    for v in bm.verts:
+        x, y, z = v.co
+        ax = abs(x)
+        # --- brow ledge: a clear ridge where the forehead meets the nose ---
+        brow = (max(0.0, 1.0 - abs(z - 1.695) / 0.024)
+                * max(0.0, 1.0 - abs(ax - 0.050) / 0.045))
+        if brow > 0:
+            v.co.y -= 0.028 * brow
+        # --- eye sockets: recess the floor, leave a raised orbital rim ---
+        for s in (-1.0, 1.0):
+            r = math.hypot(x - 0.052 * s, z - 1.664)
+            if r < 0.036:
+                v.co.y += 0.018 * (1.0 - r / 0.036)
+            elif r < 0.046:
+                v.co.y -= 0.010 * (1.0 - (r - 0.036) / 0.010)
+        # --- nose: a wide bridge/tip with ala wings ---
+        if y < 0 and ax < 0.080:
+            band = max(0.0, 1.0 - abs(z - 1.632) / 0.055)
+            if band > 0:
+                tip = max(0.0, 1.0 - abs(z - 1.615) / 0.034)
+                v.co.y -= (0.062 * tip + 0.020 * max(0.0, band - tip)) \
+                          * (1.0 - ax / 0.080)
+            for s in (-1.0, 1.0):
+                ar = math.hypot((x - 0.026 * s) / 0.015, (z - 1.604) / 0.014)
+                if ar < 1.0:
+                    v.co.y -= 0.024 * (1.0 - ar)
+        # --- chin wedge + jaw step ---
+        if y < 0 and ax < 0.044:
+            chin = max(0.0, 1.0 - abs(z - 1.548) / 0.024)
+            if chin > 0:
+                v.co.y -= 0.034 * chin
+            step = max(0.0, 1.0 - abs(z - 1.516) / 0.016)
+            if step > 0:
+                v.co.y += 0.026 * step
+        # --- mouth: recessed line + smooth protruding upper/lower lip block ---
+        if y < 0 and ax < 0.036:
+            if abs(z - 1.583) < 0.014:
+                v.co.y += 0.006
+            if abs(z - 1.590) < 0.012:
+                v.co.y -= 0.016
+            if abs(z - 1.577) < 0.014:
+                v.co.y -= 0.020
+    # --- ears: raised C-shape helix + concha recess + a lobe ---
+    for v in bm.verts:
+        x, y, z = v.co
+        r = math.hypot((z - 1.62) / 0.062, (y - 0.002) / 0.048)
+        near = abs(x) - 0.138
+        sign = 1.0 if x >= 0 else -1.0
+        if -0.02 < near < 0.07 and r < 1.0:
+            if r < 0.36:
+                v.co.x -= 0.016 * (1.0 - r / 0.36) * sign
+            else:
+                v.co.x += 0.048 * (1.0 - r) * sign
+        lr = math.hypot((z - 1.585) / 0.018, (y + 0.012) / 0.017)
+        if -0.02 < near < 0.06 and lr < 1.0:
+            v.co.x += 0.034 * (1.0 - lr) * sign
+    bm.normal_update()
+    bm.to_mesh(head.data)
+    bm.free()
+
+    # Eyeballs stay separate for readability; lids wrap the socket rim.
+    parts = [head]
+    for s in (-1.0, 1.0):
+        ex, ey, ez = 0.052 * s, -0.127, 1.664
+        parts.append(sphere("EyeWhite", 0.019, (ex, ey, ez), white, seg=10,
+                            rings=6, scale=(1.25, 0.62, 0.85)))
+        parts.append(sphere("Iris", 0.0105, (ex, ey - 0.007, ez), acc, seg=8,
+                            rings=5, scale=(1.0, 0.55, 1.0)))
+        parts.append(sphere("UpperLid", 0.020, (ex, ey - 0.006, ez + 0.014),
+                            skin, seg=8, rings=4, scale=(1.20, 0.32, 0.24),
+                            rot=(math.radians(-10), 0, 0)))
+        parts.append(sphere("LowerLid", 0.017, (ex, ey - 0.004, ez - 0.012),
+                            skin, seg=8, rings=4, scale=(1.10, 0.22, 0.18),
+                            rot=(math.radians(6), 0, 0)))
+        parts.append(box("Brow", (0.055, 0.014, 0.012), (0.052 * s, -0.137, 1.699),
+                         hair, rot=(0, 0.14 * s, 0.0)))
+    return parts
+
+
+def _makehuman_head(mats, spec):
+    """MakeHuman head shape plus the project's eye/mouth/brow pieces.
+
+    The AI-judged head rework (2026-11-04) picked the decimated MakeHuman head
+    over the displacement shell: it keeps the nose/chin/jaw landmarks at 1,573
+    tris. The MakeHuman mesh has no eyeballs, so the project's sclera/iris/lid/
+    brow pieces are added at the MakeHuman landmarks (eyes ≈ ±0.052, −0.160,
+    1.664) for readability. Blender Z-up, face front −Y.
+    """
+    skin, acc, hair = mats["skin"], mats["accessory"], mats["hair"]
+    white = material("eye_white", textured_solid=True)
+    src = SRC_DIR / "makehuman_head.glb"
+    before = {o.name for o in bpy.context.scene.objects}
+    bpy.ops.import_scene.gltf(filepath=str(src))
+    # Drop the imported armature / glTF neutral bone; build_character re-weights
+    # the head to the contract rig.
+    for a in list(bpy.context.scene.objects):
+        if a.type == "ARMATURE" and a.name not in before:
+            bpy.data.objects.remove(a, do_unlink=True)
+    # Pick the newly imported mesh, not the already-built body.
+    head = next((o for o in bpy.context.scene.objects
+                 if o.type == "MESH" and o.name not in before
+                 and o.data.materials), None)
+    if head is None:
+        raise SystemExit(f"no head mesh in {src}")
+    head.name = "HeadShell"
+    # The decimated MakeHuman "hair" scalp slot reads as shaggy shards; collapse
+    # the head to one skin slot so the join does not collide with the body's
+    # cloth/pants slots (the project `_hair` cap provides hair later).
+    head.data.materials.clear()
+    head.data.materials.append(skin)
+    # Clean the ragged neck cut left by the Head-group extraction: bisect below
+    # the jaw and cap the hole so the head ends on a clean solid underside.
+    bm = bmesh.new()
+    bm.from_mesh(head.data)
+    bmesh.ops.bisect_plane(bm, geom=bm.verts[:] + bm.edges[:] + bm.faces[:],
+                           plane_co=(0, 0, 1.50), plane_no=(0, 0, -1),
+                           clear_outer=True)
+    boundary = [e for e in bm.edges if e.is_boundary]
+    if boundary:
+        bmesh.ops.holes_fill(bm, edges=boundary)
+    bm.to_mesh(head.data)
+    bm.free()
+
+    # Lids and brows weld into the head shell so the face reads as one surface;
+    # the sclera/iris stay separate eyeballs.
+    shell_parts = [head]
+    for s in (-1.0, 1.0):
+        ex, ez = 0.052 * s, 1.664
+        shell_parts.append(sphere("UpperLid", 0.020, (ex, -0.135, ez + 0.014),
+                                  skin, seg=8, rings=4, scale=(1.20, 0.32, 0.24),
+                                  rot=(math.radians(-10), 0, 0)))
+        shell_parts.append(sphere("LowerLid", 0.017, (ex, -0.135, ez - 0.012),
+                                  skin, seg=8, rings=4, scale=(1.10, 0.22, 0.18),
+                                  rot=(math.radians(6), 0, 0)))
+        shell_parts.append(box("Brow", (0.055, 0.014, 0.012), (0.052 * s, -0.165, 1.705),
+                               hair, rot=(0, 0.14 * s, 0.0)))
+    shell = join(shell_parts, "HeadShell")
+    bm = bmesh.new()
+    bm.from_mesh(shell.data)
+    bmesh.ops.remove_doubles(bm, verts=bm.verts, dist=0.008)
+    bm.to_mesh(shell.data)
+    bm.free()
+
+    parts = [shell]
+    for s in (-1.0, 1.0):
+        # The MakeHuman socket is a deep cavity (floor ≈ −0.105); keep the
+        # sclera recessed so it never breaks the face silhouette.
+        ex, ey, ez = 0.052 * s, -0.125, 1.664
+        parts.append(sphere("EyeWhite", 0.019, (ex, ey, ez), white, seg=10,
+                            rings=6, scale=(1.25, 0.62, 0.85)))
+        parts.append(sphere("Iris", 0.0105, (ex, ey - 0.007, ez), acc, seg=8,
+                            rings=5, scale=(1.0, 0.55, 1.0)))
+    # A subtle mouth line on top of the MakeHuman lips for readability.
+    parts.append(sphere("Mouth", 0.028, (0, -0.165, 1.58), acc, seg=8, rings=5,
+                        scale=(1.0, 0.28, 0.12)))
+    # A skull-conforming buzz cap sized for the smaller MakeHuman cranium.
+    parts.append(_hair_cap("Hair", hair, 1.70, 1.56, radius=0.115,
+                           center=(0, 0.008, 1.66), scale=(0.95, 1.04, 1.05)))
+    return parts
+
+
 def _hands_and_shoes(mats, spec):
     skin = mats["skin"]
     shoe = mats["accessory"]
@@ -848,26 +1055,26 @@ def _hands_and_shoes(mats, spec):
     for s in (-1.0, 1.0):
         x = 0.275 * s * w
         # Wider and shallower than the old ball: a palm, not a wrist knob.
-        parts.append(sphere("Palm", 0.046, (x, -0.012, 0.742), skin, seg=10, rings=6,
+        parts.append(sphere("Palm", 0.046, (x, -0.012, 0.762), skin, seg=10, rings=6,
                             scale=(0.80, 0.62, 0.88)))
         # Four bent, tapering fingers with rounded tips. The two segments keep
         # the hand readable at conversation distance without adding a full
         # finger skeleton; the outer fingers are slightly shorter.
         for index, offset in enumerate((-0.024, -0.008, 0.008, 0.024)):
             fx = x + offset * s
-            tip_z = (0.692, 0.681, 0.684, 0.694)[index]
+            tip_z = (0.712, 0.701, 0.704, 0.714)[index]
             radius = 0.0115 if index in (1, 2) else 0.0105
-            parts.append(tube("Finger", [(fx, -0.018, 0.758),
-                                         (fx, -0.030, 0.726),
+            parts.append(tube("Finger", [(fx, -0.018, 0.778),
+                                         (fx, -0.030, 0.746),
                                          (fx, -0.042, tip_z)],
                               radius, skin, seg=6, caps=False))
             parts.append(sphere("Fingertip", radius, (fx, -0.042, tip_z), skin,
                                 seg=6, rings=4))
-        parts.append(tube("Thumb", [(x - 0.010 * s, -0.018, 0.758),
-                                    (x - 0.028 * s, -0.040, 0.740),
-                                    (x - 0.034 * s, -0.055, 0.718)],
+        parts.append(tube("Thumb", [(x - 0.010 * s, -0.018, 0.778),
+                                    (x - 0.028 * s, -0.040, 0.760),
+                                    (x - 0.034 * s, -0.055, 0.738)],
                           0.012, skin, seg=6, caps=False))
-        parts.append(sphere("ThumbTip", 0.012, (x - 0.034 * s, -0.055, 0.718), skin,
+        parts.append(sphere("ThumbTip", 0.012, (x - 0.034 * s, -0.055, 0.738), skin,
                             seg=6, rings=4))
         parts.append(box("Shoe", (0.10, 0.25, 0.075), (0.12 * s, -0.045, 0.04), shoe,
                          bevel=0.028, segs=1))
@@ -882,6 +1089,32 @@ def _hands_and_shoes(mats, spec):
     return parts
 
 
+def _hand_proto(mats, spec, side=-1.0):
+    """Connected hand: palm, four fingers and a thumb fused into one mesh.
+
+    The shipped hand is separate primitive parts that read as a mitten at
+    conversation distance; fusing the finger bases into the palm gives a
+    connected hand with readable finger separation. `side` is −1 (left, x<0)
+    or +1 (right, x>0).
+    """
+    hs = _hands_and_shoes(mats, spec)
+
+    def _cx(o):
+        xs = [v.co.x for v in o.data.vertices]
+        return (min(xs) + max(xs)) / 2
+
+    hand = [o for o in hs
+            if o.name.startswith(("Palm", "Finger", "Fingertip", "Thumb", "ThumbTip"))
+            and (_cx(o) < 0 if side < 0 else _cx(o) > 0)]
+    obj = join(hand, "HandL" if side < 0 else "HandR")
+    bm = bmesh.new()
+    bm.from_mesh(obj.data)
+    bmesh.ops.remove_doubles(bm, verts=bm.verts, dist=0.006)
+    bm.to_mesh(obj.data)
+    bm.free()
+    return obj
+
+
 def _clothing(spec, mats):
     layer = spec["layer"]
     cloth = mats["cloth"]
@@ -971,7 +1204,10 @@ def _clothing(spec, mats):
     return parts
 
 
-def build_character(name):
+def build_character(name, head="face"):
+    """Build one character. `head` picks the head source: "face" (current
+    primitive face), "proto" (connected-shell displacement prototype) or
+    "mh" (decimated MakeHuman head + project eyes/brows/mouth)."""
     spec = dict(CHARACTERS[name])
     if name == "npc_hoodie":
         spec["beard"] = True
@@ -986,7 +1222,12 @@ def build_character(name):
     _assign_body_slots(body, spec, body_mats)
     _auto_weights(body, layout)
 
-    head_parts = _face(mats, spec)
+    if head == "mh":
+        head_parts = _makehuman_head(mats, spec)
+    elif head == "proto":
+        head_parts = _head_proto(mats, spec)
+    else:
+        head_parts = _face(mats, spec)
     hair_style = spec["hair"] if spec["layer"] != "hood" else "buzz"
     head_parts += _hair(hair_style, mats["hair"])
     head = join(head_parts, "head")
@@ -1012,7 +1253,9 @@ def build_character(name):
                 return "Head" if p.z > 1.55 else "Neck"
             side = "L" if p.x < 0 else "R"
             if abs(p.x) > 0.26 and p.z > 0.8:
-                return f"Elbow{side}"
+                # Sleeve: the cuff follows the hand, the upper sleeve the elbow,
+                # so the sleeve does not separate from the hand at the wrist.
+                return f"Hand{side}" if p.z < 1.06 else f"Elbow{side}"
             if p.z < 0.25:
                 return f"Knee{side}"
             return None
@@ -2119,14 +2362,15 @@ def inspect_glb(path, category=None) -> dict:
     return result
 
 
-def adapt_glb(path, out_path, target_tris=8000):
+def adapt_glb(path, out_path, target_tris=16000):
     """Import an external GLB and adapt it toward the library contract.
 
     Applies node transforms, grounds the feet (lowest vertex at y = 0), welds
     duplicated seam vertices and decimates to `target_tris`, then exports the
-    result to `out_path` as a GLB. The five tint slots and the 13-bone contract
-    armature are deliberately NOT auto-mapped — that is a manual retopology/rig
-    step. Returns before/after measurements for the intake report.
+    result to `out_path` as a GLB. The five tint slots and the required 13 core
+    bones (optional extra bones are allowed) are deliberately NOT auto-mapped —
+    that is a manual retopology/rig step. Returns before/after measurements for
+    the intake report.
     """
     if bpy is None:
         return {"ok": False, "error": "adapt must run inside Blender"}
@@ -2521,8 +2765,8 @@ def main(argv=None):
     ada.add_argument("--file", required=True,
                      help="external GLB to adapt (absolute path; runs in Blender)")
     ada.add_argument("--out", required=True, help="where to write the adapted GLB")
-    ada.add_argument("--target-tris", type=int, default=8000,
-                     help="decimate target (default 8000)")
+    ada.add_argument("--target-tris", type=int, default=16000,
+                     help="decimate target (default 16000)")
     tex = sub.add_parser("texels", help="per-slot texel density of the character GLBs")
     tex.add_argument("--only", default="")
     tex.add_argument("--json", action="store_true")

tools/npc_parts.py

@@ -0,0 +1,330 @@
+#!/usr/bin/env python3
+"""Local part pipeline for the Blender NPC model overhaul.
+
+Builds, extracts, assembles, inspects and sheets the reusable head/face and hand
+parts before they are rolled into the shipped characters. It reuses the
+builders in ``blender_assets.py`` (no second face/hand implementation) and stays
+local-only and headless: the Blender commands run inside the flatpak, and the
+sheet/compare commands run with stdlib + Pillow.
+
+Part sources and preview GLBs live under ``tmp/npc-parts/<variant>/`` (gitignored).
+Only the assembled character GLBs, AO/maps, the manifest and the review sheets
+are committed; a part GLB is not a shipped asset.
+
+    # Build one part fresh from the current builders (head|face|hand_l|hand_r)
+    flatpak run org.blender.Blender --background \
+      --python "$PWD/tools/npc_parts.py" -- build --part face \
+      --variant npc_casual --out "$PWD/tmp/npc-parts/npc_casual/face.glb"
+    # Pull the current shipped head/hands out of the built character GLB
+    flatpak run org.blender.Blender --background \
+      --python "$PWD/tools/npc_parts.py" -- extract --part hand_l \
+      --variant npc_casual --out "$PWD/tmp/npc-parts/npc_casual/hand_l.glb"
+    # Assemble a variant (currently rebuilds the procedural character)
+    flatpak run org.blender.Blender --background \
+      --python "$PWD/tools/npc_parts.py" -- assemble --variant npc_casual \
+      --out "$PWD/tmp/npc-parts/npc_casual/assembled.glb"
+    # Inspect a part or assembled GLB (Blender import view)
+    flatpak run org.blender.Blender --background \
+      --python "$PWD/tools/npc_parts.py" -- inspect --file "$PWD/tmp/npc-parts/npc_casual/face.glb"
+    # Contact sheet / before-after comparison (outside Blender)
+    python3 tools/npc_parts.py sheet --dir tmp/npc-parts/npc_casual --out docs/blender_previews/sheet_parts.jpg
+    python3 tools/npc_parts.py compare --before DIR --after DIR --out sheet.jpg
+
+The flatpak sandbox cwd is /app/blender and cannot read /tmp, so every path is
+absolute and derived from this file's location.
+"""
+
+import argparse
+import math
+import sys
+from pathlib import Path
+
+# The flatpak sandbox may not put this script's directory on sys.path, so add it
+# explicitly so `import blender_assets` works from any cwd.
+_TOOLS = str(Path(__file__).resolve().parent)
+if _TOOLS not in sys.path:
+    sys.path.insert(0, _TOOLS)
+
+import blender_assets as ba  # same directory; no second implementation
+
+ROOT = Path(__file__).resolve().parent.parent
+PARTS_DIR = ROOT / "tmp" / "npc-parts"
+PROTOTYPE = "npc_casual"  # canonical one-variant prototype
+
+# The four buildable parts. `head` is the bare head shell; `face` is the shell
+# plus nose/eyes/mouth/ears; `hand_l`/`hand_r` are the left/right hand geometry.
+PART_NAMES = ("head", "face", "hand_l", "hand_r", "head_proto",
+              "hand_l_proto", "hand_r_proto", "head_mh")
+_HAND_PREFIXES = ("Palm", "Finger", "Fingertip", "Thumb", "ThumbTip")
+
+
+def _needs_blender(cmd):
+    if ba.bpy is not None:
+        return None
+    print(
+        f"npc_parts {cmd} runs inside Blender. Use:\n"
+        f"  flatpak run org.blender.Blender --background \\\n"
+        f"    --python \"$PWD/tools/npc_parts.py\" -- {cmd} ...",
+        file=sys.stderr,
+    )
+    return 2
+
+
+def _mats_and_spec(variant):
+    spec = dict(ba.CHARACTERS[variant])
+    mats = {slot: ba.material(slot) for slot in ba.SLOTS}
+    for extra in ("hivis", "reflective", "leather",
+                  "steel", "patch", "plastic_black", "rubber", "helmet"):
+        mats[extra] = ba.material(extra, textured_solid=True)
+    return mats, spec
+
+
+def _export_obj(obj, path):
+    """Export one object as a selection-only GLB (no .blend source side-effect)."""
+    path = Path(path)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    for o in ba.bpy.context.selected_objects:
+        o.select_set(False)
+    obj.select_set(True)
+    ba.bpy.context.view_layer.objects.active = obj
+    ba.bpy.ops.export_scene.gltf(
+        filepath=str(path), export_format="GLB", use_selection=True,
+        export_apply=True, export_animations=False, export_skins=True,
+        export_yup=True, export_materials="EXPORT", export_image_format="AUTO")
+    return path
+
+
+def build_part(name, variant, out, subdiv=48):
+    """Build one part fresh from the current builders (Blender-only)."""
+    mats, spec = _mats_and_spec(variant)
+    if name == "head":
+        obj = ba.sphere("Head", 0.155, (0, 0, 1.635), mats["skin"], seg=24,
+                        rings=16, scale=(0.92, 1.0, 1.12))
+        ba._shape_head_mesh(obj)
+    elif name == "face":
+        obj = ba.join(ba._face(mats, spec), "face")
+    elif name == "head_proto":
+        obj = ba.join(ba._head_proto(mats, spec, subdiv=subdiv), "head_proto")
+    elif name == "hand_l_proto":
+        obj = ba._hand_proto(mats, spec, side=-1.0)
+    elif name == "hand_r_proto":
+        obj = ba._hand_proto(mats, spec, side=1.0)
+    elif name == "head_mh":
+        obj = ba.join(ba._makehuman_head(mats, spec), "head_mh")
+    else:
+        side = -1.0 if name == "hand_l" else 1.0
+        hs = ba._hands_and_shoes(mats, spec)
+
+        def _center_x(obj):
+            xs = [v.co.x for v in obj.data.vertices]
+            return (min(xs) + max(xs)) / 2
+
+        hand = [o for o in hs if o.name.startswith(_HAND_PREFIXES)
+                and (_center_x(o) < 0 if side < 0 else _center_x(o) > 0)]
+        obj = ba.join(hand, name)
+    return _export_obj(obj, out)
+
+
+def _extract_group(mesh, group_name, out):
+    """Copy the vertices of one vertex group into a new standalone mesh."""
+    vg = mesh.vertex_groups.get(group_name)
+    if vg is None:
+        raise SystemExit(f"mesh {mesh.name} has no vertex group {group_name!r}")
+    bm = ba.bmesh.new()
+    bm.from_mesh(mesh.data)
+    deform = bm.verts.layers.deform.active
+    keep = {v.index for v in bm.verts
+            if deform is not None and vg.index in v[deform]}
+    if not keep:
+        bm.free()
+        raise SystemExit(f"vertex group {group_name!r} is empty in {mesh.name}")
+    doomed = [v for v in bm.verts if v.index not in keep]
+    ba.bmesh.ops.delete(bm, geom=doomed, context="VERTS")
+    bm.to_mesh(mesh.data)
+    bm.free()
+    return _export_obj(mesh, out)
+
+
+def extract_part(name, variant, out):
+    """Pull the current shipped head/hands out of the built character GLB.
+
+    The shipped mesh joins the head shell and its features into one Head-weighted
+    piece, so ``head`` and ``face`` both extract that piece; ``hand_l``/``hand_r``
+    extract the HandL/HandR-weighted geometry.
+    """
+    src = ba.asset_path("npc", variant)
+    if not src.is_file():
+        raise SystemExit(f"not built: {src}; run blender_assets.py build first")
+    ba.bpy.ops.wm.read_factory_settings(use_empty=True)
+    ba.bpy.ops.import_scene.gltf(filepath=str(src))
+    mesh = next((o for o in ba.bpy.context.scene.objects if o.type == "MESH"
+                 and o.name == "npc_base"), None)
+    if mesh is None:
+        raise SystemExit(f"no npc_base mesh in {src}")
+    group = ("Head" if name in ("head", "face", "head_proto")
+             else f"Hand{'L' if name in ('hand_l', 'hand_l_proto') else 'R'}")
+    return _extract_group(mesh, group, out)
+
+
+def assemble(variant, out, head="face"):
+    """Assemble a variant (currently rebuilds the procedural character).
+
+    This proves the end-to-end wiring; once parts are approved, this swaps the
+    new part GLBs in instead of calling ``build_character`` directly. Pass
+    ``head="mh"`` or ``head="proto"`` to build with the MakeHuman or prototype
+    head source.
+    """
+    objs = ba.build_character(variant, head=head)
+    mesh = next(o for o in objs if o.type == "MESH")
+    arm = next(o for o in objs if o.type == "ARMATURE")
+    out = Path(out)
+    out.parent.mkdir(parents=True, exist_ok=True)
+    for o in ba.bpy.context.selected_objects:
+        o.select_set(False)
+    for o in (arm, mesh):
+        o.select_set(True)
+    ba.bpy.context.view_layer.objects.active = mesh
+    ba.bpy.ops.export_scene.gltf(
+        filepath=str(out), export_format="GLB", use_selection=True,
+        export_apply=True, export_animations=False, export_skins=True,
+        export_yup=True, export_materials="EXPORT", export_image_format="AUTO")
+    return out
+
+
+def inspect(path):
+    result = ba.inspect_glb(str(path), category="npc")
+    ba.print_inspection(result)
+    return result
+
+
+def _pillow():
+    try:
+        from PIL import Image, ImageOps  # noqa: F401
+        return Image, ImageOps
+    except ImportError:
+        raise SystemExit("Pillow is required for sheet/compare (pip install pillow)")
+
+
+def _pngs(directory):
+    d = Path(directory)
+    if not d.is_dir():
+        raise SystemExit(f"not a directory: {d}")
+    files = sorted(d.glob("*.png"))
+    if not files:
+        raise SystemExit(f"no PNGs in {d}")
+    return files
+
+
+def make_sheet(directory, out, cols=4):
+    Image, ImageOps = _pillow()
+    files = _pngs(directory)
+    thumb_w = 512
+    tiles = []
+    for f in files:
+        im = Image.open(f).convert("RGB")
+        im = ImageOps.fit(im, (thumb_w, thumb_w), Image.LANCZOS)
+        tiles.append(im)
+    rows = (len(tiles) + cols - 1) // cols
+    sheet = Image.new("RGB", (cols * thumb_w, rows * thumb_w), (24, 24, 24))
+    for i, im in enumerate(tiles):
+        sheet.paste(im, ((i % cols) * thumb_w, (i // cols) * thumb_w))
+    out = Path(out)
+    out.parent.mkdir(parents=True, exist_ok=True)
+    sheet.save(out, quality=90)
+    print(f"sheet: {out} ({len(tiles)} tiles)")
+    return out
+
+
+def compare(before, after, out, cols=2):
+    Image, ImageOps = _pillow()
+    before_files = _pngs(before)
+    after_files = _pngs(after)
+    if len(before_files) != len(after_files):
+        print(f"warn: {len(before_files)} before vs {len(after_files)} after PNGs",
+              file=sys.stderr)
+    pairs = max(len(before_files), len(after_files))
+    thumb_w = 512
+    tiles = []
+    for i in range(pairs):
+        for files in (before_files, after_files):
+            if i < len(files):
+                im = Image.open(files[i]).convert("RGB")
+                im = ImageOps.fit(im, (thumb_w, thumb_w), Image.LANCZOS)
+            else:
+                im = Image.new("RGB", (thumb_w, thumb_w), (24, 24, 24))
+            tiles.append(im)
+    rows = (len(tiles) + cols - 1) // cols
+    sheet = Image.new("RGB", (cols * thumb_w, rows * thumb_w), (24, 24, 24))
+    for i, im in enumerate(tiles):
+        sheet.paste(im, ((i % cols) * thumb_w, (i // cols) * thumb_w))
+    out = Path(out)
+    out.parent.mkdir(parents=True, exist_ok=True)
+    sheet.save(out, quality=90)
+    print(f"compare: {out} ({pairs} pairs)")
+    return out
+
+
+def main(argv=None):
+    raw = list(argv if argv is not None else sys.argv[1:])
+    if "--" in raw:
+        raw = raw[raw.index("--") + 1:]
+    ap = argparse.ArgumentParser(description="Local NPC part pipeline")
+    sub = ap.add_subparsers(dest="cmd", required=True)
+
+    for cmd in ("build", "extract"):
+        s = sub.add_parser(cmd)
+        s.add_argument("--part", required=True, choices=PART_NAMES)
+        s.add_argument("--variant", default=PROTOTYPE)
+        s.add_argument("--out", required=True)
+        s.add_argument("--subdiv", type=int, default=48,
+                       help="head_proto UV-sphere u-segments (24/48/64 variants)")
+
+    asm = sub.add_parser("assemble")
+    asm.add_argument("--variant", default=PROTOTYPE)
+    asm.add_argument("--out", required=True)
+    asm.add_argument("--head", default="face", choices=("face", "proto", "mh"),
+                     help="head source (face | proto | mh)")
+
+    insp = sub.add_parser("inspect")
+    insp.add_argument("--file", required=True)
+
+    sh = sub.add_parser("sheet")
+    sh.add_argument("--dir", required=True)
+    sh.add_argument("--out", required=True)
+    sh.add_argument("--cols", type=int, default=4)
+
+    cm = sub.add_parser("compare")
+    cm.add_argument("--before", required=True)
+    cm.add_argument("--after", required=True)
+    cm.add_argument("--out", required=True)
+
+    args = ap.parse_args(raw)
+
+    if args.cmd == "sheet":
+        make_sheet(args.dir, args.out, args.cols)
+        return 0
+    if args.cmd == "compare":
+        compare(args.before, args.after, args.out)
+        return 0
+
+    # Everything else runs inside Blender.
+    code = _needs_blender(args.cmd)
+    if code is not None:
+        return code
+    ba.reset_scene()
+    if args.cmd == "build":
+        build_part(args.part, args.variant, args.out, subdiv=args.subdiv)
+        print(f"built part {args.part} -> {args.out}")
+    elif args.cmd == "extract":
+        extract_part(args.part, args.variant, args.out)
+        print(f"extracted {args.part} -> {args.out}")
+    elif args.cmd == "assemble":
+        assemble(args.variant, args.out, head=args.head)
+        print(f"assembled {args.variant} -> {args.out}")
+    elif args.cmd == "inspect":
+        inspect(args.file)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

tools/npc_pipeline.py

@@ -23,7 +23,8 @@ Contract (frozen in ADR-0013 and docs/blender-assets.md):
     (plus Hips/Spine/Neck as parents)
   * material slots: skin, cloth, pants, accessory, hair
   * neutral albedo + normal + packed ORM maps, albedo tinted at runtime
-  * <= 6000 triangles / 4000 vertices, UVs in [0,1], feet at y ~= 0
+  * <= 16000 triangles / 16000 vertices, UVs in [0,1], feet at y ~= 0
+  * the 13 core bones are required; extra optional bones are allowed
 """
 
 import argparse
@@ -44,8 +45,8 @@ BONES = [
     "Head", "HipL", "HipR", "KneeL", "KneeR",
     "ShoulderL", "ShoulderR", "ElbowL", "ElbowR", "HandL", "HandR",
 ]
-MAX_TRIANGLES = 6000
-MAX_VERTICES = 4000
+MAX_TRIANGLES = 16000
+MAX_VERTICES = 16000
 TEX_SIZE = 256
 AI_DIR = TEX_DIR / "ai"
 # Base material slots that get an AI fabric albedo (`prepare` layers them over

tools/tests/test_blender_assets.py

@@ -9,11 +9,10 @@ class CatalogueTests(unittest.TestCase):
     def test_contract_matches_npc_pipeline(self):
         self.assertEqual(ba.SLOTS, npc_pipeline.SLOTS)
         self.assertEqual(sorted(ba.BONES), sorted(npc_pipeline.BONES))
-        # The base mesh keeps the frozen 6000/4000 contract; the eight library
-        # variants have their own 8000/8000 detail budget (documented in
-        # blender-assets.md and covered by smoke_npc_budget.gd).
-        self.assertLessEqual(ba.CHAR_MAX_TRIS, 8000)
-        self.assertLessEqual(ba.CHAR_MAX_VERTS, 8000)
+        # The character cap was raised to 16000/16000 for the head/face/hand
+        # overhaul; the 13 core bones stay required and extra bones are optional.
+        self.assertLessEqual(ba.CHAR_MAX_TRIS, 16000)
+        self.assertLessEqual(ba.CHAR_MAX_VERTS, 16000)
 
     def test_gear_uses_known_attach_points(self):
         for name, attach in ba.GEAR.items():
@@ -188,10 +187,17 @@ class InspectionTests(unittest.TestCase):
         self.assertEqual(result["bones_missing"], [])
         self.assertEqual(result["budget"]["max_triangles"], ba.CHAR_MAX_TRIS)
 
+    def test_extra_optional_bones_are_allowed(self):
+        stats = self.stats(bones=list(ba.BONES) + ["Hips", "Spine", "Neck",
+                                                   "FingerL", "FingerR"])
+        result = ba.analyse_inspection(stats)
+        self.assertTrue(result["ok"], result["issues"])
+        self.assertEqual(result["bones_missing"], [])
+
     def test_character_contract_failures_are_listed(self):
         stats = self.stats(mesh_nodes=["Armature"], skinned=False, unskinned=["Armature"],
                            materials=["cloth"], bones=["Head"], meshes_without_uv=1,
-                           triangles=9000, split_vertices=9000,
+                           triangles=17000, split_vertices=17000,
                            world_bounds={"min": [-0.3, -0.4, -0.2], "max": [0.3, 1.2, 0.2]})
         issues = "\n".join(ba.analyse_inspection(stats)["issues"])
         self.assertIn("no mesh node named npc_base", issues)
@@ -199,8 +205,8 @@ class InspectionTests(unittest.TestCase):
         self.assertIn("missing material slot skin", issues)
         self.assertIn("mesh not skinned", issues)
         self.assertIn("mesh(es) without UVs", issues)
-        self.assertIn(f"triangles 9000 > {ba.CHAR_MAX_TRIS}", issues)
-        self.assertIn(f"glTF vertices 9000 > {ba.CHAR_MAX_VERTS}", issues)
+        self.assertIn(f"triangles 17000 > {ba.CHAR_MAX_TRIS}", issues)
+        self.assertIn(f"glTF vertices 17000 > {ba.CHAR_MAX_VERTS}", issues)
         self.assertIn("feet not on the ground", issues)
         self.assertIn("unexpected height", issues)
 

tools/tests/test_npc_parts.py

@@ -0,0 +1,52 @@
+import contextlib
+import io
+import tempfile
+import unittest
+from pathlib import Path
+
+import npc_parts
+
+
+class CliTests(unittest.TestCase):
+    def test_part_names_are_known(self):
+        self.assertEqual(
+            set(npc_parts.PART_NAMES),
+            {"head", "face", "hand_l", "hand_r", "head_proto",
+             "hand_l_proto", "hand_r_proto", "head_mh"},
+        )
+
+    def test_blender_commands_fail_cleanly_without_bpy(self):
+        # Outside Blender, build/extract/assemble/inspect must explain the
+        # flatpak invocation instead of raising.
+        for cmd in ("build", "extract", "assemble", "inspect"):
+            with self.subTest(cmd=cmd):
+                code = npc_parts._needs_blender(cmd)
+                self.assertEqual(code, 2)
+
+    def test_sheet_rejects_missing_directory(self):
+        with self.assertRaises(SystemExit) as ctx:
+            npc_parts.make_sheet("/nonexistent/does-not-exist", "/tmp/x.jpg")
+        self.assertIn("not a directory", str(ctx.exception))
+
+    def test_compare_rejects_missing_directory(self):
+        with self.assertRaises(SystemExit) as ctx:
+            npc_parts.compare("/nonexistent", "/nonexistent2", "/tmp/x.jpg")
+        self.assertIn("not a directory", str(ctx.exception))
+
+
+class SheetTests(unittest.TestCase):
+    def test_sheet_builds_from_real_pngs(self):
+        with tempfile.TemporaryDirectory() as td:
+            td = Path(td)
+            Image, _ = npc_parts._pillow()
+            for i in range(3):
+                im = Image.new("RGB", (64, 64), (i * 60, 0, 0))
+                im.save(td / f"f{i}.png")
+            out = td / "sheet.jpg"
+            result = npc_parts.make_sheet(str(td), str(out))
+            self.assertEqual(Path(result).suffix, ".jpg")
+            self.assertTrue(out.is_file())
+
+
+if __name__ == "__main__":
+    unittest.main()

tools/tests/test_npc_pipeline.py

@@ -13,8 +13,8 @@ class NpcContractTests(unittest.TestCase):
                      "ShoulderL", "ShoulderR", "ElbowL", "ElbowR",
                      "HandL", "HandR"]:
             self.assertIn(bone, npc_pipeline.BONES)
-        self.assertLessEqual(npc_pipeline.MAX_TRIANGLES, 6000)
-        self.assertLessEqual(npc_pipeline.MAX_VERTICES, 4000)
+        self.assertLessEqual(npc_pipeline.MAX_TRIANGLES, 16000)
+        self.assertLessEqual(npc_pipeline.MAX_VERTICES, 16000)
 
     def test_textures_exist_for_every_slot(self):
         for slot in npc_pipeline.SLOTS: