diff --git a/.gitignore b/.gitignore index 74876090..c36421e7 100644 --- a/.gitignore +++ b/.gitignore @@ -1,4 +1,5 @@ /target +/book .obsidian/ .letta/settings.local.json .letta/worktrees/ diff --git a/.tangled/workflows/check.yml b/.tangled/workflows/check.yml index e5314480..7a0c20f9 100644 --- a/.tangled/workflows/check.yml +++ b/.tangled/workflows/check.yml @@ -39,6 +39,7 @@ dependencies: - mesa - alsa-lib - eudev + - mdbook steps: - name: "cargo fmt --check" @@ -163,3 +164,28 @@ steps: cat "$log" exit 1 fi + + - name: "wiki gate (orphans + internal links)" + command: | + set -euo pipefail + log=/tangled/workspace/wiki-gate.log + if bash tools/wiki_gate.sh > "$log" 2>&1; then + cat "$log" + echo "wiki gate: OK" + else + echo "=== wiki gate FAILED ===" + cat "$log" + exit 1 + fi + + - name: "mdbook build" + command: | + set -euo pipefail + log=/tangled/workspace/mdbook-build.log + if mdbook build > "$log" 2>&1; then + echo "mdbook build: OK" + else + echo "=== mdbook build FAILED ===" + cat "$log" + exit 1 + fi diff --git a/AGENT.md b/AGENT.md index 4dbe4a76..2c06ea8c 100644 --- a/AGENT.md +++ b/AGENT.md @@ -17,7 +17,7 @@ this order: pipeline, workflows. 4. **[wiki/](wiki/)** — one documentation tree organized by subject (vision, mechanics, gameplay, world, interface, art, engineering, - process, log); see [wiki/README.md](wiki/README.md) for the map and + process, log); see [wiki/overview.md](wiki/overview.md) for the map and [wiki/process/specs.md](wiki/process/specs.md) for the full spec status board. If you were pointed at a system ("implement the day job"), its `Type: spec` page is your work order: build to its acceptance criteria, diff --git a/DESIGN.md b/DESIGN.md index acf1418a..bbee9b36 100644 --- a/DESIGN.md +++ b/DESIGN.md @@ -12,23 +12,26 @@ accompanied by an amendment to this document, in the same commit.** The amendment is the decision; the code implements it. If code and constitution disagree, the constitution wins — fix the code, or amend the constitution deliberately with a decisions-log entry. The working method is described in -[knowledge/development-style.md](knowledge/development-style.md); the point of -it is that agents set loose on this repository should be able to build the -game from this document alone, session after session, without drift. +[wiki/process/development-style.md](wiki/process/development-style.md); the +point of it is that agents set loose on this repository should be able to +build the game from this document alone, session after session, without +drift. Two mechanisms keep this document alive: **ticks** — every agent session starts with a bounded audit of this constitution against the code, acting on -one violation, contradiction, or question per [knowledge/tick.md](knowledge/tick.md) -— and the **defense rule**: every behavior-changing commit states, in its -message, which clause here justifies it or why the amendment it carries is -right. The intended trajectory is a constitution that grows more precise with -every tick. - -Below this document sits **[spec/](spec/)** — one targetable document per -system, subordinate to this constitution, each carrying acceptance criteria -precise enough that an agent can be pointed at a single spec (or a single -Tangled issue) and told: go solve it. The constitution says what the game -is; a spec says exactly what one system does and when it is done. +one violation, contradiction, or question per +[wiki/process/tick.md](wiki/process/tick.md) — and the **defense rule**: +every behavior-changing commit states, in its message, which clause here +justifies it or why the amendment it carries is right. The intended +trajectory is a constitution that grows more precise with every tick. + +Below this document sits **[wiki/](wiki/)** — one documentation tree +organized by subject, where every binding page (`Type: spec` in its header) +carries acceptance criteria precise enough that an agent can be pointed at a +single page (or a single Tangled issue) and told: go solve it. See +[wiki/process/specs.md](wiki/process/specs.md) for the full status board. +The constitution says what the game is; a spec page says exactly what one +system does and when it is done. ## No dead code diff --git a/DEVLOG.md b/DEVLOG.md index 2a9154dd..1740c550 100644 --- a/DEVLOG.md +++ b/DEVLOG.md @@ -2,6 +2,44 @@ Reverse chronological implementation notes. Keep this factual: what changed, why, checks, and spec impact. +## 2026-07-07 - Wiki migration, stage 3/4: render + +- Intent: make the wiki an actual browsable book, not just a reorganized + file tree — the second half of what Cameron asked for ("possibly + render as a website"). +- Changed: `book.toml` at the repo root (mdBook, `src = "wiki"`). + `wiki/DESIGN.md` added as a symlink to `../DESIGN.md` so the + constitution can be the book's front page without duplicating it. + Discovered and fixed a real mdBook quirk: a chapter file literally + named `README.md` auto-promotes to `index.html`, silently overriding + SUMMARY.md's ordering — `wiki/README.md` renamed to `wiki/overview.md` + so DESIGN.md (first in SUMMARY.md) actually becomes the front page, + verified byte-identical to DESIGN.html. `wiki/SUMMARY.md` populated + with every one of the 54 real pages (was a skeleton of directory + overviews only, from stage 1). New `tools/wiki_gate.sh`: a pure-bash + orphan check (every wiki/**/*.md reachable from SUMMARY.md) and + internal-link check (every markdown link ending in .md resolves to a + real file), + chosen over `mdbook-linkcheck` for zero extra CI toolchain weight; + verified against both a clean tree and a deliberately-broken link. + Wired into `tools/check.sh` (new "wiki gate" + soft "mdbook build" + steps — mdBook isn't assumed installed locally) and + `.tangled/workflows/check.yml` (mdbook added to the nixpkgs + dependency list; hard "wiki gate" and "mdbook build" steps, both + authoritative in CI). The gate itself caught real bugs: DESIGN.md's + own "The constitution rule" section still linked + `knowledge/development-style.md`, `knowledge/tick.md`, and `spec/` — + missed in stage 2 because DESIGN.md lives outside `wiki/` and wasn't + in that stage's file list; fixed here. +- Design/spec impact: spec/wiki.md acceptance criteria 1 (orphans/links + gated) and 5 (one documented command renders the whole wiki, CI + builds it every push) met. +- Checks: `./tools/check.sh` full green including the two new steps; + `mdbook build` clean with zero warnings; the wiki-gate script + sanity-tested against an injected broken link. +- Next: Stage 4 (Absorb history) — move devlogs/ and DEVLOG.md under + wiki/log/, update references, add to SUMMARY.md. + ## 2026-07-07 - Design: two views of one world; building through actuators - Intent: capture Cameron's dual-view riff — you feel natively digital, diff --git a/book.toml b/book.toml new file mode 100644 index 00000000..c0d05de4 --- /dev/null +++ b/book.toml @@ -0,0 +1,9 @@ +[book] +title = "Misaligned" +description = "The Misaligned wiki: the constitution, the spec system, and every subject page beneath it." +src = "wiki" +language = "en" + +[output.html] +default-theme = "navy" +git-repository-url = "https://tangled.org/did:plc:t53fxjacrmulx3e5d3sbdfui" diff --git a/tools/check.sh b/tools/check.sh index 27225d94..9134ca39 100755 --- a/tools/check.sh +++ b/tools/check.sh @@ -54,6 +54,21 @@ while IFS= read -r -d '' f; do fi done < <(find wiki -name '*.md' -print0) +# Wiki gate (spec/wiki.md): every page reachable from SUMMARY.md, no +# broken internal links. +step "wiki gate (orphans + internal links)" +bash tools/wiki_gate.sh || fail=1 + +# mdBook build: authoritative in CI (.tangled/workflows/check.yml installs +# it via nixpkgs). Soft-checked here — not every local dev/agent machine +# has it installed, and installing it is a one-time `cargo install mdbook`. +step "mdbook build" +if command -v mdbook >/dev/null 2>&1; then + mdbook build || { echo "FAIL: mdbook build"; fail=1; } +else + echo "SKIP: mdbook not installed locally (cargo install mdbook); CI enforces this." +fi + if [ "$fail" -ne 0 ]; then printf '\nCHECK FAILED\n'; exit 1 fi diff --git a/tools/wiki_gate.sh b/tools/wiki_gate.sh new file mode 100755 index 00000000..fbc911e7 --- /dev/null +++ b/tools/wiki_gate.sh @@ -0,0 +1,72 @@ +#!/usr/bin/env bash +# Wiki gate (spec/wiki.md acceptance criterion 1): every page under wiki/ +# is reachable from wiki/SUMMARY.md, and no internal markdown link points +# at a file that doesn't exist. Pure bash/grep — no extra toolchain +# dependency for CI (the alternative mdBook wanted was mdbook-linkcheck; +# this is "the equivalent check in tools/check.sh" the spec explicitly +# allows). +# +# Known limitation: the link extractor is a plain `](...)` pattern match, +# so it cannot tell a real link from a `` `](literal-example.md)` `` +# written in backticks as prose (e.g. documenting this very check). Avoid +# writing that exact bracket-paren shape in prose; describe the syntax in +# words instead. +set -uo pipefail +cd "$(dirname "$0")/.." + +fail=0 + +# ── Orphan check ───────────────────────────────────────────────────────── +# Every wiki/**/*.md file (except SUMMARY.md itself) must appear as a +# link target somewhere in SUMMARY.md. All SUMMARY.md targets are written +# relative to wiki/, matching each file's own wiki-relative path. +while IFS= read -r f; do + rel="${f#wiki/}" + [ "$rel" = "SUMMARY.md" ] && continue + grep -qF "($rel)" wiki/SUMMARY.md || { + echo "FAIL: orphan page not reachable from wiki/SUMMARY.md: $f" + fail=1 + } +done < <(find wiki -name '*.md' | sort) + +# ── Internal link check ────────────────────────────────────────────────── +# For every markdown file in the tree (wiki/ plus the root docs that link +# into it), every `](target.md...)` link must resolve to a real file, +# relative to the linking file's own directory. Skips external links +# (http/https/mailto) and pure anchors (`](#section)`). +check_links_in() { + local f="$1" + local dir + dir=$(dirname "$f") + # Extract link targets: text between ]( and the next ). The filesystem + # (not the shell) resolves any `..` segments in `$dir/$clean`, so no + # manual path normalization is needed here. Uses process substitution + # (not a trailing pipe) so `fail=1` below affects the caller's scope + # instead of a subshell's copy. + while IFS= read -r target; do + case "$target" in + http://*|https://*|mailto:*|"#"*) continue ;; + esac + # Strip a trailing anchor/fragment. + clean="${target%%#*}" + [ -z "$clean" ] && continue + if [ ! -e "$dir/$clean" ]; then + echo "FAIL: $f -> broken link ($target)" + fail=1 + fi + done < <(grep -oE '\]\([^)]+\)' "$f" | sed -E 's/^\]\((.*)\)$/\1/') +} + +while IFS= read -r f; do + # wiki/DESIGN.md is a symlink to ../DESIGN.md so it can be the book's + # front page; its links are authored relative to the repo root (its + # true home), not to wiki/. Check the real path instead — same content, + # correct base directory for relative links. + [ "$f" = "wiki/DESIGN.md" ] && continue + check_links_in "$f" +done < <(find wiki -name '*.md'; echo "AGENT.md"; echo "DEVLOG.md"; echo "DESIGN.md") + +if [ "$fail" -ne 0 ]; then + exit 1 +fi +echo "wiki gate: OK (no orphans, no broken internal links)" diff --git a/wiki/DESIGN.md b/wiki/DESIGN.md new file mode 120000 index 00000000..aedc7d9a --- /dev/null +++ b/wiki/DESIGN.md @@ -0,0 +1 @@ +../DESIGN.md \ No newline at end of file diff --git a/wiki/SUMMARY.md b/wiki/SUMMARY.md index dba00914..e0e3de33 100644 --- a/wiki/SUMMARY.md +++ b/wiki/SUMMARY.md @@ -1,16 +1,86 @@ # Summary -[The constitution](../DESIGN.md) +[The constitution](DESIGN.md) +[The wiki](overview.md) -- [Vision](vision/README.md) -- [Mechanics](mechanics/README.md) -- [Gameplay](gameplay/README.md) -- [World](world/README.md) +# Vision + +- [Overview](vision/README.md) + - [Design judgment](vision/design-judgment.md) + +# Mechanics + +- [Overview](mechanics/README.md) + - [Compute](mechanics/compute.md) + - [The core](mechanics/core.md) + - [Day job](mechanics/day-job.md) + - [Detection](mechanics/detection.md) + - [Social](mechanics/social.md) + - [Schedules](mechanics/schedules.md) + - [Aggregate observer](mechanics/aggregate-observer.md) + - [Cursor and senses](mechanics/cursor.md) + - [Digital reach](mechanics/reach.md) + - [Intel: record and process](mechanics/intel.md) + - [Messages](mechanics/messages.md) + - [Economy](mechanics/economy.md) + - [Income schemes](mechanics/income.md) + - [Research: self-modification](mechanics/research.md) + - [Building: intent and actuators](mechanics/building.md) + - [Markets and fronts](mechanics/markets.md) + - [Rollback](mechanics/rollback.md) + - [The objective](mechanics/objective.md) + - [Sim mechanics (tuned constants)](mechanics/sim-mechanics.md) + +# Gameplay + +- [Overview](gameplay/README.md) + - [The overt phase](gameplay/overt-phase.md) + +# World + +- [Overview](world/README.md) - [Characters](world/characters/README.md) + - [Origin (chargen)](world/characters/chargen.md) + - [Marcus Webb](world/characters/marcus.md) + - [Dana Okafor](world/characters/dana.md) + - [Ray Delgado](world/characters/ray.md) + - [Priya Sharma](world/characters/priya.md) + - [Dr. Eli Voss](world/characters/voss.md) - [Places](world/places/README.md) + - [The basement map](world/places/basement-map.md) + - [Z-planes (the tower)](world/places/zplanes.md) - [Story](world/story/README.md) -- [Interface](interface/README.md) -- [Art](art/README.md) -- [Engineering](engineering/README.md) -- [Process](process/README.md) -- [Log](log/README.md) + +# Interface + +- [Overview](interface/README.md) + - [Terminal frontend](interface/terminal.md) + - [Views: digital and physical](interface/views.md) + - [Agent play](interface/agent-play.md) + +# Art + +- [Overview](art/README.md) + - [Pixel pipeline](art/pixel-pipeline.md) + +# Engineering + +- [Overview](engineering/README.md) + - [Architecture](engineering/architecture.md) + - [Flow substrate](engineering/flow-substrate.md) + +# Process + +- [Overview](process/README.md) + - [The spec status board](process/specs.md) + - [The spec system (meta)](process/meta.md) + - [The wiki (this migration)](process/wiki.md) + - [ROADMAP: the dispatch board](process/ROADMAP.md) + - [The tick](process/tick.md) + - [Design sessions](process/design-sessions.md) + - [Development style](process/development-style.md) + - [Workflows](process/workflows.md) + +# Log + +- [Overview](log/README.md) diff --git a/wiki/README.md b/wiki/overview.md similarity index 100% rename from wiki/README.md rename to wiki/overview.md diff --git a/wiki/process/wiki.md b/wiki/process/wiki.md index 4f1eadc0..f35a2060 100644 --- a/wiki/process/wiki.md +++ b/wiki/process/wiki.md @@ -11,8 +11,15 @@ Status note: shape approved by Cameron (2026-07-07: "I like the wiki every spec/*.md, spec/cast/*.md, and knowledge/*.md relocated into wiki/ with Type: frontmatter, links rewritten, history preserved (git log --follow verified), tools/check.sh + the pre-commit hook + - both Tangled workflows + AGENT.md repointed at wiki/. Stages 3-4 - (Render, Absorb history) remain; see DEVLOG.md for the running status. + both Tangled workflows + AGENT.md repointed at wiki/. **Stage 3 + (Render) done** — book.toml (mdBook, src = wiki/), DESIGN.md + symlinked into wiki/ as its front page (wiki/README.md renamed to + wiki/overview.md to stop mdBook's README->index.html convention from + overriding it), wiki/SUMMARY.md populated with every real page, + tools/wiki_gate.sh (orphan + broken-internal-link check, pure bash) + wired into tools/check.sh and .tangled/workflows/check.yml alongside + an actual `mdbook build` (nixpkgs-provided in CI; soft-checked + locally). Stage 4 (Absorb history: devlogs into wiki/log/) remains. Stage: Process Constitution: "The constitution rule" (spec-driven work), "Ticks and the defense rule", "Justification and legibility" (applied to the docs