merge: bring main (v0.1.6) into anim-body-0.2.0

Conflicts resolved by union, not by picking a side:

- AGENTS.md keeps the stronger visual-review rule (README updated with every visual
  change; a stale section is a defect).
- render_screenshots.sh keeps the absolute engine path from main and adds
  -thirdperson from this branch - both were needed and neither alone worked.
- Screenshots/README.md now lists six shots, retail and third-person both embedded;
  the known-issues tables merged, with the animation defect and unproven camera
  collision added to main's rows.
- visual_targets.json carries both expectations.
- Architecture docs: ADR-8 (realistic buildings) and ADR-9 (third-person body) both
  present and in numeric order; ADR-8 was mis-placed before the Quality Requirements
  heading in the combined document by an earlier edit, now fixed.
- Binary conflicts resolved to main's content, since the retail trim only exists
  there.

Checks: 82 tool tests, prettier clean, six embeds resolve.

Docs/Architecture/architecture.md

@@ -193,6 +193,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
 
@@ -203,11 +204,14 @@ Python scripts in `Tools/` drive the content pipeline:
 | `export_*`, `hero_facade_build` | Blender headless export (FBX) |
 | `ue_import_*`, `ue_hero_facade_import` | Unreal headless import + placement |
 | `character_anim_build`, `ue_character_anim_import` | Character animation clips (`GigLine_Idle`, `GigLine_Walk`) and their import |
+| `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`, `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 |
 
@@ -454,6 +458,22 @@ Rule: place a building only against a neighbour or street mesh, never in isolati
 
 - **Consequences**: Scripts are version-controlled and repeatable. No live Blender session needed for CI.
 
+## ADR-8: Realistic building façades are a minor milestone, not a patch
+
+- **Context**: `0.1.4` carried the first façade pass as a _patch_, while the release policy says patches contain fixes and refinements and never new scope. The `0.1.6` retail pass then showed what that costs: a façade built in a patch has no release gate of its own, so a first pass that does not yet read as the building (`Screenshots/README.md`, 0.1.6 gaps) can sit inside a "done" patch series. Realism is also the project's leading quality goal, which a patch cannot carry.
+
+- **Decision**: Building realism gets its own minor milestone, `0.9.0 — Realistic buildings`, placed before the feature freeze. Its scope is the façade system (orders, profile library, storefront types, signage as decals), per-building photo-matched models, a measured material library with a texel-density rule, and LODs plus collision proxies. Patches keep fixes and refinements only. Renumbered by this decision: the former `0.9.0` freeze/beta/audit milestone becomes `0.10.0`, its patches `0.10.1`–`0.10.3`, and `1.0.0` moves to weeks 39–44.
+
+- **Consequences**: Façade work now has a release gate — every building measured against its own photograph, every building with a collision proxy and a LOD, no placeholder materials — so "modelled" means verified, not merely present. The price is that realism work stops being sliced into patches, and the schedule shifts by one minor cycle. Blockouts without a photograph stay blockouts and are listed as such, rather than being dressed up to fill the milestone.
+
+## ADR-9: Third-person body is an attachment of the first-person pawn, not a second pawn
+
+- **Context**: `0.2.0` needs a visible body and a third-person camera, while `0.1.0` shipped a first-person pawn with no body and the owner's decision was first person for that release. Two separate pawn classes would duplicate movement, input and reset logic, which is the code most likely to drift.
+
+- **Decision**: one pawn, both rigs. `AGigLineCharacter` carries a skeletal mesh (hidden in first person), a collision-tested spring-arm camera, and a **V** toggle that swaps the active camera and the body's visibility. The shipped default view stays first person; `-thirdperson` starts the pawn in the third-person rig and is what the screenshot run passes, so the review shot is reproducible without a human pressing a key.
+
+- **Consequences**: movement, reset, pause and the QA self-test stay in one place. The body's animation state is driven from `Tick` by speed rather than from input, so being pushed or falling animates correctly. The cost is that the camera swap is not a separate actor, so a future cinematic camera needs its own path rather than reusing the toggle.
+
 # Quality Requirements
 
 ## Quality Requirements Overview
@@ -490,6 +510,16 @@ Ordered by priority: realism first, performance last. The order decides design t
 
 > QS-9 is last on purpose. Performance is a floor that every release must meet, not the goal that shapes the content: realism decides what gets built, the frame budget decides how much of it.
 
+### Building realism gate (0.9.0)
+
+| ID | Check | Metric |
+| --- | --- | --- |
+| BR-1 | A building with a reference photograph has a review shot compared against it | Silhouette and proportion deltas recorded per building in `Screenshots/README.md`; owner approval per shot |
+| BR-2 | Every building is either photo-matched or explicitly recorded as an unfounded blockout | List in `TODO.md`; no building in an in-between state |
+| BR-3 | Every building has a collision proxy and at least one LOD | Count of buildings missing either = 0 |
+| BR-4 | No surface carries a placeholder material | Material audit in `Tools/ue_audit_scene.py` reports 0 placeholder slots |
+| BR-5 | The realism pass does not break the floor | QS-9 still holds at 1440p, with the measured cost of the pass recorded |
+
 # Risks and Technical Debts
 
 | ID | Risk / Debt | Priority | Mitigation |