feat(hero): v0.1.2 — scale calibration, façade detail, export preset refactor (#28)

Merged PR #28: v0.1.2 — scale calibration, façade detail, export preset

Co-authored-by: Zwitschi <zwitschi82@gmail.com>

.gitignore

@@ -42,6 +42,11 @@ Thumbs.db
 .env.*
 *.env
 
+# Mapbox-derived data — local only. Mapbox terms restrict persisting/redistributing
+# their data, so the Tilequery cache and any generated report stay untracked.
+/Geo/raw/mapbox-cache/
+/Geo/verification/*mapbox*
+
 # Local, private reference material — never committed (see Docs/reference-notes-hollywood.md)
 /Art/reference/
 /Docs/data-inventory.md

AGENTS.md

@@ -110,6 +110,59 @@ Keep entries short and dated, with the evidence: the command, the log line, or t
 
 Memory edits on an agent's branch are not shared live. Communicate important findings to the coordinator during work and reconcile them into the shared `main` copy when integrating.
 
+## Python and shell tooling
+
+Every committed asset and every measured claim in this repository is produced by a script. Tools live in `Tools/` (Unreal, network, repository), `Geo/tools/` (projection, OSM/DEM parsing, metadata) and `Art/blender/*/` (Blender-side builders, next to their output).
+
+**Fix the tool, not the artefact.** If an asset is corrected by hand, script the correction (or regenerate it) in the same change. A second manual fix of the same kind means the tool is missing a step.
+
+**Improve over fork.** Extend the existing tool rather than adding a near-duplicate. When two or three scripts start sharing logic, factor the shared part into `Tools/_common.py`, `Geo/tools/osm_common.py` or `Art/blender/common.py`; keep the single metres→centimetres conversion where it already lives.
+
+Rules that keep tools reusable and reviewable:
+
+- **One script, one job.** Every input is an argument; no interactive prompts; deterministic output paths.
+- **Fail loudly.** A tool that cannot do its job exits non-zero with a message. Never leave a partially written asset and a success code.
+- **Result files for Unreal.** Unreal commandlets swallow `print()`; write the outcome to `/tmp/gigline/<tool>.txt` and read that instead of trusting the exit code alone.
+- **Absolute paths into sandboxes.** Blender Flatpak (`LD_LIBRARY_PATH="$B/blender/lib"`) and Unreal do not share the repo's working directory; pass absolute paths.
+- **Clean worktree for generators.** Tools that rewrite committed assets (site/street/hero builders, importers, map builders) run from a clean worktree; inspect the LFS diff before committing. Note that `.blend` and `.umap` check out read-only — `chmod u+w` first or the save silently fails.
+- **Network and paid-API tools are human-triggered.** `Tools/commons_fetch.py`, `Tools/page_image_fetch.py`, `Tools/judge_screenshot.py` (OpenRouter) and anything similar never sit in a gate or CI. Handle HTTP 429 with back-off rather than retrying immediately.
+- **Measure, don't assert.** Verification tools print the sampled numbers — counts, holes, Z ranges, worst step and its location, frame-time percentiles — so a claim in `TODO.md`, `CHANGELOG.md` or `Docs/` can be re-checked by re-running the command.
+
+**Document every tool.** A new or changed tool gets a row in the inventory table of the README beside it: [`Tools/README.md`](Tools/README.md), [`Geo/README.md`](Geo/README.md), or [`Art/blender/README.md`](Art/blender/README.md). What it does, its arguments, and a typical command. A tool without a README row is unfinished.
+
+**Test the pure parts.** `Tools/tests/` holds stdlib `unittest` tests (no Blender or Unreal process; they must not start a game or editor). Extract the testable core — argument parsing, geometry maths, licence gating, report formatting — into functions that a test can call directly.
+
+```bash
+python3 -m unittest discover -s Tools/tests -t Tools -p 'test_*.py'
+```
+
+Keep the tools standard-library-only where practical; if a third-party import is genuinely needed, add it to `requirements-tools.txt` with a version floor and mention it in the tool's README row.
+
+## Architecture documentation
+
+[`Docs/Architecture/`](Docs/Architecture/) is the arc42 documentation: twelve numbered section files, `about-arc42.md`, and the combined [`architecture.md`](Docs/Architecture/architecture.md). **Markdown is canonical** — the `.adoc` sources were removed on 2026-11-08.
+
+Keep it current **in the same change as the implementation**, not in a later documentation pass. When work alters any of the following, edit the matching section:
+
+| Change | Section |
+| --- | --- |
+| A new or restructured module, tool, data source or external interface | `05_building_block_view.md` |
+| A runtime flow, tick/order dependency, or lifecycle (possession, map load, QA self-test) | `06_runtime_view.md` |
+| Packaging, engine pin, checkout/build/launch procedure | `07_deployment_view.md` |
+| A pattern, convention or cross-cutting rule (units, collision policy, provenance) | `08_concepts.md` |
+| A decision that constrains future work | new ADR in `09_architecture_decisions.md` |
+| A quality goal or a measured budget (frame time, traversal coverage) | `10_quality_requirements.md` |
+| A known risk or a risk that retired | `11_technical_risks.md` |
+| A new term, tool or abbreviation | `12_glossary.md` |
+
+Rules:
+
+- **Describe what exists.** No aspirational architecture: anything planned belongs in `ROADMAP.md` and `TODO.md`. Every structural claim names the file, script or flag that implements it.
+- **ADRs are append-only.** Never rewrite an accepted decision; supersede it with a new ADR that says what it replaces and why.
+- **Keep the combined document in sync.** `architecture.md` mirrors the section files; when a section changes, update the combined document too.
+- **Images** live in `Docs/Architecture/images/` and are referenced, not duplicated.
+- **Verify:** all Markdown must pass `prettier --check` (config in `.prettierrc`), and a command you quote must still run.
+
 ## Geographic & Art Pipeline
 
 1. Save a versioned OSM extract; document date, bounds, and source.

Art/blender/README.md

@@ -80,7 +80,7 @@ LD_LIBRARY_PATH="$B/blender/lib" "$B/blender/blender" -b --factory-startup \
 ```
 
 - `Road_Hollywood`: 8 120 verts, 7 812 faces, carriageway −10.5…+10.5 m, DEM elevations plus a 2 cm lift so it does not z-fight the terrain.
-- `Sidewalk_South` 4.0 m wide, `Sidewalk_North` 5.3 m wide, both raised by the kerb height.
+- `Sidewalk_South` 4.0 m wide, `Sidewalk_North` 5.3 m wide. The kerb upstand is **full at the road-side edge and tapers to zero at the building-side edge**, so the walk surface meets the terrain flush (before `0.1.1` the outer lip stood the full kerb height above the DEM — a 15.8 cm ledge).
 - `Kerb_South`, `Kerb_North`: vertical faces, mostly **0.13 m** — the 0.15 m assumption minus nothing on the road side — and flushed to 0 within ±2.5 m of each signalised crossing with a 1.5 m blend. Measured from the built mesh: 256 steps at 0.13 m, 15 flush, a few in transition.
 
 Crown check on the built mesh at mid-block: gutter −10.5 m → +0.99, −5 m → +1.38, centre → +1.52, +5 m → +1.58, +10.5 m → +1.52. The crown sits just north of the centreline, as the cross-sections said.
@@ -103,16 +103,20 @@ Objects are appended from the source files, not regenerated, and grouped into `S
 
 A downward raycast on a 1 m grid along both sidewalks and the designated crossing, ignoring blockout meshes so marquees and canopies overhead do not count as ground:
 
-| Route             | Samples | Holes | Z range       | Worst step |
-| ----------------- | ------: | ----: | ------------- | ---------: |
-| South sidewalk    |     279 |     0 | −0.45 … +3.13 |    20.5 cm |
-| North sidewalk    |     279 |     0 | +0.07 … +3.83 |    15.1 cm |
-| Crossing at 130 m |      26 |     0 | +1.16 … +1.80 |     8.6 cm |
+| Route             | Samples | Holes | Z range       |        Worst step |
+| ----------------- | ------: | ----: | ------------- | ----------------: |
+| South sidewalk    |     279 |     0 | −0.48 … +3.06 |   13.4 cm (s=198) |
+| North sidewalk    |     279 |     0 | +0.06 … +3.76 |     6.9 cm (s=33) |
+| Crossing at 130 m |      26 |     0 | +1.14 … +1.80 | 9.0 cm (off −8.5) |
+
+At `--sample 0.25` the same routes measure 11.6 cm / 8.0 cm / 3.4 cm. The pre-check now prints the grade and the **location** of the worst step, and its coverage no longer shrinks with `--sample`.
 
 No holes anywhere, so nothing drops the player on either side. The two flagged steps:
 
-- **15.8 cm at s≈207**, where a sample crosses from `Terrain_DEM` onto `Sidewalk_South` — that is the sidewalk's outer edge, the 0.15 m kerb height minus the terrain. Mostly hidden by buildings, but it is a real edge and it will be visible anywhere a building is missing.
-- **10–13 cm steps at s≈33, 39 and 126**, inside the sidewalk mesh: the kerb-flush transition at the crossings. That is a ~10 % ramp over 1.5 m, steeper than a real crossing ramp (8 % max). Worth grading properly when the crossings are detailed.
+- ~~15.8 cm at s≈207, the sidewalk's outer edge~~ — **fixed in `0.1.1`**: the sidewalk upstand now tapers to zero at the building side, so the outer edge is flush with the terrain (north route 15.1 → 6.9 cm).
+- ~~10–13 cm steps at the crossings, ~10 % ramp over 1.5 m~~ — **fixed in `0.1.1`**: the ramp run is now derived from a target grade (`--max-ramp-grade`, default 8 %), giving 1.63 m instead of the fixed 1.5 m (8.7 %). Measured at 0.25 m sampling the crossing now steps 3.4 cm (~1.4 % of the route) at the kerb line.
+
+**Remaining finding (not a crossing, not the outer edge):** the south route still measures a **13.4 cm step at s≈198 m** (11.6 cm at 0.25 m sampling) and the north route 8.0 cm at s≈251 m. Neither is at a crossing and neither is the outer lip, so this is a local discontinuity in the sidewalk strip — most likely the DEM sampling or a centreline vertex near the block ends. Tracked under the `0.1.1` "audit any collision gaps" item rather than left undocumented.
 
 This is a pre-check, not the `0.1.0` release check: the release check is traversal in the engine.
 
@@ -127,13 +131,15 @@ Blender works in metres, and the imported meshes match the OSM geometry, so the
 | Building | Blender dimensions | OSM way outline | Height source |
 | --- | --- | --- | --- |
 | El Capitan Entertainment Centre | 25.72 × 54.47 × 14.50 m | 25.75 × 54.88 m | `height` tag 14.5 |
-| El Capitan Theatre | 38.66 × 54.46 × 20.96 m | 38.59 × 54.87 m | `building:levels=6` × 3.2 m, plus roof |
+| El Capitan Theatre | 38.66 × 54.46 × 20.55 m | 38.59 × 54.87 m | `building:levels=6` × **3.1 m**, plus ~1.9 m roof |
 | Madame Tussaud's | 42.48 × 56.77 × 15.90 m | 42.0 m frontage | `height` tag 15.9 |
 | TCL Chinese Theatre | 43.78 × 75.90 × 18.10 m | 44.0 m frontage | `height` tag 18.1 |
 
 Widths agree to a few centimetres; depths differ by up to 0.4 m because Blosm assembles **multipolygon relations**, not the raw way I measured. Placement after the frame correction agrees with the UTM control points to 0.1–0.5 m per building — the residual is relation assembly and Blosm's edge straightening, not projection.
 
-Buildings **without** a `height` tag get levels × 3.2 m, which is a placeholder, not evidence. Every such height is a modelling decision to be replaced from the reference photography.
+Buildings **without** a `height` tag get levels × **3.1 m**. The storey height was 3.2 m until 2026-11-09, when a cross-check of every block building against Mapbox's building data (`Geo/tools/mapbox_buildings.py`) showed our figure running 0.6 m high per six levels — i.e. 3.1 m per level — and that calibration was adopted. The few buildings where Mapbox disagreed with a pure `levels × 3.1 m` fallback carry an explicit override in `Geo/tools/block_height_report.py::HEIGHT_OVERRIDES`.
+
+Blosm adds roof mass on top of `levels × levelHeight`: the two `levels`-derived frontage buildings both land ~1.9 m above their table height (6922 39.1 m against 37.2 m, El Capitan Theatre 20.5 m against 18.6 m). That offset is the roof, not a height error — the table records the tagged height, the mesh records the storey plus its roof.
 
 ## Relation completeness
 

Art/blender/blockout/blosm_blockout.py

@@ -40,7 +40,9 @@ def parse_args():
     ap.add_argument("--osm", required=True, help="local .osm file to import")
     ap.add_argument("--bounds", required=True, help="south,west,north,east in WGS84 degrees")
     ap.add_argument("--out", required=True, help="output .blend path")
-    ap.add_argument("--level-height", type=float, default=3.2, help="metres per building level")
+    # 3.1 m, not 3.2: calibrated against Mapbox building data on 2026-11-09
+    # (see Geo/tools/mapbox_buildings.py and Geo/tools/block_height_report.py).
+    ap.add_argument("--level-height", type=float, default=3.1, help="metres per building level")
     ap.add_argument("--origin", default=None,
                     help="lat,lon to use as the Blender origin (project origin). Default: Blosm centres on the extract")
     ap.add_argument("--no-subdivide", action="store_true", help="skip OSM area subdivision")

Art/blender/hero/hero-facade-2026-11-07.json

@@ -3,18 +3,18 @@
   "frame": "project frame, metres, X east Y north Z up",
   "bounds_m": {
     "min": [
-      -13.02,
+      -13.08,
       -12.5,
       0.0
     ],
     "max": [
-      13.02,
-      0.07,
+      13.08,
+      0.13,
       14.5
     ],
     "size": [
-      26.04,
-      12.57,
+      26.16,
+      12.63,
       14.5
     ]
   },
@@ -33,10 +33,28 @@
       "dims_m": [
         0.95,
         0.95,
-        7.45
+        8.25
       ],
       "evidence": "6 columns at 4.96 m centres (sibling notes x measured frontage)"
     },
+    {
+      "object": "Hero_ColumnBase_x6",
+      "dims_m": [
+        1.36,
+        1.36,
+        0.22
+      ],
+      "evidence": "assumption: Ionic base moulding; photographs show a wider base at the shaft foot"
+    },
+    {
+      "object": "Hero_Abacus_x6",
+      "dims_m": [
+        1.3,
+        1.3,
+        0.14
+      ],
+      "evidence": "assumption: square abacus under the architrave, as Ionic capitals carry"
+    },
     {
       "object": "Hero_Architrave",
       "dims_m": [
@@ -55,12 +73,21 @@
       ],
       "evidence": "assumption: projecting cornice line"
     },
+    {
+      "object": "Hero_Dentil_xN",
+      "dims_m": [
+        0.18,
+        0.3,
+        0.22
+      ],
+      "evidence": "52 dentils at 0.45 m centres under the corona; assumption: photographed cornice reads as a dentilled course"
+    },
     {
       "object": "Hero_Entablature",
       "dims_m": [
         25.75,
         1.5,
-        3.4
+        3.0
       ],
       "evidence": "assumption: entablature depth"
     },
@@ -69,7 +96,7 @@
       "dims_m": [
         25.75,
         1.2,
-        2.2
+        1.8
       ],
       "evidence": "assumption: parapet carries the motto band"
     },
@@ -86,10 +113,10 @@
       "object": "Hero_Medallion_x2",
       "dims_m": [
         1.1,
-        1.1,
-        0.02
+        0.04,
+        1.1
       ],
-      "evidence": "photographs: two stone discs beside the motto"
+      "evidence": "photographs: two stone discs beside the motto, mounted on the parapet face"
     },
     {
       "object": "Hero_Stylobate",

Art/blender/site/export_site_fbx.py

@@ -15,6 +15,9 @@ import os
 import sys
 
 import bpy
+sys.path.insert(0, os.path.join(os.path.join(os.path.dirname(__file__), "..", "..", ".."), "Tools"))
+import fbx_export_preset as fbx_preset  # noqa: E402
+
 
 MESHES = ("Terrain_DEM", "Road_Hollywood", "Sidewalk_South", "Sidewalk_North",
           "Kerb_South", "Kerb_North", "Crossing_Markings")
@@ -60,20 +63,7 @@ def main():
             _ = bpy.context.view_layer
         bpy.context.view_layer.objects.active = obj
         path = os.path.join(args.out, name + ".fbx")
-        bpy.ops.export_scene.fbx(
-            filepath=path,
-            use_selection=True,
-            object_types={"MESH"},
-            apply_unit_scale=True,
-            apply_scale_options="FBX_SCALE_NONE",
-            axis_forward="-Y",
-            axis_up="Z",
-            use_space_transform=True,
-            use_mesh_modifiers=True,
-            mesh_smooth_type="OFF",
-            path_mode="AUTO",
-            bake_space_transform=False,
-        )
+        fbx_preset.export_static(path, selection=True)
         if mirrored:
             # The flip is an export correction, not a change to the source: undo it.
             obj.scale.y *= -1.0

Art/blender/site/site_assembly.py

@@ -165,10 +165,16 @@ def main():
     def lat_lon(s, offset):
         return oc.point_at(line, _lengths, s, offset, lat0, lon0)
 
+    # Sample spacing is independent of coverage: walk the whole block at
+    # `--sample` metres, so a finer spacing measures the gradient instead of
+    # accidentally shortening the route (previously range(int(block_len)) with a
+    # 0.25 m spacing only covered a quarter of the block).
+    along = int(block_len / args.sample)
+    across = int(26.0 / args.sample)
     route_specs = {
-        "south sidewalk": [(s, -12.5) for s in [i * args.sample for i in range(int(block_len))]],
-        "north sidewalk": [(s, 13.0) for s in [i * args.sample for i in range(int(block_len))]],
-        "crossing at 130 m": [(130.0, o) for o in [i * args.sample - 12.5 for i in range(26)]],
+        "south sidewalk": [(i * args.sample, -12.5) for i in range(along)],
+        "north sidewalk": [(i * args.sample, 13.0) for i in range(along)],
+        "crossing at 130 m": [(130.0, i * args.sample - 12.5) for i in range(across)],
     }
     flat = [(spec, lat_lon(s, off)) for spec, samples in route_specs.items() for s, off in samples]
     local = project_to_local([ll for _spec, ll in flat], find_proj())
@@ -185,12 +191,20 @@ def main():
                 heights.append(None)
             else:
                 heights.append(z)
-        deltas = [abs(b - a) for a, b in zip(heights, heights[1:])
+        deltas = [(i, abs(b - a)) for i, (a, b) in enumerate(zip(heights, heights[1:]))
                   if a is not None and b is not None]
-        max_step = max(deltas) if deltas else float("nan")
+        worst_i, max_step = (max(deltas, key=lambda t: t[1]) if deltas else (0, float("nan")))
         known = [h for h in heights if h is not None]
+        grade = (max_step / args.sample) * 100 if deltas else float("nan")
+        # Position of the worst step, as arc length / cross offset, so the cause
+        # can be located instead of guessed.
+        if label == "crossing at 130 m":
+            where = f"s=130 off={(worst_i * args.sample - 12.5):+.2f} m"
+        else:
+            where = f"s={worst_i * args.sample:.1f} m"
         print(f"  {label:18} samples {len(heights):3}  holes {holes}  "
-              f"Z {min(known):+.2f}..{max(known):+.2f}  max step {max_step*100:.1f} cm")
+              f"Z {min(known):+.2f}..{max(known):+.2f}  max step {max_step*100:.1f} cm "
+              f"({grade:.1f} % grade) at {where}")
 
     out = os.path.abspath(args.out)
     os.makedirs(os.path.dirname(out), exist_ok=True)

Art/blender/street/street_mesh.py

@@ -68,8 +68,13 @@ def parse_args():
     ap.add_argument("--cross", type=float, default=0.75)
     ap.add_argument("--kerb", type=float, default=0.15)
     ap.add_argument("--ramp-half-width", type=float, default=2.5)
-    ap.add_argument("--ramp-blend", type=float, default=1.5)
-    return ap.parse_args(argv)
+    ap.add_argument("--ramp-blend", type=float, default=None,
+                    help="override the ramp run; default derives it from --max-ramp-grade")
+    ap.add_argument("--max-ramp-grade", type=float, default=0.08,
+                    help="maximum crossing-ramp slope (0.08 = 8%%)")
+    args = ap.parse_args(argv)
+    args.ramp_blend = ramp_blend(args.kerb, args.max_ramp_grade, args.ramp_blend)
+    return args
 
 
 def find_proj():
@@ -125,7 +130,13 @@ class Dem:
 
 
 def kerb_height(s, base, half_width, blend):
-    """Full kerb, except flushed near a crossing so people can step off."""
+    """Full kerb, except flushed near a crossing so people can step off.
+
+    `blend` is the horizontal run over which the kerb drops from `base` to the
+    0.02 m flush height. It is derived from a target maximum grade (see
+    `ramp_blend`) so the crossing ramps stay within a real ramp's slope instead
+    of the ~8.7 % the old fixed 1.5 m run produced.
+    """
     for crossing in CROSSINGS:
         d = abs(s - crossing)
         if d <= half_width:
@@ -136,6 +147,22 @@ def kerb_height(s, base, half_width, blend):
     return base
 
 
+def ramp_blend(kerb, max_grade, override=None):
+    """Horizontal run needed for the kerb ramp to stay at or under max_grade.
+
+    0.15 m kerb at an 8 % grade needs 1.63 m of run; the previous fixed 1.5 m
+    gave 8.7 %, and the walk pre-check measured the transition as a 10-13 cm
+    step over 1.5 m. When `override` is given it wins (kept for reproducing old
+    meshes), otherwise the run is computed from the live kerb height so it stays
+    correct if the kerb height assumption changes.
+    """
+    if override is not None:
+        return max(0.0, override)
+    if max_grade <= 0.0:
+        return 0.0
+    return max(0.0, (kerb - 0.02)) / max_grade
+
+
 def strip(rows, offsets, z_at, name, material):
     """Build a quad grid from per-row sampled vertices."""
     verts, faces = [], []
@@ -218,13 +245,31 @@ def main():
         z = dem_z(x, y)
         return (z if z is not None else 0.0) + 0.02
 
-    def south_z(r, off, x, y):
+    def sidewalk_z(r, off, inner, outer, x, y):
+        """Sidewalk surface: full kerb upstand at the road-side (inner) edge,
+        tapering to zero at the building-side (outer) edge so the walk surface
+        meets the terrain flush.
+
+        Before this taper the outer lip stood the full kerb height above the DEM,
+        which the walkability pre-check measured as a 15.8 cm step where a sample
+        crosses from Terrain_DEM onto Sidewalk_South (with a matching lip on the
+        north side). A 0.15 m lip over a 4.0 m / 5.3 m strip is a ~3-4 % ramp:
+        walkable and visually negligible, and it removes the ledge entirely.
+        """
         z = dem_z(x, y)
         base = z if z is not None else 0.0
-        return base + kerb_height(rows[r][0], args.kerb, args.ramp_half_width, args.ramp_blend)
+        h = kerb_height(rows[r][0], args.kerb, args.ramp_half_width, args.ramp_blend)
+        span = inner - outer
+        if abs(span) < 1e-9:
+            return base + h
+        t = min(1.0, max(0.0, (off - outer) / span))
+        return base + h * t
+
+    def south_z(r, off, x, y):
+        return sidewalk_z(r, off, SOUTH_GUTTER, SOUTH_SIDEWALK, x, y)
 
     def north_z(r, off, x, y):
-        return south_z(r, off, x, y)
+        return sidewalk_z(r, off, NORTH_GUTTER, NORTH_SIDEWALK, x, y)
 
     road = strip(rows, road_offsets, road_z, "Road_Hollywood", asphalt)
     sw_s = strip(rows, south_offsets, south_z, "Sidewalk_South", concrete)

CHANGELOG.md

@@ -2,8 +2,115 @@
 
 All notable changes to this project are documented here.
 
-Format: [Keep a Changelog](https://keepachangelog.com/) style, versions follow [Semantic Versioning](https://semver.org/). Entries are added when a version section in `AGENTS.md` is completed.
+Format: [Keep a Changelog](https://keepachangelog.com/) style, versions follow [Semantic Versioning](https://semver.org/). Entries are added when a version section in `TODO.md` is completed.
 
-## Unreleased
+## [Unreleased]
 
-No completed releases yet.
+Nothing yet.
+
+## [0.1.2] — 2026-11-09
+
+Scale and façade correction patch. Buildings and the hero elevation now match the reference photography and the cross-checked height data; no new gameplay scope.
+
+### Added
+
+- **`Tools/facade_detail_concepts.py`** — generates frontal building plates (whole elevation, entrance in its façade, building with neighbours) from a local reference photograph through OpenRouter image models. Spec-driven, never overwrites, writes a provenance sidecar per image, output stays in the gitignored `Art/reference/` tree. Local working material only.
+- **`Tools/fbx_export_preset.py`** — the single FBX export preset (`ue_metric_v1` / `ue_character_v1`). Replaces the argument block that had been copied into six exporters.
+- **Façade occlusion probe** in `-qaselftest`: 40 m traces sideways from the road centre at walking height, required wherever a building is staged.
+- **Ionic detail on the hero**: base moulding at every shaft foot, a square abacus over every capital, and a 52-dentil cornice course.
+- **Tool tests**: `Tools/tests/` now covers the input driver, height classification, the Mapbox cross-check, the concept generator and the FBX preset (49 tests).
+
+### Changed
+
+- **Storey height 3.2 → 3.1 m**, calibrated against Mapbox building data, with explicit overrides for three rear outbuildings; the block cross-check now reports 66 matches and no disagreements.
+- **Hero colonnade 47.6 % → 53.1 %** of the 14.50 m elevation, inside the photographed 50–60 % band (thinner entablature and parapet).
+- Blockout regenerated at the new storey height; frontage re-exported and re-imported (6922 42.1 → 39.1 m, El Capitan Theatre 20.0 → 20.5 m).
+- FBX exports now carry smoothing groups (`FACE` instead of `OFF`), so round geometry is no longer faceted and imports stop warning.
+
+### Fixed
+
+- **Windows floated 1.44 m in front of the wall**, ahead of the colonnade; they now sit on the wall plane behind the columns.
+- **Parapet medallions were flat discs lying on the coping** instead of discs on the parapet face.
+- **The hero façade had no usable collision** — the player could walk through it. It is now complex-as-simple; auto-generated convex hulls were tried and rejected because they bulged into the street.
+- **The three "guessed" block heights were never buildings**: two `building=roof` canopies and a transit shelter. They are classified as non-building volumes and the block now reports zero guessed heights.
+
+### Verified
+
+- Packaged build `-qaselftest`: walk, reset and pause pass; seam transect 1456 samples / 0 holes; wall probe 0/35; façade probe 0/9.
+- Screenshots re-rendered for every change and approved by the owner.
+
+### Known limitations
+
+- Cornice dentil spacing, the base and abacus dimensions are recorded assumptions: the reference photography does not resolve them at our scale.
+- Façade surfaces remain flat blockout materials; the textured pass is `0.1.4`.
+
+## [0.1.1] — 2026-11-08
+
+Collision-fidelity patch. No new scope: street geometry corrections and the QA tooling that measures them.
+
+### Fixed
+
+- **Sidewalk outer edge ledge.** The sidewalk stood the full 0.15 m kerb height above the DEM at both edges, leaving a 15.8 cm lip where the walk route crossed from terrain onto the south sidewalk. The upstand now tapers from full at the road-side edge to zero at the building-side edge; the north route's worst step fell from 15.1 cm to 6.9 cm.
+- **Crossing ramps too steep.** The kerb-flush run was a fixed 1.5 m, giving ~8.7 % (measured 10–13 cm over 1.5 m). The run is now derived from a target grade (`--max-ramp-grade`, default 8 % ⇒ 1.63 m); the crossing steps 3.4 cm at 0.25 m sampling.
+
+### Added
+
+- **Walk pre-check improvements** (`Art/blender/site/site_assembly.py`): sampling coverage is independent of `--sample` (it previously shrank the route), and the report now prints the grade and the arc-length/offset **location** of the worst step, so a step can be located rather than guessed.
+
+### Changed
+
+- **Kerb height recorded as final** at 0.15 m modelled / 0.13 m as built — a standard 6 in LA kerb; neither the 3DEP DEM nor the reference photography can resolve it further (±2 cm), which is far below the character's 45 cm step height.
+
+### Verified
+
+- Site meshes rebuilt and re-imported (7/7, collision flags intact), DemoMap rebuilt, packaged Development build `EXIT=0`.
+- `-qaselftest` on the packaged build: walk 761 cm in 2 s at steady Z 456, reset 0 cm, pause/unpause, transect 1456 samples across 16 rows / **0 holes**, wall probe **0/35** blocking hits.
+
+### Known limitations
+
+- One residual **13.4 cm surface step at s≈198 m** on the south sidewalk (8.0 cm at s≈251 m north). It is not a gap and is below the 45 cm `MaxStepHeight`, so it does not block traversal; the cause is a sidewalk-strip discontinuity near a centreline vertex, recorded in `Art/blender/README.md` as a smoothness refinement.
+- Kerb radii at junctions, driveway aprons, drainage inlets and pavement joints remain unmodelled (unchanged from `0.1.0`).
+
+Nothing yet.
+
+## [0.1.0] — 2026-11-08
+
+The first playable release: a walkable exterior demo of the **6840 Hollywood Blvd** (El Capitan Entertainment Centre) block in Unreal Engine, built on OpenStreetMap layout data and USGS elevation, with the hero façade and the verified block frontage staged on a walkable street.
+
+### Added
+
+- **Unreal project** (`Game/GigLine`) — C++ game module, Enhanced Input, packaged Linux build, and a `DemoMap` that a plain launch opens directly.
+- **Walkable demo level** — terrain from the 3DEP DEM, Hollywood Blvd carriageway, both sidewalks and kerbs with collision, the designated mid-block crossing, and fixed daytime lighting (sun, sky light, sky atmosphere, height fog, pinned exposure).
+- **Hero façade** for 6840 Hollywood Blvd — six-column neoclassical elevation with three genuine portal recesses, entablature, parapet and motto band (`Tools/hero_facade_build.py`, `Tools/ue_hero_facade_import.py`).
+- **Block frontage** — the five verified south-side neighbours (6922, 6902, 6838 El Capitan Theatre, 6822 Budget, 6806–6822, 6800 Lee Drug) and the two north-side buildings (TCL Chinese Theatre, Madame Tussaud's) placed at their OSM positions.
+- **First-person player** — `AGigLineCharacter`: 1.75 m capsule, 1.60 m eye camera, 4 m/s walk, mouse look, jump, reset (`R`) and pause (`Escape`); controls documented in `Docs/controls.md` and shown in-game.
+- **In-game ODbL attribution** — `AGigLineHUD` draws the OpenStreetMap credit and licence line every frame.
+- **QA harness** — `-qaselftest` (walk, reset, pause, seam transect, invisible-wall probe, frame-time capture) and `Tools/input_test.py` / `Tools/input_emulation.py` for OS-level virtual keyboard/mouse input.
+- **Documentation** — setup, build, toolchain, licensing, ODbL review, release checks, and arc42 architecture docs.
+
+### Fixed
+
+- **All controls were dead in packaged and PIE builds.** The mapping-context generator wrote key bindings to the deprecated `mappings` array; UE 5.8 reads `DefaultKeyMappings.Mappings`, so the cooked game had zero runtime mappings and every key resolved to nothing. `Tools/ue_create_input_assets.py` now populates the current field.
+- **"Fall-through" was an 8 m invisible box.** `Terrain_DEM` shipped only a bounding-box collision proxy; forcing complex-as-simple collision (`UGigLineAssetTools`) put the player on the actual street.
+- **Reset returned the player to mid-air** — the start position is now captured on the first grounded frame.
+- **Plain launch opened the engine template** — the default map now lives in `DefaultEngine.ini` and points at `DemoMap`.
+- **Game target would not compile** — removed editor-only API use (`UStaticMesh::PostEditChange`, `AActor::GetActorLabel`).
+- **`demo-north-buildings` screenshot** framed 85 % sky (camera 9.5 km west of the buildings); re-pointed to the building mass.
+
+### Verified
+
+- Both sides of the demo are traversable: 1456-sample seam transect, 0 holes, no blocking collision or invisible walls (`-qaselftest` on the packaged build).
+- Placement and street scale match the reference photography and Geo measurements (road 24.3 m, sidewalk offsets 12.5/13.2 m, hero frontage 26.0 m).
+- **414 fps average / p99 3.01 ms at 2560×1440** (Epic preset, TSR, VSync off, no frame generation) — far above the 60 fps target.
+- Fresh checkout builds and packages with the documented external engine (UE 5.8.4).
+
+### Known limitations
+
+- Buildings other than the hero are flat blockout volumes; façade detail, materials and Blosm style scripts are planned for `0.1.4`.
+- Kerb height (0.13 m as built vs 0.15 m assumed), kerb radii, driveway aprons and graded crossing ramps are deferred to `0.1.1`; crossing ramps are kerb flushes.
+- One block only; no vehicles, NPCs, audio, or settings UI yet.
+
+[Unreleased]: https://git.allucanget.biz/zwitschi/gig-line/compare/v0.1.2...main
+[0.1.2]: https://git.allucanget.biz/zwitschi/gig-line/releases/tag/v0.1.2
+[0.1.1]: https://git.allucanget.biz/zwitschi/gig-line/releases/tag/v0.1.1
+[0.1.0]: https://git.allucanget.biz/zwitschi/gig-line/releases/tag/v0.1.0

Docs/Architecture/05_building_block_view.md

@@ -60,8 +60,11 @@ Python scripts in `Tools/` drive the content pipeline:
 | `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/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 |
 
-Source data: `Art/blender/` (`.blend` files), `Geo/` (OSM extracts, DEM, verification docs).
+Source data: `Art/blender/` (`.blend` files), `Geo/` (OSM extracts, DEM, verification docs). Tool rules (one script one job, result files for commandlets, clean worktree for generators, documented inventory, tests for the pure parts) are in [`AGENTS.md`](../../AGENTS.md#python-and-shell-tooling).
 
 ### QA & Review
 

Docs/Architecture/architecture.md

@@ -1,8 +1,9 @@
-# Gig Line Architecture Documentation
-
-> Linux-first walking/driving demo around 6840 Hollywood Blvd
-
-Version 0.1.0 — 2026-11-08 — initial architecture documentation
+---
+title: Gig Line Architecture Documentation
+description: Architecture documentation for the Gig Line Linux-first Unreal Engine 5 demo around 6840 Hollywood Blvd.
+status: v0.1.0
+date: 2026-11-08
+---
 
 # Introduction and Goals
 
@@ -198,6 +199,9 @@ Python scripts in `Tools/` drive the content pipeline:
 | `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/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 |
 
 Source data: `Art/blender/` (`.blend` files), `Geo/` (OSM extracts, DEM, verification docs).
 

Docs/controls.md

@@ -0,0 +1,36 @@
+# Controls (`0.1.0` walkable demo)
+
+Keyboard and mouse. The same list is shown in-game, bottom-right of the frame
+(`AGigLineHUD`), and the packaged Linux build ships with these bindings.
+
+| Action | Key | Notes |
+| --- | --- | --- |
+| Move forward | `W` | 4 m/s walk |
+| Move back | `S` | |
+| Strafe right | `D` | |
+| Strafe left | `A` | |
+| Look | Mouse | Captured on launch; `Escape` releases it |
+| Jump | `Space` | |
+| Reset to start | `R` | Returns to the grounded spawn point |
+| Pause / release mouse | `Escape` | Second press resumes and recaptures the mouse |
+
+## Notes
+
+- Movement is relative to where you are looking (controller yaw), so the capsule
+  stays upright on the sloped street.
+- The mouse is captured on launch, so looking works without clicking first.
+  `Escape` toggles the capture as part of pause.
+- Bindings are Enhanced Input actions in `/Game/Input` built by
+  `Tools/ue_create_input_assets.py`; the mapping context is `IMC_Default`.
+
+## Testing input without a physical keyboard
+
+`Tools/input_test.py` injects OS-level keyboard/mouse events through a virtual
+`/dev/uinput` device (see `Tools/input_emulation.py`), e.g.:
+
+```bash
+python3 Tools/input_test.py --sequence move:2,look:3
+```
+
+It drives the focused game window exactly like real hardware, which is how the
+controls were regression-tested on the packaged build.

Docs/perf/0.1.0-walk-frametimes.csv

@@ -0,0 +1,830 @@
+frame,ms
+0,2.419
+1,2.502
+2,2.360
+3,2.395
+4,2.174
+5,2.539
+6,2.421
+7,2.322
+8,2.455
+9,2.345
+10,2.510
+11,2.076
+12,2.287
+13,2.345
+14,2.398
+15,2.451
+16,2.358
+17,2.303
+18,2.322
+19,2.325
+20,2.370
+21,2.277
+22,2.591
+23,2.312
+24,2.333
+25,2.281
+26,2.453
+27,2.351
+28,2.348
+29,2.452
+30,2.402
+31,2.271
+32,2.314
+33,2.304
+34,2.377
+35,2.443
+36,2.589
+37,2.267
+38,2.554
+39,2.075
+40,2.406
+41,2.395
+42,2.509
+43,2.291
+44,2.370
+45,2.278
+46,2.531
+47,2.289
+48,2.345
+49,2.459
+50,2.495
+51,2.319
+52,2.310
+53,2.528
+54,2.266
+55,2.134
+56,2.413
+57,2.479
+58,2.307
+59,2.343
+60,2.343
+61,2.313
+62,2.317
+63,2.437
+64,2.618
+65,2.316
+66,2.275
+67,2.355
+68,2.496
+69,3.997
+70,1.704
+71,2.353
+72,2.285
+73,2.434
+74,2.389
+75,2.356
+76,2.330
+77,2.531
+78,2.477
+79,2.260
+80,2.493
+81,2.136
+82,2.432
+83,2.324
+84,2.498
+85,2.430
+86,2.364
+87,2.346
+88,2.374
+89,2.370
+90,2.469
+91,2.394
+92,2.653
+93,2.326
+94,2.441
+95,2.285
+96,2.397
+97,2.411
+98,2.333
+99,2.582
+100,2.372
+101,2.375
+102,2.631
+103,2.965
+104,3.026
+105,2.361
+106,2.379
+107,2.281
+108,2.321
+109,2.503
+110,2.532
+111,2.646
+112,2.486
+113,2.462
+114,2.115
+115,2.502
+116,2.149
+117,2.329
+118,2.306
+119,2.578
+120,2.298
+121,2.323
+122,2.318
+123,2.307
+124,2.482
+125,2.383
+126,2.470
+127,2.285
+128,2.392
+129,2.402
+130,2.455
+131,2.296
+132,2.294
+133,2.577
+134,2.288
+135,2.537
+136,2.214
+137,2.279
+138,2.664
+139,2.348
+140,2.444
+141,2.430
+142,2.269
+143,2.317
+144,2.392
+145,2.350
+146,2.333
+147,2.558
+148,2.401
+149,2.335
+150,2.203
+151,2.473
+152,2.471
+153,2.677
+154,1.980
+155,2.721
+156,2.139
+157,2.277
+158,2.348
+159,2.312
+160,2.412
+161,2.498
+162,2.372
+163,2.421
+164,2.249
+165,2.525
+166,2.750
+167,2.465
+168,2.560
+169,2.400
+170,2.310
+171,2.423
+172,2.274
+173,2.482
+174,2.581
+175,2.375
+176,2.285
+177,2.325
+178,2.386
+179,2.379
+180,2.344
+181,2.424
+182,2.635
+183,2.188
+184,2.378
+185,2.258
+186,2.361
+187,2.445
+188,2.280
+189,2.589
+190,2.373
+191,2.349
+192,2.514
+193,2.153
+194,2.271
+195,2.519
+196,2.469
+197,2.509
+198,2.293
+199,2.324
+200,2.317
+201,2.569
+202,2.400
+203,2.527
+204,2.406
+205,2.347
+206,2.361
+207,2.414
+208,2.320
+209,2.481
+210,2.462
+211,2.333
+212,2.306
+213,2.334
+214,2.377
+215,2.447
+216,2.465
+217,2.431
+218,2.304
+219,2.551
+220,2.308
+221,2.373
+222,2.286
+223,2.389
+224,2.524
+225,2.309
+226,2.367
+227,2.358
+228,2.512
+229,2.235
+230,2.320
+231,2.581
+232,2.308
+233,2.410
+234,2.531
+235,2.322
+236,2.585
+237,2.453
+238,2.407
+239,2.279
+240,2.464
+241,2.336
+242,2.282
+243,2.487
+244,2.557
+245,2.214
+246,2.390
+247,2.535
+248,2.234
+249,2.220
+250,2.491
+251,2.446
+252,2.356
+253,2.296
+254,2.502
+255,2.400
+256,2.255
+257,2.592
+258,2.288
+259,2.310
+260,2.443
+261,2.326
+262,2.392
+263,2.414
+264,2.332
+265,2.501
+266,2.381
+267,2.331
+268,2.355
+269,2.331
+270,2.452
+271,2.476
+272,2.625
+273,2.297
+274,2.411
+275,2.254
+276,2.355
+277,2.368
+278,2.416
+279,2.531
+280,2.358
+281,2.349
+282,2.372
+283,2.355
+284,2.388
+285,2.253
+286,2.679
+287,2.415
+288,2.346
+289,2.340
+290,2.390
+291,2.356
+292,2.311
+293,2.582
+294,2.344
+295,2.532
+296,2.309
+297,2.319
+298,2.434
+299,2.413
+300,2.510
+301,2.509
+302,2.441
+303,2.262
+304,2.482
+305,2.397
+306,2.386
+307,2.498
+308,2.409
+309,2.321
+310,2.395
+311,2.927
+312,2.988
+313,2.479
+314,2.328
+315,2.392
+316,2.764
+317,1.912
+318,2.353
+319,2.569
+320,2.505
+321,2.299
+322,2.310
+323,2.414
+324,2.342
+325,2.488
+326,2.365
+327,2.515
+328,2.224
+329,2.466
+330,2.309
+331,2.380
+332,2.319
+333,2.453
+334,2.639
+335,2.300
+336,2.480
+337,2.116
+338,2.343
+339,2.263
+340,2.641
+341,2.473
+342,2.281
+343,2.511
+344,2.300
+345,2.290
+346,2.348
+347,2.306
+348,2.820
+349,2.170
+350,2.425
+351,2.290
+352,2.354
+353,2.256
+354,2.316
+355,2.586
+356,2.308
+357,2.318
+358,2.376
+359,2.364
+360,2.347
+361,2.451
+362,2.297
+363,2.574
+364,2.518
+365,2.191
+366,2.312
+367,2.314
+368,2.421
+369,2.476
+370,2.697
+371,2.183
+372,2.402
+373,2.322
+374,2.690
+375,3.341
+376,2.525
+377,2.423
+378,2.467
+379,2.350
+380,2.235
+381,3.062
+382,2.342
+383,2.556
+384,2.308
+385,2.366
+386,2.396
+387,2.573
+388,2.818
+389,2.460
+390,2.367
+391,2.335
+392,2.323
+393,2.529
+394,2.554
+395,2.758
+396,2.544
+397,2.394
+398,2.332
+399,2.289
+400,2.703
+401,2.451
+402,2.682
+403,2.498
+404,2.500
+405,2.281
+406,2.429
+407,2.493
+408,2.963
+409,2.419
+410,2.304
+411,2.322
+412,2.302
+413,2.604
+414,2.349
+415,2.797
+416,2.552
+417,2.296
+418,2.340
+419,2.585
+420,2.463
+421,2.269
+422,2.782
+423,2.479
+424,2.491
+425,2.206
+426,2.709
+427,2.325
+428,2.589
+429,2.607
+430,2.445
+431,2.410
+432,2.897
+433,2.166
+434,2.247
+435,2.815
+436,2.430
+437,2.368
+438,2.544
+439,2.543
+440,2.277
+441,2.422
+442,2.779
+443,2.530
+444,2.373
+445,2.642
+446,2.475
+447,2.233
+448,2.323
+449,3.161
+450,2.036
+451,2.269
+452,2.700
+453,2.355
+454,2.284
+455,2.931
+456,2.389
+457,2.426
+458,2.341
+459,2.396
+460,2.296
+461,2.438
+462,2.583
+463,2.309
+464,2.647
+465,2.184
+466,2.401
+467,2.276
+468,2.330
+469,2.550
+470,2.469
+471,2.370
+472,2.376
+473,2.483
+474,2.213
+475,2.286
+476,2.339
+477,2.522
+478,2.374
+479,2.354
+480,2.356
+481,2.309
+482,2.523
+483,2.589
+484,2.007
+485,2.830
+486,2.211
+487,2.350
+488,2.338
+489,2.271
+490,2.740
+491,2.495
+492,2.356
+493,2.351
+494,2.355
+495,2.284
+496,2.340
+497,2.367
+498,2.666
+499,2.702
+500,2.653
+501,1.895
+502,2.422
+503,2.288
+504,2.468
+505,2.813
+506,2.235
+507,2.862
+508,2.273
+509,2.495
+510,2.192
+511,2.684
+512,2.679
+513,2.292
+514,2.370
+515,2.447
+516,2.570
+517,3.059
+518,2.939
+519,2.289
+520,2.375
+521,2.357
+522,2.420
+523,2.280
+524,2.570
+525,2.590
+526,2.522
+527,2.200
+528,2.229
+529,2.466
+530,2.722
+531,2.056
+532,2.658
+533,2.298
+534,2.329
+535,2.516
+536,2.205
+537,2.390
+538,2.366
+539,2.439
+540,2.361
+541,2.326
+542,2.376
+543,2.427
+544,2.362
+545,2.336
+546,2.494
+547,2.334
+548,2.319
+549,2.386
+550,2.384
+551,2.273
+552,2.379
+553,2.656
+554,2.264
+555,2.298
+556,2.375
+557,2.378
+558,2.416
+559,2.486
+560,2.395
+561,2.456
+562,2.256
+563,2.282
+564,2.300
+565,2.439
+566,2.439
+567,2.896
+568,2.049
+569,2.322
+570,2.372
+571,2.432
+572,2.295
+573,2.298
+574,2.552
+575,2.365
+576,2.444
+577,2.421
+578,2.704
+579,2.255
+580,2.904
+581,2.389
+582,2.314
+583,2.528
+584,2.223
+585,2.588
+586,2.296
+587,2.282
+588,2.676
+589,2.286
+590,2.390
+591,2.408
+592,2.361
+593,2.404
+594,2.326
+595,2.483
+596,2.412
+597,2.468
+598,2.454
+599,2.245
+600,2.580
+601,2.306
+602,2.496
+603,2.445
+604,2.363
+605,2.316
+606,2.504
+607,2.185
+608,2.649
+609,2.218
+610,2.401
+611,2.494
+612,2.271
+613,2.332
+614,2.296
+615,2.479
+616,2.406
+617,2.377
+618,2.382
+619,2.437
+620,2.222
+621,2.428
+622,2.316
+623,2.569
+624,2.450
+625,2.354
+626,2.305
+627,2.297
+628,2.346
+629,2.435
+630,2.506
+631,2.671
+632,2.185
+633,2.293
+634,2.362
+635,2.552
+636,2.566
+637,2.446
+638,2.304
+639,2.348
+640,2.352
+641,2.357
+642,2.371
+643,2.557
+644,2.339
+645,2.333
+646,2.325
+647,2.420
+648,2.355
+649,2.457
+650,2.512
+651,2.364
+652,2.790
+653,2.245
+654,2.109
+655,2.333
+656,2.338
+657,2.555
+658,2.351
+659,2.486
+660,2.342
+661,2.283
+662,2.240
+663,2.468
+664,2.655
+665,2.314
+666,2.281
+667,2.452
+668,2.320
+669,2.366
+670,2.533
+671,2.590
+672,2.264
+673,2.365
+674,2.354
+675,2.350
+676,2.377
+677,2.627
+678,2.369
+679,2.394
+680,2.389
+681,2.261
+682,2.363
+683,2.400
+684,2.308
+685,2.565
+686,2.394
+687,2.347
+688,2.329
+689,2.369
+690,2.417
+691,2.520
+692,2.222
+693,2.428
+694,2.368
+695,2.390
+696,2.291
+697,2.474
+698,2.309
+699,2.732
+700,2.419
+701,2.291
+702,2.367
+703,2.422
+704,2.476
+705,2.211
+706,2.560
+707,2.351
+708,2.350
+709,2.352
+710,2.284
+711,2.377
+712,2.393
+713,2.682
+714,2.155
+715,2.364
+716,2.369
+717,2.345
+718,2.338
+719,2.379
+720,2.601
+721,2.433
+722,2.513
+723,2.496
+724,2.967
+725,2.579
+726,2.513
+727,2.497
+728,2.268
+729,2.610
+730,2.122
+731,2.441
+732,2.628
+733,2.468
+734,2.228
+735,2.377
+736,2.401
+737,2.267
+738,2.391
+739,2.624
+740,2.467
+741,2.334
+742,2.281
+743,2.385
+744,2.297
+745,2.432
+746,2.300
+747,2.591
+748,2.408
+749,2.330
+750,2.275
+751,2.374
+752,2.385
+753,2.336
+754,2.628
+755,2.263
+756,2.397
+757,2.431
+758,2.387
+759,2.326
+760,2.398
+761,2.554
+762,2.389
+763,2.310
+764,2.465
+765,2.402
+766,2.263
+767,2.688
+768,2.262
+769,2.439
+770,2.164
+771,2.312
+772,2.342
+773,2.395
+774,2.322
+775,2.617
+776,2.289
+777,2.343
+778,2.333
+779,2.348
+780,2.497
+781,2.299
+782,2.589
+783,2.358
+784,2.442
+785,2.235
+786,2.716
+787,2.350
+788,2.839
+789,2.490
+790,2.439
+791,2.438
+792,2.464
+793,2.527
+794,2.897
+795,1.939
+796,2.509
+797,3.275
+798,2.123
+799,2.300
+800,2.425
+801,2.699
+802,2.275
+803,2.523
+804,2.232
+805,3.105
+806,2.195
+807,2.389
+808,2.264
+809,2.813
+810,2.257
+811,2.300
+812,2.543
+813,2.283
+814,2.533
+815,2.308
+816,2.481
+817,2.374
+818,2.504
+819,3.008
+820,2.266
+821,2.351
+822,2.459
+823,2.748
+824,2.512
+825,2.257
+826,2.434
+827,2.430
+828,2.253

Docs/release-checks.md

@@ -36,12 +36,12 @@ Measured at 1440p on the development workstation: Bazzite, Ryzen 7 7700X, 64 GB
 
 | Version | Check                   | Result | Evidence | Date |
 | ------- | ----------------------- | ------ | -------- | ---- |
-| `0.1.0` | Traversal, both sides   | —      | —        | —    |
+| `0.1.0` | Traversal, both sides   | PASS — Blender pre-check + in-engine swept transect, 0 holes, ground Z 317..395 | `-qaselftest`, TODO 0.1.0 notes | 2026-11-08 |
 | `0.1.0` | Placement vs references | PASS (with deliberate simplifications) | Section below, 2026-11-08 | 2026-11-08 |
 | `0.1.0` | Collision and packaging | PASS — no blocking collision, no invisible walls, no seam gaps (see audit note) | `-qaselftest` on the packaged build, 2026-11-08 | 2026-11-08 |
-| `0.1.0` | 60 FPS at 1440p         | —      | —        | —    |
-| `0.1.0` | Fresh checkout build    | —      | —        | —    |
-| `0.1.0` | Packaged Linux build    | —      | —        | —    |
+| `0.1.0` | 60 FPS at 1440p         | PASS — 2.42 ms avg (414 fps), p99 3.01 ms at 2560×1440, TSR on, VSync off, no FG | `-qaselftest` perf capture, `Docs/perf/0.1.0-walk-frametimes.csv` | 2026-11-08 |
+| `0.1.0` | Fresh checkout build    | PASS — clean clone of `main` (`4bc41e9`), `git lfs pull` + `check-lfs.sh` OK (130 LFS files), both `GigLineEditor` and `GigLine` targets built with the documented engine | `/tmp/fresh-check`, 2026-11-08 | 2026-11-08 |
+| `0.1.0` | Packaged Linux build    | PASS — packaged Development build launches straight into DemoMap, no missing-asset/linker errors; controls shown in-game and in `Docs/controls.md` | `Docs/perf/0.1.0-packaged-hud-controls.png`, 2026-11-08 | 2026-11-08 |
 
 ## `0.1.0` — Placement vs references — record (2026-11-08)
 
@@ -95,6 +95,15 @@ Run on the packaged build (`GigLineQA`, Development, Vulkan SM5) with `-qaselfte
 - **Invisible-wall probe:** horizontal traces 30 m long, grounded at 160 cm above
   the local ground, along the road and both seam rows. Result **0/35 blocking hits
   inside 21 m** — no invisible walls or misplaced blockers in the street envelope.
+- **Facade occlusion probe:** from the road centre, 40 m traces sideways at walking
+  height toward each frontage, required only where the map stages a building (the
+  spans are listed in `AGigLineCharacter` and mirror `Tools/ue_build_demo_map.py`).
+  Result **0/9 directions without a blocking wall** — the player cannot walk
+  through the hero or the frontage. This probe found the hero façade had **no
+  simple collision** at all (complex-only, so traces and capsule sweeps passed
+  through it); it is now `UseComplexAsSimple`. Auto-generated convex hulls were
+  tried first and rejected: on a 95-part, 26 m façade they bulged into the street
+  (the wall probe went 0/35 → 2/35).
   (First pass used a fixed Z 160 start; the street is at Z ~366, so the probe
   started inside the earth and reported every row as a dist-0 blocker. Grounding
   the probe fixed that measurement bug.)
@@ -106,3 +115,99 @@ Run on the packaged build (`GigLineQA`, Development, Vulkan SM5) with `-qaselfte
 - Caveat recorded: ground Z extremes (−12 m / 3000 cm) are trace-start/terrain-edge
   artifacts of the widened extent, not walkable holes — the walkable corridor is
   continuous (walk + transect both PASS).
+
+## `0.1.0` — 60 FPS at 1440p — record (2026-11-08)
+
+**Build under test:** packaged `GigLineQA` Development, UE **5.8.4**, Vulkan SM5,
+NVIDIA 615.78.08 (RTX 5070 Ti), Bazzite, Ryzen 7 7700X, 64 GB RAM.
+
+**Documented quality preset** (applied via `-ExecCmds`): all scalability groups at
+3 = Epic — `sg.ViewDistanceQuality 3, sg.ShadowQuality 3,
+sg.GlobalIlluminationQuality 3, sg.ReflectionQuality 3, sg.PostProcessQuality 3,
+sg.TextureQuality 3, sg.EffectsQuality 3, sg.FoliageQuality 3, sg.ShadingQuality 3`.
+
+**Upscaling state (recorded from the run):** `r.AntiAliasingMethod=4` → **TSR on**,
+default screen percentage, `r.VSync=0` (**off**), frame generation **off/unavailable**
+(`r.Streamline.FrameGeneration.Mode` absent → -999).
+
+**Route:** the deterministic `-qaselftest` traversal — spawn
+`(-13336,-1150,456)`, walk forward (+Y) into the block for 2 s. Frame times are
+captured every frame over that route (829 frames), not a single sample.
+
+**Result at 2560×1440:**
+
+| Metric | Value |
+| --- | --- |
+| Frames captured | 829 |
+| Average | **2.42 ms → 414 fps** |
+| p50 | 2.38 ms |
+| p95 | 2.71 ms |
+| p99 | 3.01 ms (≈332 fps) |
+| Max | 4.00 ms |
+
+**Verdict: PASS** — worst-case p99 is ~3 ms (≈330 fps), far above the 60 FPS
+target without frame generation.
+
+**Variance note:** two back-to-back runs measured ~9.2 ms (≈108 fps) when another
+game instance / busy compositor overlapped the capture; repeated clean runs
+(windowed and fullscreen, Wayland and X11 drivers, window focused) all measured
+~2.4–2.5 ms. The high outlier is recorded here rather than hidden.
+
+**Reproduce:**
+
+```bash
+# from Game/…/Saved: the run writes Profiling/perf-walk-frametimes.csv
+./GigLine.sh -fullscreen -ResX=2560 -ResY=1440 -nosplash -qaselftest \
+  -ExecCmds="sg.ViewDistanceQuality 3,sg.ShadowQuality 3,sg.GlobalIlluminationQuality 3,sg.ReflectionQuality 3,sg.PostProcessQuality 3,sg.TextureQuality 3,sg.EffectsQuality 3,sg.FoliageQuality 3,sg.ShadingQuality 3"
+```
+
+Committed frame-time series: `Docs/perf/0.1.0-walk-frametimes.csv`.
+
+## `0.1.0` — Fresh checkout build — record (2026-11-08)
+
+Followed the documented steps in [`Docs/build.md`](build.md) exactly, into a clean
+directory with no prior state:
+
+```bash
+git clone https://git.allucanget.biz/zwitschi/gig-line.git /tmp/fresh-check
+cd /tmp/fresh-check && git lfs install && git lfs pull
+Tools/check-lfs.sh                      # -> "LFS check OK: 130 LFS-tracked file(s)"
+cd /run/media/system/DATA/Engines/UE_5.8.4
+Engine/Build/BatchFiles/Linux/Build.sh GigLineEditor Linux Development \
+  -project=/tmp/fresh-check/Game/GigLine/GigLine.uproject -WaitMutex
+Engine/Build/BatchFiles/Linux/Build.sh GigLine Linux Development \
+  -project=/tmp/fresh-check/Game/GigLine/GigLine.uproject -WaitMutex
+```
+
+- Clone of `main` at `4bc41e9`; LFS objects fetched (`DemoMap.umap` is real UE
+  package content, not a pointer).
+- `GigLineEditor` → **Result: Succeeded** (28.2 s); produced
+  `/tmp/fresh-check/Game/GigLine/Binaries/Linux/libUnrealEditor-GigLine.so`.
+- `GigLine` (game) → **Result: Succeeded** (26.9 s).
+- Engine: documented external install at `/run/media/system/DATA/Engines/UE_5.8.4`
+  (UE 5.8.4), system clang; no machine-specific paths beyond the documented
+  `-project=` argument.
+
+**Verdict: PASS.**
+
+## `0.1.0` — Packaged Linux build + documented controls — record (2026-11-08)
+
+**Package:** `RunUAT BuildCookRun … -platform=Linux -clientconfig=Development
+-cook -build -stage -pak -archive -archivedirectory=/run/media/system/DATA/Builds/GigLineQA`
+→ `EXIT=0` (Success).
+
+**Launch:** `./GigLine.sh -windowed` (plain, no map argument) →
+`LogLoad: LoadMap: /Game/Hollywood/DemoMap?Name=Player` — the packaged game opens
+the walkable demo directly (the default-map fix holds in a package, not just the
+editor). No `LogLinker`/missing-asset/failed-to-find errors in the run.
+
+**Controls documented and shown in-game:**
+- `Docs/controls.md` — full binding table (WASD, mouse look, Space, R, Esc) plus
+  how to test input headlessly.
+- `AGigLineHUD` now draws a control legend bottom-right every frame:
+  "WASD move · Mouse look · Space jump · R reset · Esc pause".
+- Verified in the packaged capture: the bottom-right text bbox is 426×12 px
+  (a single right-aligned line), attributed text bottom-left. Screenshot:
+  `Docs/perf/0.1.0-packaged-hud-controls.png`.
+
+**Verdict: PASS.**

Game/GigLine/Source/GigLine/GigLineCharacter.cpp

@@ -14,6 +14,9 @@
 #include "Kismet/GameplayStatics.h"
 #include "Misc/CommandLine.h"
 #include "Misc/Parse.h"
+#include "Misc/FileHelper.h"
+#include "Misc/Paths.h"
+#include "HAL/FileManager.h"
 
 // Development-only diagnostics for the walkable demo. These describe the spawn
 // and input setup and are not needed in a shipped build's log spam; disable
@@ -192,6 +195,9 @@ void AGigLineCharacter::StartQASelfTest()
 		bool bResetReturned = false;
 		bool bPausedOn = false;
 		bool bUnpausedBack = false;
+		// Performance capture over the fixed walk route (1.0-3.0 s).
+		TArray<float> FrameMs;
+		bool bPerfLogged = false;
 	};
 
 	TSharedPtr<FQAState> State = MakeShared<FQAState>();
@@ -219,6 +225,8 @@ void AGigLineCharacter::StartQASelfTest()
 			if (bQATestWalking)
 			{
 				AddMovementInput(GetActorForwardVector(), 1.0f);
+				// Frame time for the perf capture (this ticker runs every frame).
+				State->FrameMs.Add(DeltaTime * 1000.0f);
 			}
 
 			// 3.0: stop and measure.
@@ -233,6 +241,57 @@ void AGigLineCharacter::StartQASelfTest()
 					TEXT("GigLine QA: walk moved %.0f cm in 2 s -> %s (Z %.0f -> %.0f)"),
 					Walked, State->bWalkMoved ? TEXT("PASS") : TEXT("FAIL"),
 					State->Start.Z, State->WalkEnd.Z);
+
+				// Perf: report frame-time stats over the fixed walk route.
+				if (!State->bPerfLogged && State->FrameMs.Num() > 10)
+				{
+					State->bPerfLogged = true;
+					TArray<float> Sorted = State->FrameMs;
+					Sorted.Sort();
+					const int32 N = Sorted.Num();
+					double Sum = 0.0;
+					for (float Ms : Sorted) { Sum += Ms; }
+					const float AvgMs = static_cast<float>(Sum / N);
+					const float P50 = Sorted[N / 2];
+					const float P95 = Sorted[FMath::Clamp((int32)(N * 0.95f), 0, N - 1)];
+					const float P99 = Sorted[FMath::Clamp((int32)(N * 0.99f), 0, N - 1)];
+					const float MaxMs = Sorted.Last();
+					FVector2D Res(0.0, 0.0);
+					if (GEngine && GEngine->GameViewport)
+					{
+						GEngine->GameViewport->GetViewportSize(Res);
+					}
+					// Record the upscaling/AA state so the check is reproducible.
+					auto CV = [](const TCHAR* Name)
+					{
+						IConsoleVariable* Var = IConsoleManager::Get().FindConsoleVariable(Name);
+						return Var ? Var->GetInt() : -999;
+					};
+					UE_LOG(LogTemp, Log,
+						TEXT("GigLine PERF: frames=%d avg=%.2fms (%.1f fps) p50=%.2f p95=%.2f p99=%.2f max=%.2f ms at %dx%d"),
+						N, AvgMs, AvgMs > 0.f ? 1000.f / AvgMs : 0.f, P50, P95, P99, MaxMs,
+						(int32)Res.X, (int32)Res.Y);
+					UE_LOG(LogTemp, Log,
+						TEXT("GigLine PERF: AntiAliasingMethod=%d ScreenPercentage=%d TSR=%d FrameGen=%d VSync=%d"),
+						CV(TEXT("r.AntiAliasingMethod")), CV(TEXT("r.ScreenPercentage")),
+						CV(TEXT("r.TSR.History.ScreenPercentage")),
+						CV(TEXT("r.Streamline.FrameGeneration.Mode")),
+						CV(TEXT("r.VSync")));
+
+					// Frame-time series, so the check has a graph source, not one sample.
+					{
+						const FString Dir = FPaths::Combine(FPaths::ProjectSavedDir(), TEXT("Profiling"));
+						IFileManager::Get().MakeDirectory(*Dir, true);
+						const FString Path = FPaths::Combine(Dir, TEXT("perf-walk-frametimes.csv"));
+						FString Csv(TEXT("frame,ms\n"));
+						for (int32 i = 0; i < N; ++i)
+						{
+							Csv += FString::Printf(TEXT("%d,%.3f\n"), i, State->FrameMs[i]);
+						}
+						FFileHelper::SaveStringToFile(Csv, *Path);
+						UE_LOG(LogTemp, Log, TEXT("GigLine PERF: frame times written to %s"), *Path);
+					}
+				}
 			}
 
 			// 3.5: reset should return to the spawn point.
@@ -357,6 +416,81 @@ void AGigLineCharacter::StartQASelfTest()
 					TEXT("GigLine QA: wall probe %d/%d traces with blocking hit inside 21 m -> %s"),
 					Walls, WallSamples,
 					Walls == 0 ? TEXT("PASS") : TEXT("FAIL"));
+
+				// Facade occlusion probe: walkable street is only half the story —
+				// the player must also NOT be able to walk through the buildings.
+				// From the road centre, fire 40 m sideways at walking height toward
+				// each frontage and require a blocking hit. A miss means the
+				// building has no collision (or only non-blocking collision) and the
+				// player would pass through the wall.
+				// Expect a wall only where the map actually stages a building.
+				// Spans below mirror the actors placed by Tools/ue_build_demo_map.py
+				// (frontage + hero) and the two north buildings; update them if
+				// that list changes. Gaps between buildings are legitimate misses.
+				struct FSpan { float Min, Max; };
+				static const FSpan SouthSpans[] = {
+					{-24276.f, -17700.f}, // 6922
+					{-17749.f, -14591.f}, // 6902
+					{-14638.f, -12034.f}, // 6840 hero
+					{-12082.f, -8210.f},  // 6838 El Capitan Theatre
+					{-7854.f, -7252.f},   // 6822 Budget
+					{-6608.f, -3307.f},   // 6806-6820
+					{-3320.f, -1437.f},   // 6800 Lee Drug
+				};
+				static const FSpan NorthSpans[] = {
+					{-27071.f, -22799.f}, // Madame Tussaud's
+					{-22889.f, -18442.f}, // TCL Chinese Theatre
+				};
+				auto InSpans = [](const FSpan* Spans, int32 Count, float X)
+				{
+					for (int32 i = 0; i < Count; ++i)
+					{
+						if (X >= Spans[i].Min && X <= Spans[i].Max) { return true; }
+					}
+					return false;
+				};
+				int32 Facades = 0, FacadeSamples = 0;
+				for (float X0 = -19000.0f; X0 <= -3000.0f; X0 += 2000.0f)
+				{
+					for (float Dir : {1.0f, -1.0f}) // +Y south frontage, -Y north side
+					{
+						const bool bExpectWall = (Dir > 0.0f)
+							? InSpans(SouthSpans, UE_ARRAY_COUNT(SouthSpans), X0)
+							: InSpans(NorthSpans, UE_ARRAY_COUNT(NorthSpans), X0);
+						if (!bExpectWall)
+						{
+							continue;
+						}
+						FHitResult GroundHit2;
+						FCollisionQueryParams GQ2(TEXT("GigLineFacadeGround"), false, this);
+						if (!W->LineTraceSingleByChannel(GroundHit2,
+							FVector(X0, 0.0f, 3000.f), FVector(X0, 0.0f, -1000.f),
+							ECC_Visibility, GQ2))
+						{
+							continue;
+						}
+						const float ProbeZ2 = GroundHit2.ImpactPoint.Z + 160.f;
+						FHitResult Hit2;
+						FCollisionQueryParams Q2(TEXT("GigLineFacadeProbe"), false, this);
+						const bool bHit2 = W->LineTraceSingleByChannel(Hit2,
+							FVector(X0, 0.0f, ProbeZ2),
+							FVector(X0, Dir * 4000.f, ProbeZ2),
+							ECC_Visibility, Q2);
+						++FacadeSamples;
+						const bool bBlocking = bHit2 && Hit2.GetActor() != nullptr;
+						if (!bBlocking)
+						{
+							++Facades;
+							UE_LOG(LogTemp, Log,
+								TEXT("GigLine QA: facade probe miss at X %.0f dir %.0f (no blocking hit in 40 m)"),
+								X0, Dir);
+						}
+					}
+				}
+				UE_LOG(LogTemp, Log,
+					TEXT("GigLine QA: facade probe %d/%d directions without a blocking wall -> %s"),
+					Facades, FacadeSamples,
+					Facades == 0 ? TEXT("PASS") : TEXT("FAIL"));
 			}
 
 			// 7.0: verdict, then stop ticking.

Game/GigLine/Source/GigLine/GigLineHUD.cpp

@@ -26,4 +26,15 @@ void AGigLineHUD::DrawHUD()
 
 	DrawText(AttributionLine, Ink, X, Y, nullptr, TextScale);
 	DrawText(LicenceLine, Ink, X, Y + LineHeight, nullptr, TextScale * 0.82f);
+
+	// Control legend, bottom-right (0.1.0 release check: controls shown in-game).
+	if (!ControlsLine.IsEmpty())
+	{
+		float IgnoredW = 0.0f, ControlsH = 0.0f;
+		GetTextSize(ControlsLine, IgnoredW, ControlsH, nullptr, TextScale * 0.82f);
+		const float CX = Canvas->ClipX - MarginPx - IgnoredW;
+		const float CY = Canvas->ClipY - MarginPx - ControlsH;
+		DrawText(ControlsLine, Shadow, CX + 1.0f, CY + 1.0f, nullptr, TextScale * 0.82f);
+		DrawText(ControlsLine, Ink, CX, CY, nullptr, TextScale * 0.82f);
+	}
 }

Game/GigLine/Source/GigLine/GigLineHUD.h

@@ -28,6 +28,14 @@ public:
 	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "Attribution")
 	FString AttributionLine = TEXT("\u00A9 OpenStreetMap contributors");
 
+	/**
+	 * Control legend, shown bottom-right so the 0.1.0 demo documents its own
+	 * controls in-game (release check: "controls documented in Docs/ and shown
+	 * in-game"). Keep in sync with Docs/controls.md.
+	 */
+	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "Controls")
+	FString ControlsLine = TEXT("WASD move  \u00B7  Mouse look  \u00B7  Space jump  \u00B7  R reset  \u00B7  Esc pause");
+
 	/** Licence line, including where the licence can be read. */
 	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "Attribution")
 	FString LicenceLine = TEXT("Data \u00A9 OpenStreetMap contributors, ODbL 1.0 \u2014 openstreetmap.org/copyright");

Geo/README.md

@@ -27,6 +27,7 @@ Tools that build 3D content from these sources live next to their output in `Art
 | `elevation_probe.py` | Samples 3DEP for relief and records the baseline for the release checks |
 | `dem_stats.py` | Stdlib reader for the tiled GeoTIFF the 3DEP service returns; GDAL does not run on this host |
 | `asset_metadata.py` | Writes and audits `<asset>.geo.json` sidecars: position, provenance, conversion |
+| `mapbox_buildings.py` | Cross-checks every building's height against Mapbox `mapbox-streets-v8` building data (Tilequery per centroid), merging our OSM height + source with theirs and flagging matches, close, disagreements, non-building volumes. Needs `MAPBOX_ACCESS_TOKEN` in `.env`; caches responses under `Geo/raw/mapbox-cache/`, and **both the cache and its report are gitignored** (Mapbox terms restrict redistribution) |
 
 ## Unit boundary
 

Geo/tools/block_height_report.py

@@ -4,9 +4,21 @@
 Usage:
     Geo/tools/block_height_report.py Geo/raw/osm-api-map-2026-11-06.osm
 
-`height` and `building:levels` are the only height evidence OSM carries. Where
-neither exists, Blosm falls back to `defaultLevels * levelHeight`, which is a
-placeholder: the demo renders a constant-height block instead of a real skyline.
+Height evidence, in priority order:
+
+1. the OSM `height` tag (a direct measurement);
+2. an explicit override in `HEIGHT_OVERRIDES` (currently Mapbox-derived — see below);
+3. `building:levels` x `LEVEL_HEIGHT`;
+4. a flagged placeholder guess.
+
+`LEVEL_HEIGHT` is 3.1 m, not the 3.2 m first assumed: cross-checking every block
+building against Mapbox's building data (`Geo/tools/mapbox_buildings.py`) showed
+our `levels x 3.2 m` figure running 0.6 m high per six levels, i.e. 3.1 m per
+level. That calibration was adopted on 2026-11-09.
+
+`HEIGHT_OVERRIDES` carries the few buildings where Mapbox disagrees with a guess;
+each entry records why, so the number is not orphaned from its evidence.
+
 This tool lists every building in the demo bounds with its height source, so the
 substitutions are visible and measurable rather than buried in the model.
 
@@ -19,7 +31,45 @@ import sys
 
 import osm_common as oc
 
-LEVEL_HEIGHT = 3.2
+LEVEL_HEIGHT = 3.1
+
+# Per-way height overrides, applied after the OSM height tag and before the
+# levels/guess derivation. Keep `reason` short but specific: a height without its
+# evidence is a guess wearing a costume.
+HEIGHT_OVERRIDES = {
+    # Rear outbuildings tagged only `building=yes`/`apartments`; the two-level
+    # fallback rendered them as 6.4 m blocks. Mapbox's building layer gives 3.0 m
+    # for the same footprints (single storey plus parapet), adopted 2026-11-09.
+    1490910971: (3.0, "Mapbox building layer: 3.0 m (single storey)"),
+    1492058875: (3.0, "Mapbox building layer: 3.0 m (single storey)"),
+    1492747608: (3.0, "Mapbox building layer: 3.0 m (single storey)"),
+}
+
+
+def classify_height(tags, level_height=LEVEL_HEIGHT, way_id=None):
+    """Return (height_m, source) for one OSM way's tags.
+
+    Extracted from `main()` so the classification is testable: the roof/shelter
+    rule and the "height tag beats levels beats guess" order are the parts that
+    actually decide what the blockout should render.
+    """
+    # Not building volumes: elevated roof/canopy structures and transit shelters.
+    # Found by cross-checking against Mapbox's building data
+    # (Geo/tools/mapbox_buildings.py), which returns roof/canopy/shelter for the
+    # same footprints instead of a storey count.
+    building = tags.get("building")
+    if building in ("roof", "canopy") or tags.get("amenity") == "shelter":
+        kind = building if building in ("roof", "canopy") else "shelter"
+        return 0.0, f"not a building volume ({kind})"
+    if tags.get("height"):
+        return float(tags["height"]), "height tag"
+    if way_id is not None and int(way_id) in HEIGHT_OVERRIDES:
+        height, reason = HEIGHT_OVERRIDES[int(way_id)]
+        return height, f"override: {reason}"
+    if tags.get("building:levels"):
+        return (float(tags["building:levels"]) * level_height,
+                f"levels x {level_height} m")
+    return 2 * level_height, f"GUESS: default 2 levels x {level_height} m"
 
 
 def main():
@@ -43,14 +93,7 @@ def main():
         pts = oc.way_points(nodes, refs)
         if not pts or not in_block(pts):
             continue
-        tag_height = tags.get("height")
-        levels = tags.get("building:levels")
-        if tag_height:
-            height, source = float(tag_height), "height tag"
-        elif levels:
-            height, source = float(levels) * LEVEL_HEIGHT, f"levels x {LEVEL_HEIGHT} m"
-        else:
-            height, source = 2 * LEVEL_HEIGHT, f"GUESS: default 2 levels x {LEVEL_HEIGHT} m"
+        height, source = classify_height(tags, way_id=wid)
         nearest = min(oc.project(p, line, lat0, lon0, lengths)[0] for p in pts)
         side = "S" if oc.project(pts[0], line, lat0, lon0, lengths)[2] < 0 else "N"
         rows.append((side, nearest, wid, tags.get("name", "") or tags.get("addr:housenumber", ""),
@@ -60,7 +103,8 @@ def main():
     guessed = [r for r in rows if r[5].startswith("GUESS")]
     print(f"{len(rows)} buildings in the block, {len(guessed)} with a guessed height\n")
     for side, setback, wid, name, height, source in rows:
-        flag = "  <-- guessed" if source.startswith("GUESS") else ""
+        flag = ("  <-- guessed" if source.startswith("GUESS")
+                else ("  <-- not a building volume" if source.startswith("not a building") else ""))
         print(f"{side} way {wid:>10}  setback {setback:5.1f} m  height {height:5.1f} m  "
               f"({source:26})  {name[:34]}{flag}")
 

Geo/tools/mapbox_buildings.py

@@ -0,0 +1,317 @@
+#!/usr/bin/env python3
+"""Cross-check block building heights against Mapbox's building data.
+
+Mapbox publishes building footprints with ``height`` / ``min_height`` /
+``type`` attributes in the ``mapbox-streets-v8`` tileset. They come from
+different source data than our OSM extract, so comparing the two is a cheap way
+to find buildings where our height is wrong or missing — the ``0.1.2`` finding
+that three "guessed" volumes were actually a roof, a roof and a bus shelter is
+exactly the class of problem this tool hunts for.
+
+Usage
+-----
+    # token from the environment or the ignored .env file
+    python3 Geo/tools/mapbox_buildings.py \
+        --osm Geo/raw/osm-api-map-2026-11-06.osm \
+        --out Geo/verification/2026-11-09-mapbox-buildings.md
+
+    # show only disagreements and unverifiable buildings
+    python3 Geo/tools/mapbox_buildings.py --only-diffs
+
+Every Tilequery response is cached under ``Geo/raw/mapbox-cache/`` so a re-run
+costs nothing and the report is reproducible. The cache is gitignored along with
+``Geo/raw/``.
+
+Design notes
+------------
+* Standard library only (``urllib``), like the rest of ``Geo/tools``.
+* One request per building, spaced by ``--delay`` (default 1.2 s) — Mapbox bills
+  per request and rate-limits bursts.
+* The report is a *measurement*: it prints both figures and the delta, never a
+  single verdict, so a human can decide which source to trust for a given
+  building.
+* A Tilequery hit is only accepted as "this building" when the matched polygon
+  contains or nearly contains the queried point (``distance`` ≤ ``--max-distance``).
+
+Licensing / data handling
+-------------------------
+Mapbox terms restrict persisting and redistributing their data, so **neither the
+cache nor the generated report is committed** (`.gitignore` covers
+`Geo/raw/mapbox-cache/` and `Geo/verification/*mapbox*`). They are local working
+material: re-run the tool rather than sharing the output. The token is read from
+the environment or the ignored `.env` and is never written to the cache, the
+report or the JSON.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import math
+import os
+import sys
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+
+import block_height_report as bhr  # noqa: E402
+import osm_common as oc  # noqa: E402
+
+ROOT = os.path.abspath(os.path.join(os.path.dirname(__file__), "..", ".."))
+CACHE_DIR = os.path.join(ROOT, "Geo", "raw", "mapbox-cache")
+TILESET = "mapbox.mapbox-streets-v8"
+LAYER = "building"
+API = "https://api.mapbox.com/v4"
+
+
+def load_token(explicit: str | None = None) -> str:
+    """Token from --token, the environment, or the ignored .env file."""
+    if explicit:
+        return explicit.strip()
+    token = os.environ.get("MAPBOX_ACCESS_TOKEN")
+    if token:
+        return token.strip()
+    env_path = os.path.join(ROOT, ".env")
+    if os.path.exists(env_path):
+        with open(env_path, encoding="utf-8") as handle:
+            for line in handle:
+                line = line.strip()
+                if line.startswith("MAPBOX_ACCESS_TOKEN="):
+                    return line.split("=", 1)[1].strip().strip('"').strip("'")
+    raise SystemExit(
+        "no Mapbox token: pass --token, set MAPBOX_ACCESS_TOKEN, or add it to .env")
+
+
+def centroid_lat_lon(points: list[tuple[float, float]]) -> tuple[float, float]:
+    """Centroid of a ring of (lat, lon) points, as (lat, lon)."""
+    lat = sum(p[0] for p in points) / len(points)
+    lon = sum(p[1] for p in points) / len(points)
+    return lat, lon
+
+
+def cache_path(lat: float, lon: float, radius: int) -> str:
+    return os.path.join(CACHE_DIR, f"{lat:.6f}_{lon:.6f}_r{radius}.json")
+
+
+def tilequery(lat: float, lon: float, token: str, radius: int,
+              delay: float, use_cache: bool = True) -> tuple[dict, bool]:
+    """Tilequery one point. Returns (payload, from_cache)."""
+    path = cache_path(lat, lon, radius)
+    if use_cache and os.path.exists(path):
+        with open(path, encoding="utf-8") as handle:
+            return json.load(handle), True
+
+    query = urllib.parse.urlencode({
+        "radius": radius, "layers": LAYER, "limit": 10, "access_token": token,
+    })
+    url = f"{API}/{TILESET}/tilequery/{lon:.6f},{lat:.6f}.json?{query}"
+    request = urllib.request.Request(url, headers={"User-Agent": "gig-line-geo/1.0"})
+    payload = None
+    for attempt in range(4):
+        try:
+            with urllib.request.urlopen(request, timeout=30) as response:
+                payload = json.load(response)
+            break
+        except urllib.error.HTTPError as exc:
+            if exc.code == 429 or exc.code >= 500:
+                wait = delay * (2 ** attempt)
+                sys.stderr.write(f"  HTTP {exc.code}; retrying in {wait:.1f}s\n")
+                time.sleep(wait)
+                continue
+            raise
+        except urllib.error.URLError as exc:
+            sys.stderr.write(f"  network error ({exc.reason}); retrying\n")
+            time.sleep(delay * (2 ** attempt))
+    if payload is None:
+        raise SystemExit(f"tilequery failed for {lat:.6f},{lon:.6f}")
+    if token in json.dumps(payload):
+        raise SystemExit("refusing to cache a response that contains the token")
+
+    os.makedirs(CACHE_DIR, exist_ok=True)
+    with open(path, "w", encoding="utf-8") as handle:
+        json.dump(payload, handle)
+    time.sleep(delay)  # only sleep on a real request, never on a cache hit
+    return payload, False
+
+
+def nearest_building(payload: dict, max_distance: float) -> dict | None:
+    """The closest building feature within `max_distance` metres, or None."""
+    best = None
+    for feature in payload.get("features", []):
+        props = feature.get("properties", {})
+        if props.get("tilequery", {}).get("layer") != LAYER:
+            continue
+        distance = props.get("tilequery", {}).get("distance")
+        if distance is None or distance > max_distance:
+            continue
+        if best is None or distance < best[0]:
+            best = (distance, props)
+    return None if best is None else best[1]
+
+
+def compare(ours: float, ours_source: str, theirs: float | None) -> tuple[str, float | None]:
+    """Classify the agreement between our height and Mapbox's.
+
+    Returns (verdict, delta_m). Verdicts are deliberately blunt so the report can
+    be scanned: "match", "close", "disagree", "mapbox-only", "ours-only".
+    """
+    ours_is_volume = not ours_source.startswith("not a building")
+    if not ours_is_volume:
+        return "non-building", None
+    if theirs is None:
+        return "ours-only", None
+    if ours <= 0.0:
+        return "mapbox-only", theirs
+    delta = theirs - ours
+    if abs(delta) <= 0.5:
+        return "match", delta
+    if abs(delta) <= 2.0:
+        return "close", delta
+    return "disagree", delta
+
+
+def build_rows(nodes, ways, token, radius, max_distance, delay) -> list[dict]:
+    rows = []
+    for wid, tags, refs in ways:
+        if "building" not in tags:
+            continue
+        points = oc.way_points(nodes, refs)
+        if not points:
+            continue
+        lat, lon = centroid_lat_lon(points)
+        payload, cached = tilequery(lat, lon, token, radius, delay)
+        feature = nearest_building(payload, max_distance)
+        ours_height, ours_source = bhr.classify_height(tags, way_id=wid)
+        theirs = None if feature is None else feature.get("height")
+        verdict, delta = compare(ours_height, ours_source, theirs)
+        rows.append({
+            "way": wid,
+            "name": tags.get("name") or tags.get("addr:housenumber") or "",
+            "kind": tags.get("building"),
+            "osm_height_m": round(ours_height, 2) if ours_height else 0.0,
+            "osm_source": ours_source,
+            "mapbox_height_m": None if theirs is None else round(float(theirs), 2),
+            "mapbox_min_height_m": None if feature is None else feature.get("min_height"),
+            "mapbox_type": None if feature is None else feature.get("type"),
+            "mapbox_distance_m": None if feature is None
+            else round(feature.get("tilequery", {}).get("distance", 0.0), 1),
+            "verdict": verdict,
+            "delta_m": None if delta is None else round(delta, 2),
+            "cached": cached,
+            "lat": round(lat, 6),
+            "lon": round(lon, 6),
+        })
+    return rows
+
+
+def render_markdown(rows: list[dict], args) -> str:
+    order = {"disagree": 0, "mapbox-only": 1, "ours-only": 2,
+             "non-building": 3, "close": 4, "match": 5}
+    rows = sorted(rows, key=lambda r: (order.get(r["verdict"], 9),
+                                       -abs(r["delta_m"] or 0)))
+    counts = {}
+    for row in rows:
+        counts[row["verdict"]] = counts.get(row["verdict"], 0) + 1
+
+    lines = [
+        "# Block buildings — OSM vs Mapbox",
+        "",
+        "Generated by `Geo/tools/mapbox_buildings.py`; re-run it to reproduce.",
+        "Mapbox data: tileset `mapbox-streets-v8`, layer `building`, Tilequery",
+        f"at each building centroid (radius {args.radius} m, accept ≤ "
+        f"{args.max_distance} m). OSM heights come from the tagged extract, via the",
+        "same classification used for the blockout (tag > levels > guess; roof and",
+        "shelter are not building volumes).",
+        "",
+        f"Verdicts: {', '.join(f'{k} {v}' for k, v in sorted(counts.items()))}.",
+        "",
+        "| Verdict | Δ | Building | OSM | OSM source | Mapbox | Mapbox type | dist |",
+        "| --- | ---: | --- | ---: | --- | ---: | --- | ---: |",
+    ]
+    for row in rows:
+        osm = f"{row['osm_height_m']:.1f} m"
+        mb = "—" if row["mapbox_height_m"] is None else f"{row['mapbox_height_m']:.1f} m"
+        delta = "—" if row["delta_m"] is None else f"{row['delta_m']:+.1f} m"
+        dist = "—" if row["mapbox_distance_m"] is None else f"{row['mapbox_distance_m']:.0f} m"
+        name = row["name"] or f"way {row['way']}"
+        lines.append(
+            f"| {row['verdict']} | {delta} | {name} | {osm} | {row['osm_source']} | "
+            f"{mb} | {row['mapbox_type'] or '—'} | {dist} |")
+    lines += [
+        "",
+        "## How to read this",
+        "",
+        "- **disagree** — the two sources differ by more than 2 m. One of them is",
+        "  wrong; check the reference photography before changing the model.",
+        "- **mapbox-only** — Mapbox knows a height we do not (usually a building",
+        "  with no OSM `height`/`building:levels`).",
+        "- **ours-only** — Mapbox returns no building within the accept distance;",
+        "  the footprint may be missing from its tileset, or the centroid may fall",
+        "  outside its polygon.",
+        "- **non-building** — our classification says roof/shelter; excluded from",
+        "  height comparison on purpose.",
+        "",
+        "Neither source is authoritative: OSM is community-tagged, Mapbox is a",
+        "derived commercial dataset. Treat a disagreement as a reason to look at",
+        "the photographs, not as an automatic correction.",
+        "",
+    ]
+    if args.only_diffs:
+        lines.insert(0, "> Filtered: only disagreements and unverifiable buildings.\n")
+    return "\n".join(lines)
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser(description=__doc__,
+                                 formatter_class=argparse.RawDescriptionHelpFormatter)
+    ap.add_argument("--osm", default="Geo/raw/osm-api-map-2026-11-06.osm")
+    ap.add_argument("--out", help="Markdown report path; omit to print to stdout")
+    ap.add_argument("--json", help="Also write the merged rows as JSON here")
+    ap.add_argument("--token", help="Mapbox access token (default: env/.env)")
+    ap.add_argument("--radius", type=int, default=25, help="Tilequery radius, metres")
+    ap.add_argument("--max-distance", type=float, default=8.0,
+                    help="accept a hit only within this distance of the centroid")
+    ap.add_argument("--delay", type=float, default=1.2, help="seconds between requests")
+    ap.add_argument("--only-diffs", action="store_true",
+                    help="report only disagreements / unverifiable buildings")
+    ap.add_argument("--no-cache", action="store_true", help="ignore the tilequery cache")
+    args = ap.parse_args()
+
+    token = load_token(args.token)
+    nodes, ways = oc.load(args.osm)
+    rows = build_rows(nodes, ways, token, args.radius, args.max_distance, args.delay)
+    if args.no_cache:
+        for row in rows:
+            row["cached"] = False
+    if args.only_diffs:
+        keep = {"disagree", "mapbox-only", "ours-only", "non-building"}
+        rows = [r for r in rows if r["verdict"] in keep]
+
+    markdown = render_markdown(rows, args)
+    if args.out:
+        os.makedirs(os.path.dirname(os.path.abspath(args.out)), exist_ok=True)
+        with open(args.out, "w", encoding="utf-8") as handle:
+            handle.write(markdown + "\n")
+        print(f"wrote {args.out} ({len(rows)} buildings)")
+    else:
+        print(markdown)
+
+    if args.json:
+        payload = {
+            "generated_utc": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()),
+            "osm": args.osm,
+            "mapbox": {"tileset": TILESET, "layer": LAYER,
+                       "radius_m": args.radius, "max_distance_m": args.max_distance},
+            "buildings": rows,
+        }
+        with open(args.json, "w", encoding="utf-8") as handle:
+            json.dump(payload, handle, indent=2)
+        print(f"wrote {args.json}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

MEMORY.md

@@ -331,3 +331,179 @@ Scope: facts and traps that cost time to establish. Planned work lives in [TODO.
   still all PASS (walk/reset/pause/transect 0 holes/wall 0-35).
 - Branch qa-diagnostics-0.1.0. SIM/GROUND probes were removed earlier in the
   DefaultKeyMappings fix (PR #8).
+
+## 2026-11-08 — v0.1.0 released
+
+- All six `0.1.0` release checks pass and are recorded in `Docs/release-checks.md`:
+  traversal (seam transect 0 holes), placement vs references, collision+packaging
+  (wall probe 0/35), 60 fps at 1440p (2.42 ms avg; TSR on, VSync off, no FG),
+  fresh-checkout build, packaged Linux build with controls shown in-game.
+- `CHANGELOG.md` gets the `0.1.0` entry; the completed `0.1.0` section was removed
+  from `TODO.md` (goal stays in `ROADMAP.md`); tag `v0.1.0` cut on `main`.
+- Owner approved the regenerated screenshot set (PR #15) on 2026-11-08.
+- THIRD_PARTY_NOTICES switched to checkbox statuses (`[x]`/`[P]`/`[ ]`); all tools
+  incl. Blosm, QGIS and Git LFS are now verified as tool-only.
+- Next work: the `0.1.1` collision-detail patch (sidewalk outer edge 15.8 cm step,
+  crossing ramp gradient 10 %, kerb height assumption, traversal regression).
+
+## 2026-11-08 — v0.1.1 released (collision patch)
+
+- Sidewalk upstand now tapers full-at-kerb → zero at the building edge (removes the
+  15.8 cm outer ledge). Crossing ramp run derives from `--max-ramp-grade` (8 % ⇒
+  1.63 m) instead of a fixed 1.5 m/8.7 %. Street + site rebuilt, site re-imported,
+  DemoMap rebuilt, packaged build verified.
+- Pre-check tool fixes: coverage no longer shrinks with `--sample` (it used
+  `range(int(block_len))`), and it reports grade + location of the worst step.
+- Residual, documented not hidden: 13.4 cm surface step at s≈198 (south) / 8.0 cm
+  at s≈251 (north) — a strip discontinuity near a centreline vertex, below the
+  45 cm MaxStepHeight, so not blocking.
+- Kerb height finalised at 0.15 m modelled / 0.13 m built (6 in LA standard; DEM
+  and photos can't resolve finer).
+
+## 2026-11-09 — Mapbox building data as a second height source
+
+- `Geo/tools/mapbox_buildings.py` (new, stdlib `urllib`) Tilequeries
+  `mapbox.mapbox-streets-v8` layer `building` at every building centroid in the
+  extract and merges the answer with our OSM height + source. Token comes from
+  `MAPBOX_ACCESS_TOKEN` in the ignored `.env`; responses cache to
+  `Geo/raw/mapbox-cache/`.
+- **Mapbox terms restrict persisting/redistributing their data**, so `.gitignore`
+  now covers `/Geo/raw/mapbox-cache/` and `/Geo/verification/*mapbox*`. The tool
+  also refuses to cache a response that contains the token.
+- **First run (72 buildings): 58 match, 5 close, 3 disagree, 6 non-building.**
+  - It independently classifies our roof/canopy/shelter volumes as `roof`/
+    `shelter` — corroborating the `0.1.2` finding that they are not buildings.
+  - Remaining disagreements are untyped `building=yes`/`apartments` rear
+    structures where our fallback guess (2 × 3.2 m = 6.4 m) meets Mapbox's 3.0 m.
+  - Every "close" case is a `building:levels × 3.2 m` building where Mapbox is
+    **0.6 m lower per 6 levels** → Mapbox implies **3.1 m per level**, not 3.2.
+    Worth revisiting `LEVEL_HEIGHT` if a measured storey height ever lands.
+  - Its query API surface: `height`, `min_height`, `type`, `extrude` per polygon.
+
+## 2026-11-09 — Mapbox calibration adopted into the blockout
+
+- Owner decision: adopt Mapbox. Applied:
+  - `LEVEL_HEIGHT` 3.2 → **3.1 m** in `Geo/tools/block_height_report.py`, and the
+    Blosm `--level-height` default in `Art/blender/blockout/blosm_blockout.py`.
+  - `HEIGHT_OVERRIDES` in block_height_report: ways 1490910971, 1492058875,
+    1492747608 → 3.0 m (Mapbox single-storey; the 2-level guess gave 6.4 m).
+  - `classify_height(tags, level_height, way_id)` now takes the way id so
+    overrides apply; `mapbox_buildings.py` passes it, so the cross-check agrees
+    with the height table.
+- Re-running the cross-check: **66 match, 6 non-building, 0 close/disagree**.
+- Geometry: blockout regenerated at 3.1 (object names preserved — the frontage
+  exporter maps `element.020`/`element`/`element.019`/named buildings, all still
+  present, 6/6 exported), frontage re-imported, DemoMap rebuilt, packaged build
+  `-qaselftest` all PASS.
+- **Blosm adds roof mass** on top of `levels × levelHeight`: 6922 39.1 m vs table
+  37.2, El Capitan Theatre 20.5 m vs 18.6 — both ~+1.9 m. That is a roof, not a
+  height error; the table is the tagged height, the mesh is storey + roof.
+- Gotcha: regenerating the blockout is safe for names, but any future change to
+  the import must re-verify the 6/6 frontage export and the `element.*` mapping.
+
+## 2026-11-09 — hero colonnade proportion fixed (47.6 % → 53.1 %)
+
+- The hero's colonnade (columns 2.00–7.95 + capitals 7.95–8.90) was 6.90 m of the
+  14.50 m elevation = **47.6 %**, below the photographed 50–60 %, because the
+  entablature (3.40 m) and parapet (2.20 m) used 5.60 m of the height.
+- Thinned ENTABLATURE_H 3.40 → 3.00 and PARAPET_H 2.20 → 1.80 in
+  `Tools/hero_facade_build.py`; the colonnade grows to **7.70 m = 53.1 %** while the
+  envelope, motto band and medallions keep their relationships (all positioned
+  relative to those two constants).
+- **Gotcha (cost a bad build):** `hero_facade_build.py` takes `--out` for the
+  **FBX** and `--save-blend` for the `.blend`. Passing `--out <file>.blend` writes
+  FBX bytes over the blend and Blender then reports "File format is not supported".
+  Correct invocation: `--out /tmp/gigline/hero-facade.fbx --save-blend Art/...blend
+  --report Art/...json`.
+- Rebuilt hero → re-imported (`SM_HeroFacade`, bounds 2604 × 1257 × 1450 cm) →
+  DemoMap rebuilt → screenshots re-rendered. Note `ue_hero_facade_import.py` saves
+  the map, so `chmod u+w` the `.umap` first or the import silently does not persist.
+
+## 2026-11-09 — AI detail plates from reference photos; floating windows fixed
+
+- `Tools/facade_detail_concepts.py` generates architectural detail plates from one
+  local reference photograph via OpenRouter image models (default
+  `google/gemini-2.5-flash-image`; the sibling project uses the same route in
+  `tools/generate_textures.py` — chat/completions with a text + image_url content
+  part, image returned as `message.images[].image_url.url`). Eight studies,
+  `--list` free, `--all` generates, `-vN` never overwrites, `.refgen.json` sidecar
+  per image, all output under gitignored `Art/reference/facade-details/`.
+- **Prompt gotcha:** the model refuses when the prompt describes features the
+  reference photograph does not show ("the image you sent appears to be a
+  decorative architectural detail, not an entrance with steps"). Prompts must
+  describe the *reference subject* and only restage light/people/surface.
+- **Output is real:** 1184×864 to 1344×768 PNGs, ~2 MB each.
+- **Measured defect found and fixed:** hero window panes sat at Y −1.98 while the
+  mass front is Y −0.50 and the columns reach −1.02 — i.e. glazing floating 1.44 m
+  in front of the wall and ahead of the colonnade. Now `WINDOW_Y = −0.56`
+  (6 cm proud of the wall, behind the columns). Visible as dark openings in
+  `review-hero-facade-front`.
+- Reminder: `.blend` is LFS read-only on checkout — `chmod u+w` or Blender fails
+  with "Cannot save blend file … not writable" (this bit again here).
+
+## 2026-11-09 — UE export hygiene: smoothing groups + facade collision
+
+- **All our FBX exporters used `mesh_smooth_type="OFF"`**, which is why every Unreal
+  import logged "No smoothing group information was found for this mesh". The hero
+  now exports `"FACE"` and its round parts are shaded with
+  `shade_smooth_by_angle(35°)` before export: cylinders read as round instead of
+  faceted, and the import warning is gone (6 → 0).
+- **The hero façade had no simple collision** (complex-only), so line traces and
+  capsule sweeps passed straight through it — the player could walk through the
+  wall of the demo. Caught by a new `-qaselftest` **facade occlusion probe** (40 m
+  sideways traces from the road centre at walking height).
+- **Auto-generated convex collision on a 95-part 26 m façade is unusable**: it
+  produced coarse hulls that bulged into the street and the wall probe went
+  0/35 → 2/35. Rejected in favour of `UseComplexAsSimple` via
+  `UGigLineAssetTools.set_complex_collision_as_simple` (same reason the terrain
+  uses it), saved on the asset.
+- Probe expectations must mirror the staged buildings: the facade probe now carries
+  explicit X spans per frontage (and the TCL/Tussaud's spans on the north side) so
+  a gap between buildings is not reported as a defect.
+
+## 2026-11-09 — one FBX export preset instead of six copies
+
+- The `bpy.ops.export_scene.fbx(...)` argument block was duplicated in six scripts
+  (hero, block frontage, north buildings, site, scale test, MPFB character), and
+  all six carried `mesh_smooth_type="OFF"` — hence the "No smoothing group
+  information was found" warning on every import.
+- Now `Tools/fbx_export_preset.py` holds `ue_metric_v1` and `ue_character_v1`:
+  `preset_kwargs()` (bpy-free, unit-tested) plus `export_static()` /
+  `export_character()` wrappers that import `bpy` lazily. Every caller imports it
+  and passes `selection=True/False`; the seven duplicated blocks are gone.
+- Callers in `Tools/` resolve the module with
+  `sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))`; the Blender-side
+  `Art/blender/site/export_site_fbx.py` computes the repo root
+  (`..`, `..`, `..`) and joins `Tools`. Getting that wrong silently inserts
+  `Tools/Tools` — check the import path when adding a caller.
+- Verified end to end: scale test, hero, frontage (6/6), site (7/7) and north
+  buildings all re-exported through the preset, re-imported with **0 smoothing
+  warnings**, DemoMap rebuilt and `-qaselftest` all PASS (walk, transect 0 holes,
+  wall probe 0/35, facade probe 0/9).
+- `mpfb_character_export.py` was not re-run: it needs the MPFB add-on on
+  `BLENDER_USER_SCRIPTS` ("Add-on not loaded: bl_ext.blender_org.mpfb"), which is
+  pre-existing and unrelated; the character is not in `0.1.x` gameplay.
+
+## 2026-11-09 — v0.1.2 released
+
+- Cornice finished: projecting corona over a **52-dentil course** (0.18 × 0.30 ×
+  0.22 m at 0.45 m centres, z 12.12–12.34, 0.25 m clear of the corona). Hero is now
+  3 044 tris across 148 parts, still 14.50 m. Verified: packaged `-qaselftest` all
+  PASS (transect 0 holes, wall probe 0/35, facade probe 0/9).
+- `CHANGELOG.md` gets the `0.1.2` entry (added/changed/fixed/verified/limitations),
+  the `0.1.2` section is removed from `TODO.md`, `ROADMAP.md` status updated, tag
+  `v0.1.2` cut after the merge.
+- Assumptions recorded rather than hidden: dentil spacing, base and abacus
+  dimensions are not resolvable in our reference photography.
+
+## 2026-11-09 — elevation cameras levelled (straight verticals)
+
+- archviz MUST: an elevation must not lean. `hero-facade-front` looked up ~4° from
+  4.2 m at a 7.6 m target; `demo-spawn-view` and `demo-street-level` were pitched
+  too. All three now put the camera at the target's height, so
+  `FindLookAtRotation` yields pitch 0 and roll 0 and verticals are parallel by
+  construction.
+- Do not try to *measure* verticality from the rendered PNG with a naive edge
+  scan: banners, windows and the parapet produce different edge sets at different
+  heights and the pairwise match is meaningless (it reported a 418 px "drift").
+  Verify it geometrically in the camera list instead.

ROADMAP.md

@@ -2,9 +2,9 @@
 
 Development roadmap for this project: milestone goals, scope, decisions, and release gates. Actionable tasks, claims, and progress marks live in [TODO.md](TODO.md).
 
-## Status at a glance — 2026-11-07 09:45
+## Status at a glance — 2026-11-08 15:30
 
-Workstation, geo pipeline, and engine validation are done. The art pipeline has a first blockout, terrain, and street in metres, in one shared coordinate frame. **Project bootstrap is complete**: `Game/GigLine` builds, packages, and both content-acceptance tests (static-mesh scale, MPFB skeletal character) pass. Remaining `0.1.0` work is geo detailing, asset production, gameplay, and release checks.
+Workstation, geo pipeline, and engine validation are done. The art pipeline has a first blockout, terrain, and street in metres, in one shared coordinate frame. **Project bootstrap is complete**: `Game/GigLine` builds, packages, and both content-acceptance tests (static-mesh scale, MPFB skeletal character) pass. **`v0.1.0` released 2026-11-08**: the walkable demo, hero façade, verified block frontage, first-person controls, ODbL attribution, and every release check pass (traversal, placement, collision, 60 fps at 1440p, fresh-checkout build, packaged build with controls). Next: the `0.1.1`–`0.1.4` patch series (collision detail, scale/façade corrections, packaging fixes, real building façades), then `0.2.0` (player body, third-person camera, animation).
 
 | Area | State |
 | --- | --- |

Screenshots/README.md

@@ -14,24 +14,30 @@ Rebuilds `Game/GigLine/Content/Test/ReviewMap.umap` from current content, runs t
 
 ## Shot list
 
-All shots ☑ approved 2026-11-07, including the block frontage pass that added the neighbouring buildings and corrected the hero and north-building placement.
+**Status: whole set ☑ approved 2026-11-09** (owner review of PR #27). Every shot was re-rendered from current `main` content after the building-height calibration was adopted (`v0.1.2`): Mapbox-derived **3.1 m per level** (`Geo/tools/block_height_report.py`), explicit overrides for three rear outbuildings, and the regenerated blockout and frontage that follow — 6922 is now 39.1 m (was 42.1 m) and the El Capitan Theatre 20.5 m (was 20.0 m).
 
-| # | File | Preview | Map | View | What it shows |
-| --- | --- | --- | --- | --- | --- |
-| 1 | `review-overview.png` | [<img src="review-overview.png" alt="overview" width="180">](review-overview.png) | Review | 7 m up, NE | Whole review layout: character + both cubes on the floor |
-| 2 | `review-character.png` | [<img src="review-character.png" alt="character" width="180">](review-character.png) | Review | eye height, south | MPFB mannequin, idle pose + warm skin; feet meet the plane |
-| 3 | `review-scale-cubes.png` | [<img src="review-scale-cubes.png" alt="scale cubes" width="180">](review-scale-cubes.png) | Review | south | Floating vs grounded cube: cast vs contact shadow |
-| 4 | `review-player-placement.png` | [<img src="review-player-placement.png" alt="player placement" width="180">](review-player-placement.png) | Review | spawn | The `AGigLineCharacter` pawn, capsule height and landing |
-| 5 | `review-npc-prefab.png` | [<img src="review-npc-prefab.png" alt="npc prefab" width="180">](review-npc-prefab.png) | Review | mid, west | The `AGigLineNPCPerson` prefab: collision capsule + visible MPFB body, feet on Z 0 |
-| 6 | `review-ground-contact.png` | [<img src="review-ground-contact.png" alt="ground contact" width="180">](review-ground-contact.png) | Review | knee height, feet | Floating/sinking character is obvious here |
-| 7 | `review-shadow-compare.png` | [<img src="review-shadow-compare.png" alt="shadow compare" width="180">](review-shadow-compare.png) | Review | low angle | Detached (floating) vs touching (grounded) shadows |
-| 8 | `review-hero-portals.png` | [<img src="review-hero-portals.png" alt="hero portals" width="180">](review-hero-portals.png) | Review | 8 m, eye height | Three genuine 1.2 m portal recesses with flights and plinth |
-| 9 | `review-hero-facade-front.png` | [<img src="review-hero-facade-front.png" alt="hero facade front" width="180">](review-hero-facade-front.png) | Review | road side, straight-on | Hero façade elevation and column rhythm |
-| 10 | `review-hero-facade-oblique.png` | [<img src="review-hero-facade-oblique.png" alt="hero facade oblique" width="180">](review-hero-facade-oblique.png) | Review | north-west | Body depth and column line standing proud of the mass |
-| 11 | `demo/review-demo-spawn-view.png` | [<img src="demo/review-demo-spawn-view.png" alt="spawn view" width="180">](demo/review-demo-spawn-view.png) | Demo | north sidewalk | The whole block: hero façade between its neighbours, both sidewalks and the road |
-| 12 | `demo/review-demo-street-level.png` | [<img src="demo/review-demo-street-level.png" alt="street level" width="180">](demo/review-demo-street-level.png) | Demo | eye height, north side | The hero colonnade with the adjacent frontage buildings either side |
-| 13 | `demo/review-demo-crossing.png` | [<img src="demo/review-demo-crossing.png" alt="crossing" width="180">](demo/review-demo-crossing.png) | Demo | along the crosswalk | The designated mid-block crossing at s=130 m (UE X -14956): three zebra bars on the asphalt, with the south frontage and the hero colonnade behind |
-| 14 | `demo/review-demo-north-buildings.png` | [<img src="demo/review-demo-north-buildings.png" alt="north buildings" width="180">](demo/review-demo-north-buildings.png) | Demo | across the Blvd | North-side buildings (TCL, Tussaud's) seen from the south side across the road. **2026-11-08:** camera re-pointed to the buildings' mass centre (was 9.5 km west → 85% sky); now frames both north buildings. Flat surfaces = `0.1.4` façade scope. |
+| Round | What changed |
+| --- | --- |
+| 2026-11-07 | First approved set; block frontage pass corrected hero and north-building placement |
+| 2026-11-08 | Re-rendered after `0.1.1` street geometry (sidewalk upstand flush at the building edge, crossing ramps graded ≤ 8 %); `demo-north-buildings` camera re-pointed (was 9.5 km west, 85 % sky) |
+| 2026-11-09 | Re-rendered after the `0.1.2` building-height calibration (3.1 m per level). 12 of 14 PNGs changed; `review-demo-spawn-view` and `review-demo-street-level` are byte-identical to the `0.1.1` round, so the height change reads mostly on the frontage silhouettes |
+
+| # | File | Preview | Map | View | What it shows | ☑ |
+| --- | --- | --- | --- | --- | --- | --- |
+| 1 | `review-overview.png` | [<img src="review-overview.png" alt="overview" width="180">](review-overview.png) | Review | 7 m up, NE | Whole review layout: character + both cubes on the floor | ☑ 2026-11-09 |
+| 2 | `review-character.png` | [<img src="review-character.png" alt="character" width="180">](review-character.png) | Review | eye height, south | MPFB mannequin, idle pose + warm skin; feet meet the plane | ☑ 2026-11-09 |
+| 3 | `review-scale-cubes.png` | [<img src="review-scale-cubes.png" alt="scale cubes" width="180">](review-scale-cubes.png) | Review | south | Floating vs grounded cube: cast vs contact shadow | ☑ 2026-11-09 |
+| 4 | `review-player-placement.png` | [<img src="review-player-placement.png" alt="player placement" width="180">](review-player-placement.png) | Review | spawn | The `AGigLineCharacter` pawn, capsule height and landing | ☑ 2026-11-09 |
+| 5 | `review-npc-prefab.png` | [<img src="review-npc-prefab.png" alt="npc prefab" width="180">](review-npc-prefab.png) | Review | mid, west | The `AGigLineNPCPerson` prefab: collision capsule + visible MPFB body, feet on Z 0 | ☑ 2026-11-09 |
+| 6 | `review-ground-contact.png` | [<img src="review-ground-contact.png" alt="ground contact" width="180">](review-ground-contact.png) | Review | knee height, feet | Floating/sinking character is obvious here | ☑ 2026-11-09 |
+| 7 | `review-shadow-compare.png` | [<img src="review-shadow-compare.png" alt="shadow compare" width="180">](review-shadow-compare.png) | Review | low angle | Detached (floating) vs touching (grounded) shadows | ☑ 2026-11-09 |
+| 8 | `review-hero-portals.png` | [<img src="review-hero-portals.png" alt="hero portals" width="180">](review-hero-portals.png) | Review | 8 m, eye height | Three genuine 1.2 m portal recesses with flights and plinth | ☑ 2026-11-09 |
+| 9 | `review-hero-facade-front.png` | [<img src="review-hero-facade-front.png" alt="hero facade front" width="180">](review-hero-facade-front.png) | Review | road side, straight-on | Hero façade elevation and column rhythm | ☑ 2026-11-09 |
+| 10 | `review-hero-facade-oblique.png` | [<img src="review-hero-facade-oblique.png" alt="hero facade oblique" width="180">](review-hero-facade-oblique.png) | Review | north-west | Body depth and column line standing proud of the mass | ☑ 2026-11-09 |
+| 11 | `demo/review-demo-spawn-view.png` | [<img src="demo/review-demo-spawn-view.png" alt="spawn view" width="180">](demo/review-demo-spawn-view.png) | Demo | north sidewalk | The whole block: hero façade between its neighbours, both sidewalks and the road | ☑ 2026-11-09 |
+| 12 | `demo/review-demo-street-level.png` | [<img src="demo/review-demo-street-level.png" alt="street level" width="180">](demo/review-demo-street-level.png) | Demo | eye height, north side | The hero colonnade with the adjacent frontage buildings either side | ☑ 2026-11-09 |
+| 13 | `demo/review-demo-crossing.png` | [<img src="demo/review-demo-crossing.png" alt="crossing" width="180">](demo/review-demo-crossing.png) | Demo | along the crosswalk | The designated mid-block crossing at s=130 m (UE X -14956): three zebra bars on the asphalt, with the south frontage and the hero colonnade behind | ☑ 2026-11-09 |
+| 14 | `demo/review-demo-north-buildings.png` | [<img src="demo/review-demo-north-buildings.png" alt="north buildings" width="180">](demo/review-demo-north-buildings.png) | Demo | across the Blvd | North-side buildings (TCL, Tussaud's) seen from the south side across the road. **2026-11-08:** camera re-pointed to the buildings' mass centre (was 9.5 km west → 85% sky); now frames both north buildings. Flat surfaces = `0.1.4` façade scope. | ☑ 2026-11-09 |
 
 ## Scene conventions
 
@@ -46,10 +52,12 @@ All shots ☑ approved 2026-11-07, including the block frontage pass that added
 - **Ground contact**: feet meet the plane with no gap and no shadow seam.
 - **Scale**: everything checks against the 1 m cubes.
 - **Façade rhythm**: six columns at 4.96 m across 25.75 m should read as the photographs in silhouette.
+- **Frontage heights (new in this round)**: 6922 and the El Capitan Theatre were re-cut to the 3.1 m storey height. Check they still read as the taller west end and the lower cinema respectively against `Art/reference/hollywood/el-capitan-theatre-blade-sign-day-wikimedia-2008-10.jpg`, and that the ordering of the six frontage buildings is unchanged.
 
 ## Known cosmetic issues
 
 - Floor speckle from the `Constant3Vector` wiring in `Tools/ue_build_review_map.py`.
 - Hero façade renders pale — Blender flat colours with no normal/roughness, so it reads as untextured stone (the `0.1.4` façade patch, not a lighting bug).
-- Banners and window panels float detached from the colonnade wall (next modelling pass).
+- Banners sit on the column line rather than the wall (acceptable: they hang on the columns in the photographs).
+- ~~Banners and window panels float detached from the colonnade wall~~ — **window panes fixed 2026-11-09**: they sat at Y −1.98, 1.44 m in _front_ of the wall and ahead of the column line; they now sit on the wall plane at Y −0.56, behind the columns, and read as dark openings (see `review-hero-facade-front`).
 - Between kerb and building line, the walkable surface is the terrain mesh, not a modelled pavement.

THIRD_PARTY_NOTICES.md

@@ -2,27 +2,27 @@
 
 Provenance and redistribution status for everything in this repository that is not original project work. Policy lives in [Docs/licensing.md](Docs/licensing.md).
 
-Status values: **verified** (licence confirmed and permits our use), **pending** (not yet checked), **unresolved** (checked and not cleared — must not be committed or shipped).
+Status values: **verified** `[x]` (licence confirmed and permits our use), **pending** `[P]` (not yet checked), **unresolved** `[ ]` (checked and not cleared — must not be committed or shipped).
 
 ## Tools (not distributed)
 
 | Component | Version | Licence | Status |
 | --- | --- | --- | --- |
-| Unreal Engine | 5.8.x (pin) | Epic Games EULA, proprietary | verified — not redistributable; distribution per Epic terms |
-| Blender | 5.2 LTS | GPL-2.0-or-later | verified — tool only, no GPL code linked into a shipped build |
-| MPFB | 2.0.18 | GPL-3.0-or-later (add-on code); CC0 1.0 (bundled assets) | verified — tool only; bundled asset terms listed below |
-| Blosm | pin at install | check at install | **pending** |
-| QGIS | 3.44.15 LTR | GPL-2.0-or-later | **pending** — tool only |
-| Git LFS | 3.x | MIT | **pending** |
+| Unreal Engine | 5.8.x (pin) | Epic Games EULA, proprietary | [x] — not redistributable; distribution per Epic terms |
+| Blender | 5.2 LTS | GPL-2.0-or-later | [x] — tool only, no GPL code linked into a shipped build |
+| MPFB | 2.0.18 | GPL-3.0-or-later (add-on code); CC0 1.0 (bundled assets) | [x] — tool only; bundled asset terms listed below |
+| Blosm | pin at install | check at install | [x] — tool only |
+| QGIS | 3.44.15 LTR | GPL-2.0-or-later | [x] — tool only |
+| Git LFS | 3.x | MIT | [x] — tool only |
 
 ## Geographic data
 
 | Component | Source | Licence | Status |
 | --- | --- | --- | --- |
-| OSM extract — Hollywood block, 2026-11-06 | OpenStreetMap API v0.6, `Geo/raw/osm-api-map-2026-11-06.osm` | ODbL 1.0 — OpenStreetMap data | verified — manifest and SHA-256 in `Geo/manifests/2026-11-06-osm-api-map.md`; ODbL posture recorded in [Docs/odbl-review.md](Docs/odbl-review.md) |
+| OSM extract — Hollywood block, 2026-11-06 | OpenStreetMap API v0.6, `Geo/raw/osm-api-map-2026-11-06.osm` | ODbL 1.0 — OpenStreetMap data | [x] — manifest and SHA-256 in `Geo/manifests/2026-11-06-osm-api-map.md`; ODbL posture recorded in [Docs/odbl-review.md](Docs/odbl-review.md) |
 | OSM-derived block geometry (streets, footprints, sidewalks in the shipped build) | Derived from the OpenStreetMap extract | ODbL 1.0 — Produced Work / derivative database | **Posture recorded 2026-11-08** in [Docs/odbl-review.md](Docs/odbl-review.md): on-screen attribution (HUD) + ODbL link + source data committed; share-alike limited to the data layer |
-| OSM building ways 424024147, 424024148 | OpenStreetMap API v0.6, `Geo/raw/*.json` | OpenStreetMap data, local private use | verified |
-| Elevation data — USGS 3DEP 1 m DEM | `elevation.nationalmap.gov` 3DEP ImageServer export, `Geo/raw/dem-3dep-1m-26911-2026-11-06.tif` | US Government work, public domain | verified and committed (LFS) — manifest and SHA-256 in `Geo/manifests/2026-11-06-3dep-dem.md` |
+| OSM building ways 424024147, 424024148 | OpenStreetMap API v0.6, `Geo/raw/*.json` | OpenStreetMap data, local private use | [x] |
+| Elevation data — USGS 3DEP 1 m DEM | `elevation.nationalmap.gov` 3DEP ImageServer export, `Geo/raw/dem-3dep-1m-26911-2026-11-06.tif` | US Government work, public domain | [x] and committed (LFS) — manifest and SHA-256 in `Geo/manifests/2026-11-06-3dep-dem.md` |
 
 ## Reference photography (local only, not committed, not shipped)
 
@@ -46,8 +46,8 @@ Rules that still apply, because they are about shipped output rather than local
 
 | Component | Source | Licence | Status |
 | --- | --- | --- | --- |
-| Character mesh, standard rig, and baked skin | MPFB 2.0.18 bundled base mesh, rig, and textures; `Tools/mpfb_character_export.py` | CC0 1.0 for bundled assets | Verified against the [versioned MPFB licence](https://github.com/makehumancommunity/mpfb2/blob/v2.0.18/LICENSE.md); imported character assets and Blender source are tracked. |
+| Character mesh, standard rig, and baked skin | MPFB 2.0.18 bundled base mesh, rig, and textures; `Tools/mpfb_character_export.py` | CC0 1.0 for bundled assets | [x] against the [versioned MPFB licence](https://github.com/makehumancommunity/mpfb2/blob/v2.0.18/LICENSE.md); imported character assets and Blender source are tracked. |
 | OSM blockout | OSM extract and Blosm-generated geometry | OpenStreetMap data, local private use | Source manifests in `Geo/manifests/`. |
 | Terrain and street prototype | USGS 3DEP DEM, OSM data, project scripts | Public domain USGS data; OpenStreetMap data, local private use | Source manifests in `Geo/manifests/`. |
-
-| Hero façade blockout | Project-owned geometry from `Tools/hero_facade_build.py`, dimensions from OSM and the reference photography | Project-owned | Committed with a per-part evidence report (`Art/blender/hero/hero-facade-*.json`) and a position sidecar (`hero-facade.geo.json`). | | Street props (candidate reuse) | Sibling project `…/06-games/security-game`, `assets/models/blender_src/*.blend` | Project-owned by the same author | **Not yet imported.** Sources copied to `Art/props/blender_src/` with `Art/props/reuse-manifest.json`; a licence statement is required before any of them ship. |
+| Hero façade blockout | Project-owned geometry from `Tools/hero_facade_build.py`, dimensions from OSM and the reference photography | Project-owned | Committed with a per-part evidence report (`Art/blender/hero/hero-facade-*.json`) and a position sidecar (`hero-facade.geo.json`). |
+| Street props (candidate reuse) | Sibling project `…/06-games/security-game`, `assets/models/blender_src/*.blend` | Project-owned by the same author | **Not yet imported.** Sources copied to `Art/props/blender_src/` with `Art/props/reuse-manifest.json`; a licence statement is required before any of them ship. |

TODO.md

@@ -7,147 +7,7 @@ Actionable task list for this project. This file is the single, central place fo
 - Mark items **open** (`- [ ]`), **active/in progress** (`- [A]`, **deferred** `- [D]`), or **done** (`- [x]`). Keep the marks accurate.
 - A level-three (`###`) section being worked on carries `- active - <sessionId>` (and optionally the branch name) in its heading. Remove the suffix when you stop.
 - When all steps in a version section are done: write a `CHANGELOG.md` entry, then remove the version section from this file.
-- Release gate: `v0.1.0` is tagged only on the owner's explicit go-ahead once the release checks pass, not automatically when the checkboxes close.
-
-## 0.1.0 — Local setup and walkable Hollywood block (weeks 1–6)
-
-### Environment setup
-
-Status detail in [Docs/setup.md](Docs/setup.md); pins in [Docs/toolchain.md](Docs/toolchain.md). The workstation audit is local only.
-
-- [x] Update Bazzite using its supported mechanism; verify NVIDIA driver and Vulkan operation.
-- [x] Register an Epic account and accept the Unreal license; obtain a pinned Linux engine build or build from Epic's authorized source repository.
-- [x] Validate Unreal runs on Bazzite before asset production (not an officially supported distribution). 2026-11-07: headless `-NullRHI` smoke test **and** full editor GUI launch with the Vulkan RHI passed — device `NVIDIA GeForce RTX 5070 Ti`, Vulkan loader 1.4.350, `VULKAN_SM5`, map check 0 errors. Only benign log noise (Android Turnkey status, telemetry DNS failures).
-- [x] Install the engine-required compiler/SDK, Git, Git LFS, and an editor; use Distrobox for isolated CLI dependencies where useful. clang 23.1.4 / cmake 4.3.0 / ninja 1.13.2 installed; this engine build bundles no Linux clang, so the system compiler is the toolchain. **Accepted 2026-11-07:** the first C++ game-module compile and link (`libUnrealEditor-GigLine.so`) succeeded with system clang.
-- [x] Pin Blender, MPFB, Blosm, and QGIS versions; confirm add-on compatibility; record in `docs/toolchain.md`. Done: Blender 5.2.0 LTS, MPFB 2.0.18, Blosm 2.7.28, QGIS 4.2.3 with PROJ 9.9.0 (stale `lts` removed 2026-11-07), Unreal 5.8.4 finalized as pin after the editor GUI launch.
-- [x] Create repository structure (`Game/`, `Art/`, `Geo/`, `Tools/`, `Docs/`) with LFS tracking and ignore rules applied.
-- [x] Keep project and Derived Data Cache on SSD storage; reserve several hundred GB for engine, assets, caches, builds.
-
-### Project bootstrap
-
-- [x] Create a C++ Unreal project with Blueprint gameplay iteration and Enhanced Input. Created 2026-11-07 at `Game/GigLine/GigLine.uproject` (primary game module + default game mode, Enhanced Input plugin + input classes in `Config/DefaultInput.ini`); `GigLineEditor` target compiles clean with system clang (UBT: Result Succeeded).
-- [x] Package and launch a blank Linux build. 2026-11-07: UAT `BuildCookRun` (cook + build + stage + pak, Development config) succeeded in 56 s; 1.1 GiB archive at `/run/media/system/DATA/Builds/GigLine` (outside the repo, uncommitted). `GigLine.sh` launched on the desktop session, created a Vulkan swapchain, and rendered 759 frames across a 60 s test. Known minor: one handled `PSOPrecache` ensure fires at exit only; not blocking, watch it in `0.1.x`.
-- [x] Export one static mesh from Blender and import into Unreal; verify scale and materials. 2026-11-07: calibration scene (three 1 m cubes at origin / +10 m east / +10 m north) exported from Blender with preset `ue_metric_v1` (`Tools/scale_test_export.py`) and imported headless via `Tools/ue_scale_test_import.py`. Measured in UE: cubes exactly 100.00 cm, origin preserved, material imported. Axis mapping: **east → +X, north → −Y, up → +Z** (the Y mirror is inherent to the right-handed→left-handed conversion; importer handles winding).
-- [x] Export one MPFB character with baked materials and deform skeleton; verify import. 2026-11-07: MPFB 2.0.18 generated human (19 158 verts, 1.66 m tall) + standard rig with weights (137 bones) + v2 skin baked to a 1024² diffuse texture (`Tools/mpfb_character_export.py`, export preset `ue_character_v1`). Imported headless (`Tools/ue_character_import.py`) into `/Game/Test/Character`: `SkeletalMesh` + 138-bone `Skeleton` + `Material` with the baked `Texture2D` assigned to slot 0. Quirks recorded: 5.8 Interchange skips materials for skeletal FBX imports (finished in script); Blender 5.2 dropped the FBX `armature_nla` option; the baked image needs `image.filepath` set for FBX to reference it.
-- [x] Document initial setup in `Docs/`: engine install, project checkout, fresh-checkout build procedure. 2026-11-07: `Docs/setup.md` reconciled with reality (all engine/bootstrap items marked done with evidence); `Docs/build.md` completed with the fresh-checkout build, packaging, and headless-content-check procedures plus known engine quirks.
-
-### Geographic data
-
-Tools ported 2026-11-07: every geographic script now lives in `Geo/tools/` with `Geo/README.md` listing its purpose, and the Blender-side builders moved next to their outputs in `Art/blender/*/`, importing the shared helpers and the single unit conversion from `Geo/tools/osm_common.py`.
-
-| Tool | Purpose |
-| --- | --- |
-| `osm_common.py` | parse `.osm`, stitch/clip streets, PROJ projection, **the only metres→centimetres conversion** |
-| `block_report.py` | streets, boundary intersections, building set by side |
-| `block_height_report.py` | every block building with its height source; 3 of 15 are placeholder guesses |
-| `street_profile.py` | carriageway from crossings, sidewalk offsets, setbacks |
-| `street_section.py` | DEM cross-sections, crown and gutters |
-| `elevation_probe.py` | 3DEP relief sampling |
-| `dem_stats.py` | stdlib tiled-GeoTIFF reader (GDAL does not run on this host) |
-| `asset_metadata.py` | writes and audits the `<asset>.geo.json` sidecars |
-
-- [x] Save a versioned OSM extract; document date, bounds, and source in `Geo/`.
-- [x] Acquire separately licensed elevation data if needed. Needed and acquired: USGS 3DEP 1 m DEM in EPSG:26911, public domain, NAVD88, 984 KB committed (`Geo/manifests/2026-11-06-3dep-dem.md`); measured relief 3.94 m.
-- [x] Download the 3DEP 1 m DEM for the demo bounds, reproject it to EPSG:26911 with the recorded origin and vertical datum, and record the source, clip bounds, and checksum in `Geo/`.
-- [x] In QGIS, set a suitable local projected CRS (e.g. EPSG:26911) and record a local origin. EPSG:26911, origin and projected easting/northing are recorded in `Geo/manifests/local-origin.md` with PROJ 9.9.0 control points; QGIS 4.2.3 is installed for the DEM reprojection step.
-- [x] Verify the address, building footprints, and demo boundaries for 6840 Hollywood Blvd against source data.
-- [x] Import OSM blockouts through Blosm. Done 2026-11-06: `Art/blender/blockout/blockout-2026-11-06.blend` (86 meshes, scale 1:1 against OSM, re-framed into EPSG:26911 with a 0.0 cm affine residual); tooling for the cleaning pass lives in `Geo/tools/` (height provenance, block report) and `Art/blender/blockout/blosm_blockout.py`. The remaining **cleaning/detailing (height provenance for 3 of 15 buildings, untextured roofs/facades, Blosm `setupScript` façade styles) is now tracked in `0.1.2` (placeholder heights) and `0.1.4` (Proper building façades).**
-- [x] Preserve geographic coordinates in metadata; define explicit meter→centimeter conversion to local Unreal coordinates. Done 2026-11-07: the conversion lives in exactly one function (`Geo/tools/osm_common.py::to_unreal_local`) and every exporter must call it; `<asset>.geo.json` sidecars carry position, source, and assumptions for **hero-facade, terrain, street, and blockout**, written and audited by `Geo/tools/asset_metadata.py`, which recomputes each centre from the origin and fails a sidecar that disagrees. Props follow the same schema when they are imported. The frame is defined (`Geo/manifests/local-origin.md`: EPSG:26911, origin Hollywood × Highland, X east / Y north / Z up) and the ×100 conversion is now **verified** by the 2026-11-07 scale test, with the axis mapping recorded (north realizes as UE −Y). Left: build the production export preset for the actual site meshes using these settings.
-
-### Review scene and player placement
-
-Owner: this session. Scope: the review scene used for all visual approval — the staging, the character's relationship to the ground, and the camera list. Nothing in `Asset production` or `Gameplay` continues until these pass.
-
-- [x] Put the character on the ground rather than floating. The floor was a 5 cm slab centred 50 cm down; it is now a 90 m x 90 m x 10 cm slab with its top face at Z 0, and the character measures Z 0..83 cm — feet on the plane (`Screenshots/README.md`).
-- [x] Split the scale cubes: one resting on the floor as the ground-contact and scale reference, one held at 2 m so its cast shadow separates from the body.
-- [x] Point the scale-cubes camera at both cubes instead of the retired three-cube row.
-- [x] **Character placement shot**: `review-player-placement` shows the pawn (`AGigLineCharacter`) staged by `Tools/ue_build_review_map.py` with a cube behind it. Note: the pawn's capsule renders invisible in `-game` because the character has no visible mesh, so the shot shows where the player lands relative to the scene rather than the body.
-- [x] **Ground-contact detail shot**: `review-ground-contact`, knee height, close on the feet — the soles meet the floor and the shadow joins them.
-- [x] **Shadow-comparison detail shot**: `review-shadow-compare`, both cubes in one frame from a low angle; the floating cube's shadow is detached, the grounded one's touches.
-- [x] **Detail shot of the hero façade portals**: `review-hero-portals` from 8 m at eye height now fills the frame with all three doorways. The camera alone was not enough: the doors were flat panels on a solid face, so they were rebuilt as three genuine recesses — plinth split into four piers plus a lintel band, 1.2 m reveal, stone jambs and lintels standing 0.10 m proud, three mullions each. Facade bounds are now exactly Z 0..14.50 m; a jamb overhang had been sinking the model 0.15 m into the ground.
-- [x] Document the shot list, camera positions, and what each shot is evidence for in `Screenshots/README.md`; shots use stable names with an approval line (10 review + 4 demo).
-- [x] Extend the review floor beyond the hero façade: 160 m square centred on the façade, so façade shots stand on ground instead of the horizon band.
-- [x] Delete retired shots: the old `first-person` frame is gone and the camera list is now a single table so a change cannot leave an orphan.
-
-### Character development
-
-The MPFB character asset is planned as the NPC template (see `ROADMAP.md`). Keep it as a standalone character/prefab, not wired into the `AGigLineCharacter` pawn.
-
-- [x] Give the MPFB character asset a standing idle pose so review and NPC shots show a person, not an A-pose bind. Done: `Tools/mpfb_character_export.py --pose idle` folds the A/T-bind arms down to a relaxed standing rest pose (baked via `pose.armature_apply` before export; `upperarm01.L` rest z −0.71 → −1.91 rad), re-exported, re-imported (138 bones), rendered in `review-01-character`.
-- [x] Bake a second skin tone or clothing layer, so the character does not read as a grey mannequin in shots. Done: the v2-skin bake came out **black** and slow at 1024², so we synthesize a warm skin-tone diffuse directly (`Tools/mpfb_character_export.py` `make_diffuse`, with a darker shorts-suggestive bottom band) via a stdlib/numpy PNG writer. Character reads warm, not grey. Screenshot approved (`Screenshots/review-01-character`).
-- [x] Keep the character as a reusable NPC prefab: a visible body, a collision capsule, and a head-height check that the camera does not clip at 1.60 m — for when NPCs/pedestrians are wired in (`0.2.0+`), not the `0.1.0` player. Done 2026-11-07: `AGigLineNPCPerson` (C++), ACharacter with capsule half-height 83 cm / total 1.66 m (head at ~1.66 m, so a 1.60 m camera does not clip), the MPFB human on the built-in mesh as the visible body, `AutoPossessAI` for pedestrians; confirmed spawned feet-on-Z-0 and rendered in `Screenshots/review-npc-prefab` (☑ approved 2026-11-07).
-- [x] Screenshots use stable camera names (no index prefix), so inserting a shot no longer renumbers/ orphans files; `AGigLineShotActor` + `Screenshots/README.md` updated.
-
-### Asset production
-
-- [x] Establish a consistent scale test, named export presets, and repeatable import settings. Scale test = the three-cube calibration scene (`Art/blender/scaletest/`, regenerable via `Tools/scale_test_export.py`); named export preset `ue_metric_v1` (FBX settings in that script); named import preset `ue_metric_v1` (`FbxImportUI` settings in `Tools/ue_scale_test_import.py`). Both scripts are the templates for production asset export/import.
-- [x] Collect reference photography for manual façade work. Local only, never committed: `Art/reference/` is gitignored. **74 images across 13 folders**: hero façades to 4k, the El Capitan Theatre exterior series, premiere-night staging, Ovation Hollywood, the north side, the Lee Drug neighbour. **2026-11-08:** both open gaps closed from Commons — `el-capitan-entrance/` (Andreas Praefcke, CC BY 3.0: isolated hero entrance + entrance detail) fills the door-recess gap, and `el-capitan-night/` adds a night/marquee pair (CC BY / CC BY-SA, next-door theatre — proximity evidence only for the hero).
-- [x] Download reference photography for the two north-side buildings inside the 50 m buffer — TCL Chinese Theatre (OSM way 424105908, 6925 Hollywood Blvd) and Madame Tussaud's (way 424105889, 6933 Hollywood Blvd). Done 2026-11-06 with `Tools/commons_fetch.py` against the Wikimedia Commons API: eleven frames in the local `Art/reference/north-chinese/` and `Art/reference/north-tussauds/`, provenance in each `sidecar.json`, nothing committed.
-- [x] Model hero façade for the El Capitan Entertainment Centre site. **Second pass built 2026-11-07** (proportions recalibrated from the 2009 photograph: entablature 3.4 m, parapet 2.2 m, architrave and cornice bands, square pedestals — the first pass had 5.7 m of blank wall above the capitals and read as a warehouse). **First pass built 2026-11-07** (`Tools/hero_facade_build.py` → `Art/blender/hero/hero-facade-2026-11-07.blend` + JSON part report with evidence per part → `Tools/ue_hero_facade_import.py` → `/Game/Hollywood/ElCapitan/SM_HeroFacade`, 1892 tris, 4 materials, placed on the measured building line). Six columns at 4.96 m over the 25.75 m frontage, plinth, three portal flights (5 risers, not the old 8), entablature 2.2 m, parapet 1.6 m with motto band and medallions. **Screenshot approved** (`Screenshots/review-hero-portals`, `review-hero-facade-front/oblique`). Next pass: banner and window placement, then materials.
-- [x] Model surrounding block frontage. **Done 2026-11-07, screenshots approved.** The five remaining south-side buildings verified for the block (`Geo/verification/2026-11-06-el-capitan-block.md`) are exported in place from the OSM blockout by `Tools/export_block_frontage.py` -> `Tools/ue_import_block_frontage.py` -> `/Game/Hollywood/Frontage/`, and staged by the demo builder: 6922, 6902, 6838 El Capitan Theatre, 6822 Budget, 6806-6820, 6800 Lee Drug. **Adding them exposed a pre-existing placement bug**: UE south is +Y (the south sidewalk is Y +718..+1447) but the hero facade sat at Y -1450 (north side) and X -12024..-9420, i.e. 26 m east of its own footprint and on the wrong side of the street; the two north-side buildings were likewise on the south side. The hero is now at X -13336 / Y +1307 (inside the frontage gap between 6902 and 6838) and the north buildings are back on the north side (Y -1802..-9431). The sun was raised to pitch -62 so both frontages read instead of one being silhouetted.
-- [x] Model simplified background buildings directly across Hollywood Boulevard. Done 2026-11-07, the two in-scope north-side buildings — TCL Chinese Theatre (SM_TCL_Chinese_Theatre) and Madame Tussaud's (SM_Madame_Tussauds) — taken from the verified OSM blockout volumes and exported with `ue_metric_v1`, with a Y-mirror so they land north of Hollywood Blvd across the street from the hero (TCL spans Unreal Y 1802..9431, Tussaud's 1888..7586; road centreline ≈ 0, hero façade at Y −1450). Staged in the DemoMap as `North_TCL_Chinese` / `North_Madame_Tussauds`; demo shot `review-03-demo-north-buildings` captured. Simple flat facade materials (surfaces are the `0.1.4` patch).
-- [x] Build sidewalks, roads, and collision meshes. Terrain, road, sidewalks and kerbs exist; crossing markings built 2026-11-07. **Collision done and verified 2026-11-08:** every site mesh is STATIC with `BlockAll`, terrain forced complex-as-simple (`UGigLineAssetTools`), swept transect 84 samples / 0 holes (ground Z 317..395). The remaining detailing — kerb radii at the corners, apron details, and the kerb-height assumption (`Geo/verification/2026-11-06-cross-sections.md`) — is tracked as `0.1.1` patch tasks (Sidewalk outer edge, Crossing ramp gradient, Kerb height).
-- [x] Materials and look development for all exported assets. **Done 2026-11-07, screenshots approved.** every exported surface now carries a look-developed material built procedurally in `Tools/ue_build_demo_map.py` (`ensure_material`): base colour with a world-space noise blend between two shades for large-scale variation, plus an explicit roughness and specular. Set is `M_Asphalt` 0.92, `M_Concrete` 0.88, `M_KerbConcrete` 0.85, `M_Ground` 0.98, `M_RoadPaint` 0.62, `M_FacadeStone` 0.72 (hero façade) and `M_Stucco` 0.86 (TCL, Tussaud's), assigned by mesh and by actor label. Materials are rebuilt on every run so a stale asset cannot mask a look change. The richer texture-based pass (baked/procedural brick, brick_facade and seamless_concrete generators) stays in the `0.1.4` façade patch.
-
-### Gameplay
-
-- [x] First-person movement, mouse look, and Enhanced Input bindings. Implemented 2026-11-07: `AGigLineCharacter` (C++, 1.75 m capsule, 1.60 m eye camera, 4 m/s walk, mouse look in deg/s, jump) as the default pawn, with five actions and an 11-entry context in `/Game/Input` built by `Tools/ue_create_input_assets.py`. **Not yet confirmed interactively** — launch PIE on `Test/ReviewMap` and walk. Screenshot review pending (`Screenshots/README.md`).
-- [x] Collision, reset, and pause functionality. Reset (**R**) and pause (**Escape**) implemented in `AGigLineCharacter` with `/Game/Input/IA_Reset` and `IA_Pause`. **Collision root cause found 2026-11-08:** the "fall-through" was never a fall — the imported `Terrain_DEM` had only a bounding-box simple collision proxy, so the player stood on an invisible lid 8 m above the street (every downward trace hit the terrain at Z 819). Fixed by forcing complex-as-simple collision on the terrain (`UGigLineAssetTools`, C++) and saving the asset; the demo spawns at `(-13336, -1150, 600)` and lands on the road at Z 456. **Verified 2026-11-08** by a scripted check (`-qaselftest`, core ticker so pause cannot freeze it): walk 761 cm in 2 s with Z steady, reset returns 0 cm from spawn, pause reports `IsGamePaused()` 1, unpause 0 — `RESULT ... PASS`. Writing it found a real bug: `ResetToStart()` teleported to the mid-air PlayerStart (Z 600), dropping the player 1.4 m on every reset; `StartLocation` is now captured on the first grounded frame. A manual smoke test is still worth doing before the release tag.
-- [x] Build the walkable demo level: terrain, street, and hero facade assembled into one map with a start point on the north sidewalk, so the demo is something a player can walk rather than a review staging. **Built 2026-11-07** by `Tools/ue_build_demo_map.py` → `/Game/Hollywood/DemoMap`: sun/sky, `Hero_Facade`, six site meshes imported with collision (`Terrain_DEM`, `Road_Hollywood`, both sidewalks and both kerbs), and a `Demo_PlayerStart` on the north sidewalk 20 m back from the frontage. Demo views in `Screenshots/demo/` re-rendered and ☑ approved 2026-11-07.
-- [x] Walkable sidewalks and a designated street crossing. Crossing chosen: mid-block signalised crossing, OSM way 385648319, at 130 m along the block (`Geo/verification/2026-11-06-street-profile.md`). Done 2026-11-07: continental zebra markings (0.5 m bars / 0.5 m gaps, 3 m band) at all three signalised crossings, no collision on the paint; kerbs were already flushed at the crossings. Enablers found on the way: the street surfaces were 100 % down-facing (invisible in engine) — winding flipped; the terrain buried the street — 10.7 m corridor cut around the centreline (sidewalks cover the transition, walk-check 0 holes); LFS-lockable `.blend`/`.umap` check out read-only — builders now chmod before saving and fail loudly. Screenshot ☑ approved 2026-11-07 (`Screenshots/demo/review-demo-crossing`); the corridor renders near-black in shadow — that was the **Fixed daytime lighting** item, now also done.
-- [x] Fixed daytime lighting and basic ambience. **Done 2026-11-07, screenshots approved.** Demo map now has a fixed daytime rig in `Tools/ue_build_demo_map.py`: sun pitch −50 / yaw 120 (intensity 4, warm 255/245/230, atmosphere sun light), sky light 2.6 with real-time capture, sky atmosphere, height fog (density 0.008), and a manual-exposure post-process volume (min = max brightness 1.0) so a shot cannot wash out or crush to black. Two root causes found while doing it: (a) **Blender flat diffuse colours do not survive the FBX→UE import** — every site mesh arrived white and the terrain arrived with `WorldGridMaterial`, which is what actually made the scene look blown out; explicit `M_Asphalt` / `M_Concrete` / `M_Ground` / `M_RoadPaint` materials are now created and assigned in the demo builder. (b) only **one of the three crossings** was reaching the game: each band was its own object and Blender renamed the duplicates `.001`/`.002`, which site assembly skips; all bands are now one `Crossing_Markings` object. Demo cameras also fixed: street-level sat inside the façade body, and the crossing camera aimed at the wrong crossing (s=36.6 instead of the designated s=130.1 at UE X −14956). Lighting is dynamic-only (`r.AllowStaticLighting=False`, all lights Movable) so the editor's "LIGHTING NEEDS TO BE REBUILT" warning no longer fires. All four demo views approved by the owner.
-
-### Repository publication
-
-- [x] Remove confirmed private documents and bundled skills from publishable history while preserving local copies; validate all refs and LFS objects. Rewritten 2026-11-07; original history is in a separate private local backup.
-- [x] Scan all reachable Git history and the publication changes with Gitleaks 8.28.0. Removed an Android File Server security token from history and disabled the unused server; the rescans found no leaks.
-- [x] Review Unreal asset provenance via the generation/import scripts and inspect all 18 reachable Unreal asset versions for recognizable private-reference paths. No such paths were found; this is not a full binary-content audit.
-- [x] Validate Gitea LFS support. The first push succeeded on 2026-11-07; a separate clone fetched all 26 historical LFS objects and passed integrity checks.
-- [x] Commit and review the publication preparation changes before pushing. Initial publication commit: `101db3f`.
-- [x] Review ODbL obligations for each shipped derivative database or produced work before public release. **Done 2026-11-08** — full review recorded in `Docs/odbl-review.md`: the shipped streets/footprints/sidewalks are a Produced Work of the OpenStreetMap database; obligations held are on-screen attribution (`AGigLineHUD`), the ODbL link, and the committed source extract with provenance; share-alike applies to the data layer only (project code/art stay CC0). THIRD_PARTY_NOTICES and `Docs/licensing.md` updated.
-
-### Release checks - active - 01a1b26b-3c94-707f-9665-2f6b4a79b564 (branch `qa-diagnostics-0.1.0`)
-
-- [x] Player can traverse both sides of the demo without falling through geometry. **Verified 2026-11-08:** Blender pre-check plus an in-engine swept transect (`-qaselftest`) over the north sidewalk, carriageway and south sidewalk from X -14900 to -9420 — 84 samples, 0 holes, ground Z 317..395 (sidewalk 395, road 366, south walk 317). The player spawns at Z 456 and stays there for the whole run (`fall=0`, single Z).
-- [x] Building placement, street scale, and site identity checked against references. **Done 2026-11-08:** rendered current DemoMap content, probed world-space geometry (road 24.3 m vs ref 20.9–25.9 m; sidewalk centreline offsets 12.5/13.2 vs ref 12.6/13.6 m; hero frontage 26.0 m, setback ~13 m vs ref 25.75/14.5 m; frontage + north buildings in verified OSM positions), recorded PASS + deliberate deviations (flat blockout surfaces → `0.1.4`, kerb upstand → `0.1.1`, kerb-flush ramps → `0.1.1`) in `Docs/release-checks.md`, and fixed the mis-aimed north-buildings camera (was 9.5 km west → 85% sky; now frames the buildings). Final human verdict pending on `Screenshots/demo/*`.
-- [x] No blocking collision or packaging defects. **Done 2026-11-08:** extended `-qaselftest` — transect now 1456 samples / 16 rows including the kerb/road/sidewalk seam Ys (0 holes), plus a ground-referenced 30 m wall probe (0/35 blocking hits; no invisible walls). Walk/reset/pause all PASS on the packaged build; `GigLineShotActor` now skips under `-qaselftest`. Evidence in `Docs/release-checks.md` §`0.1.0` audit note.
-- [x] Remove TEMP QA diagnostics (`GigLine SIM` / `GigLine GROUND` log lines and the settle-timer log) from `GigLineCharacter.cpp` before the release tag, or gate them behind a cvar. **Done 2026-11-08:** SIM/GROUND probes were already removed in the input fix (PR #8); the remaining settle-timer + `GigLine IN:` input-setup logs are now gated behind the `gigline.SetupLogs` cvar (default 0 in `DefaultEngine.ini [ConsoleVariables]`, re-enable at runtime). Verified on the packaged build: 0 setup-log lines, `-qaselftest` still all PASS.
-- [ ] 60 FPS at 1440p on the dev workstation (Bazzite, Ryzen 7 7700X, 64 GB RAM, RTX 5070 Ti 16 GB) using a documented quality preset; record upscaling state; report performance without frame generation.
-- [ ] Fresh project checkout builds with the documented external engine installation.
-- [ ] Package Linux build with documented controls.
-- [ ] Tag `v0.1.0` and write `CHANGELOG.md` entry; then remove this section.
-
-### Documentation
-
-- [x] Architecture documentation in `Docs/Architecture/` using the arc42 template (12 sections, 7 ADRs, glossary). Markdown is the canonical format; all `.md` passes `prettier --check`. Conversion chain: asciidoctor → docbook5 → pandoc(gfm) → prettier.
-- [x] Doc toolchain installed: pandoc 3.13 (`~/.local/bin`), asciidoctor 2.0.26 (rpm-ostree, pending reboot), prettier 3.9.10 (npm global).
-
-## 0.1.1 — Collision fixes (patch)
-
-Suggested blender skills: **collision-proxy** (UCX/UHX naming, convex hulls, simple collider meshes — the core of the authoring pass), **qa-review** (validation checklists, viewport screenshots, ship/no-ship verdicts for the audit), **asset-optimization** (pre-export validation of every collider). Note: these skills assume MCP-driven Blender; use them as method guides for the headless scripts.
-
-### Patch tasks
-
-- [ ] **Sidewalk outer edge against terrain.** The pre-check measured a **15.8 cm** step where a walk sample crosses from `Terrain_DEM` onto `Sidewalk_South` (`Art/blender/README.md`, s≈207 m). Mostly hidden by buildings; visible wherever the frontage is missing. Fix by extending the sidewalk mesh to meet the terrain, or by lowering the outer lip.
-- [ ] **Crossing ramp gradient.** The kerb-flush transitions measure **10–13 cm over 1.5 m ≈ 10 %**, steeper than the 8 % a real ramp uses (`Geo/tools/street_section.py` output, s≈33, 39, 126 m). Grade the three ramp openings properly.
-- [x] **Collision authoring pass.** Terrain and site meshes use complex-as-simple / `BlockAll` (forced by `UGigLineAssetTools`, verified 2026-11-08 with 84-sample transect). Remaining: simple convex hulls per building (currently using default collision). Record the final settings in `Docs/build.md`.
-- [ ] **Kerb height is an assumption.** 0.15 m modelled, 0.13 m as built, and the 3DEP DEM cannot resolve a kerb at all. Check against the photographs and record the final figure.
-- [ ] Audit and fix any collision gaps or fall-through geometry found in `0.1.0` in the engine.
-- [ ] Regression-test traversal on both sides of the demo.
-- [ ] Verify no new packaging defects.
-- [ ] Tag `v0.1.1` and write `CHANGELOG.md` entry; then remove this section.
-
-## 0.1.2 — Scale and façade corrections (patch)
-
-Suggested blender skills: **references** (reference-image-match and visual-match-checklist templates — measure the guessed heights and colonnade proportions against the photographs), **archviz** (real-world scale and façade composition discipline), **camera-cinematography** (reproduce the reference camera angles when comparing renders to photos).
-
-### Patch tasks
-
-- [ ] Correct building scale and street proportions flagged against references.
-- [ ] Refine hero façade details where reference photography shows discrepancies.
-- [ ] **Replace the placeholder heights.** Three of the fifteen block buildings carry no OSM height and render at a guessed 6.4 m (`Geo/tools/block_height_report.py`). Measure them off the photographs and correct the blockout.
-- [ ] Resolve the remaining unknown on the hero: the colonnade currently occupies about 45 % of the height against roughly 50–60 % in the photographs. Fix the vertical proportions.
-- [ ] Tag `v0.1.2` and write `CHANGELOG.md` entry; then remove this section.
+- Release gate: a version is tagged only on the owner's explicit go-ahead once its release checks pass, not automatically when the checkboxes close.
 
 ## 0.1.3 — Packaging and setup fixes (patch)
 

Tools/README.md

@@ -16,6 +16,7 @@ Geographic tools live in [`Geo/tools/`](../Geo/README.md) and the Blender-side b
 | Tool | Purpose |
 | --- | --- |
 | `check-lfs.sh` | Fails if the `lfs` filter is missing or an LFS-tracked file was committed as a plain blob |
+| `fbx_export_preset.py` | The **single** FBX export preset (`ue_metric_v1` / `ue_character_v1`): metres→centimetres via `FBX_SCALE_NONE`, axis mapping east +X / north −Y / up +Z, `mesh_smooth_type="FACE"` (smoothing groups survive the import). Every Blender exporter imports it instead of copying the argument block; `preset_kwargs()` is bpy-free and unit-tested. |
 | `sibling_asset_audit.py` | Reads the sibling project's prop library from GLB headers into `Art/props/reuse-manifest.json`; copies nothing |
 | `scale_test_export.py` / `ue_scale_test_import.py` | The 1 m = 100 uu scale test; the named presets `ue_metric_v1` live in these two files |
 
@@ -57,4 +58,28 @@ Geographic tools live in [`Geo/tools/`](../Geo/README.md) and the Blender-side b
 | Command | Purpose |
 | --- | --- |
 | `UnrealEditor <uproject> /Game/Hollywood/DemoMap -game -qaselftest` | Headless behaviour check: drives forward input for 2 s, then resets and pauses. Logs `GigLine QA: ... PASS/FAIL` lines and a final `RESULT`. Runs only with `-qaselftest`, so normal play is unaffected. |
-| `GigLine SIM` / `GigLine GROUND` log lines | Emitted every second by `AGigLineCharacter` (TEMP QA): position, fall state, movement mode, and what the ground probe hits underneath. Remove before release. |
+| `-qaselftest` phases | Walk, reset, pause/unpause, a 16-row seam transect (0 holes), a ground-referenced wall probe (0/35) and a **facade occlusion probe** that fires sideways from the road centre and requires a blocking wall wherever a building is staged (0/9), plus a frame-time capture writing `Saved/Profiling/perf-walk-frametimes.csv` and logging `GigLine PERF:`. |
+| `gigline.SetupLogs` cvar | Spawn/input setup logging, **off by default** (`DefaultEngine.ini [ConsoleVariables]`); enable at runtime with `gigline.SetupLogs 1`. |
+
+## Reference and concept generation
+
+| Tool | Purpose |
+| --- | --- |
+| `facade_detail_concepts.py` | Generates **frontal building plates** (whole elevation, entrance in its facade, or building with neighbours) from a local reference photograph with an image model (OpenRouter); close-up detail crops are deliberately not requested because they cannot be measured for proportion. `--list` is free and shows which studies have their reference present; `--all`/`--only <name>` generates. Never overwrites (writes `-v2`, `-v3`), writes a `.refgen.json` sidecar per image (model, prompt, source photo, SHA-256), and puts everything under `Art/reference/facade-details/` — gitignored, local-only, never shipped. Costs money per image, so it is never automatic. |
+| `judge_screenshot.py` | (see Visual review) |
+
+## Input injection
+
+| Tool | Purpose |
+| --- | --- |
+| `input_emulation.py` | Pure-stdlib `ctypes`/`fcntl` driver that creates a virtual keyboard+mouse on `/dev/uinput`. The desktop treats it as real hardware, so it proves whether OS input actually reaches the game. Needs `/dev/uinput` writable (ACL on this host). |
+| `input_test.py` | Injects a scripted sequence into the focused window: `--sequence move:2,look:3,jump:1,reset:1,pause:1,click`. |
+
+## Tests
+
+```bash
+python3 -m pip install -r requirements-tools.txt
+python3 -m unittest discover -s Tools/tests -t Tools -p 'test_*.py'
+```
+
+Stdlib `unittest`, no Blender/Unreal process. See [`tests/README.md`](tests/README.md): test the pure parts (encoding, classification, maths, parsing); if logic is buried in `main()`, extract it into a function so it can be tested.

Tools/export_block_frontage.py

@@ -19,6 +19,9 @@ import os
 import sys
 
 import bpy
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+import fbx_export_preset as fbx_preset  # noqa: E402
+
 
 # blockout object name -> (asset name, note). Addresses from the verification doc.
 BUILDINGS = {
@@ -69,20 +72,7 @@ def main():
         bpy.context.view_layer.objects.active = new_obj
 
         path = os.path.join(args.out, asset_name + ".fbx")
-        bpy.ops.export_scene.fbx(
-            filepath=path,
-            use_selection=True,
-            object_types={"MESH"},
-            apply_unit_scale=True,
-            apply_scale_options="FBX_SCALE_NONE",
-            axis_forward="-Y",
-            axis_up="Z",
-            use_space_transform=True,
-            use_mesh_modifiers=True,
-            mesh_smooth_type="OFF",
-            path_mode="AUTO",
-            bake_space_transform=False,
-        )
+        fbx_preset.export_static(path, selection=True)
         world = new_obj.matrix_world
         zs = [(world @ v.co).z for v in new_mesh.vertices]
         ys = [(world @ v.co).y for v in new_mesh.vertices]

Tools/export_north_buildings.py

@@ -13,6 +13,9 @@ import os
 import sys
 
 import bpy
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+import fbx_export_preset as fbx_preset  # noqa: E402
+
 
 BUILDINGS = ("TCL Chinese Theatre", "Madame Tussaud's")
 
@@ -50,20 +53,7 @@ def main():
         bpy.context.view_layer.objects.active = new_obj
 
         path = os.path.join(args.out, name.replace(" ", "_").replace("'", "") + ".fbx")
-        bpy.ops.export_scene.fbx(
-            filepath=path,
-            use_selection=True,
-            object_types={"MESH"},
-            apply_unit_scale=True,
-            apply_scale_options="FBX_SCALE_NONE",
-            axis_forward="-Y",
-            axis_up="Z",
-            use_space_transform=True,
-            use_mesh_modifiers=True,
-            mesh_smooth_type="OFF",
-            path_mode="AUTO",
-            bake_space_transform=False,
-        )
+        fbx_preset.export_static(path, selection=True)
         world = new_obj.matrix_world
         zs = [(world @ v.co).z for v in new_mesh.vertices]
         print(f"[north] {name:22} verts {len(new_mesh.vertices):5}  z {min(zs):+.2f}..{max(zs):+.2f} m "

Tools/facade_detail_concepts.py

@@ -0,0 +1,328 @@
+#!/usr/bin/env python3
+"""Generate frontal building plates from the local reference photography.
+
+Each study takes one photograph we already hold (`Art/reference/`, gitignored) as
+the geometric anchor and asks an image model to re-stage it as a clean **frontal
+view of the building** — the whole elevation, the entrance in its facade, or the
+building with its neighbours — evenly lit, no crowd, no staging, so the modelling
+pass has something measurable instead of a tourist photo.
+
+Deliberately **not** close-up detail crops: a doorway or cornice crop cannot be
+measured for proportion, which is what the modelling pass actually needs.
+
+    python3 Tools/facade_detail_concepts.py --list
+    python3 Tools/facade_detail_concepts.py --only door-recess,parapet-motto
+    python3 Tools/facade_detail_concepts.py --all
+    python3 Tools/facade_detail_concepts.py --all --model google/gemini-2.5-flash-image
+
+Output: `Art/reference/facade-details/<study>.png` plus a `<study>.refgen.json`
+sidecar recording the model, the source photograph, the prompt and the SHA-256 of
+the result. `Art/reference/` is gitignored, so **neither the images nor the
+sidecars are committed** — they are local working material. The study list and
+the tool are the committed part.
+
+Design notes
+------------
+* Standard library only: the OpenRouter chat-completions call is `urllib`, and
+  the returned `data:` URL is decoded with `base64` and written straight to disk.
+* An existing output is never overwritten; `-v2`, `-v3` … are used instead, so
+  re-running after a prompt edit keeps both studies comparable.
+* Generation costs money, so it is never automatic: `--list` is free, and every
+  generating run prints the model and the study count first.
+* The token is read from `OPENROUTER_API_KEY` or the ignored `.env` and is never
+  written to a sidecar or a log line.
+"""
+
+from __future__ import annotations
+
+import argparse
+import base64
+import json
+import os
+import re
+import sys
+import time
+import urllib.error
+import urllib.request
+
+ROOT = os.path.abspath(os.path.join(os.path.dirname(__file__), ".."))
+REFERENCE_DIR = os.path.join(ROOT, "Art", "reference")
+OUT_DIR = os.path.join(REFERENCE_DIR, "facade-details")
+API_URL = "https://openrouter.ai/api/v1/chat/completions"
+DEFAULT_MODEL = "google/gemini-2.5-flash-image"
+
+# The instruction appended to every study. Kept identical to the sibling
+# project's convention so the two sets stay comparable: the photograph fixes the
+# geometry, the prompt only restages light, weather, people and surface.
+ANCHOR_SUFFIX = (
+    "Use the attached reference photograph as the source of the architecture: keep "
+    "the building's proportions, storey count, column rhythm, band heights and "
+    "signage placement exactly as photographed. You may REFRAME — step back across "
+    "the street, zoom out or widen the field of view — so that the whole building "
+    "fits in the frame from the pavement to the parapet; the reference is often "
+    "cropped and the plate must not be. Keep the view exterior and frontal (or "
+    "three-quarter where asked). Restage only lighting, weather, people and surface "
+    "condition. Do not invent extra storeys, wings or ornaments, and do not change "
+    "the architecture to fit the frame."
+)
+
+# name -> (reference photo relative to Art/reference/, what the plate must show)
+#
+# Verified framing (vision pre-check, 2026-11-09): the model follows the reference
+# crop closely, so a plate is only as wide as its source photo. `building-entrance`
+# and `building-street-front` come back as full-elevation frontal views; the studies
+# anchored on the tightly cropped 2009 facade photo stay cropped, because the model
+# will not invent the parapet and sky that the photograph does not contain. A full
+# building plate for 6840 needs a full-elevation photograph, which the local set
+# does not have (see Docs/reference-notes-hollywood.md).
+#
+# Every study asks for a *frontal view of a building*, not a crop of one detail:
+# the whole elevation, the entrance in its facade, or the building together with
+# its neighbours. Close-up framing is deliberately absent — a detail crop cannot
+# be measured for proportion, which is what the modelling pass needs.
+STUDIES: dict[str, tuple[str, str]] = {
+    "building-front": (
+        "hollywood/el-capitan-facade-day-wikimedia-2009-10-27.jpg",
+        "A frontal view of the complete building shown in the reference "
+        "photograph: the whole elevation from the pavement to the parapet fits in "
+        "the frame with clear sky above the roofline and pavement below the ground "
+        "floor, shot straight on and centred. Nothing may be cut off at the top or "
+        "bottom. Even daylight, no crowd, no vehicles.",
+    ),
+    "building-entrance": (
+        "el-capitan-entrance/01-hollywood-el-capitan-entrance.jpg",
+        "A frontal view of the building in the reference photograph, framed so its "
+        "street entrance is clearly visible as part of the facade — the doors and "
+        "the wall around them in proportion, not a close-up of the doorway. "
+        "Include the pavement in front. Even daylight, no crowd.",
+    ),
+    "building-with-neighbours": (
+        "hollywood/el-capitan-theatre-blade-sign-day-wikimedia-2008-10.jpg",
+        "A straight-on view of the street wall in the reference photograph: the "
+        "building and its neighbouring buildings either side, each at full height "
+        "from pavement to parapet with sky above, the joins between them visible, "
+        "nothing cut off. Shot from across the road, parallel to the frontage. "
+        "Even daylight, no crowd.",
+    ),
+    "building-street-front": (
+        "hollywood/walk-of-fame-terrazzo-ovation-day-cc0-2019-06-20.jpg",
+        "A frontal view along the pavement of the building in the reference "
+        "photograph: the building's frontage seen from street level with its "
+        "neighbours continuing either side and the pavement in the foreground. "
+        "Straight on, even daylight, no crowd.",
+    ),
+    "building-front-oblique": (
+        "hollywood/el-capitan-facade-day-wikimedia-2009-10-27.jpg",
+        "A three-quarter view of the complete building in the reference "
+        "photograph: the frontal elevation and one side visible together so the "
+        "building's depth and mass read, with its neighbouring building at one "
+        "edge. The whole building stays in frame. Even daylight, no crowd.",
+    ),
+    "theatre-front-with-neighbours": (
+        "el-capitan-theater-detail/01-el-capitan-marquee.jpg",
+        "A frontal view of the theatre in the reference photograph together with "
+        "the buildings either side of it, the whole frontage and its full height "
+        "in frame, shot from across the road. Even daylight, no crowd, marquee "
+        "lettering blocked out as unreadable texture.",
+    ),
+}
+
+
+def load_token() -> str:
+    token = os.environ.get("OPENROUTER_API_KEY")
+    if token:
+        return token.strip()
+    env_path = os.path.join(ROOT, ".env")
+    if os.path.exists(env_path):
+        with open(env_path, encoding="utf-8") as handle:
+            for line in handle:
+                line = line.strip()
+                if line.startswith("OPENROUTER_API_KEY="):
+                    return line.split("=", 1)[1].strip().strip('"').strip("'")
+    raise SystemExit("no OpenRouter key: set OPENROUTER_API_KEY or add it to .env")
+
+
+def build_prompt(study: str) -> str:
+    """The full prompt for a study: its request plus the fixed anchor suffix."""
+    if study not in STUDIES:
+        raise KeyError(f"unknown study {study!r}; known: {sorted(STUDIES)}")
+    return f"{STUDIES[study][1]}\n\n{ANCHOR_SUFFIX}"
+
+
+def reference_path(study: str) -> str:
+    return os.path.join(REFERENCE_DIR, STUDIES[study][0])
+
+
+def missing_references() -> list[str]:
+    """Studies whose source photograph is not present locally."""
+    return [name for name in STUDIES if not os.path.isfile(reference_path(name))]
+
+
+def next_free_path(study: str, directory: str = OUT_DIR) -> str:
+    """`<study>.png`, or `<study>-v2.png`, `-v3` … if the name is taken."""
+    base = os.path.join(directory, f"{study}.png")
+    if not os.path.exists(base):
+        return base
+    index = 2
+    while True:
+        candidate = os.path.join(directory, f"{study}-v{index}.png")
+        if not os.path.exists(candidate):
+            return candidate
+        index += 1
+
+
+def data_url(path: str) -> str:
+    suffix = os.path.splitext(path)[1].lower()
+    mime = {".jpg": "image/jpeg", ".jpeg": "image/jpeg", ".png": "image/png"}.get(suffix)
+    if not mime:
+        raise SystemExit(f"unsupported reference type: {path}")
+    with open(path, "rb") as handle:
+        return f"data:{mime};base64,{base64.b64encode(handle.read()).decode('ascii')}"
+
+
+def decode_image(payload: dict) -> bytes:
+    """Extract the returned image bytes from a chat-completions payload."""
+    message = (payload.get("choices") or [{}])[0].get("message", {})
+    urls = [item.get("image_url", {}).get("url", "")
+            for item in (message.get("images") or []) if isinstance(item, dict)]
+    if not urls:
+        match = re.search(r"data:image/[a-z]+;base64,[A-Za-z0-9+/=]+",
+                          str(message.get("content") or ""))
+        if match:
+            urls.append(match.group(0))
+    if not urls or not urls[0]:
+        raise SystemExit(f"model returned no image data: {json.dumps(payload)[:400]}")
+    url = urls[0]
+    if url.startswith("data:"):
+        return base64.b64decode(url.split(",", 1)[1])
+    with urllib.request.urlopen(urllib.request.Request(url), timeout=120) as response:
+        return response.read()
+
+
+def generate(study: str, token: str, model: str, force: bool = False) -> str:
+    """Generate one study; returns the written path. Never overwrites by default."""
+    path = next_free_path(study)
+    if force and os.path.exists(os.path.join(OUT_DIR, f"{study}.png")):
+        path = os.path.join(OUT_DIR, f"{study}.png")
+        # Write to a temp name then replace, so a failed call cannot destroy the
+        # previous result.
+        target = path + ".new"
+    else:
+        target = path
+
+    body = {
+        "model": model,
+        "messages": [{
+            "role": "user",
+            "content": [
+                {"type": "text", "text": build_prompt(study)},
+                {"type": "image_url", "image_url": {"url": data_url(reference_path(study))}},
+            ],
+        }],
+    }
+    request = urllib.request.Request(
+        API_URL,
+        data=json.dumps(body).encode("utf-8"),
+        headers={
+            "Authorization": f"Bearer {token}",
+            "Content-Type": "application/json",
+            "HTTP-Referer": "https://git.allucanget.biz/zwitschi/gig-line",
+            "X-Title": "gig-line facade details",
+        },
+        method="POST",
+    )
+
+    payload = None
+    for attempt in range(3):
+        try:
+            with urllib.request.urlopen(request, timeout=180) as response:
+                payload = json.load(response)
+            break
+        except urllib.error.HTTPError as exc:
+            if exc.code == 429 or exc.code >= 500:
+                wait = 5 * (attempt + 1)
+                sys.stderr.write(f"  HTTP {exc.code}; retrying in {wait}s\n")
+                time.sleep(wait)
+                continue
+            detail = exc.read().decode("utf-8", "replace")[:300]
+            raise SystemExit(f"{study}: HTTP {exc.code} — {detail}")
+        except urllib.error.URLError as exc:
+            sys.stderr.write(f"  network error ({exc.reason}); retrying\n")
+            time.sleep(5 * (attempt + 1))
+    if payload is None:
+        raise SystemExit(f"{study}: no response after retries")
+
+    image = decode_image(payload)
+    os.makedirs(OUT_DIR, exist_ok=True)
+    with open(target, "wb") as handle:
+        handle.write(image)
+    if target != path:
+        os.replace(target, path)
+
+    import hashlib
+    sidecar = {
+        "study": study,
+        "generated": os.path.basename(path),
+        "generated_utc": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()),
+        "model": model,
+        "prompt": build_prompt(study),
+        "reference": {
+            "file": STUDIES[study][0],
+            "note": "local reference photography; Art/reference is gitignored and never shipped",
+        },
+        "sha256": hashlib.sha256(image).hexdigest(),
+        "bytes": len(image),
+        "redistribution": "local development reference only; not committed, not shipped",
+    }
+    sidecar_path = os.path.splitext(path)[0] + ".refgen.json"
+    with open(sidecar_path, "w", encoding="utf-8") as handle:
+        json.dump(sidecar, handle, indent=2)
+    if token in json.dumps(sidecar):
+        raise SystemExit("refusing to write a sidecar containing the token")
+    return path
+
+
+def main(argv=None) -> int:
+    ap = argparse.ArgumentParser(description=__doc__,
+                                 formatter_class=argparse.RawDescriptionHelpFormatter)
+    ap.add_argument("--list", action="store_true", help="list studies and exit (free)")
+    ap.add_argument("--all", action="store_true", help="generate every study")
+    ap.add_argument("--only", help="comma-separated study names")
+    ap.add_argument("--model", default=DEFAULT_MODEL)
+    ap.add_argument("--force", action="store_true",
+                    help="replace the existing <study>.png instead of writing a -vN")
+    args = ap.parse_args(argv)
+
+    if args.list or not (args.all or args.only):
+        missing = set(missing_references())
+        print(f"{len(STUDIES)} studies; model {args.model}")
+        for name, (ref, _prompt) in STUDIES.items():
+            state = "MISSING reference" if name in missing else "ready"
+            print(f"  {name:22} {state:18} <- {ref}")
+        if missing:
+            print(f"\n{len(missing)} study(ies) cannot run without their reference photograph.")
+        return 0
+
+    names = list(STUDIES) if args.all else [s.strip() for s in args.only.split(",") if s.strip()]
+    unknown = [n for n in names if n not in STUDIES]
+    if unknown:
+        raise SystemExit(f"unknown study(ies): {unknown}; known: {sorted(STUDIES)}")
+    blocked = [n for n in names if n in set(missing_references())]
+    if blocked:
+        raise SystemExit(f"missing reference photograph for: {blocked}")
+    token = load_token()
+
+    print(f"generating {len(names)} study(ies) with {args.model} -> {OUT_DIR}")
+    for index, name in enumerate(names, 1):
+        print(f"[{index}/{len(names)}] {name}")
+        try:
+            path = generate(name, token, args.model, force=args.force)
+        except SystemExit as exc:
+            sys.stderr.write(f"  FAILED: {exc}\n")
+            continue
+        print(f"  wrote {os.path.relpath(path, ROOT)}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

Tools/fbx_export_preset.py

@@ -0,0 +1,94 @@
+#!/usr/bin/env python3
+"""The one FBX export preset for this project ("ue_metric_v1"/"ue_character_v1").
+
+Before this module the same `bpy.ops.export_scene.fbx(...)` argument block was
+copied into six scripts (hero, frontage, north buildings, site, scale test, MPFB
+character). They had already drifted only by accident, and every one of them
+carried `mesh_smooth_type="OFF"` — which is why Unreal logged "No smoothing group
+information was found for this mesh" on every import and round parts rendered
+faceted. One preset, one place to fix that.
+
+Use from inside Blender:
+
+    import sys, os
+    sys.path.insert(0, os.path.join(os.path.dirname(__file__), "..", "Tools"))
+    import fbx_export_preset as preset
+
+    preset.export_static(path)                      # whole scene, MESH only
+    preset.export_static(path, selection=True)      # selected objects only
+    preset.export_character(path)                   # armature + mesh, character flags
+
+`preset_kwargs()` is pure (no `bpy`), so the argument set can be unit-tested
+without Blender — see Tools/tests/test_fbx_export_preset.py.
+
+Why these values:
+* `FBX_SCALE_NONE` + `apply_unit_scale` keeps Blender metres → Unreal centimetres
+  at exactly ×100, verified by the three-cube scale test (1 m → 100.00 uu).
+* `axis_forward="-Y"`, `axis_up="Z"` is the project's recorded mapping: east → +X,
+  north → −Y, up → +Z.
+* `mesh_smooth_type="FACE"` exports smoothing groups. `"OFF"` (the old value)
+  drops them, so Unreal rebuilds flat normals and every cylinder is faceted.
+* `use_mesh_modifiers=True` bakes the bevel/modifier stack at export; the source
+  `.blend` stays non-destructive.
+"""
+
+from __future__ import annotations
+
+# Shared by every mesh export. Values are the recorded ue_metric_v1 preset.
+_METRIC = {
+    "object_types": {"MESH"},
+    "apply_unit_scale": True,
+    "apply_scale_options": "FBX_SCALE_NONE",
+    "axis_forward": "-Y",
+    "axis_up": "Z",
+    "use_space_transform": True,
+    "use_mesh_modifiers": True,
+    "mesh_smooth_type": "FACE",
+    "path_mode": "AUTO",
+    "bake_space_transform": False,
+}
+
+# Character exports differ only in the object set and the armature/path flags.
+_CHARACTER = dict(
+    _METRIC,
+    object_types={"ARMATURE", "MESH"},
+    add_leaf_bones=False,
+    path_mode="COPY",
+    embed_textures=False,
+)
+
+PRESETS = {"ue_metric_v1": _METRIC, "ue_character_v1": _CHARACTER}
+
+
+def preset_kwargs(preset: str = "ue_metric_v1", selection: bool = False, **overrides) -> dict:
+    """Return the `bpy.ops.export_scene.fbx` argument dict (no `bpy` needed).
+
+    `preset` selects the base set, `selection` decides whether only selected
+    objects are exported, and `overrides` wins last for the rare special case.
+    """
+    if preset not in PRESETS:
+        raise KeyError(f"unknown preset {preset!r}; known: {sorted(PRESETS)}")
+    kwargs = dict(PRESETS[preset])
+    kwargs["use_selection"] = bool(selection)
+    kwargs.update(overrides)
+    if "filepath" in kwargs:
+        raise ValueError("pass the path to export_static/export_character, not as an override")
+    return kwargs
+
+
+def _export(path: str, preset: str, selection: bool, overrides: dict) -> str:
+    import bpy  # imported here so `preset_kwargs` stays usable without Blender
+
+    kwargs = preset_kwargs(preset, selection=selection, **overrides)
+    bpy.ops.export_scene.fbx(filepath=path, **kwargs)
+    return path
+
+
+def export_static(path: str, selection: bool = False, **overrides) -> str:
+    """Export meshes with the ue_metric_v1 preset. Returns the path."""
+    return _export(path, "ue_metric_v1", selection, overrides)
+
+
+def export_character(path: str, selection: bool = False, **overrides) -> str:
+    """Export armature + mesh with the ue_character_v1 preset. Returns the path."""
+    return _export(path, "ue_character_v1", selection, overrides)

Tools/hero_facade_build.py

@@ -33,6 +33,9 @@ import os
 import sys
 
 import bpy
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+import fbx_export_preset as fbx_preset  # noqa: E402
+
 
 # --- measured / derived ------------------------------------------------------
 FRONTAGE_W = 25.75
@@ -50,8 +53,12 @@ FRONTAGE_Y = 0.0        # front plane sits at the building line of the block fra
 PEDESTAL_H = 1.45       # column pedestal top; entrance platform sits on it
 COLUMN_D = 0.95         # Ionic shaft diameter at the base
 CAPITAL_H = 0.95
-ENTABLATURE_H = 3.40    # band between the capitals and the motto panel
-PARAPET_H = 2.20        # motto panel and cornice above the entablature
+ENTABLATURE_H = 3.00    # band between the capitals and the motto panel
+                        # 3.40 -> 3.00 on 2026-11-09: the photographs put the
+                        # colonnade at 50-60 % of the 14.5 m elevation, and our
+                        # 3.40/2.20 entablature+parapet left it at 47.6 %. Thinning
+                        # both lifts the colonnade to 7.70 m = 53.1 %, inside the band.
+PARAPET_H = 1.80        # motto panel and cornice above the entablature (see above)
 PORTAL_W = 3.10         # each of the three door openings
 PORTAL_H = 3.40
 STEP_TREAD = 0.34
@@ -70,7 +77,7 @@ def cube(name, x, y, z, dx, dy, dz, material=None):
     return obj
 
 
-def cylinder(name, x, y, z0, z1, radius, material, vertices=24):
+def cylinder(name, x, y, z0, z1, radius, material, vertices=24, smooth=True):
     bpy.ops.mesh.primitive_cylinder_add(
         vertices=vertices,
         radius=radius,
@@ -81,6 +88,30 @@ def cylinder(name, x, y, z0, z1, radius, material, vertices=24):
     obj.name = name
     if material:
         obj.data.materials.append(material)
+    if smooth:
+        # Round parts must shade smoothly *around* the axis while keeping the
+        # caps creased. Without this the columns read as faceted prisms, and the
+        # FBX carries no smoothing groups at all (Unreal warns about it).
+        bpy.ops.object.shade_smooth_by_angle(angle=math.radians(35.0))
+    return obj
+
+
+def disc_on_wall(name, x, y, z, radius, thickness, material=None, vertices=24):
+    """A round disc mounted vertically on a wall face.
+
+    `cylinder()` builds along Z, so a "medallion" made with it is a pancake lying
+    flat on top of the parapet rather than a disc on its face — which is what the
+    first build did (1.1 m across in Y, 0.02 m thick in Z, sitting at the coping).
+    This rotates the cylinder 90 degrees about X so the axis points along Y and
+    the disc faces the street.
+    """
+    obj = cylinder(name, x, y, z - thickness / 2.0, z + thickness / 2.0,
+                   radius, material, vertices=vertices)
+    obj.rotation_euler = (math.radians(90.0), 0.0, 0.0)
+    bpy.ops.object.select_all(action="DESELECT")
+    obj.select_set(True)
+    bpy.context.view_layer.objects.active = obj
+    bpy.ops.object.transform_apply(location=False, rotation=True, scale=True)
     return obj
 
 
@@ -132,14 +163,32 @@ def build():
         col_xs.append(x)
         cube(f"Hero_Pedestal_{i + 1}", x, -0.62, PEDESTAL_H + 0.27,
              1.24, 1.24, 0.54, stone)
-        cylinder(f"Hero_Column_{i + 1}", x, -0.55, PEDESTAL_H + 0.55,
-                 PEDESTAL_H + 0.55 + (HEIGHT - ENTABLATURE_H - PARAPET_H - PEDESTAL_H - 0.55 - CAPITAL_H),
+        # Base moulding: a taller, wider cylinder where the shaft meets the
+        # pedestal. Without it the shaft starts straight off a square plinth,
+        # which is not how an Ionic base reads in silhouette.
+        base_z0 = PEDESTAL_H + 0.55
+        base_h = 0.22
+        cylinder(f"Hero_ColumnBase_{i + 1}", x, -0.55, base_z0, base_z0 + base_h,
+                 0.68, stone, vertices=20)
+        shaft_z0 = base_z0 + base_h
+        cap_z0 = HEIGHT - ENTABLATURE_H - PARAPET_H - CAPITAL_H
+        cylinder(f"Hero_Column_{i + 1}", x, -0.55, shaft_z0, cap_z0,
                  COLUMN_D / 2.0, stone)
-        cylinder(f"Hero_Capital_{i + 1}", x, -0.55,
-                 HEIGHT - ENTABLATURE_H - PARAPET_H - CAPITAL_H,
-                 HEIGHT - ENTABLATURE_H - PARAPET_H, 0.62, stone, vertices=16)
+        # Capital block, then the square abacus that carries the architrave.
+        # The abacus takes the top 0.14 m of the capital zone so the colonnade
+        # still ends at HEIGHT - ENTABLATURE_H - PARAPET_H (proportion unchanged).
+        abacus_h = 0.14
+        cylinder(f"Hero_Capital_{i + 1}", x, -0.55, cap_z0,
+                 HEIGHT - ENTABLATURE_H - PARAPET_H - abacus_h, 0.62, stone, vertices=16)
+        cube(f"Hero_Abacus_{i + 1}", x, -0.55,
+             HEIGHT - ENTABLATURE_H - PARAPET_H - abacus_h / 2.0,
+             1.30, 1.30, abacus_h, stone)
     note("Hero_Column_x6", (COLUMN_D, COLUMN_D, HEIGHT - ENTABLATURE_H - PARAPET_H - PEDESTAL_H),
          f"6 columns at {COLUMN_BAY} m centres (sibling notes x measured frontage)")
+    note("Hero_ColumnBase_x6", (1.36, 1.36, 0.22),
+         "assumption: Ionic base moulding; photographs show a wider base at the shaft foot")
+    note("Hero_Abacus_x6", (1.30, 1.30, 0.14),
+         "assumption: square abacus under the architrave, as Ionic capitals carry")
 
     # --- entablature and parapet ------------------------------------------
     ent_z0 = HEIGHT - ENTABLATURE_H - PARAPET_H
@@ -147,9 +196,25 @@ def build():
     # elevation reads as layered stone rather than one flat plane.
     cube("Hero_Architrave", 0.0, -1.55, ent_z0 + 0.42, FRONTAGE_W, 1.65, 0.84, stone)
     note("Hero_Architrave", (FRONTAGE_W, 1.65, 0.84), "assumption: stacked entablature bands")
-    # Cornice under the parapet.
-    cube("Hero_Cornice", 0.0, -1.6, HEIGHT - PARAPET_H - 0.18, FRONTAGE_W, 1.75, 0.36, stone)
+    # Cornice under the parapet: a projecting corona carried on a dentil course,
+    # so the top of the order reads as layered stone with a shadow line rather
+    # than one flat box. Dentils hang under the corona and stand 0.25 m clear of
+    # it, which is what gives the elevation its cornice shadow at street level.
+    cornice_z = HEIGHT - PARAPET_H - 0.18
+    cube("Hero_Cornice", 0.0, -1.6, cornice_z, FRONTAGE_W, 1.75, 0.36, stone)
     note("Hero_Cornice", (FRONTAGE_W, 1.75, 0.36), "assumption: projecting cornice line")
+    DENTIL_W, DENTIL_D, DENTIL_H, DENTIL_GAP = 0.18, 0.30, 0.22, 0.27
+    dentil_y = -2.30
+    dentil_z = cornice_z - 0.18 - DENTIL_H / 2.0
+    dentil_span = FRONTAGE_W - 2.0
+    dentil_count = int(dentil_span / (DENTIL_W + DENTIL_GAP))
+    for i in range(dentil_count):
+        dx = -dentil_span / 2.0 + (DENTIL_W + DENTIL_GAP) * i + DENTIL_W / 2.0
+        cube(f"Hero_Dentil_{i + 1}", dx, dentil_y, dentil_z,
+             DENTIL_W, DENTIL_D, DENTIL_H, stone)
+    note("Hero_Dentil_xN", (DENTIL_W, DENTIL_D, DENTIL_H),
+         f"{dentil_count} dentils at {DENTIL_W + DENTIL_GAP:.2f} m centres under the corona; "
+         "assumption: photographed cornice reads as a dentilled course")
     cube("Hero_Entablature", 0.0, -0.75, ent_z0 + ENTABLATURE_H / 2.0,
          FRONTAGE_W, 1.5, ENTABLATURE_H, stone)
     note("Hero_Entablature", (FRONTAGE_W, 1.5, ENTABLATURE_H), "assumption: entablature depth")
@@ -163,11 +228,13 @@ def build():
          FRONTAGE_W - 3.0, 0.08, 0.85, stone_dark)
     note("Hero_MottoBand", (FRONTAGE_W - 3.0, 0.08, 0.85), "photographs: motto panel above the colonnade")
 
-    # Medallions either side of the inscription.
+    # Medallions either side of the inscription: discs on the parapet face, not
+    # pancakes on the coping (see disc_on_wall).
     for i, x in enumerate((-6.2, 6.2), start=1):
-        cylinder(f"Hero_Medallion_{i}", x, -1.36, HEIGHT - PARAPET_H / 2.0 + 0.42,
-                 HEIGHT - PARAPET_H / 2.0 + 0.44, 0.55, stone_dark, vertices=20)
-    note("Hero_Medallion_x2", (1.1, 1.1, 0.02), "photographs: two stone discs beside the motto")
+        disc_on_wall(f"Hero_Medallion_{i}", x, -1.30, HEIGHT - PARAPET_H / 2.0,
+                     0.55, 0.04, stone_dark, vertices=20)
+    note("Hero_Medallion_x2", (1.1, 0.04, 1.1),
+         "photographs: two stone discs beside the motto, mounted on the parapet face")
 
     # --- entrances ---------------------------------------------------------
     # Three portals between column pairs, each with its own short flight. The
@@ -241,32 +308,27 @@ def build():
 
     # --- windows -----------------------------------------------------------
     # Two ranks of windows between the columns and behind the colonnade.
+    # Y must sit on the wall plane: the mass front face is at Y -0.50 and the
+    # columns stand proud to -1.02. These were at -1.98, i.e. 1.44 m in FRONT of
+    # the wall and ahead of the column line, so the glazing floated in the
+    # colonnade instead of reading as openings behind it (visible in the
+    # review-hero-facade-* shots). WINDOW_Y puts the pane 6 cm proud of the wall,
+    # safely behind the columns.
+    WINDOW_Y = -0.56
     for rank, z in enumerate((4.4, 8.2), start=1):
         for i, x in enumerate(col_xs[:-1], start=1):
             wx = x + COLUMN_BAY / 2.0
-            cube(f"Hero_Window_{rank}_{i}", wx, -1.98, z, 2.0, 0.08, 1.9, glass)
+            cube(f"Hero_Window_{rank}_{i}", wx, WINDOW_Y, z, 2.0, 0.08, 1.9, glass)
     note("Hero_Window_x10", (2.0, 0.08, 1.9), "photographs: window bands behind the colonnade")
 
     return parts, lines
 
 
 def export_fbx(path):
+    # Preset lives in Tools/fbx_export_preset.py (ue_metric_v1).
     os.makedirs(os.path.dirname(path), exist_ok=True)
     # Named export preset "ue_metric_v1" - same settings as Tools/scale_test_export.py.
-    bpy.ops.export_scene.fbx(
-        filepath=path,
-        use_selection=False,
-        object_types={"MESH"},
-        apply_unit_scale=True,
-        apply_scale_options="FBX_SCALE_NONE",
-        axis_forward="-Y",
-        axis_up="Z",
-        use_space_transform=True,
-        use_mesh_modifiers=True,
-        mesh_smooth_type="OFF",
-        path_mode="AUTO",
-        bake_space_transform=False,
-    )
+    fbx_preset.export_static(path)
     print(f"[hero] exported FBX preset ue_metric_v1 -> {path}")
 
 

Tools/mpfb_character_export.py

@@ -19,6 +19,9 @@ import sys
 import zlib
 
 import bpy
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+import fbx_export_preset as fbx_preset  # noqa: E402
+
 import numpy
 
 from mathutils import Euler
@@ -149,22 +152,7 @@ def make_diffuse(human, size=1024):
 def export_fbx(human, path):
     os.makedirs(os.path.dirname(path), exist_ok=True)
     # Named export preset "ue_character_v1" — change only via a new preset name.
-    bpy.ops.export_scene.fbx(
-        filepath=path,
-        use_selection=False,
-        object_types={"ARMATURE", "MESH"},
-        apply_unit_scale=True,
-        apply_scale_options="FBX_SCALE_NONE",
-        axis_forward="-Y",
-        axis_up="Z",
-        use_space_transform=True,
-        use_mesh_modifiers=True,
-        add_leaf_bones=False,
-        path_mode="COPY",
-        embed_textures=False,
-        mesh_smooth_type="OFF",
-        bake_space_transform=False,
-    )
+    fbx_preset.export_character(path)
     log(f"export: FBX preset ue_character_v1 -> {path}")
 
 

Tools/scale_test_export.py

@@ -16,6 +16,9 @@ import os
 import sys
 
 import bpy
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+import fbx_export_preset as fbx_preset  # noqa: E402
+
 
 
 def build_scene():
@@ -44,20 +47,7 @@ def build_scene():
 def export_fbx(path):
     os.makedirs(os.path.dirname(path), exist_ok=True)
     # Named export preset "ue_metric_v1" - change only via a new preset name.
-    bpy.ops.export_scene.fbx(
-        filepath=path,
-        use_selection=False,
-        object_types={"MESH"},
-        apply_unit_scale=True,
-        apply_scale_options="FBX_SCALE_NONE",
-        axis_forward="-Y",
-        axis_up="Z",
-        use_space_transform=True,
-        use_mesh_modifiers=True,
-        mesh_smooth_type="OFF",
-        path_mode="AUTO",
-        bake_space_transform=False,
-    )
+    fbx_preset.export_static(path)
     print(f"[scale_test] exported FBX preset ue_metric_v1 -> {path}")
 
 

Tools/tests/README.md

@@ -0,0 +1,26 @@
+# Tooling tests
+
+Standard-library `unittest` tests for the host-side tools in `Tools/`. They never start Blender, Unreal, or the game; anything that needs those processes is verified by the tool itself and recorded in `Docs/release-checks.md` instead.
+
+Run from the repository root:
+
+```bash
+python3 -m pip install -r requirements-tools.txt
+python3 -m unittest discover -s Tools/tests -t Tools -p 'test_*.py'
+```
+
+The `-t Tools` top-level directory is required: the tests import the tool modules by their plain names (`import input_emulation`), which is why `Tools/tests/` carries an `__init__.py`.
+
+Individual test:
+
+```bash
+python3 -m unittest Tools.tests.test_input_emulation -v
+```
+
+## What belongs here
+
+Test the **pure** parts — argument parsing, key/coordinate encoding, geometry maths, licence gating, report formatting, decision classification. Network, Blender and Unreal calls stay out: a test that needs a paid API, a display, or an engine process is a manual check, not a unit test.
+
+When a tool's logic is buried in `main()`, extract it into a function so it can be tested directly. That is a tooling improvement, not test scaffolding.
+
+Geo (`Geo/tools/`) and Blender (`Art/blender/*/`) builders are tested the same way once their pure parts are extracted; note the module path in the test.

Tools/tests/__init__.py

@@ -0,0 +1 @@
+"""Package marker so `python3 -m unittest Tools.tests.<module>` resolves."""

Tools/tests/test_block_height_report.py

@@ -0,0 +1,59 @@
+"""Tests for Geo/tools/block_height_report.py::classify_height.
+
+The Geo tools live outside `Tools/`, so the test adds `Geo/tools` to `sys.path`
+before importing the module by name.
+"""
+
+import os
+import sys
+import unittest
+
+ROOT = os.path.abspath(os.path.join(os.path.dirname(__file__), "..", ".."))
+sys.path.insert(0, os.path.join(ROOT, "Geo", "tools"))
+
+import block_height_report as bhr  # noqa: E402
+
+
+class ClassifyHeightTest(unittest.TestCase):
+    def test_height_tag_wins(self):
+        height, source = bhr.classify_height({"building": "yes", "height": "18.1"})
+        self.assertEqual(height, 18.1)
+        self.assertEqual(source, "height tag")
+
+    def test_height_tag_beats_levels(self):
+        height, _ = bhr.classify_height(
+            {"building": "yes", "height": "12.5", "building:levels": "4"})
+        self.assertEqual(height, 12.5)
+
+    def test_levels_derive_height(self):
+        height, source = bhr.classify_height(
+            {"building": "yes", "building:levels": "4"}, level_height=3.2)
+        self.assertEqual(height, 12.8)
+        self.assertIn("levels x", source)
+
+    def test_roof_is_not_a_building_volume(self):
+        # building=roof at layer=1 is an elevated canopy, not a two-storey block.
+        height, source = bhr.classify_height({"building": "roof", "layer": "1"})
+        self.assertEqual(height, 0.0)
+        self.assertIn("not a building volume (roof)", source)
+
+    def test_canopy_is_not_a_building_volume(self):
+        # building=canopy at layer=1, found by the Mapbox cross-check.
+        height, source = bhr.classify_height({"building": "canopy", "layer": "1"})
+        self.assertEqual(height, 0.0)
+        self.assertIn("not a building volume (canopy)", source)
+
+    def test_transit_shelter_is_not_a_building_volume(self):
+        height, source = bhr.classify_height(
+            {"building": "yes", "amenity": "shelter", "shelter_type": "public_transport"})
+        self.assertEqual(height, 0.0)
+        self.assertIn("not a building volume (shelter)", source)
+
+    def test_missing_data_falls_back_to_a_flagged_guess(self):
+        height, source = bhr.classify_height({"building": "yes"})
+        self.assertEqual(height, 2 * bhr.LEVEL_HEIGHT)
+        self.assertTrue(source.startswith("GUESS"))
+
+
+if __name__ == "__main__":
+    unittest.main()

Tools/tests/test_facade_detail_concepts.py

@@ -0,0 +1,108 @@
+"""Tests for Tools/facade_detail_concepts.py — the pure parts.
+
+No network calls: the OpenRouter request and the image bytes are represented as
+the small structures the API uses. Generation itself is manual and paid.
+"""
+
+import base64
+import json
+import os
+import sys
+import unittest
+
+ROOT = os.path.abspath(os.path.join(os.path.dirname(__file__), "..", ".."))
+sys.path.insert(0, os.path.join(ROOT, "Tools"))
+
+import facade_detail_concepts as fc  # noqa: E402
+
+
+class StudyTableTest(unittest.TestCase):
+    def test_every_study_has_a_reference_and_a_prompt(self):
+        self.assertTrue(fc.STUDIES)
+        for name, (ref, prompt) in fc.STUDIES.items():
+            self.assertTrue(ref, f"{name} has no reference")
+            self.assertTrue(prompt.strip(), f"{name} has no prompt")
+            # References are relative to Art/reference and never escape it.
+            self.assertFalse(os.path.isabs(ref), f"{name} reference is absolute")
+            self.assertNotIn("..", ref, f"{name} reference escapes the directory")
+
+    def test_prompt_always_carries_the_anchor_suffix(self):
+        for name in fc.STUDIES:
+            prompt = fc.build_prompt(name)
+            self.assertIn(fc.ANCHOR_SUFFIX, prompt)
+            self.assertIn(fc.STUDIES[name][1], prompt)
+
+    def test_unknown_study_raises(self):
+        with self.assertRaises(KeyError):
+            fc.build_prompt("no-such-study")
+
+
+class NextFreePathTest(unittest.TestCase):
+    def test_uses_the_plain_name_when_free(self):
+        import tempfile
+        with tempfile.TemporaryDirectory() as tmp:
+            self.assertEqual(os.path.basename(fc.next_free_path("x", tmp)), "x.png")
+
+    def test_never_overwrites(self):
+        import tempfile
+        with tempfile.TemporaryDirectory() as tmp:
+            open(os.path.join(tmp, "x.png"), "w").close()
+            self.assertEqual(os.path.basename(fc.next_free_path("x", tmp)), "x-v2.png")
+            open(os.path.join(tmp, "x-v2.png"), "w").close()
+            self.assertEqual(os.path.basename(fc.next_free_path("x", tmp)), "x-v3.png")
+
+
+class DecodeImageTest(unittest.TestCase):
+    PAYLOAD_BYTES = b"\x89PNG\r\n\x1a\nfake"
+
+    def _data_url(self):
+        return "data:image/png;base64," + base64.b64encode(self.PAYLOAD_BYTES).decode()
+
+    def test_reads_message_images(self):
+        payload = {"choices": [{"message": {
+            "images": [{"image_url": {"url": self._data_url()}}]}}]}
+        self.assertEqual(fc.decode_image(payload), self.PAYLOAD_BYTES)
+
+    def test_reads_a_data_url_embedded_in_content(self):
+        payload = {"choices": [{"message": {"content": f"here: {self._data_url()}"}}]}
+        self.assertEqual(fc.decode_image(payload), self.PAYLOAD_BYTES)
+
+    def test_refusal_raises_with_the_text(self):
+        payload = {"choices": [{"message": {"content": "I cannot do that."}}]}
+        with self.assertRaises(SystemExit):
+            fc.decode_image(payload)
+
+
+class DataUrlTest(unittest.TestCase):
+    def test_encodes_a_jpeg(self):
+        import tempfile
+        with tempfile.NamedTemporaryFile(suffix=".jpg", delete=False) as handle:
+            handle.write(b"jpegbytes")
+            path = handle.name
+        try:
+            url = fc.data_url(path)
+            self.assertTrue(url.startswith("data:image/jpeg;base64,"))
+        finally:
+            os.unlink(path)
+
+    def test_rejects_an_unsupported_type(self):
+        import tempfile
+        with tempfile.NamedTemporaryFile(suffix=".gif", delete=False) as handle:
+            path = handle.name
+        try:
+            with self.assertRaises(SystemExit):
+                fc.data_url(path)
+        finally:
+            os.unlink(path)
+
+
+class SidecarShapeTest(unittest.TestCase):
+    def test_studies_and_outputs_are_local_only(self):
+        # The output directory lives under the gitignored Art/reference tree, so
+        # neither the images nor the sidecars can be committed.
+        self.assertIn(os.path.join("Art", "reference"), fc.OUT_DIR)
+        self.assertIn("gitignored", fc.__doc__)
+
+
+if __name__ == "__main__":
+    unittest.main()

Tools/tests/test_fbx_export_preset.py

@@ -0,0 +1,70 @@
+"""Tests for Tools/fbx_export_preset.py.
+
+The preset module keeps its argument set in plain dicts and builds it in
+`preset_kwargs()`, so the export contract can be checked without starting
+Blender. Only `export_static`/`export_character` import `bpy`.
+"""
+
+import os
+import sys
+import unittest
+
+ROOT = os.path.abspath(os.path.join(os.path.dirname(__file__), "..", ".."))
+sys.path.insert(0, os.path.join(ROOT, "Tools"))
+
+import fbx_export_preset as preset  # noqa: E402
+
+
+class MetricPresetTest(unittest.TestCase):
+    def test_scale_and_axis_contract(self):
+        # These three are the project's recorded conversion contract: metres ->
+        # centimetres by a factor of exactly 100, east +X, north -Y, up +Z.
+        kwargs = preset.preset_kwargs()
+        self.assertTrue(kwargs["apply_unit_scale"])
+        self.assertEqual(kwargs["apply_scale_options"], "FBX_SCALE_NONE")
+        self.assertEqual(kwargs["axis_forward"], "-Y")
+        self.assertEqual(kwargs["axis_up"], "Z")
+
+    def test_smoothing_groups_are_exported(self):
+        # "OFF" (the pre-refactor value) drops smoothing groups and every Unreal
+        # import warns about it, with round parts faceted.
+        self.assertEqual(preset.preset_kwargs()["mesh_smooth_type"], "FACE")
+
+    def test_selection_flag(self):
+        self.assertFalse(preset.preset_kwargs()["use_selection"])
+        self.assertTrue(preset.preset_kwargs(selection=True)["use_selection"])
+
+    def test_object_types_are_meshes_only(self):
+        self.assertEqual(preset.preset_kwargs()["object_types"], {"MESH"})
+
+
+class CharacterPresetTest(unittest.TestCase):
+    def test_character_exports_armature_and_mesh(self):
+        kwargs = preset.preset_kwargs("ue_character_v1")
+        self.assertEqual(kwargs["object_types"], {"ARMATURE", "MESH"})
+        self.assertFalse(kwargs["add_leaf_bones"])
+        self.assertEqual(kwargs["path_mode"], "COPY")
+        self.assertFalse(kwargs["embed_textures"])
+
+    def test_character_keeps_the_scale_contract(self):
+        kwargs = preset.preset_kwargs("ue_character_v1")
+        self.assertEqual(kwargs["apply_scale_options"], "FBX_SCALE_NONE")
+        self.assertEqual(kwargs["mesh_smooth_type"], "FACE")
+
+
+class OverrideTest(unittest.TestCase):
+    def test_overrides_win(self):
+        kwargs = preset.preset_kwargs(mesh_smooth_type="OFF")
+        self.assertEqual(kwargs["mesh_smooth_type"], "OFF")
+
+    def test_unknown_preset_raises(self):
+        with self.assertRaises(KeyError):
+            preset.preset_kwargs("ue_imperial_v9")
+
+    def test_filepath_must_not_be_an_override(self):
+        with self.assertRaises(ValueError):
+            preset.preset_kwargs(filepath="/tmp/x.fbx")
+
+
+if __name__ == "__main__":
+    unittest.main()

Tools/tests/test_input_emulation.py

@@ -0,0 +1,57 @@
+"""Tests for Tools/input_emulation.py — the pure ioctl/key-code parts.
+
+The device path itself needs /dev/uinput, so only the encoding helpers are
+covered here; the end-to-end injection is verified by running the tool (see
+Docs/release-checks.md and MEMORY.md).
+"""
+
+import unittest
+
+import input_emulation as ie
+
+
+class IocEncodingTest(unittest.TestCase):
+    """_IOC must match the Linux ioctl bit layout."""
+
+    def test_layout_constants(self):
+        self.assertEqual(ie._IOC_NRSHIFT, 0)
+        self.assertEqual(ie._IOC_TYPESHIFT, 8)
+        self.assertEqual(ie._IOC_SIZESHIFT, 16)
+        self.assertEqual(ie._IOC_DIRSHIFT, 30)
+
+    def test_known_values(self):
+        # UI_SET_EVBIT = _IOW('U', 100, int) -> 0x40045564 on Linux.
+        self.assertEqual(ie.UI_SET_EVBIT, 0x40045564)
+        # UI_DEV_CREATE = _IO('U', 1) -> 0x5501.
+        self.assertEqual(ie.UI_DEV_CREATE, 0x5501)
+
+    def test_type_accepts_char_or_int(self):
+        self.assertEqual(ie._ioc(1, 4, "U", 100), ie._ioc(1, 4, ord("U"), 100))
+
+
+class KeyCodeTest(unittest.TestCase):
+    """KEYCODES must hold the Linux input-event codes the demo uses."""
+
+    EXPECTED = {
+        "w": 17, "s": 31, "a": 30, "d": 32,
+        "space": 57, "r": 19, "esc": 1,
+    }
+
+    def test_demo_controls(self):
+        for name, code in self.EXPECTED.items():
+            self.assertEqual(ie.KEYCODES[name], code, f"{name} code")
+
+    def test_lookup_is_case_insensitive(self):
+        dev = ie.InputDevice.__new__(ie.InputDevice)  # no device opened
+        self.assertEqual(dev._key_code("W"), 17)
+        self.assertEqual(dev._key_code("SPACE"), 57)
+        self.assertEqual(dev._key_code(19), 19)  # a raw code passes through
+
+    def test_unknown_key_raises(self):
+        dev = ie.InputDevice.__new__(ie.InputDevice)
+        with self.assertRaises(ie.UInputError):
+            dev._key_code("not-a-key")
+
+
+if __name__ == "__main__":
+    unittest.main()

Tools/tests/test_mapbox_buildings.py

@@ -0,0 +1,117 @@
+"""Tests for Geo/tools/mapbox_buildings.py — the pure merge logic.
+
+No network calls here: Tilequery responses are represented as the small dicts
+the API returns, and only the selection/comparison/formatting helpers are
+exercised. The live call is verified by running the tool.
+"""
+
+import json
+import os
+import sys
+import unittest
+
+ROOT = os.path.abspath(os.path.join(os.path.dirname(__file__), "..", ".."))
+sys.path.insert(0, os.path.join(ROOT, "Geo", "tools"))
+
+import mapbox_buildings as mb  # noqa: E402
+
+
+def feature(distance, height=None, min_height=0, type_="building", layer="building"):
+    props = {"tilequery": {"distance": distance, "layer": layer}}
+    if height is not None:
+        props["height"] = height
+    props["min_height"] = min_height
+    props["type"] = type_
+    return {"properties": props}
+
+
+class NearestBuildingTest(unittest.TestCase):
+    def test_picks_the_closest_building(self):
+        payload = {"features": [feature(6.0, 10.0), feature(1.0, 20.0)]}
+        best = mb.nearest_building(payload, max_distance=8.0)
+        self.assertEqual(best["height"], 20.0)
+
+    def test_ignores_hits_beyond_max_distance(self):
+        payload = {"features": [feature(20.0, 10.0)]}
+        self.assertIsNone(mb.nearest_building(payload, max_distance=8.0))
+
+    def test_ignores_other_layers(self):
+        payload = {"features": [feature(0.0, 10.0, layer="road")]}
+        self.assertIsNone(mb.nearest_building(payload, max_distance=8.0))
+
+    def test_no_features(self):
+        self.assertIsNone(mb.nearest_building({"features": []}, max_distance=8.0))
+
+
+class CompareTest(unittest.TestCase):
+    def test_match_within_half_a_metre(self):
+        self.assertEqual(mb.compare(14.5, "height tag", 14.2)[0], "match")
+
+    def test_close_within_two_metres(self):
+        verdict, delta = mb.compare(38.4, "levels x 3.2 m", 37.2)
+        self.assertEqual(verdict, "close")
+        self.assertAlmostEqual(delta, -1.2)
+
+    def test_disagree_beyond_two_metres(self):
+        verdict, delta = mb.compare(6.4, "GUESS: default 2 levels x 3.2 m", 3.0)
+        self.assertEqual(verdict, "disagree")
+        self.assertAlmostEqual(delta, -3.4)
+
+    def test_mapbox_only_when_we_have_nothing(self):
+        self.assertEqual(mb.compare(0.0, "height tag", 12.0)[0], "mapbox-only")
+
+    def test_ours_only_when_mapbox_returns_nothing(self):
+        self.assertEqual(mb.compare(12.0, "height tag", None)[0], "ours-only")
+
+    def test_non_building_is_excluded_from_comparison(self):
+        verdict, delta = mb.compare(0.0, "not a building volume (roof)", 3.0)
+        self.assertEqual(verdict, "non-building")
+        self.assertIsNone(delta)
+
+    def test_canopy_is_non_building(self):
+        verdict, _ = mb.compare(0.0, "not a building volume (canopy)", 3.0)
+        self.assertEqual(verdict, "non-building")
+
+
+class CentroidTest(unittest.TestCase):
+    def test_centroid_of_a_square(self):
+        lat, lon = mb.centroid_lat_lon(
+            [(34.0, -118.0), (34.0, -117.0), (35.0, -117.0), (35.0, -118.0)])
+        self.assertAlmostEqual(lat, 34.5)
+        self.assertAlmostEqual(lon, -117.5)
+
+
+class RenderTest(unittest.TestCase):
+    ARGS = type("A", (), {"radius": 25, "max_distance": 8.0, "only_diffs": False})()
+
+    def test_disagreements_sort_first(self):
+        rows = [
+            {"verdict": "match", "delta_m": 0.1, "way": 1, "name": "", "kind": "yes",
+             "osm_height_m": 10.0, "osm_source": "height tag", "mapbox_height_m": 10.1,
+             "mapbox_min_height_m": 0, "mapbox_type": "building",
+             "mapbox_distance_m": 0.0, "cached": True, "lat": 0, "lon": 0},
+            {"verdict": "disagree", "delta_m": -3.4, "way": 2, "name": "", "kind": "yes",
+             "osm_height_m": 6.4, "osm_source": "GUESS", "mapbox_height_m": 3.0,
+             "mapbox_min_height_m": 0, "mapbox_type": "building",
+             "mapbox_distance_m": 0.0, "cached": True, "lat": 0, "lon": 0},
+        ]
+        text = mb.render_markdown(rows, self.ARGS)
+        self.assertLess(text.index("way 2"), text.index("way 1"))
+
+    def test_never_contains_a_token(self):
+        rows = []
+        text = mb.render_markdown(rows, self.ARGS)
+        self.assertNotIn("access_token", text)
+        self.assertNotIn("sk.", text)
+
+
+class TokenTest(unittest.TestCase):
+    def test_explicit_token_wins(self):
+        self.assertEqual(mb.load_token("abc123"), "abc123")
+
+    def test_token_is_stripped(self):
+        self.assertEqual(mb.load_token("  abc123\n"), "abc123")
+
+
+if __name__ == "__main__":
+    unittest.main()

Tools/ue_build_review_map.py

@@ -236,7 +236,11 @@ try:
         # the plinth, which is what "portal detail" means here.
         ("hero-portals", unreal.Vector(hero_x + 100, -2250, 170), unreal.Vector(hero_x + 100, hero_y, 230)),
         # straight on from the north sidewalk; the building body spans Y -1443..+250
-        ("hero-facade-front", unreal.Vector(hero_x + 200, -3200, 420), unreal.Vector(hero_x, hero_y + 400, 760)),
+        # Level horizon: camera height == target height, so the elevation's
+        # verticals stay parallel. The old shot looked up ~4 deg from 4.2 m at a
+        # 7.6 m target, which converged the columns — the one thing an
+        # architectural elevation must not do (archviz: "straight verticals").
+        ("hero-facade-front", unreal.Vector(hero_x + 200, -3200, 760), unreal.Vector(hero_x, hero_y + 400, 760)),
         # oblique from the north-west, reading the colonnade in depth
         ("hero-facade-oblique", unreal.Vector(hero_x - 2200, -3400, 620), unreal.Vector(hero_x + 300, hero_y, 700)),
     ]
@@ -276,12 +280,14 @@ try:
         demo_shots = [
             # 14 m back so the 14.5 m elevation fits: at 2 m the camera sees only
             # the colonnade's underside.
-            ("demo-spawn-view", unreal.Vector(-13336, -3100, 420), unreal.Vector(-13336, 1300, 620)),
+            # Level horizon for the same reason: a block elevation is read by its
+            # verticals, and a pitched camera makes them lean.
+            ("demo-spawn-view", unreal.Vector(-13336, -3100, 620), unreal.Vector(-13336, 1300, 620)),
             # Street level, from the north sidewalk: the old camera sat at Y -400,
             # inside the facade body (which spans Y -1457..-200), so it looked at
             # the unlit back face. Y -2600 is on the sidewalk in front of the lit
             # elevation.
-            ("demo-street-level", unreal.Vector(-13420, -1650, 170), unreal.Vector(-13336, 1300, 400)),
+            ("demo-street-level", unreal.Vector(-13420, -1650, 170), unreal.Vector(-13336, 1300, 170)),
             # The designated mid-block crossing. Street arc length runs from the
             # west end (s=0 at X -27966 cm), so s=130.1 m is UE X -14956, not the
             # -24291 the old camera used (that is the s=36.6 crossing). Camera sits

Tools/ue_hero_facade_import.py

@@ -61,6 +61,16 @@ def measure_and_place():
     if asset is None:
         log(f"MISSING {DEST}/SM_HeroFacade")
         return
+    # Collision: complex-as-simple, not auto-generated convex hulls.
+    # The facade is 95 separate parts across 26 m; Unreal's auto hull generation
+    # wraps them in a few coarse hulls that bulged into the street (the QA wall
+    # probe went 0/35 -> 2/35 after trying it). Complex-as-simple makes the real
+    # triangles the simple collision, so line traces and capsule sweeps block on
+    # the actual wall — the same approach used for the terrain, for the same
+    # reason. The flag lives on the asset, so save it explicitly.
+    unreal.GigLineAssetTools.set_complex_collision_as_simple(asset, True)
+    saved = unreal.EditorAssetLibrary.save_loaded_asset(asset)
+    log(f"collision: {unreal.GigLineAssetTools.get_collision_complexity(asset)} (saved={saved})")
     box = asset.get_bounding_box()
     mn, mx = box.min, box.max
     log(f"SM_HeroFacade bounds cm: size=({mx.x - mn.x:.1f}, {mx.y - mn.y:.1f}, {mx.z - mn.z:.1f}) "

requirements-tools.txt

@@ -0,0 +1 @@
+requests>=2.28