docs(review): embed every screenshot inline so the review happens in the file

Each shot now has its own section with the image embedded, its view, expected
content and both verdicts, plus a status table at the top that links to them.
A path alone was not a review: the owner had to open five PNGs to judge a pass.

Also recorded in AGENTS.md (a path is not a review; approval ticks both the section
and the table row), the two retail assets and tools in the arc42 building block
view and the combined architecture.md, and prettier-formatted the changed files.

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`: 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 point is that the review happens in the file; a path alone is not a review. Describe any new shots or scene changes in the same change.
 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`.

Art/blender/retail/ref-analysis.md

@@ -1,11 +1,10 @@
 # Reference analysis — retail frontage, 0.1.6
 
-Phase 0 of the `references` pack (reference-image-match). Written before any geometry,
+Phase 0 of the `references` pack (reference-image-match). Written before any geometry, because the pass that produced the hero façade skipped it and cost two rebuilds.
-because the pass that produced the hero façade skipped it and cost two rebuilds.
 
 ## Source
 
-| | |
+|  |  |
 | --- | --- |
 | Image | `Art/reference/retail-neighbours/01-lee-drug-and-neighbor.jpg` (1920×953) |
 | Author / licence | Gb321, own work, **CC BY-SA 4.0** — attribution required |
@@ -13,19 +12,13 @@ because the pass that produced the hero façade skipped it and cost two rebuilds
 | Description | "Lee Drug and 6806 Hollywood Buildings in Hollywood" |
 | Coverage | Both target buildings in one frame, mid-morning sun from the south-east |
 
-**One photograph is the whole evidence base for 6800 and 6806–6820.** It is a street-level
+**One photograph is the whole evidence base for 6800 and 6806–6820.** It is a street-level oblique, not an elevation: verticals converge, the ground floor of 6806–6820 is partly behind a parked car, and the Lee Drug shopfront is behind a bus. Everything below that the photo does not resolve is marked _assumed_ and is carried into the part report.
-oblique, not an elevation: verticals converge, the ground floor of 6806–6820 is partly behind
-a parked car, and the Lee Drug shopfront is behind a bus. Everything below that the photo does
-not resolve is marked *assumed* and is carried into the part report.
 
-**6822 Budget has no photograph.** It is a 6.0 m × 5.5 m single-storey sliver west of
+**6822 Budget has no photograph.** It is a 6.0 m × 5.5 m single-storey sliver west of 6806–6820, and the TODO item already records that Commons has nothing usable. It stays a blockout extrusion and the item is deferred rather than guessed.
-6806–6820, and the TODO item already records that Commons has nothing usable. It stays a
-blockout extrusion and the item is deferred rather than guessed.
 
 ## Measured (not from the photo)
 
-From `Geo/raw/osm-api-map-2026-11-06.osm` and the blockout, in the shared frame
+From `Geo/raw/osm-api-map-2026-11-06.osm` and the blockout, in the shared frame (metres, X east, Y north, Z from the project datum):
-(metres, X east, Y north, Z from the project datum):
 
 | Building | OSM way | X | Front face Y | Height | Depth |
 | --- | --- | --- | --- | --- | --- |
@@ -33,9 +26,7 @@ From `Geo/raw/osm-api-map-2026-11-06.osm` and the blockout, in the shared frame
 | 6806–6820 | 424024150 | −66.08 … −33.07 | −12.52 | 12.10 m | 30.8 m |
 | 6822 Budget | 424024144 | −78.54 … −72.52 | −12.92 | 5.50 m | 15.4 m |
 
-Both target buildings are 12.10 m tall, which makes the *relative* proportions in the photo
+Both target buildings are 12.10 m tall, which makes the _relative_ proportions in the photo directly usable: the parapet line, the cornice and the shopfront line can be read as fractions of the frame height.
-directly usable: the parapet line, the cornice and the shopfront line can be read as fractions
-of the frame height.
 
 ## 6800 Lee Drug — reading
 
@@ -44,9 +35,9 @@ of the frame height.
 | Subject | Corner retail block at Hollywood × Highland; the street face and the corner return are both visible |
 | Silhouette | Long low box, broken by a **rounded corner tower** that rises above the frontage parapet; the parapet is **stepped**, not flat |
 | Storeys | Two zones, not storeys: a tall shopfront zone and a single tall display wall above it |
