Reorganize docs into category folders and drop the retired head-review page
Full build / Import + headless tests (push) Successful in 41s
Full build / Full desktop build + optional release (push) Skipped

Group the top-level docs into docs/project, docs/design, docs/assets and
docs/process, each with its own README index. Delete the superseded
docs/screens/head-review page and sheets. Rewrite every markdown link,
absolute docs path and tool/test reference to the new locations, fix the
pre-existing broken anchors and remove the dead Joke Shop photo-board link.
check_docs OK, Python tooling 167/167.
This commit is contained in:
zwitschi committed 2026-11-06 20:13:03 +01:00
1 parent 045ed2a58f
commit 2ba40f3578
57 files changed
+406 -414

No files matched your search

+16 -16
View File
@@ -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