Documentation Structure Review¶

Document Type: Project Management Version: 0.1 Last Updated: 2026-08-30 Vault destination: 04_Project Management

Purpose¶

A structural audit of docs/ — what is genuinely broken, what only looks broken, and what a restructure should and should not touch.

This document is a plan, not a change. Nothing here has been done except the two deletions marked as such.

1. The fact that changes the cost of everything¶

mkdocs-roamlinks-plugin resolves [[Wikilink]] by searching the whole docs/ tree for a matching filename, not by path.

Operation	Breaks wikilinks?
Moving a file between folders	No
Renaming a file	Yes, every link to it

That is the reverse of the usual assumption, and it decides the whole approach:

Reorganising into subfolders is cheap. Renumbering is expensive.

⚠️ Verify this before relying on it. Move one low-traffic document, run mkdocs build, and confirm no new warnings appear. The claim is worth ten minutes of proof before it is worth acting on.

Two caveats that survive either way:

Relative markdown links — [text](../path.md) — do break on a move. The vault uses wikilinks almost throughout, but not entirely.
The mkdocs.yml nav names every file by full path and must be updated.

2. Delete — dead compatibility stubs¶

Both point at an absolute path that exists on no machine: C:/Users/zeler/auto-warz/auto-warz/docs/... — the folder is doubled and Projects/ is missing.

File	Was
`docs/AutoWarz.md`	A stub pointing at `01_Master GDD`
`docs/Auto Warz - Scope & MVP Document.md`	A stub pointing at `02_Scope & MVP Document`

Both say "use this only for legacy references". Nothing references them; they were left behind by a move that happened before the repo was at its current path.

git rm docs/AutoWarz.md
git rm "docs/Auto Warz - Scope & MVP Document.md"

3. The three roadmaps — RESOLVED, merged 2026-08-30¶

There were three roadmap files at three granularities, all maintained by hand, and all three had drifted identically. They are now one file: 04_Project Management/ROADMAP.md.

Was	Held	Fate
`04_Project Management/01_Development Roadmap.md`	The plan and the record — 7 phases, 34 milestones, deliverables, estimates, timeline comparison	Became the merged file
`docs/ROADMAP.md`	A worklist. Next plus Backlog. Read by BADE	Absorbed, deleted
`docs/ROADMAP-COMPLETED.md`	One line per completed milestone, newest first. BADE ignored it	Absorbed as Recently completed, deleted

3a. The BADE contract is now structural rather than incidental¶

BADE locates the file by filename, not by path, so it can live in 04_Project Management. But it reads the first unchecked checkbox in the file.

That contract was safe in a 30-line worklist where every checkbox was a next action. In a 450-line merged document with checklists throughout M2.4 to M2.7, it would have been fragile: anyone adding a checkbox anywhere above the intended one silently changes what BADE reports, and nothing fails visibly.

So the merged file puts ## Next first, with exactly one shippable action at the top of it, and every milestone checklist far below under ## The plan. First unchecked box and the next action are now the same thing by construction.

⚠️ The filename must never take a numeric prefix. 01_ROADMAP.md would not be found. This is the one place in the vault where a filename is an interface, and it is a deliberate exception to the prefix convention rather than an oversight. The warning is written into the file itself, not only into a commit message, because that is where the next tidy-up will be looking.

A parser trap worth knowing about. The guard comment in that file deliberately does not spell out the checkbox syntax. Writing the literal example inside the comment means a parser doing a plain string search matches the comment instead of the real action below it — the safety note would have broken the thing it documents.

3b. The staleness this fixed¶

All three files stopped at M2.3, 2026-03-13, leaving five months unrecorded — OI-036. The merged file backfills that from git history and AGENTS.md, and adds a Where we actually are section, because the milestone numbering read as linear progress when it is not: M2.4 to M2.6 were skipped rather than pending, M2.7 was built out of order and never marked, and Outpost Mode sits outside the sequence entirely.

Two stale entries were corrected in the same pass:

