Plan reference imagery, generated boards and per-section captures

TODO.md

@@ -14,7 +14,8 @@ The MIT Blender skill pack lives locally at `.agents/skills/blender-skills/` (gi
 ## 3D model re-evaluation
 
 Goal: re-judge every shipped 3D asset against the newly available Blender skill guidance, rank
-the real gaps, and fix only what the rankings justify. This is an unversioned development track:
+the real gaps, and fix only what the rankings justify. Evidence comes from three separate sources:
+licensed real-location photos, generated concept boards, and build captures. This is an unversioned development track:
 it must not change the `npc_base` contract, the renderer or the 0.10.0 release candidate.
 
 Scope: 8 library characters (`npc_casual`, `npc_jacket`, `npc_coat`, `npc_vest`, `npc_dress`,
@@ -78,6 +79,12 @@ except the rebuilt assets themselves.
       `hair-groom` guidance; decide explicitly whether cloth simulation stays out of scope.
 - [ ] Fix only the ranked P0/P1s, one asset family per commit; refresh the comparison sheet and
       re-run `inspect`, `audit`, `fit` and `npc_proportions.py` after each fix.
+- [ ] Build a licensed real-photo reference board for crowd variety (ages, builds, hair, outer
+      layers) and record what was adopted; reference only, never traced or repainted.
+- [ ] Generate a face/hand concept board for the highest-ranked P1 and compare it with the 0.9.4
+      baseline before rebuilding anything; keep it development-only and record model and prompt.
+- [ ] After each accepted fix, capture front/three-quarter/profile comparisons, add them to the
+      review sheet, and refresh the README character row.
 - [ ] `qa-review` sign-off: a ship/no-ship verdict per variant with accepted limits recorded.
 
 ### C. Gear and prop re-evaluation
@@ -96,6 +103,13 @@ except the rebuilt assets themselves.
       sedan at day and late; confirm the flashlight stays a tight spot with no beam geometry.
 - [ ] Collision: verify every prop collider and navigation obstacle matches its silhouette and
       add the missing `collision-proxy` shapes where walking is blocked.
+- [ ] Build a real-photo comparison for street furniture (bollard, bench, bin, hydrant, planter,
+      lamp) and rank the silhouette and proportion mismatches.
+- [ ] Rebuild only the mismatched pieces through the assisted Blender pipeline
+      (`blender_assets.py inspect` → scripted retopo/UV assist → atlas → `audit`/`fit`); document
+      the exact commands in `docs/asset-tooling.md`.
+- [ ] Refresh `sheet_props.jpg`/`sheet_npc_gear.jpg`, the README asset rows and
+      `docs/blender_previews/README.md` after the rebuilds.
 - [ ] Exit: a prop/gear capture sheet, budgets and collision checks pass with no unreviewed asset.
 
 ### D. Venue and camera re-evaluation
@@ -111,10 +125,43 @@ except the rebuilt assets themselves.
       navigation obstacles and readable storytelling clusters.
 - [ ] Camera height: decide 1.7 m gameplay framing vs the ~1.55 m concept frames using
       `camera-cinematography`, and record the decision instead of leaving the mismatch open.
+- [ ] Build the venue three-up boards (real photo | generated concept | current capture) and
+      attach them to `docs/hollywood-boulevard-map.md` and `docs/joke-shop-map.md`.
+- [ ] Use the generated concept lighting and palette as the target for the `lighting`/`lookdev`
+      pass, and record the deviations that stay accepted.
+- [ ] After the pass, regenerate the venue captures and update README plus both venue documents.
 - [ ] Hooded/winter portrait: close the deferred close-up by staging a types 5–7 capture
       (`--portrait-type`) or adding a scenario spawn that provides one.
 
-### E. Gates and documentation
+### E. Reference images, concept boards and screenshots
+
+*Skill route: `lookdev`, `lighting`, `environment-artist`, `qa-review`; tooling:
+`tools/scene_concepts.py`, `tools/screen_designs.py`, `tools/asset_pipeline.py`.*
+
+Licensed photos are evidence of what a place looks like, generated boards are art-direction
+proposals, and captures are proof that the build matches. Keep the three labelled and separate,
+and never ship a generated or downloaded image without provenance.
+
+- [ ] Create `docs/screens/refs/` with a README and a sidecar template: source URL, author,
+      licence/attribution, capture or generation date, what it is evidence for, and whether it is
+      shipped or development-only.
+- [ ] Collect licence-cleared real-location photos for each venue (Wikimedia Commons, own captures,
+      and Mapillary only where its licence allows) into per-venue boards there. No Street View,
+      no scraped social media; link each board from its venue map doc.
+- [ ] Generate one concept board per venue with `tools/scene_concepts.py generate` (palette, facade
+      rhythm, lighting), keep raw output gitignored, commit only the selected board, and record the
+      model, prompt and spend in the sidecar.
+- [ ] Build a three-up sheet per venue (real photo | generated concept | current build capture) and
+      use it as the reference for the character, prop and venue verdicts.
+- [ ] Apply the screenshot rule to every workstream: each accepted fix updates the relevant row in
+      `README.md` plus the matching docs page (`docs/blender_previews/README.md`,
+      `docs/screenshots/README.md`, `docs/3d-model-review.md` or the venue map doc).
+- [ ] Re-run `tools/check_screenshots.sh` and `python3 tools/check_docs.py` after gallery changes
+      and record both results in the handoff.
+- [ ] Keep AI-generated images out of `assets/` until they are picked, cropped, credited and (for
+      textures) audited; `CREDITS.md` and ADR-0015 still govern provenance.
+
+### F. Gates and documentation
 
 - [x] Add the measurable checks the review needs (texel density, weight/pose sanity, collider
       coverage, LOD/impostor check) as stdlib or GDScript gates where possible; CI stays offline.
@@ -209,6 +256,8 @@ must inherit the reviewed face/hand/gear baseline instead of multiplying whateve
       hood/cup; prototype sheet committed.)
 - [ ] Re-derive the four approved specs against the re-evaluated character baseline (face, hands,
       proportions, gear offsets) so the new variants do not reintroduce the gaps the review found.
+- [ ] Generate the four variants through the assisted pipeline (procedural generator → `inspect` →
+      `audit`/`fit`) and capture the result before committing any of them.
 - [ ] Add the four approved specs to `CHARACTERS`, build and commit their GLBs/AO maps, and
       update the manifest with roles and tint data. Build only the new assets, never a no-op full
       rebuild, and remember that `export_filter="all_resources"` packs committed GLBs into the
@@ -217,6 +266,11 @@ must inherit the reviewed face/hand/gear baseline instead of multiplying whateve
       tests for repeatability and duplicate avoidance (`godot-export` contract check included).
 - [ ] Rebuild and verify gear fit for every new variant (`blender_assets.py fit` plus the runtime
       gear checks) and re-run `inspect` on the four new GLBs.
+- [ ] Build the crowd-variety reference board (licensed street-crowd photos plus AI proposals) and
+      compare it with the approved Blender prototypes before building; keep proposals
+      development-only and record them in `docs/npc-model-sourcing.md`.
+- [ ] Capture the four new variants in the neutral baseline and a portrait set, add the rows to
+      `docs/npc-visual-review.md` and the README character row when they land.
 
 ### QA and release
 
@@ -266,10 +320,12 @@ facades and AI-assisted composition. This is an unversioned development track, n
 - [ ] 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
-      other clearly licensed sources; record author, licence and attribution. Do not use
-      unlicensed Street View or scraped commercial imagery.
+      other clearly licensed sources; record author, licence and attribution with the §E sidecar
+      template. Do not use unlicensed Street View or scraped commercial imagery.
 - [ ] Separate development-only references from shipped textures; commit only images with clear
       redistribution rights and keep the rest under `tmp/` or the ignored reference folders.
+- [ ] Build the per-block real-photo board under `docs/screens/refs/<block>/` using the sidecar
+      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`).
@@ -284,12 +340,28 @@ facades and AI-assisted composition. This is an unversioned development track, n
 - [ ] Build a reusable photoreal facade kit (window bays, cornices, storefronts, awnings, signage)
       with `environment-artist`/`hard-surface`/`geometry-nodes` so buildings share materials and
       stay inside the venue triangle/material budgets.
-- [ ] Add an AI-assisted composition step for palette, facade rhythm and reference boards; record
-      the model, prompt and output, and keep human review as the acceptance gate. AI output must
-      not be treated as licensed map data or shipped without provenance.
+- [ ] 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`.
 - [ ] Integrate the result behind `WorldBuilder.VENUE_SPECS` with colliders, navigation obstacles,
       occlusion and the existing day/night materials.
 
+### Generated location imagery
+
+*Skill route: `lookdev`, `lighting`, `environment-artist`, `texture-workflow`; tooling:
+`tools/scene_concepts.py`, `tools/asset_pipeline.py`, `tools/screen_designs.py`.*
+
+- [ ] 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.
+- [ ] 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
+      role audit and the `CREDITS.md` provenance check before anything is used in the kit.
+- [ ] Compare generated concepts against the licensed photos: where they disagree, the photos win
+      for shape and the generated board only informs colour, mood and detail density. Human review
+      stays the acceptance gate, and AI output is never treated as licensed map data.
+
 ### Gaussian splatting evaluation: photo intake and provenance
 
 Gaussian splatting is evaluated as a photo-driven pipeline: licensed or permissioned photos
@@ -384,6 +456,10 @@ reference-image licence and privacy gates above rather than replacing them.
       the stylized fallback available.
 - [ ] Run the venue triangle/mesh budget, navigation and collider checks, plus day/night capture
       comparisons.
+- [ ] Capture day/night gallery frames of the new block and add before/after rows to `README.md`
+      and the venue map documents.
+- [ ] Re-run `tools/check_screenshots.sh` after the map swap so the 21-shot gallery reflects the
+      new geometry, and refresh the `docs/screens/refs/` three-up sheets.
 - [ ] Update `docs/architecture.md`, the venue map documents, `docs/asset-tooling.md`,
       `docs/development-status.md` and `CHANGELOG.md` when the pipeline ships or a source is
       rejected.
@@ -408,6 +484,15 @@ task, not on a schedule.
       corrected on 2026-11-03); add a documentation check or grep note only if the same class of
       drift returns.
 
