Plan recent-photo tooling and reference-anchored generation

TODO.md

@@ -339,6 +339,24 @@ facades and AI-assisted composition. This is an unversioned development track, n
 
 ### Reference imagery
 
+**Recent-photo research (2026-11-03):** Commons geosearch around 34.10118/-118.34009 (500 m) plus
+category/date sorting shows usable imagery from the last 12 months: Dolby Theatre billboards
+(2026-09-30, CC0, 6 frames), Dolby street level and a fresh Walk of Fame star (2026-07-17, CC0),
+a Michael Jackson impersonator at the El Capitan frontage (2026-02-25, CC BY-SA 4.0), the Celia
+Cruz Square marker and a 2025-09-28 star series (CC0), and a Thunderbolts premiere (2025-04-28,
+CC BY-SA 2.0). No recent frame shoots the El Capitan facade straight-on in daylight; the best
+facade evidence is still the 2009 CC BY frame. The 8 downloaded candidates are in
+`tmp/research/elcapitan-2026/` (gitignored) with `meta.json`; nothing was committed.
+
+- [ ] Wire `scene_concepts.py refboard`: list/fetch Commons files by `titles=`, `geosearch` or
+      category with date and licence sorting, write the `SIDECAR.md` rows and the folder README
+      rows automatically (User-Agent, batched `titles=`, 3–4 s spacing to avoid HTTP 429; date-only
+      fetch into `tmp/` by default, committed copies require the licence gate).
+- [ ] Add a `--max-age-months` filter (default 12) and a `--must-reuse` mode that matches the
+      folder's existing sidecar entries so a refresh only reports what changed.
+- [ ] Research-diff step: keep the last-12-months board as the "current reality" evidence and the
+      older photos as the geometry evidence, labelled per photo; no sidecar date field needs to
+      change, only the purpose column.
 - [ ] Write a reference shot list per block: facade materials, windows, signage, rooflines,
       street furniture, curb cuts and lighting.
 - [ ] Download and catalogue reference images from Wikimedia Commons, local/own photography or
@@ -350,7 +368,8 @@ facades and AI-assisted composition. This is an unversioned development track, n
       template from the 3D review §E, and link it from the venue map documents.
 - [ ] Define the photoreal target and a material-derivation workflow (albedo/normal/roughness,
       AO, weathering) that matches the existing Compatibility renderer (`texture-workflow`,
-      `materials`, `lookdev`).
+      `materials`, `lookdev`), with the recent 2026 street frames as the current-reality reference
+      and the 2009 facade frame as the geometry reference.
 
 ### Geometry and AI-assisted composing
 
@@ -365,6 +384,13 @@ facades and AI-assisted composition. This is an unversioned development track, n
 - [ ] Run the assisted Blender pipeline end to end on the first block (OSM import → `inspect` →
       retopo/UV assist → atlas → `audit`), and document the exact commands in
       `docs/asset-tooling.md`.
+- [ ] Building-appearance realism pass, measured against the reference set: bring the masonic
+      facade's material response (limestone value/roughness, joint lines, weathering streaks),
+      the banner/canopy and marquee materials, and the night emissive balance to the level of the
+      2009 facade photo and the 2026 street frames; capture before/after and record each delta.
+- [ ] Upgrade the facade from flat material bands to photoreal detail: either texture-projected
+      detail (Path B below) or AI-generated material tiles derived from the facade photo (with
+      provenance), then verify texel density, tiling and the night look.
 - [ ] Integrate the result behind `WorldBuilder.VENUE_SPECS` with colliders, navigation obstacles,
       occlusion and the existing day/night materials.
 
@@ -373,9 +399,21 @@ facades and AI-assisted composition. This is an unversioned development track, n
 *Skill route: `lookdev`, `lighting`, `environment-artist`, `texture-workflow`; tooling:
 `tools/scene_concepts.py`, `tools/asset_pipeline.py`, `tools/screen_designs.py`.*
 
+**Tool plan for reference-anchored generation (plan first, implement after this section's review):**
+
+- [ ] Add `scene_concepts.py generate --reference <photo.png>`: attach a licence-cleared real photo
+      as a source image to the OpenRouter image request (image-edit/image-to-image endpoint), with
+      a prompt suffix that preserves the photographed facade geometry ("keep the building's column
+      count, spacing, band heights and sign placement exactly"). Record the reference file, its
+      licence and the model/prompt/spend in the sidecar.
+- [ ] Extend `generate_textures.generate_image()` with an optional `reference_url` (base64 data URL
+      of the photo) and a `strength` argument; keep every existing call signature unchanged and
+      gate the new path behind the reference being licence-cleared in the sidecar.
+- [ ] Add a sidecar-driven variant pass: for each real photo, generate day, night and weathered
+      variants of the same framing so the concept board stays comparable with the photo board.
 - [ ] Generate facade, street and signage concept frames for the target block
-      (`scene_concepts.py generate`), commit only the selected frames, and record model, prompt and
-      spend in the block sidecar.
+      (`scene_concepts.py generate --reference ...`), commit only the selected frames, and record
+      model, prompt, spend **and source photo** in the block sidecar.
 - [ ] Derive palette, lighting and material targets from the real-photo board and the generated
       concepts, and record the deltas the facade kit has to close.
 - [ ] Generate signage, awning and poster texture candidates with `asset_pipeline.py`; run the
@@ -440,9 +478,11 @@ reference-image licence and privacy gates above rather than replacing them.
 - [ ] **Path A — Reference and QA (lowest risk):** render the splat from game camera poses and
       compare it with the realism captures; derive dimensions, signage placement, facade rhythm
       and material colours. No splat data reaches the runtime.
-- [ ] **Path B — Texture derivation:** project splat renders onto the facade kit to produce
-      albedo, normal, roughness and AO candidates; de-light and bake them (`texture-workflow`),
-      then verify UV scale, tiling and readability under the Compatibility renderer.
+- [ ] **Path B — Texture derivation:** project splat renders **or reference photos** onto the
+      facade kit to produce albedo, normal, roughness and AO candidates; de-light and bake them
+      (`texture-workflow`), then verify UV scale, tiling and readability under the Compatibility
+      renderer. Deriving directly from a committed reference photo requires its licence to allow
+      derived works and a `CREDITS.md` entry; CC BY-SA sources stay out unless reviewed.
 - [ ] **Path C — Mesh proxy:** extract a mesh from the splat or dense reconstruction, retopo and
       dress it in Blender (`retopology`, `prop-artist`), assign LODs (`lod-pipeline`), and keep it
       inside the venue triangle/material budgets with mesh-based colliders (`collision-proxy`).