-| Proportion (vertical) | Shopfront ≈ 0 → 0.36 H; bronze cornice ≈ 0.36 → 0.43 H; mural + lettering wall ≈ 0.43 → 0.82 H; stepped parapet ≈ 0.82 → 1.0 H (*assumed split; read off the frame, ±0.03 H*) |
+| Proportion (vertical) | Shopfront ≈ 0 → 0.36 H; bronze cornice ≈ 0.36 → 0.43 H; mural + lettering wall ≈ 0.43 → 0.82 H; stepped parapet ≈ 0.82 → 1.0 H (_assumed split; read off the frame, ±0.03 H_) |
 | Proportion (horizontal) | Corner tower occupies ≈ 4 m of the east end; eight mural panels at roughly 2.2 m centres along the frontage |
-| Colour | Cream stucco wall `#EDE6D8`, bronze/brown cornice `#6B4A2F`, near-black mural plates `#1C1A18`, dark glazing `#20262A` (*sampled from the frame*) |
+| Colour | Cream stucco wall `#EDE6D8`, bronze/brown cornice `#6B4A2F`, near-black mural plates `#1C1A18`, dark glazing `#20262A` (_sampled from the frame_) |
 | Unique features | Stepped Deco parapet with 4 horizontal reveal lines; projecting bronze cornice; row of black celebrity-portrait panels; large dark "SOUVENIRS OF …" lettering on the upper wall; shopfront glazing with slim mullions |
 | Mood | 1930s Deco retail, freshly painted, bright midday |
 
@@ -55,17 +46,14 @@ of the frame height.
 | Category | Observation |
 | --- | --- |
 | Silhouette | Flat-fronted two-storey block; parapet steps up in fins at the west end |
-| Proportion (vertical) | Shopfront ≈ 0 → 0.32 H; burgundy fascia band ≈ 0.32 → 0.38 H; window storey ≈ 0.38 → 0.62 H; blank wall + parapet ≈ 0.62 → 1.0 H (*assumed*) |
+| Proportion (vertical) | Shopfront ≈ 0 → 0.32 H; burgundy fascia band ≈ 0.32 → 0.38 H; window storey ≈ 0.38 → 0.62 H; blank wall + parapet ≈ 0.62 → 1.0 H (_assumed_) |
 | Horizontal | Brown pilaster strips divide the frontage into roughly 3 m bays; seven upper windows across 33 m |
 | Colour | Same cream stucco; brown pilasters `#6B4A2F`; **burgundy-green** fascia `#5B3A3A`; white window frames |
 | Unique features | Banded parapet with 3 reveal lines; white-framed upper windows with security bars; shopfront glazing behind a burgundy fascia |
 
 ## Camera match (for the review shot)
 
-The photo is a street-level oblique from the **north** side looking south-east, subject filling
+The photo is a street-level oblique from the **north** side looking south-east, subject filling ~80 % of the frame width. The demo review shot must reproduce that: camera at 1.7 m on the north sidewalk, yaw toward the south frontage, 35–42° lens, both buildings in frame. A wide block view will not compare usefully against this crop.
-~80 % of the frame width. The demo review shot must reproduce that: camera at 1.7 m on the
-north sidewalk, yaw toward the south frontage, 35–42° lens, both buildings in frame. A wide
-block view will not compare usefully against this crop.
 
 ## Assumptions to carry into the model report
 

Docs/Architecture/05_building_block_view.md

@@ -47,6 +47,7 @@ Static meshes and materials in `/Game/Hollywood/Site/`:
 | `SM_HeroFacade` | El Capitan Entertainment Centre detailed façade |
 | `SM_ElCapitanTheatre`, `SM_Budget_6822`, `SM_Hollywood_6806`, `SM_Hollywood_6902`, `SM_Hollywood_6922`, `SM_LeeDrug_6800` | South block frontage (6 buildings) |
 | `SM_Madame_Tussauds`, `SM_TCL_Chinese_Theatre` | North-side buildings (within 50 m) |
+| `SM_Retail_LeeDrug`, `SM_Retail_6806` | Retail trim over 6800 and 6806–6820, modelled from their own photograph (`Tools/retail_frontage_build.py`, staged as `RetailTrim_*`). `6822 Budget` stays a bare volume: no photograph exists. |
 
 ### Art Pipeline
 
@@ -54,13 +55,14 @@ Python scripts in `Tools/` drive the content pipeline:
 
 | Script group | Purpose |
 | --- | --- |
