Skip to content

Wiki ​

Wiki is the docs-site generator – the skill that produced the very site you are reading. Point it at a repo and it turns the whole codebase into a browsable VitePress site under <repo>/wiki/: a home page, one page per module, an entry-points table, and a flow page of Mermaid diagrams. The mechanical half – the scaffold, the theme, the run tooling – is templated and identical for every repo, while the per-module pages are written by a fanned-out subagent grounded in the real code.

The module's own source moved to harness/modules/wiki/ in the 2026-07-21 restructure, alongside every other harness-built module, and the harness's own generated output moved with it, from the old repo-root wiki-site/ to harness/wiki/. You run wiki on demand with /wiki, never from a hook, because a full pass reads a fair bit of the tree and spends real tokens doing it – a pair of hooks does watch for the site going stale, but they only nudge you to regenerate, they never invoke the skill themselves.

In Practice ​

Run it on the whole repo. From a session inside the repo you want documented:

/wiki

The overseer scopes the repo into modules, decides the name, hero text, tagline, and the What This Is paragraph, and writes the module list to a small nuon file of { id, title, blurb } records.

Scaffold the shell first. scripts/scaffold.nu gen writes every fixed file – package.json, the config with the sidebar built from the module list, the green theme, the home hero, the run and stop scripts – plus a stub per page, so the site builds clean before a single page is written:

nu .claude/skills/wiki/scripts/scaffold.nu gen --name <repo> --out <repo>/wiki --modules <modules.nuon> --text "<hero text>" --tagline "<tagline>" --about "<what this is>"

Prove the voice on one page before rolling out. The overseer writes, or hands a single wiki-page-writer call, one exemplar module page first, shows it, and only fans out to the rest once the style and depth are signed off. This is a named step in the procedure, not an afterthought: catching a voice or depth problem on one page is cheap, catching it after every module page is written means redoing all of them.

Fan a writer over each remaining module. Once the exemplar lands, the overseer spawns one wiki-page-writer per module, in parallel – one message, many agent calls. Each gets its module id and title, the exact output path <repo>/wiki/docs/modules/<id>.md, that module's own source files, and the two style references. Each writer reads only the module it was handed, writes its one page in the site's proper-prose voice, and returns a tight summary – the module, the file it wrote, the files it actually read, the sections, whether it added a diagram – never the page body itself. The overseer never re-reads what a writer produced except to spot-check it against the real code.

Write the cross-cutting pages by hand. The flow and entry-points pages need the whole-repo view, so the overseer writes those directly; the home page is already filled in by scaffold from the supplied strings.

Normalize, then build. scripts/normalize.nu sweeps every page for the finn-style punctuation the theme wants (em-dashes to spaced en-dashes, curly quotes to straight), and scripts/scaffold.nu build installs deps then runs the VitePress build – which link-checks every internal reference on the way through, so a clean build is itself the proof that nothing points at a page that doesn't exist:

nu .claude/skills/wiki/scripts/normalize.nu <repo>/wiki/docs
nu .claude/skills/wiki/scripts/scaffold.nu build --out <repo>/wiki

An example outcome. A clean build leaves a static site in <repo>/wiki/docs/.vitepress/dist, and you serve it three ways – double-click start-docs.cmd, run nu run.nu, or npm run dev – each landing on the pinned port, 5180 by default. The two run scripts step up to the next free port when another wiki already holds it, and print the port they took.

Mind the cost

A measured run on this repo came in at roughly 86k tokens per page, one wiki-page-writer fan-out per module, each reading its own module's real source before writing a word. That grounding is the point, not overhead to trim: no page here is a summary of a summary. It is also why regeneration stays a deliberate, scoped act instead of something wired to a hook or a schedule – harness/CLAUDE.md says explicitly not to auto-generate this site. The site is accurate the moment it is built, and starts going stale the moment the code it describes moves past it.

Templated vs Generated ​

