From 7644868f93c851c54e667e16a8343279b479351e Mon Sep 17 00:00:00 2001 From: Cameron Date: Thu, 9 Jul 2026 13:18:26 -0700 Subject: [PATCH] Retire mdBook documentation path Defense: Starlight is the sole live documentation renderer. Keeping mdBook, its config, CI dependency, and constitution symlink duplicated infrastructure and left agents maintaining a dead verification surface. The renderer-independent wiki gate remains, while Starlight now syncs root DESIGN.md and repo-level reference images explicitly. --- .githooks/pre-commit | 2 +- .gitignore | 1 + .tangled/workflows/check.yml | 13 ----- README.md | 4 +- book.toml | 9 ---- site/.gitignore | 1 + site/README.md | 10 ++-- site/package.json | 6 --- site/pnpm-workspace.yaml | 3 ++ site/scripts/sync-wiki.mjs | 40 ++++++++++++--- tools/check.sh | 10 ---- tools/site-build.sh | 4 +- tools/wiki_gate.sh | 11 +---- wiki/DESIGN.md | 1 - wiki/SUMMARY.md | 2 +- wiki/log/2026-07-09-mdbook-retired.md | 53 ++++++++++++++++++++ wiki/log/DEVLOG.md | 13 +++++ wiki/process/wiki.md | 71 ++++++++++++--------------- wiki/process/workflows.md | 24 ++++----- 19 files changed, 158 insertions(+), 120 deletions(-) delete mode 100644 book.toml create mode 100644 site/pnpm-workspace.yaml delete mode 120000 wiki/DESIGN.md create mode 100644 wiki/log/2026-07-09-mdbook-retired.md diff --git a/.githooks/pre-commit b/.githooks/pre-commit index cd931961..4cb420c8 100755 --- a/.githooks/pre-commit +++ b/.githooks/pre-commit @@ -36,7 +36,7 @@ if [ "$touches_spec" -eq 0 ]; then echo " wiki/ or DESIGN.md (the amendment)." echo "" echo " AGENT.md: 'No amendment, no functional change.'" - echo " Either add a wiki/DESIGN.md change to this commit, or restructure" + echo " Either add a wiki spec change or root DESIGN.md amendment, or restructure" echo " so functional changes and their amendment ship together." echo "" echo " If this is a false positive (e.g. generated code, test-only change)," diff --git a/.gitignore b/.gitignore index ef5b34e8..576becf6 100644 --- a/.gitignore +++ b/.gitignore @@ -14,4 +14,5 @@ /site/dist/ /site/.astro/ /site/src/content/docs/ +/site/src/content/assets/ /site/src/generated/ diff --git a/.tangled/workflows/check.yml b/.tangled/workflows/check.yml index 7a0c20f9..36565880 100644 --- a/.tangled/workflows/check.yml +++ b/.tangled/workflows/check.yml @@ -39,7 +39,6 @@ dependencies: - mesa - alsa-lib - eudev - - mdbook steps: - name: "cargo fmt --check" @@ -177,15 +176,3 @@ steps: 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/README.md b/README.md index 0224e9bf..d48b4c07 100644 --- a/README.md +++ b/README.md @@ -64,8 +64,8 @@ Agents are then set at the constitution, session after session. with the page. Public site: Astro Starlight under `site/` (splash at `/`, constitution at `/constitution/`, wiki beneath; deployed to the orphan `pages` branch for Tangled Sites). Use `pnpm --dir site dev` for a local - preview and `./tools/site-build.sh` for the public build; mdBook remains an - auxiliary local/check renderer, not the public surface. See + preview and `./tools/site-build.sh` for the public build; Starlight is the + only documentation renderer. See [wiki/overview.md](wiki/overview.md) and [wiki/process/workflows.md](wiki/process/workflows.md). - **[AGENT.md](AGENT.md)** — the entry point that routes agent sessions diff --git a/book.toml b/book.toml deleted file mode 100644 index c0d05de4..00000000 --- a/book.toml +++ /dev/null @@ -1,9 +0,0 @@ -[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/site/.gitignore b/site/.gitignore index c442ee63..e4940f22 100644 --- a/site/.gitignore +++ b/site/.gitignore @@ -4,6 +4,7 @@ dist/ # generated from wiki/ — never hand-edit src/content/docs/ +src/content/assets/ src/generated/ # dependencies diff --git a/site/README.md b/site/README.md index 92943bc6..012ee41a 100644 --- a/site/README.md +++ b/site/README.md @@ -29,9 +29,9 @@ Every site asset/page must have a source clause, per DESIGN.md's - `public/favicon.svg` — browser/site identity affordance for the public documentation site, justified by `wiki/interface/site.md` and the Starlight public-site workflow in `wiki/process/workflows.md`. -- Generated `src/content/docs/`, `src/generated/`, and `dist/` — outputs of - `scripts/sync-wiki.mjs` / Astro, justified by `wiki/process/wiki.md` and - `wiki/process/workflows.md`; never hand-edit them. +- Generated `src/content/docs/`, `src/content/assets/`, `src/generated/`, and + `dist/` — outputs of `scripts/sync-wiki.mjs` / Astro, justified by + `wiki/process/wiki.md` and `wiki/process/workflows.md`; never hand-edit them. ## Commands @@ -44,8 +44,8 @@ pnpm --dir site dev # local preview (SITE_BASE=/) ./tools/site-deploy.sh # build + force-push orphan `pages` branch ``` -Generated paths (`src/content/docs/`, `src/generated/`, `dist/`) are -gitignored. Do not hand-edit them. +Generated paths (`src/content/docs/`, `src/content/assets/`, `src/generated/`, +`dist/`) are gitignored. Do not hand-edit them. See [wiki/process/workflows.md](../wiki/process/workflows.md) for Tangled Sites configuration and the deferred CI deploy note. diff --git a/site/package.json b/site/package.json index 70931ff2..29a0a3af 100644 --- a/site/package.json +++ b/site/package.json @@ -12,12 +12,6 @@ "preview": "node ./node_modules/astro/bin/astro.mjs preview", "astro": "node ./node_modules/astro/bin/astro.mjs" }, - "pnpm": { - "onlyBuiltDependencies": [ - "esbuild", - "sharp" - ] - }, "dependencies": { "@astrojs/starlight": "^0.41.3", "astro": "^7.0.2", diff --git a/site/pnpm-workspace.yaml b/site/pnpm-workspace.yaml new file mode 100644 index 00000000..dbb26c82 --- /dev/null +++ b/site/pnpm-workspace.yaml @@ -0,0 +1,3 @@ +allowBuilds: + esbuild: true + sharp: true diff --git a/site/scripts/sync-wiki.mjs b/site/scripts/sync-wiki.mjs index 85adbf0d..c9c4bc17 100755 --- a/site/scripts/sync-wiki.mjs +++ b/site/scripts/sync-wiki.mjs @@ -13,7 +13,9 @@ const __dirname = path.dirname(fileURLToPath(import.meta.url)); const SITE_ROOT = path.resolve(__dirname, '..'); const REPO_ROOT = path.resolve(SITE_ROOT, '..'); const WIKI_ROOT = path.join(REPO_ROOT, 'wiki'); +const REPO_ASSETS_ROOT = path.join(REPO_ROOT, 'assets'); const DOCS_OUT = path.join(SITE_ROOT, 'src', 'content', 'docs'); +const ASSETS_OUT = path.join(SITE_ROOT, 'src', 'content', 'assets'); const GENERATED_OUT = path.join(SITE_ROOT, 'src', 'generated'); const SIDEBAR_OUT = path.join(GENERATED_OUT, 'sidebar.ts'); @@ -85,9 +87,10 @@ function yamlEscape(s) { /** wiki-relative path → Starlight slug (no leading/trailing slash). */ function wikiRelToSlug(relPosix) { - let slug = relPosix.replace(/\.md$/i, ''); + const normalized = path.posix.normalize(relPosix); + let slug = normalized.replace(/\.md$/i, ''); // Constitution is a docs page; the splash homepage is a custom Astro route. - if (slug === 'DESIGN') return 'constitution'; + if (slug === 'DESIGN' || slug === '../DESIGN') return 'constitution'; if (slug.endsWith('/README')) { slug = slug.slice(0, -'/README'.length); } else if (slug === 'README') { @@ -212,7 +215,7 @@ function mapItem(item) { return { label: item.label, slug }; } -/** Parse mdBook SUMMARY.md into Starlight sidebar items. */ +/** Parse the repo's CommonMark SUMMARY.md into Starlight sidebar items. */ function parseSummary(summaryText) { const lines = summaryText.split(/\r?\n/); const top = []; @@ -296,11 +299,17 @@ function main() { } rmrf(DOCS_OUT); + rmrf(ASSETS_OUT); ensureDir(DOCS_OUT); + ensureDir(ASSETS_OUT); ensureDir(GENERATED_OUT); + // DESIGN.md is root law, not a wiki file. Sync it explicitly as the public + // constitution instead of keeping a renderer-specific symlink under wiki/. + writeDoc('DESIGN.md', path.join(REPO_ROOT, 'DESIGN.md')); + let pageCount = 1; + const mdFiles = walkFiles(WIKI_ROOT, (name) => name.endsWith('.md')); - let pageCount = 0; for (const abs of mdFiles) { const rel = path.relative(WIKI_ROOT, abs).split(path.sep).join('/'); const real = fs.realpathSync(abs); @@ -308,11 +317,11 @@ function main() { pageCount += 1; } - const assets = walkFiles(WIKI_ROOT, (name) => + const wikiAssets = walkFiles(WIKI_ROOT, (name) => ASSET_EXT.has(path.extname(name).toLowerCase()), ); let assetCount = 0; - for (const abs of assets) { + for (const abs of wikiAssets) { const rel = path.relative(WIKI_ROOT, abs).split(path.sep).join('/'); const dest = path.join(DOCS_OUT, rel); ensureDir(path.dirname(dest)); @@ -320,6 +329,25 @@ function main() { assetCount += 1; } + // Wiki pages keep repo-relative links to design references under assets/. + // Mirror those files beside the generated docs so Astro can resolve the + // same ../../assets/... paths without rewriting source documentation. + if (fs.existsSync(REPO_ASSETS_ROOT)) { + const repoAssets = walkFiles(REPO_ASSETS_ROOT, (name) => + ASSET_EXT.has(path.extname(name).toLowerCase()), + ); + for (const abs of repoAssets) { + const rel = path + .relative(REPO_ASSETS_ROOT, abs) + .split(path.sep) + .join('/'); + const dest = path.join(ASSETS_OUT, rel); + ensureDir(path.dirname(dest)); + fs.copyFileSync(fs.realpathSync(abs), dest); + assetCount += 1; + } + } + const summary = fs.readFileSync(path.join(WIKI_ROOT, 'SUMMARY.md'), 'utf8'); const sidebar = parseSummary(summary); writeSidebar(sidebar); diff --git a/tools/check.sh b/tools/check.sh index 1157cc0f..08a5fcd9 100755 --- a/tools/check.sh +++ b/tools/check.sh @@ -215,16 +215,6 @@ done < <(find wiki -name '*.md' -print0) 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/site-build.sh b/tools/site-build.sh index 0a4a598b..2c072dcf 100755 --- a/tools/site-build.sh +++ b/tools/site-build.sh @@ -20,8 +20,8 @@ cd "$SITE" if [ ! -d node_modules ]; then echo "site-build: installing dependencies..." - # pnpm 10 ignores dependency build scripts unless listed in - # package.json pnpm.onlyBuiltDependencies (esbuild, sharp). + # pnpm runs only the reviewed dependency build scripts listed in + # site/pnpm-workspace.yaml (esbuild and sharp). pnpm install --frozen-lockfile fi diff --git a/tools/wiki_gate.sh b/tools/wiki_gate.sh index 53b739be..fbe832ae 100755 --- a/tools/wiki_gate.sh +++ b/tools/wiki_gate.sh @@ -1,10 +1,8 @@ #!/usr/bin/env bash # Wiki gate (wiki/process/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). +# at a file that doesn't exist. Pure bash/grep, with no renderer/toolchain +# dependency in CI. # # Known limitation: the link extractor is a plain `](...)` pattern match, # so it cannot tell a real link from a `` `](literal-example.md)` `` @@ -69,11 +67,6 @@ check_links_in() { } 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 "README.md"; echo "DESIGN.md") diff --git a/wiki/DESIGN.md b/wiki/DESIGN.md deleted file mode 120000 index aedc7d9a..00000000 --- a/wiki/DESIGN.md +++ /dev/null @@ -1 +0,0 @@ -../DESIGN.md \ No newline at end of file diff --git a/wiki/SUMMARY.md b/wiki/SUMMARY.md index 4bf89171..6a535d31 100644 --- a/wiki/SUMMARY.md +++ b/wiki/SUMMARY.md @@ -1,6 +1,6 @@ # Summary -[The constitution](DESIGN.md) +[The constitution](../DESIGN.md) [The wiki](overview.md) # Vision diff --git a/wiki/log/2026-07-09-mdbook-retired.md b/wiki/log/2026-07-09-mdbook-retired.md new file mode 100644 index 00000000..16837906 --- /dev/null +++ b/wiki/log/2026-07-09-mdbook-retired.md @@ -0,0 +1,53 @@ +# mdBook retired — Starlight is the documentation renderer + +``` +Type: log +``` + +## Finding + +Cameron noted that the proportional-check cleanup still described mdBook as a +live documentation surface. Repository inspection confirmed the drift: +Starlight is the public/local wiki renderer and has its own Tangled site-build +workflow, but mdBook remained installed in the Rust CI image, ran from +`tools/check.sh`, owned `book.toml`, and required a `wiki/DESIGN.md` symlink. + +That was redundant infrastructure and contradicted the single-renderer wiki +reality. + +## Removed + +- root `book.toml`; +- the mdBook-only `wiki/DESIGN.md -> ../DESIGN.md` symlink; +- local mdBook execution from `tools/check.sh`; +- the nixpkgs mdBook dependency and build step from + `.tangled/workflows/check.yml`; +- live workflow/README claims that mdBook remained an auxiliary renderer. + +Historical devlogs retain their mdBook references because they accurately +record what ran at the time. + +## Starlight sync correction + +The symlink had also been the implicit way `site/scripts/sync-wiki.mjs` found +the constitution. The sync now copies root `DESIGN.md` explicitly to the +Starlight constitution page. `wiki/SUMMARY.md` links directly to +`../DESIGN.md`; its parser normalizes that root-law path to `/constitution/`. +The SUMMARY remains the single navigation source because Starlight still +parses it; only the mdBook renderer is gone. + +The focused production build also exposed two stale edges in that sole +renderer. The sync now mirrors repo-level image references used by wiki pages, +and pnpm's reviewed `esbuild`/`sharp` build allowlist now lives in the current +`pnpm-workspace.yaml` format. + +## Verification + +- shell syntax for changed hooks/gates; +- `bash tools/wiki_gate.sh`; +- Starlight sync + production site build; +- generated constitution and sidebar assertions; +- global live-doc/config search leaves only explicit retirement history. + +No Rust, clippy, Bevy, or mdBook run is relevant to this docs/site/tooling +change. diff --git a/wiki/log/DEVLOG.md b/wiki/log/DEVLOG.md index 174a5bb6..6b9cc894 100644 --- a/wiki/log/DEVLOG.md +++ b/wiki/log/DEVLOG.md @@ -5,6 +5,19 @@ Type: log ``` Reverse chronological implementation notes. Keep this factual: what changed, why, checks, and spec impact. +## 2026-07-09 - mdBook retired + +- Intent: remove the obsolete auxiliary renderer after Starlight became the + sole public/local documentation surface. +- Changed: deleted `book.toml` and the renderer-only constitution symlink; + removed mdBook from local/CI gates; Starlight sync now copies root DESIGN.md + explicitly, parses the root-law SUMMARY link, and mirrors referenced design + assets. Migrated pnpm's dependency-build allowlist to its current workspace + format so the sole renderer installs and builds cleanly. +- Checks: shell syntax, wiki gate, Starlight sync/build, generated constitution + and sidebar assertions. No Rust/Bevy gate. +- Log: wiki/log/2026-07-09-mdbook-retired.md. + ## 2026-07-09 - Proportional verification policy - Intent: stop full Cargo/clippy/Bevy gates from running for minor docs, spec, diff --git a/wiki/process/wiki.md b/wiki/process/wiki.md index e9dccdef..3d9099fb 100644 --- a/wiki/process/wiki.md +++ b/wiki/process/wiki.md @@ -5,28 +5,16 @@ Type: spec Status: IMPLEMENTED Status note: shape approved by Cameron (2026-07-07: "I like the wiki format... go ahead and implement the wiki thing"); migrated in four - staged commits (Adopt, Move, Render, Absorb history) per this spec's - own plan. All six acceptance criteria verified 2026-07-07: 79/80 real - pages carry `Type:` (the 80th is `wiki/DESIGN.md`'s `law`-type - exception); `git log --follow` traces full pre-migration history for - every one of the 67 moved pages (44 spec/knowledge pages in stage 2, 23 - history pages in stage 4; verified with a script checking every - page in the tree has 2+ commits in its --follow history); the two - dissolved - index pages required a two-commit split — see stage 2's commits — - specifically to keep their rename detectable); AGENT.md, tick.md, - ROADMAP dispatch lines, the pre-commit hook, and both Tangled - workflows all repoint at `wiki/`; `mdbook build`/`mdbook serve` render - the whole tree with `DESIGN.md` as the front page (documented in - wiki/process/workflows.md), and `.tangled/workflows/check.yml` builds - it every push via a nixpkgs-provided `mdbook`; `tools/check.sh`'s - spec-header step mechanically enumerates every `Type: spec` page and - its status (independent of the hand-maintained `wiki/process/specs.md` - board). One deliberate, documented scope narrowing: `wiki/log/*.md` - (dated devlogs) are exempt from individual SUMMARY.md reachability — - see "Design note" below. **NOT yet merged to main** — Cameron asked - this branch be held for review given the size of the path churn; - merge is a separate step. + staged commits (Adopt, Move, Render, Absorb history) per this spec's own + plan. The current renderer is Astro Starlight under `site/`; it explicitly + syncs root `DESIGN.md` as `/constitution/` and parses `wiki/SUMMARY.md` for + navigation. mdBook, `book.toml`, the renderer-only `wiki/DESIGN.md` symlink, + and the mdBook CI/local gate were retired 2026-07-09. `tools/wiki_gate.sh` + enforces reachability and links without a renderer dependency; + `tools/check.sh` mechanically enumerates every `Type: spec` page and its + status (independent of the hand-maintained `wiki/process/specs.md` board). + Dated `wiki/log/*.md` entries remain deliberately exempt from individual + SUMMARY.md reachability — see "Design note" below. Stage: Process Constitution: "The constitution rule" (spec-driven work), "Ticks and the defense rule", "Justification and legibility" (applied to the docs @@ -56,12 +44,13 @@ renderable as a website. ``` 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. + everything subordinate to it. Starlight syncs + it explicitly as the constitution 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. + SUMMARY.md — the CommonMark navigation tree parsed by the + Starlight sync. 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, @@ -115,9 +104,9 @@ 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 agent navigation, mdBook, and the public Starlight - sidebar (`site/scripts/sync-wiki.mjs` parses it). +- `wiki/SUMMARY.md` is the single CommonMark navigation tree. It drives agent + navigation and the public Starlight sidebar + (`site/scripts/sync-wiki.mjs` parses it). - **Public renderer: Astro Starlight** under `site/`. Syncs `wiki/` into generated content, builds static HTML, and publishes an orphan `pages` branch for Tangled Sites (see [workflows.md](workflows.md)). The visual @@ -130,10 +119,11 @@ bindingness must remain mechanically checkable (the gate greps `Type:`). and a primary CTA to the constitution. Public claims are part of the constitution contract, and the splash/its assets obey DESIGN.md's no-unsourced-surface law. DESIGN.md renders at `/constitution/`. -- **Local / CI renderer: mdBook** remains (`mdbook serve` / `mdbook build`, - enforced in `tools/check.sh` and `.tangled/workflows/check.yml`). DESIGN.md - is symlinked as the book's opening chapter. The wiki-gate script fails - the gate on broken internal links and orphans. +- **One renderer.** Starlight serves both local preview and public output. + Root `DESIGN.md` is copied explicitly as the constitution page; there is no + renderer-specific duplicate/symlink under `wiki/`. The renderer-independent + wiki gate fails on broken internal links and orphans, while the site workflow + owns the rendered build. - 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. @@ -154,8 +144,9 @@ current process — worktree, `./tools/check.sh`, rebase onto This commit is path churn with no content change — land it fast and alone; every open worktree conflicts with it, so rebase immediately before pushing and fold in anything landed concurrently. -3. **Render** — mdBook config, gate integration (orphan + link checks), - and a Tangled pipeline that builds the site on every push. +3. **Render** — originally landed with mdBook plus orphan/link gates; the + renderer was later superseded by Starlight and retired 2026-07-09. The + renderer-independent wiki gate remains. 4. **Absorb history** — pre-migration devlogs and root DEVLOG.md move under `wiki/log/` unchanged (append-only rules keep applying). @@ -180,7 +171,7 @@ requiring a matching SUMMARY.md edit for every entry would either rot silently (forgotten, permanently failing the gate on unrelated commits) or turn "write a devlog" into a two-file chore, undermining the habit the whole append-only design depends on. They remain fully reachable — -via `wiki/log/DEVLOG.md`'s ledger, `git log`, and the mdBook-rendered +via `wiki/log/DEVLOG.md`'s ledger, `git log`, and the Starlight-rendered `log/README.md` overview — just not through individually hand-maintained nav entries. This is a deliberate, documented narrowing, not a silent gap (meta.md's cross-spec-contract rule). @@ -198,10 +189,10 @@ gap (meta.md's cross-spec-contract rule). 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 commit that moves them. -5. One documented command renders the whole wiki as a browsable website - with the constitution as the front page: `pnpm --dir site dev` (public - Starlight) or `mdbook serve` (local mdBook). A Tangled pipeline builds - the Starlight site on every push (`.tangled/workflows/site.yml`); the +5. One documented renderer builds the whole wiki as a browsable website with + the constitution as the front page: Astro Starlight (`pnpm --dir site dev` + locally, `./tools/site-build.sh` for production). A Tangled pipeline builds + the site on every push (`.tangled/workflows/site.yml`); the orphan `pages` branch is published via `./tools/site-deploy.sh` (CI auto-deploy deferred until a write secret exists). 6. The spec surface remains mechanically auditable after the move: a diff --git a/wiki/process/workflows.md b/wiki/process/workflows.md index 32cd75b3..5c959f63 100644 --- a/wiki/process/workflows.md +++ b/wiki/process/workflows.md @@ -33,13 +33,14 @@ For Rust-impacting work (`src/`, Cargo/build configuration, Rust tests/examples/benches), run: ```bash -./tools/check.sh # fmt, tests, clippy (both features), bevy build, spec headers, wiki gate, mdbook build +./tools/check.sh # fmt, tests, clippy (both features), bevy build, spec headers, wiki gate ``` For non-Rust work, run the smallest checks that can actually detect a mistake: - docs/spec/process/logs: `git diff --check` and `bash tools/wiki_gate.sh` when - wiki-facing; `mdbook build` only when the rendered book surface matters; + wiki-facing; run `./tools/site-build.sh` only when the rendered Starlight + surface or sync pipeline matters; - reference art: validate the source format, render it, and inspect the output; - public site: run the site sync/build relevant to the changed page or style; - shell/tooling: syntax-check the changed script and run its targeted smoke or @@ -130,19 +131,12 @@ after wiki-facing landings when the public site should refresh. Optional later step: add a deploy job that uses the secret to force-push `pages` the same way `site-deploy.sh` does. -**mdBook (local / check gate).** Still wired for agent browsing and -`tools/check.sh`: - -```bash -mdbook serve # local live-reloading server (default: http://localhost:3000) -mdbook build # static site in book/ (gitignored) -``` - -`book.toml` at the repo root points mdBook at `src = "wiki"`; the -constitution renders as the front page via `wiki/DESIGN.md` (a symlink -to `../DESIGN.md`). Install once with `cargo install mdbook` — CI -enforces the build via the nixpkgs-provided binary regardless of what's -installed locally (`.tangled/workflows/check.yml`). +Starlight is the only documentation renderer. mdBook, `book.toml`, and the +renderer-only `wiki/DESIGN.md` symlink were retired 2026-07-09. The Starlight +sync copies root `DESIGN.md` explicitly to `/constitution/` and parses +`wiki/SUMMARY.md` for navigation. The Rust/check pipeline enforces structural +wiki correctness through `tools/wiki_gate.sh`; `.tangled/workflows/site.yml` +owns the rendered-site build. ## Running the game -- 2.51.2