-| `export_*`, `hero_facade_build` | Blender headless export (FBX) |
+| `export_*`, `hero_facade_build`, `retail_frontage_build`, `theatre_trim_build`, `facade_kit_build` | Blender headless export (FBX); trim builders work in world coordinates |
-| `ue_import_*`, `ue_hero_facade_import` | Unreal headless import + placement |
+| `ue_import_*`, `ue_hero_facade_import`, `ue_import_retail_detail` | Unreal headless import + placement |
 | `ue_build_demo_map`, `ue_build_review_map` | Map assembly (lighting, meshes, player start) |
 | `ue_create_input_assets` | Enhanced Input actions + mapping context |
 | `render_screenshots.sh` | Screenshot capture pipeline |
 | `judge_screenshot.py` | Vision-model pre-check (optional) |
 | `input_emulation.py`, `input_test.py` | OS-level virtual keyboard/mouse injection for input verification |
+| `Tools/_common.py` | Pure helper shared by Blender builders, importable without Blender (bay layout) |
 | `Tools/tests/` | Stdlib `unittest` tests for the pure parts of the tools (`requirements-tools.txt`) |
 | `Geo/tools/mapbox_buildings.py` | Second height source: Mapbox `mapbox-streets-v8` building data vs our OSM heights |
 

Docs/Architecture/architecture.md

@@ -191,6 +191,7 @@ Static meshes and materials in `/Game/Hollywood/Site/`:
 | `SM_HeroFacade` | El Capitan Entertainment Centre detailed façade |
 | `SM_ElCapitanTheatre`, `SM_Budget_6822`, `SM_Hollywood_6806`, `SM_Hollywood_6902`, `SM_Hollywood_6922`, `SM_LeeDrug_6800` | South block frontage (6 buildings) |
 | `SM_Madame_Tussauds`, `SM_TCL_Chinese_Theatre` | North-side buildings (within 50 m) |
+| `SM_Retail_LeeDrug`, `SM_Retail_6806` | Retail trim over 6800 and 6806–6820, modelled from their own photograph (`Tools/retail_frontage_build.py`, staged as `RetailTrim_*`). `6822 Budget` stays a bare volume: no photograph exists. |
 
 ### Art Pipeline
 
@@ -198,13 +199,14 @@ Python scripts in `Tools/` drive the content pipeline:
 
 | Script group | Purpose |
 | --- | --- |
-| `export_*`, `hero_facade_build` | Blender headless export (FBX) |
+| `export_*`, `hero_facade_build`, `retail_frontage_build`, `theatre_trim_build`, `facade_kit_build` | Blender headless export (FBX); trim builders work in world coordinates |
-| `ue_import_*`, `ue_hero_facade_import` | Unreal headless import + placement |
+| `ue_import_*`, `ue_hero_facade_import`, `ue_import_retail_detail` | Unreal headless import + placement |
 | `ue_build_demo_map`, `ue_build_review_map` | Map assembly (lighting, meshes, player start) |
 | `ue_create_input_assets` | Enhanced Input actions + mapping context |
 | `render_screenshots.sh` | Screenshot capture pipeline |
 | `judge_screenshot.py` | Vision-model pre-check (optional) |
 | `input_emulation.py`, `input_test.py` | OS-level virtual keyboard/mouse injection for input verification |
+| `Tools/_common.py` | Pure helper shared by Blender builders, importable without Blender (bay layout) |
 | `Tools/tests/` | Stdlib `unittest` tests for the pure parts of the tools (`requirements-tools.txt`) |
 | `Geo/tools/mapbox_buildings.py` | Second height source: Mapbox `mapbox-streets-v8` building data vs our OSM heights |
 

Screenshots/README.md

