Add the real-location reference folder and provenance sidecar

2026-11-03 12:42:13 +01:00
1 parent c0ddce79e8
commit 4ed73fcc7b
@@ -8,8 +8,10 @@ Session memory for durable decisions, state, and gotchas. Keep concise, remove o
  not be mixed: licensed real-location photos (evidence of what a place looks like), generated
  concept boards (art-direction proposals with model/prompt/spend provenance), and build captures
  (proof the build matches). Per-venue boards go under `docs/screens/refs/<venue|block>/` with a
-  sidecar template (URL, author, licence, date, purpose, shipped vs development-only); generated
-  images stay out of `assets/` until picked, cropped, credited and audited. Every workstream now
+  `SIDECAR.md` per folder (photo table: file, subject, view, URL, author, licence, date, purpose,
+  shipped; plus redactions, derived-decision log and a table referencing the generated boards used
+  in the three-up). Generated frames stay in `docs/screens/concepts/`, never in `refs/`, and stay
+  out of `assets/` until picked, cropped, credited and audited. Every workstream now
  ends with a capture step that updates `README.md` plus the matching docs page, verified with
  `tools/check_screenshots.sh` and `python3 tools/check_docs.py`.
 - **Collider coverage gate (2026-11-03):** `WorldBuilder` sets `library_prop` metadata on every
@@ -142,9 +142,12 @@ Licensed photos are evidence of what a place looks like, generated boards are ar
 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,
+- [x] 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.
+      shipped or development-only. (`docs/screens/refs/README.md` defines the layout, naming,
+      licence and privacy gates and the three-way separation from concepts and captures;
+      `SIDECAR-TEMPLATE.md` carries the photo table, redaction/permission notes, derived-decision
+      log and the generated-board reference table. Linked from `docs/screens/README.md`.)
 - [ ] 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.
@@ -2,6 +2,7 @@

 Visual references and generated QA evidence for Gig Line.

+- [`refs/README.md`](refs/README.md) — licensed real-location photos, provenance sidecars and the licence/privacy rules
 - [`concepts/README.md`](concepts/README.md) — AI-assisted realism concept frames
 - [`designs/README.md`](designs/README.md) — screen-design mockups
 - [`../screenshots/README.md`](../screenshots/README.md) — committed game gallery
