Consolidate architecture docs and add the v1.0.0 roadmap

Make architecture the canonical system/data-flow source, add explicit documentation ownership and consolidation rules, and mark the old graphics plan historical. Fix stale README/status/Blender/release claims. Add a full gap register and milestone roadmap from v0.8 through v1.0.0, including onboarding, content depth, accessibility/localization, performance, release/legal blockers and non-blocking future ideas.
2026-11-01 20:04:47 +01:00
1 parent 659b0e35b2
commit 6c367e8c7e
@@ -44,6 +44,7 @@ Session memory for durable decisions, state, and gotchas. Keep concise, remove o
 - Shift length is the scenario's `shift_duration_s` (900 s in all three venues). Tests and the screenshot tool override elapsed time; they do not change the default.
 - RNG: NPC reactions and event scheduling are seedable for deterministic tests.

+- **Documentation ownership (2026-11-01):** `docs/architecture.md` §12 now defines the source-of-truth map and consolidation rules. `docs/plan-graphics-v0.6.md` is historical; current work belongs in `TODO.md`. README/development-status/Blender AO/Forward+ stale claims were corrected. The v1.0.0 gap register and 0.8/0.9/0.9.5/1.0 roadmap live in `TODO.md`.
 - **Vision judge (v0.7.2):** `tools/openrouter_judge.py` reads `/api/v1/models`, filters image-input models with `response_format`, and ranks by advertised prompt/image/completion prices. `--model auto` (default) uses the cheapest (`z-ai/glm-5.3-flash` on 2026-11-01) with fallbacks; explicit `--model`/`GIG_LINE_JUDGE_MODEL` wins. Auth errors abort, provider/model errors fall through. Full screen judge 13/13 match, 0 diff; A/B judge ~$0.006.
 - **Desktop HQ preset (v0.7.1):** `packaging/desktop_hq/override.cfg` switches a
  copied executable to Forward+; `Materials.forward_plus_active()` gates
@@ -153,13 +153,13 @@ The visual direction is readable stylized realism:
 - **References and QA:** runtime UI art lives in `assets/images/ui/`; reference/art-direction sets live in `docs/screens/designs/` and `docs/screens/concepts/`; captures live in `docs/screenshots/`; realism runs live in `docs/screens/realism/`. `screen_designs.py compare/judge` and `tools/check_screenshots.sh` guard drift.
 - **Storage convention:** see [ADR-0014](docs/adr/0014-runtime-image-root.md). Never overwrite an existing image; new outputs get a new path or `-vN` suffix.

-Remaining visual work is tracked in `TODO.md` (NPC fidelity and the two venue stages), not in this plan.
+The path from the current vertical slice to v1.0.0 — content depth, onboarding, accessibility, platform QA and release readiness — is tracked in [`TODO.md`](TODO.md); this plan stays at the product/design level.

 Primary decisions: [ADR-0007](docs/adr/0007-locomotion-and-input-layers.md), [ADR-0008](docs/adr/0008-cone-focus-and-head-ring.md), [ADR-0009](docs/adr/0009-radial-action-menu.md), [ADR-0010](docs/adr/0010-procedural-npc-presentation.md), [ADR-0011](docs/adr/0011-aim-free-selection-and-precision-walk.md), [ADR-0012](docs/adr/0012-surface-materials-and-generated-props.md), [ADR-0013](docs/adr/0013-blender-authored-npc-characters.md).

 ## Tech Stack

- **Engine:** Godot 4.3, GL Compatibility renderer (Web parity).
+- **Engine:** Godot 4.3 baseline (local dev verified with 4.7.2), GL Compatibility renderer (Web parity); optional Forward+ Desktop HQ build.
 - **Language:** GDScript.
 - **Architecture:** venue-driven simulation; shared systems plus `Resource`-based scenario data.
 - **Navigation:** `NavigationRegion3D` / `NavigationAgent3D`.
