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.

docs/RELEASING.md

@@ -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.

docs/architecture.md

@@ -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.

docs/asset-tooling.md

@@ -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
 

docs/blender-assets.md

@@ -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
 

docs/development-status.md

@@ -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).

docs/plan-graphics-v0.6.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.