@@ -0,0 +1,86 @@
+# Real-location references
+
+Evidence of what the real places look like, kept separate from the two other image sets:
+
+| Folder | What it holds | Role |
+| --- | --- | --- |
+| `docs/screens/refs/` (this folder) | Licensed photographs and, where useful, measured notes | **Evidence**: proportions, signage, materials, lighting, street furniture |
+| [`../concepts/`](../concepts/README.md) | AI-generated art-direction frames | **Proposal**: colour, mood, detail density |
+| [`../../screenshots/`](../../screenshots/README.md) | Build captures | **Proof**: what the game actually renders |
+
+A generated frame never overrides a photograph for shape or signage. Where they disagree, the
+photo wins and the concept only informs palette and atmosphere.
+
+## Layout
+
+```
+docs/screens/refs/
+  README.md                 # this file
+  SIDECAR-TEMPLATE.md       # copy per folder
+  hollywood/                # 6840 Hollywood Blvd block
+    SIDECAR.md
+    *.jpg|png
+  joke-shop/                # 8433 Sunset Blvd block
+    SIDECAR.md
+  tv-studio/                # studio entrance reference set
+    SIDECAR.md
+  blocks/<block-id>/        # local map-development blocks (TODO: Local map development)
+    SIDECAR.md
+```
+
+One folder per venue or block, one `SIDECAR.md` per folder listing **every** image in it. Keep the
+folders flat; do not add sub-collections that the sidecar cannot describe.
+
+## Naming
+
+```
+<subject>-<view>-<source>-<YYYYMMDD>.<ext>
+el-capitan-entrance-day-wikimedia-20231102.jpg
+sunset-canopy-building-standard-ownphoto-20251103.jpg
+```
+
+Use lowercase words separated by hyphens, the camera view (`day`, `night`, `entrance`, `profile`,
+`across-street`), the source (`wikimedia`, `ownphoto`, `mapillary`), and the capture or download
+date. Never overwrite an existing file; add a new dated file instead
+(see [ADR-0014](../../adr/0014-runtime-image-root.md)).
+
+## Licence gate
+
+Only commit an image when redistribution is unambiguous:
+
+- **Own photography** — permitted, with the photographer named in the sidecar.
+- **CC0 / public domain** — preferred.
+- **CC BY** — allowed with the attribution text recorded here and in
+  [`../../../CREDITS.md`](../../../CREDITS.md).
+- **CC BY-SA** — allowed only after a share-alike review of the derived textures and meshes; record
+  the decision in the sidecar before use.
+- **Rejected**: Street View, scraped social media, unlicensed commercial imagery, and AI upscales of
+  unknown originals.
+
+Anything that fails this gate may still be used locally for study, but it stays in `tmp/` and never
+enters the repository or a build.
+
+## Privacy gate
+
+Blur or crop identifiable faces, minors, licence plates, screens and private interiors; do not
+photograph behind closed doors; obtain property permission where a venue requires it. The image
+committed here is the redacted copy, not the original.
+
+## How the folder is used
+
+- Build the venue **three-up boards** (photo | concept | current capture) for the review verdicts.
+- Link the board from the venue map document (`docs/hollywood-boulevard-map.md`,
+  `docs/joke-shop-map.md`) and from the local-map block notes.
+- Cite the sidecar when a texture, proportion or signage decision is derived from a photo.
+- Refresh the board when a venue change makes an old reference misleading, and note the change in
+  the sidecar.
+
+## Checks
+
+- Every image in a folder must be listed in that folder's `SIDECAR.md`.
+- The sidecar must name the licence and attribution for each entry.
+- `python3 tools/check_docs.py` must pass after adding or moving a file (each tracked image has to
+  be linked from its folder README).
+- Generated images belong in `../concepts/`, not here.
+
+Copy [`SIDECAR-TEMPLATE.md`](SIDECAR-TEMPLATE.md) into a new folder and fill it in.
@@ -0,0 +1,54 @@
+# Sidecar — `<venue or block>`
+
+Copy this file into a new folder as `SIDECAR.md` and fill in every field. One row per image, no
+exceptions; an image that is not listed here must not be committed.
+
+## Collection
+
+| Field | Value |
+| --- | --- |
+| Venue / block | e.g. `El Capitan Entertainment Centre block, 6840 Hollywood Blvd` |
+| Folder | `docs/screens/refs/hollywood/` |
+| Collected by | name or agent session |
+| Date range | first and last capture/download date |
+| Intended use | e.g. venue three-up board, facade materials, signage reference |
+| Shipped? | no — reference only (state the exception if a derived texture ships) |
+
+## Photographs
+
+| File | Subject | View | Source URL | Author | Licence | Captured | Purpose | Shipped |
+| --- | --- | --- | --- | --- | --- | --- | --- | --- |
+| `el-capitan-entrance-day-wikimedia-20231102.jpg` | El Capitan facade | day, straight on | https://commons.wikimedia.org/… | Jane Doe | CC BY 4.0 | 2023-11-02 | column spacing, banner size, stone joints | no |
+| `sunset-canopy-night-ownphoto-20251103.jpg` | Joke Shop canopy | night, three-quarter | — (own capture) | project | project-owned | 2025-11-03 | canopy depth, bulb rhythm | no |
+
+Licence options: `project-owned`, `CC0`, `CC BY 4.0`, `CC BY-SA 4.0 (reviewed)`. Add the exact
+attribution string for CC BY / CC BY-SA in the `Author` or a note below.
+
+## Redactions and permissions
+
+- Faces / plates / screens: state what was blurred or cropped and where.
+- Property permission: name the venue contact or state "not required for public frontage".
+- Interiors or staff: confirm none are included, or describe the permission.
+
+## What was derived from this set
+
+| Decision | Evidence | Where it landed |
+| --- | --- | --- |
+| e.g. six-column spacing kept at 2.4 m | photo 1, measured against door width | `docs/hollywood-boulevard-map.md` |
+| e.g. banner red sampled to `#8a1f24` | photo 1 + photo 2 | `docs/screens/refs/hollywood/` notes, facade kit |
+
+## Generated boards used with this set
+
+Generated frames live in [`../../concepts/`](../../concepts/README.md); reference them here so the
+three-up sheet is reproducible.
+
+| Board | Path | Model | Prompt / seed | Generated | Spend |
+| --- | --- | --- | --- | --- | --- |
+| Hollywood entrance day | `docs/screens/concepts/hollywood_boulevard/hollywood_boulevard_entrance_day.png` | `openai/gpt-5-image-mini` | `scene_concepts.py generate --group scene --only hollywood_boulevard_entrance_day` | 2026-11-01 | ~$0.01 |
+
+## Notes
+
+- Anything that is not committed (development-only study images) stays in `tmp/` and is not listed
+  as a file here, but may be described if it informed a decision.
+- When an image is replaced, add the new file rather than overwriting the old one, and keep both
+  rows until the old file is deleted from the repository.