From 4ed73fcc7bec8f789f90664eeb7535ea91be9a57 Mon Sep 17 00:00:00 2001 From: Zwitschi Date: Tue, 3 Nov 2026 12:42:13 +0100 Subject: [PATCH] Add the real-location reference folder and provenance sidecar --- MEMORY.md | 6 +- TODO.md | 7 ++- docs/screens/README.md | 1 + docs/screens/refs/README.md | 86 +++++++++++++++++++++++++++ docs/screens/refs/SIDECAR-TEMPLATE.md | 54 +++++++++++++++++ 5 files changed, 150 insertions(+), 4 deletions(-) create mode 100644 docs/screens/refs/README.md create mode 100644 docs/screens/refs/SIDECAR-TEMPLATE.md diff --git a/MEMORY.md b/MEMORY.md index 73d6291..4c4fac9 100644 --- a/MEMORY.md +++ b/MEMORY.md @@ -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//` 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 diff --git a/TODO.md b/TODO.md index d59f67a..2f21ef5 100644 --- a/TODO.md +++ b/TODO.md @@ -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. diff --git a/docs/screens/README.md b/docs/screens/README.md index 05460ba..b87deaf 100644 --- a/docs/screens/README.md +++ b/docs/screens/README.md @@ -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 diff --git a/docs/screens/refs/README.md b/docs/screens/refs/README.md new file mode 100644 index 0000000..552d19b --- /dev/null +++ b/docs/screens/refs/README.md @@ -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// # 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 + +``` +---. +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. diff --git a/docs/screens/refs/SIDECAR-TEMPLATE.md b/docs/screens/refs/SIDECAR-TEMPLATE.md new file mode 100644 index 0000000..7ebaa3e --- /dev/null +++ b/docs/screens/refs/SIDECAR-TEMPLATE.md @@ -0,0 +1,54 @@ +# Sidecar — `` + +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.