OI-298 — the Drone Port appeared in both roadmaps, and BADE was reporting "Implement the Drone Port building" as the next action for a building removed from the design. M2.4 is rewritten against [21_Drone Logistics Design](<../01_Design Documents/Logistics/21_Drone Logistics Design.md>).
OI-314 — M3.4 was named Advanced Diagnostics & Factory Overview; the Factory Overview was removed in [09_UI-UX Design Document](<../01_Design Documents/Interface/09_UI-UX Design Document.md>) v0.6. Rescoped, not deleted — the diagnostics half survives.

4. `01_Design Documents` — 32 files, no grouping¶

The largest structural problem, and the one with an obvious answer.

The nav already knows the right structure. mkdocs.yml groups these files into Design, Systems, Logistics and Interface. The folder has simply never caught up with the organisation the nav has been asserting for a week.

Proposed subfolders, taken directly from the nav groupings rather than invented:

Subfolder	Contents
(root)	`01_Master GDD`, `02_Scope & MVP`
`Systems/`	Factory, Vertical Layers, Pipes, Ports, Modules, Power, Pollution, Farming
`Logistics/`	Transport, Router, Drones, Trains
`Interface/`	UI-UX, Tutorial, HUD Layout, HUD Panel Flap, Notifications
`Content/`	World Gen, Research Tree, Achievements, Gauntlet, Levelling, Win Conditions, Ships, Restoration
`Unwritten/`	The six OI-313 placeholders

Moving the placeholders into their own subfolder solves the numbering collision (§5) without renaming anything, which is the cheap fix rather than the correct-looking one.

4a. One file is in the wrong folder entirely¶

05_Reference/08_AI Toolchain.md is a tooling reference, not a design document — art tools, audio tools, licensing checklist. It belongs in 05_Reference or 02_Technical Documents.

It is also the document OI-327 says needs rewriting, so the move and the rewrite should happen together.

5. Numeric prefixes — the real question¶

5a. The collisions — RESOLVED 2026-08-30, without renaming anything¶

Four prefix collisions were created by the OI-313 placeholders, which had to take the names the existing links already used. All four are resolved, and the fix cost nothing: the subfoldering in §4 put each pair in a different folder, so the duplicate prefixes stopped being duplicates.

Prefix	Was colliding	Now
`05_`	World Generation · Spaceship Design	`Content/` · `Unwritten/`
`06_`	Vertical Layers · Combat & War	`Systems/` · `Unwritten/`
`07_`	Pipe & Fluid · Space Exploration	`Systems/` · `Unwritten/`
`08_`	Research Tree · Economy & Progression	`Content/` · `Unwritten/`

⚠️ Unwritten/ is therefore load-bearing. It looks like a tidy-up folder and is not: flattening it brings all four collisions straight back. The warning is written into 01_Design Documents/Unwritten/README.md, where whoever considers flattening it will actually be looking.

One rename was made, deliberately, and it is not a precedent. 03_AI Toolchain moved to 05_Reference/ as 08_AI Toolchain. Unlike the four above, that move would have created a collision — 05_Reference already has a 03_ — in a folder where every other file has a unique key. §5c protects against renumbering to close gaps and against renaming settled documents; this was neither. It was cheap because the file had three inbound links, --strict was already on to catch a miss, and OI-327 rewrites the document anyway, so its header was changing regardless.

Gaps, left by deletions and consolidations. Per §5c these stay open:

Folder	Missing
`03_Art & Audio`	`04_` — the second Blender doc, consolidated away
`04_Project Management`	`04_` — the AI Tool Selection Guide, deleted 2026-08-30
`06_Outpost`	`06_`, `08_`

5b. What the prefixes actually buy¶

For	Against
Ordering in Obsidian's file tree	MkDocs orders from the nav, so they do nothing on the site
A stable sort in `git status` and directory listings	Every insert or delete forces a renumber or leaves a gap
	They are the reason the placeholders collide
	They make URLs longer and uglier

5c. The recommendation: keep them, stop treating them as a sequence¶

Removing prefixes would break every wikilink in the vault, because links use the prefixed name ([24_Module System Design](<../01_Design Documents/Systems/24_Module System Design.md>)). That is a very large edit for a cosmetic gain.

