Add documentation folder READMEs and visual previews

Create an index README in docs/ and every tracked docs subfolder, with relative
image galleries for Blender previews, screen designs, screenshots and concepts.
Generated realism-run READMEs were also created on disk but remain gitignored.
Validate all Markdown/image links.

README.md

@@ -106,6 +106,7 @@ Full setup, every run/test/smoke command, and the controls table are in
 - [`DONE.md`](DONE.md) — Completed task sections.
 - [`MEMORY.md`](MEMORY.md) — Persistent session notes.
 - [`CHANGELOG.md`](CHANGELOG.md) — User-facing changes by version.
+- [`docs/README.md`](docs/README.md) — Documentation index and visual previews.
 - [`docs/architecture.md`](docs/architecture.md) — arc42-style architecture documentation.
 - [`docs/gameplay.md`](docs/gameplay.md) — Gameplay systems, venues, and the escalation model.
 - [`docs/tutorial.md`](docs/tutorial.md) — First-shift tutorial beats and rules.

docs/README.md

@@ -0,0 +1,31 @@
+# Gig Line Documentation
+
+This folder holds the project documentation, visual references and generated QA evidence.
+
+## Start here
+
+- [`../PLAN.md`](../PLAN.md) — product and game-design plan
+- [`gameplay.md`](gameplay.md) — controls, venues and escalation
+- [`tutorial.md`](tutorial.md) — first-shift tutorial beats
+- [`architecture.md`](architecture.md) — arc42 system architecture
+- [`getting-started.md`](getting-started.md) — setup, run/test commands and controls
+- [`asset-tooling.md`](asset-tooling.md) — image/model pipelines and screenshot gates
+- [`development-status.md`](development-status.md) — implemented features and current gaps
+- [`smoke-checklist.md`](smoke-checklist.md) — manual verification
+- [`RELEASING.md`](RELEASING.md) — export, CI and publishing workflow
+- [`adr/README.md`](adr/README.md) — architecture decisions
+
+## Visual references
+
+- [`screens/README.md`](screens/README.md) — concepts, designs, screenshots and realism runs
+- [`blender_previews/README.md`](blender_previews/README.md) — character/gear/prop previews
+- [`screenshots/README.md`](screenshots/README.md) — committed game gallery
+
+## Quick preview
+
+| Reference | Screenshot |
+| --- | --- |
+| Venue design | <img src="screens/designs/venue_overview.png" width="320" alt="Venue overview design"> |
+| Current entrance | <img src="screenshots/01-venue-overview.png" width="320" alt="In-game venue overview"> |
+| Character sheet | <img src="blender_previews/sheet_npc.jpg" width="320" alt="NPC character sheet"> |
+| Prop sheet | <img src="blender_previews/sheet_props.jpg" width="320" alt="Prop asset sheet"> |

docs/adr/README.md

@@ -0,0 +1,20 @@
+# Architecture Decision Records
+
+Each ADR records the context, decision, consequences and alternatives for a durable architecture choice.
+
+## Decisions
+
+- [0001-venue-driven-simulation-architecture](0001-venue-driven-simulation-architecture.md)
+- [0002-de-escalation-first-escalation-model](0002-de-escalation-first-escalation-model.md)
+- [0003-explicit-access-verification-system](0003-explicit-access-verification-system.md)
+- [0004-local-single-player-first](0004-local-single-player-first.md)
+- [0005-event-based-incident-recording](0005-event-based-incident-recording.md)
+- [0006-godot-4-gdscript](0006-godot-4-gdscript.md)
+- [0007-locomotion-and-input-layers](0007-locomotion-and-input-layers.md)
+- [0008-cone-focus-and-head-ring](0008-cone-focus-and-head-ring.md)
+- [0009-radial-action-menu](0009-radial-action-menu.md)
+- [0010-procedural-npc-presentation](0010-procedural-npc-presentation.md)
+- [0011-aim-free-selection-and-precision-walk](0011-aim-free-selection-and-precision-walk.md)
+- [0012-surface-materials-and-generated-props](0012-surface-materials-and-generated-props.md)
+- [0013-blender-authored-npc-characters](0013-blender-authored-npc-characters.md)
+- [0014-runtime-image-root](0014-runtime-image-root.md)