@@ -31,15 +31,16 @@ precision walk, the Joke Shop alley, the TV Studio arrival, and the prop lineup.
 | **Linux — portable** | [`gig-line-linux-<ver>.x86_64`](https://git.allucanget.biz/zwitschi/security-game/releases) · 64-bit, `chmod +x` and run |
 | **macOS** | [`gig-line-macos-<ver>.zip`](https://git.allucanget.biz/zwitschi/security-game/releases) · unsigned build, quarantine note below |
 | **Web (browser)** | [`gig-line-web-<ver>.zip`](https://git.allucanget.biz/zwitschi/security-game/releases) · unzip and serve the folder from any static host (no special headers) |
+| **Desktop HQ** | [`gig-line-desktop-hq-<ver>.zip`](https://git.allucanget.biz/zwitschi/security-game/releases) · optional Forward+ build with volumetric fog/SDFGI/flashlight; requires a Vulkan-capable GPU/driver |

 **All releases:** <https://git.allucanget.biz/zwitschi/security-game/releases>

 > Downloads are public (no sign-in required) since the host's instance-wide
 > `REQUIRE_SIGNIN_VIEW` was disabled on 2026-10-31.
 >
-> **Latest: v0.7.0** — distinct Joke Shop and TV Studio geometry, fitted NPC gear,
-> and the post-v0.6.0 realism/visual-alignment work (v2 skylines/textures, UI mockup
-> art, flashlight beam, HUD fixes).
+> **Latest: v0.7.2** — a cost-aware OpenRouter screenshot judge, an optional
+> Forward+ Desktop HQ build with volumetric fog/SDFGI/flashlight, distinct Joke
+> Shop and TV Studio geometry, and fitted NPC gear.
 > Releases are built automatically when a `vX.Y.Z` tag is pushed
 > (see [`docs/RELEASING.md`](docs/RELEASING.md)); manual builds use
 > `./tools/build_releases.sh`. Installer/AppImage packaging runs in the same pipeline
@@ -74,7 +75,7 @@ decisions are recorded as ADRs in [`docs/adr/`](docs/adr/).

 ## Tech Stack

- **Engine:** Godot 4.x · **Language:** GDScript
+- **Engine:** Godot 4.3 baseline (local dev verified with 4.7.2) · **Language:** GDScript
 - **NPCs:** Blender-authored skinned library (`assets/models/blender/`) with procedural fallbacks; lightweight FSMs on `NpcProfile`
 - **World:** procedural `WorldBuilder` + generated prop models
 - **Art:** v2 skyline/surface textures in `assets/textures/ai/game_ready/v2/picks/`; UI/scene art in `assets/images/`
@@ -102,7 +103,6 @@ Full setup, every run/test/smoke command, and the controls table are in

 - [`PLAN.md`](PLAN.md) — Game design plan and scenario details.
 - [`AGENTS.md`](AGENTS.md) — Development and collaboration workflow.
- [`TODO.md`](TODO.md) — Active checkbox task list.
 - [`DONE.md`](DONE.md) — Completed task sections.
 - [`MEMORY.md`](MEMORY.md) — Persistent session notes.
 - [`CHANGELOG.md`](CHANGELOG.md) — User-facing changes by version.
@@ -114,16 +114,17 @@ Full setup, every run/test/smoke command, and the controls table are in
 - [`docs/smoke-checklist.md`](docs/smoke-checklist.md) — Manual smoke-test checklist.
 - [`docs/blender-assets.md`](docs/blender-assets.md) — Blender asset library: characters, gear, props, attach points.
 - [`docs/adr/`](docs/adr/) — Architecture Decision Records.
- [`docs/plan-graphics-v0.6.md`](docs/plan-graphics-v0.6.md) — Graphics-quality plan: Blender-authored NPC characters.
+- [`TODO.md`](TODO.md) — Active tasks plus the v1.0.0 gap analysis and milestone roadmap.
+- [`docs/plan-graphics-v0.6.md`](docs/plan-graphics-v0.6.md) — Historical v0.6 graphics program (completed).

 ## Development Status

-v0.7.0 shipped distinct venue geometry: the Joke Shop alley and TV Studio
-entrance no longer share the Hollywood layout. It builds on v0.6.1's fitted NPC
-gear and v0.6.0's Blender asset library, baked AO and environment lift. See
-[`docs/development-status.md`](docs/development-status.md) for the full
-implemented list and [`TODO.md`](TODO.md) for what's next. Manual verification
-uses the [`docs/smoke-checklist.md`](docs/smoke-checklist.md).
+v0.7.2 ships the cost-aware OpenRouter judge and the optional Desktop HQ build.
+The three venues now have distinct geometry, fitted NPC gear, the Blender asset
+library and the post-v0.6.0 realism pass. See
+[`docs/development-status.md`](docs/development-status.md) for the implemented
+list, and [`TODO.md`](TODO.md) for the v1.0.0 gap analysis and roadmap. Manual
+verification uses the [`docs/smoke-checklist.md`](docs/smoke-checklist.md).

 ## Development Workflow

@@ -3,6 +3,136 @@
 Work is grouped by theme. Each item should be small enough to complete and verify on its own;
 see `AGENTS.md` for the workflow and `MEMORY.md` for the decisions behind these plans.

+## Gap Analysis and v1.0.0 Roadmap
+
+Baseline: **v0.7.2** (2026-11-01). Three playable venues, a complete escalation/access/radio
+loop, shift review, Blender character/gear/prop library, 231 headless + 94 Python tests, a
+13/13 clean screen-design judge and an optional Forward+ Desktop HQ build. This baseline is a
+strong vertical slice, not yet a 1.0 product.
+
+### Documentation audit (completed 2026-11-01)
+
+- [x] Make `docs/architecture.md` the single architecture source: added the asset/content
+      pipeline contracts, runtime venue-switch/fallback flows, deployment/version constraints,
+      quality requirements, risk register and a documentation ownership map.
+- [x] Keep command-heavy operational pages separate but subordinate: `docs/asset-tooling.md`,
+      `docs/blender-assets.md`, `docs/getting-started.md`, `docs/RELEASING.md` and
+      `docs/smoke-checklist.md` now link to architecture rather than acting as parallel sources.
+- [x] Mark `docs/plan-graphics-v0.6.md` as completed/historical; current graphics work belongs in
+      this roadmap.
+- [x] Resolve stale claims: README release version/download row, development status
+      "Forward+ not implemented", Blender props "not AO-baked", and historical plan status.
+- [x] Record the documentation ownership rule in `docs/architecture.md` §12: design intent
+      (`PLAN.md`), mechanics (`gameplay.md`), system architecture/contracts (`architecture.md`),
+      decisions (ADRs), status (`development-status.md`), roadmap (`TODO.md`), operations
+      (tooling/release docs).
+
+### Gap register
+
+| Area | Current baseline | Gap to 1.0 | Risk | Milestone |
+| --- | --- | --- | --- | --- |
+| First-hour experience | Venue menu and controls exist; no tutorial | No guided first shift, control coaching, objective recap or "what went wrong" debrief | New players bounce before the de-escalation loop lands | 0.8 |
+| Campaign/progression | Venue selection and debug cycle | No career/venue order, unlocks, difficulty curve or persistent player progression | Shift loop feels like a tech demo rather than a game | 0.8 |
+| Authored content | 3 venues, small event pools, one-line dialogue | Need a larger event matrix per venue, repeat/remix rules, failure/recovery events and more NPC dialogue | Repetition after a few shifts | 0.8 |
+| NPC behavior | FSM intents, reactions, crowd/theater poses | Deeper negotiation, memory of earlier interactions, group dynamics, believable refusal/escalation edges | NPCs still feel deterministic/scripted | 0.8 |
+| Access/evaluation | Recognition, wristbands/IDs/tickets/credentials, reputation/review | Fairness tuning, ambiguous cases, clearer evidence trail, richer grades and actionable feedback | Players cannot learn why a decision scored poorly | 0.8 |
+| Shift lifecycle | Settings + completed-shift history persist | No mid-shift save/resume, pause-safe serialization, versioned save schema or replay | Interrupted sessions lose the run; future changes can break saves | 0.8 |
+| Accessibility | Key remapping, gamepad, HUD font scale, shape escalation cue | Subtitles/captions, colour-independent cues, motion/audio sensitivity, text expansion, menu narration and full input alternatives need an audit | Public 1.0 cannot claim accessible play | 0.8–0.9 |
+| Localization | English strings in `content/strings.en.json` | String extraction/coverage, pseudo-locale test, font fallback, text-length layout budgets and translator workflow | Text bugs and unsupported locales at release | 0.9 |
+| Audio | Procedural crowd bed and radio crackle | Music/ambience direction, event SFX, voice/VO decision, caption hooks and mix budgets | Scene can feel silent/placeholder | 0.9 |
+| Animation/presentation | Procedural poses, walk/idle theater, LOD impostor | More reaction/idle/negotiation poses, transitions, facial readability at portrait distance, camera-height decision | Cinematic close-ups expose the prototype layer | 0.9 |
+| Performance/platform | 16-NPC budget measured headlessly; Compatibility default; optional Vulkan HQ | Target hardware matrix, 24-NPC profiling, draw-call/memory budgets, Web/HQ parity and frame-time regression gates | Crowded studio or Web drops frames | 0.9 |
+| Content tooling | ScenarioFactory/.tres export, Blender manifest, asset audits | Schema validation, previews, event authoring workflow, reproducible asset rebuild notes and contributor onboarding | Content expansion becomes expensive/error-prone | 0.8–0.9 |
+| QA/CI | Headless suite, smokes, screenshot compare, model-aware judge | End-to-end shift automation, full venue matrix, CI Godot-version strategy, manual judge budget and release checklist automation | Regressions escape or CI becomes non-reproducible | 0.9 |
+| Release/legal | Tag-driven unsigned builds, Web zip, optional HQ | Signing/notarization, checksums, AI-asset provenance/licensing, credits, privacy/body-camera statement and storefront requirements | Public release blocked by trust/policy issues | 0.9.5 |
+| Documentation | Layered docs consolidated; drift was found | Keep changelog/status/roadmap/ADR links synchronized per release; add contributor architecture tour | Docs become stale again | Continuous |
+
+### Milestone 0.8.0 — First hour and content depth
+
+- [ ] Add a skippable first-shift tutorial: movement/look, focus, action wheel, access check,
+      warning, body camera, radio and shift review; teach by doing, not a wall of text.
+- [ ] Add a persistent campaign shell: venue order/unlocks, selected difficulty, shift summaries
+      and a clear "next shift" path. Keep debug venue cycling separate.
+- [ ] Add an objective/recap layer: current venue policy, shift phase and a post-incident recap of
+      what evidence was checked and why the outcome was judged fair/unfair.
+- [ ] Define a content matrix for each venue (routine, scripted, edge, recovery and rare-threat
+      events) and fill the largest holes; target meaningful variety across all four phases.
+- [ ] Expand NPC dialogue beyond one-line intent replies: refusal reasons, de-escalation responses,
+      recognition callbacks and group reactions, all localized and deterministic under seed.
+- [ ] Add mid-shift save/resume with a versioned schema and migration test; keep completed-shift
+      history and settings compatible.
+- [ ] Add difficulty/pacing options (spawn rate, tolerance, report strictness) without changing the
+      de-escalation-first rules; expose them in Settings with defaults matching the current build.
+- [ ] Add a new-player help overlay and a searchable controls reference distinct from the HUD legend.
+- [ ] Exit: a new player can complete a first shift without the README; each venue has enough
+      content for repeated shifts; save/resume survives restart; 0.8 test matrix is green.
+
+### Milestone 0.9.0 — Production quality and platform readiness
+
+- [ ] Animation/presentation pass: negotiation/reaction poses and transitions, readable faces in
+      portrait, resolved camera height, and no coat/skirt leg clipping in normal movement.
+- [ ] Audio pass: music/ambience direction, event SFX, radio/crowd mix, caption hooks and a VO
+      decision with production scope.
+- [ ] Localization pass: all player-facing strings externalized, pseudo-locale layout test, font
+      fallback and a contributor translation workflow.
+- [ ] Accessibility pass: subtitles/captions, colour-independent access/escalation cues, motion
+      and flash options, full keyboard/gamepad parity and documented assist options.
+- [ ] Performance pass: profile 24 live NPCs, all venues, Web and Desktop HQ; record frame-time,
+      draw-call and memory budgets; add regression checks where automation is possible.
+- [ ] QA pass: automated end-to-end shift for each venue, full smoke matrix, screenshot/judge
+      baselines, and a documented manual judge budget/model pin.
+- [ ] Resolve the Godot baseline: choose one supported version (or an explicit 4.3-CI/4.7-local
+      matrix), align export templates and visual smoke results, and document the policy.
+- [ ] Exit: production content is feature-complete, accessibility/localization acceptance criteria
+      pass, target hardware matrix is measured, and no P0/P1 defect remains open.
+
+### Milestone 0.9.5 — Release candidate
+
+- [ ] Content lock and external playtest round (at least five first-time players); triage findings
+      by severity and fix all P0/P1 issues.
+- [ ] Balance and fairness pass across all venues: scoring, difficulty, event weights, NPC
+      compliance and emergency false-positive/negative rates.
+- [ ] Save migration test from 0.8/0.9 saves; verify settings, shift history and resume paths.
+- [ ] Release engineering: signed/notarized macOS where possible, checksums, Windows/Linux install
+      smoke tests, AppImage update, Web hosting verification and Desktop HQ Vulkan fallback.
+- [ ] Legal/credits review: AI-assisted asset provenance, music/SFX licenses, privacy/body-camera
+      language, age/content rating and storefront requirements.
+- [ ] Documentation sign-off: architecture/ADR/status/TODO/changelog/README/smoke checklist all
+      match the release candidate; capture final gallery and run compare + judge.
+- [ ] Exit: release candidate passes the manual smoke checklist on every target; no release-blocking
+      legal or platform issue remains.
+
+### Milestone 1.0.0 — Launch
+
+- [ ] Freeze content and version, run full final QA on Windows/Linux/macOS/Web/Desktop HQ, and
+      verify fresh installs plus upgrade paths.
+- [ ] Publish store/release notes, credits, known limitations, accessibility statement and
+      controls; verify every download link and artifact checksum.
+- [ ] Tag `v1.0.0`, publish through CI, verify the release page and post-launch patch policy.
+- [ ] Definition of 1.0: three complete venues with campaign/tutorial, stable save/resume,
+      accessibility/localization acceptance, measured performance on the target matrix, signed
+      release artifacts where platform rules require it, and documentation synchronized with the
+      build.
+
+### Explicit post-1.0 / non-blocking candidates
+
+- [ ] Live 3D body-camera replay.
+- [ ] Additional venues or seasonal events.
+- [ ] Real voice/dialogue audio.
+- [ ] Image-to-mesh prop pipeline.
+- [ ] Rare easter eggs/cameos (e.g. Bob Dobbs) only after core content and QA are stable.
+
+### Roadmap dependencies and risks
+
+- Content volume is the largest schedule risk; tutorial and campaign work must not outrun the
+      event/dialogue matrix.
+- The vision judge is a dev-time aid with an external key/budget; CI must never make it a hard gate.
+- Godot version changes can alter lighting/imports; do not combine an engine baseline move with a
+      content/feature milestone.
+- Signed macOS builds and legal/AI provenance are release blockers, not polish.
+- Keep the de-escalation-first rules and rare-emergency design unchanged while adding progression,
+      difficulty and feedback.
+
 ## Realism follow-ups (deferred)

 - [x] Re-run the screen-design judge for `12-joke-shop`, `13-studio-arrival` and the
@@ -127,14 +127,15 @@ published the release, re-running the script only adds missing assets.

 > **Host note**: the release is fully built by CI, but anonymous users can only
 > browse and download when the instance sets `[service] REQUIRE_SIGNIN_VIEW=false`
-> in `app.ini` (the repo itself is public). See the TODO for the exact steps.
+> in `app.ini` (the repo itself is public). This is a host-admin setting, not a
+> repository file.

 Manual alternative:

 ### Via the web UI

 1. Create a **New Release** with tag `v<version>`.
-2. Attach all three `build/` artifacts.
+2. Attach all artifacts from `build/` (portables, installer/AppImage, Web and optional Desktop HQ).
 3. Write release notes (see checklist below).

 ### Via the API
@@ -171,7 +172,7 @@ change, update `tools/build_releases.sh` first.

 - [ ] All headless tests pass (exit code 0).
 - [ ] Game boots cleanly in a smoke test.
- [ ] Controls documented in `README.md` match the build.
+- [ ] Controls documented in `docs/getting-started.md` match the build.
 - [ ] Version in `project.godot` matches the tag.
 - [ ] Export templates used are the official ones for the pinned engine.
 - [ ] Artifacts uploaded; README downloads page shows them.
@@ -25,7 +25,7 @@ This document follows the structure of the arc42 architecture documentation temp
 ## 2. Constraints

 - The first implementation should be small enough for a playable vertical slice.
- The engine is Godot 4 with GDScript; a playable prototype vertical slice is implemented.
+- The engine is Godot 4 with GDScript; a playable prototype vertical slice is implemented. CI pins Godot 4.3 while local development is verified with 4.7.2; the default renderer stays GL Compatibility for Web parity, with an optional Forward+ Desktop HQ build.
 - Venue-specific policies must be configurable rather than hard-coded into individual NPCs.
 - The game must preserve the de-escalation-first design described in [`PLAN.md`](../PLAN.md).
 - The project uses the repository workflow described in [`AGENTS.md`](../AGENTS.md).
@@ -83,7 +83,7 @@ The player interacts with NPCs, venue entrances, access artifacts, equipment, st
 - `tools/model_pipeline.py` builds and audits the street-prop `.glb` models and packs their colour atlases.
 - `tools/npc_pipeline.py` builds and audits the skinned NPC base model (`assets/models/generated/npc_base.glb`) and its per-slot material maps, with an optional AI fabric override (ADR-0013).
 - `tools/blender_assets.py` builds, renders and audits the Blender asset library (`assets/models/blender/{npc,npc_gear,props}/` + `manifest.json`): NPC character variants that are drop-in for `npc_base`, attach-point gear, and street/venue props. `NpcAvatar` selects variants/gear by role/seed and `WorldBuilder` loads the prop replacements and new street dressing, with procedural fallbacks (see `docs/blender-assets.md`).
- `tools/scene_concepts.py` generates realism-pass references (`docs/screens/concepts/`), skyline backdrops and surface tiles (raw `assets/textures/ai/v2/raw/` → candidates `assets/textures/ai/game_ready/v2/`), promotes the validated ones to the tracked `v2/picks/` that `SurfaceMaterials`/`WorldBuilder` preload, audits them, and scores `src/test/capture_realism.gd` A/B captures (five stages, runtime texture swaps) against the concepts (`docs/screens/realism/<run>/`).
+- `tools/scene_concepts.py` generates realism-pass references (`docs/screens/concepts/`), skyline backdrops and surface tiles (raw `assets/textures/ai/v2/raw/` → candidates `assets/textures/ai/game_ready/v2/`), promotes the validated ones to the tracked `v2/picks/` that `SurfaceMaterials`/`WorldBuilder` preload, audits them, and scores `src/test/capture_realism.gd` A/B captures (six stages, runtime texture swaps) against the concepts (`docs/screens/realism/<run>/`).
 - `tools/asset_pipeline.py` generates and audits role-aware textures; `tools/screen_designs.py` generates screen references and judges captures; `tools/check_screenshots.sh` renders the staged gallery and runs the compare gate.

 Confirmed game assets live in `assets/textures/ai/game_ready/` (audited surface, UI, and card textures), `assets/models/generated/` (prop and NPC `.glb` models plus their texture atlases), and `assets/textures/npc/` (NPC material maps and `palette.json`). Development-only outputs — AI concept sheets, Blender sources, raw AI fabrics — are gitignored and regenerated by the tools.
@@ -106,6 +106,36 @@ When reference art becomes runtime art, copy or process it into `assets/images/`
 new descriptive name (never overwrite an existing image) and keep a procedural fallback
 in code.

+### Content and asset pipeline architecture
+
+The asset/content pipeline is part of the architecture, not an external build detail:
+
+| Stage | Producer | Committed artifact | Runtime consumer | Failure fallback |
+| --- | --- | --- | --- | --- |
+| Scenario data | `ScenarioFactory` / editor export | `content/venues/*.tres`, event/profile data | `VenueScenario` → `ShiftCoordinator` | built-in scenario defaults |
+| NPC library | Blender flatpak + `tools/blender_assets.py` | `assets/models/blender/npc/*.glb`, manifest, baked AO | `NpcAvatar` | `npc_base.glb` → procedural rig |
+| Gear/props | Blender flatpak + tool + bake | `npc_gear/*.glb`, `props/*.glb`, `*_ao.png` | `NpcAvatar`, `WorldBuilder` | primitive assets / generated props |
+| Surface/UI art | Python pipelines / AI-assisted references | `assets/textures/ai/game_ready/`, `assets/images/` | `SurfaceMaterials`, `UiArt` | neutral material / procedural UI |
+| Screenshots/QA | capture scripts + `scene_concepts`/`screen_designs` | `docs/screenshots/`, `docs/screens/realism/` | reviewers and CI gates | regenerate; never runtime input |
+| Release | Gitea workflow + build/publish scripts | platform binaries, Web zip, Desktop HQ zip | players | source build |
+
+Contracts that keep the pipeline replaceable:
+
+- `npc_base` armature/bone names, five tint slots and front direction are frozen by tests; gear is authored in attach-point space and measured against the character silhouette.
+- Library characters, gear and props are audited for grounding, UVs, triangle budgets, degenerate triangles and manifest coverage; Blender is a developer tool, never a CI runtime dependency.
+- `WorldBuilder.VENUE_SPECS` drives geometry, navigation, features and prop placements; `GameManager` rebuilds only the world container on a venue change.
+- UI/scene art is loaded through `UiArt` with a null/neutral fallback; composed images live in `assets/images/`, not in the docs reference tree (ADR-0014).
+- CI stays offline: only committed `.glb`/`.png`/`.tres` and Godot are needed; optional AI/Blender steps are reproducible development tools.
+
+### Content authoring and runtime data flow
+
+`ScenarioFactory` is the source of truth for the three authored venues. `tools/export_venues.gd`
+writes `content/venues/<id>.tres` for editor inspection; the factory remains the canonical
+scenario definition. At runtime `GameManager` selects a `VenueScenario`, `ShiftCoordinator`
+schedules events and phases, and `NPCController`/`AccessVerifier`/`EscalationManager` produce
+incidents. `IncidentRecorder` is the authoritative event history; body-camera review,
+reputation, crowd reaction and shift review read it rather than resolving gameplay separately.
+
 ## 6. Runtime View

 ### Routine interaction
@@ -118,6 +148,19 @@ in code.
 6. The incident recorder stores the interaction.
 7. Reputation and crowd systems react to the outcome.

+### Venue switch
+
+1. The player selects a venue from the start menu or cycles with the debug shortcut.
+2. `GameManager` loads the matching `VenueScenario` and keeps the guard/UI state.
+3. `WorldBuilder` rebuilds only `world_root` from `VENUE_SPECS`, including geometry, props and the navigation mesh.
+4. Shift state, NPCs and incidents are reset for the new venue; phase lighting and the door state are reapplied.
+
+### Asset fallback
+
+1. A runtime loader asks for the library scene or texture.
+2. If the imported asset is missing, the loader uses the generated/procedural fallback rather than failing the boot.
+3. Contracts and audits ensure the fallback and library paths expose the same observable behaviour; CI runs headless against whichever path is available.
+
 ### Access check

 1. The player stops or receives an approaching person.
@@ -137,7 +180,7 @@ in code.

 ## 7. Deployment View

-The game is a single-player local client containing presentation, simulation, rules, content, and persistence for local settings and shift results. No online backend is required. A non-threaded Web export ships alongside the desktop builds and can be served from any static host without special headers.
+The game is a single-player local client containing presentation, simulation, rules, content, and persistence for local settings and shift results. No online backend is required. A non-threaded Web export ships alongside the desktop builds and can be served from any static host without special headers. The default renderer is GL Compatibility; an optional Desktop HQ zip uses Forward+ with volumetric fog/SDFGI on Vulkan-capable desktops. CI pins Godot 4.3 while local development is verified with 4.7.2, so the light falloff path is version-adaptive until the baseline is unified.

 Future options include external analytics, cloud saves, or replay sharing, but they are not part of the current architecture.

@@ -173,6 +216,8 @@ The release process is: bump the version, run the full test suite and `tools/che
 - **Localization:** Dialogue and prompts should be externalized from logic.
 - **Observability:** Debug overlays show NPC intent, access status, escalation level, active incidents, and response timers during development.
 - **Visual regression:** Staged captures are compared against the runtime reference art (`screen_designs.py compare`) and optionally judged by a vision model; `tools/check_screenshots.sh` makes the pass repeatable.
+- **Asset provenance and AI usage:** AI-assisted images/concepts are development inputs only; validated outputs are committed, audited and loaded through the same runtime asset contracts. Generated content must not become an offline/CI dependency.
+- **Documentation ownership:** `PLAN.md` owns design intent; `docs/gameplay.md` owns playable mechanics; `docs/architecture.md` owns system boundaries, data flow, constraints and cross-cutting decisions; ADRs own decision history; `docs/development-status.md` owns the implemented/gap list; `TODO.md` owns the roadmap; `MEMORY.md` owns gotchas and open questions. Specialized docs link to these rather than becoming competing sources of truth.

 ## 9. Architecture Decisions

@@ -203,6 +248,9 @@ Architecture decisions are recorded as ADRs:
 | Performance | The target venue should support a believable crowd without harming input or simulation responsiveness. |
 | Testability | Access and escalation rules can be tested independently of presentation. |
 | Accessibility | Core actions are available through clear input alternatives and readable feedback. |
+| Reliability | A fresh checkout, missing optional asset, invalid AI key, or unavailable Forward+ renderer must not prevent a normal Compatibility/Web/headless boot. |
+| Performance | A busy venue should hold its budget at the target NPC cap on desktop and Web; the current 16-NPC check is a baseline, not a 1.0 guarantee. |
+| Documentation integrity | Every released version has a changelog entry, current status/roadmap, and architecture/ADR references that match the build. |

 ## 11. Risks and Technical Debt

@@ -213,8 +261,45 @@ Architecture decisions are recorded as ADRs:
 - Mental-health-crisis scenarios require careful writing, playtesting, and respectful presentation.
 - The choice of engine may affect navigation, crowd scale, tooling, and content authoring.
 - Reference mockups can outpace the runtime art style; compare/judge catch gross drift but not composition errors, so the staged gallery needs human review after large visual changes.
+- Godot version skew (CI 4.3 vs local 4.7.2) can change lighting, import sidecars and generated UIDs; a single supported version and a visual smoke matrix are required before 1.0.
+- Content volume and authoring tools are still thin; adding venues/events by editing the factory can become error-prone without schema validation and preview tooling.
+- Save data currently covers settings and shift history, not mid-shift resume; adding saves/replays requires a versioned schema and migration policy.
+- The optional judge and image-generation paths depend on an external key, model availability and budget; CI cannot make them a release gate, and keys must never be committed.
+- Accessibility and localization coverage is partial; a 1.0 release needs subtitles/captions, colour-independent cues, remapping, text expansion tests and at least a documented localization workflow.
+- Unsigned macOS builds, AI asset provenance and any storefront/legal requirements are release blockers for a public 1.0.
+- Documentation drift has already occurred (release version, implemented status, historical graphics plan); the ownership map and roadmap must be kept current in the same change as the implementation.

-## 12. Glossary
+## 12. Documentation Consolidation and Ownership
+
+The documentation set is intentionally layered. Architecture-level material is consolidated here;
+specialized operational detail remains in focused pages so commands do not rot inside the
+architecture document.
+
+| Document | Canonical role | Relationship to this architecture |
+| --- | --- | --- |
+| [`PLAN.md`](../PLAN.md) | Product/design intent, pillars, venues and success criteria | Design source; architecture realizes it |
+| [`docs/gameplay.md`](gameplay.md) | Playable loop, escalation, venue mechanics | Runtime/behavioral view |
+| [`docs/architecture.md`](architecture.md) | System boundaries, data flow, constraints, deployment, cross-cutting decisions, quality risks | Single architecture source |
+| [`docs/adr/`](adr/) | Immutable decision records with context and consequences | Decision history linked from §9 |
+| [`docs/asset-tooling.md`](asset-tooling.md) | Build/audit/capture commands and pipeline usage | Operational appendix to the pipeline section |
+| [`docs/blender-assets.md`](blender-assets.md) | Blender character/gear/prop contracts and attach points | Detailed asset contract appendix |
+| [`docs/getting-started.md`](getting-started.md) | Setup, commands, controls | Developer onboarding |
+| [`docs/RELEASING.md`](RELEASING.md) | Release checklist and CI/publishing steps | Deployment appendix to §7 |
+| [`docs/smoke-checklist.md`](smoke-checklist.md) | Manual verification script | QA appendix to §10 |
+| [`docs/development-status.md`](development-status.md) | Implemented features and current gaps | Status companion to the roadmap |
+| [`TODO.md`](../TODO.md) | Active tasks and v1.0.0 roadmap | Planning source; no architecture duplication |
+| [`docs/plan-graphics-v0.6.md`](plan-graphics-v0.6.md) | Historical v0.6 graphics program (completed) | Historical context; superseded by ADR-0013 and this document |
+| [`CHANGELOG.md`](../CHANGELOG.md) | User-facing release history | Release/version companion |
+
+Consolidation decisions:
+
+- **Architecture owns the "how"** (components, contracts, data flow, constraints, quality gates); **PLAN/gameplay own the "what"**; **ADRs own the "why"**. Links replace duplicated prose.
+- **Asset and release documents remain separate** because they are command-heavy operational procedures; their architecture-relevant contracts and failure modes are summarized in §5 and §7.
+- **`plan-graphics-v0.6.md` is historical, not a current plan.** The completed work is represented by ADR-0013, the asset pipeline section and the v0.6.0 changelog; new graphics work belongs in TODO, not a revived phase plan.
+- **Status and roadmap are separate from architecture.** `docs/development-status.md` records what exists; `TODO.md` records what remains, including the v1.0.0 gap analysis and milestone exit criteria.
+- **Documentation drift is a tracked risk:** release/version, test counts, renderer status, and stale plans must be corrected in the same commit as the change that invalidates them.
+
+## 13. Glossary

 - **Access artifact:** A wristband, ID, ticket, credential, or other item used to verify entry.
 - **Authorized person:** Someone permitted to enter under the current venue policy.
@@ -1,6 +1,10 @@
 # Asset Pipeline and Tooling

-Everything the game renders is produced or gated by the scripts below. Development-only outputs (AI concept sheets, Blender sources, raw AI fabrics) are gitignored; the audited game assets are committed.
+Everything the game renders is produced or gated by the scripts below. Architecture-level contracts,
+data flow and failure fallbacks are summarized in
+[`architecture.md`](architecture.md#content-and-asset-pipeline-architecture); this page is the
+operational reference. Development-only outputs (AI concept sheets, Blender sources, raw AI fabrics)
+are gitignored; the audited game assets are committed.

 ## Image Asset Tools

@@ -1,5 +1,8 @@
 # Blender asset library

+Architecture context: the asset contracts and fallback path are summarized in
+[`architecture.md`](architecture.md#content-and-asset-pipeline-architecture).
+
 Status: built, audited, and integrated (2026-11-01). `NpcAvatar` selects the
 character variants and attaches the gear; `WorldBuilder` loads the prop library
 with colliders and phase-driven emissives. See the Phase 3.5 integration in
@@ -159,10 +162,10 @@ exactly these points, which gives a quick visual check of the convention.
 | `marquee` | the procedural marquee | 6 m canopy and sign box; emissive `bulb` + `sign_face`. Overlay the text with the existing `Label3D` |
 | `sedan` | new (studio arrival) | 4.6 m; emissive `headlight`, red tail lamps |

-Props use plain PBR factors (base colour, roughness, metallic, emission) and
-have no textures. They are not yet AO-baked; that is still a Phase 4 task.
-Emissive materials are always on in the GLB. The integration should tie them to
-`WorldBuilder.set_night_mode()`.
+Props use plain PBR factors (base colour, roughness, metallic, emission) plus
+the committed 256² baked AO maps (`<name>_ao.png`) wired by `WorldBuilder`;
+emissive materials are tied to `WorldBuilder.set_night_mode()`. Characters
+carry baked AO and the shared neutral material maps described above.

 ## Checks

@@ -46,4 +46,4 @@ Implemented so far:
 - Venue geometry (v0.7.0): the Joke Shop now builds as a narrow brick alley with a warm wall lantern, shutters, dumpster/AC clutter and no skyline; the TV Studio builds a stone facade, bulb canopy, glossy black car and barrier line. `WorldBuilder.VENUE_SPECS` drives facade/street/nav dimensions, and `GameManager` rebuilds only the world container when the venue changes.
 - Gear fit (post-v0.6.0): Blender gear is measured against the avatar head/skirt silhouette and the checks run in both the Python tooling and the headless suite. Sunglasses, the shoulder bag and the firefighter helmet were fitted to the new faces; the Influencer portrait and gallery were recaptured with a before/after report.

-Not yet implemented: a desktop-only Forward+ preset (the renderer stays GL Compatibility for Web parity), live 3D body-camera replay, editor-based GUT integration, and crowd performance profiling/LOD (see [`TODO.md`](../TODO.md)).
+Current gaps for v1.0.0: onboarding/campaign progression, deeper authored content and NPC dialogue, mid-shift save/resume and replay, localization/accessibility expansion, voice/audio production, wider performance profiling, signed/notarized release packaging, and a unified Godot baseline. The full gap analysis and milestone plan live in [`TODO.md`](../TODO.md); the current architecture and documentation ownership map are in [`docs/architecture.md`](architecture.md).
@@ -1,7 +1,12 @@
 # Development Plan — Graphics Quality v0.6.0 (Blender-authored NPCs)

-> Status: Proposed · Target version: **v0.6.0** (MINOR)
+> Status: **Completed / historical** · Target version: **v0.6.0** (MINOR), followed by
+> v0.7.1's optional Forward+ Desktop HQ build
 > Companion decision: [ADR-0013](adr/0013-blender-authored-npc-characters.md)
+>
+> This is an implementation-history document. The current architecture is in
+> [`architecture.md`](architecture.md); remaining graphics work is tracked in
+> [`TODO.md`](../TODO.md), not as a revived phase plan.

 ## Why this exists

@@ -242,9 +247,9 @@ Props are grounded except `wall_lantern` and `marquee`; both may be emissive.
 2. **Higher-resolution environment textures:** regenerate brick/concrete/asphalt
   through `asset_pipeline.py` with normal maps, keeping the current UV scales;
   use the same sRGB/albedo + packed ORM discipline as the library assets.
-3. **Evaluate a desktop-only Forward+ preset** — done: it boots on the desktop Vulkan
-driver, but the renderer is project-wide and the Web preset must stay GL
-Compatibility. v0.6.0 keeps Compatibility; a desktop-only override is deferred.
+3. **Evaluate a desktop-only Forward+ preset** — completed in v0.7.1 as the optional
+Desktop HQ zip. The default renderer stays GL Compatibility for Web parity; the
+override is applied only to the copied HQ binaries.
 4. Regenerate `docs/screenshots/` with `capture_screenshots.gd`, then run
   `screen_designs.py compare` and `judge` as the regression gate, plus
   `blender_assets.py sheet` for the character/gear/prop library.