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: lead with the numbers, restore the five-layer table, fix serve ports (#961)

Raghav Chamadiyab5658f7de124
diff --git a/README.md b/README.md
index fcbc936ad..471e4a381 100644
--- a/README.md
+++ b/README.md
@@ -26,12 +26,13 @@
<p align="center"><sub>
<a href="#your-agent-stops-guessing">For your agent</a> ·
+ <a href="#what-one-index-actually-builds">The five layers</a> ·
<a href="#stop-paying-for-output-nobody-reads">Distill</a> ·
<a href="#know-whats-dangerous-before-you-merge">Change risk</a> ·
<a href="#-know-exactly-what-to-fix">Code health</a> ·
<a href="#see-all-of-it">Dashboard</a> ·
<a href="#past-one-repo">Workspaces</a> ·
- <a href="#quickstart">Quickstart</a> ·
+ <a href="#quickstart-under-5-minutes-no-api-key">Quickstart</a> ·
<a href="#the-ten-mcp-tools">MCP tools</a> ·
<a href="#how-it-compares">Comparison</a> ·
<a href="#for-teams--enterprises">Teams</a>
@@ -41,7 +42,10 @@
### Your AI agent burns most of its budget rediscovering your codebase. Index it once, and it never has to again.
-<sub>Free and self-hosted, runs on your machine, and the first index needs no API key.</sub>
+### up to −96% tokens to load context&nbsp;&nbsp;·&nbsp;&nbsp;−89% file reads&nbsp;&nbsp;·&nbsp;&nbsp;−70% tool calls
+
+<sub>Paired runs, same model, same harness, with and without repowise ([the numbers, and what they do not show →](docs/BENCHMARKS.md)).<br />
+Free and self-hosted, runs on your machine, and the first index needs no API key.</sub>
<picture>
<source media="(prefers-color-scheme: dark)" srcset=".github/assets/one-index-dark.svg" />
@@ -73,18 +77,10 @@ built around **tasks**: pass several targets in one call, get complete context b
<img src=".github/assets/demo.gif" alt="Claude Code querying the codebase through repowise's MCP tools" width="100%" />
-Because the exploration work is already done, that phase mostly disappears:
-
-<div align="center">
-
-**up to −96% tokens to load context&nbsp;&nbsp;·&nbsp;&nbsp;−89% file reads&nbsp;&nbsp;·&nbsp;&nbsp;−70% tool calls**
-
-</div>
-
-Loading one commit's context through `get_context` costs **2,391 tokens instead of
-64,039** raw. On a long multi-step investigation that compounds to **−41% of the
-context re-read across the whole session**. Paired runs, same model, same harness,
-with and without repowise ([the numbers, and what they do not show →](docs/BENCHMARKS.md)).
+Because the exploration work is already done, that phase mostly disappears. Loading
+one commit's context through `get_context` costs **2,391 tokens instead of 64,039**
+raw. On a long multi-step investigation that compounds to **−41% of the context
+re-read across the whole session**.
**And it arrives without being asked.** Optional [hooks](docs/agent/HOOKS.md) push
context into the session at the moment it matters: the governing architectural
@@ -101,6 +97,28 @@ local, all deterministic, no extra LLM calls.
---
+## What one index actually builds
+
+Five layers, built in a single pass and kept in sync on every commit. Each one is
+queryable from the CLI, the MCP tools, and the local dashboard.
+
+| Layer | What it gives you | Edge |
+|---|---|---|
+| **◈ Graph** | Dependency graph across 16 languages · file + symbol nodes · 3-tier call resolution · Leiden communities · PageRank and execution flows · framework-aware route→handler edges | A real graph most tools never build |
+| **◈ Git** | Hotspots (churn × complexity) · ownership % · co-change pairs (hidden coupling) · bus factor · which files actually get bug-fixed, and how recently | Behavioural signals static analysis cannot see |
+| **◈ Docs** | A generated wiki page per module and file · rebuilt incrementally every commit · freshness and confidence scoring · hybrid search (full-text + vector) · selectable style and output language | Stays current instead of rotting |
+| **◈ Decisions** | Architectural decisions mined from eight sources, evidence-backed, linked to the graph nodes they govern, connected by supersedes / refines / conflicts_with, tracked for staleness | **★ Captured nowhere else** |
+| **★ Code health** | **25 deterministic markers**, 1 to 10 per file · three signals: defect risk · maintainability · performance · coverage ingestion · concrete refactoring plans (Extract Class / Helper, Move Method, Break Cycle, Split File) · **zero LLM, under 30s** | **★ Defect-validated, with the fix attached** |
+
+Only the Docs layer needs an LLM. `repowise init --index-only` builds the graph,
+git, decision, and health layers with no API key and no spend (seven of the eight
+decision sources are deterministic; only the one harvested during doc generation
+needs a provider).
+
+Full detail on every layer: **[docs/layers/INTELLIGENCE_LAYERS.md →](docs/layers/INTELLIGENCE_LAYERS.md)**
+
+---
+
## Stop paying for output nobody reads
Most of what an agent reads back from a shell command is noise: 300 lines of passing
diff --git a/docs/BENCHMARKS.md b/docs/BENCHMARKS.md
index eef695706..92fa8b35d 100644
--- a/docs/BENCHMARKS.md
+++ b/docs/BENCHMARKS.md
@@ -163,8 +163,9 @@ correlated with strictly no leakage: nothing after T0 feeds the score.
### Cross-project validation
-Across **21 open-source repositories spanning all 9 Full-tier languages** and
-2,826 files:
+Across **21 open-source repositories spanning 9 languages** and 2,826 files
+(the study predates the promotion of Scala and Ruby to the Full tier, so it
+covers 9 of today's 11):
- **Mean ROC AUC 0.74** (95% CI 0.68 to 0.79) at identifying the files that go
on to receive bug fixes, reaching **0.90** on individual repos. ROC AUC is the
diff --git a/docs/start/DASHBOARD.md b/docs/start/DASHBOARD.md
index 91d0b550e..05dbeba1f 100644
--- a/docs/start/DASHBOARD.md
+++ b/docs/start/DASHBOARD.md
@@ -1,15 +1,20 @@
# The dashboard
-`repowise serve` starts a local web app on `http://localhost:7777` that reads
-the same `.repowise/wiki.db` the CLI and MCP server read. Nothing leaves your
-machine, and no view calls an LLM unless you click something that says it will
-(Chat, refactoring code generation, doc regeneration).
+`repowise serve` starts the API on `http://localhost:7337` and the local web
+dashboard on `http://localhost:3000`. Both read the same `.repowise/wiki.db`
+the CLI and MCP server read. Nothing leaves your machine, and no view calls an
+LLM unless you click something that says it will (Chat, refactoring code
+generation, doc regeneration).
```bash
-repowise serve # http://localhost:7777
-repowise serve --port 8080
+repowise serve # API on :7337, dashboard on :3000
+repowise serve --port 8080 # move the API
+repowise serve --ui-port 3001 # move the dashboard
+repowise serve --no-ui # API only
```
+The dashboard needs Node >= 20. Without it, `serve` falls back to API-only.
+
The URL shape is `/repos/<repo-id>/<view>`. Every view is directly linkable,
including tab state, so a link you paste in a PR lands on exactly what you were
looking at.