+### Reference and generated imagery upkeep
+
+- [ ] Keep `docs/screens/refs/` sidecars, concept-board records and `CREDITS.md` in sync whenever an
+      image is added, replaced or dropped, including the model/prompt for generated boards.
+- [ ] Run `python3 tools/check_docs.py` after any gallery or reference-board edit so every tracked
+      image stays linked from its folder README.
+- [ ] Delete or ignore development-only photos and raw generations once a board is committed; the
+      repository carries the picks and their provenance, not the working set.
+
 ### Blender skills upkeep
 
 - [ ] Re-check the installed Blender pack (`version.json`) when updating it and record the version
@@ -594,8 +679,11 @@ order. Only a release-blocking defect from those tracks may enter this milestone
 
 - [ ] Update `README.md`, `PLAN.md`, `docs/architecture.md`, ADRs, `docs/development-status.md`,
       `docs/getting-started.md`, `docs/smoke-checklist.md`, `CHANGELOG.md` and this roadmap.
-- [ ] Regenerate the full screenshot gallery and realism baselines after content lock; run
-      `check_screenshots.sh` and the pinned vision judge, recording model/spend/verdicts.
+- [ ] Regenerate the full screenshot gallery and realism baselines from the release-candidate
+      build (not the dev tree) after content lock; run `check_screenshots.sh` and the pinned vision
+      judge, recording model/spend/verdicts, and refresh the README and venue-doc images.
+- [ ] Include the reference/concept boards and the updated asset sheets in the release docs, and
+      verify every README and docs-page image resolves from the tagged build.
 - [ ] Run the manual smoke checklist on every target and attach/link the release-candidate evidence.
 - [ ] Verify the tutorial/campaign/help text at maximum font scale and with the longest strings.
 - [x] Remove or archive stale plans/notes and confirm no contradictory version/status claims remain.