The skill draws a hard line between what is mechanical and what is written. Everything with a fixed shape – the VitePress config, the theme, the home page skeleton, the run and stop scripts – lives in templates/ as token files that scaffold.nu stamps with the repo name and the pinned port. Everything that carries meaning – the module pages, the flow diagrams, the entry-points table – is generated from the real code, by the writer subagents for the modules and by the overseer for the cross-cutting pages.

The voice splits the same way. The skill's own files stay finn-style: ascii, tabs, lowercase headings. The pages it writes into the site use proper prose – real capitalization, en-dashes, straight quotes – a deliberate exception spelled out in references/style.md. normalize.nu enforces the mechanical half of that (em-dashes to spaced en-dashes, curly quotes to straight), but it can't fix voice or capitalization, so the writer has to get those right on its own.

Regenerating This Site ​

The skill writes into <repo>/wiki/ by convention, wherever --out points it for that run. That convention has a real wrinkle the moment the repo being documented is the harness itself. The module's source lives at harness/modules/wiki/, but the harness is itself a subtree of the outer claude repo this file sits in, and the harness's own site lives one level down at harness/wiki/, not at the outer repo's own wiki/. Scope a run to the outer repo and --out would land the scaffold at the wrong root entirely – not nested under harness/ where this site actually lives.

Regenerating the wiki you are reading right now means scoping the run to harness/ as the repo root, not to the repo it sits inside. That is the one case where "the repo" the skill maps is not obviously the top of whatever session you are in, and it is exactly the kind of thing that catches someone out on a repo shaped like this one, a harness nested inside a larger personal claude-tooling repo. .claude/wiki/wiki.nuon, read below, is what lets the hooks and the regen agree on that wrinkle instead of each guessing separately.

Staleness Hooks ​

A generated site is only true the moment it is built, and the code moves past it from the next commit on. Two hooks and a config file carry that job between them, and neither hook ever runs the skill itself – a full pass is too heavy, and per the cost above too expensive, to fire on its own. They only bank what changed and nudge the agent to regenerate at the right moment, which is the end of the session, not mid-session.

wiki-stale.nu ​

The Stop hook, doing two separate jobs. The first job never speaks and never blocks: every turn it reads the session transcript for files touched through Edit, Write, MultiEdit, or NotebookEdit, drops anything under the wiki's own output dir or under node_modules/, .git/, .claude/, archive/, dist/, build/, or .vitepress/, and banks the rest into .claude/wiki/pending.nuon as { rel, at, session } records. Staleness is tested per page rather than against one site-wide watermark – an entry is pruned once its own covering page (matched by stem against the entry's path segments, so modules/anti-slop/craft/STATES.md answers to docs/modules/anti-slop.md) has a newer mtime than the change itself. An entry no page claims, a repo-level doc like RECONCILE.md, answers instead to the oldest of the top-level pages (home, flow, entry-points), so it is never permanently unprunable. Where a match is ambiguous the hook errs toward keeping the entry: a false positive just costs a line in a list the agent judges anyway.

The second job is what actually blocks. It reads finn's last message, and only when that reads as him wrapping up (a handoff ask, "i think were done here", "lets wrap up", matched against a deliberately narrow list of phrases) and the ledger is non-empty does it block the stop, with one line pointing at wiki-recap.nu for the actual brief. The reason string is worded so it can never match its own wrap-up patterns – a blocked stop's reason lands back in the transcript as finn's next "last message," so a reason that itself reads like a session end would re-block every following turn forever. An earlier version of this hook did exactly that (2026-09-04) before the wording was constrained. stop_hook_active guards the same re-block loop from the platform side, and HARNESS_HOOKS_OFF guards a spawned-child loop, the same pair of guards the rest of the hooks pack uses.

wiki-recap.nu ​

