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.

chore: add GitHub Pages docs site and deploy workflow

RaghavChamadiyaf31cccf67b2b
diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
new file mode 100644
index 000000000..a497b2431
--- /dev/null
+++ b/.github/workflows/docs.yml
@@ -0,0 +1,58 @@
+name: Deploy docs to GitHub Pages
+
+on:
+ push:
+ branches:
+ - main
+ paths:
+ - "website/**"
+ workflow_dispatch:
+
+permissions:
+ contents: read
+ pages: write
+ id-token: write
+
+concurrency:
+ group: "pages"
+ cancel-in-progress: false
+
+jobs:
+ build:
+ runs-on: ubuntu-latest
+ steps:
+ - name: Checkout
+ uses: actions/checkout@v4
+
+ - name: Setup Ruby
+ uses: ruby/setup-ruby@v1
+ with:
+ ruby-version: "3.3"
+ bundler-cache: true
+ working-directory: website
+
+ - name: Setup Pages
+ id: pages
+ uses: actions/configure-pages@v5
+
+ - name: Build with Jekyll
+ working-directory: website
+ run: bundle exec jekyll build --baseurl "${{ steps.pages.outputs.base_path }}"
+ env:
+ JEKYLL_ENV: production
+
+ - name: Upload artifact
+ uses: actions/upload-pages-artifact@v3
+ with:
+ path: website/_site
+
+ deploy:
+ environment:
+ name: github-pages
+ url: ${{ steps.deployment.outputs.page_url }}
+ runs-on: ubuntu-latest
+ needs: build
+ steps:
+ - name: Deploy to GitHub Pages
+ id: deployment
+ uses: actions/deploy-pages@v4
diff --git a/website/Gemfile b/website/Gemfile
new file mode 100644
index 000000000..e6bffb6fc
--- /dev/null
+++ b/website/Gemfile
@@ -0,0 +1,6 @@
+source "https://rubygems.org"
+
+gem "jekyll", "~> 4.3"
+gem "just-the-docs", "~> 0.10"
+gem "jekyll-seo-tag"
+gem "jekyll-github-metadata"
diff --git a/website/_config.yml b/website/_config.yml
new file mode 100644
index 000000000..8ad9c8510
--- /dev/null
+++ b/website/_config.yml
@@ -0,0 +1,79 @@
+title: repowise
+description: Codebase intelligence for developers and AI.
+baseurl: ""
+url: "https://repowise-dev.github.io"
+
+theme: just-the-docs
+
+logo: "/assets/images/logo.png"
+
+# Aux links for the upper right navigation
+aux_links:
+ "GitHub":
+ - "https://github.com/repowise-dev/repowise"
+ "PyPI":
+ - "https://pypi.org/project/repowise/"
+
+aux_links_new_tab: true
+
+# Footer content
+footer_content: "Copyright &copy; 2025 repowise. Distributed under the <a href=\"https://github.com/repowise-dev/repowise/blob/main/LICENSE\">AGPL-3.0 License</a>."
+
+# Color scheme
+color_scheme: dark
+
+# Enable search
+search_enabled: true
+search:
+ heading_level: 2
+ previews: 2
+ preview_words_before: 3
+ preview_words_after: 3
+ tokenizer_separator: /[\s/]+/
+ rel_url: true
+ button: false
+
+# Navigation
+nav_sort: order
+
+# Callouts
+callouts_level: quiet
+callouts:
+ highlight:
+ color: yellow
+ important:
+ title: Important
+ color: blue
+ new:
+ title: New
+ color: green
+ note:
+ title: Note
+ color: purple
+ warning:
+ title: Warning
+ color: red
+
+# Back to top button
+back_to_top: true
+back_to_top_text: "Back to top"
+
+# Last edit timestamp
+last_edit_timestamp: true
+last_edit_time_format: "%b %e %Y at %I:%M %p"
+
+# Heading anchors
+heading_anchors: true
+
+# Plugins
+plugins:
+ - jekyll-seo-tag
+ - jekyll-github-metadata
+
+# Exclude from processing
+exclude:
+ - "*.gemspec"
+ - "Gemfile"
+ - "Gemfile.lock"
+ - "node_modules"
+ - "vendor"
diff --git a/website/claude-code-plugin.md b/website/claude-code-plugin.md
new file mode 100644
index 000000000..2590d0a1f
--- /dev/null
+++ b/website/claude-code-plugin.md
@@ -0,0 +1,153 @@
+---
+layout: default
+title: Claude Code Plugin
+nav_order: 8
+---
+
+# Claude Code Plugin
+{: .no_toc }
+
+The fastest way to get repowise — Claude handles everything.
+{: .fs-6 .fw-300 }
+
+---
+
+## Table of contents
+{: .no_toc .text-delta }
+
+1. TOC
+{:toc}
+
+---
+
+## Overview
+
+The Claude Code plugin integrates repowise directly into Claude Code. It handles installation, API key setup, MCP server registration, and teaches Claude to use repowise tools proactively — without manual configuration.
+
+---
+
+## Installation
+
+Open Claude Code and run:
+
+```
+/plugin marketplace add repowise-dev/repowise-plugin
+/plugin install repowise@repowise
+```
+
+That's the entire installation. The plugin:
+
+- Installs `repowise` via pip if not already installed
+- Registers the MCP server with Claude Code
+- Loads the slash commands
+- Configures Claude to use repowise tools automatically
+
+---
+
+## Slash commands
+
+### `/repowise:init`
+
+Interactive setup and indexing for the current repository.
+
+Claude will guide you through:
+
+1. **Mode selection** — choose between:
+ - **Full** — complete wiki generation with LLM docs (requires API key)
+ - **Index-only** — graph + git + dead code, no LLM (free)
+ - **Advanced** — manual control over provider, concurrency, exclude patterns
+
+2. **Provider selection** — Anthropic, OpenAI, Gemini, or local Ollama
+
+3. **API key entry** — saved to `.repowise/.env` (gitignored)
+
+4. **Indexing** — runs in the background with live progress updates
+
+When done, Claude confirms the MCP server is active and the codebase is queryable.
+
+---
+
+### `/repowise:status`
+
+Show the current state of the repowise index.
+
+Output includes:
+- Last sync commit and timestamp
+- Total pages, symbols, decisions indexed
+- Provider and model in use
+- Pages marked stale (need regeneration)
+- MCP server connection status
+
+---
+
+### `/repowise:update`
+
+Incrementally sync the wiki after code changes.
+
+Claude detects which files have changed since the last indexed commit, regenerates only the affected pages, updates CLAUDE.md, and confirms when done.
+
+---
+
+### `/repowise:search`
+
+Search the indexed wiki from within Claude Code.
+
+Claude will ask for your query and search mode (fulltext, semantic, or symbol), then display results inline with links to relevant pages.
+
+---
+
+### `/repowise:reindex`
+
+Rebuild the vector search index without making LLM calls.
+
+Use this after switching embedding providers, or if semantic search results seem off.
+
+---
+
+## Automatic behaviors
+
+Beyond the slash commands, the plugin teaches Claude skills it uses automatically — without being asked.
+
+### Codebase exploration
+
+Before reading raw source files, Claude calls:
+
+- `get_overview()` at the start of new tasks to orient itself
+- `search_codebase(query)` to locate code instead of using grep
+- `get_context(targets)` to get docs and ownership before opening files
+
+### Pre-modification checks
+
+Before editing any file, Claude calls `get_risk(targets)` to assess:
+
+- Whether the file is a hotspot (high churn)
+- How many other files depend on it
+- Whether there are co-change patterns to be aware of
+
+If the risk is high, Claude surfaces this before making changes.
+
+### Architectural decision queries
+
+When facing "why is this structured this way" questions, Claude calls `get_why(query)` to check decision records and git archaeology before suggesting changes that might conflict with existing decisions.
+
+### Dead code awareness
+
+During refactoring or cleanup tasks, Claude calls `get_dead_code()` to find confirmed unused code rather than guessing.
+
+---
+
+## How skills work
+
+Skills in Claude Code are prompt instructions that modify Claude's behavior. The repowise plugin registers four skills that Claude loads when working in an indexed repo.
+
+You don't need to trigger them manually. When Claude detects it's working in a repo with a connected repowise MCP server, the skills activate automatically.
+
+The CLAUDE.md generator reinforces these skills by writing the mandatory MCP tool workflow directly into your project's context file — so even without the plugin, any Claude session that reads your CLAUDE.md will follow the same workflow.
+
+---
+
+## Requirements
+
+- Claude Code (desktop app, CLI, or IDE extension)
+- Python 3.11+
+- An LLM API key (for full mode — not needed for index-only)
diff --git a/website/claude-md-generator.md b/website/claude-md-generator.md
new file mode 100644
index 000000000..67059ffbd
--- /dev/null
+++ b/website/claude-md-generator.md
@@ -0,0 +1,149 @@
+---
+layout: default
+title: CLAUDE.md Generator
+nav_order: 7
+---
+
+# CLAUDE.md Generator
+{: .no_toc }
+
+How repowise keeps Claude Code informed about your codebase automatically.
+{: .fs-6 .fw-300 }
+
+---
+
+## Table of contents
+{: .no_toc .text-delta }
+
+1. TOC
+{:toc}
+
+---
+
+## What it is
+
+Claude Code reads `.claude/CLAUDE.md` at startup to understand the project it's working in. repowise generates this file from your indexed codebase — filling it with architecture summaries, hotspot warnings, module maps, MCP tool instructions, and codebase conventions.
+
+The result is a Claude that understands your repo's structure, knows which files are risky to edit, and uses the right tools before making changes.
+
+---
+
+## How it's generated
+
+The generator runs at the end of `repowise init` and `repowise update`, or on demand:
+
+```bash
+repowise generate-claude-md
+```
+
+It queries the already-indexed database — **no LLM calls are made**. All content comes from data collected during ingestion and analysis.
+
+What goes into the generated content:
+
+| Section | Source |
+|---------|--------|
+| Architecture summary | Repository-level wiki page (4 sentences max) |
+| Key modules | Top modules by PageRank with purpose and owner |
+| Entry points | Detected `main.py`, `__main__`, CLI entry files |
+| Tech stack | Languages, frameworks, databases, infra |
+| Hotspots | Top 5 high-churn files with percentile rank |
+| MCP tool instructions | Mandatory usage table for all 8 tools |
+| Codebase conventions | Active architectural decisions + build commands |
+
+---
+
+## Two-section design
+
+The file is split into two sections with clear markers:
+
+```markdown
+# CLAUDE.md
+
+<!-- Add your custom instructions here. repowise will never
+ modify anything outside the markers below. -->
+<!-- Examples: coding style, test commands, constraints -->
+
+Your custom content goes here and is never touched.
+
+<!-- REPOWISE:START — Do not edit below this line. Auto-generated by repowise. -->
+
+## IMPORTANT: Codebase Intelligence Instructions for my-repo
+
+> **CRITICAL**: This repository is indexed by repowise.
+> You MUST use the repowise MCP tools below instead of reading raw source files.
+
+... auto-generated content ...
+
+<!-- REPOWISE:END -->
+```
+
+**Your section (above the markers):** Add anything you want — coding style rules, test commands, workflow preferences, constraints. repowise never touches this.
+
+**repowise section (between markers):** Fully auto-generated. Updated on every `repowise update` run. Never edit this manually — changes will be overwritten.
+
+---
+
+## Merge behavior
+
+The generator handles three cases:
+
+| Scenario | Behavior |
+|---------|----------|
+| No existing file | Creates file with empty user section + repowise section |
+| File without markers | Appends repowise section at the bottom, preserves all existing content |
+| File with markers | Replaces only the content between markers, preserves everything outside |
+
+Updates are written atomically via a temp file — if something goes wrong mid-write, the original file is not corrupted.
+
+---
+
+## What Claude does with it
+
+When Claude Code opens your project, it reads CLAUDE.md and sees:
+
+1. **The MCP tool instructions** — a mandatory workflow table telling Claude to call `get_overview()` first, `get_context()` before reading files, `get_risk()` before edits, etc.
+
+2. **The hotspot warning** — a table of high-churn files with their percentile ranks and owners, so Claude knows which files need extra care.
+
+3. **The architecture summary** — enough context to understand the repo without reading every file.
+
+4. **Codebase conventions** — active architectural decisions that should be respected.
+
+This is why Claude Code performs better on indexed repos — it has the same mental model a senior engineer would have after a few weeks on the project.
+
+---
+
+## Auto-sync on commits
+
+If you're using `repowise watch`, CLAUDE.md is updated automatically whenever indexed files change.
+
+For manual sync after coding sessions:
+
+```bash
+repowise update # Updates wiki + regenerates CLAUDE.md
+repowise generate-claude-md # Regenerates CLAUDE.md only (faster)
+```
+
+In Claude Code, run `/repowise:update` to trigger an update from within your editor.
+
+---
+
+## Opting out
+
+To skip CLAUDE.md generation entirely during `init`:
+
+```bash
+repowise init --no-claude-md
+```
+
+To generate the content without writing a file (for inspection):
+
+```bash
+repowise generate-claude-md --stdout
+```
+
+To write to a custom path:
+
+```bash
+repowise generate-claude-md --output ./my-custom-context.md
+```
diff --git a/website/cli-reference.md b/website/cli-reference.md
new file mode 100644
index 000000000..8d2f6759c
--- /dev/null
+++ b/website/cli-reference.md
@@ -0,0 +1,430 @@
+---
+layout: default
+title: CLI Reference
+nav_order: 4
+---
+
+# CLI Reference
+{: .no_toc }
+
+Every command, flag, and option.
+{: .fs-6 .fw-300 }
+
+---
+
+## Table of contents
+{: .no_toc .text-delta }
+
+1. TOC
+{:toc}
+
+---
+
+## Global
+
+```bash
+repowise --version # Print version
+repowise --help # Show help
+repowise COMMAND --help # Help for a specific command
+```
+
+Most commands accept an optional `PATH` argument — the root of the repository to operate on. If omitted, the current directory is used.
+
+---
+
+## `init`
+
+Generate the full wiki for a codebase. Runs all four layers: ingestion, analysis, generation, persistence.
+
+```bash
+repowise init [PATH] [OPTIONS]
+```
+
+### Options
+
+| Flag | Type | Default | Description |
+|------|------|---------|-------------|
+| `--provider` | string | auto | LLM provider: `anthropic`, `openai`, `gemini`, `ollama`, `litellm`, `mock` |
+| `--model` | string | — | Model override (e.g., `claude-sonnet-4-6`, `gpt-4.1`) |
+| `--embedder` | choice | auto | Embedding provider: `gemini`, `openai`, `mock` |
+| `--index-only` | flag | false | Skip LLM generation — parse, graph, git, dead code only |
+| `--dry-run` | flag | false | Show generation plan and token estimate without running |
+| `--test-run` | flag | false | Limit to top 10 files by PageRank (for validation) |
+| `--skip-tests` | flag | false | Exclude test files |
+| `--skip-infra` | flag | false | Exclude Dockerfiles, Makefiles, Terraform, shell scripts |
+| `--exclude` / `-x` | string | — | Gitignore-style exclude pattern (repeatable: `-x vendor/ -x "*.gen.*"`) |
+| `--concurrency` | int | 5 | Max concurrent LLM calls |
+| `--resume` | flag | false | Resume from last checkpoint after an interruption |
+| `--force` | flag | false | Regenerate all pages even if up to date |
+| `--commit-limit` | int | 500 | Max commits per file for git analysis (max 5000, saved to config) |
+| `--follow-renames` | flag | false | Track file renames in git history (saved to config) |
+| `--no-claude-md` | flag | false | Skip generating `.claude/CLAUDE.md` |
+| `--yes` / `-y` | flag | false | Skip the cost confirmation prompt |
+
+### Examples
+
+```bash
+# Interactive setup (recommended for first run)
+repowise init
+
+# Non-interactive, specific provider
+repowise init --provider anthropic --yes
+
+# Analysis only — free, no API key needed
+repowise init --index-only
+
+# Skip tests and infra, limit concurrency
+repowise init --skip-tests --skip-infra --concurrency 3
+
+# Exclude generated files and vendor directories
+repowise init -x "*.generated.ts" -x vendor/ -x proto/
+
+# Dry run to estimate cost before committing
+repowise init --dry-run
+
+# Resume an interrupted run
+repowise init --resume
+```
+
+### What it does
+
+1. **Ingestion** — parses all files with tree-sitter, builds dependency graph
+2. **Analysis** — git churn/ownership, dead code detection, decision mining
+3. **Generation** — LLM writes wiki pages at repo/module/file level (skipped with `--index-only`)
+4. **Persistence** — writes to SQLite, builds vector index, generates `.claude/CLAUDE.md`
+
+### Provider auto-detection
+
+If `--provider` is not specified, repowise checks in order:
+1. `REPOWISE_PROVIDER` environment variable
+2. `.repowise/config.yaml` from a previous run
+3. API key environment variables: `ANTHROPIC_API_KEY` → `OPENAI_API_KEY` → `OLLAMA_BASE_URL` → `GEMINI_API_KEY`
+
+---
+
+## `update`
+
+Incrementally sync the wiki after code changes. Diffs against the last indexed commit, regenerates only affected pages.
+
+```bash
+repowise update [PATH] [OPTIONS]
+```
+
+### Options
+
+| Flag | Type | Default | Description |
+|------|------|---------|-------------|
+| `--provider` | string | — | Override LLM provider |
+| `--model` | string | — | Override model |
+| `--since` | string | — | Git ref to diff from (overrides saved `state.json`) |
+| `--cascade-budget` | int | auto | Max pages to regenerate from cascading changes |
+| `--dry-run` | flag | false | Show affected pages without regenerating |
+
+### Examples
+
+```bash
+repowise update # Sync since last indexed commit
+repowise update --since HEAD~10 # Re-sync last 10 commits
+repowise update --dry-run # Preview what would change
+repowise update --cascade-budget 20 # Limit cascade regeneration
+```
+
+---
+
+## `watch`
+
+Auto-update wiki on file saves. Watches for filesystem changes and debounces rapid saves.
+
+```bash
+repowise watch [PATH] [OPTIONS]
+```
+
+### Options
+
+| Flag | Type | Default | Description |
+|------|------|---------|-------------|
+| `--provider` | string | — | Override LLM provider |
+| `--model` | string | — | Override model |
+| `--debounce` | int | 2000 | Debounce delay in milliseconds |
+
+### Example
+
+```bash
+repowise watch --debounce 3000 # Wait 3 seconds after last save before updating
+```
+
+---
+
+## `mcp`
+
+Start the MCP server for AI editor integration.
+
+```bash
+repowise mcp [PATH] [OPTIONS]
+```
+
+### Options
+
+| Flag | Type | Default | Description |
+|------|------|---------|-------------|
+| `--transport` | choice | stdio | `stdio` (for editors) or `sse` (for web clients) |
+| `--port` | int | 7338 | Port for SSE transport |
+
+### Examples
+
+```bash
+repowise mcp # stdio (Claude Code, Cursor, Cline)
+repowise mcp --transport sse --port 7338 # SSE for web clients
+```
+
+See [MCP Server →](mcp-server) for editor-specific configuration.
+
+---
+
+## `serve`
+
+Start the API server and web dashboard.
+
+```bash
+repowise serve [PATH] [OPTIONS]
+```
+
+### Options
+
+| Flag | Type | Default | Description |
+|------|------|---------|-------------|
+| `--port` | int | 7337 | API server port |
+| `--host` | string | 127.0.0.1 | Host to bind |
+| `--workers` | int | 1 | Number of uvicorn workers |
+| `--ui-port` | int | 3000 | Web UI port |
+| `--no-ui` | flag | false | Start API only, skip web UI |
+
+### Examples
+
+```bash
+repowise serve # API on :7337, UI on :3000
+repowise serve --no-ui # API only
+repowise serve --host 0.0.0.0 # Expose on network
+repowise serve --port 8080 --ui-port 4000 # Custom ports
+```
+
+See [Web Dashboard →](web-dashboard) for what you can do from the UI.
+
+---
+
+## `search`
+
+Full-text, semantic, or symbol search across the indexed wiki.
+
+```bash
+repowise search <QUERY> [PATH] [OPTIONS]
+```
+
+### Options
+
+| Flag | Type | Default | Description |
+|------|------|---------|-------------|
+| `--mode` | choice | fulltext | `fulltext`, `semantic`, or `symbol` |
+| `--limit` | int | 10 | Max results |
+
+### Examples
+
+```bash
+repowise search "authentication flow"
+repowise search "rate limiting" --mode semantic
+repowise search "AuthService" --mode symbol
+repowise search "database connection" --limit 20
+```
+
+---
+
+## `reindex`
+
+Rebuild the vector search index from existing wiki pages. Does not make LLM calls.
+
+```bash
+repowise reindex [PATH] [OPTIONS]
+```
+
+### Options
+
+| Flag | Type | Default | Description |
+|------|------|---------|-------------|
+| `--embedder` | choice | auto | `gemini`, `openai`, or `auto` |
+| `--batch-size` | int | 20 | Pages per embedding batch |
+
+Use this after switching embedding providers, or if the LanceDB index is corrupted.
+
+---
+
+## `status`
+
+Show the current sync state, page counts, and provider info.
+
+```bash
+repowise status [PATH]
+```
+
+Output includes:
+- Last indexed commit and timestamp
+- Total pages, symbols, and decisions
+- Provider and model in use
+- Total tokens consumed
+- Index freshness (pages marked stale)
+
+---
+
+## `doctor`
+
+Run health checks on the wiki setup.
+
+```bash
+repowise doctor [PATH]
+```
+
+Checks:
+- Database connectivity and schema version
+- Vector store consistency (pages without embeddings)
+- Stale pages that need regeneration
+- Missing or broken `.mcp.json` config
+- API key availability for configured provider
+
+---
+
+## `dead-code`
+
+Detect and report unused code in the indexed codebase.
+
+```bash
+repowise dead-code [PATH] [OPTIONS]
+```
+
+### Options
+
+| Flag | Type | Default | Description |
+|------|------|---------|-------------|
+| `--min-confidence` | float | 0.4 | Minimum confidence threshold (0.0–1.0) |
+| `--safe-only` | flag | false | Only show findings marked `safe_to_delete` |
+| `--kind` | choice | — | Filter by type: `unreachable_file`, `unused_export`, `unused_internal`, `zombie_package` |
+| `--format` | choice | table | Output format: `table`, `json`, or `md` |
+
+### Examples
+
+```bash
+repowise dead-code # All findings, table format
+repowise dead-code --safe-only # Only confirmed safe to delete
+repowise dead-code --kind unused_export # Only unused exports
+repowise dead-code --format json # Machine-readable output
+repowise dead-code --min-confidence 0.8 # High confidence only
+```
+
+---
+
+## `decision`
+
+Manage architectural decision records (ADRs).
+
+```bash
+repowise decision SUBCOMMAND [OPTIONS]
+```
+
+### Subcommands
+
+| Subcommand | Description |
+|-----------|-------------|
+| `add` | Interactively add a new decision |
+| `list [PATH]` | List all decisions |
+| `show <ID>` | Display full decision details |
+| `confirm <ID>` | Mark a proposed decision as active |
+| `dismiss <ID>` | Delete a proposed decision |
+| `deprecate <ID>` | Mark a decision as deprecated |
+| `health [PATH]` | Show decision health metrics |
+
+### `list` options
+
+| Flag | Type | Description |
+|------|------|-------------|
+| `--status` | choice | Filter by status: `proposed`, `active`, `deprecated`, `superseded`, `all` |
+| `--source` | choice | Filter by origin: `git_archaeology`, `inline_marker`, `readme_mining`, `cli`, `all` |
+| `--proposed` | flag | Show only proposed decisions |
+| `--stale-only` | flag | Show only decisions with staleness score ≥ 0.5 |
+
+### Examples
+
+```bash
+repowise decision list
+repowise decision list --status proposed
+repowise decision show d-42
+repowise decision confirm d-42
+repowise decision deprecate d-17 --superseded-by d-42
+```
+
+---
+
+## `generate-claude-md`
+
+Generate or update the `.claude/CLAUDE.md` file for Claude Code context.
+
+```bash
+repowise generate-claude-md [PATH] [OPTIONS]
+```
+
+### Options
+
+| Flag | Type | Default | Description |
+|------|------|---------|-------------|
+| `--output` | string | `.claude/CLAUDE.md` | Custom output path |
+| `--stdout` | flag | false | Print to stdout instead of writing a file |
+
+### Example
+
+```bash
+repowise generate-claude-md # Update .claude/CLAUDE.md in place
+repowise generate-claude-md --stdout # Preview without writing
+```
+
+See [CLAUDE.md Generator →](claude-md-generator) for how the file is structured.
+
+---
+
+## `export`
+
+Export wiki pages to files.
+
+```bash
+repowise export [PATH] [OPTIONS]
+```
+
+### Options
+
+| Flag | Type | Default | Description |
+|------|------|---------|-------------|
+| `--format` / `-f` | choice | markdown | `markdown`, `html`, or `json` |
+| `--output` / `-o` | string | `.repowise/export` | Output directory |
+
+### Examples
+
+```bash
+repowise export # Export all pages as markdown
+repowise export --format html -o ./site # HTML export to ./site
+repowise export --format json # Machine-readable JSON dump
+```
+
+---
+
+## Configuration
+
+Settings are saved to `.repowise/config.yaml` after the first `init`. You can edit this file directly or pass flags to override settings per run.
+
+```yaml
+provider: anthropic
+model: claude-sonnet-4-6
+embedder: gemini
+exclude_patterns:
+ - vendor/
+ - "*.generated.*"
+commit_limit: 500
+follow_renames: false
+```
+
+See [Configuration →](configuration) for the full reference.
diff --git a/website/concepts.md b/website/concepts.md
new file mode 100644
index 000000000..9305d09e5
--- /dev/null
+++ b/website/concepts.md
@@ -0,0 +1,186 @@
+---
+layout: default
+title: Core Concepts
+nav_order: 3
+---
+
+# Core Concepts
+{: .no_toc }
+
+The four layers that make up repowise, and why each one exists.
+{: .fs-6 .fw-300 }
+
+---
+
+## Table of contents
+{: .no_toc .text-delta }
+
+1. TOC
+{:toc}
+
+---
+
+## Overview
+
+Every time you run `repowise init`, it runs through four layers in sequence. Each layer builds on the previous one. Understanding what each layer captures helps you interpret what you're getting — and what to do when something looks wrong.
+
+```
+Source code
+ │
+ ▼
+┌─────────────┐
+│ Ingestion │ Parse, extract, build graph
+└──────┬──────┘
+ │
+ ▼
+┌─────────────┐
+│ Analysis │ Git signals, dead code, decisions
+└──────┬──────┘
+ │
+ ▼
+┌─────────────┐
+│ Generation │ LLM-written wiki pages
+└──────┬──────┘
+ │
+ ▼
+┌─────────────┐
+│ Persistence │ SQLite, vector index, REST, MCP
+└─────────────┘
+```
+
+---
+
+## Layer 1: Ingestion
+
+**What it captures:** The static structure of your code.
+
+Ingestion parses every source file using [tree-sitter](https://tree-sitter.github.io/), a fast incremental parser that understands the syntax of each language. For each file, it extracts:
+
+- **Symbols** — functions, classes, methods, interfaces, types
+- **Imports and exports** — what each file depends on and exposes
+- **Call sites** — which functions call which
+- **File metadata** — size, language, path
+
+From this, repowise builds a **dependency graph** using NetworkX. Nodes are files and modules. Edges are imports and call relationships. This graph is used by every subsequent layer.
+
+**Why it matters for you:** The dependency graph powers risk analysis, cascade detection, and architecture diagrams. When you ask "what does this module affect?", the answer comes from this layer.
+
+**Supported languages:** Python, TypeScript, JavaScript, Go, Rust, Java, C, C++, Kotlin, Ruby. More are added regularly.
+
+---
+
+## Layer 2: Analysis
+
+**What it captures:** Everything your code history knows that the source doesn't.
+
+Analysis runs after ingestion and enriches each file with three types of signals:
+
+### Git intelligence
+
+For each file, repowise runs `git log` to extract:
+
+- **Churn score** — how often this file changes relative to others (percentile rank)
+- **Ownership** — which contributors have touched this file and by how much
+- **Bus factor** — whether a file depends on knowledge held by too few people
+- **Recency** — how recently it was last changed
+- **Co-change partners** — which other files tend to change at the same time
+
+High-churn files appear in the hotspots view and receive a warning in the MCP `get_risk` tool. Files with bus factor 1 are flagged as single points of failure.
+
+### Dead code detection
+
+repowise compares what your dependency graph says is reachable against what is exported or imported. Files and symbols with no inbound edges from reachable code are flagged as potentially dead.
+
+Dead code findings are tiered by confidence:
+
+| Tier | Meaning |
+|------|---------|
+| **High** | Confirmed unreachable — no imports from anywhere |
+| **Medium** | No external imports, but exported (may be a public API) |
+| **Low** | Referenced only in tests or dead code itself |
+
+### Decision mining
+
+repowise scans your git history, README files, and inline comments for patterns that indicate architectural decisions: `"we chose X because"`, `"ADR:"`, `"decision:"`, and similar markers. These are surfaced in the decision tracker and made queryable via `get_why`.
+
+**Why it matters for you:** When an AI assistant edits a hotspot file without knowing it's high-churn, the change is risky. When it deletes an unused export without knowing it's a public API, that's a bug. The analysis layer gives AI tools the context to avoid these mistakes.
+
+---
+
+## Layer 3: Generation
+
+**What it captures:** Human-readable documentation at every level of the hierarchy.
+
+Generation is the only layer that requires an LLM API key. repowise sends structured prompts to your chosen provider (Anthropic, OpenAI, Gemini, Ollama, or LiteLLM) and generates wiki pages at three levels:
+
+| Level | What it contains |
+|-------|-----------------|
+| **Repository** | High-level architecture overview, module map, tech stack |
+| **Module** | Purpose, responsibilities, key dependencies, design patterns |
+| **File** | What this file does, how it fits in the module, key symbols |
+
+Each page is stored in the database and linked to the file it describes. Pages have a freshness score — if the underlying file changes, the page is marked stale and queued for regeneration.
+
+**Skipping generation:** You can skip this layer entirely with `repowise init --index-only`. You'll still get the full dependency graph, git intelligence, dead code, and decision data — just no narrative docs. You can add generation later by running `repowise init` on an existing index.
+
+**Cost:** For a 200-file codebase, generation typically uses 150,000–300,000 tokens. The `--dry-run` flag shows you the estimated cost before committing.
+
+---
+
+## Layer 4: Persistence
+
+**What it captures:** Everything, queryable in three complementary ways.
+
+All data from the previous three layers is stored across three stores:
+
+### SQL (SQLite or PostgreSQL)
+
+The primary store. Contains:
+- All wiki pages with full text and metadata
+- Symbol index (every function, class, method)
+- Dependency graph (nodes and edges)
+- Git metadata (churn, ownership, recency per file)
+- Architectural decisions
+- Dead code findings
+
+Default: SQLite at `.repowise/wiki.db`. Switch to PostgreSQL by setting `REPOWISE_DB_URL`.
+
+### Vector store (LanceDB)
+
+An embedding index on top of the wiki pages. Powers semantic search — when you run `repowise search "authentication flow"` or ask Claude `search_codebase("how is auth handled")`, this is what responds.
+
+Stored at `.repowise/lancedb/`. You can rebuild it at any time with `repowise reindex`.
+
+### In-memory graph (NetworkX)
+
+The dependency graph is loaded into memory at server startup for fast traversal. Used by `get_dependency_path`, `get_architecture_diagram`, and cascade analysis during `update`.
+
+**Why it matters for you:** Three stores means three access patterns. Simple lookups hit SQL. Natural language queries hit the vector store. Graph traversal hits NetworkX. The MCP server abstracts all of this — you ask one question, it queries the right store.
+
+---
+
+## The MCP server
+
+The MCP server sits on top of the persistence layer and exposes everything to AI coding assistants via 8 tools. It's the primary interface between repowise and Claude Code, Cursor, Cline, or any other MCP-compatible editor.
+
+When you run `repowise mcp`, the server starts in stdio mode and your editor can begin calling tools. The tools are designed to answer the questions an AI needs to make good decisions about your code — not just "what is this file" but "should I edit it", "why is it structured this way", and "what will break if I change it".
+
+See [MCP Server →](mcp-server) for the full tool reference.
+
+---
+
+## The `.repowise/` directory
+
+Everything repowise knows about your repo lives in `.repowise/`:
+
+```
+.repowise/
+├── wiki.db # SQLite database
+├── lancedb/ # Vector search index
+├── config.yaml # Provider, model, embedder settings
+├── state.json # Last sync commit, page counts
+├── mcp.json # MCP server config
+└── .env # API keys (gitignored)
+```
+
+This directory is created on first `init`. It should be added to `.gitignore` — repowise does this automatically.
diff --git a/website/configuration.md b/website/configuration.md
new file mode 100644
index 000000000..f0ed70b33
--- /dev/null
+++ b/website/configuration.md
@@ -0,0 +1,277 @@
+---
+layout: default
+title: Configuration
+nav_order: 9
+---
+
+# Configuration
+{: .no_toc }
+
+The `.repowise/` directory, provider setup, API keys, and what's customizable.
+{: .fs-6 .fw-300 }
+
+---
+
+## Table of contents
+{: .no_toc .text-delta }
+
+1. TOC
+{:toc}
+
+---
+
+## The `.repowise/` directory
+
+Everything repowise knows about your repository lives here. It's created at the repo root on first `init`.
+
+```
+.repowise/
+├── wiki.db # SQLite database — all pages, symbols, graph, git metadata, decisions
+├── lancedb/ # Vector search index (LanceDB)
+├── config.yaml # Provider, model, embedder, exclude patterns
+├── state.json # Last sync commit, page counts, token usage
+├── mcp.json # MCP server configuration
+└── .env # API keys (gitignored automatically)
+```
+
+repowise adds `.repowise/` to your `.gitignore` automatically. The directory should not be committed — it's a local cache, not source of truth.
+
+---
+
+## `config.yaml`
+
+The main configuration file. Created after first `init`, updated when you pass `--commit-limit` or `--follow-renames` flags.
+
+```yaml
+provider: anthropic # LLM provider
+model: claude-sonnet-4-6 # Model identifier
+embedder: gemini # Embedding provider
+exclude_patterns: # Gitignore-style patterns
+ - vendor/
+ - "*.generated.*"
+ - proto/
+commit_limit: 500 # Max commits per file for git analysis
+follow_renames: false # Track file renames in git history
+```
+
+You can edit this file directly. Changes take effect on the next `init`, `update`, or `serve` run.
+
+---
+
+## LLM providers
+
+### Anthropic (Claude)
+
+```bash
+export ANTHROPIC_API_KEY="sk-ant-..."
+```
+
+| Model | Notes |
+|-------|-------|
+| `claude-sonnet-4-6` | Default — best balance of quality and cost |
+| `claude-opus-4-6` | Highest quality, higher cost |
+| `claude-haiku-4-5-20251001` | Fastest, lowest cost |
+
+```bash
+repowise init --provider anthropic --model claude-haiku-4-5-20251001
+```
+
+---
+
+### OpenAI (GPT)
+
+```bash
+export OPENAI_API_KEY="sk-..."
+```
+
+| Model | Notes |
+|-------|-------|
+| `gpt-4.1` | Default |
+| `gpt-4o` | Alternative |
+
+```bash
+repowise init --provider openai --model gpt-4.1
+```
+
+---
+
+### Gemini (Google)
+
+```bash
+export GEMINI_API_KEY="AI..."
+# or:
+export GOOGLE_API_KEY="AI..."
+```
+
+| Model | Notes |
+|-------|-------|
+| `gemini-3.1-flash-lite-preview` | Default — very fast and cheap |
+| `gemini-2.5-pro` | Higher quality |
+
+```bash
+repowise init --provider gemini
+```
+
+Gemini is also the default embedding provider when `GEMINI_API_KEY` is set.
+
+---
+
+### Ollama (local)
+
+Run models locally without any API key.
+
+```bash
+export OLLAMA_BASE_URL="http://localhost:11434" # default if Ollama is running locally
+```
+
+```bash
+repowise init --provider ollama --model llama3.2
+```
+
+Any model available in your local Ollama installation can be used.
+
+---
+
+### LiteLLM (100+ providers)
+
+LiteLLM acts as a proxy supporting OpenAI, Azure, Cohere, Mistral, and dozens more.
+
+```bash
+pip install "repowise[litellm]"
+export LITELLM_API_KEY="..."
+repowise init --provider litellm --model azure/gpt-4
+```
+
+---
+
+### Provider auto-detection
+
+If you don't pass `--provider`, repowise detects your provider by checking:
+
+1. `REPOWISE_PROVIDER` environment variable
+2. `provider` in `.repowise/config.yaml`
+3. API key environment variables, in order: `ANTHROPIC_API_KEY` → `OPENAI_API_KEY` → `OLLAMA_BASE_URL` → `GEMINI_API_KEY`
+
+---
+
+## Embeddings (for semantic search)
+
+Embeddings power semantic search via the vector index. The embedder is separate from the LLM provider.
+
+| Embedder | Env var | Notes |
+|----------|---------|-------|
+| `gemini` | `GEMINI_API_KEY` | Default when key is present |
+| `openai` | `OPENAI_API_KEY` | OpenAI text-embedding-3-small |
+| `mock` | — | Dummy embeddings, no semantic search |
+
+```bash
+repowise init --embedder openai
+repowise reindex --embedder gemini # Switch embedder and rebuild index
+```
+
+---
+
+## BYOK (Bring Your Own Key)
+
+API keys can be provided in three ways, checked in this order:
+
+1. **Environment variable** — set before running repowise
+2. **`.repowise/.env`** — persisted from interactive setup, loaded automatically
+3. **Interactive prompt** — repowise asks during `init` if no key is found, then saves to `.repowise/.env`
+
+The `.repowise/.env` file is gitignored automatically. Example:
+
+```env
+ANTHROPIC_API_KEY=sk-ant-...
+GEMINI_API_KEY=AI...
+```
+
+---
+
+## `state.json`
+
+Tracks the current indexing state. Do not edit manually.
+
+```json
+{
+ "last_sync_commit": "59ca5c8a1b2c3d4e5f6a7b8c",
+ "total_pages": 247,
+ "provider": "anthropic",
+ "model": "claude-sonnet-4-6",
+ "total_tokens_used": 180432
+}
+```
+
+`last_sync_commit` is used by `repowise update` to determine which files have changed since the last run.
+
+---
+
+## `mcp.json`
+
+MCP server configuration for this repository.
+
+```json
+{
+ "mcpServers": {
+ "repowise": {
+ "command": "repowise",
+ "args": ["mcp", "/path/to/repo", "--transport", "stdio"],
+ "description": "repowise: codebase intelligence for my-repo"
+ }
+ },
+ "settings": {
+ "port": 7338
+ }
+}
+```
+
+repowise also writes a `.mcp.json` at the repository root for Claude Code auto-discovery. This file can be committed.
+
+---
+
+## Environment variables
+
+| Variable | Description |
+|----------|-------------|
+| `ANTHROPIC_API_KEY` | Anthropic API key |
+| `OPENAI_API_KEY` | OpenAI API key |
+| `GEMINI_API_KEY` / `GOOGLE_API_KEY` | Google Gemini API key |
+| `OLLAMA_BASE_URL` | Ollama server URL (default: `http://localhost:11434`) |
+| `LITELLM_API_KEY` | LiteLLM proxy key |
+| `REPOWISE_PROVIDER` | Override provider (skips auto-detection) |
+| `REPOWISE_DB_URL` | Use PostgreSQL instead of SQLite (e.g., `postgresql+asyncpg://...`) |
+| `REPOWISE_HOST` | API server host (default: `127.0.0.1`) |
+| `REPOWISE_PORT` | API server port (default: `7337`) |
+| `REPOWISE_MCP_PORT` | MCP SSE server port (default: `7338`) |
+
+---
+
+## Exclude patterns
+
+Control which files are indexed using gitignore-style patterns:
+
+```bash
+repowise init -x vendor/ -x "*.generated.ts" -x proto/ -x "**/*.pb.go"
+```
+
+Patterns are saved to `config.yaml` and applied on subsequent `update` runs.
+
+Built-in exclusions (always applied):
+- `.git/`, `.repowise/`, `node_modules/`
+- `__pycache__/`, `*.pyc`, `.venv/`
+- Binary files and media assets
+
+Use `--skip-tests` to exclude test files and `--skip-infra` to exclude Dockerfiles, Makefiles, and shell scripts.
+
+---
+
+## PostgreSQL
+
+For team deployments or larger repos, use PostgreSQL instead of SQLite:
+
+```bash
+export REPOWISE_DB_URL="postgresql+asyncpg://user:pass@localhost:5432/repowise"
+repowise init
+```
+
+The schema is managed with Alembic migrations. See [Self-hosting →](self-hosting) for Docker setup with PostgreSQL.
diff --git a/website/contributing.md b/website/contributing.md
new file mode 100644
index 000000000..7843b000d
--- /dev/null
+++ b/website/contributing.md
@@ -0,0 +1,33 @@
+---
+layout: default
+title: Contributing
+nav_order: 11
+---
+
+# Contributing
+
+Contributions are welcome. Full guidelines are maintained in the repository.
+
+**[Read CONTRIBUTING.md on GitHub →](https://github.com/repowise-dev/repowise/blob/main/CONTRIBUTING.md)**
+
+## Quick links
+
+- [Open an issue](https://github.com/repowise-dev/repowise/issues) — bugs, feature requests, questions
+- [Open a pull request](https://github.com/repowise-dev/repowise/pulls)
+- [Read the architecture guide](https://github.com/repowise-dev/repowise/blob/main/docs/ARCHITECTURE.md) — required reading before contributing
+
+## Development setup
+
+```bash
+git clone https://github.com/repowise-dev/repowise.git
+cd repowise
+uv sync --all-extras # Python dependencies
+npm install # Web frontend
+npm run build # Build frontend
+pytest # Run tests
+ruff check packages/ # Lint
+```
+
+## Security issues
+
+For security vulnerabilities, see [SECURITY.md](https://github.com/repowise-dev/repowise/blob/main/SECURITY.md) — do not open a public issue.
diff --git a/website/getting-started.md b/website/getting-started.md
new file mode 100644
index 000000000..e79adcd3b
--- /dev/null
+++ b/website/getting-started.md
@@ -0,0 +1,218 @@
+---
+layout: default
+title: Getting Started
+nav_order: 2
+---
+
+# Getting Started
+{: .no_toc }
+
+The 60-second path to codebase intelligence.
+{: .fs-6 .fw-300 }
+
+---
+
+## Table of contents
+{: .no_toc .text-delta }
+
+1. TOC
+{:toc}
+
+---
+
+## Choose your path
+
+There are three ways to set up repowise. Pick the one that fits how you work.
+
+| Path | Best for | Time |
+|------|----------|------|
+| [Claude Code Plugin](#path-1-claude-code-plugin) | Claude Code users | ~30 seconds |
+| [pip + Claude Code](#path-2-pip--claude-code) | Manual control + Claude Code | ~2 minutes |
+| [Standalone CLI](#path-3-standalone-cli) | No Claude Code, or CI use | ~2 minutes |
+
+---
+
+## Path 1: Claude Code Plugin
+
+**The recommended path.** Claude handles everything — installation, API key setup, indexing, and MCP registration.
+
+### Step 1: Install the plugin
+
+Open Claude Code and run:
+
+```
+/plugin marketplace add repowise-dev/repowise-plugin
+/plugin install repowise@repowise
+```
+
+### Step 2: Index your repo
+
+Navigate to your project directory and run:
+
+```
+/repowise:init
+```
+
+Or just ask Claude naturally:
+
+```
+set up repowise for this repo
+```
+
+### What happens
+
+Claude walks you through:
+
+1. **Mode selection** — full documentation, index-only (free, no LLM), or advanced
+2. **Provider setup** — choose Anthropic, OpenAI, Gemini, or local Ollama
+3. **API key** — entered once, saved to `.repowise/.env` (gitignored automatically)
+4. **Indexing** — parses your code, runs git analysis, generates docs
+
+When it finishes, the MCP server is registered and Claude can query your codebase directly. You'll see a progress bar as each phase completes.
+
+### What you see
+
+```
+ repowise
+─────────────────────────────────────────────
+ Indexing your codebase...
+
+ Phase 1 of 4 — Ingestion
+ Parsing files... [████████████████████] 247/247
+ Building dependency graph... done
+ Running git analysis... done
+
+ Phase 2 of 4 — Analysis
+ Computing churn scores... done
+ Detecting dead code... done
+ Mining decisions... done
+
+ Phase 3 of 4 — Generation
+ Generating wiki pages... [████████████████░░░░] 82%
+ Estimated tokens: ~180k
+
+ Phase 4 of 4 — Persistence
+ Writing to database... done
+ Building vector index... done
+ Generating CLAUDE.md... done
+
+ Done. 247 pages generated.
+─────────────────────────────────────────────
+```
+
+---
+
+## Path 2: pip + Claude Code
+
+Install manually, then connect Claude Code to the MCP server.
+
+### Step 1: Install repowise
+
+```bash
+pip install repowise
+```
+
+### Step 2: Set your API key
+
+```bash
+export ANTHROPIC_API_KEY="sk-ant-..."
+# or: export OPENAI_API_KEY="sk-..."
+# or: export GEMINI_API_KEY="AI..."
+```
+
+### Step 3: Index your repo
+
+```bash
+cd /path/to/your-repo
+repowise init
+```
+
+repowise detects your API key automatically and starts the interactive setup. Follow the prompts — it takes about 2 minutes for a medium-sized codebase.
+
+### Step 4: Connect Claude Code
+
+After `init` completes, repowise writes a `.mcp.json` file at your repo root. Claude Code picks this up automatically next time you open the project.
+
+To verify the MCP server is connected:
+
+```
+/repowise:status
+```
+
+---
+
+## Path 3: Standalone CLI
+
+Use repowise without Claude Code — with the web dashboard, REST API, or any MCP-compatible editor.
+
+### Step 1: Install and set up
+
+```bash
+pip install repowise
+export ANTHROPIC_API_KEY="sk-ant-..."
+```
+
+### Step 2: Index your repo
+
+```bash
+cd /path/to/your-repo
+repowise init
+```
+
+### Step 3: Start the web dashboard
+
+```bash
+repowise serve
+```
+
+Open [http://localhost:3000](http://localhost:3000) in your browser. You'll see the full wiki, dependency graph, search, and more.
+
+### Step 4: Start the MCP server (optional)
+
+To connect any MCP-compatible editor (Cursor, Cline, Windsurf):
+
+```bash
+repowise mcp
+```
+
+Then add the MCP server to your editor's configuration. See [MCP Server →](mcp-server) for editor-specific setup.
+
+---
+
+## Analysis-only mode (no API key needed)
+
+If you don't have an LLM API key — or just want the git intelligence and dead code detection without generated docs — use `--index-only`:
+
+```bash
+repowise init --index-only
+```
+
+This runs the full ingestion and analysis pipeline (parsing, graph, git, dead code) but skips LLM generation. It's free, takes under a minute for most repos, and still gives you:
+
+- Dependency graph
+- Hotspot detection
+- Dead code findings
+- Ownership data
+
+You can always run `repowise init` later to add docs on top of an existing index.
+
+---
+
+## Keeping docs in sync
+
+After the initial index, keep your wiki current with:
+
+```bash
+repowise update # Sync changed files since last commit
+repowise watch # Auto-update on file saves
+```
+
+Or in Claude Code, run `/repowise:update` — Claude detects changed files and regenerates only the affected pages.
+
+---
+
+## Next steps
+
+- [Core concepts →](concepts) — understand the four layers
+- [CLI reference →](cli-reference) — all commands and flags
+- [MCP server →](mcp-server) — connecting to Claude Code, Cursor, Cline
diff --git a/website/index.md b/website/index.md
new file mode 100644
index 000000000..ea3641bdc
--- /dev/null
+++ b/website/index.md
@@ -0,0 +1,54 @@
+---
+layout: home
+title: Home
+nav_order: 1
+---
+
+# repowise
+
+**Codebase intelligence for developers and AI.**
+
+repowise generates and maintains a structured wiki for any codebase. It tracks changes, exposes everything through an MCP server, and keeps your AI coding assistant deeply informed about your code — automatically.
+
+[![PyPI version](https://img.shields.io/pypi/v/repowise.svg)](https://pypi.org/project/repowise/)
+[![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue.svg)](https://pypi.org/project/repowise/)
+[![License: AGPL-3.0](https://img.shields.io/badge/license-AGPL--3.0-purple.svg)](https://github.com/repowise-dev/repowise/blob/main/LICENSE)
+
+---
+
+## What repowise does
+
+| Capability | Description |
+|-----------|-------------|
+| **Auto-documentation** | Module, file, and symbol-level docs generated from source code |
+| **Git intelligence** | Churn hotspots, ownership, bus factor, change patterns |
+| **Dead code detection** | Finds confirmed unused exports, functions, and types |
+| **Decision intelligence** | Captures *why* code is structured the way it is |
+| **MCP server** | 8 tools for AI assistants (Claude Code, Cursor, Windsurf, Cline) |
+| **Web dashboard** | Browse wiki, search, and explore architecture diagrams |
+| **Multi-language** | Python, TypeScript, JavaScript, Go, Rust, Java, C/C++, Kotlin, Ruby |
+
+---
+
+## Install in one line
+
+```bash
+pip install repowise
+```
+
+---
+
+## Get started
+
+<div class="d-flex flex-wrap gap-3 mt-4">
+
+**[60-second quickstart →](getting-started)**
+The fastest path to a working setup.
+
+**[Core concepts →](concepts)**
+Understand the four layers before diving in.
+
+**[CLI reference →](cli-reference)**
+Every command, flag, and option.
+
+</div>
diff --git a/website/mcp-server.md b/website/mcp-server.md
new file mode 100644
index 000000000..41abdca3a
--- /dev/null
+++ b/website/mcp-server.md
@@ -0,0 +1,346 @@
+---
+layout: default
+title: MCP Server
+nav_order: 5
+---
+
+# MCP Server
+{: .no_toc }
+
+Connect repowise to Claude Code, Cursor, Cline, or any MCP-compatible editor.
+{: .fs-6 .fw-300 }
+
+---
+
+## Table of contents
+{: .no_toc .text-delta }
+
+1. TOC
+{:toc}
+
+---
+
+## Overview
+
+The MCP (Model Context Protocol) server is how repowise talks to AI coding assistants. Once connected, your editor's AI can call 8 tools to query your codebase wiki — getting docs, ownership, risk signals, dependency paths, and architectural decisions in a single call.
+
+Start the server with:
+
+```bash
+repowise mcp [PATH]
+```
+
+---
+
+## Connecting to editors
+
+### Claude Code
+
+**Via plugin (recommended):** The repowise Claude Code plugin registers the MCP server automatically. See [Claude Code Plugin →](claude-code-plugin).
+
+**Manual setup:** Add this to `.mcp.json` at your repo root:
+
+```json
+{
+ "mcpServers": {
+ "repowise": {
+ "command": "repowise",
+ "args": ["mcp", "/path/to/your-repo"],
+ "description": "repowise codebase intelligence"
+ }
+ }
+}
+```
+
+If you're running repowise for the current directory, you can omit the path:
+
+```json
+{
+ "mcpServers": {
+ "repowise": {
+ "command": "repowise",
+ "args": ["mcp"]
+ }
+ }
+}
+```
+
+### Cursor
+
+Add to `.cursor/mcp.json` in your repo or `~/.cursor/mcp.json` globally:
+
+```json
+{
+ "mcpServers": {
+ "repowise": {
+ "command": "repowise",
+ "args": ["mcp", "/path/to/your-repo"]
+ }
+ }
+}
+```
+
+### Cline
+
+Add to Cline's MCP settings file (`cline_mcp_settings.json`):
+
+```json
+{
+ "mcpServers": {
+ "repowise": {
+ "command": "repowise",
+ "args": ["mcp", "/path/to/your-repo"],
+ "disabled": false,
+ "autoApprove": ["get_overview", "get_context", "search_codebase"]
+ }
+ }
+}
+```
+
+### Windsurf
+
+Add to Windsurf's MCP configuration:
+
+```json
+{
+ "mcpServers": {
+ "repowise": {
+ "command": "repowise",
+ "args": ["mcp", "/path/to/your-repo"]
+ }
+ }
+}
+```
+
+---
+
+## Transport protocols
+
+### stdio (default)
+
+The default transport. The MCP server runs as a subprocess of your editor, communicating over stdin/stdout. This is the correct option for Claude Code, Cursor, Cline, and Windsurf.
+
+```bash
+repowise mcp # stdio, current directory
+repowise mcp /path/to/repo # stdio, specific repo
+repowise mcp --transport stdio # explicit
+```
+
+### SSE (Server-Sent Events)
+
+For web-based MCP clients or headless setups where a persistent HTTP server is preferable.
+
+```bash
+repowise mcp --transport sse # SSE on port 7338
+repowise mcp --transport sse --port 8080 # Custom port
+```
+
+Clients connect to `http://localhost:7338/sse` and receive server-sent events. Configure with `REPOWISE_MCP_PORT` env var or `mcp.settings.port` in `.repowise/mcp.json`.
+
+---
+
+## The 8 tools
+
+### `get_overview()`
+
+Returns a high-level architecture summary of the indexed repository: key modules, entry points, tech stack, git health (churn percentiles, bus factors), and recent activity trends.
+
+**When to use:** Start every new task by calling this. It orients the AI and surfaces risk signals before any code is read.
+
+**Example response:**
+```
+Repository: repowise
+Architecture: Python monorepo (cli, core, server, web)
+Entry points: packages/cli/src/repowise/cli/main.py
+Tech stack: Python, FastAPI, SQLite, LanceDB, Next.js
+Top hotspots: init_cmd.py (99.8th %ile), test_mcp.py (99.5th %ile)
+Bus factor risk: git_indexer.py (1 author)
+```
+
+---
+
+### `get_context(targets, include?)`
+
+Returns rich context for one or more files, modules, or symbols: documentation, ownership, last change, governing decisions, and freshness status.
+
+**Parameters:**
+- `targets` (list of strings) — file paths, module names, or symbol names
+- `include` (optional) — subset of `["docs", "ownership", "last_change", "decisions", "freshness"]`
+
+**When to use:** Before reading or editing any file. Faster and richer than reading the raw source.
+
+**Example:**
+```
+get_context(targets=["packages/cli/src/repowise/cli/commands/init_cmd.py"])
+
+→ Purpose: Orchestrates the 4-phase init pipeline
+ Owner: RaghavChamadiya (89% of commits)
+ Last changed: 3 days ago (14 commits in 90d — 99.8th %ile)
+ Decisions: "Use interactive mode when stdin is a TTY"
+ Freshness: current
+```
+
+---
+
+### `get_risk(targets)`
+
+Returns a modification risk assessment for each target file.
+
+**Parameters:**
+- `targets` (list of strings) — file paths
+
+**Returns per file:**
+- Churn percentile rank
+- Number of direct and transitive dependents
+- Co-change partners (files that tend to change together)
+- Bus factor (number of authors with meaningful ownership)
+- Change trend: increasing / decreasing / stable
+
+**When to use:** Required before making changes to any file, especially in hotspot areas.
+
+**Example:**
+```
+get_risk(targets=["packages/core/src/repowise/core/ingestion/git_indexer.py"])
+
+→ Hotspot: 99.3th %ile (9 commits in 90 days)
+ Dependents: 7 direct, 23 transitive
+ Co-change partners: init_cmd.py, update_cmd.py
+ Bus factor: 1 (sole author: RaghavChamadiya)
+ Trend: increasing
+ Recommendation: High risk — coordinate before changing
+```
+
+---
+
+### `get_why(query?, targets?)`
+
+Searches for architectural decisions and intent behind code structure.
+
+**Parameters:**
+- `query` (string) — natural language question ("why JWT instead of sessions?")
+- `targets` (optional, list) — file paths to focus on
+
+**Returns:**
+- Matching decision records with title, rationale, and status
+- Git archaeology: commit messages and PR descriptions that explain design choices
+- Origin story for specific files (if `targets` provided)
+- Decision health (staleness scores for applicable decisions)
+
+**When to use:** Before any architectural change. Ask "why is this structured this way" before refactoring.
+
+**Example:**
+```
+get_why(query="why is rate limiting done in the app layer")
+
+→ Decision: "Rate limiting at application layer"
+ Rationale: Need per-user limits; load balancer can't distinguish users
+ Status: active
+ Source: cli (manually recorded)
+ Affected: server/middleware/rate_limit.py
+```
+
+---
+
+### `search_codebase(query, limit?, page_type?)`
+
+Semantic search over the full wiki using natural language.
+
+**Parameters:**
+- `query` (string) — natural language query
+- `limit` (int, default 5) — max results
+- `page_type` (optional) — filter to `"file"`, `"module"`, or `"repository"`
+
+**Returns:** Ranked list of wiki pages with relevance scores and short excerpts. Recently-changed files receive a freshness boost.
+
+**When to use:** When locating code — prefer over `grep`/`find` for conceptual searches.
+
+**Example:**
+```
+search_codebase(query="how database connections are pooled")
+
+→ 1. packages/server/src/repowise/server/db.py (0.92)
+ "Creates async SQLAlchemy engine with connection pooling..."
+ 2. packages/core/src/repowise/core/persistence/session.py (0.87)
+ "Session factory configured with pool_size=5..."
+```
+
+---
+
+### `get_dependency_path(source, target)`
+
+Finds the dependency path between two files or modules through the graph.
+
+**Parameters:**
+- `source` (string) — starting file/module
+- `target` (string) — destination file/module
+
+**Returns:** The shortest path with edge types (imports, calls). When no direct path exists, returns nearest common ancestors, shared neighbors, and bridge suggestions.
+
+**When to use:** When tracing how modules connect, understanding blast radius, or planning refactors.
+
+**Example:**
+```
+get_dependency_path(
+ source="packages/cli/src/repowise/cli/commands/init_cmd.py",
+ target="packages/core/src/repowise/core/persistence/db.py"
+)
+
+→ init_cmd.py → orchestrator.py → persistence/writer.py → db.py
+ (3 hops, all import edges)
+```
+
+---
+
+### `get_dead_code(kind?, min_confidence?, safe_only?, tier?, directory?)`
+
+Returns a tiered report of unused code.
+
+**Parameters:**
+- `kind` — filter by `unreachable_file`, `unused_export`, `unused_internal`, `zombie_package`
+- `min_confidence` — 0.0–1.0, default 0.4
+- `safe_only` — only return findings marked `safe_to_delete`
+- `tier` — `high`, `medium`, or `low`
+- `directory` — limit to a specific directory
+- `group_by` — `directory` or `owner`
+
+**When to use:** Before any cleanup or removal tasks. Gives confirmed unused code rather than guesses.
+
+---
+
+### `get_architecture_diagram(scope?, path?, diagram_type?, show_heat?)`
+
+Generates a Mermaid diagram of the architecture.
+
+**Parameters:**
+- `scope` — `"repo"` (default), `"module"`, or `"file"`
+- `path` — required for module/file scope
+- `diagram_type` — `"auto"`, `"flowchart"`, `"class"`, or `"sequence"`
+- `show_heat` — boolean; colors nodes by churn intensity (red = hot, green = cold)
+
+**When to use:** For documentation, architecture reviews, or understanding unfamiliar areas.
+
+**Example output:**
+```mermaid
+graph TD
+ cli["CLI (init, update, mcp...)"]
+ core["Core (ingestion, analysis, generation)"]
+ server["Server (FastAPI + MCP)"]
+ cli --> core
+ cli --> server
+ server --> core
+```
+
+---
+
+## How AI editors use these tools
+
+The tools are designed to form a decision workflow:
+
+1. **Before any task** → `get_overview()` to orient
+2. **Before reading a file** → `get_context(targets=[...])` instead of reading raw source
+3. **Before editing a file** → `get_risk(targets=[...])` to assess impact
+4. **When facing an architectural question** → `get_why(query="...")` before changing structure
+5. **When locating code** → `search_codebase(query="...")` before grep
+6. **After making changes** → `update_decision_records(action="create", ...)` to record decisions
+
+The [CLAUDE.md generator](claude-md-generator) writes these instructions directly into your project's CLAUDE.md, so Claude Code follows this workflow automatically.
diff --git a/website/self-hosting.md b/website/self-hosting.md
new file mode 100644
index 000000000..d7e65e992
--- /dev/null
+++ b/website/self-hosting.md
@@ -0,0 +1,246 @@
+---
+layout: default
+title: Self-hosting & Deployment
+nav_order: 10
+---
+
+# Self-hosting & Deployment
+{: .no_toc }
+
+Docker setup, environment variables, and running repowise in production or CI.
+{: .fs-6 .fw-300 }
+
+---
+
+## Table of contents
+{: .no_toc .text-delta }
+
+1. TOC
+{:toc}
+
+---
+
+## Docker (quickstart)
+
+The Docker image bundles the Python backend, the Next.js frontend, and all dependencies. No Node.js required on the host.
+
+```bash
+docker pull ghcr.io/repowise-dev/repowise:latest
+
+docker run \
+ -p 7337:7337 \
+ -p 3000:3000 \
+ -v $(pwd):/repo \
+ -v $(pwd)/.repowise:/data \
+ -e ANTHROPIC_API_KEY="sk-ant-..." \
+ ghcr.io/repowise-dev/repowise:latest \
+ serve /repo
+```
+
+Open [http://localhost:3000](http://localhost:3000) to access the dashboard.
+
+---
+
+## Docker Compose
+
+A full setup with the API server, web UI, and a PostgreSQL database:
+
+```yaml
+# docker-compose.yml
+services:
+ db:
+ image: postgres:16
+ environment:
+ POSTGRES_DB: repowise
+ POSTGRES_USER: repowise
+ POSTGRES_PASSWORD: repowise
+ volumes:
+ - postgres_data:/var/lib/postgresql/data
+ healthcheck:
+ test: ["CMD-SHELL", "pg_isready -U repowise"]
+ interval: 5s
+ timeout: 5s
+ retries: 5
+
+ repowise:
+ image: ghcr.io/repowise-dev/repowise:latest
+ ports:
+ - "7337:7337"
+ - "3000:3000"
+ volumes:
+ - ./:/repo
+ - lancedb_data:/data/lancedb
+ environment:
+ REPOWISE_DB_URL: postgresql+asyncpg://repowise:repowise@db:5432/repowise
+ REPOWISE_HOST: 0.0.0.0
+ ANTHROPIC_API_KEY: ${ANTHROPIC_API_KEY}
+ depends_on:
+ db:
+ condition: service_healthy
+ command: serve /repo --host 0.0.0.0
+
+volumes:
+ postgres_data:
+ lancedb_data:
+```
+
+```bash
+ANTHROPIC_API_KEY=sk-ant-... docker compose up
+```
+
+---
+
+## Environment variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `ANTHROPIC_API_KEY` | — | Anthropic API key |
+| `OPENAI_API_KEY` | — | OpenAI API key |
+| `GEMINI_API_KEY` | — | Google Gemini API key |
+| `REPOWISE_PROVIDER` | auto | Override provider detection |
+| `REPOWISE_DB_URL` | SQLite (`.repowise/wiki.db`) | PostgreSQL connection string |
+| `REPOWISE_HOST` | `127.0.0.1` | API server bind host |
+| `REPOWISE_PORT` | `7337` | API server port |
+| `REPOWISE_MCP_PORT` | `7338` | MCP SSE server port |
+
+---
+
+## Building from source
+
+```bash
+git clone https://github.com/repowise-dev/repowise.git
+cd repowise
+
+# Python dependencies
+uv sync --all-extras
+
+# Web frontend
+npm install
+npm run build
+
+# Run
+repowise serve
+```
+
+---
+
+## Running in CI
+
+Use `--index-only` for CI pipelines that don't need full LLM documentation — just analysis signals:
+
+```yaml
+# GitHub Actions example
+- name: Index codebase
+ run: |
+ pip install repowise
+ repowise init --index-only --yes
+
+- name: Check dead code
+ run: repowise dead-code --safe-only --format json > dead-code-report.json
+
+- name: Upload report
+ uses: actions/upload-artifact@v4
+ with:
+ name: dead-code-report
+ path: dead-code-report.json
+```
+
+For full documentation generation in CI (with LLM):
+
+```yaml
+- name: Generate docs
+ env:
+ ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+ run: |
+ pip install repowise
+ repowise init --yes --concurrency 10
+
+- name: Export to markdown
+ run: repowise export --format markdown --output ./wiki-export
+```
+
+---
+
+## Keeping the index current in CI
+
+Update the wiki on every push to main:
+
+```yaml
+on:
+ push:
+ branches: [main]
+
+jobs:
+ update-wiki:
+ runs-on: ubuntu-latest
+ steps:
+ - uses: actions/checkout@v4
+ with:
+ fetch-depth: 0 # Full history for git analysis
+
+ - name: Restore index cache
+ uses: actions/cache@v4
+ with:
+ path: .repowise
+ key: repowise-${{ github.sha }}
+ restore-keys: repowise-
+
+ - name: Update wiki
+ env:
+ ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+ run: |
+ pip install repowise
+ repowise update --yes
+```
+
+{: .note }
+Use `fetch-depth: 0` to include full git history. repowise uses git log for ownership and churn analysis — shallow clones will produce incomplete results.
+
+---
+
+## Reverse proxy (nginx)
+
+To serve the dashboard at a custom domain:
+
+```nginx
+server {
+ listen 80;
+ server_name docs.yourcompany.com;
+
+ location / {
+ proxy_pass http://localhost:3000;
+ proxy_set_header Host $host;
+ proxy_set_header X-Real-IP $remote_addr;
+ }
+
+ location /api/ {
+ proxy_pass http://localhost:7337/;
+ proxy_set_header Host $host;
+ proxy_set_header X-Real-IP $remote_addr;
+ }
+}
+```
+
+---
+
+## Database migrations
+
+repowise uses Alembic for PostgreSQL schema management. Migrations run automatically at startup. To run them manually:
+
+```bash
+cd packages/server
+alembic upgrade head
+```
+
+---
+
+## Requirements summary
+
+| Component | Requirement |
+|-----------|-------------|
+| Python | 3.11+ |
+| Git | Any recent version |
+| Node.js | 20+ (for web UI without Docker) |
+| Docker | Any version (alternative to Node.js) |
+| PostgreSQL | 14+ (optional, SQLite is the default) |
+| LLM API key | Anthropic, OpenAI, Gemini, or Ollama (not needed for `--index-only`) |
diff --git a/website/web-dashboard.md b/website/web-dashboard.md
new file mode 100644
index 000000000..8f37ec961
--- /dev/null
+++ b/website/web-dashboard.md
@@ -0,0 +1,183 @@
+---
+layout: default
+title: Web Dashboard
+nav_order: 6
+---
+
+# Web Dashboard
+{: .no_toc }
+
+Browse your codebase wiki, explore architecture, and search from a browser.
+{: .fs-6 .fw-300 }
+
+---
+
+## Table of contents
+{: .no_toc .text-delta }
+
+1. TOC
+{:toc}
+
+---
+
+## Starting the dashboard
+
+```bash
+repowise serve
+```
+
+This starts two servers:
+
+| Server | URL | Purpose |
+|--------|-----|---------|
+| API | `http://localhost:7337` | REST API (FastAPI) |
+| Web UI | `http://localhost:3000` | Next.js frontend |
+
+Open [http://localhost:3000](http://localhost:3000) in your browser.
+
+On first run, repowise downloads and caches the frontend automatically. Node.js 20+ must be installed. For Docker-based setup without Node.js, see [Self-hosting →](self-hosting).
+
+### Custom ports
+
+```bash
+repowise serve --port 8080 --ui-port 4000
+```
+
+### API only (no UI)
+
+```bash
+repowise serve --no-ui
+```
+
+### Expose on your network
+
+```bash
+repowise serve --host 0.0.0.0
+```
+
+---
+
+## Dashboard views
+
+### Wiki browser
+
+The main view. Shows all indexed pages organized by module and file. Each page contains:
+
+- AI-generated documentation for the file or module
+- Key symbols (functions, classes, interfaces) with signatures
+- Dependency list (what this file imports and what imports it)
+- Git sidebar: last commit, contributors, churn percentile, change history
+
+Pages marked stale (underlying file has changed since last generation) show a regeneration prompt.
+
+### Dependency graph
+
+An interactive force-directed graph built with D3.js. Handles repositories with 2,000+ nodes without degrading.
+
+- **Zoom and pan** to navigate large graphs
+- **Click a node** to open its wiki page
+- **Hover** to see the file name and module
+- **Filter by module** to isolate a subsystem
+- **Toggle heat map** to color nodes by churn intensity (red = high churn, green = stable)
+- **Search** to highlight matching nodes
+
+### Search
+
+Full-text and semantic search across the entire wiki. Press `Ctrl+K` (or `Cmd+K`) from anywhere in the dashboard to open the global command palette.
+
+Search modes:
+- **Full-text** — keyword matching against page content
+- **Semantic** — natural language queries using vector embeddings
+- **Symbol** — search by function name, class name, or method signature
+
+### Symbol index
+
+A filterable table of every indexed symbol: functions, classes, methods, interfaces, types. Columns include:
+
+- Name and signature
+- File and module
+- Kind (function, class, method, etc.)
+- Usage count (how many other files reference it)
+
+Click any symbol to jump to its wiki page.
+
+### Coverage dashboard
+
+Shows documentation freshness across the codebase:
+
+- **Fresh** — page is current with the source file
+- **Stale** — source file has changed since the page was generated
+- **Missing** — file exists but has no wiki page
+
+One-click regeneration for individual stale pages, or bulk-regenerate all with `repowise update`.
+
+### Ownership view
+
+Shows contributor attribution across modules:
+
+- Per-file owner (contributor with the most commit weight)
+- Bus factor risk detection (files where one person holds >80% of knowledge)
+- Contributor activity over time
+- Module-level ownership breakdown
+
+### Hotspots
+
+A ranked list of high-churn files. Each entry shows:
+
+- File path and module
+- Churn percentile (e.g., "99.8th %ile")
+- Number of commits in the last 90 days
+- Primary owner
+- Trend direction (increasing / stable / decreasing)
+
+### Dead code finder
+
+Lists unused code with confidence scores and bulk actions:
+
+- **Unreachable files** — files with no inbound imports
+- **Unused exports** — exported symbols with no external consumers
+- **Unused internals** — internal symbols never called
+- **Zombie packages** — installed dependencies never imported
+
+Each finding shows confidence score and a "safe to delete" flag for high-confidence cases. Findings can be exported as a Markdown checklist.
+
+### Decision tracker
+
+All architectural decisions captured by repowise, organized by:
+
+- **Status** — proposed, active, deprecated, superseded
+- **Source** — git archaeology, inline markers, README mining, manually added
+- **Health score** — staleness relative to how much the affected code has changed
+
+Proposed decisions (mined automatically) can be confirmed or dismissed from this view.
+
+### Codebase chat
+
+Ask natural language questions about your codebase. The chat endpoint uses the wiki index as retrieval context, so answers are grounded in your actual code — not a hallucination.
+
+Example questions:
+- "How does authentication work?"
+- "Which module handles database migrations?"
+- "What are the entry points for the CLI?"
+- "Show me all files that depend on the session module"
+
+---
+
+## REST API
+
+The API at `http://localhost:7337` exposes everything in the dashboard programmatically. Key endpoints:
+
+| Endpoint | Description |
+|----------|-------------|
+| `GET /health` | Server health check |
+| `GET /repos/{id}/pages` | List all wiki pages |
+| `GET /repos/{id}/pages/{page_id}` | Get a wiki page |
+| `GET /repos/{id}/search?q=...` | Full-text search |
+| `GET /repos/{id}/symbols` | List all symbols |
+| `GET /repos/{id}/graph` | Dependency graph data |
+| `GET /repos/{id}/dead-code` | Dead code findings |
+| `GET /repos/{id}/decisions` | Decision records |
+| `POST /repos/{id}/chat` | Codebase chat |
+| `GET /repos/{id}/generate-claude-md` | Generate CLAUDE.md content |
+
+Full API docs are available at `http://localhost:7337/docs` (Swagger UI) when the server is running.