docs: rebuild the site with Astro and Starlight

[max-sixty]

The docs now build with Astro and Starlight instead of Zola. This removes the Tera 2 migration blocker from #3827 while keeping the published routes, anchors, generated references, metadata, and crawler URLs stable. It replaces the approach closed in #3840.

What changed

• Move the site into Starlight, with a custom Worktrunk homepage and a shared copper, gold, paper, and ink design system.
• Keep generated docs as portable Markdown. The Rust sync pipeline no longer needs Zola shortcodes, template escaping, ANSI-to-HTML conversion, or reverse transforms for skill and README output.
• Preserve terminal semantics and command-only copying, add responsive handling for short wide tables, retain stable heading IDs, and give repeated command-reference headings useful search labels.
• Move docs CI and publishing to Node, Astro, and built-site contract tests. The tests cover public routes, links, assets, metadata, navigation, tables, terminal frames, and compatibility aliases.
• Record demo themes from isolated environments, add a mobile core demo, and test the recording contract. The matching mobile assets are published in max-sixty/worktrunk-assets.

Closes #3827.

Verification

• cargo run -- hook pre-merge --yes (4,660 tests)
• npm --prefix docs run check
• npm --prefix docs test (9 tests)
• npm --prefix docs run build (16 pages)
• npm --prefix docs run test:site (12 tests)
• pytest docs/demos/tests/test_recording.py (4 tests)

This was written by Codex on behalf of max-sixty

[worktrunk-bot]

Reviewed the merged tree at 282fbf8c. The shape is good — the Rust side is a net −620 lines, and dropping the ANSI→HTML round trip fixes a real defect: the skill reference files were shipping raw <span class=g> markup to agents (skills/worktrunk/reference/llm-commits.md was almost entirely HTML), and they're now clean text. I built the site locally and walked the route/asset/link contract; the .md companions and the .well-known/agent-skills/worktrunk symlink both dereference correctly into dist/, so those published URLs survive the move.

Two things I'd fix before merge, one inline each.

link-check is red on this head, and it's this PR's doing — 164 errors in run 32554191286, all of the shape file:///…/docs/public/config#wt-config-state-vars | File not found. The old config excluded "/@/" because Zola's internal-link syntax was validated by zola check rather than lychee; the replacement root-relative form (/config/#anchor) has no equivalent exclusion, so lychee resolves every one of them under root_dir and 404s. The coverage isn't actually lost — npm run test:site's "built pages have unique IDs and valid internal page links" checks every internal page link and fragment against the built site, which is stricter than what lychee could do on the sources.

Prose in captured output picks up state colors. semanticOutputSegments matches a bare + ([+↑⇡]\d*, zero digits allowed — asymmetric with the - branch's \d+), so cargo's own output renders a green bold +; [!?](?=\s|$) has no left boundary, so the approval prompt's ? renders amber. Both are visible in the current build:

$ grep -o 'unoptimized <span class="wt-positive">+</span>' dist/hook/index.html | head -1
unoptimized <span class="wt-positive">+</span>
$ grep -o 'remember<span class="wt-warning">?</span>' dist/faq/index.html | head -1
remember<span class="wt-warning">?</span>

Non-blocking:

• sync_llms_txt now hardcodes the site title, description, and base URL that docs/config.toml's title / extra.site_description used to single-source for both the site and llms.txt. The description string is byte-identical to docs/src/content/docs/worktrunk.md's frontmatter description: and nothing enforces that — edit the homepage description and llms.txt keeps the old one silently. The loop already parses that page's frontmatter (it computes fm.description, then continues on slug == "worktrunk"), so lifting the value from there instead of a literal would close it. Related: Cargo.toml's affected rule now lists docs/astro.config.mjs under a comment saying the test "reads each of these at runtime (via fs::read_to_string)", but readme_sync.rs no longer reads it — harmless, just no longer true. And Head.astro carries a third copy of a site description (const description = 'Git worktree management for parallel AI agent workflows.'), distinct from the two above.
• With PageMode::color() now returning ColorChoice::Never for both variants and transform_raw() an identity function, both are constant in self — the enum is still doing real work in process_body / emit_header / experimental_marker, but these two look like they want to be plain values rather than methods.
• docs/scripts/parity.mjs defaults --reference to https://worktrunk.dev/, which is exactly what this PR replaces. Nothing references it (no CI job, and docs/CLAUDE.md's architecture table doesn't list scripts/), so after merge it compares the site against itself. Worth deleting with the migration unless it's meant to survive.
• The built-site suite pins some counts that unrelated content edits will move — assert.equal(…configToc…length, 32) and assert.equal(outputOnlyBlocks, 1). Both carry good messages, so it's a judgment call, but adding a heading to config.md will fail a test about tables of contents.

I checked the deletion surface per this repo's review guidance: remove.md, faq.md, remove.rs, and the feat_custom_remove.json entry are all touched, but only as path strings and ANSI-stripped help rendering — no destructive command is added or widened, so no hold on that account. Holding the approval purely on the red link-check.

[worktrunk-bot]

All three threads from the last review are closed. I re-verified each at this head rather than taking the commit messages for it:

• Built the site and ran the pinned lychee (0.24.2, --offline) over the same tracked .md/.txt set the hook selects: no file:// errors from the PR's files, against 164 on 282fbf8c. (The two hits my run does show are on CLAUDE.md, which this review checkout reverts to the base version; the PR head's copy already carries the updated docs/src/content/docs/faq.md paths.) root_dir = docs/dist resolves directory routes — /config/#anchor → dist/config/index.html — and a planted /nonexistent-page/ still errors, so the links are genuinely checked rather than skipped. Better than the exclusion I'd suggested.
• Rebuilt after the regex change: the wt-positive + census goes 181 → 178 and wt-warning ? 6 → 5, with both offenders gone (unoptimized + debuginfo on /hook/, Allow and remember? on /faq/) and every diffstat and status-column marker still colored. npm test 9/9.
• readme_sync 16/16 including test_docs_are_in_sync; worktrunk.md's frontmatter title and description are byte-identical to the literals they replaced, so llms.txt is unchanged by the switch to single-sourcing. cargo clippy --all-targets --all-features -- -D warnings is clean after the PageMode trim, and mode still does real work in both call sites.

One non-blocking thing on the new link-check steps: they're a verbatim copy of publish-docs.yaml's four (same Node 24, same worktrunk-assets clone and cp target), and nothing keeps the two in step. If one side moves, link-check starts validating links against a site that isn't the one that ships, with nothing to catch the drift. The repo already has .github/actions/{test,tend}-setup, so a docs-build composite would make the two builds identical by construction.