@@ -12,19 +12,86 @@ 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 |
+| #   | Shot                                  | 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 |
+| 1   | [Spawn view](#1-spawn-view)           | ☑ 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 |
+| 2   | [Street level](#2-street-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 |
+| 3   | [Crossing](#3-crossing)               | ☑ 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 |
+| 4   | [North buildings](#4-north-buildings) | ☑ 2026-11-09 | ☑ 2026-11-09 |
-| 5 | `demo/review-demo-retail-frontage.png` | north sidewalk, level horizon | The retail run beside the hero: 6800 Lee Drug's bronze cornice, mural row and parapet next to 6806–6820's burgundy fascia, pilasters and window storey | ☑ 2026-11-09 | ☐ pending |
+| 5   | [Retail frontage](#5-retail-frontage) | ☑ 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. Retail frontage
+
+![Retail frontage: 6800 Lee Drug and 6806–6820 from across the street](demo/review-demo-retail-frontage.png)
+
+- **File:** `demo/review-demo-retail-frontage.png`
+- **View:** north sidewalk, level horizon, 68° lens
+- **Expected content:** the retail run beside the hero — 6800 Lee Drug's bronze cornice, mural row and parapet next to 6806–6820's burgundy fascia, pilasters and window storey
+- **Verified:** ☑ 2026-11-09 · **Approved:** ☐ pending
+
+Read this one against the reference photograph it was modelled from: `Art/reference/retail-neighbours/01-lee-drug-and-neighbor.jpg` (Gb321, CC BY-SA 4.0).
+
+Known gaps in this first pass, recorded rather than hidden:
+
+- **The parapet reads as a blank white band.** It is modelled as one 2.18 m wall with four 0.10 m reveal strips, and at review distance the strips disappear into the wash.
+- **The mural row and lettering band barely read.** They are shallow plates (0.06–0.08 m) on the same plane as the wall; they need either depth or a decal before they read as the photographs' black-framed panels.
+- **The corner tower is a plain cylinder with two cap rings** — the stepped Deco profile in the photograph is richer than that.
+- **The camera crops the east end** of Lee Drug at 68° from the north sidewalk.
+- **6822 Budget is untouched** and still a bare blockout volume: no photograph of it exists.
+
+---
 
 ## The iteration loop (uncommitted)
 
@@ -41,7 +108,7 @@ 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
@@ -50,20 +117,3 @@ Note the comparison is only meaningful when the shot and the reference frame the
 - 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.
-
-## 0.1.6 retail frontage — what to look at
-
-Shot 5 is the review shot for this pass. Read it against
-`Art/reference/retail-neighbours/01-lee-drug-and-neighbor.jpg` (Gb321, CC BY-SA 4.0).
-
-Known gaps in this first pass, recorded rather than hidden:
-
-- **The parapet reads as a blank white band.** It is modelled as one 2.18 m wall with four
-  0.10 m reveal strips, and at review distance the strips disappear into the wash.
-- **The mural row and lettering band barely read.** They are shallow plates (0.06–0.08 m) on
-  the same plane as the wall; they need either depth or a decal before they read as the
-  photographs' black-framed panels.
-- **The corner tower is a plain cylinder with two cap rings** — the stepped Deco profile in the
-  photograph is richer than that.
-- **The camera crops the east end** of Lee Drug at 68° from the north sidewalk.
-- **6822 Budget is untouched** and still a bare blockout volume: no photograph of it exists.

TODO.md

@@ -15,9 +15,7 @@ Suggested blender skills: **references** (reference-image-match), **archviz**, *
 
 ### Patch tasks - active - session-5598ce7e-27e3-4c64-bb49-c04a4a31ee58 (branch `facade-retail-0.1.6`)
 
-- [A] **Model 6800 Lee Drug and 6806–6820 from their own reference.** First pass 2026-11-09 on branch `facade-retail-0.1.6`: `Tools/retail_frontage_build.py` builds both façades from the one photograph (`Art/reference/retail-neighbours/`, Gb321 CC BY-SA 4.0) with the analysis in `Art/blender/retail/ref-analysis.md`;
+- [A] **Model 6800 Lee Drug and 6806–6820 from their own reference.** First pass 2026-11-09 on branch `facade-retail-0.1.6`: `Tools/retail_frontage_build.py` builds both façades from the one photograph (`Art/reference/retail-neighbours/`, Gb321 CC BY-SA 4.0) with the analysis in `Art/blender/retail/ref-analysis.md`; `Tools/ue_import_retail_detail.py` imports them and the demo builder stages them as `RetailTrim_*`. The generic façade kit is now skipped on these two, so their walls carry one façade language instead of two. **Open on this item:** the parapet reads as a blank band, the mural row and lettering band do not resolve at review distance, the corner tower is a plain cylinder, and the review camera crops the east end — all listed in `Screenshots/README.md`.
-  `Tools/ue_import_retail_detail.py` imports them and the demo builder stages them as `RetailTrim_*`. The generic façade kit is now skipped on these two, so their walls carry one façade language instead of two.
-  **Open on this item:** the parapet reads as a blank band, the mural row and lettering band do not resolve at review distance, the corner tower is a plain cylinder, and the review camera crops the east end — all listed in `Screenshots/README.md`.
 - [D] **Model 6822 Budget.** Deferred: no photograph exists for it (Commons has nothing usable) and the single-storey 6.0 × 5.5 m volume cannot be read from the neighbour shot. Needs photography before it can be modelled honestly; do not substitute the El Capitan Theatre's set or the 6806–6820 shot.
 - [ ] Review every façade change with `Tools/render_screenshots.sh --verify` before tagging.
 - [ ] Tag `v0.1.6` and write `CHANGELOG.md` entry; then remove this section.