Skip to content

Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.

docs: give the documentation layer its own reference and fold wiki styles into it (#1493)

Raghav Chamadiya8af86c9eea20
diff --git a/docs/README.md b/docs/README.md
index f659052e3..50a073a44 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -58,7 +58,7 @@ your agent in under five minutes, with no API key.
| [layers/DECISIONS.md](layers/DECISIONS.md) | Architectural decisions mined from your repo and from your own agent sessions |
| [layers/DEAD_CODE.md](layers/DEAD_CODE.md) | Unreachable files, unused exports, and zombie packages by confidence tier |
| [layers/LANGUAGE_SUPPORT.md](layers/LANGUAGE_SUPPORT.md) | What works per language, across 18 parsed languages and 13 at the Full tier |
-| [layers/WIKI_STYLES.md](layers/WIKI_STYLES.md) | Selectable documentation styles (comprehensive / reference / tutorial / caveman) |
+| [layers/WIKI.md](layers/WIKI.md) | The generated wiki: page types, what `update` re-renders, styles, output language |
## Scale it
diff --git a/docs/layers/INTELLIGENCE_LAYERS.md b/docs/layers/INTELLIGENCE_LAYERS.md
index 134adcd02..43e02398a 100644
--- a/docs/layers/INTELLIGENCE_LAYERS.md
+++ b/docs/layers/INTELLIGENCE_LAYERS.md
@@ -121,6 +121,8 @@ upgrades the prose rather than enabling the layer.
A typical single-commit update regenerates only the handful of pages your change
actually touched.
+Reference: [`WIKI.md`](WIKI.md).
+
---
## Decision Intelligence
diff --git a/docs/layers/WIKI.md b/docs/layers/WIKI.md
new file mode 100644
index 000000000..57c9a3ce5
--- /dev/null
+++ b/docs/layers/WIKI.md
@@ -0,0 +1,280 @@
+# The Wiki
+
+Repowise builds a wiki for your repository at index time: a page per source
+file, per selected public symbol, per subsystem, per dependency cycle, per
+infrastructure file and per API surface, plus a repository overview and an
+onboarding collection. It is refreshed incrementally on every commit, and it is
+what `get_answer`, `search_codebase`, the CLI and the local dashboard read from.
+
+Almost all of it is rendered from your code's structure with no model in the
+loop. A provider key adds prose to the subsystem layer and the top-level
+narrative pages. It does not switch the layer on: a repository indexed with no
+key gets a complete wiki, not a placeholder.
+
+## Quick start
+
+```bash
+repowise init # builds the wiki as part of indexing
+repowise init --no-prose # keyless and free, guaranteed no spend
+repowise update # re-renders only what your commits touched
+repowise generate # fill in the subsystem prose later
+repowise restyle reference # re-render every page in a different voice
+repowise serve # browse it at localhost:3000
+repowise export --format markdown # write it out as files
+```
+
+## What gets generated
+
+Pages are produced in ordered levels, most local first, so a page that quotes
+another is generated after it.
+
+| Level | Page type | One per | Written by |
+|-------|-----------|---------|------------|
+| 0 | `api_contract` | file classified as an API surface | structure |
+| 1 | `symbol_spotlight` | selected public symbol | structure |
+| 2 | `file_page` | eligible source file | structure |
+| 3 | `scc_page` | dependency cycle | structure |
+| 4 | `module_page` | subsystem in the concept tree | model, structure when keyless |
+| 6 | `repo_overview` | repository | model, structure when keyless |
+| 6 | `architecture_diagram` | repository | model, structure when keyless |
+| 7 | `infra_page` | infrastructure file (Dockerfile, CI, IaC) | structure |
+| 8 | `onboarding` | slot | model, structure when keyless |
+
+The onboarding slots are Project Overview, Getting Started, Key Concepts, How It
+Works, Active Landscape and Glossary. Project Overview is not generated
+separately, the repository overview is tagged into that slot, and Glossary is
+rendered from mined terms with no model in every run, keyed or not.
+
+`layer_page` was retired. Layers stopped being pages and became grouping rows in
+the docs tree, built from provenance stamped on their members. An inbound link
+to a retired layer page lands on the repository overview.
+
+## Which pages exist
+
+There is no page budget to spend by default. Every page type below the concept
+tree is rendered from structure and costs no tokens, and the concept partition
+is a total cover of the production files that would stop being a map of the
+repository if it were rationed. So each bucket takes every candidate that clears
+its eligibility floor.
+
+The one exception is opt-in and owner-chosen. `max_file_pages` bounds the file
+bucket, highest importance first, for repositories large enough that the tail
+costs more in bytes and retrieval noise than it pays back. Unset lets a size
+policy decide, `0` means one page per eligible file however many that is, and a
+positive value is a hard cap. It does not reduce model spend, because file pages
+are rendered from structure either way.
+
+Selection does not fork on whether a key is present, and that is the point: a
+keyed and a keyless index of the same commit agree about which files have pages
+at all.
+
+## What a model writes
+
+Four page types are model-written when a provider is configured: `module_page`,
+`repo_overview`, `architecture_diagram` and `onboarding`. That is the layer
+where prose earns its keep, the one that explains how the codebase fits together
+above the file level. Everything else is rendered from the parse, the import
+graph and git history, and no model ever sees it.
+
+A model-written page is not prompted with raw source. It is prompted with
+assembled material: parsed structure and signatures, what the subject imports
+and what imports it, ownership and churn signals, the significant commits from
+its history with merges, dependency bumps and lint-only commits filtered out,
+and cross-references to the pages it should link to. That is the recipe for a
+page that explains *why* rather than restating *what*.
+
+### Keyless runs
+
+`repowise init` never requires a key. Without one it renders the whole wiki from
+structure and exits 0. Ask for it explicitly with `--no-prose`, which is what
+free-tier, CI and air-gapped runs want.
+
+What you give up is the subsystem prose, and semantic search until an embedder is
+configured. Full-text and symbol search work either way. File pages, symbol
+pages, hotspots, ownership, dead code, the dependency graph, code health and
+decision archaeology are identical.
+
+### Two facts on every page
+
+Worth keeping apart, because collapsing them is the mistake this layer has
+already made once:
+
+- **`provider_name`** answers *has a model written this page yet*. It is what
+ the docs tree's "not written yet" marker and the reader's upgrade affordance
+ read.
+- **`confidence`** answers *how far should a reader trust the statements*. A
+ structure-rendered page is `1.0`, because everything on it was extracted
+ rather than summarised. A model-written page is `0.8`: grounded in the
+ assembled material and checked against it, but a summary of the code rather
+ than an extraction from it. Nothing gates on the difference, it is reported.
+
+The axis is trust, not completeness. A page can be thin and still be entirely
+true. The only `0.3` left is a page that was meant to carry prose and lost it to
+a provider outage, which is the one state a reader cannot infer from the page
+itself. A keyless run produces `1.0` pages throughout, because an index built
+without a key is that shape by design.
+
+## Adding prose later
+
+Upgrading is in place and incremental. Neither command re-indexes: the graph and
+git metadata are rehydrated from SQL, and only the per-file parse and the
+generation you asked for run.
+
+```bash
+repowise generate # every subsystem page still unwritten
+repowise generate --path src/api # under a path prefix or glob
+repowise generate --stale # pages whose code changed since writing
+repowise generate --all # rewrite the prose everywhere
+repowise update --full # the whole wiki at once
+```
+
+`generate` writes the model-written pages and only those. Naming a structural
+page with `--page` is an actionable error rather than a silent LLM re-render,
+because those pages refresh on `repowise update` for free. Run it bare on a
+terminal and it prints the wiki's state, defaults to the unwritten pages, and
+ends at the normal cost confirmation.
+
+## What `update` re-renders
+
+`repowise update` does not rebuild the wiki. It finds the files changed since
+the last sync, walks the dependency graph for the pages those changes affect,
+and re-renders only those, typically a handful per commit.
+
+Two mechanisms decide what is stale:
+
+- **Model-written pages** compare a hash of the rendered prompt against the
+ stored one. Same prompt and same model means the prior page is reused
+ verbatim, with no tokens spent.
+- **Structure-rendered pages** fold the subject's own hash together with a
+ fingerprint of the renderer: the template source, the resolved style and the
+ output language. Nothing else refreshes these pages, and no model will ever
+ come along and fix them, so comparing the stored key against a freshly
+ computed one is what turns a released template change into exactly one
+ regeneration.
+
+That second mechanism is why shipping a template edit shows up as a one-time
+re-render of every page of that type. It is the intended behaviour, not drift.
+
+`--cascade-budget N` caps how many pages a single update may regenerate from
+cascading changes. It is adaptive when unset, which is what you want except on a
+very large refactor commit.
+
+Pages also carry a freshness status of `fresh`, `stale`, `expired` or `unknown`.
+Expiry by age takes priority, then a source-hash mismatch marks a page stale.
+
+## Styles
+
+A **style** controls the voice and density of the prose without changing the
+structural markdown. Headings and sections stay the same, so search, the table
+of contents and cross-links keep working across a style change.
+
+| Style | Best for | What it reads like |
+|-------|----------|--------------------|
+| `comprehensive` | The default. Humans and AI. | Full, narrative documentation. |
+| `caveman` | AI agents, token budgets. | Token-condensed fragments, ~70% smaller. |
+| `reference` | Library consumers. | API-manual: signature-dense, minimal narrative. |
+| `tutorial` | New contributors. | Guided, beginner-friendly walkthroughs. |
+
+List the available styles and the repo's current one:
+
+```bash
+repowise wiki-styles
+```
+
+### Choosing and switching
+
+At init (full mode), pick a style with a flag or the interactive prompt:
+
+```bash
+repowise init --wiki-style caveman
+```
+
+The choice is saved to `.repowise/config.yaml` as `wiki_style:`, so `update`
+keeps regenerated pages in the same style.
+
+Switching re-renders every page in the new voice. Use the dedicated command: it
+reuses the existing index and git data, so nothing is re-resolved or re-blamed.
+
+```bash
+repowise restyle reference
+```
+
+In the web app, **Settings → Documentation style** does the same, and an
+individual page can be regenerated in a one-off style from its **Regenerate**
+control.
+
+> Editing `wiki_style` in `config.yaml` by hand and running `repowise update`
+> will **not** regenerate existing pages, that path only re-scores health. Use
+> `repowise restyle` to apply a style change.
+
+### Custom styles
+
+Define your own under `.repowise/styles/<name>/style.yaml`:
+
+```yaml
+# .repowise/styles/terse/style.yaml
+description: Ultra-terse internal style
+onboarding_condenses: true # also condense the onboarding pages
+style_version: 1 # bump when you edit this file to force regen
+system_note: |
+ Write for senior engineers who know the domain. Be extremely concise.
+user_directive: |
+ Write in TERSE style.
+ - Keep every required ## heading; bodies are short fragments.
+ - No filler, no restating the heading, no closing summary.
+ - Keep code identifiers and paths verbatim.
+```
+
+Then apply it:
+
+```bash
+repowise restyle terse
+```
+
+A style may also ship per-page-type Jinja templates in
+`.repowise/styles/<name>/templates/`, using the same filenames as the built-ins
+(`file_page.j2` and so on). They override the built-in template for the page
+types you supply; anything you leave out falls back to the default.
+
+Guard rails: style names must match `[a-z0-9][a-z0-9_-]*`, directive and note
+text are length-bounded, and a style with neither a directive nor a note is
+ignored. Built-in style names always take precedence over a custom directory of
+the same name.
+
+## Output language
+
+`language` in `.repowise/config.yaml`, or `init --language <code>`, sets the
+natural language of the wiki. It reaches both the model-written prose and the
+headings and fixed sentences of the structure-rendered pages, for the languages
+that have a label catalog. A supported language without one keeps English
+headings on those pages while the model-written prose is still translated, and
+an unknown code falls back to English with a warning.
+
+Code, file paths and symbol names are never translated, in any language.
+
+Changing the language later does not retranslate existing pages. Re-run
+`init --force --language <code>` to rebuild the wiki in the new language.
+
+## Where the wiki shows up
+
+- **Agents**: `get_answer` retrieves and quotes from it, `search_codebase` ranks
+ it, `get_context` pulls the page for a file or symbol. Hybrid retrieval merges
+ SQLite full-text and vector results through Reciprocal Rank Fusion, biased by
+ PageRank, then expands one to two hops along the imports and projected-calls
+ graph for flow-shaped questions. Full-text works with no embedder; semantic
+ search needs one configured.
+- **CLI**: `repowise ask`, `repowise search`, `repowise context`.
+- **Dashboard**: `repowise serve`, then the Docs tab.
+- **Files**: `repowise export --format markdown|html|json`, written to
+ `.repowise/export` by default.
+
+## Related
+
+- [`INTELLIGENCE_LAYERS.md`](INTELLIGENCE_LAYERS.md) for how this layer sits
+ next to graph, git, decisions and code health.
+- [`CONFIG.md`](../reference/CONFIG.md) for `wiki_style`, `language`,
+ `max_file_pages` and the rest of the generation settings.
+- [`CLI_REFERENCE.md`](../reference/CLI_REFERENCE.md) for `init`, `update`,
+ `generate`, `restyle`, `wiki-styles` and `export` in full.
+- [`AUTO_SYNC.md`](../scale/AUTO_SYNC.md) for keeping the wiki fresh
+ automatically on every commit.
diff --git a/docs/layers/WIKI_STYLES.md b/docs/layers/WIKI_STYLES.md
deleted file mode 100644
index 725368588..000000000
--- a/docs/layers/WIKI_STYLES.md
+++ /dev/null
@@ -1,84 +0,0 @@
-# Wiki styles
-
-Repowise generates wiki pages in a configurable **style** that controls the
-*voice and density* of the prose, without changing the structural markdown
-(headings and sections stay the same, so search, the table of contents, and
-cross-links keep working).
-
-## Built-in styles
-
-| Style | Best for | What it reads like |
-|-------|----------|--------------------|
-| `comprehensive` | The default. Humans and AI. | Full, narrative documentation. |
-| `caveman` | AI agents, token budgets. | Token-condensed fragments, ~70% smaller. |
-| `reference` | Library consumers. | API-manual: signature-dense, minimal narrative. |
-| `tutorial` | New contributors. | Guided, beginner-friendly walkthroughs. |
-
-List the available styles (and the repo's current one):
-
-```bash
-repowise wiki-styles
-```
-
-## Choosing a style
-
-At init (full mode), pick a style with a flag or the interactive prompt:
-
-```bash
-repowise init --wiki-style caveman
-```
-
-The choice is saved to `.repowise/config.yaml` (`wiki_style:`), so `repowise
-update` keeps regenerated pages in the same style.
-
-## Switching styles
-
-Switching regenerates every page in the new voice. Use the dedicated command —
-it reuses the existing index and git data, so no re-resolution or re-blame is
-needed:
-
-```bash
-repowise restyle reference
-```
-
-In the web app, the repo **Settings → Documentation style** selector does the
-same: it saves the style and offers to regenerate the wiki. Individual pages can
-also be regenerated in a one-off style from the page's **Regenerate** control.
-
-> Note: editing `wiki_style` in `config.yaml` by hand and running `repowise
-> update` will **not** regenerate existing pages (that path only re-scores
-> health). Use `repowise restyle` to apply a style change.
-
-## Custom styles (power users)
-
-Define your own style under `.repowise/styles/<name>/style.yaml`:
-
-```yaml
-# .repowise/styles/terse/style.yaml
-description: Ultra-terse internal style
-onboarding_condenses: true # also condense the onboarding pages
-style_version: 1 # bump when you edit this file to force regen
-system_note: |
- Write for senior engineers who know the domain. Be extremely concise.
-user_directive: |
- Write in TERSE style.
- - Keep every required ## heading; bodies are short fragments.
- - No filler, no restating the heading, no closing summary.
- - Keep code identifiers and paths verbatim.
-```
-
-Then apply it:
-
-```bash
-repowise restyle terse
-```
-
-Optionally ship per-page-type Jinja templates in
-`.repowise/styles/<name>/templates/` (same filenames as the built-in templates,
-e.g. `file_page.j2`). They override the built-ins for the page types you supply;
-anything you don't provide falls back to the default template.
-
-Guard rails: style names must match `[a-z0-9][a-z0-9_-]*`; directive and note
-text are length-bounded; a style with neither a directive nor a note is ignored.
-Built-in style names always take precedence over a custom directory of the same
-name.
diff --git a/docs/reference/CLI_REFERENCE.md b/docs/reference/CLI_REFERENCE.md
index c6e47b4a7..063d1c37c 100644
--- a/docs/reference/CLI_REFERENCE.md
+++ b/docs/reference/CLI_REFERENCE.md
@@ -148,7 +148,7 @@ All three reach the indexing knobs; the LLM-only knobs appear only when model-wr
| `--provider` | LLM provider: `anthropic`, `openai`, `openrouter`, `gemini`, `deepseek`, `kimi`, `ollama`, `litellm`, `codex_cli`, `opencode`, `mock` |
| `--model` | Model name override (e.g., `claude-sonnet-4-6`) |
| `--embedder` | Embedder for semantic search: `gemini`, `openai`, `openrouter`, `ollama`, `mock` (default: auto-detect) |
-| `--prose` / `--no-prose` | The single knob over LLM spend. The file, symbol, layer and cycle (SCC), API and infra pages are rendered from structure either way, with no key and no cost. The model-written set is the subsystem (concept) tree plus the repo overview, the architecture diagram, and the onboarding collection: `--prose` writes those as model prose and needs a key; `--no-prose` leaves them as structural stubs, so the whole wiki is keyless and free. Default: prose when a key is available. Full-text search works either way; semantic search needs an embedder. Fill or refill that prose later with [`repowise generate`](#repowise-generate-path). |
+| `--prose` / `--no-prose` | The single knob over LLM spend. The file, symbol, cycle (SCC), API and infra pages are rendered from structure either way, with no key and no cost. The model-written set is the subsystem (concept) tree plus the repo overview, the architecture diagram, and the onboarding collection: `--prose` writes those as model prose and needs a key; `--no-prose` leaves them as structural stubs, so the whole wiki is keyless and free. Default: prose when a key is available. Full-text search works either way; semantic search needs an embedder. Fill or refill that prose later with [`repowise generate`](#repowise-generate-path). |
| `--index-only` | Deprecated hidden alias for `--no-prose`. |
| `--docs` | Deprecated hidden alias: `--docs llm` == `--prose`, `--docs deterministic` == `--no-prose`. Prefer `--prose` / `--no-prose`. |
| `--mode` | Pipeline depth: `standard` (default) or `fast` (graph + essential-git only, no per-file blame/co-change, no LLM docs, for very large repos; upgrade later with `update --full`) |
@@ -162,7 +162,7 @@ All three reach the indexing knobs; the LLM-only knobs appear only when model-wr
| `--coverage-report` | Test-coverage report to ingest (LCOV / Cobertura / Clover). Repeatable. Auto-discovered when omitted. This is test coverage for code-health, not a documentation-breadth knob: every code file is documented either way. |
| `--onboarding` / `--no-onboarding` | Generate the curated Onboarding collection (up to 8 overview pages). Default: on; slots without enough signal are skipped. |
| `--harvest-decisions` / `--no-harvest-decisions` | Harvest architectural decisions during page generation (verified against source before storage). Default: on. |
-| `--wiki-style` | Documentation voice/density: `comprehensive` (default), `caveman` (token-condensed, AI-first), `reference` (API-manual), `tutorial` (beginner-friendly). Interactive full runs prompt when omitted. Saved to config so `update` keeps the style. See [WIKI_STYLES.md](../layers/WIKI_STYLES.md). |
+| `--wiki-style` | Documentation voice/density: `comprehensive` (default), `caveman` (token-condensed, AI-first), `reference` (API-manual), `tutorial` (beginner-friendly). Interactive full runs prompt when omitted. Saved to config so `update` keeps the style. See [WIKI.md](../layers/WIKI.md#styles). |
| `--language` | Output language for generated wiki pages: `en` (default), `ar`, `de`, `es`, `fr`, `hi`, `it`, `ja`, `ko`, `nl`, `pl`, `pt`, `ru`, `tr`, `zh`. Code, file paths, and symbol names stay untranslated. Saved to config so `update` keeps the language. Also asked in advanced interactive mode. To switch an existing wiki's language, set the flag and re-run `init --force`. |
| `--resume` | Continue a previous run instead of redoing it: completed phases (indexing, analysis) are skipped, the earlier run's git tier is kept, and generation writes only the pages this repo does not have yet. Use it after an interrupted run, and after one that finished with failed pages (a provider outage, rate limiting) — pages already written are skipped with no model call, so nothing is paid for twice. Matching is per page, not per model, so switching provider still keeps what the old one wrote. |
| `--force` | Regenerate all pages even if they exist |
@@ -297,7 +297,7 @@ is an actionable error naming the key-setup path.
`generate` writes the model-written pages, and only those: the numbered concept
tree above the file level plus the repo overview, the architecture diagram, and
the onboarding collection. Every structural page (file, symbol, API, infra,
-cycle, layer) is rendered from structure and refreshes on `repowise update`, so
+cycle) is rendered from structure and refreshes on `repowise update`, so
naming one with `--page` is an actionable error rather than a silent LLM
re-render.
@@ -378,7 +378,7 @@ With no `STYLE`, prints the current style and the available choices.
Styles only differ in voice and density; the markdown structure (headings,
sections) stays the same, so search, the table of contents, and cross-links keep
-working. See [WIKI_STYLES.md](../layers/WIKI_STYLES.md).
+working. See [WIKI.md](../layers/WIKI.md#styles).
**Options:**
diff --git a/docs/reference/CONFIG.md b/docs/reference/CONFIG.md
index 27a57a51e..3d6e10db5 100644
--- a/docs/reference/CONFIG.md
+++ b/docs/reference/CONFIG.md
@@ -243,7 +243,7 @@ the partial page instead of saving it.
`wiki_style` controls the voice and density of generated wiki pages. Set it with
`init --wiki-style` or switch later with `repowise restyle <style>` (which also
regenerates the wiki). Power users can define their own style under
-`.repowise/styles/<name>/style.yaml`. Full guide: [WIKI_STYLES.md](../layers/WIKI_STYLES.md).
+`.repowise/styles/<name>/style.yaml`. Full guide: [WIKI.md](../layers/WIKI.md#styles).
Note: hand-editing `wiki_style` here and running `update` does not regenerate
existing pages, use `restyle`.
diff --git a/docs/start/USER_GUIDE.md b/docs/start/USER_GUIDE.md
index aee317398..e858ad925 100644
--- a/docs/start/USER_GUIDE.md
+++ b/docs/start/USER_GUIDE.md
@@ -197,7 +197,7 @@ Grouped by what you are trying to do. Every flag for every command lives in the
| Command | What it is for |
|---|---|
| `repowise reindex` | Rebuild the vector store from existing pages (embedding calls only, no LLM). |
-| `repowise restyle` | Re-render the wiki in a different [style](../layers/WIKI_STYLES.md). |
+| `repowise restyle` | Re-render the wiki in a different [style](../layers/WIKI.md#styles). |
| `repowise export` | Export the wiki, for static hosting or archival. |
| `repowise costs` | What indexing has cost you, by provider and operation. |
| `repowise generate-claude-md` | Regenerate `CLAUDE.md` / `AGENTS.md` on demand. |