AGENTS.md

@@ -210,8 +210,8 @@ Any change that affects the game's appearance — meshes, materials, lighting, l
 
 1. Run `Tools/render_screenshots.sh` (rebuilds `Game/GigLine/Content/Test/ReviewMap.umap` from current content, runs the game on it, captures the fixed camera list, copies the PNGs into `Screenshots/`).
 2. Optional pre-check with a vision model: `Tools/judge_screenshot.py --image <shot.png> --expect "<what it should show>"` (or `--shots` to run every shot in the README) flags likely-missing content before a human looks. It reads `OPENROUTER_API_KEY` from `.env` (ignored). Small helper only — it never replaces the human verdict.
-3. Update `Screenshots/README.md`: one row per screenshot with what it shows and an approval state; describe any new shots or scene changes in the same change.
+3. Update `Screenshots/README.md` **in the same change as any visual work** — every change that affects appearance, not only new shots: the image is **embedded inline** (`![alt](demo/<shot>.png)`) with its view, expected content, verification and approval state, plus one row in the status table at the top. The review happens in the file; a path alone is not a review, and a shot whose README section is stale is a defect.
 4. The PNGs **are committed** so reviewers see exactly what the build rendered (`.gitignore` does not exclude them). Keep them in sync with this README: drop retired shots in the same change.
-5. Wait for the user's approval before treating a visual change as done; record approval by ticking the table in `Screenshots/README.md`.
+5. Wait for the user's approval before treating a visual change as done; record approval by ticking both the shot's section and its row in the status table in `Screenshots/README.md`.
 
 New content that needs a different camera angle gets a new entry in the shot list in `Tools/ue_build_review_map.py`.

Screenshots/README.md

@@ -12,19 +12,83 @@ Tools/render_screenshots.sh --verify
 
 Stages the demo shot cameras, runs the game on `/Game/Hollywood/DemoMap`, copies the PNGs into `Screenshots/demo/` and then runs [`Tools/visual_loop.py`](../Tools/visual_loop.py) `--verify` to check that each shot still shows the content its expectation describes. About a minute.
 
-## The shot list
+## Status at a glance
 
-Each shot has an **expectation** in [`Tools/visual_targets.json`](../Tools/visual_targets.json) — the content the capture must show — and a verification state produced by `--verify`: it fails if the frame is blank, the wrong size, or has no tonal range.
+Every shot is embedded below, in order, so the whole review happens in this file.
 
