Add a repeatable screenshot capture and compare smoke

Both capture helpers now accept --out=res://docs/screenshots, and
tools/check_screenshots.sh renders the staged set (using xvfb-run when headless)
before running screen_designs.py compare. Record the judge result: 7 match,
4 review, 0 diff. Headless 226/226 and the smoke both pass in a clean worktree.

TODO.md

@@ -1,9 +1,10 @@
 # TODO
 
 Godot 4.3 prototype. Latest release **v0.6.0** (Blender character/gear/prop library, baked AO, environment lift).
-Headless suite **222/222** plus **81** Python tooling tests; the session, PLAN-verb, crowd, emergency,
+Headless suite **227/227** plus **86** Python tooling tests; the session, PLAN-verb, crowd, emergency,
 timeline, audio, scenario-content, props, NPC-budget, movement, and windowed focus/radial smokes
-pass. Anonymous downloads are enabled on the host.
+pass. Anonymous downloads are enabled on the host. The realism pass is adopted (per-phase skyline
+panoramas, v2 surface tiles, retuned lighting); see `DONE.md` and `TODO.md` → Realism follow-ups.
 
 The scheduled presentation pass is complete (see `DONE.md`). The next scheduled pass is the
 graphics-quality work in [`docs/plan-graphics-v0.6.md`](docs/plan-graphics-v0.6.md).