So: keep the prefixes as ordering hints, and accept that they are neither contiguous nor unique. Gaps are fine — they record that something was deleted. Collisions are resolved by the Unwritten/ subfolder in §4, which separates the placeholders without touching a single filename.

The rule worth writing down: a prefix orders a file within its folder. It is not an identifier, it is not a sequence, and nothing should be renumbered to close a gap.

6. Smaller items¶

Item	Finding	Action
`05_Reference/` vs "World Bible" nav label	The folder says Reference, the nav says World Bible	Cosmetic. Renaming the folder is safe for wikilinks (§1) but changes every URL. Low priority.
`07_Prompts/`	~~Three Copilot prompts from the HUD work~~	Deleted 2026-08-30. The scenes and scripts are the artefact; the prompt was the scaffolding, and a build instruction that has been followed has no remaining consumer. The finding that settled it: `exclude_docs` kept the folder out of the build, so the Phase C moves broke two paths inside it with no warning at all — content guaranteed to rot in the one part of `docs/` the checker does not reach. The test applied was: if they were worth keeping, they would have to come out of `exclude_docs` so `--strict` covered them; anything not worth that is not worth keeping. Raised OI-329 on the way out — the shipped `GenesisQueue.gd` colours diverge from the palette, and the deleted prompt was more compliant than the code it produced.
`06_Outpost/`	Documents 06 and 08 missing; 07 is now a placeholder	Check whether 06 and 08 were planned like 07 was, or whether the numbering simply skipped
`docs/data/`	New. Holds `power-tuning.json` (authored) and `buildings.json` (generated, gitignored)	Correct as-is. Worth a README when a second system moves to JSON.

7. Sequence¶

Order matters here, and the first step is what makes the rest safe.

✅ All eight steps completed 2026-08-30. Recorded below as what happened.

Close OI-313 — done, via the six placeholders
Switch the docs workflow to --strict (OI-326) — done. Its first strict run failed on nine unresolved links, not just the placeholders: three literal [[...]] written as examples in prose (which roamlinks resolves anyway, because it does not respect code spans) and six genuinely broken. The gate found all of them on its first run, which is the argument for having it
Verify the move-vs-rename claim in §1 with one test file — done, and it holds. 12_Gauntlet Planet Design moved into Content/ with both inbound wikilinks left untouched; strict build exits 0 and the rendered hrefs resolve to the new path. Moving is free, renaming is expensive, and §4 is cheap as a result
Delete the two dead stubs (§2)
~~Move the ROADMAP pair into 04_Project Management~~ — done differently, 2026-08-30. All three roadmaps were merged into one 04_Project Management/ROADMAP.md rather than the pair being relocated alongside a third file. See section 3.
Subfolder 01_Design Documents (§4) — done. 32 files became 3 at root plus five groups, in five batches with a strict build and a commit after each, so any failure had a clean state to return to
Move 03_AI Toolchain out — done, as 05_Reference/08_AI Toolchain. The OI-327 rewrite is still outstanding and remains its own job
Update mkdocs.yml nav paths throughout — done, and all 64 nav entries were audited against disk rather than trusting the build alone

Step 2 is the one not to skip. Restructuring with the link checker disabled is how a broken reference reaches the published site unnoticed. Every conflict found in this vault so far was found by a tool, not by reading.

8. Revision History¶

Version	Date	Changes
0.1	2026-08-30	Created. Structural audit of `docs/`. Identified two dead stubs, the BADE integration that must not move, the 32-file design folder, and the prefix collisions created by the OI-313 placeholders.
0.2	2026-08-30	The restructure this document proposed was carried out. §5a, §6 and §7 rewritten as what happened rather than what to do: four prefix collisions resolved by subfoldering with no filename touched, `07_Prompts` deleted, and all eight sequence steps completed. §3 was rewritten earlier the same day when the three roadmaps were merged. Records the one deliberate rename, `03_AI Toolchain` to `05_Reference/08_AI Toolchain`, as an exception with a stated reason rather than a precedent.