-| # | File | View | Expected content | Verified | Approved |
-| --- | --- | --- | --- | --- | --- |
-| 1 | `demo/review-demo-spawn-view.png` | north sidewalk | The whole south block: the neoclassical hero façade between its neighbours, both sidewalks and the road in the foreground | ☑ 2026-11-09 | ☑ 2026-11-09 |
-| 2 | `demo/review-demo-street-level.png` | eye height, north side | Street level: the hero colonnade with the adjacent frontage buildings either side, shopfronts at pavement level | ☑ 2026-11-09 | ☑ 2026-11-09 |
-| 3 | `demo/review-demo-crossing.png` | along the crosswalk | The designated mid-block crossing (s=130 m, UE X −14956): zebra bars on the asphalt, south frontage and colonnade behind | ☑ 2026-11-09 | ☑ 2026-11-09 |
-| 4 | `demo/review-demo-north-buildings.png` | across the Boulevard | The two north-side buildings (TCL Chinese Theatre, Madame Tussaud's) from the south side, full height in frame | ☑ 2026-11-09 | ☑ 2026-11-09 |
-| 5 | `demo/review-demo-third-person.png` | third-person boom, 6 m behind the pawn | The player's own visible body on the north sidewalk, seen from behind, with the hero façade across the street. Captured with `-thirdperson`, which starts the pawn in the third-person rig | ☑ 2026-11-09 | ☐ pending |
+| # | Shot | Verified | Approved |
+| --- | --- | --- | --- |
+| 1 | [Spawn view](#1-spawn-view) | ☑ 2026-11-09 | ☑ 2026-11-09 |
+| 2 | [Street level](#2-street-level) | ☑ 2026-11-09 | ☑ 2026-11-09 |
+| 3 | [Crossing](#3-crossing) | ☑ 2026-11-09 | ☑ 2026-11-09 |
+| 4 | [North buildings](#4-north-buildings) | ☑ 2026-11-09 | ☑ 2026-11-09 |
+| 5 | [Third-person body](#5-third-person-body) | ☑ 2026-11-09 | ☐ pending |
 
-Approval is per shot, in the table above (owner review of the `0.1.4` set, recorded in [`Docs/reviews/0.1.4-review.md`](../Docs/reviews/0.1.4-review.md)). Add a row when a shot is added; remove the file in the same change when a shot is retired.
+**Verified** is what `--verify` reports: the frame is not blank, is the right size, and has tonal range. **Approved** is the owner's verdict, recorded here. Each shot also has an **expectation** in [`Tools/visual_targets.json`](../Tools/visual_targets.json) describing the content it must show.
+
+---
+
+## 1. Spawn view
+
+![Spawn view: the whole south block from the north sidewalk](demo/review-demo-spawn-view.png)
+
+- **File:** `demo/review-demo-spawn-view.png`
+- **View:** north sidewalk, 14 m back, level horizon
+- **Expected content:** the whole south block — the neoclassical hero façade between its neighbouring buildings, both sidewalks and the road in the foreground
+- **Verified:** ☑ 2026-11-09 · **Approved:** ☑ 2026-11-09
+
+---
+
+## 2. Street level
+
+![Street level: the hero colonnade at eye height](demo/review-demo-street-level.png)
+
+- **File:** `demo/review-demo-street-level.png`
+- **View:** eye height, north side
+- **Expected content:** the hero colonnade with the adjacent frontage buildings either side, shopfronts at pavement level
+- **Verified:** ☑ 2026-11-09 · **Approved:** ☑ 2026-11-09
+
+---
+
+## 3. Crossing
+
+![Crossing: the designated mid-block crossing with zebra bars](demo/review-demo-crossing.png)
+
+- **File:** `demo/review-demo-crossing.png`
+- **View:** from the north sidewalk along the crosswalk
+- **Expected content:** the designated mid-block crossing (s=130 m, UE X −14956) — zebra bars on the asphalt, south frontage and colonnade behind
+- **Verified:** ☑ 2026-11-09 · **Approved:** ☑ 2026-11-09
+
+---
+
+## 4. North buildings
+
+![North buildings: TCL Chinese Theatre and Madame Tussaud's from the south](demo/review-demo-north-buildings.png)
+
+- **File:** `demo/review-demo-north-buildings.png`
+- **View:** across the Boulevard from the south side
+- **Expected content:** the two north-side buildings (TCL Chinese Theatre, Madame Tussaud's), full height in frame
+- **Verified:** ☑ 2026-11-09 · **Approved:** ☑ 2026-11-09
+
+---
+
+## 5. Third-person body
+
+![Third-person body: the player pawn seen from behind on the north sidewalk](demo/review-demo-third-person.png)
+
+- **File:** `demo/review-demo-third-person.png`
+- **View:** third-person boom, ~6 m behind the pawn, captured with `-thirdperson` so the pawn starts in the third-person rig
+- **Expected content:** the player's own visible body on the north sidewalk, seen from behind, with the hero façade across the street
+- **Verified:** ☑ 2026-11-09 · **Approved:** ☐ pending
+
+What this shot is evidence for, and what it is not:
+
+- **Implemented and visible:** the pawn carries a visible skeletal body with the warm skin material, and a spring-arm camera with collision testing. The **V** toggle swaps first and third person; the shipped default stays first person and the review passes `-thirdperson`.
+- **Not working:** the figure is in **bind pose, arms out**. The idle clip is bound and `PlayAnimation` is called — the run logs `GigLine: playing body clip Character_AnimHuman_rig_GigLine_Idle` — so the call succeeds and the pose does not apply. Tracked in `TODO.md` under "Verify animation plays correctly on the imported rig" with that evidence.
+- **Camera collision is implemented but unproven:** the spawn point has open space behind it, so no shot exercises the arm shortening.
+- The skin material needed `used_with_skeletal_mesh=True`; without it Unreal silently substituted the default grey, which is what the first capture of this shot showed.
+
+---
 
 ## The iteration loop (uncommitted)
 
@@ -41,26 +105,26 @@ Note the comparison is only meaningful when the shot and the reference frame the
 ## Scene conventions
 
 - **Demo map** (`/Game/Hollywood/DemoMap`): fixed daytime — sun pitch −62 / yaw 120 (intensity 4, warm), sky light 2.6, sky atmosphere, height fog, fixed exposure.
-- **Cameras**: elevation shots sit at their target height (pitch 0, so verticals stay parallel) and use a 42–55° lens to fill the frame from across the street.
+- **Cameras**: elevation shots sit at their target height (pitch 0, so verticals stay parallel) and use a 42–68° lens to fill the frame from across the street.
 - **Materials**: every surface carries a look-developed material from `Tools/ue_build_demo_map.py` — noise-blended base colour, masonry coursing, and a generated texture set (`Tools/generate_facade_textures.py`) sampled world-aligned. Explicit roughness and specular per surface type.
 
 ## Known cosmetic issues
 
-- Hero façade renders pale: the stone material is a graph and a texture set, not a scanned surface (the `0.1.4` façade pass is in progress).
-- Banners sit on the column line rather than flush to the wall (they hang on the columns in the photographs, so this is acceptable).
-- Between kerb and building line the walkable surface is the terrain mesh, not a modelled pavement.
-- The El Capitan Theatre has no marquee or blade sign yet — the feature that makes it read as itself.
+Every issue is tracked in `TODO.md` under the version that will fix it; an issue with no ticket is a bug in the plan, not a note.
 
-## 0.2.0 third-person body — what to look at
+| Issue | Where it is tracked | State |
+| --- | --- | --- |
+| Hero stone renders pale — the material is a procedural graph and a generated texture set, not a measured surface | `0.9.0` → measured material library | Open |
+| Hero façade has no doors at street level left and right of the central bay, and the central-bay elements are not positioned as the photographs show | `0.9.0` → per-building models, hero façade | Open |
+| Third-person body renders in bind pose: the clip is bound and `PlayAnimation` is called, but the pose does not apply | `0.2.0` → verify animation plays correctly | Open (blocking `0.2.0`) |
+| Camera collision is implemented but never exercised against a wall | `0.2.0` → camera collision | Open |
+| Between kerb and building line the walkable surface is the terrain mesh, not a modelled pavement | `0.6.0` → visual polish | Open |
 
-Shot 5 is the review for the third-person rig. It is **not** a finished body: the figure is in bind pose, arms out.
+Accepted by the owner, not a defect:
 
-What is implemented and visible:
+- Banners hang on the column line rather than flush to the wall — that is how they hang in the photographs.
 
-- The pawn carries a visible skeletal body with the warm skin material (the material needed `used_with_skeletal_mesh=True`; without it Unreal silently substituted the default grey, which is what the first render showed).
-- A spring-arm camera with collision testing, and a **V** toggle between first and third person. The shipped default stays first person; the review passes `-thirdperson` so the shot is reproducible.
+Resolved and removed:
 
-What is **not** working, with evidence:
-
-- The idle clip is bound and `PlayAnimation` is called — the run logs `GigLine: playing body clip Character_AnimHuman_rig_GigLine_Idle` — but the body still renders in bind pose. The clip therefore is not deforming the mesh; that is the open defect, tracked in `TODO.md` under "Verify animation plays correctly on the imported rig".
-- The arms-down offsets are baked into the clips as a base on top of the A-pose bind (`BASE` in `Tools/character_anim_build.py`), so a correct playback should show arms down. Seeing them out is the same defect, not a missing offset.
+- "The El Capitan Theatre has no marquee or blade sign" — `Tools/ue_stage_theatre_trim.py` stages all six trim actors; verified in `/tmp/gigline/theatre-import.txt`.
+- "Materials are not yet created in Blender or fully integrated" — contradicted by the scene conventions above.