The regen brief, printed only once greenlit. wiki-stale.nu used to hand the agent this whole brief the moment it read a wrap-up match, and a wrong guess dropped roughly thirty lines of regen instructions into a session that was still running, every turn until the ledger emptied. Now the brief is a separate script the agent runs by hand only after finn has actually confirmed the regen, never wired as a hook itself. It re-resolves the site path the same way wiki-stale.nu does, reads the same pending.nuon ledger, and prints the pending file list plus the actual instructions: which changes are page-worthy (a module added, renamed, or removed; what a module does; how it's run), hand each wiki-page-writer the pending files for its module plus a one-line summary of what changed and why, and regenerate through /wiki rather than hand-patching the markdown. An empty ledger prints a one-line all-clear instead of the brief.

inject-wiki-note.nu ​

The SessionStart primer – a single line dropped in at session start so the Stop-time block is not a cold surprise, silent unless a generated wiki is already present. It also reports whatever the Stop hook has already banked from earlier sessions, so the pending count is in context well before finn gets near wrapping up.

wiki.nuon ​

Where the site lives – .claude/wiki/wiki.nuon carries one key, parent, the directory containing the wiki/ folder, relative to the project root. Empty, the default, means <repo>/wiki/; this repo's own copy sets parent: "harness", because the harness is a repo nested inside the outer claude repo and its site lives at harness/wiki/ rather than the outer root. Both hooks and the SKILL.md procedure resolve the site path off this file before they scaffold or regenerate, and a value that doesn't resolve reads as absent rather than being guessed at – it falls back to the project root, it never guesses further. Before this file existed, both hooks were hard-gated on <repo>/wiki/docs existing rather than reading a config. From the 2026-07-21 restructure, when the harness's own site moved to harness/wiki/, until this config landed, that gate failed on line one of every fire in this very repo – the hooks were wired in settings.json the whole time and simply had nothing to say.

settings-fragment.json ​

The hook wiring – the two entries merged into a project's settings.json by harness settings --merge: SessionStart to inject-wiki-note.nu, Stop to wiki-stale.nu. wiki-recap.nu is not wired as a hook at all, it's run by hand once finn has greenlit the regen. Every script path is rooted at ${CLAUDE_PROJECT_DIR} rather than a relative path, because a hook runs with the session's cwd, not necessarily the project root, and a relative path stops resolving the moment the agent cds.

The Overseer ​

SKILL.md ​

The procedure – the ten-step overseer loop: scope the repo, write the modules spec, scaffold, sign off one exemplar page, fan out the writers, write the flow and entry-points pages, normalize, build and link-check, then serve and report. It also carries the fallbacks – node missing, a writer returning junk, a huge repo – so the run degrades cleanly.

README.md ​

The module map – what the site produces, how the templated and generated halves fit, and the pointer to harness/docs-site as the gold-standard output this reproduces and generalizes.

Commands ​

wiki.md ​

The /wiki entry point – a thin command that invokes the wiki skill and follows its procedure, on demand only and explicitly not wired to a hook.

Scripts ​

scaffold.nu ​

The engine – two subcommands. gen writes the fixed scaffold and a stub per page, seeding a stub only where none exists so a regeneration never clobbers written content; build installs deps if missing then runs the VitePress build, which doubles as the dead-link check, driving npm through node against npm-cli.js directly to dodge the npm .cmd shim misresolving under Nushell. gen also takes an optional --references list of atlas pages: passed one, it renders a Research sidebar section, stages each page into docs/public/atlas/, and scopes ignoreDeadLinks to /atlas/ so the build still fails loudly on any other broken link; passed none, the wiki is unchanged.

normalize.nu ​

The punctuation pass – sweeps every .md under the docs dir, collapses each em-dash to a spaced en-dash, and straightens curly quotes. It leaves line endings alone, deliberately – it used to force crlf, but the write is gated on the punctuation being dirty so a clean page never reached the conversion anyway, and crlf was dropped repo-wide on 2026-07-29. A --check flag reports offenders without rewriting.

References ​

style.md ​

The prose voice – the proper-prose rules for the generated pages: real sentences, proper nouns capitalized while the model tiers and the repo name stay lowercase, en-dashes not em-dashes, straight ascii quotes, and the anti-slop rule that every claim is grounded in the code.

page-shapes.md ​

The page skeletons – the fixed shape of each page type (module, flow, entry-points, home) with a worked module page, so the whole site reads as one thing.

The Writer ​

wiki-page-writer.md ​

The fan-out writer – a sonnet subagent, one spawned per module. It reads that module's real source and writes its one page to the exact path it was handed, in the site's voice, then returns a tight summary rather than the page body. It never scaffolds, builds, or writes the home, flow, or entry-points pages – that stays with the overseer and the scripts.

Templates ​

config.mts ​

The VitePress config – wraps the theme with withMermaid so mermaid fences render as diagrams, builds the nav and sidebar from the module list, turns on local search and a deep outline, and pins the dev server port, reading DOCS_PORT first so the run scripts can override it. That override has to be the env var: VitePress merges this vite block over the --port flag it takes on the command line, so the flag is silently ignored. strictPort then makes a bare npm run dev fail outright on a busy port rather than quietly drifting to the next one and serving a different site than the URL says. It registers the ahk.mts grammar below, and turns useMaxWidth off for each diagram type the pages use, which stops Mermaid shrinking a wide diagram down to the prose column and scaling its label text down with it.

custom.css ​

The theme tuning – a green accent over the default theme, roomier line spacing, and per-file ### headings styled as coloured labels. It also carries the diagram rules: a wide diagram holds its natural size and scrolls sideways instead of being squashed, a framed one reads as draggable, and the label line-height is pinned to the 1.5 Mermaid measures with, so the roomier prose spacing cannot spill a wrapped label out of the foreignObject that clips it.

ahk.mts ​

The AutoHotkey grammar – Shiki bundles around 300 language grammars and AutoHotkey is not one of them, so every ahk fence rendered as flat grey plain text until this existed. A hand-written TextMate grammar covering what the pages actually show: directives, hotkey and hotstring declarations, comments, strings, the control flow keywords, the A_ builtins, and function and class names. It is deliberately partial. AutoHotkey is the only gap in the stack, so a repo without any just carries an unused grammar.

theme-index.ts ​

The pan and zoom layer – the default theme plus the client wiring that makes a big diagram readable in place. Any diagram too wide for the prose column gets a bounded frame, dragged to pan and wheeled to zoom, opening at 1:1 so the text reads at the size Mermaid drew it, with a double click to put it back. It watches the DOM rather than hooking one lifecycle event, so a diagram redrawn by a route change or a dark/light flip is picked up and re-wired. The CSS above stands on its own if this never runs, so no JavaScript means a scrollable diagram rather than a broken one.

index.md ​

The home page – the hero, the feature cards, the What This Is paragraph, and the fixed staleness warning callout, all filled from the strings the overseer supplies.

run.nu / start-docs.cmd ​

The run tooling – start the VitePress dev server and open the site once the port is bound, paired with stop.nu / stop-docs.cmd to kill it. Both drive vitepress through node directly so they never trip on the npm shim. Each takes one netstat snapshot before starting and claims the first free port from the pinned one up, handing it to VitePress in DOCS_PORT and recording it in .docs-port, so a second wiki opens its own page instead of the first one, and the stop scripts kill the server this site actually started rather than whoever holds the pinned port.

Connects to ​

  • Context – when the repo already has a codebase map (from /map or codebase-map.nu), wiki reads it as its module primer, so a huge tree doesn't have to be surveyed from scratch.
  • Lecture (formerly chalk) – the sibling explainer, but at a different altitude: lecture teaches one file or system to a beginner, wiki turns the whole repo into a browsable site. Its LECTURES.md carries an empty wiki column, stubbed for cross-linking decks into a generated wiki when that work lands, and the green accent here is borrowed from its dark spirit.
  • Atlas – opt-in, one direction. Atlas's wiki-link.nu registers a rendered research page into a wiki and stages it into docs/public/atlas/; the next scaffold.nu gen run, passed --references, picks it up and adds the Research sidebar section above.