Reorganize docs into category folders and drop the retired head-review page
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:
1 parent
045ed2a58f
commit
2ba40f3578
57 files changed
+406
-414
No files matched your search
@@ -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
|
||||
|
||||
Reference in new issue
Block a user