| name | wiki-build |
| version | 0.2.0 |
| description | Generate a code-grounded corpus (docs/wiki) for a codebase — per-concept MD notes pinned to the current commit, interlinked and indexed, passing the freshness gate. Use when the user wants a grounding wiki, a queryable knowledge base for a repo, or says "build a wiki for this codebase" / "ground this repo". |
wiki-build — generate a grounding wiki from a codebase
Produces a grounded corpus (see docs/corpus-spec.md in the praxisflux repo; the plugin's
templates/note.md is the note shape) at docs/wiki/ in the target repo: one note per
concept/component, each pinned to the commit it was verified against and listing the source
files whose change invalidates it.
Precondition gate
- The target must be a git repo with a clean-enough tree to pin: run
git rev-parse HEAD — this hash is the pin for every note written in this pass.
- If
docs/wiki/INDEX.md already exists, STOP: this is an update job — use the
wiki-update skill instead.
Work
- Survey the codebase (README, entry points, package layout) and draft the note list:
one note per concept — components, pipelines, cross-cutting patterns, config. Typical
repo: 15–25 notes. Write
INDEX.md first (grouped one-liners; it doubles as your plan).
- Write an
overview note yourself — the system's shape, data planes, entry points.
- Write the remaining notes (parallel subagents are fine for >10 notes; group by
subsystem). For every note:
- READ the actual source before writing; the code is ground truth, not docs or comments.
- Follow
templates/note.md: frontmatter name/description/kind/sources:/
verified_against: <the pin>, then Title / How it works / Connections / Operational notes.
- Neutral, factual tone. File paths + symbol names, never line numbers. Short verbatim
snippets only where load-bearing. 40–90 lines.
[[links]] only to notes on the list.
sources: lists every file whose change should invalidate the note — no more, no less.- Token budgets (corpus-spec v2):
description: is the note's capsule — ≤500 chars,
written for routing (what the note covers, when to load it), never a teaser. The body
stays ≤8,000 chars; at the cap split summary-style into child notes (parent keeps a
one-paragraph summary + [[wikilink]] per child) — but never split a child under
~1,500 chars of substance; an unsplittable over-cap note gets
size_budget_exempt: <reason> in its frontmatter instead.
- Generate the capsule rollup —
CAPSULES.md is part of every build pass:
node ${CLAUDE_PLUGIN_ROOT}/scripts/capsules.mjs <repo-root> docs/wiki. It is derived
state (never hand-edit it), and its presence turns the freshness gate's budget checks
from warnings into failures — that is the point.
Output gate
Run node ${CLAUDE_PLUGIN_ROOT}/gates/cli.mjs freshness <repo-root> docs/wiki — must exit 0
(all notes pinned + fresh, all [[links]] resolving, capsules and bodies within the v2
budgets, CAPSULES.md current; warnings are yours to judge).
Handing off
Tell the user what's now possible: ask grounded questions against the wiki, keep it honest
with wiki-update when code changes, wire the gate into CI/hooks as a pre-merge check, or
consume it downstream (courses, lessons, MCP ingestion). Don't do those here.
