Brain · Wiki
Map a repository back to its source
RepoOps generates a small markdown wiki from a targeted view of the repository. The Wiki tab renders its quickstart, checks cited files against the current tree, and can place related lessons, errors, and decisions beside the page.
For: a developer entering an unfamiliar repository, and the maintainer who owns its code map
What it does, and why it helps
Run npm run brain-wiki -- --init in the repository. RepoOps lists tracked files, reads a bounded set of package, readme, entrypoint, route, schema, and representative source excerpts, and sends that discovery bundle to the configured model. The initial run writes .claude/brain/wiki/quickstart.md, focused section pages, and .wiki-meta.json. It keeps at most eight pages. A section with fewer than 15 non-empty lines is folded into the quickstart instead of being left as a thin page.
The generator's prompt asks every substantive claim to cite a source file. The Wiki tab then checks those backticked paths against the current tree. It labels the page verified fresh, unverified, or no source refs, and gives each extracted claim a memory receipt with its source, page line, commit, timestamp, and status. The label verifies that a cited path resolves. It does not prove that the prose interpreted the file correctly, so follow the receipt before relying on a claim.
The pain. A new contributor has to infer the system from entrypoints, folders, and old notes. A hand-written overview can drift while the code changes.
The point of view. Treat generated documentation as a map, not an authority. Give every claim a route back to source, expose broken citations, and keep past decisions separate from the description of current code.
What gets easier. Starting an investigation. The quickstart links to denser topic pages, receipts name the cited files, and the Around this page rail can show lessons, errors, or decisions that mention those files.
When it helps. You inherit a repository, prepare an onboarding path, or need a compact architecture map before reading the implementation in depth.
Its limits. Generation reads a targeted sample, not the whole repository. A path-resolution badge checks the citation, not the meaning of the sentence. The live side rail is omitted when no experiential record intersects the cited files. The hosted dashboard only points to this local feature.
Understand it in 30 seconds
Read the narration
- 0:00 New teammates ask how the repository works, but the source keeps changing.
- 0:06 Generate a small wiki from the code, and make each claim point back to evidence.
- 0:13 Beside the generated text, RepoOps shows citation status and claim receipts.
- 0:18 Lessons and decisions that touch the same files sit alongside.
- 0:23 Read the map, then follow its citations before trusting the summary.
Synthetic example. Read the guide
Where to find it
Where to find it
- Desktop:
localhost:4000. It has no sidebar row: open it from the palette, or go straight to its address. - Hosted: desktop only.
- Keyboard: ⌘ K, then type “Wiki”.
When to use it
Cold-start an unfamiliar repository
Situation. The repository has source and configuration, but no Brain Wiki pages yet. The Wiki tab reads Nothing here yet and offers the brain-wiki command as the next action.
What you do. Configure a model key, run npm run brain-wiki -- --init, then open Wiki and start with quickstart.md.
What you see. The tab renders the quickstart and its section links. The page also shows a citation verdict and a receipt for each extracted source reference.
What it establishes. You have a bounded reading map under .claude/brain/wiki. The source receipts show where to check its claims.
Review a map after the code changes
Situation. Brain Health reports that the oldest page is beyond the configured commit or day threshold, or a page shows a rotten citation.
What you do. Run npm run brain-wiki -- --update and review the changed markdown and metadata before landing them. If there is no source diff, the command stops before key lookup or a model call.
What you see. The update reports the files it touched. On the next request, the Wiki tab checks the page citations against the current tree and shows any failing receipt in red and open.
What it establishes. You can judge the proposed description against the current files. A fresh stamp or resolving citation does not prove the prose is correct.
Before you start
- Supported versions
- RepoOps desktop v0.3.1, the release this guide was read against. The repository must be a git checkout for discovery, diff, and freshness measurements.
- Where it runs
- Local: Memory, then Brain library, which lists the wiki's architecture pages. The Wiki tab renders .claude/brain/wiki/quickstart.md for the selected repository. Hosted: pointer only for this local-scope leaf.
- Permissions
- Write access to .claude/brain/wiki and to AGENTS.md or CLAUDE.md when the reference block is wired. The generator also needs read access to the tracked repository files it selects.
- Connections
- A BYOK Anthropic API key, or all four OpenAI-compatible gateway settings. No key makes initialization refuse before writing anything.
- Plan
- Not provided. The generator and local Wiki tab have no product-plan gate in the shipped modules.
Configure it
- Choose the model connection.
Set ANTHROPIC_API_KEY for the default provider, or fill all four Wiki LLM fields for an OpenAI-compatible gateway. A partial gateway configuration is refused.
- Generate the first map.
Run npm run brain-wiki -- --init once. RepoOps builds all pages in memory first, then writes the wiki, so a model failure does not leave a partial set of pages.
- Read the receipts before the prose.
Open Wiki. A verified fresh chip means every extracted path resolved against HEAD. Open the receipts and inspect the cited source before adopting the explanation.
- Refresh through a reviewable landing path.
Run npm run brain-wiki -- --update yourself, keep the default held proposal, or opt into pull request landing. The working-copy setting writes directly and needs its own review discipline.
| Setting | Where | A sensible choice | Why it matters |
|---|---|---|---|
ANTHROPIC_API_KEY | Environment or the RepoOps data-directory .env written by Settings | Your own Anthropic API key | The default provider refuses generation when this key is absent. |
REPOOPS_WIKI_PROVIDER | Settings, Wiki LLM provider, or environment | Leave unset for Anthropic, or set openai-compatible | Selects the default Anthropic path or the gateway path. |
REPOOPS_WIKI_BASE_URL | Settings, Wiki LLM base URL, or environment | The gateway chat-completions base URL | Required with the OpenAI-compatible provider. |
REPOOPS_WIKI_API_KEY | Settings, Wiki LLM API key, or environment | The gateway key | Required with the OpenAI-compatible provider and sent as its bearer credential. |
REPOOPS_WIKI_MODEL | Settings, Wiki LLM model, or environment | A model id accepted by the configured gateway | Required for the gateway. The default Anthropic path uses claude-opus-4-8 unless --model overrides it. |
REPOOPS_WIKI_STALENESS_COMMITS | Environment | 500 when unset | A page is stale only when it is more than this many commits behind HEAD. |
REPOOPS_WIKI_STALENESS_DAYS | Environment | 14 when unset | A page is stale only when its generated timestamp is older than this many days. |
REPOOPS_WIKI_REFRESH_LANDING | Environment | Leave unset for a held proposal; pr and working-copy are opt-ins | Controls where a stale nightly refresh request lands. Pull request landing can spend the configured key and open a remote pull request. |
What you should see
A cited quickstart and focused pages
Configuration. A valid model connection, followed by npm run brain-wiki -- --init.
Expect. Up to eight markdown pages under .claude/brain/wiki plus .wiki-meta.json. quickstart.md is always first, and thin sections are merged into it.
Verify. Open Wiki, follow its section links, then inspect the verdict and memory receipts. A page with no extracted file references reads no source refs rather than verified.
A bounded diff update
Configuration. An existing wiki with .wiki-meta.json, then npm run brain-wiki -- --update after source changes.
Expect. The updater makes one model call and limits the pages it can rewrite. An unchanged source diff makes zero model calls. If review finds no page edit is needed, only the verified metadata stamp can move.
Verify. Review the reported paths and the repository diff before landing it. Then re-open Wiki and inspect the receipts against the new HEAD.
Data and cost
- What is captured
- Tracked file names, package metadata, README text, entrypoints, route and schema hints, one representative source file per top-level domain, generated markdown, and metadata containing generated time, git head, model, snapshot hash, and page stamps. The discovery bundle is capped at 100000 characters.
- Who can see it
- The generated files stay in the repository working tree until you commit or share them. Anyone with local access to the tracked repository can read them. The local tab also reads local lessons, errors, and decisions to build the Around this page rail.
- How long it is kept
- Not provided. The generator writes repository files and has no time-based pruning or retention control.
- What leaves the machine
- The targeted discovery bundle leaves the machine for the configured model provider during initialization or a changed-source update. Paths matching environment files, key files, secret stores, and credential names are excluded. A no-change update makes no model call.
- What it costs
- Your provider account pays for the calls. Initialization makes one planning call and one writing call per planned page, with at most eight pages. A changed-source update makes one call. RepoOps does not set a currency amount in this module.
When the result differs
| Symptom | Likely cause | Next action |
|---|---|---|
| The Wiki tab says Nothing here yet. | The selected repository has no .claude/brain/wiki/quickstart.md. | Configure a model key and run npm run brain-wiki -- --init in that repository. |
| Initialization says no Anthropic key and writes nothing. | ANTHROPIC_API_KEY is absent, and a complete OpenAI-compatible provider was not configured. | Add the Anthropic key or fill provider, base URL, API key, and model for the gateway, then run the command again. |
| Initialization refuses because pages already exist. | The --init command is a one-shot cold start. | Use npm run brain-wiki -- --update. Review and remove an existing wiki yourself only if you intend to replace it. |
| The page reads unverified or shows a failing receipt. | At least one extracted source path no longer resolves against the working tree. | Open the failing receipt, inspect the source change, run an update, and review the rewritten claim before landing it. |
| The Around this page rail is absent. | No active lesson, dated error, or decision intersects the page's cited files. The inline renderer does not load recall neighbors or cost. | Treat the empty rail as no matching experiential context, not as an error. Use the API fusion route when recall neighbors are needed. |
- Disable
- Not provided. There is no wiki-specific disable switch. Generation is one-shot; leaving refresh landing unset keeps stale refreshes held as proposals.
- Roll back
- Not provided. The wiki is stored in repository files; use your version-control workflow to restore an earlier revision.
- Revoke access
- Remove ANTHROPIC_API_KEY or the OpenAI-compatible gateway key from Settings or the environment. This stops future model-backed generation but does not remove existing pages.
- Delete
- Not provided. No shipped command deletes the wiki, its metadata, or the wired agent reference block.
Related tasks
Maintenance evidence
- Feature id
wiki(spine leafwiki)- Owner
- Brain Wiki, OpenWiki gap closure; Guide: LDG-0717
- Supported product version
- RepoOps v0.3.1
- Last verified
- 2026-09-15, read against origin/main at 52366bb6d; labels read from the served tab source; dynamic tab resolution and empty state checked in the renderer
- Example fixtures
- scripts/brain-wiki.test.mjs; lib/wiki-verify.test.mjs; lib/wiki-fusion.test.mjs; lib/brain-wiki-staleness.test.mjs; lib/brain-cron.wiki-refresh.test.mjs; lib/brain-cron.wiki-pr-landing.test.mjs
- Source references
lib/canonical-spine.json,lib/canonical-tabs.mjs,lib/zero-states.mjs,lib/md-renderer.mjs,lib/routes/mirror-files.mjs,scripts/brain-wiki.mjs,lib/wiki-verify.mjs,lib/wiki-fusion.mjs,lib/brain-wiki-staleness.mjs,lib/brain/wiki-refresh-proposal.mjs,.env.example,public/settings.html- Documentation review
- Independent review requested on the slice pull request; not yet recorded.
- Video review
- Narrated story rendered and published 2026-09-26 (render 7f13a254910e, LDG-1012) with the breadcrumb Memory, checked against main at b0bb02812. Six frames, the captions and the transcript were reviewed by the authoring agent, not an independent reviewer; the audio was not listened to by a person. Narration is the provisional Windows voice until LDG-0721.
Last updated