@@ -14,13 +15,6 @@ graphics-quality work in [`docs/plan-graphics-v0.6.md`](docs/plan-graphics-v0.6.
 
 ## Visual alignment with rendered mockups
 
-The AI-rendered references in `docs/screens/designs/` (start menu, pause, settings,
-shift review, radial menu, HUD, scene views) describe the intended look of every
-screen. This pass reorganizes how generated images are stored, makes the game load
-the proposed interface/scene art from disk, and aligns the selection screens, HUD,
-and scene visuals with those mockups — verified with
-`tools/screen_designs.py compare` + `judge`.
-
 ### Storage restructure
 
 - [x] Decide the canonical runtime image root (`assets/images/` for UI/scene art): recorded in
@@ -64,8 +58,8 @@ and scene visuals with those mockups — verified with
 ### Verify against the mockups
 
 - [x] Regenerate the staged captures and run `screen_designs.py compare` (11 good, 0 bad; verified in a clean HEAD worktree).
-- [ ] Run `screen_designs.py judge` and clear every `diff` verdict (target `match`/`review`).
-- [ ] Add the capture + compare step to CI or a repeatable smoke so drift is caught early.
+- [x] Run `screen_designs.py judge` and clear every `diff` verdict (7 match, 4 review, 0 diff).
+- [x] Add the capture + compare step as a repeatable smoke so drift is caught early (`tools/check_screenshots.sh`).
 
 ## Fix mouse movement bug
 
@@ -75,128 +69,22 @@ and scene visuals with those mockups — verified with
 
 - [ ] Improve the visual appearance of in-game pop-ups (layout, button style, palette, icons, and text styling).
 
-## Realistic backgrounds, textures and scene references
+## Realism follow-ups (v0.6.1 candidates)
 
-Goal: replace the outdated flat skyline backdrop (`assets/textures/skyline.png`, black boxes
-with dot windows) and the flat-looking surface tiles with AI-generated, more realistic
-backgrounds and textures. Add a larger set of example 3D scene images as art direction, and
-measure the in-game result against that target with the screenshot tools. Plan:
-[`PLAN.md` → Visual Quality Direction → Realism pass](PLAN.md#realism-pass).
-
-**Rule for every step: never overwrite an existing image.** New outputs get new paths. When a
-path is taken, the tools pick the next free `-vN` suffix. Raw AI output stays on disk under
-`assets/textures/ai/v2/raw/` (gitignored like the other raw AI folders). Processed game-ready
-candidates go to `assets/textures/ai/game_ready/v2/`, a local pool where only the validated picks
-are tracked (ADR-0014). Scene references go to `docs/screens/concepts/`, and trial captures and
-reports to `docs/screens/realism/<run>/`.
-
-### Step 1 — Tooling (`tools/scene_concepts.py`)
-
-- [x] Add a catalogue of prompts in three groups: `scene` (16:9 example 3D game frames),
-      `backdrop` (4:1 skyline panoramas with transparent sky), and `texture` (seamless PBR
-      surface tiles). Each entry has a name, prompt, role and target path.
-- [x] `generate [--group] [--only] [--variants N]`: call the OpenRouter image API through
-      `generate_textures.generate_image` (key from the repo `.env`), save raw output, and never
-      overwrite (`next_free_path`). Print every file written.
-- [x] `process`: turn raw backdrops into 2048×512 RGBA strips that tile horizontally (edge
-      crossfade, sky made fully transparent, hard alpha for the alpha-scissor material). Turn raw
-      textures into seamless 1024² tiles (`asset_pipeline.make_seamless`) plus a normal map
-      (`make_normal_maps.normal_map`). Skip outputs that already exist.
-- [x] `audit`: run `asset_pipeline.audit_image` on the processed candidates (`backdrop` /
-      `tile` roles) and fail on any bad result.
-- [x] `realism`: for each trial capture, report the Pillow detail metrics (edge density,
-      contrast, colour spread, saturation) next to the matching concept image. Optionally ask a
-      vision model (`google/gemini-2.5-flash-lite`) for 0–10 realism scores (lighting,
-      materials, texture detail, backdrop, overall) with concrete fixes. Write a new JSON +
-      Markdown report per run.
-- [x] Unit tests (`tools/test_scene_concepts.py`): catalogue shape, the no-overwrite path
-      picker, backdrop/tile processing on synthetic images, metrics, and the judge payload/parse
-      (offline, no network).
-
-### Step 2 — Example 3D scene images
-
-- [x] Generate 3D-game-style example frames for every venue and time of day: Hollywood entrance
-      (morning, golden hour, rainy night), boulevard skyline view (day, dusk), Joke Shop alley
-      (evening, close-up of the door), studio stage door (night arrival), sidewalk material
-      close-up, entrance steps and podium, crowd-control barrier line, and a responder arrival
-      wide shot.
-- [x] Review the set and record the visual targets each frame sets (sky, haze, material detail,
-      backdrop depth) in the report.
-
-### Step 3 — Backgrounds (replace the outdated skyline)
-
-- [x] Generate skyline panoramas for day, dusk and night (lit windows): Hollywood/Los Angeles
-      mid-rise blocks, palm silhouettes, the hills on the horizon, a transparent sky, and a
-      straight-on view, in several variants each.
-- [x] Process them into `assets/textures/ai/game_ready/v2/skyline_{day,dusk,night}*.png`,
-      seamless horizontally for the 3× UV repeat around the backdrop ring. Strips are 2048×1024
-      (2:1, one UV repeat of the 400×60 m ring is about 133×60 m). 12 candidates, 11 audit
-      clean; `skyline_day-v3` misses the seam limit by 0.6. Variants 1–2 contain garbled
-      "Hollywood" lettering, so the prompt now forbids signs. Picks: `skyline_day-v4`,
-      `skyline_dusk-v3`, `skyline_night-v4`.
-
-### Step 4 — Textures
-
-- [x] Generate higher-detail seamless tiles: red brick facade, granite/limestone facade
-      (studio), sidewalk concrete pavers with joints, asphalt with aggregate, wet night asphalt,
-      stone steps, striped awning canvas, and stucco wall.
-- [x] Process them into 1024² game-ready tiles plus normal maps in
-      `assets/textures/ai/game_ready/v2/` and audit them (16 tiles + 16 normals, all good). The
-      `awning_canvas` seam crossfade smears the stripes at the tile edge; it needs a
-      stripe-aligned crop.
-
-### Step 5 — In-game trial captures (no game-code change)
-
-- [x] Add `src/test/capture_realism.gd`. It boots the Hollywood venue, captures a fixed shot
-      list (entrance day, boulevard/skyline day, boulevard night), and can swap textures at
-      runtime from `--skyline=` / `--brick=` / `--concrete=` / `--asphalt=` user arguments. The
-      swap finds materials by their current texture, so baseline and candidate frames use the
-      same camera. Writes to `user://screenshots/realism/<tag>/`.
-- [x] Capture the baseline (current assets) and the candidate set (v2 skyline + textures), and
-      copy them into `docs/screens/realism/<run>/{baseline,candidate}/`.
-
-### Step 6 — Compare against the realistic target
-
-- [x] Run `scene_concepts.py realism` on baseline and candidate. Record the metric deltas and the
-      vision scores, and note which candidate textures/backdrops win. Run
-      `docs/screens/realism/2026-11-01-v2/` (`report-v2.md`, `sheet.jpg`) gives these mean
-      judge scores: backdrop 2.6 → 3.6 (v2 day + night skyline) → **4.0** (v2 day + dusk
-      skyline for the Evening phase), texture detail 1.2 → 1.6–1.75, overall 1.6 → 2.0. Single
-      scores swing by ±1–2 between runs, so read them as trends. The `characters` score
-      moved from 3.0 to 1.0 with identical NPCs, which shows the noise.
-- [x] Note the remaining realism gaps (sky/fog, lighting, building geometry, NPC fidelity) as
-      follow-up tasks below.
-
-### Step 6b — Follow-ups from the 2026-11-01 realism report
-
-- [ ] Fix sidewalk overexposure: the concrete reads near-white in every day shot, while the
-      concepts keep the ground mid-grey. Lower the albedo tint or the sun energy, or add tonemap
-      exposure in `Materials.configure_environment`.
-- [ ] Make the Evening/Late phases darker and lit by practical lights (marquee, lamps,
-      windows), and add wet-asphalt roughness at night, as in the rain-night concept.
-- [ ] Choose the skyline per phase (day → `skyline_day`, Evening → `skyline_dusk`, Late →
-      `skyline_night`) and lower the fog density on the backdrop so the night windows show.
-- [ ] Raise the backdrop plane (60 m → ~90 m) or use 2 UV repeats so the skyline is not a
-      thin strip at the horizon.
-- [ ] Add facade depth (plinth, cornice, window reveals) and replace the blob trees and shrubs
-      with denser foliage meshes (Blender library follow-up).
-- [ ] Re-cut `awning_canvas` so its stripes align at the tile edge.
-- [ ] Capture shots from the Joke Shop and the studio too (add them to `capture_realism.gd` /
-      `SHOTS`).
-
-### Step 7 — Adopt the winners (after the in-flight normal-map/AO work is committed)
-
-- [x] Track the validated picks in place (ADR-0014). `game_ready/v2/*` is a gitignored local
-      pool; `.gitignore` un-ignores the skyline picks and the brick/pavers/asphalt (+ wet) tiles
-      and their normals. Never replace the existing `game_ready/` files.
-- [ ] Point `WorldBuilder.T_SKYLINE` at the chosen v2 skyline (separate day/night textures through
-      `set_night_mode`), and retune `albedo_color` for the realistic strip.
-- [ ] Switch `materials.gd` / `world_builder.gd` surface preloads to the chosen v2 tiles + normal
-      maps, keeping the current UV scales. Update `test_materials.gd` / `test_world.gd`.
-- [ ] Regenerate `docs/screenshots/` with `capture_screenshots.gd`, then run
-      `screen_designs.py compare` + `judge` and `scene_concepts.py realism`. There must be no
-      `diff` verdict regressions, and realism scores must not drop.
-- [ ] Update `README.md` (tool usage + gallery), `MEMORY.md` and `docs/architecture.md`.
+- [ ] Fixed ground exposure for the entrance view: it is still ~20 % brighter than the concept.
+      Either put the entrance in the building's shadow (sun yaw/elevation) or add a slight
+      per-view exposure so the shaded sidewalk reads mid-grey.
+- [ ] Make the flashlight read in the dark: the `06-night-flashlight` concept shows a visible
+      beam, but a Compatibility spot light only brightens the near wall. A cheap fake cone (an
+      additive mesh or a light-shaft quad) would sell it, and the night mockup expects it.
+- [ ] NPC skin/clothing still reads as low-poly next to the concepts (judge `characters` ≈ 0–1).
+      The Blender library has the budgets for one more detail pass (fingers, sleeves, faces).
+- [ ] The `screen_designs.py judge` default model (`google/gemini-2.5-flash-lite`) currently
+      fails with a provider "API key not valid" 400; the tool retries once. Re-check before the
+      next release and either pin a working model or document `--model`.
+- [ ] Add the two venue stages to the committed gallery (they are capture-only today) and give
+      the Joke Shop and studio their own geometry so their concept comparisons are geometric,
+      not just lighting.
 
 ## Future ideas (optional, not scheduled)