diff --git a/DEVLOG.md b/DEVLOG.md index b33f9b12..7581443c 100644 --- a/DEVLOG.md +++ b/DEVLOG.md @@ -2,6 +2,21 @@ Reverse chronological implementation notes. Keep this factual: what changed, why, checks, and spec impact. +## 2026-07-06 - Spec: the wiki (DRAFT proposal) + +- Intent: capture Cameron's direction to reshape the documentation into a + compartmentalized, agent-navigable wiki renderable as a website. +- Changed: added spec/wiki.md (Status DRAFT): one wiki/ tree organized by + aspect (vision, mechanics, gameplay, world/characters/story, interface, + art, engineering, process, log), page types (spec/knowledge/log) as + frontmatter so bindingness survives the move, SUMMARY.md navigation, + mdBook rendering, staged four-PR migration plan, and acceptance criteria + (orphan/link checks in the gate, history preserved via git mv, hook and + dispatch paths updated atomically). +- Design/spec impact: proposal only; nothing moves until Cameron approves + the shape and the spec goes READY. +- Checks: docs-only; spec-header gate green. + ## 2026-07-06 - Spec update: serde JSON save format amendment - Intent: address PR review comment — the save format rewrite needed a diff --git a/spec/wiki.md b/spec/wiki.md new file mode 100644 index 00000000..63a9b0c7 --- /dev/null +++ b/spec/wiki.md @@ -0,0 +1,143 @@ +# Spec: the wiki — one documentation tree, agent-navigable, renderable + +``` +Status: DRAFT +Status note: directional proposal from Cameron (2026-07-06): reshape the + documentation into a compartmentalized wiki — "a huge wiki that we can + throw agents at and possibly render as a website." Big blast radius + (every doc path moves); Cameron approves the shape before anyone + implements. Migration is staged into separate PRs below. +Stage: Process +Constitution: "The constitution rule" (spec-driven work), "Ticks and the + defense rule", "Justification and legibility" (applied to the docs + themselves) +Depends on: meta.md (the page-type and header rules extend it) +``` + +## Why + +Today the documentation is three parallel trees with different rules: +`spec/` (binding contracts with status), `knowledge/` (current-state +facts), `devlogs/` + `DEVLOG.md` (history), plus the constitution and +AGENT.md at the root. It works, but it compartmentalizes by *rule type*, +not by *subject* — an agent asked about detection must know to look in +`spec/detection.md`, `knowledge/sim-mechanics.md`, and the constitution. +The proposal: one wiki tree organized by **aspect of the game** (graphics, +UX, gameplay, characters, plot, mechanics, engineering, process), where the +rule type travels with the page instead of with the directory. Single +source of truth, one navigation surface, trivially appendable, and +renderable as a website. + +## Shape + +### The tree + +``` +DESIGN.md — the constitution. Stays at the root, whole. + The law is one document; the wiki is + everything subordinate to it, and renders + it as the front page. +AGENT.md — stays at the root (session entry point). +wiki/ + SUMMARY.md — the navigation tree (mdBook format). Every + page is reachable from here; orphans fail CI. + vision/ — pitch, the gap it fills, design pillars, + design judgment (taste calibration) + mechanics/ — system contracts: compute, day-job, + detection, social, schedules, core, + rollback, markets, aggregate-observer + gameplay/ — how it plays: the big loop, acts and + pacing, whole-spectrum strategy, tuning + world/ + characters/ — cast pages (marcus, dana, ray, priya, + voss), People-as-Agents, procedural + templates + places/ — basement map, z-planes, prefab rooms, + spaces + story/ — plot: act arcs, the Voss scene, the + reveal, tone and fiction rules + interface/ + terminal.md — the terminal frontend spec (look/feel/act) + bevy.md — the Bevy frontend + ux.md — input, controls, panels, legibility rules + art/ — visual identity (clinical gore), palette, + pixel-pipeline.md Pixel Lab workflow, asset manifest rules + engineering/ — architecture, determinism, save format, + build/test workflows, check gate + process/ — meta (page rules), ticks, development + style, the PR flow, roadmap/dispatch + log/ — devlogs (append-only), the DEVLOG ledger +``` + +### Page types (the old trees become frontmatter) + +Every wiki page declares a `Type:` in its header block: + +- **spec** — a binding contract. Keeps the full meta.md header (Status / + Status note / Stage / Constitution / Depends on) and acceptance + criteria. The exact-enum rules are unchanged. +- **knowledge** — current-state fact, edited in place, no status. +- **log** — append-only history; never edited after the fact. +- (`law` is reserved for DESIGN.md itself, which does not move.) + +This preserves the load-bearing distinction the current layout encodes in +directory names — what is *binding* vs what is *descriptive* vs what is +*historical* — while letting navigation organize by subject. A page's +bindingness must remain mechanically checkable (the gate greps `Type:`). + +### Navigation and rendering + +- `wiki/SUMMARY.md` is the single navigation tree, in mdBook's format, so + the same file drives both agent navigation and website rendering. +- Renderer: **mdBook** (Rust-native; `mdbook serve` for local browsing, + `mdbook build` for the static site). DESIGN.md is symlinked/preludeed + as the book's opening chapter. `mdbook-linkcheck` (or the equivalent + check in `tools/check.sh`) fails the gate on broken internal links. +- Every directory gets a short `README.md` index paragraph: what belongs + here, what does not. Appending = drop a page in the right directory and + add its SUMMARY.md line; the gate catches a page that forgets. + +## Migration plan (staged, one PR each) + +1. **Adopt** — this spec approved; `wiki/` skeleton, SUMMARY.md, page-type + convention added to meta.md. +2. **Move** — `git mv` every `spec/` and `knowledge/` page into its wiki + home (history must survive `git log --follow`); rewrite internal + links; update AGENT.md's reading order, tick.md, ROADMAP dispatch + paths, and `.githooks/pre-commit` + `.tangled/workflows` path rules + (`touches src/ without spec/` becomes `without wiki/ or DESIGN.md`). + This PR is path churn with no content change — land it fast and alone; + every open worktree conflicts with it, so coordinate a quiet window. +3. **Render** — mdBook config, gate integration (orphan + link checks), + and a Tangled pipeline that builds the site on every PR. +4. **Absorb history** — devlogs and DEVLOG.md move under `wiki/log/` + unchanged (append-only rules keep applying). + +## Non-goals + +- Splitting the constitution. DESIGN.md remains one document at the root; + whether it ever becomes wiki chapters is **[OPEN]** and its own + constitutional act. +- A CMS or database. Markdown files in git remain the medium; "wiki" + names the organization and rendering, not the technology. +- Rewriting content. Migration moves pages; improving them stays + tick-by-tick work. + +## Acceptance criteria + +1. Every documentation page except `DESIGN.md`, `AGENT.md`, and the root + `README.md` lives under `wiki/`, is reachable from `wiki/SUMMARY.md`, + and `tools/check.sh` fails on any orphan page or broken internal link. +2. Every wiki page declares `Type: spec | knowledge | log`; spec-typed + pages keep the exact meta.md header block and acceptance criteria, and + the gate enforces headers per type. +3. `git log --follow` reaches pre-migration history for every moved page. +4. AGENT.md's reading order, tick.md's audit scope, ROADMAP dispatch + lines, and the pre-commit hook / server pipeline path rules all point + at the new paths in the same PR that moves them. +5. One documented command (`mdbook serve` or equivalent) renders the + whole wiki as a browsable website with the constitution as the front + page; a Tangled pipeline builds it on every PR. +6. The spec surface remains mechanically auditable after the move: a + script can still enumerate all spec-typed pages and their exact + statuses (the aggregate the ROADMAP and ticks depend on).