Auto-generated wiki

The wiki is repowise's documentation layer. Every page is rendered from your code's structure. On top of that, when a provider is configured, an LLM writes the prose for the subsystem (concept) pages and the repo overview: the layer that explains how the codebase fits together above the file level. Those model-written pages cite the source ranges they're describing, get a confidence score, and are regenerated only when the underlying code changes meaningfully. File pages are structural and never model-written.

Incremental update flow#

What gets written#

The model writes the subsystem layer, the pages where prose earns its keep:

• Subsystem (concept) pages: a derived, numbered tree above the file level. Each page describes a coherent part of the system, what it covers and what it deliberately does not, and how it relates to its siblings.
• Repo overview and the onboarding collection: the top-level narrative entry points into the wiki.

Everything below that is rendered from structure, with no model and no key: one file page per source file (documenting structure, key symbols, imports, and intent), plus symbol, API, infra, layer and cycle (SCC) pages. See the Deterministic wiki for the full page set.

Pick a wiki style to change the voice without re-indexing: comprehensive (full narrative, the default), reference (signature-dense, minimal prose), tutorial (guided, beginner-facing), or caveman (token-condensed, AI-first fragments, ~70% smaller).

Docs that follow your questions#

The page budget isn't spread evenly. repowise reads which modules you and your agent actually ask about, from get_answer citations and search_codebase hits, and tilts the file-page budget toward the modules in demand, so depth lands where you work instead of spreading flat. The total is conserved, every module keeps a floor, and a fresh repo with no session history generates byte-identically to before. It's one half of how repowise learns from how you use it; the other is session-mined decisions.

What goes into the prompt#

The LLM doesn't just see source. It sees:

• The file's parsed structure (classes, functions, signatures).
• Its imports and what imports it.
• Its top callers and callees with confidence scores.
• The 10 most significant commit messages from its history (filtered of merges, dependency bumps, lint runs).
• Ownership and trend signals.
• Cross-references to existing wiki pages it should link to.

That's the recipe for documentation that explains why, not just what.

Citations#

Every page references the source ranges it's describing. The MCP get_context tool can pull the cited source back when the agent needs to verify.

Confidence and freshness#

Each page carries a confidence_score and a freshness_status. The score reflects how well the underlying source maps to what the page claims. Pages drift over time as code changes; freshness is how recently the page was regenerated relative to the file's last meaningful change. Both surface through get_context(include=["freshness"]), and they're included by default for exactly this reason.

Incremental regeneration#

repowise update finds the files changed since the last sync, walks the dependency graph to find affected wiki pages, and regenerates only those. A typical single-commit update touches 3 to 10 pages and finishes in under 30 seconds.

There's a cascade-budget knob that caps how many pages a single update may regenerate (auto-scaled if unset), useful for very large refactor commits where you'd otherwise regenerate hundreds of pages.

Search#

The wiki is indexed two ways and searched as hybrid RAG:

• SQLite FTS: exact keyword search.
• LanceDB vector store: semantic search via embeddings (Gemini, OpenAI, OpenRouter, or Ollama). Auto-detected from your environment; it falls back to mock, meaning no semantic search, when no embedding key is found.

Results from both are merged via Reciprocal Rank Fusion, biased by PageRank, and expanded one hop along the dependency graph before ranking. Both feed search_codebase and get_answer.

When no model is in the loop#

This page describes the subsystem prose. It is optional: the rest of the wiki is rendered from the parsed AST, the dependency graph, and git history whether or not a model runs, and without a provider the subsystem pages are left as structural stubs.

repowise init never requires an API key. Without one it renders the structural wiki and exits 0. You can ask for it directly with --no-prose, which is what free-tier, CI, and air-gapped runs want.

What you give up is the subsystem prose, the paragraphs that explain why a part of the system is shaped the way it is, plus semantic search until an embedder is configured. Everything else, your file pages, hotspots, ownership, dead code, the dependency graph, code health, and decision archaeology, is identical.

Upgrading is in place and incremental: repowise generate writes the subsystem pages with a model, repowise update --full does the whole wiki at once. Neither re-indexes from scratch. Full detail in Deterministic wiki.