docs/blender_previews/README.md

@@ -0,0 +1,57 @@
+# Blender Previews
+
+Committed contact sheets and local Blender renders for the character, gear and prop library. Individual PNGs are development previews and are gitignored; the sheets are tracked.
+
+## Image previews
+
+| Preview | File |
+| --- | --- |
+| <img src="a_frame_sign.png" width="280" alt="a_frame_sign.png"> | [`a_frame_sign.png`](a_frame_sign.png) |
+| <img src="backpack.png" width="280" alt="backpack.png"> | [`backpack.png`](backpack.png) |
+| <img src="beanie.png" width="280" alt="beanie.png"> | [`beanie.png`](beanie.png) |
+| <img src="bench.png" width="280" alt="bench.png"> | [`bench.png`](bench.png) |
+| <img src="bollard.png" width="280" alt="bollard.png"> | [`bollard.png`](bollard.png) |
+| <img src="camera.png" width="280" alt="camera.png"> | [`camera.png`](camera.png) |
+| <img src="cap.png" width="280" alt="cap.png"> | [`cap.png`](cap.png) |
+| <img src="clipboard.png" width="280" alt="clipboard.png"> | [`clipboard.png`](clipboard.png) |
+| <img src="crowd_barrier.png" width="280" alt="crowd_barrier.png"> | [`crowd_barrier.png`](crowd_barrier.png) |
+| <img src="cup.png" width="280" alt="cup.png"> | [`cup.png`](cup.png) |
+| <img src="double_door.png" width="280" alt="double_door.png"> | [`double_door.png`](double_door.png) |
+| <img src="fire_hydrant.png" width="280" alt="fire_hydrant.png"> | [`fire_hydrant.png`](fire_hydrant.png) |
+| <img src="firefighter_helmet.png" width="280" alt="firefighter_helmet.png"> | [`firefighter_helmet.png`](firefighter_helmet.png) |
+| <img src="flashlight.png" width="280" alt="flashlight.png"> | [`flashlight.png`](flashlight.png) |
+| <img src="handrail.png" width="280" alt="handrail.png"> | [`handrail.png`](handrail.png) |
+| <img src="hood.png" width="280" alt="hood.png"> | [`hood.png`](hood.png) |
+| <img src="lanyard.png" width="280" alt="lanyard.png"> | [`lanyard.png`](lanyard.png) |
+| <img src="marquee.png" width="280" alt="marquee.png"> | [`marquee.png`](marquee.png) |
+| <img src="newspaper_box.png" width="280" alt="newspaper_box.png"> | [`newspaper_box.png`](newspaper_box.png) |
+| <img src="npc_casual.png" width="280" alt="npc_casual.png"> | [`npc_casual.png`](npc_casual.png) |
+| <img src="npc_coat.png" width="280" alt="npc_coat.png"> | [`npc_coat.png`](npc_coat.png) |
+| <img src="npc_dress.png" width="280" alt="npc_dress.png"> | [`npc_dress.png`](npc_dress.png) |
+| <img src="npc_firefighter.png" width="280" alt="npc_firefighter.png"> | [`npc_firefighter.png`](npc_firefighter.png) |
+| <img src="npc_guard.png" width="280" alt="npc_guard.png"> | [`npc_guard.png`](npc_guard.png) |
+| <img src="npc_hoodie.png" width="280" alt="npc_hoodie.png"> | [`npc_hoodie.png`](npc_hoodie.png) |
+| <img src="npc_jacket.png" width="280" alt="npc_jacket.png"> | [`npc_jacket.png`](npc_jacket.png) |
+| <img src="npc_vest.png" width="280" alt="npc_vest.png"> | [`npc_vest.png`](npc_vest.png) |
+| <img src="palm_tree.png" width="280" alt="palm_tree.png"> | [`palm_tree.png`](palm_tree.png) |
+| <img src="phone.png" width="280" alt="phone.png"> | [`phone.png`](phone.png) |
+| <img src="planter_box.png" width="280" alt="planter_box.png"> | [`planter_box.png`](planter_box.png) |
+| <img src="protest_sign.png" width="280" alt="protest_sign.png"> | [`protest_sign.png`](protest_sign.png) |
+| <img src="radio.png" width="280" alt="radio.png"> | [`radio.png`](radio.png) |
+| <img src="round_planter.png" width="280" alt="round_planter.png"> | [`round_planter.png`](round_planter.png) |
+| <img src="scba_tank.png" width="280" alt="scba_tank.png"> | [`scba_tank.png`](scba_tank.png) |
+| <img src="security_podium.png" width="280" alt="security_podium.png"> | [`security_podium.png`](security_podium.png) |
+| <img src="sedan.png" width="280" alt="sedan.png"> | [`sedan.png`](sedan.png) |
+| <img src="sheet_npc.jpg" width="280" alt="sheet_npc.jpg"> | [`sheet_npc.jpg`](sheet_npc.jpg) |
+| <img src="sheet_npc_gear.jpg" width="280" alt="sheet_npc_gear.jpg"> | [`sheet_npc_gear.jpg`](sheet_npc_gear.jpg) |
+| <img src="sheet_props.jpg" width="280" alt="sheet_props.jpg"> | [`sheet_props.jpg`](sheet_props.jpg) |
+| <img src="shoulder_bag.png" width="280" alt="shoulder_bag.png"> | [`shoulder_bag.png`](shoulder_bag.png) |
+| <img src="stanchion.png" width="280" alt="stanchion.png"> | [`stanchion.png`](stanchion.png) |
+| <img src="street_lamp.png" width="280" alt="street_lamp.png"> | [`street_lamp.png`](street_lamp.png) |
+| <img src="street_tree.png" width="280" alt="street_tree.png"> | [`street_tree.png`](street_tree.png) |
+| <img src="sunglasses.png" width="280" alt="sunglasses.png"> | [`sunglasses.png`](sunglasses.png) |
+| <img src="traffic_cone.png" width="280" alt="traffic_cone.png"> | [`traffic_cone.png`](traffic_cone.png) |
+| <img src="trash_bin.png" width="280" alt="trash_bin.png"> | [`trash_bin.png`](trash_bin.png) |
+| <img src="umbrella.png" width="280" alt="umbrella.png"> | [`umbrella.png`](umbrella.png) |
+| <img src="wall_lantern.png" width="280" alt="wall_lantern.png"> | [`wall_lantern.png`](wall_lantern.png) |
+| <img src="wand.png" width="280" alt="wand.png"> | [`wand.png`](wand.png) |

