diff --git a/.agents/skills/gig-line-blender-asset-contract/SKILL.md b/.agents/skills/gig-line-blender-asset-contract/SKILL.md
index 5d7c0e4..38e985f 100644
--- a/.agents/skills/gig-line-blender-asset-contract/SKILL.md
+++ b/.agents/skills/gig-line-blender-asset-contract/SKILL.md
@@ -24,7 +24,7 @@ The project contract and measured gates override any generic Blender advice.
Blender MCP is optional interactive tooling; the headless flatpak CLI remains
authoritative and CI never needs Blender or MCP. The `blender-skills` pack is
optional, local guidance only, and gitignored. Setup and safety are in
-`docs/asset-tooling.md#optional-interactive-blender-mcp`.
+`docs/assets/asset-tooling.md#optional-interactive-blender-mcp`.
## Read first
@@ -33,11 +33,11 @@ skill alone:
1. `AGENTS.md` — required workflow and verification.
2. `TODO.md` and `MEMORY.md` — current track, claimed tasks, known gotchas.
-3. `docs/blender-assets.md` — library contract and command reference.
-4. `docs/asset-tooling.md` — exact rebuild/bake/capture commands.
-5. `docs/npc-model-sourcing.md` and `docs/3d-model-review.md` — accepted limits,
+3. `docs/assets/blender-assets.md` — library contract and command reference.
+4. `docs/assets/asset-tooling.md` — exact rebuild/bake/capture commands.
+5. `docs/assets/npc-model-sourcing.md` and `docs/assets/3d-model-review.md` — accepted limits,
scorecards and known blockers.
-6. `docs/known-limitations.md` — limits that must not be silently “fixed” into
+6. `docs/design/known-limitations.md` — limits that must not be silently “fixed” into
contract changes.
The contract lives in code and docs, not in this skill. If they disagree, stop
@@ -114,7 +114,7 @@ only the specialists the task needs:
- budget/LOD/collision: `asset-optimization`, `lod-pipeline`, `collision-proxy`
- final review: `qa-review`
-If MCP is available, use it for interactive part exploration only; mirror the result into a scripted change or local `.blend`, then re-export and run the CLI audit/fit gates. Never make the build, CI, tests or runtime depend on MCP. Setup: `docs/asset-tooling.md#optional-interactive-blender-mcp`.
+If MCP is available, use it for interactive part exploration only; mirror the result into a scripted change or local `.blend`, then re-export and run the CLI audit/fit gates. Never make the build, CI, tests or runtime depend on MCP. Setup: `docs/assets/asset-tooling.md#optional-interactive-blender-mcp`.
### 4. Build or bake
@@ -185,7 +185,7 @@ gates run, and any accepted limit.
- **Empty or stale captures** — close modals/pause, check the capture script's
settle frames, and remove stale output directories before re-running.
- **Pose harness mismatch** — the current `capture_npc_pose.gd` is blocked per
- `docs/3d-model-review.md`; do not use its frames as pose evidence until the
+ `docs/assets/3d-model-review.md`; do not use its frames as pose evidence until the
recipe is fixed.
- **Asset test fails after import** — re-run audit/fit first, then import; if the
manifest or AO path changed, rebuild the affected asset rather than editing
@@ -197,7 +197,7 @@ gates run, and any accepted limit.
- [`references/asset-contract.md`](references/asset-contract.md) — full contract,
inventory, file locations and provenance rules.
-- `docs/asset-tooling.md#optional-interactive-blender-mcp` — optional MCP installation, connection, safety and
+- `docs/assets/asset-tooling.md#optional-interactive-blender-mcp` — optional MCP installation, connection, safety and
part-workflow instructions.
- [`references/verification.md`](references/verification.md) — command matrix,
capture gates, expected results and acceptance criteria.
diff --git a/.agents/skills/gig-line-blender-asset-contract/references/asset-contract.md b/.agents/skills/gig-line-blender-asset-contract/references/asset-contract.md
index 55204be..537c43a 100644
--- a/.agents/skills/gig-line-blender-asset-contract/references/asset-contract.md
+++ b/.agents/skills/gig-line-blender-asset-contract/references/asset-contract.md
@@ -1,7 +1,7 @@
# Asset Contract Reference
This is a working summary. The authoritative sources remain
-`docs/blender-assets.md`, `docs/asset-tooling.md`, ADR-0013, the tests in
+`docs/assets/blender-assets.md`, `docs/assets/asset-tooling.md`, ADR-0013, the tests in
`src/test/tests/` and the constants in `tools/blender_assets.py` /
`tools/npc_pipeline.py`.
diff --git a/.agents/skills/gig-line-blender-asset-contract/references/verification.md b/.agents/skills/gig-line-blender-asset-contract/references/verification.md
index 08af6ee..758425e 100644
--- a/.agents/skills/gig-line-blender-asset-contract/references/verification.md
+++ b/.agents/skills/gig-line-blender-asset-contract/references/verification.md
@@ -113,8 +113,8 @@ For each changed variant, inspect at least:
- Day and night/LATE final-context frames.
- Front, three-quarter and profile for a shape change.
-Accepted stylized limits are in `docs/3d-model-review.md` and
-`docs/known-limitations.md`. Do not turn an accepted limit into an unreviewed
+Accepted stylized limits are in `docs/assets/3d-model-review.md` and
+`docs/design/known-limitations.md`. Do not turn an accepted limit into an unreviewed
contract change.
## Final diff review
diff --git a/.agents/skills/gig-line-release-qa/SKILL.md b/.agents/skills/gig-line-release-qa/SKILL.md
index 096510c..c5dcb2f 100644
--- a/.agents/skills/gig-line-release-qa/SKILL.md
+++ b/.agents/skills/gig-line-release-qa/SKILL.md
@@ -19,9 +19,9 @@ publishing, and the full visual/QA gate. For a Blender/asset rebuild, use
1. `AGENTS.md` — release procedure and verification rules.
2. `TODO.md` — current milestone, blockers and release exit criteria.
-3. `docs/RELEASING.md` — build/publish commands, artifact list, macOS policy.
-4. `docs/release-qa.md` — manual QA matrix and balance protocol.
-5. `docs/development-status.md`, `CHANGELOG.md`, `README.md` — current claims.
+3. `docs/process/RELEASING.md` — build/publish commands, artifact list, macOS policy.
+4. `docs/process/release-qa.md` — manual QA matrix and balance protocol.
+5. `docs/project/development-status.md`, `CHANGELOG.md`, `README.md` — current claims.
6. `MEMORY.md` — release gotchas, especially the clean-worktree rule.
A release is not just a tag. It includes a version bump, changelog, clean build,
@@ -58,8 +58,8 @@ Update:
1. `project.godot` `config/version`.
2. `CHANGELOG.md` with a dated entry.
-3. `README.md`, `PLAN.md`, `docs/architecture.md`,
- `docs/development-status.md`, `TODO.md`/`DONE.md` and `MEMORY.md` as needed.
+3. `README.md`, `PLAN.md`, `docs/project/architecture.md`,
+ `docs/project/development-status.md`, `TODO.md`/`DONE.md` and `MEMORY.md` as needed.
For a release candidate, use a prerelease version only if the project policy
allows it and never present it as the final release.
@@ -213,7 +213,7 @@ The default `RETAIN_RELEASES=0` never prunes.
### 7. Post-release record
-Update `README.md`, `docs/development-status.md`, `MEMORY.md`, `CHANGELOG.md`,
+Update `README.md`, `docs/project/development-status.md`, `MEMORY.md`, `CHANGELOG.md`,
`TODO.md`/`DONE.md` and the release page with the built/CI result. Commit the
release record and push. Record any skipped check and the reason; never leave a
tag with unreported missing verification.
diff --git a/.agents/skills/gig-line-release-qa/references/qa-gates.md b/.agents/skills/gig-line-release-qa/references/qa-gates.md
index 4971929..230ea3d 100644
--- a/.agents/skills/gig-line-release-qa/references/qa-gates.md
+++ b/.agents/skills/gig-line-release-qa/references/qa-gates.md
@@ -93,7 +93,7 @@ python3 tools/screen_designs.py judge --model auto
```
Record model, confidence/verdict summary, `diff` count and any manual review.
-`docs/ui-copy.md#screen-design-judge-report` is the durable record.
+`docs/design/ui-copy.md#screen-design-judge-report` is the durable record.
## 6. Realism judge (when visual assets/lighting changed)
diff --git a/.agents/skills/gig-line-release-qa/references/release-runbook.md b/.agents/skills/gig-line-release-qa/references/release-runbook.md
index 125907c..7a50f9e 100644
--- a/.agents/skills/gig-line-release-qa/references/release-runbook.md
+++ b/.agents/skills/gig-line-release-qa/references/release-runbook.md
@@ -1,6 +1,6 @@
# Release Runbook
-Authoritative source: `AGENTS.md` (Release Procedure), `docs/RELEASING.md`.
+Authoritative source: `AGENTS.md` (Release Procedure), `docs/process/RELEASING.md`.
This runbook is the operational checklist; if it conflicts with those, they win.
## 0. Decide the release
@@ -29,8 +29,8 @@ Files to update:
| `project.godot` | `config/version="X.Y.Z"` |
| `CHANGELOG.md` | dated `## [X.Y.Z] — YYYY-MM-DD` entry |
| `README.md` | latest/current version and summary |
-| `PLAN.md` / `docs/architecture.md` | current version reference |
-| `docs/development-status.md` | shipped capability/release result |
+| `PLAN.md` / `docs/project/architecture.md` | current version reference |
+| `docs/project/development-status.md` | shipped capability/release result |
| `TODO.md` / `DONE.md` | close/move milestone when complete |
| `MEMORY.md` | release state and gotchas |
diff --git a/AGENTS.md b/AGENTS.md
index f7f7f1c..751721c 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -15,15 +15,15 @@ The project should be developed in small, reviewable steps. Agents must keep pla
- `README.md` — Root-level documentation for the project. It should explain what the game is, how to work on it, how to run it, and where to find project information.
- `AGENTS.md` — This collaboration and agent workflow guide.
- `CHANGELOG.md` — The version history of user-facing changes. Keep an entry for each patch, minor, and major version.
-- `docs/development-status.md` — The implemented-features list and what is not yet implemented. Update it whenever a feature lands, is renamed, or is removed.
-- `docs/architecture.md` — The arc42-style architecture documentation (goals, constraints, building blocks, runtime views, decisions, risks).
-- `docs/gameplay.md` — Gameplay systems, tutorial, venues and the escalation model.
-- `docs/venues.md` — Real-site evidence, game mapping and venue simplifications.
-- `docs/asset-tooling.md` — Asset pipelines, model tools, optional Blender MCP and screenshot gates.
-- `docs/blender-assets.md` — Blender library operation and asset roles.
-- `docs/npc-model-sourcing.md` — Character-source evaluation, licence rules and the character-development plan.
-- `docs/getting-started.md` — Setup, run/test commands, and the controls table.
-- `docs/release-qa.md` — The manual smoke checklist and balance-acceptance protocol.
+- `docs/project/development-status.md` — The implemented-features list and what is not yet implemented. Update it whenever a feature lands, is renamed, or is removed.
+- `docs/project/architecture.md` — The arc42-style architecture documentation (goals, constraints, building blocks, runtime views, decisions, risks).
+- `docs/design/gameplay.md` — Gameplay systems, tutorial, venues and the escalation model.
+- `docs/design/venues.md` — Real-site evidence, game mapping and venue simplifications.
+- `docs/assets/asset-tooling.md` — Asset pipelines, model tools, optional Blender MCP and screenshot gates.
+- `docs/assets/blender-assets.md` — Blender library operation and asset roles.
+- `docs/assets/npc-model-sourcing.md` — Character-source evaluation, licence rules and the character-development plan.
+- `docs/process/getting-started.md` — Setup, run/test commands, and the controls table.
+- `docs/process/release-qa.md` — The manual smoke checklist and balance-acceptance protocol.
- `docs/adr/` — Architecture Decision Records.
## Priority and Versioning
@@ -102,7 +102,7 @@ specialists the task needs:
the change is explicitly planned and the contract, tests and docs are updated together.
2. **Blender MCP is optional interactive tooling.** The headless flatpak scripts
(`tools/blender_assets.py`, `tools/npc_pipeline.py`) remain authoritative. MCP may be used
- for local part exploration; setup and safety are in [`docs/asset-tooling.md#optional-interactive-blender-mcp`](docs/asset-tooling.md#optional-interactive-blender-mcp).
+ for local part exploration; setup and safety are in [`docs/assets/asset-tooling.md#optional-interactive-blender-mcp`](docs/assets/asset-tooling.md#optional-interactive-blender-mcp).
Never add an MCP dependency to the build, CI, tests or runtime, and always re-run the CLI
audit/fit gates on anything MCP touched.
3. **CI stays offline and skill-free.** Skills are local guidance only; every gate must still
@@ -110,7 +110,7 @@ specialists the task needs:
4. **No new asset source without the licence gate.** Skills may suggest reference packs or
generated meshes; ADR-0017 (the CC0 Quaternius NPC base) supersedes the generator-first
decision in ADR-0015, and the CC0/CC-BY rule in ADR-0015 (attribution in `CREDITS.md`) plus
- the provenance rules in `docs/npc-model-sourcing.md` still apply to any new source.
+ the provenance rules in `docs/assets/npc-model-sourcing.md` still apply to any new source.
5. **Evidence, not vibes.** After a skill-informed change, run `blender_assets.py inspect`,
`audit` and `fit` plus the relevant capture/smoke gates, and say in the handoff which
skills informed the change and what the measurements were.
@@ -196,7 +196,7 @@ first, then versioned milestones in version order, then future/deferred work.
level-3 section to `DONE.md`.
2. **Level-2 milestone/theme:** it is complete only when its direct checkboxes and **all** of its
level-3 workstreams are complete. Verify the whole milestone, record its capabilities in
- `docs/development-status.md` when it represents shipped functionality, and write the matching
+ `docs/project/development-status.md` when it represents shipped functionality, and write the matching
`CHANGELOG.md` entry.
3. Move the **entire level-2 section**, including all level-3 headings and checklists, to
`DONE.md`. Remove it from `TODO.md` and add a completion date/note.
@@ -207,7 +207,7 @@ first, then versioned milestones in version order, then future/deferred work.
complete, or split the unfinished work into a new smaller level-2 milestone first.
When a completed milestone represents shipped functionality, also record the new capability in
-`docs/development-status.md` so the implemented-features list stays accurate, and write a matching
+`docs/project/development-status.md` so the implemented-features list stays accurate, and write a matching
entry in `CHANGELOG.md` (see "Maintain `CHANGELOG.md`" below).
### 4. Maintain `MEMORY.md`
@@ -217,7 +217,7 @@ Use `MEMORY.md` for information that should persist between sessions but does no
Record items such as:
- Important design and architecture decisions
-- Notable implementation state and gotchas (the canonical implemented-features list lives in `docs/development-status.md`, not here)
+- Notable implementation state and gotchas (the canonical implemented-features list lives in `docs/project/development-status.md`, not here)
- Known bugs and workarounds
- Commands needed to run, test, or build the project
- Decisions that future agents should not revisit unnecessarily
@@ -267,7 +267,7 @@ The root-level `README.md` is the project’s public-facing technical and projec
- Links to `PLAN.md`, `TODO.md`, `DONE.md`, `MEMORY.md`, and this file where appropriate
- Known limitations and contribution guidance
-Update `README.md` whenever setup instructions, commands, project structure, or user-facing behavior changes. The README is intentionally concise and links to the `docs/` files; keep `docs/development-status.md` (and the other docs it links to) synchronized with the implementation rather than pasting detail back into the README.
+Update `README.md` whenever setup instructions, commands, project structure, or user-facing behavior changes. The README is intentionally concise and links to the `docs/` files; keep `docs/project/development-status.md` (and the other docs it links to) synchronized with the implementation rather than pasting detail back into the README.
### 7. Maintain `CHANGELOG.md`
@@ -297,7 +297,7 @@ For each task:
2. Inspect the relevant files and dependencies.
3. Make the smallest coherent change that completes the task.
4. Run the relevant tests, checks, or manual verification.
-5. Update documentation if the change creates lasting context: add features to `docs/development-status.md`, adjust the README links or other `docs/` files as needed, and record decisions/gotchas in `MEMORY.md`.
+5. Update documentation if the change creates lasting context: add features to `docs/project/development-status.md`, adjust the README links or other `docs/` files as needed, and record decisions/gotchas in `MEMORY.md`.
6. Mark the task complete.
7. Keep completed level-3 workstreams in place until the parent milestone is complete; then move the entire level-2 milestone to `DONE.md` after recording its `CHANGELOG.md` entry.
8. Commit each coherent, verified change as it is completed. Do not wait until a whole
diff --git a/CREDITS.md b/CREDITS.md
index 2402d72..17ca582 100644
--- a/CREDITS.md
+++ b/CREDITS.md
@@ -16,7 +16,7 @@ been cleared for public distribution.
## 3D characters, gear and props
The local MakeHuman head prototype uses the CC0 MakeHuman/MPFB base mesh
-(see [`docs/makehuman-head-review.md`](docs/makehuman-head-review.md)); it is a
+(see [`docs/assets/makehuman-head-review.md`](docs/assets/makehuman-head-review.md)); it is a
development prototype, not a shipped character.
The character, gear and prop library is generated by project-owned scripts
@@ -53,7 +53,7 @@ CC0 1.0). It is cut, retopologised and re-weighted by project scripts; the expor
character GLBs remain project assets. The development source files were removed
from `tmp/` after the 2026-11-05 pivot to Quaternius. The head is retained as a
tested fallback, not the active NPC base. See ADR-0017 and
-`docs/npc-model-sourcing.md`.
+`docs/assets/npc-model-sourcing.md`.
### Quaternius NPC base source
@@ -61,7 +61,7 @@ The active NPC base migration uses **Quaternius Ultimate Modular Characters** an
**Ultimate Modular Women** (CC0 1.0, ). The three
researched GLBs are development inputs and are not shipped directly; the baked,
retargeted character GLBs are project assets. See ADR-0017 and
-`docs/npc-model-sourcing.md` for the decision, source hashes and rollout status.
+`docs/assets/npc-model-sourcing.md` for the decision, source hashes and rollout status.
The venue geometry is authored procedurally in `src/game/world_builder.gd` as a
stylized reconstruction. The Joke Shop is a fictional stand-in for the real
@@ -118,7 +118,7 @@ reference more directly, its attribution and licence must be added here.
All runtime audio is procedural (crowd bed, radio crackle and interface cues).
There are no external audio files, so there is no separate music/SFX licence to
-clear. See `docs/accessibility.md` for caption and volume behaviour.
+clear. See `docs/design/accessibility.md` for caption and volume behaviour.
## Third-party names
diff --git a/DONE.md b/DONE.md
index 069611c..d48ec2c 100644
--- a/DONE.md
+++ b/DONE.md
@@ -137,7 +137,7 @@ Completed task sections moved from `TODO.md`. Sections are moved only when every
- [x] Commit `export_presets.cfg` with Linux, Windows, and macOS desktop presets.
- [x] Add `tools/build_releases.sh` for headless release exports.
-- [x] Add `docs/RELEASING.md` with template installation, build, and Gitea release steps.
+- [x] Add `docs/process/RELEASING.md` with template installation, build, and Gitea release steps.
- [x] Add a prominent **Downloads** section at the top of `README.md` linking to the release page.
- [x] Add `tools/publish_release.sh` (Gitea API release + asset upload, requires `GITEA_TOKEN`).
@@ -149,7 +149,7 @@ Completed task sections moved from `TODO.md`. Sections are moved only when every
- [x] Tag builds automatically publish the Gitea release via `tools/publish_release.sh` using
the `GITEA_TOKEN` secret.
- [x] Remove the old `.github/workflows/ci.yml` to avoid double runs on hosts scanning both paths.
-- [x] Document the CI flow in `docs/RELEASING.md`.
+- [x] Document the CI flow in `docs/process/RELEASING.md`.
## Gameplay — Venue selection
@@ -249,7 +249,7 @@ Completed task sections moved from `TODO.md`. Sections are moved only when every
service; ~2 min of retry timeouts per run; Godot import is fast without it).
- [x] Add `GODOT_SILENCE_ROOT_WARNING=1` to both jobs.
- [x] Confirmed in run 1090: zero `CacheService` lines, 54/54 tests pass, job succeeds.
-- [x] Document the cache situation and re-enable path in `docs/RELEASING.md`.
+- [x] Document the cache situation and re-enable path in `docs/process/RELEASING.md`.
- [x] Ignore runner logs in `.gitignore` (`.gitea/logs/`).
## Gameplay — Venue door-staff dialogue
@@ -660,7 +660,7 @@ produces a 63 MB static bundle and it serves locally with HTTP 200s for html/was
- [x] Publish the web zip with the desktop artifacts (`tools/publish_release.sh`).
- [x] Cover the preset, the non-threaded choice, and the release wiring in
`src/test/tests/test_web_export.gd`.
-- [x] Document the artifact in `docs/RELEASING.md`, the README gallery/status, and `PLAN.md`.
+- [x] Document the artifact in `docs/process/RELEASING.md`, the README gallery/status, and `PLAN.md`.
## Prop Texture Atlas
@@ -909,7 +909,7 @@ Goal: replace the outdated flat skyline backdrop (`assets/textures/skyline.png`,
with dot windows) and the flat-looking surface tiles with AI-generated, more realistic
backgrounds and textures. Add a larger set of example 3D scene images as art direction, and
measure the in-game result against that target with the screenshot tools. Plan:
-[`PLAN.md` → Visual Quality Direction → Realism pass](PLAN.md#realism-pass).
+[`PLAN.md` → Visual Quality Direction → Realism pass](PLAN.md#presentation-and-controls).
**Rule for every step: never overwrite an existing image.** New outputs get new paths. When a
path is taken, the tools pick the next free `-vN` suffix. Raw AI output stays on disk under
@@ -1047,7 +1047,7 @@ reports to `docs/screens/realism//`.
`docs/screens/realism/2026-11-01-adopt/` (3 judge repeats per shot) gives a like-for-like
improvement on every sub-score: overall 0.8→1.0, lighting 0.8→1.0, materials 0.8→1.0,
texture 0.8→1.0, backdrop 0.6→1.6, and the Pillow metric gap 0.444→0.348.
-- [x] Update `README.md` (tool usage + gallery), `MEMORY.md` and `docs/architecture.md`.
+- [x] Update `README.md` (tool usage + gallery), `MEMORY.md` and `docs/project/architecture.md`.
## Realism Follow-ups — Lighting, Flashlight, NPC Detail
@@ -1087,7 +1087,7 @@ Completed 2026-11-01. The follow-ups left over after the texture/skyline adoptio
bridge and tip, ears with lobes, and split upper/lower lips. Hands have four fingers plus a
thumb, and every sleeve ends in a cuff ring.
- [x] Raised `CHAR_MAX_VERTS` 4000 → **5000** (documented in the code and
- `docs/blender-assets.md`) after measuring 16 avatars at ~6.9 ms of a 50 ms frame on a single
+ `docs/assets/blender-assets.md`) after measuring 16 avatars at ~6.9 ms of a 50 ms frame on a single
skinned mesh, so `npc_coat` fits at 4807 vertices; the character range is now 3,974–5,026
triangles and 3,744–4,807 vertices. Body decimation 0.36 → 0.26.
- [x] Rebuilt all 8 variants and re-baked their AO maps (`assets/models/blender/npc/*_ao.png`),
@@ -1114,14 +1114,14 @@ Completed 2026-11-01.
- [x] Decide the canonical runtime image root (`assets/images/` for UI/scene art): recorded in
`MEMORY.md` and [ADR-0014](docs/adr/0014-runtime-image-root.md).
- [x] Move the reference mockups from `docs/screens/designs/` into the runtime root (keep `docs/screens/designs/` as a docs-only copy or replace it with the new path).
-- [x] Document one convention for game vs reference vs development images across `assets/textures/`, `assets/images/`, `assets/models/generated/`, `docs/screenshots/`, and `docs/screens/designs/` (in `docs/architecture.md`, ADR-0014).
+- [x] Document one convention for game vs reference vs development images across `assets/textures/`, `assets/images/`, `assets/models/generated/`, `docs/screenshots/`, and `docs/screens/designs/` (in `docs/project/architecture.md`, ADR-0014).
- [x] Re-run `godot --headless --path . --import` to regenerate `.import` sidecars after any move.
- [x] Confirm `.gitignore` still excludes development-only outputs (concepts, Blender sources, raw AI fabrics) under the new layout; Blender `.blend` sources are now untracked and ignored.
### Documentation path updates
- [x] Update `README.md` paths (screen-designs section, confirmed-assets links, the `assets/images/scenes` resize example).
-- [x] Update `docs/architecture.md`, `PLAN.md`, and ADR references: docs/screens/designs/ is now explicitly the reference-only snapshot; runtime art lives in assets/images/ (ADR-0014).
+- [x] Update `docs/project/architecture.md`, `PLAN.md`, and ADR references: docs/screens/designs/ is now explicitly the reference-only snapshot; runtime art lives in assets/images/ (ADR-0014).
- [x] Update `tools/screen_designs.py` docstrings and mark the old paths in `DONE.md` as historical.
### Code path updates
@@ -1188,7 +1188,7 @@ architecture's version, runtime-art loader, asset/tooling blocks, Gitea CI/build
Web deployment and release artifact list were brought up to date. `MEMORY.md` was cleaned of
obsolete uncommitted/active-pass claims and now points at the current follow-ups.
-- [x] Re-check `PLAN.md`/`MEMORY.md` against the current build, update `README.md` and `docs/architecture.md`, and compact the historical PLAN sections.
+- [x] Re-check `PLAN.md`/`MEMORY.md` against the current build, update `README.md` and `docs/project/architecture.md`, and compact the historical PLAN sections.
## NPC gear fit (v0.6.1)
@@ -1197,7 +1197,7 @@ Completed 2026-11-01. Eyes, bag and helmet now fit the measured body silhouette;
The 2026-11-01 detail pass fixed the bodies but not the props worn on them. In the portrait
capture (`--stages=day,portrait`, see the report in `docs/screens/realism/2026-11-01-npc/`) the
sunglasses span the whole upper face and the shoulder bag cuts through `npc_coat`'s skirt. Blender sources for gear
-live in `tools/blender_assets.py` (`_build_gear()`), the contract in `docs/blender-assets.md`
+live in `tools/blender_assets.py` (`_build_gear()`), the contract in `docs/assets/blender-assets.md`
(gear budget 1500 tris, `GEAR_ATTACH` points in `NpcAvatar`).
- [x] Measure the fit in Blender, not by eye: `python3 tools/blender_assets.py fit` prints each
@@ -1270,7 +1270,7 @@ have no stage in the committed `docs/screenshots/` gallery, only in `capture_rea
`src/test/capture_screenshots.gd` (`12-joke-shop.png`, `13-studio-arrival.png`) reuse the
existing `joke_shop_queue` / `studio_arrival` designs. `check_screenshots.sh` is **13 good /
0 bad**; the new screenshots are 18.2 / 32.6 MAE against their references.
-- [-] Update `docs/architecture.md` (venue geometry), `README.md` (gallery) and the screenshot
+- [-] Update `docs/project/architecture.md` (venue geometry), `README.md` (gallery) and the screenshot
table when the stages land.
## Forward+ desktop preset and a volumetric flashlight (v0.7.1)
@@ -1296,7 +1296,7 @@ path.
dirs) and record the diff in `docs/screens/realism/2026-11-01-forward-plus/`: entrance
metric gap 1.568 → 1.187, two-shot mean 0.907 → 0.723. Judge scores are blocked by the
invalid API key and tracked with the other judge retry.
-- [x] Add the preset to `tools/build_releases.sh` and `docs/RELEASING.md` as an optional
+- [x] Add the preset to `tools/build_releases.sh` and `docs/process/RELEASING.md` as an optional
"desktop HQ" artifact, and note the runtime requirement (Vulkan driver) in `README.md`.
`gig-line-desktop-hq-.zip` packages the Linux/Windows binaries, override.cfg and
README; `publish_release.sh` uploads it when present.
@@ -1327,7 +1327,7 @@ back when a provider rejects a request.
- [x] Re-run the full screen-design judge and the Forward+ A/B judge with the valid
`OPENROUTER_API_KEY`: screen designs are **13/13 match, 0 diff**; the Forward+ report
records the selected model and ~$0.006 spend.
-- [x] Update `docs/asset-tooling.md`, `MEMORY.md`, `README.md` and `CHANGELOG.md`; the
+- [x] Update `docs/assets/asset-tooling.md`, `MEMORY.md`, `README.md` and `CHANGELOG.md`; the
public catalogue picks the cheapest image+JSON model (`z-ai/glm-5.3-flash` at run time).
## Milestone 0.8.0 — First hour and content depth
@@ -1343,7 +1343,7 @@ venues, and see enough authored variety that a second shift does not feel like a
- [x] Write the tutorial beat sheet: menu → movement/look → focus and target cycling → action
wheel → access inspection → polite direction → formal warning/body camera → radio →
shift review. Eight beats and a safe compliant visitor are specified in
- [`docs/gameplay.md#first-shift-tutorial`](docs/gameplay.md#first-shift-tutorial).
+ [`docs/design/gameplay.md#first-shift-tutorial`](docs/design/gameplay.md#first-shift-tutorial).
- [x] Add a tutorial state machine independent of the normal shift FSM. `Tutorial` in
`src/game/tutorial.gd` owns the eight beats, accepts only the current beat's action,
supports skip/restart and has deterministic headless tests. GameManager/UI wiring starts
@@ -1544,7 +1544,7 @@ and supported by a stable CI/release baseline.
- [x] Existing scenario-content, tutorial and campaign smokes cover the venue/action/review paths;
the 0.9.5 release candidate adds the external first-hour pass.
-- [x] `docs/getting-started.md` and `docs/release-qa.md#manual-smoke-checklist` list tutorial, campaign/checkpoint,
+- [x] `docs/process/getting-started.md` and `docs/process/release-qa.md#manual-smoke-checklist` list tutorial, campaign/checkpoint,
session, scenario, audio, crowd, emergency, movement and performance smokes.
- [x] Current gallery/judge baselines are green; the 0.9.5 release candidate refreshes the final
gallery after content lock.
@@ -1560,7 +1560,7 @@ and supported by a stable CI/release baseline.
smoke requirement. This explicit matrix is documented.
- [x] No project-wide upgrade in 0.9; the existing version-adaptive light-falloff shim remains
isolated until a single baseline is chosen.
-- [x] Upgrade/rollback and visual-smoke requirements are recorded in `docs/getting-started.md`
+- [x] Upgrade/rollback and visual-smoke requirements are recorded in `docs/process/getting-started.md`
and `MEMORY.md`.
- [ ] Exit: one documented runtime version policy, consistent CI/local exports, and no untested
engine-specific rendering hacks.
@@ -1589,7 +1589,7 @@ Goal: streamline the maps, refactor geometry to match the images in `docs/screen
- [x] Remove unnecessary or hidden geometry to improve performance.
- [x] Ensure texture and material consistency across the map.
-Completed: the Hollywood venue is rebuilt from the real 6840 Hollywood Blvd references (six-column Masonic/El Capitan facade, eight steps, neighbours, Ovation arcade, Walk of Fame, four-lane street). The map-budget test measures 58,884 triangles across 409 meshes; Day/Night menu variants start in `EARLY`/`LATE`; the realism judge gaps are 0.148 (day) and 0.278 (late). See `docs/venues.md#hollywood-boulevard`.
+Completed: the Hollywood venue is rebuilt from the real 6840 Hollywood Blvd references (six-column Masonic/El Capitan facade, eight steps, neighbours, Ovation arcade, Walk of Fame, four-lane street). The map-budget test measures 58,884 triangles across 409 meshes; Day/Night menu variants start in `EARLY`/`LATE`; the realism judge gaps are 0.148 (day) and 0.278 (late). See `docs/design/venues.md#hollywood-boulevard`.
### Map 2 — Joke Shop
@@ -1601,7 +1601,7 @@ Completed: the Hollywood venue is rebuilt from the real 6840 Hollywood Blvd refe
- [x] Remove unnecessary or hidden geometry to improve performance.
- [x] Ensure texture and material consistency across the map.
-Completed 2026-11-02: the Joke Shop is rebuilt from the real Comedy Store block at 8433 Sunset Blvd (27 m black hall, signature canopy, circular blade sign, red curtains, west entrance, low-rise neighbours, dry hillside and opposite frontage). The map-budget test measures 22,680 triangles across 454 meshes. The day/late captures and real-site notes are in `docs/venues.md#the-joke-shop` and `docs/screens/concepts/joke_shop/`; the final gallery passed 13 good / 0 bad and the screen-design judge (13/13 match, 0 diff), with a 0.454 realism gap on the photoreal night reference.
+Completed 2026-11-02: the Joke Shop is rebuilt from the real Comedy Store block at 8433 Sunset Blvd (27 m black hall, signature canopy, circular blade sign, red curtains, west entrance, low-rise neighbours, dry hillside and opposite frontage). The map-budget test measures 22,680 triangles across 454 meshes. The day/late captures and real-site notes are in `docs/design/venues.md#the-joke-shop` and `docs/screens/concepts/joke_shop/`; the final gallery passed 13 good / 0 bad and the screen-design judge (13/13 match, 0 diff), with a 0.454 realism gap on the photoreal night reference.
### Scenery Change (Day/Night) for Hollywood Boulevard
@@ -1646,7 +1646,7 @@ redesign.
- [x] Do not run the release build, bump a release version or tag until the map exit criteria and
this NPC revisit are both signed off.
-- [x] Record the sign-off in `docs/development-status.md` and `MEMORY.md`, then hand off to the
+- [x] Record the sign-off in `docs/project/development-status.md` and `MEMORY.md`, then hand off to the
postponed integration/build milestone.
**Exit:** the final maps and lighting still present the NPCs clearly; no untriaged NPC regression
@@ -1663,20 +1663,20 @@ screen-design judge before any model/texture changes. No gameplay rules change.
- [x] Inventory every screen/panel: start menu, venue menu, tutorial, HUD, pause,
settings, Help, inspection, wand, radio/emergency, wheel, shift review,
- timeline and campaign/continue screens. Recorded in `docs/ui-copy.md`.
+ timeline and campaign/continue screens. Recorded in `docs/design/ui-copy.md`.
- [x] Record the canonical terms for admit/refuse, warning/blocking,
assistance/emergency, body camera, shift review and campaign; the current
- inspection/wand/radio/review labels use them (see `docs/ui-copy.md`).
+ inspection/wand/radio/review labels use them (see `docs/design/ui-copy.md`).
- [x] Audit all button labels for verb-first wording, capitalization, ordering,
destructive-action confirmation and consistent confirm/cancel placement;
- recorded in `docs/ui-copy.md` and fixed Quit/Apply wording.
+ recorded in `docs/design/ui-copy.md` and fixed Quit/Apply wording.
- [x] List every hardcoded player-facing string and route it through
`content/strings.en.json`; remaining UI literals are numeric/debug-only or
dynamic data. Placeholder validation covers the new keys.
- [x] Review NPC/door-staff/radio/tutorial/help/review/campaign dialogue for
repetition, ambiguity, tone and localization length. (Reason contexts,
door-staff lines, radio/tutorial/help copy and length findings recorded in
- `docs/ui-copy.md`; longest dialogue line is 56 characters.)
+ `docs/design/ui-copy.md`; longest dialogue line is 56 characters.)
### Button and panel behavior
@@ -1684,15 +1684,15 @@ screen-design judge before any model/texture changes. No gameplay rules change.
tutorial skip, venue continue, settings apply/cancel/reset, judge/review,
radio send/emergency hold and Help close. (Shared `UiStyles` states applied;
timeline boundary disabling and the keyboard-only F1 skip are documented in
- `docs/ui-copy.md`.)
+ `docs/design/ui-copy.md`.)
- [x] Verify keyboard-only and gamepad-only navigation: focus order, wrapping,
default focus, confirm/cancel behavior and no focus traps. (Focus rings,
gamepad A/B UI bindings, default focus and per-modal cancel behavior are
- recorded in `docs/ui-copy.md`.)
+ recorded in `docs/design/ui-copy.md`.)
- [x] Verify every modal closes with Esc/right-click where documented, recaptures
the mouse, and does not leave the guard frozen or the menu visible. (Single
top-modal close path, menu/settings return handling and pointer recapture are
- recorded in `docs/ui-copy.md`; session smoke covers menu Settings, Help
+ recorded in `docs/design/ui-copy.md`; session smoke covers menu Settings, Help
right-click and pause Settings.)
- [x] Test buttons at minimum/maximum HUD font scale and with 1.5–2× longer
strings; fix clipping, overflow and overlapping layouts. (Target chip now
@@ -1720,9 +1720,9 @@ screen-design judge before any model/texture changes. No gameplay rules change.
- [x] Ran `tools/check_screenshots.sh` and `screen_designs.py compare`: 21 good,
0 bad.
- [x] Ran the judge with automatic model selection: 21/21 match, 0 review, 0 diff.
-- [x] Recorded the judge model and result in `docs/ui-copy.md#screen-design-judge-report`; the
+- [x] Recorded the judge model and result in `docs/design/ui-copy.md#screen-design-judge-report`; the
generated captures remain local/gitignored.
-- [x] Add a short UI copy/button checklist to `docs/release-qa.md#manual-smoke-checklist`.
+- [x] Add a short UI copy/button checklist to `docs/process/release-qa.md#manual-smoke-checklist`.
- [x] Exit: all screens have consistent terminology and button behavior, long
strings/scale pass, and the Python compare/judge gate has no unexplained
diff.
@@ -1755,7 +1755,7 @@ fallback behavior.
the side-by-side after sheet without overwriting it.)
Completed 2026-11-02: 48-frame neutral studio baseline, eight criteria, current fit and
-triangle/vertex measurements, and ranked P1/P2 gaps are in `docs/3d-model-review.md`. The
+triangle/vertex measurements, and ranked P1/P2 gaps are in `docs/assets/3d-model-review.md`. The
baseline itself changed no character models; the first P1 gear fixes are recorded under Gear
and equipment fit.
@@ -1768,7 +1768,7 @@ and equipment fit.
- [x] Audit all variants against a shared human proportion guide (head height, shoulder width,
torso length, hip width, limb length, foot length) and correct the worst outliers.
- (`tools/npc_proportions.py` + `docs/3d-model-review.md#character-measurements`: all eight pass; no skeleton or
+ (`tools/npc_proportions.py` + `docs/assets/3d-model-review.md#character-measurements`: all eight pass; no skeleton or
mesh rescue was needed. Head and broad-build silhouettes are nearest their upper bounds.)
- [x] Improve the neck and shoulder transition so the silhouette reads as one body rather than a
thin post on a hanger. (Fuller neck base/top, lower shoulder root, degenerate-face cleanup;
@@ -1857,7 +1857,7 @@ and equipment fit.
`blender_assets.py audit`, `fit`, character imports and the full Godot test suite.
- [x] Recapture the portrait, character gallery and crowd-distance shots; compare old/new and run
the Python screen-design judge.
-- [x] Update `docs/blender-assets.md`, architecture/status, `MEMORY.md` and the changelog with the
+- [x] Update `docs/assets/blender-assets.md`, architecture/status, `MEMORY.md` and the changelog with the
new budgets, limitations and rebuild commands.
- [x] Exit: all eight variants pass the portrait/readability criteria, gear and hems no longer
clip in normal play, the 24-NPC budget remains green, and the visual judge has no unexplained
@@ -2007,7 +2007,7 @@ target paths and leave a clean release-candidate handoff.
final patch-level results and any remaining gaps. (README/PLAN/architecture
now point at 0.9.6; the changelog and development status record the
integration build, performance numbers, judge results and the clean-worktree
- export rule; `docs/RELEASING.md` documents the ignored-folder trap.)
+ export rule; `docs/process/RELEASING.md` documents the ignored-folder trap.)
- [x] Tag/version or otherwise freeze `0.9.6` as the integration checkpoint before
the `0.10.0` release candidate. (Tag `v0.9.6` on `4bb2896`; Gitea run 1296
passed checks and the full build and published seven assets.)
@@ -2050,7 +2050,7 @@ must inherit the reviewed face/hand/gear baseline instead of multiplying whateve
the existing Blender contract. (Measured Quaternius CC0, Kenney CC0, Khronos
CesiumMan/RiggedFigure CC-BY and the MakeHuman CC0 base mesh; none is a drop-in.
Results, local preview sheet and SHA-256 provenance are in
- `docs/npc-model-sourcing.md`.)
+ `docs/assets/npc-model-sourcing.md`.)
- [x] Review the sourcing research with the project owner and choose Option A (procedural),
Option B (Quaternius CC0 intake) or Option C (MakeHuman/MPFB body pipeline); record the
decision in an ADR and in `MEMORY.md`. (2026-11-03: extend the procedural generator as the
@@ -2127,7 +2127,7 @@ must inherit the reviewed face/hand/gear baseline instead of multiplying whateve
- [x] Gates with the expanded library: 24-NPC budget smoke 152,464 tris / 168 meshes / 6.94 ms
(under 50 ms), portrait baseline 12 variants × 6 views, `fit` clean, Godot 277/277, Python
160/160. No release build is created for this unversioned track.
-- [x] Docs: `docs/development-status.md`, `docs/3d-model-review.md` and the baseline sheet updated;
+- [x] Docs: `docs/project/development-status.md`, `docs/assets/3d-model-review.md` and the baseline sheet updated;
`CREDITS.md` needs no change (the crowd variants are procedural, no new source). Accepted
visual limits: the crowd accessories (umbrella canopy, cup, sunglasses, beard) read at
full-body distance but not in the head-only portrait framing.
@@ -2154,7 +2154,7 @@ Goal: `src/test/capture_npc_pose.gd` reports a pose but saves rest frames; the r
narrowed to the skinned mesh ignoring its `Rig` parent transform. Fixing it unblocks the
weights/pose column of the 3D review; the evidence now feeds the Quaternius base bake.
-*Skill route: `rigging`; evidence in `docs/3d-model-review.md` §"Pose evidence is blocked".*
+*Skill route: `rigging`; evidence in `docs/assets/3d-model-review.md` §"Pose evidence is blocked".*
- [x] Root cause found (2026-11-04): the harness never disabled the avatar's `_physics_process`,
so `_advance_fsm` + `_move_toward_target` ran every tick and reset `arrived`/velocity, which
@@ -2205,8 +2205,8 @@ player-facing system. The 0.10.0 minor is reserved for the release gates (see be
blocked rig can no longer block the whole release.
**Completed 2026-11-06.** Shipped as `v0.9.9` (tagged, local release build with checksums)
-and accepted by the owner after the follow-up fixes. Durable evidence: `docs/3d-model-review.md`,
-`docs/blender-assets.md`, `docs/adr/0018-quaternius-stage2-runtime-rig.md`.
+and accepted by the owner after the follow-up fixes. Durable evidence: `docs/assets/3d-model-review.md`,
+`docs/assets/blender-assets.md`, `docs/adr/0018-quaternius-stage2-runtime-rig.md`.
### Rig and export correction
@@ -2264,7 +2264,7 @@ and accepted by the owner after the follow-up fixes. Durable evidence: `docs/3d-
`npc_proportions`).
- [x] Owner visual signoff obtained (2026-11-06) on the roster, the faces, the head gear and the
hand/back gear. The review page and its sheets were retired after acceptance; the measurements
- live on in `docs/3d-model-review.md` and `docs/blender-assets.md`.
+ live on in `docs/assets/3d-model-review.md` and `docs/assets/blender-assets.md`.
- [x] Face-fidelity comparison was made and the full swap chosen; the comparison sheets were
retired with the review pages, and the decision is recorded in the follow-up section of
[`docs/adr/0018-quaternius-stage2-runtime-rig.md`](docs/adr/0018-quaternius-stage2-runtime-rig.md).
@@ -2272,7 +2272,7 @@ and accepted by the owner after the follow-up fixes. Durable evidence: `docs/3d-
baked from the three Quaternius sources inside 24,000 tris / 24,000 glTF vertices
(`a6ccd86`), and the gate was re-run.
- [x] Record the decision and its consequence in `MEMORY.md`,
- `docs/npc-model-sourcing.md#shipped-roster-099-owner-chose-the-full-swap` and the
+ `docs/assets/npc-model-sourcing.md#shipped-roster-099-owner-chose-the-full-swap` and the
follow-up decision section of
[`docs/adr/0018-quaternius-stage2-runtime-rig.md`](docs/adr/0018-quaternius-stage2-runtime-rig.md).
- [x] Owner visual signoff on the shipped roster (2026-11-06): accepted.
diff --git a/MEMORY.md b/MEMORY.md
index 8c082ec..019d34f 100644
--- a/MEMORY.md
+++ b/MEMORY.md
@@ -2,7 +2,7 @@
Session memory for durable decisions, gotchas, and commands. Implementation history lives in
`DONE.md`, user-facing changes in `CHANGELOG.md`, the live task list in `TODO.md`, and the
-canonical implemented-features list in `docs/development-status.md`.
+canonical implemented-features list in `docs/project/development-status.md`.
## Decisions
@@ -13,8 +13,8 @@ canonical implemented-features list in `docs/development-status.md`.
- **AI-assisted asset review loop (2026-11-04):** head/face shape decisions use a concept +
judge loop — generate a target concept (`generate_textures.generate_image`, Seedream) and use
`tools/describe_image.py` as the vision judge, iterating until the judge's specific fixes
- converge. Review pages: `docs/screens/head-review/README.md`, `docs/3d-model-review.md`
- §AI-driven head rework.
+ converge. Durable evidence: `docs/assets/3d-model-review.md` §AI-driven head rework; the
+ retired head-review page was removed in the 2026-11-06 docs restructure.
- **Project agent skills (2026-11-03):** two tracked skills live in `.agents/skills/`:
`gig-line-blender-asset-contract` and `gig-line-release-qa`. They are guidance only,
add no runtime dependency and are referenced from `tools/README.md`. The third-party
@@ -24,7 +24,7 @@ canonical implemented-features list in `docs/development-status.md`.
restaged for a late-night arrival. `VENUE_SPECS["tv_studio"]` is a 30.0 m variant of the 29.6 m
Hollywood facade. One reference board serves both venues; never create a separate TV Studio board.
- **Jimmy Kimmel Live = starting point:** the Hollywood first shift and the TV Studio arrival both
- begin at the El Capitan block. Stated in `docs/venues.md#hollywood-boulevard` and `docs/gameplay.md`.
+ begin at the El Capitan block. Stated in `docs/design/venues.md#hollywood-boulevard` and `docs/design/gameplay.md`.
- **Street-view limitation:** Google Street View panoramas need a Google API key or manual browser
capture, so the local reference sets use DDG street-level photos instead.
- **Image-recitation filter:** Gemini image models reject well-known branded facades (Comedy Store
@@ -54,12 +54,12 @@ canonical implemented-features list in `docs/development-status.md`.
privacy, Compatibility/Web cost and mesh collision. Accepted photo channels: team captures,
permissioned user/volunteer photos, clearly licensed downloads; every set needs a
provenance/consent sidecar. No runtime splat dependency in 0.10.0.
-- **0.10.0 balance protocol:** `docs/release-qa.md#balance-acceptance` defines targets/denominators for the
+- **0.10.0 balance protocol:** `docs/process/release-qa.md#balance-acceptance` defines targets/denominators for the
36 venue/difficulty/phase cells, seeds 1–100, and access/emergency error rates. Gotcha:
`_read_npc_truth()` is type-derived, not behaviour-derived; the emergency-fairness review must
account for that oracle mismatch.
- **Blender MCP is optional (2026-11-04):** setup and safe part workflow are in
- `docs/asset-tooling.md#optional-interactive-blender-mcp`. The headless flatpak scripts remain authoritative; MCP is
+ `docs/assets/asset-tooling.md#optional-interactive-blender-mcp`. The headless flatpak scripts remain authoritative; MCP is
never a build/CI/test/runtime dependency, and anything MCP touched must pass the
CLI audit/fit gates.
- **Character mesh cap (2026-11-05):** all characters use 24,000 tris / 24,000 glTF vertices
@@ -108,7 +108,7 @@ canonical implemented-features list in `docs/development-status.md`.
avatars. Head-turn offsets use `+basis.z` for the same reason.
- **Release blockers (still open):** macOS unsigned, AI image provider terms/commercial rights not
cleared, storefront/rating approval pending, external playtests and full hardware matrix pending.
- Recorded in `CREDITS.md`, `PRIVACY.md`, `docs/accessibility.md`, `docs/known-limitations.md`.
+ Recorded in `CREDITS.md`, `PRIVACY.md`, `docs/design/accessibility.md`, `docs/design/known-limitations.md`.
- **Release roadmap (2026-11-05, owner):** `0.9.9` Quaternius pilot base (rig/export fix,
rest-relative pose math, owner face/silhouette gate), `0.9.10` 12-role roster, `0.9.11`
@@ -345,7 +345,7 @@ canonical implemented-features list in `docs/development-status.md`.
## Current State
-v0.9.8 is published. The build covers the three venues, the shift loop, tutorial/campaign/
+v0.9.9 is published. The build covers the three venues, the shift loop, tutorial/campaign/
checkpoints, the 0.9.3–0.9.8 polish/texture/integration/character passes and the Blender +
realism asset pipeline (see `DONE.md` and `CHANGELOG.md`). The 12-character procedural library
(realistic face + four crowd variants) and the Comedy Store map rebuild are complete.
@@ -363,7 +363,7 @@ body defects (holes, unibrow, missing eyes) and the head-gear seating are fixed,
the firefighter helmet is removed, and every head has an authored mouth. Gates: `audit` 12/12,
`inspect` clean, `fit` OK, 24-NPC budget 174,976 tris / 0.85 ms, Godot 278/278, Python 167/167.
The owner **accepted the roster on 2026-11-06** and the review page plus its sheets were then
-retired; durable evidence lives in `docs/3d-model-review.md` and `docs/blender-assets.md`. Release
+retired; durable evidence lives in `docs/assets/3d-model-review.md` and `docs/assets/blender-assets.md`. Release
packaging was fixed the same day:
excluding `tmp/`, `build/`, `docs/`, `tools/`, `src/test/` and `.agents/` from the export presets
cut the Linux binary from 426 MB to 273 MB, and `tools/build_releases.sh` writes a SHA256SUMS file.
@@ -381,6 +381,12 @@ code on the 62-joint rig, and the procedural rigs are visually unchanged. Verifi
0.82 ms avg frame). The face/silhouette gate sheet and the three options are in
the face-gate decision (owner chose the full swap).
-Test counts as of 2026-11-05: Python 167/167, Godot 278/278, `check_docs` OK.
+Test counts as of 2026-11-06: Python 167/167, Godot 278/278, `check_docs` OK.
+
+**Docs layout (2026-11-06):** `docs/` is grouped into `project/`, `design/`, `assets/` and
+`process/`; `adr/`, `screens/`, `screenshots/` and `blender_previews/` are unchanged.
+`docs/README.md` is the index and every category folder has a README (required by
+`tools/check_docs.py`). The retired `docs/screens/head-review/` page and its sheets were deleted;
+the MakeHuman fallback head is documented in `docs/assets/makehuman-head-review.md`.
diff --git a/PLAN.md b/PLAN.md
index 8210fc7..6097024 100644
--- a/PLAN.md
+++ b/PLAN.md
@@ -265,7 +265,7 @@ Primary decisions: [ADR-0007](docs/adr/0007-locomotion-and-input-layers.md), [AD
## Versioning and Delivery
-`config/version` in `project.godot` is the single version source (currently `0.9.8`). Releases are tagged `v`; the CI pipeline builds and publishes the standard artifacts plus the optional Desktop HQ zip. Version bumps follow [Semantic Versioning](https://semver.org/): every major, minor and patch increment needs a changelog entry, a local `tools/build_releases.sh` build, and artifact/checksum verification before tagging. Unversioned development tracks do not receive a version until their scope enters a release. See [`docs/RELEASING.md`](docs/RELEASING.md) and [`README.md`](README.md) for commands.
+`config/version` in `project.godot` is the single version source (currently `0.9.9`). Releases are tagged `v`; the CI pipeline builds and publishes the standard artifacts plus the optional Desktop HQ zip. Version bumps follow [Semantic Versioning](https://semver.org/): every major, minor and patch increment needs a changelog entry, a local `tools/build_releases.sh` build, and artifact/checksum verification before tagging. Unversioned development tracks do not receive a version until their scope enters a release. See [`docs/process/RELEASING.md`](docs/process/RELEASING.md) and [`README.md`](README.md) for commands.
## Gap Analysis
diff --git a/PRIVACY.md b/PRIVACY.md
index cac5269..d818098 100644
--- a/PRIVACY.md
+++ b/PRIVACY.md
@@ -14,7 +14,7 @@ Player data is written only to Godot's local `user://` directory:
Those files stay on the player's machine unless the player copies them. Deleting
the files (or the `Gig Line` user directory) resets the profile. See
-[`docs/getting-started.md`](docs/getting-started.md#save-data-and-migration) for
+[`docs/process/getting-started.md`](docs/process/getting-started.md#save-data) for
locations, migration and rollback instructions.
The repository's development tools can call OpenRouter when a developer supplies
diff --git a/README.md b/README.md
index 0937910..8145858 100644
--- a/README.md
+++ b/README.md
@@ -46,13 +46,13 @@ Versions are assigned only when a track's scope is accepted into a release. Ever
> development track remains gated on the Quaternius NPC rollout, local-map work
> and release approvals.
> Releases are built automatically when a `vX.Y.Z` tag is pushed
-> (see [`docs/RELEASING.md`](docs/RELEASING.md)); manual builds use
+> (see [`docs/process/RELEASING.md`](docs/process/RELEASING.md)); manual builds use
> `./tools/build_releases.sh`. Installer/AppImage packaging runs in the same pipeline
> (NSIS + appimagetool) and uploads with the portable binaries.
>
> macOS builds are unsigned: right-click → Open, or clear the quarantine with
> `xattr -dr com.apple.quarantine gig-line-macos.zip`. Build instructions and
-> the release pipeline live in [`docs/RELEASING.md`](docs/RELEASING.md).
+> the release pipeline live in [`docs/process/RELEASING.md`](docs/process/RELEASING.md).
If you are here to develop or test locally instead of downloading, jump to
[Setup and Run](#setup-and-run) below.
@@ -112,7 +112,7 @@ current library and will be replaced after the 12 × 6 baseline review.
|  | **Crowd variety prototypes.** Four approved looks (bun/slim, bald/broad, coat/umbrella, hood/cup) queued for the roster build. |
More sheets and the review criteria are in [`docs/blender_previews/`](docs/blender_previews/README.md)
-and [`docs/3d-model-review.md`](docs/3d-model-review.md).
+and [`docs/assets/3d-model-review.md`](docs/assets/3d-model-review.md).
## Game Overview
@@ -122,7 +122,7 @@ tickets or credentials, and escalate only when necessary. The game rewards calm
resolution over force. The venue menu splits Hollywood Boulevard into Day and
Night rows; the full mechanics — the three venues, the six-level
escalation model, and the core systems — are in
-[`docs/gameplay.md`](docs/gameplay.md); the design rationale lives in
+[`docs/design/gameplay.md`](docs/design/gameplay.md); the design rationale lives in
[`PLAN.md`](PLAN.md).
## Architecture
@@ -130,8 +130,8 @@ escalation model, and the core systems — are in
A venue-driven simulation: shared systems (movement, perception, interaction,
access verification, escalation, radio, crowd, reputation, evidence, shift
review) driven by per-venue scenario data, on Godot 4 + GDScript. The full
-arc42-style document is [`docs/architecture.md`](docs/architecture.md);
-decisions are recorded as ADRs in [`docs/adr/`](docs/adr/).
+arc42-style document is [`docs/project/architecture.md`](docs/project/architecture.md);
+decisions are recorded as ADRs in [`docs/adr/`](docs/adr).
## Tech Stack
@@ -144,7 +144,7 @@ decisions are recorded as ADRs in [`docs/adr/`](docs/adr/).
- **Targets:** Windows, Linux, macOS, Web
The asset pipelines, model tools, and screenshot gates are documented in
-[`docs/asset-tooling.md`](docs/asset-tooling.md).
+[`docs/assets/asset-tooling.md`](docs/assets/asset-tooling.md).
## Setup and Run
@@ -157,36 +157,36 @@ godot --headless --path . --script res://src/test/test_runner.gd # run all tes
```
Full setup, every run/test/smoke command, and the controls table are in
-[`docs/getting-started.md`](docs/getting-started.md).
+[`docs/process/getting-started.md`](docs/process/getting-started.md).
## Project Documentation
- [`PLAN.md`](PLAN.md) — Game design plan, development priorities and scenario details.
- [`TODO.md`](TODO.md) — Priority-ordered tasks: character and local-map development, release milestones, and future work.
- [`docs/README.md`](docs/README.md) — Documentation index, current priorities and visual previews.
-- [`docs/npc-model-sourcing.md`](docs/npc-model-sourcing.md) — Character-source evaluation, licence rules and the character-development plan.
-- [`docs/makehuman-head-review.md`](docs/makehuman-head-review.md) — Local MakeHuman head prototype, provenance and review verdict.
+- [`docs/assets/npc-model-sourcing.md`](docs/assets/npc-model-sourcing.md) — Character-source evaluation, licence rules and the character-development plan.
+- [`docs/assets/makehuman-head-review.md`](docs/assets/makehuman-head-review.md) — Local MakeHuman head prototype, provenance and review verdict.
- [`AGENTS.md`](AGENTS.md) — Development, commit, build and collaboration workflow.
- [`DONE.md`](DONE.md) — Completed task sections.
- [`MEMORY.md`](MEMORY.md) — Persistent session notes.
- [`CHANGELOG.md`](CHANGELOG.md) — User-facing changes by version.
-- [`docs/architecture.md`](docs/architecture.md) — arc42-style architecture documentation.
-- [`docs/gameplay.md`](docs/gameplay.md) — Gameplay systems, venues, and the escalation model.
-- [`docs/venues.md`](docs/venues.md) — Real-site references, game mapping and limitations for Hollywood, the Joke Shop and the TV Studio.
-- [`docs/asset-tooling.md`](docs/asset-tooling.md) — Asset pipelines, model tools, and screenshot gates.
+- [`docs/project/architecture.md`](docs/project/architecture.md) — arc42-style architecture documentation.
+- [`docs/design/gameplay.md`](docs/design/gameplay.md) — Gameplay systems, venues, and the escalation model.
+- [`docs/design/venues.md`](docs/design/venues.md) — Real-site references, game mapping and limitations for Hollywood, the Joke Shop and the TV Studio.
+- [`docs/assets/asset-tooling.md`](docs/assets/asset-tooling.md) — Asset pipelines, model tools, and screenshot gates.
- [`tools/README.md`](tools/README.md) — Tool inventory, categories, test commands and AI-skill evaluation.
- [`.agents/skills/gig-line-blender-asset-contract`](.agents/skills/gig-line-blender-asset-contract/SKILL.md) — tracked AI skill for Blender/NPC/gear asset work.
- [`.agents/skills/gig-line-release-qa`](.agents/skills/gig-line-release-qa/SKILL.md) — tracked AI skill for release and visual-QA work.
-- [`docs/getting-started.md`](docs/getting-started.md) — Setup, run/test commands, and controls.
-- [`docs/development-status.md`](docs/development-status.md) — Implemented features and what's next.
-- [`docs/accessibility.md`](docs/accessibility.md) — Accessibility features, known gaps and statement.
-- [`docs/known-limitations.md`](docs/known-limitations.md) — Release-candidate blockers and accepted limitations.
-- [`docs/release-qa.md`](docs/release-qa.md) — Manual smoke checklist and release-candidate balance protocol.
+- [`docs/process/getting-started.md`](docs/process/getting-started.md) — Setup, run/test commands, and controls.
+- [`docs/project/development-status.md`](docs/project/development-status.md) — Implemented features and what's next.
+- [`docs/design/accessibility.md`](docs/design/accessibility.md) — Accessibility features, known gaps and statement.
+- [`docs/design/known-limitations.md`](docs/design/known-limitations.md) — Release-candidate blockers and accepted limitations.
+- [`docs/process/release-qa.md`](docs/process/release-qa.md) — Manual smoke checklist and release-candidate balance protocol.
- [`CREDITS.md`](CREDITS.md) — Credits, AI/reference provenance and licensing notes.
- [`PRIVACY.md`](PRIVACY.md) — Local-only data, save files and development API use.
-- [`docs/blender-assets.md`](docs/blender-assets.md) — Blender asset library: characters, gear, props, attach points.
-- [`docs/npc-model-sourcing.md`](docs/npc-model-sourcing.md) — character sources, the shipped roster table and the build steps; 0.9.5 texture comparison is in [`docs/blender_previews/sheet_texture_refinement_0.9.5.jpg`](docs/blender_previews/sheet_texture_refinement_0.9.5.jpg).
-- [`docs/adr/`](docs/adr/) — Architecture Decision Records.
+- [`docs/assets/blender-assets.md`](docs/assets/blender-assets.md) — Blender asset library: characters, gear, props, attach points.
+- [`docs/assets/npc-model-sourcing.md`](docs/assets/npc-model-sourcing.md) — character sources, the shipped roster table and the build steps; 0.9.5 texture comparison is in [`docs/blender_previews/sheet_texture_refinement_0.9.5.jpg`](docs/blender_previews/sheet_texture_refinement_0.9.5.jpg).
+- [`docs/adr/`](docs/adr) — Architecture Decision Records.
## Development Status
@@ -198,9 +198,9 @@ UI/accessibility polish, 0.9.2 Hollywood/Joke Shop maps and the 0.9.x engine
baseline. The active work is the `0.9.9`–`0.9.12` patch line (Quaternius NPC
base, roster, venue/asset polish, performance) followed by the `0.10.0`
public-readiness minor. See
-[`docs/development-status.md`](docs/development-status.md) for the implemented list
+[`docs/project/development-status.md`](docs/project/development-status.md) for the implemented list
and [`TODO.md`](TODO.md) for the priority-ordered roadmap. Manual verification uses
-[`docs/release-qa.md`](docs/release-qa.md).
+[`docs/process/release-qa.md`](docs/process/release-qa.md).
## Credits, Privacy and Accessibility
@@ -209,8 +209,8 @@ network service, and saves stay in Godot's local `user://` folder. The
body-camera overlay is simulated. Asset provenance, AI-assisted image usage and
credits are recorded in [`CREDITS.md`](CREDITS.md); the local-data policy is in
[`PRIVACY.md`](PRIVACY.md); accessibility features and gaps are in
-[`docs/accessibility.md`](docs/accessibility.md); and release-candidate blockers
-are listed in [`docs/known-limitations.md`](docs/known-limitations.md).
+[`docs/design/accessibility.md`](docs/design/accessibility.md); and release-candidate blockers
+are listed in [`docs/design/known-limitations.md`](docs/design/known-limitations.md).
## Development Workflow
diff --git a/TODO.md b/TODO.md
index c2e0275..2d0d7a8 100644
--- a/TODO.md
+++ b/TODO.md
@@ -74,7 +74,7 @@ pieces, 20 library props, 6 generated props and the three venue families — plu
pipeline that re-evaluates those venues (OSM data/licensing, reference imagery, the photoreal
facade kit, AI-assisted composing, Gaussian-splatting evaluation and map QA).
-**Exit (asset review, A–G):** `docs/3d-model-review.md` scores every catalogue asset; every P0/P1
+**Exit (asset review, A–G):** `docs/assets/3d-model-review.md` scores every catalogue asset; every P0/P1
is fixed or explicitly accepted with a measurement; `inspect`/`audit`/`fit`/proportions, the
24-NPC budget and the capture gates are green; no runtime contract, dependency or release artifact
changed except the rebuilt assets themselves.
@@ -111,16 +111,16 @@ licence-free zone only.
(`elcapitan`, `hollywood-block`, `jimmy-kimmel-stage`, `jimmy-kimmel-entrance`,
`comedy-store`).
- [x] Record which local frames changed a decision: added the frame→decision mapping to
- `docs/venues.md#hollywood-boulevard` (recent `elcapitan-2026` geosearch → 2009 frame stays the
+ `docs/design/venues.md#hollywood-boulevard` (recent `elcapitan-2026` geosearch → 2009 frame stays the
geometry reference; `jimmy-kimmel-entrance/07.jpg` → the four entrance concepts) and
- `docs/venues.md#the-joke-shop` (`comedy-store/` → the four concept pairs + map plan;
+ `docs/design/venues.md#the-joke-shop` (`comedy-store/` → the four concept pairs + map plan;
`comedy-store-hillside/` → the day-concept anchor that clears the image-recitation filter).
Frames stay gitignored; only the provenance notes are committed.
### B. Baseline, scorecard and routing
- [x] Load `blender-director` plus the per-family specialists before touching geometry, and
- record the skill stack and the advice that changed a decision in `docs/3d-model-review.md`.
+ record the skill stack and the advice that changed a decision in `docs/assets/3d-model-review.md`.
(Routing, QA severity/verdict, texel-density tiers, character loop criteria and budget rules
recorded in the review doc; MCP-only steps translated to headless flatpak runs.)
- [x] Re-run the neutral NPC baseline (48 frames), the final-context review (96 frames), the
@@ -128,7 +128,7 @@ licence-free zone only.
not replace committed sheets until a fix lands. (48/48 and 96/96 frames captured under
`xvfb-run`, none blank; raw sets in `tmp/model-baseline` and `tmp/model-review`; committed
sheets untouched. 24-NPC smoke still 6.94 ms / 168 meshes / 131,616 triangles.)
-- [x] Create `docs/3d-model-review.md` with a per-asset scorecard: silhouette, anatomy/proportion,
+- [x] Create `docs/assets/3d-model-review.md` with a per-asset scorecard: silhouette, anatomy/proportion,
topology/edge flow, UV/texel density, textures/materials, rig/weights, LOD/impostor,
collision/grounding, export contract, provenance, skill route, verdict (P0/P1/P2/accept).
(Doc created with character/gear/prop/venue tables, verdict columns and a ranked candidate
@@ -144,11 +144,10 @@ licence-free zone only.
### C. Character re-evaluation (superseded 2026-11-05)
The procedural character review is complete and its evidence stays in
-`docs/3d-model-review.md`. The next character pass is the Quaternius base in
-[`Milestone 0.9.9`](#milestone-099--quaternius-npc-base-swap-patch) and
-[`Milestone 0.9.10`](#milestone-0910--npc-roster-rollout-patch); the open items below are kept
-as evidence for what the new base must not regress (face read, hands, weights, cloth, texel
-density, crowd variety).
+`docs/assets/3d-model-review.md`. The Quaternius base shipped in 0.9.9; the remaining roster
+follow-ups are [`Milestone 0.9.10`](#milestone-0910--npc-roster-rollout-patch). The open items
+below are kept as evidence for what the new base must not regress (face read, hands, weights,
+cloth, texel density, crowd variety).
*Skill route: `character-artist`, `retopology`, `rigging`, `uv-workflow`, `texture-workflow`,
`materials`, `hair-groom`, `asset-optimization`, `lookdev`, `qa-review`.*
@@ -175,7 +174,7 @@ density, crowd variety).
hip fix clean, knee crease minor residual. The guard hip-pouch clip and the residual knee
crease remain as 0.10.0 refinements.
- [x] UV/texel density: measured (64–122 px/m authored, 287–440 px/m effective fabric on the 4×
- repeat; table in `docs/3d-model-review.md`). Decision: **accept as-is** — the maps are
+ repeat; table in `docs/assets/3d-model-review.md`). Decision: **accept as-is** — the maps are
neutral/runtime-tinted (not painted skin), so density controls only subtle weave/noise, and
fabric already sits in the standard tier. No atlas/UDIM/resolution change is justified until
a portrait shows texture starvation; `CHAR_MAX_TRIS`/`CHAR_MAX_VERTS` stay unchanged.
@@ -187,7 +186,7 @@ density, crowd variety).
reconsidered if a later close-up shows visible hem/coat stiffness.
- [ ] Fix only the ranked P0/P1s, one asset family per commit; refresh the comparison sheet and
re-run `inspect`, `audit`, `fit` and `npc_proportions.py` after each fix. **Scheduled: the
- remaining character items are covered by Milestone 0.9.9/0.9.10; this row is evidence only.**
+ remaining character items are covered by Milestone 0.9.10; this row is evidence only.**
- [x] Crowd-variety reference: five licence-cleared Commons photos fetched to
`tmp/research/crowd-variety/` (CC0 ×2, CC BY 2.0, CC BY 3.0, PD) covering umbrella/dense
crowds and a pedestrian mall — general build/hair/outer-layer variety context, reference
@@ -200,7 +199,7 @@ density, crowd variety).
- [x] `qa-review` sign-off: all eight variants **ship with notes** (face realism landed, hands/
cloth/gear accepted, props reviewed); the weights/pose column is the only open item (blocked
on the harness) and the full foliage carded-cluster is the one remaining owner-gated P1.
- Recorded in `docs/3d-model-review.md` §qa-review sign-off.
+ Recorded in `docs/assets/3d-model-review.md` §qa-review sign-off.
### D. Gear and prop re-evaluation
@@ -209,7 +208,7 @@ density, crowd variety).
- [ ] Gear: review the 18 pieces for silhouette, straps/buckles, helmet and lanyard readability
and rebuild only what fails the scorecard. (Attach/clearance verification is done — the
- `fit` report is recorded in `docs/3d-model-review.md` with the back-gear-vs-hip-radius
+ `fit` report is recorded in `docs/assets/3d-model-review.md` with the back-gear-vs-hip-radius
measurement caveat; the visual silhouette read is what remains, pending the owner scorecard.)
- [ ] Props: review the 20 library props plus the 6 generated props for bevels, chamfers,
silhouette, ground contact and shared material language (`prop-artist`, `hard-surface`);
@@ -233,7 +232,7 @@ density, crowd variety).
lamp) and rank the silhouette and proportion mismatches.
- [ ] Rebuild only the mismatched pieces through the assisted Blender pipeline
(`blender_assets.py inspect` → scripted retopo/UV assist → atlas → `audit`/`fit`); document
- the exact commands in `docs/asset-tooling.md`.
+ the exact commands in `docs/assets/asset-tooling.md`.
- [ ] Refresh `sheet_props.jpg`/`sheet_npc_gear.jpg`, the README asset rows and
`docs/blender_previews/README.md` after the rebuilds.
- [ ] Exit: a prop/gear capture sheet, budgets and collision checks pass with no unreviewed asset.
@@ -293,8 +292,8 @@ density, crowd variety).
`tools/three_up.py compose` renders labelled strips into `docs/screens/boards/` (caption
sidecar per board, `rows` emits README rows). Boards committed: El Capitan day, El Capitan
night, Joke Shop day. Tests in `tools/test_three_up.py`.
-- [x] Link each committed board from `docs/venues.md#hollywood-boulevard` and
- `docs/venues.md#the-joke-shop`.
+- [x] Link each committed board from `docs/design/venues.md#hollywood-boulevard` and
+ `docs/design/venues.md#the-joke-shop`.
- [ ] Use the generated concept lighting and palette as the target for the `lighting`/`lookdev`
pass, and record the deviations that stay accepted.
- [ ] After the pass, regenerate the venue captures and update README plus both venue documents.
@@ -322,10 +321,10 @@ and never ship a generated or downloaded image without provenance.
log and the generated-board reference table. Linked from `docs/screens/README.md`.)
- [x] Hollywood board: five licence-cleared photos (facade day, blade sign, 1922 elevation,
Ovation across street, premiere staging) with a sidecar and per-image purpose, linked from
- `docs/venues.md#hollywood-boulevard` and credited in `CREDITS.md`. Cropped the foreground crowd
+ `docs/design/venues.md#hollywood-boulevard` and credited in `CREDITS.md`. Cropped the foreground crowd
out of the facade shot; EXIF stripped. (`docs/screens/refs/hollywood/`.)
- [x] Joke Shop board: three licence-cleared photos (hillside/canopy block, frontage with palms,
- canopy signature band) with a sidecar, linked from `docs/venues.md#the-joke-shop` and credited in
+ canopy signature band) with a sidecar, linked from `docs/design/venues.md#the-joke-shop` and credited in
`CREDITS.md`. The CC BY-SA `The Comedy Store.jpg` from the old link list was deliberately not
used; the public-domain frames cover the same evidence. (`docs/screens/refs/joke-shop/`.)
**Removed 2026-11-03:** the committed Comedy Store photo board was replaced by the local-only
@@ -333,8 +332,8 @@ and never ship a generated or downloaded image without provenance.
- [x] TV Studio: no separate board — the venue is the same El Capitan Entertainment Centre block as
the Hollywood day shift, restaged for a late-night arrival. The Hollywood board covers both
venues and the premiere-staging photo is the arrival evidence; the reuse is now stated in
- `docs/venues.md#hollywood-boulevard`, `docs/gameplay.md`, `PLAN.md` and
- `docs/development-status.md`.
+ `docs/design/venues.md#hollywood-boulevard`, `docs/design/gameplay.md`, `PLAN.md` and
+ `docs/project/development-status.md`.
- [x] Fill the Hollywood gaps that have a clean licence: El Capitan Theatre neighbour and marquee,
Walk of Fame terrazzo band, star close-up, and a night street-lighting context frame (cropped
to remove people and a plate). The board now has nine photos. (CC BY-SA night frame is
@@ -348,7 +347,7 @@ and never ship a generated or downloaded image without provenance.
preview sheets.)
- [ ] Apply the screenshot rule to every workstream: each accepted fix updates the relevant row in
`README.md` plus the matching docs page (`docs/blender_previews/README.md`,
- `docs/screenshots/README.md`, `docs/3d-model-review.md` or the venue map doc).
+ `docs/screenshots/README.md`, `docs/assets/3d-model-review.md` or the venue map doc).
- [ ] Re-run `tools/check_screenshots.sh` and `python3 tools/check_docs.py` after gallery changes
and record both results in the handoff.
- [ ] Keep AI-generated images out of `assets/` until they are picked, cropped, credited and (for
@@ -372,16 +371,16 @@ and never ship a generated or downloaded image without provenance.
Suite is 275/275.)
- [x] Add a coverage test so every catalogue asset has a scorecard row and verdict.
(`tools/test_model_review.py`: every `CHARACTERS`/`GEAR`/`PROPS` entry needs a row in
- `docs/3d-model-review.md`, and character rows need a non-empty verdict.)
-- [x] Document the new gates: `docs/blender-assets.md` now lists `texels`, the
+ `docs/assets/3d-model-review.md`, and character rows need a non-empty verdict.)
+- [x] Document the new gates: `docs/assets/blender-assets.md` now lists `texels`, the
`test_model_review.py` coverage gate and the `test_world.gd` collider/proxy gate; skill
routes live in `AGENTS.md` §Local Blender skills and each `TODO.md` section; the scorecard
- and evidence table are in `docs/3d-model-review.md`.
-- [x] Record accepted limits/deferred rebuilds: `docs/known-limitations.md` already records the
+ and evidence table are in `docs/assets/3d-model-review.md`.
+- [x] Record accepted limits/deferred rebuilds: `docs/design/known-limitations.md` already records the
stylized low-poly style, no finger-curl rig and the >26 m impostor; `MEMORY.md` holds the
durable decisions (texel density accepted, cloth sim out of scope, open palm + forward
offset, face subdivision prototype gated on the owner). The corrected face note is also in
- `docs/blender-assets.md`.
+ `docs/assets/blender-assets.md`.
**Local map workstreams (H–M).** Build a local, data-backed map pipeline that can replace or
supplement the stylized venue geometry with licensed OpenStreetMap footprints, 3D building
@@ -402,7 +401,7 @@ still apply; the map pipeline has its own exit in M.
- [x] ODbL audit: OpenStreetMap is used as **reference only** (hand-built geometry informed by
OSM ways + Commons photos), so the shipped geometry is not an ODbL derived database and no
share-alike obligation attaches. Attribution is still kept via the OSM way links in
- `docs/venues.md#hollywood-boulevard` / `docs/venues.md#the-joke-shop`. If derived OSM geometry ever
+ `docs/design/venues.md#hollywood-boulevard` / `docs/design/venues.md#the-joke-shop`. If derived OSM geometry ever
ships, it needs the attribution + share-alike review in a separate ADR.
- [x] OSM extract workflow: no offline extract is required while OSM is reference-only. If the
pipeline later imports footprints, pin an Overpass query + extract date and record it in a
@@ -501,13 +500,13 @@ Nothing is committed until the licence gate on any promoted reference and the ma
pass. The current `_build_comedy_store_building()` stays as the fallback.*
- [x] Extract the real proportions and reconcile: vision-read `tmp/research/comedy-store/` frames
- via `tools/describe_image.py` and recorded the reconciled table in `docs/venues.md#the-joke-shop`
+ via `tools/describe_image.py` and recorded the reconciled table in `docs/design/venues.md#the-joke-shop`
§Measured proportions. Key finding: the game facade is proportionally **taller** than the
real (3.2:1 vs ~6:1) — the main shape-language deviation; canopy pitch, blade-sign diameter,
entrance and roofline all match closely. Curtain-bay count is crop-dependent (3–7), so 7 is
accepted as a readable stylization.
- [x] Rank the shape-language gaps and write the top-five fix list (measurements from the
- proportions pass, §`docs/venues.md#the-joke-shop`):
+ proportions pass, §`docs/design/venues.md#the-joke-shop`):
1. **Facade height** — game 8.4 m vs real ~5.5–6 m (≈3.2:1 vs ~6:1 ratio). **Fixed
2026-11-03:** `facade_height` lowered to 6.0 m; the wall now reads as a low single-storey
hall with the canopy capping the top (vision-verified).
@@ -533,8 +532,8 @@ pass. The current `_build_comedy_store_building()` stays as the fallback.*
top-five list.
- [x] Gates after the rebuild: Godot 277/277 (map budget 26,828 tris / 580 meshes under 150k/700;
navigation/collider tests pass), `tools/check_screenshots.sh` 21 good / 0 bad; the three-up
- board and `docs/venues.md#the-joke-shop` were refreshed.
-- [ ] Update `docs/development-status.md`, `docs/asset-tooling.md` and `CHANGELOG.md` when the
+ board and `docs/design/venues.md#the-joke-shop` were refreshed.
+- [ ] Update `docs/project/development-status.md`, `docs/assets/asset-tooling.md` and `CHANGELOG.md` when the
rebuild lands; record any accepted deviations from the reference.
### L. Generated location imagery
@@ -575,7 +574,7 @@ pass. The current `_build_comedy_store_building()` stays as the fallback.*
### M. Local map QA and exit
- [x] Compare the block against screenshots/map docs and keep the stylized fallback: the three-up
- boards (photo | concept | capture) and `docs/venues.md#the-joke-shop` record the evidence chain;
+ boards (photo | concept | capture) and `docs/design/venues.md#the-joke-shop` record the evidence chain;
the procedural `_build_comedy_store_building()` remains the fallback.
- [x] Budget/navigation/collider + day/night captures: Godot 277/277 (Joke Shop 26,828 tris /
580 meshes under 150k/700; navmesh, step collider and prop-collider tests pass),
@@ -583,8 +582,8 @@ pass. The current `_build_comedy_store_building()` stays as the fallback.*
- [x] Gallery + before/after: the Joke Shop day gallery frame and three-up board were recaptured
after each facade change; the photo/concept/capture strip is the before/after record.
- [x] `tools/check_screenshots.sh` re-run (21/0) and the Joke Shop three-up board refreshed.
-- [x] Docs: `docs/venues.md#the-joke-shop` (mapping, measured proportions, simplifications),
- `docs/asset-tooling.md` (`describe_image.py`) and `docs/development-status.md` updated.
+- [x] Docs: `docs/design/venues.md#the-joke-shop` (mapping, measured proportions, simplifications),
+ `docs/assets/asset-tooling.md` (`describe_image.py`) and `docs/project/development-status.md` updated.
`CHANGELOG.md` is untouched (unversioned track; no release).
- [x] Exit: **one local block (the Comedy Store) is reconstructed with reference-derived facades
and massing** — 6.0 m low hall, white signature fascia, tied-back curtains, hotel tower —
@@ -776,7 +775,7 @@ regressing gear fit, budget or readability.
FBX artefacts (per-file armatures, `_end`/`neutral_bone`, node transforms, the shared
jacket/trouser fabric, seam degenerates). `Suit.glb` is the first base: `npc_coat` is now a
dark formal suit instead of a tinted hoodie. The pitfalls are recorded in
- `docs/npc-model-sourcing.md` and `MEMORY.md`.
+ `docs/assets/npc-model-sourcing.md` and `MEMORY.md`.
- [x] **Outfit families rolled out.** Seven more bases intaken (Adventurer, Beach, Casual_2,
Farmer, King, Punk, Suit) with a slot map each: the roster now runs **eleven distinct outfits
across twelve roles**. `patch_slots` buries a hidden triangle for slots a family cannot paint
@@ -833,8 +832,8 @@ accepted on 2026-11-06; the review page and its sheets were then retired.
quads became the light sclera and a shrunken copy pushed along the sclera's own normal became
the dark pupil (`_add_quaternius_eye_whites()`). Two extra draw calls per head, no new UV work.
- [x] Review page re-created for the second pass, then retired after the owner accepted the roster
- (2026-11-06). The durable evidence is `docs/3d-model-review.md`, the measurements in
- `docs/blender-assets.md`, and the `capture_npc_gear.gd` / `capture_npc_baseline.gd` scripts.
+ (2026-11-06). The durable evidence is `docs/assets/3d-model-review.md`, the measurements in
+ `docs/assets/blender-assets.md`, and the `capture_npc_gear.gd` / `capture_npc_baseline.gd` scripts.
- [-] Arm/torso intersection on `npc_dress`/`npc_jacket`/`npc_crowd_a`/`npc_crowd_d`: the baked
rest now aims the upper arm 7° out from vertical. Verified clear on the `casual` base; a
light clip remains on `worker`, so this needs either a wider angle or a per-base shoulder
@@ -871,7 +870,7 @@ contract.
It now reports grip drop, the lowest point at rest against the Quaternius wrist (y 1.017), the
hip-line flag (0.95), the authored size and `size_vs_head` — the proportion number that makes
"reads oversized" measurable.
-- [x] Record the nine hand-item measurements (table in `docs/blender-assets.md`). Only the
+- [x] Record the nine hand-item measurements (table in `docs/assets/blender-assets.md`). Only the
`clipboard` was actually mis-authored: its grip sat in the *middle* of the board, so it hung
through the thigh line. It now grips the top edge like a carried clipboard (0.22 x 0.30 m).
- [x] Re-author the `clipboard` (top-edge grip, 0.22 x 0.30 m) and rebuild + re-bake AO. The
@@ -885,7 +884,7 @@ contract.
- [x] Retire the gear GLBs the roster no longer uses: `cap` and `hood` are gone from `GEAR`, the
manifest and the asset tree (`beanie` was already retired). The builder branches stay for a
future design, guarded by a comment.
-- [x] `docs/blender-assets.md` documents the 15-piece matrix and the hand-item fit table;
+- [x] `docs/assets/blender-assets.md` documents the 15-piece matrix and the hand-item fit table;
`architecture.md`, `asset-tooling.md` and the preview index were updated with the new counts.
`CREDITS.md` still cites the upstream pack, which is unchanged.
- [x] Owner feedback: the back gear hung at the waist. The `back` attach moved from y 1.10 to
@@ -923,7 +922,7 @@ is signed off.
- [ ] Re-run the 24-NPC budget smoke and the Web/Compatibility capture; record frame time,
mesh/triangle counts and Web load before/after.
- [ ] Retire the procedural variants that are no longer used, keeping one tested fallback; update
- `docs/development-status.md`, `docs/3d-model-review.md`, `docs/blender-previews` sheets and
+ `docs/project/development-status.md`, `docs/assets/3d-model-review.md`, `docs/blender-previews` sheets and
the README character row.
- [ ] Release `0.9.10` with the full procedure (version, changelog, local build, checksums, tag).
- [ ] Shrink the release artifacts: `assets/` alone is ~273 MB in the Linux binary. Excluding
@@ -1026,7 +1025,7 @@ only release-blocking fixes and balance changes may land here.
### Balance and fairness
- [ ] Run the scripted venue sweeps across easy/normal/hard and all four phases using the
- `docs/release-qa.md#balance-acceptance` targets; tune event weights, reaction tables,
+ `docs/process/release-qa.md#balance-acceptance` targets; tune event weights, reaction tables,
compliance and report strictness where targets fail.
- [ ] Review emergency calls against independent behaviour labels, not `_read_npc_truth()` as its
own oracle; no routine behaviour may make emergency the dominant winning move.
@@ -1052,8 +1051,8 @@ only release-blocking fixes and balance changes may land here.
### Documentation and visual sign-off
-- [ ] Update `README.md`, `PLAN.md`, `docs/architecture.md`, the ADRs, `docs/development-status.md`,
- `docs/getting-started.md`, `docs/release-qa.md`, `CHANGELOG.md` and this roadmap.
+- [ ] Update `README.md`, `PLAN.md`, `docs/project/architecture.md`, the ADRs, `docs/project/development-status.md`,
+ `docs/process/getting-started.md`, `docs/process/release-qa.md`, `CHANGELOG.md` and this roadmap.
- [ ] Regenerate the gallery and realism baselines from the release-candidate build, not the dev
tree; verify every README/docs image resolves from the tagged build.
- [ ] Run the manual smoke checklist on every target and link the evidence.
@@ -1225,7 +1224,7 @@ Goal: publish the first stable release with a documented compatibility promise.
- [ ] Confirm legal, privacy, rating and storefront approval is complete in writing.
- [ ] Confirm the hardware matrix, accessibility audit and localization sign-off are complete.
- [ ] Confirm no P0/P1 defects remain and every P2 is a documented known limitation.
-- [ ] Update `README.md`, `PLAN.md`, `docs/development-status.md`, `CHANGELOG.md`, `CREDITS.md`,
+- [ ] Update `README.md`, `PLAN.md`, `docs/project/development-status.md`, `CHANGELOG.md`, `CREDITS.md`,
`PRIVACY.md` and the release notes for 1.0.0.
- [ ] Run the full release procedure: version 1.0.0, changelog, clean build, checksum
verification, tag, push and publish.
diff --git a/assets/models/blender_src/quaternius/README.md b/assets/models/blender_src/quaternius/README.md
index fb9ee0e..c07a4c4 100644
--- a/assets/models/blender_src/quaternius/README.md
+++ b/assets/models/blender_src/quaternius/README.md
@@ -21,7 +21,7 @@ Reproducing the shipped characters:
flatpak run org.blender.Blender --background \
--python "$PWD/tools/blender_assets.py" -- build --only npc
-Upstream quirks the build compensates for (see `docs/npc-model-sourcing.md`):
+Upstream quirks the build compensates for (see `docs/assets/npc-model-sourcing.md`):
1. every mesh ships a **degenerate UV map** (all loops at `0,0`) with flat-colour
materials, so the build Smart-UV-unwraps and repacks before export;
diff --git a/docs/README.md b/docs/README.md
index f35a907..d7149cd 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -1,42 +1,43 @@
# Gig Line Documentation
-This folder holds the project documentation, visual references and generated QA evidence.
+Documentation is grouped by category. Product intent, the gap analysis and the release roadmap
+live in [`../PLAN.md`](../PLAN.md); the executable task list is [`../TODO.md`](../TODO.md); the
+workflow rules are in [`../AGENTS.md`](../AGENTS.md).
-## Current priorities
+## Categories
-1. [Quaternius NPC base migration](../TODO.md#quaternius-npc-base-migration-top-priority) — CC0 Quaternius mesh/animation source baked to the 24,000-budget runtime contract.
-2. [3D model and local map improvements](../TODO.md#3d-model-and-local-map-re-evaluation) — asset re-evaluation and local map reconstruction.
-3. [0.10.0 release candidate](../TODO.md#milestone-0100--3d-model-and-map-improvements-minor) — versioned release hardening after the unversioned development tracks.
+| Folder | Contents |
+| --- | --- |
+| [`project/`](project/README.md) | Architecture (arc42) and the implemented-features status |
+| [`design/`](design/README.md) | Gameplay, venues, UI copy, accessibility and known limitations |
+| [`assets/`](assets/README.md) | Blender library, asset tooling, NPC sourcing and the 3D model review |
+| [`process/`](process/README.md) | Setup/controls, release QA and the release runbook |
+| [`adr/`](adr/README.md) | Architecture Decision Records |
+| [`screens/`](screens/README.md) | Licensed references, concepts and screen designs |
+| [`blender_previews/`](blender_previews/README.md) | Committed character/gear/prop preview sheets |
+| [`screenshots/`](screenshots/README.md) | The committed in-game gallery |
## Start here
-- [`../PLAN.md`](../PLAN.md) — product, design intent and development priorities
-- [`../TODO.md`](../TODO.md) — priority-ordered active tasks and roadmap
-- [`npc-model-sourcing.md`](npc-model-sourcing.md) — character-source evaluation, licence rules and the character-development plan
-- [`makehuman-head-review.md`](makehuman-head-review.md) — retained MakeHuman fallback head, provenance and review verdict
-- [`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
-- [`../tools/README.md`](../tools/README.md) — tool inventory, categories and test runner
-- [`gameplay.md`](gameplay.md) — controls, venues and escalation
-- [`venues.md`](venues.md) — Hollywood, Joke Shop and TV Studio real-site mapping
-- [`3d-model-review.md`](3d-model-review.md) — 3D model re-evaluation: measurements, scorecard and ranked gaps
-- [`development-status.md`](development-status.md) — implemented features, current gaps and active planning
-- [`accessibility.md`](accessibility.md) — accessibility statement and known gaps
-- [`known-limitations.md`](known-limitations.md) — release-candidate blockers and accepted limits
-- [`release-qa.md`](release-qa.md) — manual smoke checklist and balance-acceptance protocol
-- [`../CREDITS.md`](../CREDITS.md) — credits and asset provenance
-- [`../PRIVACY.md`](../PRIVACY.md) — privacy note
-- [`ui-copy.md`](ui-copy.md) — screen, copy and button inventory
-- [`RELEASING.md`](RELEASING.md) — export, CI and publishing workflow
-- [`adr/README.md`](adr/README.md) — architecture decisions
+- [`../PLAN.md`](../PLAN.md) — product, design pillars, gap analysis and the roadmap to 1.0.0
+- [`../TODO.md`](../TODO.md) — milestone-ordered active tasks
+- [`project/architecture.md`](project/architecture.md) — system architecture and ownership
+- [`project/development-status.md`](project/development-status.md) — what the build supports now
+- [`design/gameplay.md`](design/gameplay.md) — the playable loop and escalation model
+- [`design/venues.md`](design/venues.md) — venue mapping and real-site evidence
+- [`assets/npc-model-sourcing.md`](assets/npc-model-sourcing.md) — the active NPC base and licence
+ rules
+- [`assets/3d-model-review.md`](assets/3d-model-review.md) — asset measurements and scorecard
+- [`process/getting-started.md`](process/getting-started.md) — setup, run/test and controls
+- [`../tools/README.md`](../tools/README.md) — tool inventory and test runner
+- [`../CREDITS.md`](../CREDITS.md) — credits, AI/reference provenance and licensing
+- [`../PRIVACY.md`](../PRIVACY.md) — local-only data and save files
-## Visual references
+## Current work
-- [`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
-- [`ui-copy.md`](ui-copy.md#screen-design-judge-report) — screen/button inventory and latest judge result
+v0.9.9 shipped the Quaternius NPC roster. The active patch line is `0.9.10` (roster follow-ups:
+outfit families, the Swat base orientation, per-slot atlases) through `0.9.12`, followed by the
+`0.10.0` public-readiness minor. See [`../TODO.md`](../TODO.md) for the live checklist.
## Quick preview
diff --git a/docs/adr/0015-npc-model-variety-sourcing.md b/docs/adr/0015-npc-model-variety-sourcing.md
index 627d21a..b3bea00 100644
--- a/docs/adr/0015-npc-model-variety-sourcing.md
+++ b/docs/adr/0015-npc-model-variety-sourcing.md
@@ -21,7 +21,7 @@ A review compared free/open-source sources against that contract. Quaternius
Ultimate Modular (CC0), Kenney Blocky Characters (CC0), Khronos CesiumMan and
RiggedFigure (CC BY 4.0) and the MakeHuman base mesh (CC0) were imported and
measured. None was a drop-in; the full results are in
-[`docs/npc-model-sourcing.md`](../npc-model-sourcing.md).
+[`docs/assets/npc-model-sourcing.md`](../assets/npc-model-sourcing.md).
## Decision
@@ -86,4 +86,4 @@ measured. None was a drop-in; the full results are in
- MakeHuman is now an active local development pipeline (body retarget plus project-owned
head/hands), while the procedural library remains the shipped path and CI fallback.
- Blender MCP is optional interactive tooling only; it is not a build, CI, test or runtime
- dependency. Setup is in [`docs/asset-tooling.md#optional-interactive-blender-mcp`](../asset-tooling.md#optional-interactive-blender-mcp).
+ dependency. Setup is in [`docs/assets/asset-tooling.md#optional-interactive-blender-mcp`](../assets/asset-tooling.md#optional-interactive-blender-mcp).
diff --git a/docs/adr/0017-quaternius-npc-base.md b/docs/adr/0017-quaternius-npc-base.md
index f7d52c1..5f83781 100644
--- a/docs/adr/0017-quaternius-npc-base.md
+++ b/docs/adr/0017-quaternius-npc-base.md
@@ -16,7 +16,7 @@ The CC0 **Quaternius Ultimate Modular Characters** pack already provides a
coherent low-poly human silhouette, 21 modular outfits and 24 animation clips.
The researched GLBs (`Casual`, `Casual_Hoodie`, `Worker`) measure 4 meshes, 62
joints and 24 clips each. The owner directed that Quaternius become the NPC
-base. The full evaluation is in [`docs/npc-model-sourcing.md`](../npc-model-sourcing.md).
+base. The full evaluation is in [`docs/assets/npc-model-sourcing.md`](../assets/npc-model-sourcing.md).
## Decision
diff --git a/docs/adr/0018-quaternius-stage2-runtime-rig.md b/docs/adr/0018-quaternius-stage2-runtime-rig.md
index 4f5b929..ca6983b 100644
--- a/docs/adr/0018-quaternius-stage2-runtime-rig.md
+++ b/docs/adr/0018-quaternius-stage2-runtime-rig.md
@@ -10,7 +10,7 @@ ADR-0017 made Quaternius the NPC base and staged the migration: Stage 1 bakes a
proportion-warped mesh onto the existing 13-core contract; Stage 2 adopts the
62-joint rig at runtime only if the warp fails.
-The Stage 1 proportion warp was executed and measured (`docs/npc-model-sourcing.md`
+The Stage 1 proportion warp was executed and measured (`docs/assets/npc-model-sourcing.md`
§Rest-pose and proportion-warp measurement). The arm-down rest pose bakes cleanly, but the
warp to the contract proportions does not:
diff --git a/docs/3d-model-review.md b/docs/assets/3d-model-review.md
similarity index 98%
rename from docs/3d-model-review.md
rename to docs/assets/3d-model-review.md
index bc7cbb8..fa40b93 100644
--- a/docs/3d-model-review.md
+++ b/docs/assets/3d-model-review.md
@@ -1,7 +1,7 @@
# 3D model review (2026-11-03)
Status: **baseline measured; scorecard open.** This is the working document for the unversioned
-`3D model re-evaluation` track in [`TODO.md`](../TODO.md). It records what was measured, what the
+`3D model re-evaluation` track in [`TODO.md`](../../TODO.md). It records what was measured, what the
Blender skill guidance says the targets are, the ranked candidate gaps, and the decisions that
still need the project owner. Nothing here re-opens the accepted 0.9.4 limits by itself.
@@ -88,7 +88,7 @@ Readings:
Recorded for the character baseline before the Quaternius migration. `npc_base.blend` is the
frozen fallback; the 12 characters are currently assembled procedurally by
`tools/blender_assets.py`. The active plan is now the CC0 Quaternius base bake
-([ADR-0017](adr/0017-quaternius-npc-base.md)); this section and the MakeHuman notes below are the
+([ADR-0017](../adr/0017-quaternius-npc-base.md)); this section and the MakeHuman notes below are the
pre-migration record. The MPFB/MakeHuman development files were removed from `tmp/` after the
2026-11-05 pivot.
@@ -283,7 +283,7 @@ front/three-quarter/profile and judged side by side:
The chosen s48 is the `head_proto` default; the rejected s24/s64 stay local under
`tmp/npc-parts/`. A before/after sign-off sheet (current `_face` vs s48, 1.85 m
front/three-quarter/profile) is
-[`blender_previews/sheet_head_proto_before_after.jpg`](blender_previews/sheet_head_proto_before_after.jpg).
+[`blender_previews/sheet_head_proto_before_after.jpg`](../blender_previews/sheet_head_proto_before_after.jpg).
## Foliage language P1 — resolved 2026-11-06
@@ -517,6 +517,6 @@ and the full carded-cluster foliage pass is the one remaining owner-gated P1. No
- Review the assembled [`makehuman-head-review.md`](makehuman-head-review.md) prototype (hair cap and full-body silhouette) before rebuilding the 12 shipped character GLBs.
-Tracked in [`TODO.md`](../TODO.md) `3D model re-evaluation`: the remaining `A. Baseline…` item is
+Tracked in [`TODO.md`](../../TODO.md) `3D model re-evaluation`: the remaining `A. Baseline…` item is
this owner review; `B`/`C`/`D` carry the per-family work, and `E` adds the pose/weight,
collider-coverage and scorecard-coverage gates this document found missing.
diff --git a/docs/assets/README.md b/docs/assets/README.md
new file mode 100644
index 0000000..5a17c1f
--- /dev/null
+++ b/docs/assets/README.md
@@ -0,0 +1,19 @@
+# Asset Documentation
+
+Asset contracts, pipelines, sourcing and reviews. These pages own the measured evidence; the
+executable gates are `tools/blender_assets.py inspect|audit|fit`, `tools/npc_proportions.py` and
+the capture scripts.
+
+- [`blender-assets.md`](blender-assets.md) — Blender library operation, the character/gear/prop
+ contract, attach points and rebuild discipline.
+- [`asset-tooling.md`](asset-tooling.md) — image/model pipelines, the optional Blender MCP setup
+ and the screenshot/vision gates.
+- [`npc-model-sourcing.md`](npc-model-sourcing.md) — character-source evaluation, licence rules,
+ the Quaternius intake and the active NPC plan.
+- [`3d-model-review.md`](3d-model-review.md) — measurements, per-asset scorecard, ranked gaps and
+ accepted limits.
+- [`makehuman-head-review.md`](makehuman-head-review.md) — the retained MakeHuman fallback head,
+ its provenance and the review verdict.
+
+Up: [`../README.md`](../README.md) · Product plan: [`../../PLAN.md`](../../PLAN.md) · Tasks:
+[`../../TODO.md`](../../TODO.md).
diff --git a/docs/asset-tooling.md b/docs/assets/asset-tooling.md
similarity index 95%
rename from docs/asset-tooling.md
rename to docs/assets/asset-tooling.md
index 10f6852..5ace819 100644
--- a/docs/asset-tooling.md
+++ b/docs/assets/asset-tooling.md
@@ -2,7 +2,7 @@
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
+[`architecture.md`](../project/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.
@@ -72,7 +72,7 @@ colours onto material roles (darkest → metal, warm saturated → wood, light g
stone, green → foliage). glTF stores colours in linear space, so the tool converts
the sRGB palettes before writing them. Re-run `build` and `godot --headless
--path . --import` after changing a prop. See
-[ADR-0012](adr/0012-surface-materials-and-generated-props.md).
+[ADR-0012](../adr/0012-surface-materials-and-generated-props.md).
Surface materials share one definition in `src/game/materials.gd`: named
roughness/metallic profiles per surface, plus the environment tune-up (ACES
@@ -81,14 +81,14 @@ tonemapping, glow, fog, colour grading) that the phase lighting applies.
## NPC character model
NPCs are moving from the procedural capsule rig to a skinned, UV-mapped base
-character authored in Blender ([ADR-0013](adr/0013-blender-authored-npc-characters.md)).
+character authored in Blender ([ADR-0013](../adr/0013-blender-authored-npc-characters.md)).
The active base is the CC0 Quaternius modular character, baked to the runtime contract
-([ADR-0017](adr/0017-quaternius-npc-base.md)).
+([ADR-0017](../adr/0017-quaternius-npc-base.md)).
`tools/npc_pipeline.py` builds `assets/models/generated/npc_base.glb` plus the
per-slot material maps. `NpcAvatar` instantiates that skinned model, tints its
five material slots from the seed-driven outfit, and drives the bones from the
existing animation code; the procedural rig remains the offline fallback (see
-[ADR-0013](adr/0013-blender-authored-npc-characters.md) and
+[ADR-0013](../adr/0013-blender-authored-npc-characters.md) and
[`blender-assets.md`](blender-assets.md)).
```bash
@@ -138,7 +138,7 @@ the fallback. Kenney/Khronos/MakeHuman remain evaluated references, not active b
| Characters | Props |
| --- | --- |
-|  |  |
+|  |  |
```bash
flatpak run org.blender.Blender --background --python "$PWD/tools/blender_assets.py" -- build
@@ -246,7 +246,7 @@ gate as `--reference` on `generate`.
`tools/refcollect.py` downloads images from DuckDuckGo image search into `tmp/research//` for
development reference only. It applies **no licence gate** (rows are marked `local_only` /
`unchecked-local`); everything it fetches must never be committed or promoted into
-[`screens/refs/`](screens/refs/README.md) without the normal sidecar licence + privacy gate. This
+[`screens/refs/`](../screens/refs/README.md) without the normal sidecar licence + privacy gate. This
is the owner-authorised local-only override (TODO.md §3D model re-evaluation → A).
```bash
@@ -265,7 +265,7 @@ string); the UA alone is no longer enough to look like a browser.
### Reference-board research (`refboard`)
`tools/refboard.py` searches, fetches and documents Wikimedia Commons photos of a real location for
-the [`screens/refs/`](screens/refs/README.md) boards. It is stdlib-only and never commits anything
+the [`screens/refs/`](../screens/refs/README.md) boards. It is stdlib-only and never commits anything
itself: downloads land in `tmp/`, and moving a file into a board folder is a deliberate manual step
that goes through the sidecar licence gate.
@@ -322,10 +322,10 @@ their SHA-256 in `CREDITS.md`.
## Local map development (planned)
-The local map workstreams (H–M) in [`TODO.md`](../TODO.md#3d-model-re-evaluation) are
+The local map workstreams (H–M) in [`TODO.md`](../../TODO.md#3d-model-and-local-map-re-evaluation) are
planned, not implemented; there are no map-generation commands yet. The runtime
contract, provenance rules, budget/navigation gates and fallback are in
-[`architecture.md#venue-implementation-contract`](architecture.md#venue-implementation-contract).
+[`architecture.md#venue-implementation-contract`](../project/architecture.md#venue-implementation-contract).
The detailed pipeline/task list lives in `TODO.md`.
## Confirmed game assets
@@ -335,9 +335,9 @@ Everything below is audited and shipped in the game; development-only outputs
| | |
| --- | --- |
-|  |  |
-|  |  |
-|  |  |
+|  |  |
+|  |  |
+|  |  |
- **Surface textures:** the v2 picks above (brick, sidewalk pavers, dry and wet asphalt, awning canvas) plus their normal maps, loaded by `src/game/materials.gd` and `WorldBuilder`; the three skyline panoramas are switched per shift phase. The first-generation tiles and `assets/textures/skyline.png` are no longer loaded.
- **UI art:** `assets/textures/ai/game_ready/icons/` (flashlight, door lock, wand, REC) and `assets/textures/ai/game_ready/cards/` (ID, wristband, ticket, credential, guest list), loaded by `src/game/ui/hud.gd`.
@@ -511,7 +511,7 @@ remain optional interactive exploration; the headless commands stay the build an
## Realism pass: scene concepts, skylines and textures
The skyline, surface tiles and phase lighting were rebuilt against AI concept frames. The
-concepts live in [`docs/screens/concepts/`](../docs/screens/concepts/README.md); the validated
+concepts live in [`docs/screens/concepts/`](../screens/concepts/README.md); the validated
picks the game loads are in `assets/textures/ai/game_ready/v2/picks/` (day/dusk/night
panoramas, brick, sidewalk pavers, dry and wet asphalt, awning canvas, each with a normal
map).
@@ -633,7 +633,7 @@ texture detail 1.2, backdrop 2.0 and characters 1.2; the Pillow metric gap was
particularly lit night facades and dense backdrop detail. That is expected: the
pass validated close-range surfaces and promoted the texture repairs, not a
photoreal renderer. The 0.9.5 before/after close-up sheet is
-[`blender_previews/sheet_texture_refinement_0.9.5.jpg`](blender_previews/sheet_texture_refinement_0.9.5.jpg);
+[`blender_previews/sheet_texture_refinement_0.9.5.jpg`](../blender_previews/sheet_texture_refinement_0.9.5.jpg);
the texture-adoption run itself was the earlier 0.8-style candidate comparison,
and its report remains local/gitignored.
diff --git a/docs/blender-assets.md b/docs/assets/blender-assets.md
similarity index 95%
rename from docs/blender-assets.md
rename to docs/assets/blender-assets.md
index 5af220b..bcbe7c1 100644
--- a/docs/blender-assets.md
+++ b/docs/assets/blender-assets.md
@@ -1,21 +1,21 @@
# Blender asset library
Architecture context: the asset contracts and fallback path are summarized in
-[`architecture.md`](architecture.md#content-and-asset-pipeline-architecture).
+[`architecture.md`](../project/architecture.md#content-and-asset-pipeline-architecture).
Status: built, audited, and integrated (2026-11-01). The active character migration
replaces the procedural body with a baked CC0 Quaternius base
-([ADR-0017](adr/0017-quaternius-npc-base.md)); the current library remains the shipped
+([ADR-0017](../adr/0017-quaternius-npc-base.md)); the current library remains the shipped
fallback until the Quaternius 12-variant baseline passes review. `NpcAvatar` selects the
character variants and attaches the gear; `WorldBuilder` loads the prop library
with colliders and phase-driven emissives. The 0.9.4 neutral baseline and its
-acceptance criteria are in [`architecture.md`](architecture.md#character-and-gear-asset-contract);
+acceptance criteria are in [`architecture.md`](../project/architecture.md#character-and-gear-asset-contract);
the committed 8 × 6 contact sheet is
-[`blender_previews/sheet_npc_baseline.jpg`](blender_previews/sheet_npc_baseline.jpg).
+[`blender_previews/sheet_npc_baseline.jpg`](../blender_previews/sheet_npc_baseline.jpg).
-Generator: [`tools/blender_assets.py`](../tools/blender_assets.py). Manifest (the
+Generator: [`tools/blender_assets.py`](../../tools/blender_assets.py). Manifest (the
source of truth for integration):
-[`assets/models/blender/manifest.json`](../assets/models/blender/manifest.json).
+[`assets/models/blender/manifest.json`](../../assets/models/blender/manifest.json).
## Art direction
@@ -143,7 +143,7 @@ render about 2.5 min.
## Characters
All library variants share the
-[character and gear asset contract](architecture.md#character-and-gear-asset-contract):
+[character and gear asset contract](../project/architecture.md#character-and-gear-asset-contract):
`npc_base` mesh node, five tint slots, +Z visual front, 24,000/24,000 character budget and the
same 256² slot-map/AO rules. The shipped roster is on the 62-joint Quaternius skeleton
(ADR-0018); the procedural fallback built by `build --source procedural` keeps the 13 core bones.
@@ -201,7 +201,7 @@ the role's `TYPE_COLORS`.
## Gear attach points
Gear is authored in attach-point space; the exact contract and runtime fit offsets are in
-[`architecture.md#character-and-gear-asset-contract`](architecture.md#character-and-gear-asset-contract).
+[`architecture.md#character-and-gear-asset-contract`](../project/architecture.md#character-and-gear-asset-contract).
The shipped matrix is **fifteen pieces** since the hat removal (owner, 2026-11-06): `cap` and
`hood` are retired, and `firefighter_helmet` is the only head item.
@@ -278,7 +278,7 @@ carry baked AO and the shared neutral material maps described above.
`npc_base`, the bones accept `NpcAvatar`'s pose composition, and props are
grounded.
- `tools/test_model_review.py`: every `CHARACTERS`/`GEAR`/`PROPS` entry has a
- scorecard row and verdict in `docs/3d-model-review.md` (coverage gate).
+ scorecard row and verdict in `docs/assets/3d-model-review.md` (coverage gate).
- `src/test/tests/test_world.gd`: every library prop that blocks walking has a
`StaticBody3D` + `NavigationObstacle3D`, checked against the catalogue
(collider/proxy gate).
diff --git a/docs/makehuman-head-review.md b/docs/assets/makehuman-head-review.md
similarity index 95%
rename from docs/makehuman-head-review.md
rename to docs/assets/makehuman-head-review.md
index 0ba887a..c9c5d7f 100644
--- a/docs/makehuman-head-review.md
+++ b/docs/assets/makehuman-head-review.md
@@ -10,8 +10,8 @@ base. The development source files were removed from `tmp/` on 2026-11-05.
## Asset
-- GLB: [`assets/models/blender_src/makehuman_head.glb`](../assets/models/blender_src/makehuman_head.glb)
-- Review sheet: [`blender_previews/sheet_makehuman_head.jpg`](blender_previews/sheet_makehuman_head.jpg)
+- GLB: [`assets/models/blender_src/makehuman_head.glb`](../../assets/models/blender_src/makehuman_head.glb)
+- Review sheet: [`blender_previews/sheet_makehuman_head.jpg`](../blender_previews/sheet_makehuman_head.jpg)
- Source workflow (development-only, files removed after the Quaternius pivot;
retained here as the historical method) — extracts the MakeHuman head, cuts it at the neck, keeps the head/eye/mouth
components, cuts an almond aperture through a skin eyelid mask, adds recessed
@@ -26,7 +26,7 @@ base. The development source files were removed from `tmp/` on 2026-11-05.
- Materials used: `skin`, `eye_white`, `iris`, `pupil`, `hair`. No textures are
baked into this prototype.
-
+
## What was done
@@ -54,7 +54,7 @@ base. The development source files were removed from `tmp/` on 2026-11-05.
- Base mesh: MakeHuman / MPFB base, CC0, from the local research set
(development source files removed after the 2026-11-05 Quaternius pivot); see
- [`CREDITS.md`](../CREDITS.md).
+ [`CREDITS.md`](../../CREDITS.md).
- The head is a **derived prototype**, not a shipped NPC. It does not enter
`assets/models/blender/npc/`, `npc_base`, the runtime `NpcAvatar` path, CI, or
a release package. It is retained as a fallback, not the active NPC base.
diff --git a/docs/npc-model-sourcing.md b/docs/assets/npc-model-sourcing.md
similarity index 96%
rename from docs/npc-model-sourcing.md
rename to docs/assets/npc-model-sourcing.md
index 102c7f9..818fd20 100644
--- a/docs/npc-model-sourcing.md
+++ b/docs/assets/npc-model-sourcing.md
@@ -1,8 +1,8 @@
# NPC Model Sourcing
This page records the source evaluation and the active character plan. The
-decision is [ADR-0017](adr/0017-quaternius-npc-base.md), which supersedes the
-generator-first sourcing decision in [ADR-0015](adr/0015-npc-model-variety-sourcing.md).
+decision is [ADR-0017](../adr/0017-quaternius-npc-base.md), which supersedes the
+generator-first sourcing decision in [ADR-0015](../adr/0015-npc-model-variety-sourcing.md).
## Active direction
@@ -198,7 +198,7 @@ deltoid + hand) — both are the gate's rejection conditions.
contract proportions; the gate fails and Stage 2 (a 62-joint runtime ADR) is indicated. Do not
start the 12-variant rebuild on the warped base.
-[ADR-0018](adr/0018-quaternius-stage2-runtime-rig.md) records the Stage 2 decision (accepted
+[ADR-0018](../adr/0018-quaternius-stage2-runtime-rig.md) records the Stage 2 decision (accepted
2026-11-05, owner chose option 2): adopt the **Quaternius 62-joint rig at runtime**, keep the
mesh at source LOD, re-derive gear attach points from the Quaternius skeleton, and use the
Quaternius Idle/Walk clips directly (no retarget).
@@ -237,7 +237,7 @@ Two source quirks shaped the bake:
contract is applied as a rename, not a re-author.
The face/silhouette gate that chose the full swap is recorded in the follow-up decision of
-[ADR-0018](adr/0018-quaternius-stage2-runtime-rig.md); its comparison sheets were retired with the
+[ADR-0018](../adr/0018-quaternius-stage2-runtime-rig.md); its comparison sheets were retired with the
review pages.
## Shipped roster (0.9.9, owner chose the full swap)
@@ -354,7 +354,7 @@ not a local workaround.
## Licence and provenance
- CC0 preferred. CC-BY is allowed only with attribution in
- [`CREDITS.md`](../CREDITS.md).
+ [`CREDITS.md`](../../CREDITS.md).
- No service asset whose terms restrict redistribution may be shipped.
- Keep the source URL, author, licence, download date and SHA-256 in this page
and in `CREDITS.md`.
@@ -369,12 +369,12 @@ The MakeHuman/MPFB body pipeline is closed for the NPC base. The accepted
MakeHuman head and the procedural `npc_base` remain tested fallbacks until the
Quaternius rollout is complete. Their research scripts and renders were removed
from `tmp/` after the pivot; the measurements and decisions remain in
-[`DONE.md`](../DONE.md), [`MEMORY.md`](../MEMORY.md) and the review docs.
+[`DONE.md`](../../DONE.md), [`MEMORY.md`](../../MEMORY.md) and the review docs.
## Related documents
-- [ADR-0017: Quaternius NPC base](adr/0017-quaternius-npc-base.md)
-- [ADR-0016: 24,000-triangle character budget](adr/0016-npc-character-budget-24k.md)
-- [Blender asset contract](architecture.md#character-and-gear-asset-contract)
+- [ADR-0017: Quaternius NPC base](../adr/0017-quaternius-npc-base.md)
+- [ADR-0016: 24,000-triangle character budget](../adr/0016-npc-character-budget-24k.md)
+- [Blender asset contract](../project/architecture.md#character-and-gear-asset-contract)
- [`3d-model-review.md`](3d-model-review.md)
- [`asset-tooling.md`](asset-tooling.md)
diff --git a/docs/blender_previews/README.md b/docs/blender_previews/README.md
index 9ee4eaa..e7b15cf 100644
--- a/docs/blender_previews/README.md
+++ b/docs/blender_previews/README.md
@@ -9,7 +9,7 @@ capture harnesses.
| --- | --- |
| [](sheet_npc.jpg)
`sheet_npc.jpg` | Eight skinned character variants (casual, jacket, coat, hi-vis vest, dress, hoodie, firefighter, guard) with their gear attach points. |
| [](sheet_npc_baseline.jpg)
`sheet_npc_baseline.jpg` | Neutral studio baseline: 8 characters x front, three-quarter, profile, back, full body and crowd views. |
-| [](sheet_makehuman_head.jpg)
`sheet_makehuman_head.jpg` | MakeHuman head: front, three-quarter and profile review views. The owner accepted the basic head; the automated vision gate still rejects the eye/lid region as deferred polish. See [`../makehuman-head-review.md`](../makehuman-head-review.md). |
+| [](sheet_makehuman_head.jpg)
`sheet_makehuman_head.jpg` | MakeHuman head: front, three-quarter and profile review views. The owner accepted the basic head; the automated vision gate still rejects the eye/lid region as deferred polish. See [`../makehuman-head-review.md`](../assets/makehuman-head-review.md). |
| [](sheet_npc_baseline_compare-body.jpg)
`sheet_npc_baseline_compare-body.jpg` | Neck/shoulder transition: fuller neck base and a lower shoulder root. |
| [](sheet_npc_baseline_compare-face-detail.jpg)
`sheet_npc_baseline_compare-face-detail.jpg` | Face detail: nose ala wings, a single rounded mouth and a darker ear concha. |
| [](sheet_npc_baseline_compare-face.jpg)
`sheet_npc_baseline_compare-face.jpg` | Face-depth pass: recessed sclera, upper lid and sculpted chin/cheek planes. |
@@ -27,5 +27,5 @@ capture harnesses.
| [](sheet_props.jpg)
`sheet_props.jpg` | Twenty street and venue props with baked maps, ground contact and collider footprints. |
| [](sheet_texture_refinement_0.9.5.jpg)
`sheet_texture_refinement_0.9.5.jpg` | 0.9.5 texture refinement before/after: pavers, awning stripes and NPC fabric. |
-The measurements are in [`../3d-model-review.md`](../3d-model-review.md) and the asset contract in
-[`../blender-assets.md`](../blender-assets.md).
+The measurements are in [`../3d-model-review.md`](../assets/3d-model-review.md) and the asset contract in
+[`../blender-assets.md`](../assets/blender-assets.md).
diff --git a/docs/design/README.md b/docs/design/README.md
new file mode 100644
index 0000000..059283b
--- /dev/null
+++ b/docs/design/README.md
@@ -0,0 +1,13 @@
+# Design Documentation
+
+Gameplay, venues, presentation and player-facing constraints.
+
+- [`gameplay.md`](gameplay.md) — the playable loop, escalation mechanics, venues and tutorial.
+- [`venues.md`](venues.md) — real-site evidence, game mapping and venue simplifications.
+- [`ui-copy.md`](ui-copy.md) — screen, copy and button inventory plus the screen-design judge
+ record.
+- [`accessibility.md`](accessibility.md) — accessibility statement and known gaps.
+- [`known-limitations.md`](known-limitations.md) — release blockers and accepted limitations.
+
+Up: [`../README.md`](../README.md) · Product plan: [`../../PLAN.md`](../../PLAN.md) · Tasks:
+[`../../TODO.md`](../../TODO.md).
diff --git a/docs/accessibility.md b/docs/design/accessibility.md
similarity index 90%
rename from docs/accessibility.md
rename to docs/design/accessibility.md
index 2283703..d374ad7 100644
--- a/docs/accessibility.md
+++ b/docs/design/accessibility.md
@@ -28,5 +28,5 @@ Known gaps:
review is still a 0.10.0 release-review item.
Test evidence and the manual checklist live in
-[`release-qa.md`](release-qa.md#manual-smoke-checklist); settings and save behaviour are
-documented in [`getting-started.md`](getting-started.md).
+[`release-qa.md`](../process/release-qa.md#manual-smoke-checklist); settings and save behaviour are
+documented in [`getting-started.md`](../process/getting-started.md).
diff --git a/docs/gameplay.md b/docs/design/gameplay.md
similarity index 98%
rename from docs/gameplay.md
rename to docs/design/gameplay.md
index 58a6f07..7d83748 100644
--- a/docs/gameplay.md
+++ b/docs/design/gameplay.md
@@ -1,6 +1,6 @@
# Gameplay
-The complete design rationale also lives in [`PLAN.md`](../PLAN.md); this page keeps the playable mechanics close to the README.
+The complete design rationale also lives in [`PLAN.md`](../../PLAN.md); this page keeps the playable mechanics close to the README.
## Game Overview
diff --git a/docs/known-limitations.md b/docs/design/known-limitations.md
similarity index 95%
rename from docs/known-limitations.md
rename to docs/design/known-limitations.md
index 0740050..85b961d 100644
--- a/docs/known-limitations.md
+++ b/docs/design/known-limitations.md
@@ -12,7 +12,7 @@ public release.
observation.
- **AI asset provenance:** the image-generation provider terms and commercial
redistribution rights for the committed AI-assisted textures/UI art still need
- legal review. See [`../CREDITS.md`](../CREDITS.md).
+ legal review. See [`../CREDITS.md`](../../CREDITS.md).
- **Storefront/legal approval:** age/content rating, storefront policy, trademark
language and the mental-health-crisis/body-camera representation have not been
externally approved.
@@ -31,7 +31,7 @@ public release.
- Character faces, hands and fabric use a deliberately low-poly style; the
>26 m tier remains a two-quad impostor and there is no separate finger-curl
rig. The accepted limits are recorded in
- [`npc-model-sourcing.md`](npc-model-sourcing.md).
+ [`npc-model-sourcing.md`](../assets/npc-model-sourcing.md).
- There is no live 3D body-camera replay; the timeline is text-based.
- There is no recorded voice/music track. Ambience and cues are procedural.
- The game is English-only and does not yet have a translator workflow or
diff --git a/docs/ui-copy.md b/docs/design/ui-copy.md
similarity index 97%
rename from docs/ui-copy.md
rename to docs/design/ui-copy.md
index e590936..d17a703 100644
--- a/docs/ui-copy.md
+++ b/docs/design/ui-copy.md
@@ -1,6 +1,6 @@
# UI copy and button inventory
-Status: dialogue, button-state, focus, modal-close, font/layout, destructive-action and end-to-end passes complete; capture/smoke sign-off remains for 0.9.3.
+Status: complete (0.9.3). Retained as the screen/button inventory, copy audit and screen-design judge record.
## Screen inventory
@@ -236,9 +236,9 @@ Command: `python3 tools/screen_designs.py judge`
Result: **21/21 match, 0 review, 0 diff**
The screenshot gallery was regenerated on the current build before judging, including the eight UI-state captures 14–21 added in `src/test/capture_ui_states.gd`.
-Accepted captures are in [`docs/screens/`](screens/README.md); the committed
-gallery is in [`docs/screenshots/`](screenshots/README.md).
+Accepted captures are in [`docs/screens/`](../screens/README.md); the committed
+gallery is in [`docs/screenshots/`](../screenshots/README.md).
The automatic model selection and retry/spend behavior is documented in
-[`docs/asset-tooling.md`](asset-tooling.md). This report intentionally records
+[`docs/assets/asset-tooling.md`](../assets/asset-tooling.md). This report intentionally records
the outcome rather than generated captures, which remain local/gitignored.
diff --git a/docs/venues.md b/docs/design/venues.md
similarity index 94%
rename from docs/venues.md
rename to docs/design/venues.md
index 14a5020..9520b91 100644
--- a/docs/venues.md
+++ b/docs/design/venues.md
@@ -11,7 +11,7 @@ The game uses two physical Hollywood blocks across three playable venue rows:
The runtime implementation contract (facade specs, map budgets, navigation,
colliders, phase behavior and fallback) lives in
-[`architecture.md`](architecture.md#venue-implementation-contract). This page
+[`architecture.md`](../project/architecture.md#venue-implementation-contract). This page
keeps the real-site evidence, mapping decisions and deliberate simplifications.
## Hollywood Boulevard
@@ -49,7 +49,7 @@ keeps the real-site evidence, mapping decisions and deliberate simplifications.
| TV Studio arrival | same six-column facade/eight steps plus bulb canopy, sedan, handrail and barriers |
The generated references in
-[`screens/concepts/hollywood_boulevard/`](screens/concepts/hollywood_boulevard/README.md)
+[`screens/concepts/hollywood_boulevard/`](../screens/concepts/hollywood_boulevard/README.md)
are art direction for lighting, material scale and composition; they are not
texture or geometry sources.
@@ -128,9 +128,9 @@ The guard starts west of the entrance at (-4.8, 0.1, 1.4), facing the approach.
- [Hollywood Masonic Temple facade — Wikimedia Commons](https://commons.wikimedia.org/wiki/File:El_Capitan_Theater_frontal_fachade-The_Masonic_Temple.jpg)
- [Hollywood Masonic Temple and El Capitan Theatre, 2013 — Wikimedia Commons](https://commons.wikimedia.org/wiki/File:Hollywood_Masonic_Temple_2013-10-13_10-02-25.jpg)
- [Comedy Store — OpenStreetMap way 428854155](https://www.openstreetmap.org/way/428854155)
-- Committed photo boards: [`screens/refs/hollywood/`](screens/refs/hollywood/README.md),
- [`screens/refs/joke-shop/`](screens/refs/joke-shop/README.md); three-up boards
- are in [`screens/boards/`](screens/boards/README.md).
+- Committed photo board: [`screens/refs/hollywood/`](../screens/refs/hollywood/README.md);
+ three-up boards are in [`screens/boards/`](../screens/boards/README.md). The Joke Shop has no
+ committed photo board: its reference set stays local-only under `tmp/research/comedy-store/`.
- Local-only research (never committed): `tmp/research/elcapitan-2026/`,
`tmp/research/jimmy-kimmel-entrance/`, `tmp/research/comedy-store/` and
`tmp/research/comedy-store-hillside/`. These are evidence for decisions, not
diff --git a/docs/process/README.md b/docs/process/README.md
new file mode 100644
index 0000000..f823c85
--- /dev/null
+++ b/docs/process/README.md
@@ -0,0 +1,11 @@
+# Process Documentation
+
+Setup, quality assurance and releasing.
+
+- [`getting-started.md`](getting-started.md) — setup, run/test commands, controls and save data.
+- [`release-qa.md`](release-qa.md) — the manual smoke checklist and the balance-acceptance
+ protocol.
+- [`RELEASING.md`](RELEASING.md) — export templates, release build, CI/publishing and rollback.
+
+Up: [`../README.md`](../README.md) · Product plan: [`../../PLAN.md`](../../PLAN.md) · Tasks:
+[`../../TODO.md`](../../TODO.md).
diff --git a/docs/RELEASING.md b/docs/process/RELEASING.md
similarity index 98%
rename from docs/RELEASING.md
rename to docs/process/RELEASING.md
index b0d4ddb..1d02704 100644
--- a/docs/RELEASING.md
+++ b/docs/process/RELEASING.md
@@ -127,7 +127,7 @@ the documented right-click/`xattr` quarantine instructions. Signing and
notarization remain a public-release blocker until an Apple Developer account and
a reproducible signing/notarization job are available; they are not silently
claimed as complete. The same limitation is recorded in
-[`known-limitations.md`](known-limitations.md).
+[`known-limitations.md`](../design/known-limitations.md).
Always run the release build from a clean checkout or detached worktree. Godot
can pack files from ignored `tmp/` and old `build/` folders into the PCK; the
@@ -205,7 +205,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 `docs/getting-started.md` match the build.
+- [ ] Controls documented in `docs/process/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.
diff --git a/docs/getting-started.md b/docs/process/getting-started.md
similarity index 98%
rename from docs/getting-started.md
rename to docs/process/getting-started.md
index 5a86c46..5dcd120 100644
--- a/docs/getting-started.md
+++ b/docs/process/getting-started.md
@@ -87,7 +87,7 @@ The game writes four JSON files in Godot's `user://` directory:
Files: `settings.json`, `campaign.json`, `shift_results.json` and the versioned
`shift_state.json` checkpoint. The schema, migration/default-filling rules,
atomic-write behavior and checkpoint contents are in
-[`architecture.md#persistence-and-save-contract`](architecture.md#persistence-and-save-contract).
+[`architecture.md#persistence-and-save-contract`](../project/architecture.md#persistence-and-save-contract).
For a clean first launch, delete the four files (or the whole `Gig Line` user
directory). Settings' **Reset campaign** clears campaign progress separately.
diff --git a/docs/release-qa.md b/docs/process/release-qa.md
similarity index 98%
rename from docs/release-qa.md
rename to docs/process/release-qa.md
index fa8e080..3278059 100644
--- a/docs/release-qa.md
+++ b/docs/process/release-qa.md
@@ -60,8 +60,8 @@ owns the mechanics.
These are the acceptance targets for the 0.10.0 balance pass, not measured results.
No reaction tables, event weights or scoring rules were changed to set them. The
-[roadmap](../TODO.md) tracks the sweeps and external playtests still needed.
-[Gameplay](gameplay.md) owns the mechanics; this page owns their balance-test protocol.
+[roadmap](../../TODO.md) tracks the sweeps and external playtests still needed.
+[Gameplay](../design/gameplay.md) owns the mechanics; this page owns their balance-test protocol.
### Test matrix and evidence
diff --git a/docs/project/README.md b/docs/project/README.md
new file mode 100644
index 0000000..ccb81f8
--- /dev/null
+++ b/docs/project/README.md
@@ -0,0 +1,11 @@
+# Project Documentation
+
+Architecture and project status.
+
+- [`architecture.md`](architecture.md) — the arc42-style architecture: goals, constraints,
+ building blocks, runtime views, decisions and risks.
+- [`development-status.md`](development-status.md) — the canonical implemented-features list,
+ verification baseline and known gaps.
+
+Up: [`../README.md`](../README.md) · Product plan: [`../../PLAN.md`](../../PLAN.md) · Tasks:
+[`../../TODO.md`](../../TODO.md).
diff --git a/docs/architecture.md b/docs/project/architecture.md
similarity index 86%
rename from docs/architecture.md
rename to docs/project/architecture.md
index 06c6b9b..49f5dd7 100644
--- a/docs/architecture.md
+++ b/docs/project/architecture.md
@@ -27,8 +27,8 @@ This document follows the structure of the arc42 architecture documentation temp
- The first implementation should be small enough for a playable vertical slice.
- The engine is Godot 4.7.2 with GDScript; a playable prototype vertical slice is implemented. CI, local development and exported builds use 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).
+- 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).
- The project follows [Semantic Versioning](https://semver.org/) (`MAJOR.MINOR.PATCH`).
### Version management
@@ -37,7 +37,7 @@ This document follows the structure of the arc42 architecture documentation temp
- **MINOR** — new venues, NPC archetypes, systems, or features that are backward compatible.
- **PATCH** — bug fixes and small polish that do not change behavior.
-The single source of truth for the version is `config/version` in `project.godot` (currently `0.9.8`). Each release is tagged in git as `v` (e.g. `v0.6.0`). The `0.x` series is pre-stable, so MINOR bumps may introduce breaking changes while the prototype is still stabilizing. `tools/build_releases.sh` and `tools/publish_release.sh` read the version from `project.godot`, so bumping it there is the only required step before a release. The full bump checklist lives in [`RELEASING.md`](RELEASING.md).
+The single source of truth for the version is `config/version` in `project.godot` (currently `0.9.9`). Each release is tagged in git as `v` (e.g. `v0.6.0`). The `0.x` series is pre-stable, so MINOR bumps may introduce breaking changes while the prototype is still stabilizing. `tools/build_releases.sh` and `tools/publish_release.sh` read the version from `project.godot`, so bumping it there is the only required step before a release. The full bump checklist lives in [`RELEASING.md`](../process/RELEASING.md).
## 3. Context and Scope
@@ -82,7 +82,7 @@ The player interacts with NPCs, venue entrances, access artifacts, equipment, st
- `src/game/ui/art.gd` loads runtime UI/scene art from `assets/images/ui/` and `assets/images/scenes/`, with null fallbacks so panels keep their procedural layouts.
- `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). The active character migration bakes the CC0 Quaternius base onto the same contract (ADR-0017); the procedural base remains the fallback.
-- `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/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/assets/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 (six stages, runtime texture swaps) against the concepts (`docs/screens/realism//`).
- `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.
@@ -90,7 +90,7 @@ Confirmed game assets live in `assets/textures/ai/game_ready/` (audited surface,
### Asset storage conventions
-The canonical rules live in [ADR-0014](adr/0014-runtime-image-root.md). In short:
+The canonical rules live in [ADR-0014](../adr/0014-runtime-image-root.md). In short:
| Location | Contents | Loaded at runtime? |
| --- | --- | --- |
@@ -190,7 +190,7 @@ Venue rules:
Persistence is local-only under Godot's `user://` directory. The architecture
owns the schema; operational locations and reset/rollback steps live in
-[`getting-started.md`](getting-started.md#save-data-and-migration).
+[`getting-started.md`](../process/getting-started.md#save-data).
| File | Contents | Compatibility |
| --- | --- | --- |
@@ -220,8 +220,8 @@ developer tools only — runtime, tests and CI consume committed GLBs and maps.
| `tools/npc_pipeline.py` | Builds the skinned base avatar, five-slot material maps, palette and AI-fabric preparation (`prepare`/`palette`) | `npc_base.glb`, `assets/textures/npc/*_{albedo,normal,orm}.png`, `palette.json` | `audit_glb` against the 24,000-triangle / 24,000-vertex base contract (13 core bones required; extras allowed) |
| `tools/blender_assets.py` | Builds/renders the library: 12 characters, 15 gear pieces, 20 props, plus `manifest.json`; stdlib `audit`/`fit`/`sheet`/`list` | `assets/models/blender/{npc,npc_gear,props}/*.glb` | Character cap 24,000 tris / 24,000 verts, 1,500 per gear, 4,000 per prop; grounding, UV, degenerate-triangle, attach-fit and manifest coverage checks |
| `tools/bake_ao.py` | Bakes per-asset AO maps | `_ao.png` (256²) | Wired through `Materials.apply_ao()`/`SurfaceMaterials`; cloth/pants opt out (see below) |
-| `tools/npc_proportions.py` | Measures exported GLB rest pose (height, head, shoulders, hips, torso, limbs, feet) against the stylized guide | report / JSON in `docs/3d-model-review.md#character-measurements` | All eight variants must stay inside the guide after a body change |
-| `tools/npc_baseline.py` | Assembles neutral-baseline sheets and before/after comparisons | `docs/blender_previews/sheet_npc_baseline*.jpg` | Human review against `docs/3d-model-review.md` |
+| `tools/npc_proportions.py` | Measures exported GLB rest pose (height, head, shoulders, hips, torso, limbs, feet) against the stylized guide | report / JSON in `docs/assets/3d-model-review.md#character-measurements` | All eight variants must stay inside the guide after a body change |
+| `tools/npc_baseline.py` | Assembles neutral-baseline sheets and before/after comparisons | `docs/blender_previews/sheet_npc_baseline*.jpg` | Human review against `docs/assets/3d-model-review.md` |
| `src/test/capture_npc_baseline.gd` | Fixed-camera studio baseline, 8 variants × 6 views | local `tmp/` frames | Neutral silhouette/face/gear review |
| `src/test/capture_npc_review.gd` | Final-context gate: 8 variants × 2 venues × day/night × 3 distances = 96 frames, crowd hidden, review-only `character_override` for the guard | local `tmp/` frames | Pre-build acceptance gate for gear fit and venue lighting |
| `src/test/capture_realism.gd` | Venue realism stages plus a frozen portrait and surface close-ups | `docs/screens/realism//` | Optional vision judge; portrait is the only avatar-detail capture |
@@ -243,16 +243,16 @@ Runtime contracts that must survive any character change:
- Rebuild only the assets whose geometry changed (Blender GLB export is byte-nondeterministic),
then run `godot --headless --path . --import`; never commit a no-op full rebuild.
-Evidence and detailed contracts live in [`blender-assets.md`](blender-assets.md),
-[`3d-model-review.md`](3d-model-review.md) and
-[`3d-model-review.md#character-measurements`](3d-model-review.md#character-measurements); command-level usage is in
-[`asset-tooling.md`](asset-tooling.md).
+Evidence and detailed contracts live in [`blender-assets.md`](../assets/blender-assets.md),
+[`3d-model-review.md`](../assets/3d-model-review.md) and
+[`3d-model-review.md#character-measurements`](../assets/3d-model-review.md#character-measurements); command-level usage is in
+[`asset-tooling.md`](../assets/asset-tooling.md).
### Local map development tooling (planned)
The current venues are hand-authored procedural reconstructions in
`src/game/world_builder.gd`. The local map workstreams (**H–M**) in
-[`TODO.md`](../TODO.md#3d-model-re-evaluation) are unversioned and planned: they will
+[`TODO.md`](../../TODO.md#3d-model-and-local-map-re-evaluation) are unversioned and planned: they will
test whether licensed data and reference photography can replace or supplement the
stylized geometry without moving map data, AI composition or splat rendering into
the runtime.
@@ -353,7 +353,7 @@ Releases are produced from a tagged commit and published to the repository host'
- `tools/build_releases.sh` — exports the desktop binaries and Web zip into `build/`, named `gig-line--.`.
- `tools/publish_release.sh` — creates a release and uploads the artifacts via the Gitea API, using `GITEA_TOKEN` or the checkout extraheader fallback.
- Packaging — NSIS builds the Windows installer; `packaging/linux/build_appimage.sh` builds the AppImage.
-- [`RELEASING.md`](RELEASING.md) — step-by-step guide and release checklist.
+- [`RELEASING.md`](../process/RELEASING.md) — step-by-step guide and release checklist.
The release process is: bump the version, run the full test suite and `tools/check_screenshots.sh`, run `tools/build_releases.sh`, tag and push (CI publishes), then verify the README "Downloads" links and the release artifacts.
@@ -372,27 +372,27 @@ The release process is: bump the version, run the full test suite and `tools/che
- **Campaign and checkpoint state:** `Campaign` owns venue order/progression; settings, campaign, completed shift history and a versioned pause checkpoint are separate JSON documents. The checkpoint snapshots coordinator systems, scheduler RNG and NPC presentation/access state; it deliberately does not serialize the tutorial overlay or transient input state.
- **Difficulty:** easy/normal/hard only scale spawn pacing, NPC compliance tolerance and report-credibility strictness; access/escalation rules and emergency rarity are invariant.
- **Settings and accessibility:** volume/motion/caption settings persist through `settings.json`; Help is generated from the input-binding catalogue and the HUD log is the text caption surface. CI/release, local development and exported builds are unified on Godot 4.7.2.
-- **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.
+- **Documentation ownership:** `PLAN.md` owns design intent; `docs/design/gameplay.md` owns playable mechanics; `docs/project/architecture.md` owns system boundaries, data flow, constraints and cross-cutting decisions; ADRs own decision history; `docs/project/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
Architecture decisions are recorded as ADRs:
-- [ADR-0001: Venue-driven simulation architecture](adr/0001-venue-driven-simulation-architecture.md)
-- [ADR-0002: De-escalation-first escalation model](adr/0002-de-escalation-first-escalation-model.md)
-- [ADR-0003: Explicit access-verification system](adr/0003-explicit-access-verification-system.md)
-- [ADR-0004: Local single-player first](adr/0004-local-single-player-first.md)
-- [ADR-0005: Event-based incident recording](adr/0005-event-based-incident-recording.md)
-- [ADR-0006: Godot 4 with GDScript](adr/0006-godot-4-gdscript.md)
-- [ADR-0007: Locomotion and input layers](adr/0007-locomotion-and-input-layers.md)
-- [ADR-0008: Cone focus and focus circle](adr/0008-cone-focus-and-head-ring.md)
-- [ADR-0009: Radial action menu](adr/0009-radial-action-menu.md)
-- [ADR-0010: Procedural NPC presentation](adr/0010-procedural-npc-presentation.md)
-- [ADR-0017: Quaternius NPC base](adr/0017-quaternius-npc-base.md)
-- [ADR-0011: Aim-free selection and precision walk](adr/0011-aim-free-selection-and-precision-walk.md)
-- [ADR-0012: Surface materials and generated props](adr/0012-surface-materials-and-generated-props.md)
-- [ADR-0013: Blender-authored NPC characters and baked materials](adr/0013-blender-authored-npc-characters.md)
-- [ADR-0014: Canonical runtime image root and image conventions](adr/0014-runtime-image-root.md)
+- [ADR-0001: Venue-driven simulation architecture](../adr/0001-venue-driven-simulation-architecture.md)
+- [ADR-0002: De-escalation-first escalation model](../adr/0002-de-escalation-first-escalation-model.md)
+- [ADR-0003: Explicit access-verification system](../adr/0003-explicit-access-verification-system.md)
+- [ADR-0004: Local single-player first](../adr/0004-local-single-player-first.md)
+- [ADR-0005: Event-based incident recording](../adr/0005-event-based-incident-recording.md)
+- [ADR-0006: Godot 4 with GDScript](../adr/0006-godot-4-gdscript.md)
+- [ADR-0007: Locomotion and input layers](../adr/0007-locomotion-and-input-layers.md)
+- [ADR-0008: Cone focus and focus circle](../adr/0008-cone-focus-and-head-ring.md)
+- [ADR-0009: Radial action menu](../adr/0009-radial-action-menu.md)
+- [ADR-0010: Procedural NPC presentation](../adr/0010-procedural-npc-presentation.md)
+- [ADR-0017: Quaternius NPC base](../adr/0017-quaternius-npc-base.md)
+- [ADR-0011: Aim-free selection and precision walk](../adr/0011-aim-free-selection-and-precision-walk.md)
+- [ADR-0012: Surface materials and generated props](../adr/0012-surface-materials-and-generated-props.md)
+- [ADR-0013: Blender-authored NPC characters and baked materials](../adr/0013-blender-authored-npc-characters.md)
+- [ADR-0014: Canonical runtime image root and image conventions](../adr/0014-runtime-image-root.md)
## 10. Quality Requirements
@@ -435,32 +435,32 @@ 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, tutorial, venue mechanics | Runtime/behavioral view |
-| [`docs/venues.md`](venues.md) | Real-site evidence, mapping decisions and deliberate simplifications | Runtime venues' evidence companion to §5 |
-| [`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, optional Blender MCP and pipeline usage | Operational appendix to the pipeline section |
-| [`docs/blender-assets.md`](blender-assets.md) | Blender library art direction, roles, layout and checks | Operational asset appendix; contract lives here in §5 |
-| [`docs/3d-model-review.md`](3d-model-review.md) | Character and asset measurements, scorecard and ranked gaps | Visual-QA appendix to the character tooling section |
-| [`docs/3d-model-review.md`](3d-model-review.md) | Scorecard, measurements and ranked asset gaps | Working review companion to §5 |
-| [`docs/npc-model-sourcing.md`](npc-model-sourcing.md) | Character-source evaluation and licence/prototype outcome | Supports the character tooling section and ADR-0015 |
-| [`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/release-qa.md`](release-qa.md) | Manual smoke checklist and balance protocol | QA appendix to §10 |
-| [`docs/accessibility.md`](accessibility.md) | Accessibility features, statement and known gaps | Player-facing quality statement |
-| [`docs/known-limitations.md`](known-limitations.md) | Release blockers and accepted limitations | Player/release-facing risk statement |
-| [`docs/ui-copy.md`](ui-copy.md) | Screen/button inventory, copy audit and screen-judge report | Presentation appendix |
-| [`docs/development-status.md`](development-status.md) | Implemented features and current gaps | Status companion to the roadmap |
-| [`TODO.md`](../TODO.md) | Priority-ordered active tasks, unversioned development tracks and versioned roadmap | Planning source; no architecture duplication |
-| [`CHANGELOG.md`](../CHANGELOG.md) | User-facing release history | Release/version companion |
+| [`PLAN.md`](../../PLAN.md) | Product/design intent, pillars, venues and success criteria | Design source; architecture realizes it |
+| [`docs/design/gameplay.md`](../design/gameplay.md) | Playable loop, escalation, tutorial, venue mechanics | Runtime/behavioral view |
+| [`docs/design/venues.md`](../design/venues.md) | Real-site evidence, mapping decisions and deliberate simplifications | Runtime venues' evidence companion to §5 |
+| [`docs/project/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/assets/asset-tooling.md`](../assets/asset-tooling.md) | Build/audit/capture commands, optional Blender MCP and pipeline usage | Operational appendix to the pipeline section |
+| [`docs/assets/blender-assets.md`](../assets/blender-assets.md) | Blender library art direction, roles, layout and checks | Operational asset appendix; contract lives here in §5 |
+| [`docs/assets/3d-model-review.md`](../assets/3d-model-review.md) | Character and asset measurements, scorecard and ranked gaps | Visual-QA appendix to the character tooling section |
+| [`docs/assets/3d-model-review.md`](../assets/3d-model-review.md) | Scorecard, measurements and ranked asset gaps | Working review companion to §5 |
+| [`docs/assets/npc-model-sourcing.md`](../assets/npc-model-sourcing.md) | Character-source evaluation and licence/prototype outcome | Supports the character tooling section and ADR-0015 |
+| [`docs/process/getting-started.md`](../process/getting-started.md) | Setup, commands, controls | Developer onboarding |
+| [`docs/process/RELEASING.md`](../process/RELEASING.md) | Release checklist and CI/publishing steps | Deployment appendix to §7 |
+| [`docs/process/release-qa.md`](../process/release-qa.md) | Manual smoke checklist and balance protocol | QA appendix to §10 |
+| [`docs/design/accessibility.md`](../design/accessibility.md) | Accessibility features, statement and known gaps | Player-facing quality statement |
+| [`docs/design/known-limitations.md`](../design/known-limitations.md) | Release blockers and accepted limitations | Player/release-facing risk statement |
+| [`docs/design/ui-copy.md`](../design/ui-copy.md) | Screen/button inventory, copy audit and screen-judge report | Presentation appendix |
+| [`docs/project/development-status.md`](development-status.md) | Implemented features and current gaps | Status companion to the roadmap |
+| [`TODO.md`](../../TODO.md) | Priority-ordered active tasks, unversioned development tracks and versioned roadmap | Planning source; no architecture duplication |
+| [`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.
- **Completed plans are removed, not kept as competing roadmaps.** Historical graphics work is summarized by ADR-0013, the asset pipeline section and the v0.6.0 changelog; new work belongs in TODO.
-- **Status and roadmap are separate from architecture.** `docs/development-status.md` records what exists; `TODO.md` records what remains, ordered as unversioned development tracks, versioned milestones and deferred work.
+- **Status and roadmap are separate from architecture.** `docs/project/development-status.md` records what exists; `TODO.md` records what remains, ordered as unversioned development tracks, versioned milestones and deferred work.
- **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
diff --git a/docs/development-status.md b/docs/project/development-status.md
similarity index 88%
rename from docs/development-status.md
rename to docs/project/development-status.md
index 56c0a16..4aab66e 100644
--- a/docs/development-status.md
+++ b/docs/project/development-status.md
@@ -1,9 +1,9 @@
# Development Status
-Baseline: **v0.9.8** (2026-11-04). This page lists what the build currently
+Baseline: **v0.9.9** (2026-11-06). This page lists what the build currently
supports and what remains; it is not a release history. Completed work lives in
-[`DONE.md`](../DONE.md), user-facing changes in [`CHANGELOG.md`](../CHANGELOG.md),
-and the active order/gaps in [`TODO.md`](../TODO.md).
+[`DONE.md`](../../DONE.md), user-facing changes in [`CHANGELOG.md`](../../CHANGELOG.md),
+and the active order/gaps in [`TODO.md`](../../TODO.md).
## Implemented
@@ -16,7 +16,7 @@ and the active order/gaps in [`TODO.md`](../TODO.md).
| Access and escalation | Six escalation levels, venue access policies, artifact validity/recognition, door lock, crowd reactions, investigation/false-report handling and shift review. |
| UI/input | Keyboard/mouse and gamepad bindings, focus rings, default modal focus, single top-modal close path, shared button states, font scaling, long-string handling, searchable Help and 21 committed UI/game captures. |
| Audio/accessibility | Procedural crowd bed and radio cues, master/SFX/ambience volumes, reduced motion, captions, colour-independent escalation cue, hold-to-confirm emergency and guarded destructive actions. |
-| Persistence | Separate settings, campaign, shift-history and versioned checkpoint files; default-filling migration, atomic writes and corrupt/partial-file fallback. Save locations and rollback are documented in [`getting-started.md`](getting-started.md#save-data-and-migration). |
+| Persistence | Separate settings, campaign, shift-history and versioned checkpoint files; default-filling migration, atomic writes and corrupt/partial-file fallback. Save locations and rollback are documented in [`getting-started.md`](../process/getting-started.md#save-data). |
| Assets | Blender character/gear/prop library with AO and manifests; 256² NPC maps with 4× fabric weave; image/texture pipelines, reference boards and three-up boards; environment/realism capture tools. |
| Build/release | Godot 4.7.2 Compatibility/Web default plus optional Forward+ Desktop HQ. Gitea checks/build/publish, seven release assets, checksums, preflight/rollback and clean-worktree release discipline. |
@@ -41,7 +41,7 @@ and the active order/gaps in [`TODO.md`](../TODO.md).
library and the MakeHuman head remain the tested fallback.
- The roster passed its owner visual review on 2026-11-06: faces, head gear, hand-held and back
gear were all accepted after the follow-up fixes. The review page and its sheets were retired;
- the measurements live in `docs/3d-model-review.md` and `docs/blender-assets.md`.
+ the measurements live in `docs/assets/3d-model-review.md` and `docs/assets/blender-assets.md`.
- Roster silhouette variety is narrower than the procedural library (three meshes for twelve
roles, differentiated by tint and gear) until the modular part library is added.
- Head gear is authored for the shipped Quaternius head; the procedural fallback therefore wears
@@ -51,6 +51,6 @@ and the active order/gaps in [`TODO.md`](../TODO.md).
- Live 3D replay, recorded VO/music, more venues and seasonal content are future
work.
-See [`TODO.md`](../TODO.md) for the ordered task list and
-[`known-limitations.md`](known-limitations.md) for the current release blockers.
+See [`TODO.md`](../../TODO.md) for the ordered task list and
+[`known-limitations.md`](../design/known-limitations.md) for the current release blockers.
Architecture and ownership are in [`architecture.md`](architecture.md).
diff --git a/docs/screens/concepts/README.md b/docs/screens/concepts/README.md
index 354a3c1..64408eb 100644
--- a/docs/screens/concepts/README.md
+++ b/docs/screens/concepts/README.md
@@ -15,13 +15,13 @@ The map-optimization references for the El Capitan Entertainment Centre block
(6840 Hollywood Blvd) are in
[`hollywood_boulevard/README.md`](hollywood_boulevard/README.md). The real-site
facts and game mapping are documented in
-[`../../venues.md`](../../venues.md#hollywood-boulevard).
+[`../../venues.md`](../../design/venues.md#hollywood-boulevard).
## The Joke Shop — Sunset Strip
The current Joke Shop map is based on The Comedy Store at 8433 Sunset Blvd.
The real-site mapping and simplifications are in
-[`../../venues.md`](../../venues.md#the-joke-shop); the frames are in
+[`../../venues.md`](../../design/venues.md#the-joke-shop); the frames are in
[`joke_shop/README.md`](joke_shop/README.md).
diff --git a/docs/screens/concepts/hollywood_boulevard/README.md b/docs/screens/concepts/hollywood_boulevard/README.md
index 19ae5f3..fdb2782 100644
--- a/docs/screens/concepts/hollywood_boulevard/README.md
+++ b/docs/screens/concepts/hollywood_boulevard/README.md
@@ -4,7 +4,7 @@ AI-generated art-direction frames for the real El Capitan Entertainment Centre
block at 6840 Hollywood Boulevard. They are generated with
`tools/scene_concepts.py generate --group scene --only ...` and are not shipped
game textures. The geometry mapping and source links are in
-[`../../../venues.md`](../../../venues.md#hollywood-boulevard).
+[`../../../venues.md`](../../../design/venues.md#hollywood-boulevard).
## Entrance — day
diff --git a/docs/screens/concepts/joke_shop/README.md b/docs/screens/concepts/joke_shop/README.md
index 3ef007e..e8632da 100644
--- a/docs/screens/concepts/joke_shop/README.md
+++ b/docs/screens/concepts/joke_shop/README.md
@@ -4,7 +4,7 @@ AI-generated art-direction frames for the fictional Joke Shop, based on the
real Comedy Store block at 8433 Sunset Boulevard. They are generated with
`tools/scene_concepts.py generate --group scene --only ...` and are not shipped
game textures. The geometry mapping and source links are in
-[`../../../venues.md`](../../../venues.md#the-joke-shop).
+[`../../../venues.md`](../../../design/venues.md#the-joke-shop).
## Entrance — day, photo-anchored
diff --git a/docs/screens/head-review/README.md b/docs/screens/head-review/README.md
deleted file mode 100644
index bb19ce3..0000000
--- a/docs/screens/head-review/README.md
+++ /dev/null
@@ -1,68 +0,0 @@
-# Head rework — review page (2026-11-04)
-
-> **Historical page / changed source (2026-11-04).** The numbers below describe the
-> earlier decimated MakeHuman head (1,548-tri skin). The shared source
-> `assets/models/blender_src/makehuman_head.glb` now holds the higher-resolution
-> standalone prototype. The owner accepted the basic head; the automated vision gate
-> still records REJECT on the eye/lid region as deferred polish. See
-> [`../../makehuman-head-review.md`](../../makehuman-head-review.md). Re-run the
-> library head build before relying on the comparison counts below.
-
-This page is the review checkpoint for the NPC head rework. The goal was to replace the
-sphere-and-floating-primitive face with a head that has real nose / chin / jaw landmarks at
-portrait distance.
-
-## What changed
-
-The original procedural face is a head sphere plus separate nose, mouth, ear and eye primitives.
-The new head uses the **decimated MakeHuman head** (CC0, 1,573 tris) as the base shape and keeps
-the project's separate eyeballs, brow and mouth pieces on top. An AI judge was used to drive the
-decision: it scored the procedural rework at ~3/5 and then picked the MakeHuman head as the
-clearer silhouette.
-
-| | Source | Tris (head) | Read |
-| --- | --- | --- | --- |
-| **Before** | procedural `_face` (sphere + primitives) | ~1,900 | flat face, slit eyes |
-| **After** | overhauled MakeHuman head + project eyes/brows/mouth | ~1,880 | smooth nose/chin/jaw landmarks |
-
-The head source was overhauled 2026-11-04: the blocky decimated MakeHuman head was welded
-(merge-by-distance) and Laplacian-relaxed into one clean manifold shell (`makehuman_head.glb`,
-1,548 tris skin), then the project eyes/brows/mouth were added.
-
-## AI-generated target concept
-
-The rework was guided by two generated concept frames (front + profile, `bytedance-seed/seedream-4.5`).
-
-
-
-## 1.85 m comparison (top = current, bottom = new)
-
-Left to right: front, three-quarter, profile.
-
-
-
-## New head at 1.5 m (portrait)
-
-
-
-## Contract and checks
-
-- `blender_assets.py inspect` on the assembled `npc_casual` with the new head: **14 bones,
- skinned, no issues**.
-- Source: `assets/models/blender_src/makehuman_head.glb` (CC0, attributed in `CREDITS.md`).
-- Python 167/167, Godot 277/277, `check_docs` OK.
-
-## Remaining polish (known, not blockers)
-
-1. The hair cap still reads as a stepped block instead of hugging the skull.
-2. The brows weld to the face but can read as a slightly separate bar.
-3. The neck underside cap is plain; it is hidden by the body neck in the assembled character.
-4. The head skin is 1.5k tris (smooth but low-poly); a retopology pass could add resolution if a
- portrait shows faceting.
-
-## Decision (2026-11-04, owner)
-
-The MakeHuman-head direction is approved for the basic human head. The remaining review is the
-assembled prototype's hair cap and full-body silhouette. After that, roll the head into the other
-11 variants (one asset family at a time) with a before/after sheet per batch, then re-run the
-24-NPC budget + AO bake.
diff --git a/docs/screens/head-review/sheet_compare_1.85.jpg b/docs/screens/head-review/sheet_compare_1.85.jpg
deleted file mode 100644
index 04fbf6b..0000000
Binary files a/docs/screens/head-review/sheet_compare_1.85.jpg and /dev/null differ
diff --git a/docs/screens/head-review/sheet_concept.jpg b/docs/screens/head-review/sheet_concept.jpg
deleted file mode 100644
index 112d31f..0000000
Binary files a/docs/screens/head-review/sheet_concept.jpg and /dev/null differ
diff --git a/docs/screens/head-review/sheet_head_1.5.jpg b/docs/screens/head-review/sheet_head_1.5.jpg
deleted file mode 100644
index 5d92e28..0000000
Binary files a/docs/screens/head-review/sheet_head_1.5.jpg and /dev/null differ
diff --git a/docs/screens/refs/README.md b/docs/screens/refs/README.md
index b204486..61f05c1 100644
--- a/docs/screens/refs/README.md
+++ b/docs/screens/refs/README.md
@@ -76,8 +76,8 @@ 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/venues.md#hollywood-boulevard`,
- `docs/venues.md#the-joke-shop`) and from the local-map block notes.
+- Link the board from the venue map document (`docs/design/venues.md#hollywood-boulevard`,
+ `docs/design/venues.md#the-joke-shop`) 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.
diff --git a/docs/screens/refs/SIDECAR-TEMPLATE.md b/docs/screens/refs/SIDECAR-TEMPLATE.md
index 09ff2a4..16a55c4 100644
--- a/docs/screens/refs/SIDECAR-TEMPLATE.md
+++ b/docs/screens/refs/SIDECAR-TEMPLATE.md
@@ -34,12 +34,12 @@ attribution string for CC BY / CC BY-SA in the `Author` or a note below.
| Decision | Evidence | Where it landed |
| --- | --- | --- |
-| e.g. six-column spacing kept at 2.4 m | photo 1, measured against door width | `docs/venues.md#hollywood-boulevard` |
+| e.g. six-column spacing kept at 2.4 m | photo 1, measured against door width | `docs/design/venues.md#hollywood-boulevard` |
| 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
+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 |
diff --git a/docs/screens/refs/hollywood/README.md b/docs/screens/refs/hollywood/README.md
index 3f0c3c3..18c450c 100644
--- a/docs/screens/refs/hollywood/README.md
+++ b/docs/screens/refs/hollywood/README.md
@@ -11,7 +11,7 @@ TV Studio board.
Provenance, licences and the decisions these photos informed are in
[`SIDECAR.md`](SIDECAR.md). The rules for this folder are in
-[`../README.md`](../README.md); generated art-direction frames live in
+[`../README.md`](README.md); generated art-direction frames live in
[`../../concepts/hollywood_boulevard/`](../../concepts/hollywood_boulevard/README.md).
| Photo | What it is evidence for |
@@ -35,5 +35,5 @@ Provenance, licences and the decisions these photos informed are in
- The east retail neighbour beyond the temple (the modern retail block), for facade rhythm at the
right-hand edge of the venue.
-Add new files with the naming convention in [`../README.md`](../README.md) and list them in the
+Add new files with the naming convention in [`../README.md`](README.md) and list them in the
sidecar in the same commit.
diff --git a/docs/screens/refs/hollywood/SIDECAR.md b/docs/screens/refs/hollywood/SIDECAR.md
index 4d88175..f05ab2a 100644
--- a/docs/screens/refs/hollywood/SIDECAR.md
+++ b/docs/screens/refs/hollywood/SIDECAR.md
@@ -26,7 +26,7 @@
Licence texts: [CC BY 2.0](https://creativecommons.org/licenses/by/2.0/),
[CC BY 3.0](https://creativecommons.org/licenses/by/3.0/) and
[CC BY-SA 3.0](https://creativecommons.org/licenses/by-sa/3.0/). The CC BY and CC BY-SA files are
-also listed in [`../../../CREDITS.md`](../../../CREDITS.md) under "Development-only reference
+also listed in [`../../../../CREDITS.md`](../../../../CREDITS.md) under "Development-only reference
images".
**CC BY-SA review (2026-11-03):** `hollywood-boulevard-night-context-ccbysa.jpg` is redistributed
@@ -51,10 +51,10 @@ before use.
| Decision | Evidence | Where it landed |
| --- | --- | --- |
-| Six Ionic columns, ~2.4 m spacing, 8 steps | facade photo measured against the door width | `docs/venues.md#hollywood-boulevard` geometry notes |
+| Six Ionic columns, ~2.4 m spacing, 8 steps | facade photo measured against the door width | `docs/design/venues.md#hollywood-boulevard` geometry notes |
| Masonic parapet motto and medallions | 1922 elevation + facade photo | `WorldBuilder` facade, `docs/screenshots/01-venue-overview.png` |
| Three vertical event banners | facade photo | facade banners and the day/night capture set |
-| Red carpet + barrier staging narrows the sidewalk | premiere photo | `docs/venues.md#hollywood-boulevard` event staging notes |
+| Red carpet + barrier staging narrows the sidewalk | premiere photo | `docs/design/venues.md#hollywood-boulevard` event staging notes |
| Across-street height and plaza opening | Ovation photo | opposite frontage massing |
| TV Studio arrival staging (bulb canopy, car, barriers) | premiere staging photo | `VENUE_SPECS["tv_studio"]` and the Late Night TV Studio venue docs |
| Terrazzo band width, star size/spacing | terrazzo + star close-up photos | `WalkOfFame` band geometry and the paver material |
diff --git a/docs/screenshots/README.md b/docs/screenshots/README.md
index 7c4bd28..0ae0843 100644
--- a/docs/screenshots/README.md
+++ b/docs/screenshots/README.md
@@ -29,6 +29,6 @@ README, the gameplay docs and the screenshot gate; do not edit them by hand.
| 21 | [Responder arrival](21-responder-arrival.png) | A responder at the locked door |
The captures are 1280×720 PNGs. Reference designs and the judge report live in
-[`../screens/`](../screens/README.md) and [`../ui-copy.md#screen-design-judge-report`](../ui-copy.md#screen-design-judge-report);
+[`../screens/`](../screens/README.md) and [`../ui-copy.md#screen-design-judge-report`](../design/ui-copy.md#screen-design-judge-report);
the re-evaluation's pose and review sheets are under
[`../blender_previews/`](../blender_previews/README.md).
diff --git a/src/test/capture_npc_pose.gd b/src/test/capture_npc_pose.gd
index fba8420..2c2084b 100644
--- a/src/test/capture_npc_pose.gd
+++ b/src/test/capture_npc_pose.gd
@@ -23,7 +23,7 @@ extends SceneTree
## same `_animate()` sequence *does* render the crouch, and writing a single
## bone rotation directly does deform the mesh, so this is a staging/capture
## discrepancy, not a rig failure. Do not use these sheets as pose evidence.
-## Repro and what was ruled out: `docs/3d-model-review.md` section
+## Repro and what was ruled out: `docs/assets/3d-model-review.md` section
## "Pose evidence is blocked".
##
## Usage (windowed; `xvfb-run -a` works for automation):
diff --git a/tools/README.md b/tools/README.md
index 6f756e1..dd0940b 100644
--- a/tools/README.md
+++ b/tools/README.md
@@ -160,7 +160,7 @@ dependencies or replace the tools above.
network/budget-dependent review aids, not deterministic CI gates.
- `openrouter_judge.py` is an implementation detail imported by other tools.
- `check_docs.py` and `export_venues.gd` are short, single-purpose commands;
- documenting them in this README and `docs/asset-tooling.md` is enough.
+ documenting them in this README and `docs/assets/asset-tooling.md` is enough.
- `npc_baseline.py`, `npc_proportions.py` and `three_up.py` are better included
as references/steps inside the proposed asset or release skill than exposed as
separate skills; fragmenting them would increase routing mistakes.
diff --git a/tools/blender_assets.py b/tools/blender_assets.py
index 51fe688..f014650 100644
--- a/tools/blender_assets.py
+++ b/tools/blender_assets.py
@@ -4,7 +4,7 @@
Everything here is modelled procedurally inside Blender (flatpak, headless) so
the assets are reproducible from source. Outputs are staged for *later*
integration: nothing in the game loads them yet (see
-`docs/blender-assets.md` for the integration contract).
+`docs/assets/blender-assets.md` for the integration contract).
# build every asset (or --only name,name) -> assets/models/blender/**.glb
flatpak run org.blender.Blender --background \
@@ -1489,7 +1489,7 @@ def build_character(name, head="face"):
# is 4 skinned meshes on the same 62-joint armature; the build joins them
# **without welding** (a weld corrupts the skin weights), renames the upstream
# materials onto the five tint slots, unwraps the degenerate source UVs and bakes
-# the arm-down rest. See docs/npc-model-sourcing.md for the measurements.
+# the arm-down rest. See docs/assets/npc-model-sourcing.md for the measurements.
QUATERNIUS_SRC = SRC_DIR / "quaternius"
@@ -1497,7 +1497,7 @@ QUATERNIUS_SRC = SRC_DIR / "quaternius"
# (face, hair detail and hivis fabrics); anything not listed is kept too, so a
# new upstream material shows up as an extra fixed-colour slot instead of
# silently disappearing. The maps were derived from the per-material height bands
-# measured in docs/npc-model-sourcing.md.
+# measured in docs/assets/npc-model-sourcing.md.
QUATERNIUS_SOURCES = {
"casual": {
"file": "Casual.glb",
@@ -2605,7 +2605,7 @@ def build_gear(name):
# procedural library's 0.315 m, and its centre sits 0.07 m higher, so the
# head gear is scaled and lifted to match. The procedural fallback then
# wears slightly small hats — cosmetic, and recorded in
- # docs/blender-assets.md.
+ # docs/assets/blender-assets.md.
centre = Vector((0.0, 0.0, HEAD_GEAR_LIFT))
obj.data.transform(
Matrix.Translation(centre)
diff --git a/tools/build_releases.sh b/tools/build_releases.sh
index 52c6d34..ce8014c 100755
--- a/tools/build_releases.sh
+++ b/tools/build_releases.sh
@@ -3,7 +3,7 @@
#
# Requirements:
# - Godot 4.7.2 (or the version in project.godot `config/features`) on PATH,
-# with export templates installed (see docs/RELEASING.md).
+# with export templates installed (see docs/process/RELEASING.md).
# - Run from the repository root.
#
# Produces:
@@ -20,8 +20,8 @@ VERSION="$(grep -oP 'config/version="\K[^"]+' project.godot)"
PLAYER_DOCS=(
"CREDITS.md"
"PRIVACY.md"
- "docs/accessibility.md"
- "docs/known-limitations.md"
+ "docs/design/accessibility.md"
+ "docs/design/known-limitations.md"
)
mkdir -p build
# Presets now embed the PCK into a single binary; drop stale .pck leftovers.
@@ -95,4 +95,4 @@ shasum -a 256 build/*"${VERSION}"* > "build/SHA256SUMS-${VERSION}.txt"
cat "build/SHA256SUMS-${VERSION}.txt"
echo ""
echo "Upload to: https://git.allucanget.biz/zwitschi/security-game/releases"
-echo "See docs/RELEASING.md for the full release checklist."
+echo "See docs/process/RELEASING.md for the full release checklist."
diff --git a/tools/npc_pipeline.py b/tools/npc_pipeline.py
index 4776bdb..288ad2a 100644
--- a/tools/npc_pipeline.py
+++ b/tools/npc_pipeline.py
@@ -16,7 +16,7 @@ path must be absolute):
python3 tools/npc_pipeline.py palette # derive outfit colours -> palette.json
python3 tools/npc_pipeline.py audit
-Contract (frozen in ADR-0013 and docs/blender-assets.md):
+Contract (frozen in ADR-0013 and docs/assets/blender-assets.md):
* scene root "Rig" with a skinned mesh and an armature
* bones: Head, HipL/R, KneeL/R, ShoulderL/R, ElbowL/R, HandL/R
diff --git a/tools/tests/test_model_review.py b/tools/tests/test_model_review.py
index c426f49..fe0f5f5 100644
--- a/tools/tests/test_model_review.py
+++ b/tools/tests/test_model_review.py
@@ -1,7 +1,7 @@
"""Keep the 3D model review scorecard honest.
Every catalogue asset (characters, gear, props) must have a row in
-`docs/3d-model-review.md`, and the character rows must carry a verdict. This does
+`docs/assets/3d-model-review.md`, and the character rows must carry a verdict. This does
not judge the art; it only fails when an asset is added or renamed without being
reviewed, which is how a scorecard silently rots.
"""
@@ -13,7 +13,7 @@ from pathlib import Path
import blender_assets as model
ROOT = Path(model.__file__).resolve().parent.parent
-REVIEW = ROOT / "docs" / "3d-model-review.md"
+REVIEW = ROOT / "docs" / "assets" / "3d-model-review.md"
def catalogue_names() -> set[str]: