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: sharpen tagline, reframe layer positioning, lift dashboard (#335)

Raghav Chamadiya604d2429026e
diff --git a/README.md b/README.md
index 7c90d04c6..d9df4458c 100644
--- a/README.md
+++ b/README.md
@@ -2,7 +2,7 @@
<a href="https://www.repowise.dev"><img src=".github/assets/banner.png" alt="repowise — the codebase intelligence layer for your AI coding agent" width="100%" /></a>
-<p align="center"><em>The codebase intelligence layer for your AI coding agent.</em></p>
+<p align="center"><em>The intelligence layer that gives your AI agent context, ownership, decisions — and a code-health score proven to predict real bugs.</em></p>
<p align="center"><strong>Five intelligence layers · Nine MCP tools · 15 languages · Multi-repo workspaces · One <code>pip install</code></strong></p>
@@ -63,13 +63,13 @@ answer quality** ([benchmarks ↓](#benchmarks)).
repowise runs once, builds everything, then keeps it in sync on every commit.
Each layer is queryable from the CLI, the MCP tools, and the local dashboard.
-| Layer | What it gives you | Unique? |
+| Layer | What it gives you | Edge |
|---|---|---|
-| **◈ Graph** | tree-sitter dependency graph across 15 languages · two-tier file + symbol nodes · 3-tier call resolution · Leiden communities · PageRank / centrality / execution flows · framework-aware route→handler edges | Table stakes |
-| **◈ Git** | hotspots (churn × complexity) · ownership % · co-change pairs (hidden coupling) · bus factor · contributor profiles · module health · reviewer suggestions | Rare |
-| **◈ Docs** | LLM-generated wiki per module/file · incremental on every commit · freshness + confidence scoring · hybrid RAG search (FTS + vector via RRF) | Table stakes |
-| **◈ Decisions** | architectural decisions mined from **8 sources**, evidence-backed (verified / fuzzy / unverified), linked to graph nodes, connected by `supersedes`/`refines`/`conflicts_with` edges, tracked for staleness | **Nobody else** |
-| **★ Code Health** | **25 deterministic biomarkers**, 1–10 score per file · defect-calibrated weights · coverage ingestion · trend alerts · refactoring targets · **zero LLM, <30s** | **Our moat ↓** |
+| **◈ Graph** | tree-sitter dependency graph across 15 languages · two-tier file + symbol nodes · 3-tier call resolution · Leiden communities · PageRank / centrality / 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 · contributor profiles · module health · reviewer suggestions | Behavioral signals static analysis can't see |
+| **◈ Docs** | LLM-generated wiki per module/file · incremental on every commit · freshness + confidence scoring · hybrid RAG search (FTS + vector via RRF) | Stays current — rebuilt every commit |
+| **◈ Decisions** | architectural decisions mined from **8 sources**, evidence-backed (verified / fuzzy / unverified), linked to graph nodes, connected by `supersedes`/`refines`/`conflicts_with` edges, tracked for staleness | **★ Captured nowhere else** |
+| **★ Code Health** | **25 deterministic biomarkers**, 1–10 score per file · defect-calibrated weights · coverage ingestion · trend alerts · refactoring targets · **zero LLM, <30s** | **★ Defect-validated — our edge ↓** |
Full deep-dive on every layer (graph, git, docs, decisions, hooks, auto-sync,
dead code, CLAUDE.md generation): **[docs/INTELLIGENCE_LAYERS.md →](docs/INTELLIGENCE_LAYERS.md)**
@@ -78,8 +78,8 @@ dead code, CLAUDE.md generation): **[docs/INTELLIGENCE_LAYERS.md →](docs/INTEL
## ★ Code Health — the layer nobody else nails
-Graph and wiki layers now have competition. **Code health is where repowise is
-unique** — and we can prove it predicts real bugs.
+Code health is repowise's deepest differentiator — the one layer with no real
+equivalent, and **the only one we can prove predicts real bugs**.
repowise scores **every file 1–10** from **25 deterministic biomarkers** —
McCabe complexity, deep nesting, brain methods, class cohesion (LCOM4), god
@@ -161,6 +161,25 @@ Full report: **[health-defect/BENCHMARK_REPORT.md →](https://github.com/repowi
---
+## Local dashboard
+
+`repowise serve` starts a full web UI alongside the MCP server — no separate
+setup.
+
+<img src=".github/assets/webui.gif" alt="repowise web UI" width="100%" />
+
+Highlights: **Chat** (natural-language Q&A) · **Docs** (wiki with Mermaid +
+graph sidebar) · **Graph** (interactive, 2,000+ nodes, community coloring, path
+finder) · **C4 Architecture** (Context → Containers → Components) · **Risk**
+(hotspots, ownership heatmap, module health, dead code, blast radius) ·
+**Contributors** (per-author profiles) · **Decisions** (evidence drawer,
+evolution timeline, decision-graph) · **Health** (biomarker scores, coverage,
+trends) · **Security** (local pattern scan) · **Costs** · **Workspace**
+(cross-repo contracts & co-changes). Full view-by-view list in
+[docs/USER_GUIDE.md](docs/USER_GUIDE.md).
+
+---
+
## Supported languages
**15 languages parsed to AST · 9 at the Full tier · framework-aware across all of them.**
@@ -284,25 +303,6 @@ Worked example (*"Add rate limiting to all API endpoints"* in 5 calls instead of
---
-## Local dashboard
-
-`repowise serve` starts a full web UI alongside the MCP server — no separate
-setup.
-
-<img src=".github/assets/webui.gif" alt="repowise web UI" width="100%" />
-
-Highlights: **Chat** (natural-language Q&A) · **Docs** (wiki with Mermaid +
-graph sidebar) · **Graph** (interactive, 2,000+ nodes, community coloring, path
-finder) · **C4 Architecture** (Context → Containers → Components) · **Risk**
-(hotspots, ownership heatmap, module health, dead code, blast radius) ·
-**Contributors** (per-author profiles) · **Decisions** (evidence drawer,
-evolution timeline, decision-graph) · **Health** (biomarker scores, coverage,
-trends) · **Security** (local pattern scan) · **Costs** · **Workspace**
-(cross-repo contracts & co-changes). Full view-by-view list in
-[docs/USER_GUIDE.md](docs/USER_GUIDE.md).
-
----
-
## How it compares
| | repowise | Google Code Wiki | DeepWiki | Swimm | CodeScene |