docs/screens/README.md

@@ -0,0 +1,16 @@
+# Screens and Visual Evidence
+
+Visual references and generated QA evidence for Gig Line.
+
+- [`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
+- [`realism/README.md`](realism/README.md) — locally generated realism runs (gitignored)
+
+## Quick preview
+
+| Screen | Reference | Current capture |
+| --- | --- | --- |
+| Venue | <img src="designs/venue_overview.png" width="320" alt="Venue design"> | <img src="../screenshots/01-venue-overview.png" width="320" alt="Venue capture"> |
+| Joke Shop | <img src="designs/joke_shop_queue.png" width="320" alt="Joke Shop design"> | <img src="../screenshots/12-joke-shop.png" width="320" alt="Joke Shop capture"> |
+| TV Studio | <img src="designs/studio_arrival.png" width="320" alt="Studio design"> | <img src="../screenshots/13-studio-arrival.png" width="320" alt="Studio capture"> |

docs/screens/concepts/README.md

@@ -1,40 +1,83 @@
 # Scene concepts: the realistic target look
 
-These are AI-generated example frames (`python3 tools/scene_concepts.py generate --group scene`,
+These are AI-generated example frames (`python3 tools/scene_concepts.py generate --group scene`, `openai/gpt-5-image-mini`, 1280×720) for the realism pass. They are art direction, not assets. `tools/scene_concepts.py realism` pairs them with the in-game shots from `src/test/capture_realism.gd` (see `SHOTS` in the tool). New generations never overwrite a file here; they are saved as `<name>-vN.png`.
-`openai/gpt-5-image-mini`, 1280×720) for the realism pass. They are art direction, not
-assets. `tools/scene_concepts.py realism` pairs them with the in-game shots from
-`src/test/capture_realism.gd` (see `SHOTS` in the tool). New generations never overwrite a
-file here; they are saved as `<name>-vN.png`.
 
-| Concept | Visual targets it sets |
+## Concept list
-| --- | --- |
-| `hollywood_entrance_morning` | warm low sun, long soft shadows, brick with visible mortar and wear, stone plinth, potted topiary, haze that fades the far street to beige |
-| `hollywood_entrance_golden_hour` | strong back light and rim light on people, marquee bulbs reading even in daylight |
-| `hollywood_entrance_rain_night` | dark scene lit by practical lights only (marquee, sodium lamps), wet glossy ground with reflections, fog |
-| `boulevard_skyline_day` | deep layered skyline with real towers and haze, palms lining the road, red curb paint, believable asphalt |
-| `boulevard_skyline_dusk` | purple/orange gradient sky, neon signs, lit windows, car light trails |
-| `joke_shop_alley_evening` | narrow brick alley, one warm wall lantern as key light, deep shadows, people in dark jackets |
-| `joke_shop_door_closeup` | close material detail: brick, mortar, aged wood door, brass |
-| `studio_stage_door_night` | granite facade, a bright bulb canopy as the main light, a glossy black car, stanchions and a barrier |
-| `sidewalk_material_closeup` | paver joints, stains, granite curb, aggregate asphalt and a tree grate at grazing light |
-| `entrance_steps_podium` | granite steps, handrails, glass doors, the check-in podium |
-| `crowd_barrier_line` | steel barriers, a red carpet, a crowd with depth-of-field haze |
-| `responder_arrival_wide` | fire engine, turnout gear, red/blue light spill on wet pavement |
-| `npc_portrait_day` | close portrait of a pedestrian: skin with visible pores and stubble, fabric weave, shallow depth of field. The bar for an avatar close-up, not for the crowd shots |
 
-The `npc_portrait` capture in `capture_realism.gd` is staged, not posed by the
+### Hollywood Entrance
-crowd: it freezes one NPC on an open patch of sidewalk, parks the rest of the
+
-crowd out of frame, turns the subject into the camera and stands the guard on the
+![hollywood entrance morning](hollywood_entrance_morning.png)
-sunlit side. It is the only shot where a face fills the frame, so it is the one to
+warm low sun, long soft shadows, brick with visible mortar and wear, stone plinth, potted topiary, haze that fades the far street to beige
-eyeball after an avatar change (generate a local run under `docs/screens/realism/`).
+
+### Hollywood Entrance Golden Hour
+
+![hollywood entrance golden hour](hollywood_entrance_golden_hour.png)
+strong back light and rim light on people, marquee bulbs reading even in daylight
+
+### Hollywood Entrance Rain Night
+
+![hollywood entrance rain night](hollywood_entrance_rain_night.png)
+dark scene lit by practical lights only (marquee, sodium lamps), wet glossy ground with reflections, fog
+
+### Boulevard Skyline
+
+![boulevard skyline day](boulevard_skyline_day.png)
+deep layered skyline with real towers and haze, palms lining the road, red curb paint, believable asphalt
+
+### Boulevard Skyline Dusk
+
+![boulevard skyline dusk](boulevard_skyline_dusk.png)
+purple/orange gradient sky, neon signs, lit windows, car light trails
+
+### Joke Shop Alley Evening
+
+![joke shop alley evening](joke_shop_alley_evening.png)
+narrow brick alley, one warm wall lantern as key light, deep shadows, people in dark jackets
+
+### Joke Shop Door Closeup
+
+![joke shop door closeup](joke_shop_door_closeup.png)
+close material detail: brick, mortar, aged wood door, brass
+
+### Studio Stage Door Night
+
+![studio stage door night](studio_stage_door_night.png)
+granite facade, a bright bulb canopy as the main light, a glossy black car, stanchions and a barrier
+
+### Sidewalk Material Closeup
+
+![sidewalk material closeup](sidewalk_material_closeup.png)
+paver joints, stains, granite curb, aggregate asphalt and a tree grate at grazing light
+
+### Entrance Steps Podium
+
+![entrance steps podium](entrance_steps_podium.png)
+granite steps, handrails, glass doors, the check-in podium
+
+### Crowd Barrier Line
+
+![crowd barrier line](crowd_barrier_line.png)
+steel barriers, a red carpet, a crowd with depth-of-field haze
+
+### Responder Arrival Wide
+
+![responder arrival wide](responder_arrival_wide.png)
+fire engine, turnout gear, red/blue light spill on wet pavement
+
+### NPC Portrait Day
+
+![npc portrait day](npc_portrait_day.png)
+close portrait of a pedestrian: skin with visible pores and stubble, fabric weave, shallow depth of field. The bar for an avatar close-up, not for the crowd shots
+
+The `npc_portrait` capture in `capture_realism.gd` is staged, not posed by the crowd: it freezes one NPC on an open patch of sidewalk, parks the rest of the crowd out of frame, turns the subject into the camera and stands the guard on the sunlit side. It is the only shot where a face fills the frame, so it is the one to eyeball after an avatar change (generate a local run under `docs/screens/realism/`).
 
 Cross-cutting targets, for comparison with locally generated realism runs:
 
-- **Exposure.** The concepts keep the ground mid-grey. The game's sidewalk is close to white,
+- **Exposure.** The concepts keep the ground mid-grey. The game's sidewalk is close to white, so it is overexposed.
-  so it is overexposed.
+- **Night means dark.** The night/dusk concepts are lit by practical lights. The game's "Evening" phase is a bright pink-orange frame.
-- **Night means dark.** The night/dusk concepts are lit by practical lights. The game's
+- **Depth.** The concepts show a layered skyline fading into haze. The new v2 skyline strips supply this; the old box skyline did not.
-  "Evening" phase is a bright pink-orange frame.
+- **Geometry and foliage.** The facades have plinths, cornices and deep window reveals, and the trees and shrubs are organic. The game uses flat walls and blob trees.
-- **Depth.** The concepts show a layered skyline fading into haze. The new v2 skyline strips
+
-  supply this; the old box skyline did not.
+## Additional previews
-- **Geometry and foliage.** The facades have plinths, cornices and deep window reveals, and the
+
-  trees and shrubs are organic. The game uses flat walls and blob trees.
+![npc_portrait_day-v2.png](npc_portrait_day-v2.png)

docs/screens/designs/README.md

@@ -0,0 +1,29 @@
+# Screens/Designs
+
+Screen-design mockups used by the comparison and vision-judge gates for the runtime UI.
+
+## Image previews
+
+| Preview | File |
+| --- | --- |
+| <img src="access_inspection.png" width="280" alt="access_inspection.png"> | [`access_inspection.png`](access_inspection.png) |
+| <img src="body_camera_timeline.png" width="280" alt="body_camera_timeline.png"> | [`body_camera_timeline.png`](body_camera_timeline.png) |
+| <img src="crowd_panic.png" width="280" alt="crowd_panic.png"> | [`crowd_panic.png`](crowd_panic.png) |
+| <img src="emergency_radio.png" width="280" alt="emergency_radio.png"> | [`emergency_radio.png`](emergency_radio.png) |
+| <img src="escalation_hud.png" width="280" alt="escalation_hud.png"> | [`escalation_hud.png`](escalation_hud.png) |
+| <img src="joke_shop_queue.png" width="280" alt="joke_shop_queue.png"> | [`joke_shop_queue.png`](joke_shop_queue.png) |
+| <img src="late_night_avenue.png" width="280" alt="late_night_avenue.png"> | [`late_night_avenue.png`](late_night_avenue.png) |
+| <img src="movement_precision.png" width="280" alt="movement_precision.png"> | [`movement_precision.png`](movement_precision.png) |
+| <img src="night_flashlight.png" width="280" alt="night_flashlight.png"> | [`night_flashlight.png`](night_flashlight.png) |
+| <img src="pause_overlay.png" width="280" alt="pause_overlay.png"> | [`pause_overlay.png`](pause_overlay.png) |
+| <img src="prop_gallery.png" width="280" alt="prop_gallery.png"> | [`prop_gallery.png`](prop_gallery.png) |
+| <img src="radial_menu.png" width="280" alt="radial_menu.png"> | [`radial_menu.png`](radial_menu.png) |
+| <img src="radio_report.png" width="280" alt="radio_report.png"> | [`radio_report.png`](radio_report.png) |
+| <img src="responder_arrival.png" width="280" alt="responder_arrival.png"> | [`responder_arrival.png`](responder_arrival.png) |
+| <img src="settings_panel.png" width="280" alt="settings_panel.png"> | [`settings_panel.png`](settings_panel.png) |
+| <img src="shift_review.png" width="280" alt="shift_review.png"> | [`shift_review.png`](shift_review.png) |
+| <img src="start_menu.png" width="280" alt="start_menu.png"> | [`start_menu.png`](start_menu.png) |
+| <img src="studio_arrival.png" width="280" alt="studio_arrival.png"> | [`studio_arrival.png`](studio_arrival.png) |
+| <img src="targeting_npc.png" width="280" alt="targeting_npc.png"> | [`targeting_npc.png`](targeting_npc.png) |
+| <img src="venue_overview.png" width="280" alt="venue_overview.png"> | [`venue_overview.png`](venue_overview.png) |
+| <img src="wand_screening.png" width="280" alt="wand_screening.png"> | [`wand_screening.png`](wand_screening.png) |

docs/screenshots/README.md

@@ -0,0 +1,21 @@
+# Screenshots
+
+Committed gallery captures generated from the current build by src/test/capture_screenshots.gd and src/test/capture_prop_gallery.gd.
+
+## Image previews
+
+| Preview | File |
+| --- | --- |
+| <img src="01-venue-overview.png" width="280" alt="01-venue-overview.png"> | [`01-venue-overview.png`](01-venue-overview.png) |
+| <img src="02-targeting-npc.png" width="280" alt="02-targeting-npc.png"> | [`02-targeting-npc.png`](02-targeting-npc.png) |
+| <img src="03-access-inspection.png" width="280" alt="03-access-inspection.png"> | [`03-access-inspection.png`](03-access-inspection.png) |
+| <img src="04-radio-report.png" width="280" alt="04-radio-report.png"> | [`04-radio-report.png`](04-radio-report.png) |
+| <img src="05-late-night-avenue.png" width="280" alt="05-late-night-avenue.png"> | [`05-late-night-avenue.png`](05-late-night-avenue.png) |
+| <img src="06-night-flashlight.png" width="280" alt="06-night-flashlight.png"> | [`06-night-flashlight.png`](06-night-flashlight.png) |
+| <img src="07-wand-screening.png" width="280" alt="07-wand-screening.png"> | [`07-wand-screening.png`](07-wand-screening.png) |
+| <img src="08-escalation-hud.png" width="280" alt="08-escalation-hud.png"> | [`08-escalation-hud.png`](08-escalation-hud.png) |
+| <img src="09-body-camera-timeline.png" width="280" alt="09-body-camera-timeline.png"> | [`09-body-camera-timeline.png`](09-body-camera-timeline.png) |
+| <img src="10-prop-gallery.png" width="280" alt="10-prop-gallery.png"> | [`10-prop-gallery.png`](10-prop-gallery.png) |
+| <img src="11-precision-walk.png" width="280" alt="11-precision-walk.png"> | [`11-precision-walk.png`](11-precision-walk.png) |
+| <img src="12-joke-shop.png" width="280" alt="12-joke-shop.png"> | [`12-joke-shop.png`](12-joke-shop.png) |
+| <img src="13-studio-arrival.png" width="280" alt="13-studio-arrival.png"> | [`13-studio-arrival.png`](13-studio-arrival.png) |