crg-dev-kit 1.0.0

package/README.md

@@ -0,0 +1,111 @@
+# CRG Dev Kit
+
+One command to set up [code-review-graph](https://github.com/tirth8205/code-review-graph) across any project, any stack. Track token savings and prove ROI to your team.
+
+## Quick Start
+
+```bash
+# Open the dashboard
+npx crg-dev-kit
+
+# Copy setup scripts to your project
+npx crg-dev-kit install
+
+# Check installation status
+npx crg-dev-kit status
+```
+
+## Commands
+
+| Command | What it does |
+|---------|-------------|
+| `npx crg-dev-kit` | Opens the dashboard (default) |
+| `npx crg-dev-kit install` | Copies setup scripts to current directory |
+| `npx crg-dev-kit start --port 9000` | Dashboard on custom port |
+| `npx crg-dev-kit start --no-open` | Dashboard without auto-opening browser |
+| `npx crg-dev-kit status` | Check if CRG is installed in current project |
+| `npx crg-dev-kit uninstall` | Remove CRG files from current project |
+| `npx crg-dev-kit help` | Show all commands |
+
+## What You Get
+
+### Setup Scripts
+- **Linux/macOS/WSL**: `bash setup-crg.sh --with-communities`
+- **Windows**: `.\setup-crg.ps1 -WithCommunities`
+- **Health check**: `bash check-crg.sh`
+- **AI config**: `CLAUDE.md` (drop in project root)
+- **Reference**: `crg-cheatsheet.pdf`
+
+### Token Analytics Dashboard
+
+The dashboard at `http://localhost:8742` shows:
+- **Token savings %** — average reduction vs reading full source files
+- **Cost estimates** — approximate $ savings at current LLM pricing
+- **Per-project breakdown** — sessions, files reviewed, savings by project
+- **Tool usage** — which CRG tools your team uses most
+
+Data stored locally in `~/.crg-analytics/` — zero telemetry.
+
+### REST API
+
+The dashboard exposes endpoints for programmatic access:
+
+```bash
+# Get all analytics
+curl http://localhost:8742/api/analytics
+
+# Download analytics report (Markdown)
+curl http://localhost:8742/api/report
+
+# Start a new session
+curl -X POST http://localhost:8742/api/session \
+  -H 'Content-Type: application/json' \
+  -d '{"project": "/path/to/repo", "operation": "code_review"}'
+
+# Log tool usage
+curl -X POST http://localhost:8742/api/session/{sessionId} \
+  -H 'Content-Type: application/json' \
+  -d '{"tool": "detect_changes", "count": 1}'
+
+# End session
+curl -X POST http://localhost:8742/api/session/{sessionId} \
+  -H 'Content-Type: application/json' \
+  -d '{"filesReviewed": 12, "avgLinesPerFile": 150}'
+```
+
+## For Team Leads
+
+Share this with your team:
+
+```bash
+# Everyone runs this in their project
+npx crg-dev-kit install
+bash setup-crg.sh --with-communities
+```
+
+Then open the dashboard to see team-wide analytics:
+```bash
+npx crg-dev-kit
+```
+
+## Token Savings
+
+Based on benchmarks across 6 real repos, CRG tools reduce token usage by **8.2x on average**:
+
+| Scenario | Without CRG | With CRG | Reduction |
+|----------|:---:|:---:|:---:|
+| 200-file project review | ~150k tokens | ~25k tokens | 6x |
+| Incremental review | ~150k tokens | ~8k tokens | 19x |
+| PR review | ~100k tokens | ~15k tokens | 6.7x |
+
+The dashboard tracks your actual savings in real time.
+
+## Requirements
+
+- Node.js >= 16
+- Python 3.10+ (for code-review-graph installation)
+- pipx (recommended) or pip
+
+## License
+
+MIT

package/assets/CLAUDE.md

@@ -0,0 +1,48 @@
+## MCP Tools: code-review-graph
+
+**Graph first, grep second.** Use CRG tools before Grep/Glob/Read — fewer tokens, structural context.
+
+### Tools that work (no extras)
+
+| Tool | When |
+|------|------|
+| `detect_changes` | Review changes — risk-scored, prioritized |
+| `get_review_context` | Token-efficient source snippets for review |
+| `get_impact_radius` | Blast radius of changed files (2-hop BFS) |
+| `query_graph` | 8 patterns: callers_of, callees_of, imports_of, importers_of, children_of, tests_for, inheritors_of, file_summary |
+| `semantic_search_nodes` | Find functions/classes by keyword |
+| `refactor_tool` | mode=rename (preview+apply), mode=dead_code, mode=suggest |
+| `apply_refactor` | Execute previewed rename (10min expiry) |
+| `find_large_functions` | Functions/classes over N lines |
+| `build_or_update_graph` | Build or refresh the graph |
+| `list_graph_stats` | Node/edge counts, health |
+| `cross_repo_search` | Search across registered repos |
+
+### Tools that need [communities] extra
+
+| Tool | Note |
+|------|------|
+| `get_architecture_overview` | **Returns empty without communities — no error** |
+| `list_communities` | Use min_size=20 to avoid token overflow |
+| `get_community` | include_members=true for deep dive |
+| `generate_wiki` | Also needs Ollama running |
+
+### Broken in v2.1.0 — skip these
+
+- `get_affected_flows` — depends on flows (broken)
+- `list_flows` / `get_flow` — trace_flows TypeError bug
+
+### Workflow
+
+1. Graph auto-updates via hooks on file save.
+2. `detect_changes` for code review.
+3. `query_graph pattern="tests_for"` for coverage check.
+4. `get_impact_radius` before merging.
+5. Fall back to Grep/Glob/Read only when graph doesn't cover it.
+
+### Gotchas
+
+- Communities return 0? Restart AI tool (MCP server caches old env).
+- Over-clustered? `list_communities(min_size=20)`.
+- Package name is `code-review-graph` NOT `crg`.
+- Linux: use pipx, not pip. Extras via `pipx inject`.

package/assets/README.md

@@ -0,0 +1,72 @@
+# code-review-graph — Dev Kit
+
+AI knowledge graph for your codebase. Gives your AI assistant (Claude Code, Cursor, etc.) structural understanding — callers, dependencies, test coverage, blast radius — without reading every file.
+
+## Quick Start
+
+### Windows (PowerShell)
+```powershell
+cd your-project
+.\setup-crg.ps1                          # basic install
+.\setup-crg.ps1 -WithCommunities         # + architecture view
+.\setup-crg.ps1 -WithAll                  # + semantic search (2GB download)
+```
+
+### Linux / macOS / WSL
+```bash
+cd your-project
+bash setup-crg.sh                         # basic install
+bash setup-crg.sh --with-communities      # + architecture view
+bash setup-crg.sh --with-all              # + semantic search (2GB download)
+```
+
+### Health Check
+```bash
+bash check-crg.sh                         # run anytime to verify
+```
+
+## What's in this kit
+
+| File | Purpose |
+|------|---------|
+| `setup-crg.sh` | Setup script for Linux/macOS/WSL |
+| `setup-crg.ps1` | Setup script for Windows |
+| `check-crg.sh` | Health check (run anytime) |
+| `CLAUDE.md` | Drop into project root — tells AI which tools to use |
+| `crg-cheatsheet.pdf` | One-page visual reference |
+| `.github/workflows/test-crg.yml` | CI workflow to validate on Windows + Ubuntu |
+
+## What the setup script does
+
+1. Detects OS and Python version
+2. Installs `code-review-graph` (pip on Windows, pipx on Linux)
+3. Configures MCP server for your AI tool
+4. Builds the knowledge graph
+5. Optionally installs extras (communities, embeddings)
+6. Runs community detection workaround (v2.1.0 bug)
+7. Adds `.code-review-graph/` to `.gitignore`
+8. Runs health check
+
+## What works after setup
+
+**13 tools work immediately** — code review, search, impact analysis, refactoring.
+
+**5 tools need `--with-communities`** — architecture overview, module clusters.
+
+**3 tools are broken in v2.1.0** — flow analysis (trace_flows TypeError). Skip these.
+
+## Known Issues (v2.1.0)
+
+| Issue | Impact | Workaround |
+|-------|--------|------------|
+| `architecture_overview` returns empty | Misleading — no error | Install communities extra |
+| `build` doesn't trigger Leiden | Communities stay 0 | Setup script handles this automatically |
+| `trace_flows` TypeError | Flows completely broken | No fix — wait for v2.2+ |
+| Over-clustering (400+ for 500 files) | Token overflow | Use `min_size=20` param |
+| `crg` is wrong package name | Installs different package | Always use `code-review-graph` |
+| PEP 668 on Linux | pip blocked | Setup script auto-detects, uses pipx |
+| MCP server caches old env | Extras don't activate | Restart AI tool after installing extras |
+
+## For CI
+
+Copy `.github/workflows/test-crg.yml` into your repo. Tests install + build + communities on both Windows and Ubuntu. Trigger manually from Actions tab.

package/assets/check-crg.sh

@@ -0,0 +1,34 @@
+#!/usr/bin/env bash
+# Quick health check — run anytime to verify CRG is working
+set -uo pipefail
+RED='\033[0;31m'; GREEN='\033[0;32m'; YELLOW='\033[1;33m'; CYAN='\033[0;36m'; NC='\033[0m'
+
+echo -e "${CYAN}code-review-graph health check${NC}"
+echo "──────────────────────────────"
+
+P=0; T=0
+check() {
+  T=$((T+1))
+  if eval "$2" &>/dev/null; then echo -e "${GREEN}✓${NC} $1"; P=$((P+1))
+  else echo -e "${RED}✗${NC} $1"; fi
+}
+
+PYTHON=$(command -v python3 || command -v python)
+
+check "Python 3.10+"        "$PYTHON -c 'import sys; assert sys.version_info >= (3,10)'"
+check "CRG installed"       "command -v code-review-graph"
+check "Graph DB exists"     "test -f .code-review-graph/graph.db"
+check "Nodes > 0"           "$PYTHON -c \"import sqlite3; assert sqlite3.connect('.code-review-graph/graph.db').execute('SELECT COUNT(*) FROM nodes').fetchone()[0] > 0\""
+check "Edges > 0"           "$PYTHON -c \"import sqlite3; assert sqlite3.connect('.code-review-graph/graph.db').execute('SELECT COUNT(*) FROM edges').fetchone()[0] > 0\""
+check "Communities > 0"     "$PYTHON -c \"import sqlite3; assert sqlite3.connect('.code-review-graph/graph.db').execute('SELECT COUNT(*) FROM communities').fetchone()[0] > 0\"" || true
+check "igraph importable"   "$PYTHON -c 'import igraph'" || true
+check "leidenalg importable" "$PYTHON -c 'import leidenalg'" || true
+
+echo "──────────────────────────────"
+echo -e "Result: ${GREEN}$P${NC}/$T passed"
+
+# Show graph stats
+if command -v code-review-graph &>/dev/null && [ -f ".code-review-graph/graph.db" ]; then
+  echo ""
+  code-review-graph status 2>/dev/null
+fi

package/assets/setup-crg.ps1

@@ -0,0 +1,182 @@
+# ─────────────────────────────────────────────────────────────
+# code-review-graph — Automated Setup Script (Windows)
+# Works on: Windows 10/11, PowerShell 5.1+
+# Usage: .\setup-crg.ps1 [-WithCommunities] [-WithEmbeddings] [-WithAll]
+# ─────────────────────────────────────────────────────────────
+param(
+    [switch]$WithCommunities,
+    [switch]$WithEmbeddings,
+    [switch]$WithAll
+)
+
+$ErrorActionPreference = "Stop"
+
+if ($WithAll) { $WithCommunities = $true; $WithEmbeddings = $true }
+
+function Info($msg)  { Write-Host "[INFO] $msg" -ForegroundColor Cyan }
+function Ok($msg)    { Write-Host "[OK] $msg" -ForegroundColor Green }
+function Warn($msg)  { Write-Host "[WARN] $msg" -ForegroundColor Yellow }
+function Fail($msg)  { Write-Host "[FAIL] $msg" -ForegroundColor Red; exit 1 }
+
+# ── Step 1: Check Python ──
+Info "Checking Python..."
+$python = $null
+foreach ($cmd in @("python", "python3", "py")) {
+    try {
+        $ver = & $cmd -c "import sys; print(f'{sys.version_info.major}.{sys.version_info.minor}')" 2>$null
+        $major = & $cmd -c "import sys; print(sys.version_info.major)" 2>$null
+        $minor = & $cmd -c "import sys; print(sys.version_info.minor)" 2>$null
+        if ([int]$major -ge 3 -and [int]$minor -ge 10) {
+            $python = $cmd
+            Ok "Python $ver found ($cmd)"
+            break
+        }
+    } catch {}
+}
+if (-not $python) { Fail "Python 3.10+ required. Install from https://python.org" }
+
+# ── Step 2: Install ──
+$installed = $false
+try { $null = & code-review-graph --version 2>$null; $installed = $true } catch {}
+
+if ($installed) {
+    $v = & code-review-graph --version 2>$null
+    Ok "code-review-graph already installed ($v)"
+} else {
+    Info "Installing code-review-graph..."
+    & $python -m pip install code-review-graph
+    if ($LASTEXITCODE -ne 0) { Fail "pip install failed. Try: $python -m pip install --user code-review-graph" }
+    Ok "Installed via pip"
+
+    # Verify on PATH
+    try { $null = & code-review-graph --version 2>$null }
+    catch {
+        Warn "code-review-graph not on PATH. Adding Python Scripts to PATH..."
+        $scriptsDir = & $python -c "import sysconfig; print(sysconfig.get_path('scripts'))" 2>$null
+        if ($scriptsDir) {
+            $env:PATH = "$scriptsDir;$env:PATH"
+            Warn "Added $scriptsDir to PATH for this session. Add permanently via System Settings."
+        }
+    }
+}
+
+# ── Step 3: Configure MCP ──
+Info "Configuring MCP server..."
+try {
+    & code-review-graph install --platform claude-code 2>$null
+    Ok "MCP server configured"
+} catch {
+    Warn "Auto-configure failed. Run manually: code-review-graph install"
+}
+
+# ── Step 4: Build graph ──
+if (-not (Test-Path ".code-review-graph/graph.db")) {
+    Info "Building knowledge graph (first build)..."
+    & code-review-graph build
+} else {
+    Info "Graph exists. Incremental update..."
+    try { & code-review-graph update --base HEAD~5 2>$null }
+    catch { & code-review-graph build }
+}
+
+Write-Host ""
+& code-review-graph status
+Write-Host ""
+
+# ── Step 5: Extras ──
+if ($WithCommunities) {
+    Info "Installing communities extra..."
+    & $python -m pip install "code-review-graph[communities]"
+    Ok "Communities deps installed"
+
+    Info "Rebuilding graph..."
+    & code-review-graph build
+
+    Info "Running community detection (v2.1.0 workaround)..."
+    & $python -c @"
+import sys, glob
+try:
+    from code_review_graph.graph import GraphStore
+    from code_review_graph.communities import detect_communities, store_communities
+    dbs = glob.glob('.code-review-graph/graph.db')
+    if not dbs:
+        print('No graph DB found')
+        sys.exit(0)
+    gs = GraphStore(dbs[0])
+    comms = detect_communities(gs)
+    store_communities(gs, comms)
+    print(f'Communities detected: {len(comms)}')
+except ImportError:
+    print('igraph/leidenalg not importable')
+except Exception as e:
+    print(f'Community detection failed: {e}')
+"@
+}
+
+if ($WithEmbeddings) {
+    Warn "Embeddings require PyTorch (~2GB download). Takes 5-10 minutes."
+    $reply = Read-Host "Continue? [y/N]"
+    if ($reply -eq 'y' -or $reply -eq 'Y') {
+        Info "Installing embeddings..."
+        & $python -m pip install "code-review-graph[embeddings]"
+        Ok "Embeddings installed. Use embed_graph MCP tool to compute vectors."
+    } else {
+        Info "Skipped embeddings."
+    }
+}
+
+# ── Step 6: .gitignore ──
+if (Test-Path ".gitignore") {
+    $content = Get-Content ".gitignore" -Raw -ErrorAction SilentlyContinue
+    if ($content -notmatch "code-review-graph") {
+        Add-Content ".gitignore" "`n# code-review-graph`n.code-review-graph/"
+        Ok "Added .code-review-graph/ to .gitignore"
+    }
+}
+
+# ── Step 7: Health check ──
+Write-Host ""
+Write-Host "═══════════════════════════════════════" -ForegroundColor Cyan
+Write-Host "  Health Check" -ForegroundColor Cyan
+Write-Host "═══════════════════════════════════════" -ForegroundColor Cyan
+
+$pass = 0; $total = 0
+
+function Check($name, $test) {
+    $script:total++
+    try {
+        $result = & $python -c $test 2>$null
+        if ($LASTEXITCODE -eq 0) { Ok $name; $script:pass++ }
+        else { Warn "$name - FAILED" }
+    } catch { Warn "$name - FAILED" }
+}
+
+$total++
+try { $null = & code-review-graph --version 2>$null; Ok "code-review-graph on PATH"; $pass++ }
+catch { Warn "code-review-graph on PATH - FAILED" }
+
+$total++
+if (Test-Path ".code-review-graph/graph.db") { Ok "Graph DB exists"; $pass++ }
+else { Warn "Graph DB exists - FAILED" }
+
+Check "Nodes > 0" "import sqlite3; db=sqlite3.connect('.code-review-graph/graph.db'); n=db.execute('SELECT COUNT(*) FROM nodes').fetchone()[0]; assert n > 0"
+Check "Edges > 0" "import sqlite3; db=sqlite3.connect('.code-review-graph/graph.db'); n=db.execute('SELECT COUNT(*) FROM edges').fetchone()[0]; assert n > 0"
+
+if ($WithCommunities) {
+    Check "Communities > 0" "import sqlite3; db=sqlite3.connect('.code-review-graph/graph.db'); n=db.execute('SELECT COUNT(*) FROM communities').fetchone()[0]; assert n > 0"
+}
+
+Write-Host ""
+Write-Host "Passed: $pass/$total" -ForegroundColor Green
+
+if ($pass -eq $total) {
+    Write-Host ""
+    Write-Host "Setup complete. Your AI assistant can now use the knowledge graph." -ForegroundColor Green
+    Write-Host ""
+    Write-Host 'Quick test - ask your AI:'
+    Write-Host '  "Use detect_changes to review my recent changes"'
+    Write-Host '  "Use query_graph to find callers of <function_name>"'
+} else {
+    Write-Host ""
+    Warn "Some checks failed. See warnings above."
+}

package/assets/setup-crg.sh

@@ -0,0 +1,242 @@
+#!/usr/bin/env bash
+# ─────────────────────────────────────────────────────────────
+# code-review-graph — Automated Setup Script
+# Works on: Ubuntu/Debian, macOS, WSL2
+# Usage: bash setup-crg.sh [--with-communities] [--with-embeddings] [--with-all]
+# ─────────────────────────────────────────────────────────────
+set -euo pipefail
+
+RED='\033[0;31m'; GREEN='\033[0;32m'; YELLOW='\033[1;33m'; CYAN='\033[0;36m'; NC='\033[0m'
+info()  { echo -e "${CYAN}[INFO]${NC} $1"; }
+ok()    { echo -e "${GREEN}[OK]${NC} $1"; }
+warn()  { echo -e "${YELLOW}[WARN]${NC} $1"; }
+fail()  { echo -e "${RED}[FAIL]${NC} $1"; exit 1; }
+
+INSTALL_COMMUNITIES=false
+INSTALL_EMBEDDINGS=false
+for arg in "$@"; do
+  case $arg in
+    --with-communities) INSTALL_COMMUNITIES=true ;;
+    --with-embeddings)  INSTALL_EMBEDDINGS=true ;;
+    --with-all)         INSTALL_COMMUNITIES=true; INSTALL_EMBEDDINGS=true ;;
+  esac
+done
+
+# ── Step 1: Check Python ──
+info "Checking Python..."
+PYTHON=""
+for cmd in python3 python; do
+  if command -v "$cmd" &>/dev/null; then
+    ver=$("$cmd" -c "import sys; print(f'{sys.version_info.major}.{sys.version_info.minor}')" 2>/dev/null)
+    major=$("$cmd" -c "import sys; print(sys.version_info.major)" 2>/dev/null)
+    minor=$("$cmd" -c "import sys; print(sys.version_info.minor)" 2>/dev/null)
+    if [ "$major" -ge 3 ] && [ "$minor" -ge 10 ]; then
+      PYTHON="$cmd"
+      ok "Python $ver found ($cmd)"
+      break
+    fi
+  fi
+done
+[ -z "$PYTHON" ] && fail "Python 3.10+ required. Install from https://python.org"
+
+# ── Step 2: Detect install method ──
+USE_PIPX=false
+if command -v code-review-graph &>/dev/null; then
+  ok "code-review-graph already installed ($(code-review-graph --version 2>/dev/null || echo 'unknown version'))"
+  # Detect if installed via pipx
+  if pipx list 2>/dev/null | grep -q "code-review-graph"; then
+    USE_PIPX=true
+    info "Installed via pipx"
+  else
+    info "Installed via pip"
+  fi
+else
+  info "Installing code-review-graph..."
+
+  # Try pip first
+  if $PYTHON -m pip install code-review-graph 2>/dev/null; then
+    ok "Installed via pip"
+  else
+    # pip blocked (PEP 668) — use pipx
+    warn "pip blocked by system (PEP 668). Trying pipx..."
+    if ! command -v pipx &>/dev/null; then
+      info "Installing pipx..."
+      if command -v apt &>/dev/null; then
+        sudo apt install -y pipx 2>/dev/null || $PYTHON -m pip install --user pipx
+      elif command -v brew &>/dev/null; then
+        brew install pipx
+      else
+        $PYTHON -m pip install --user pipx
+      fi
+      pipx ensurepath 2>/dev/null || true
+      export PATH="$HOME/.local/bin:$PATH"
+    fi
+    pipx install code-review-graph
+    USE_PIPX=true
+    ok "Installed via pipx"
+  fi
+fi
+
+# Verify on PATH
+if ! command -v code-review-graph &>/dev/null; then
+  export PATH="$HOME/.local/bin:$PATH"
+  if ! command -v code-review-graph &>/dev/null; then
+    fail "code-review-graph not found on PATH. Run: pipx ensurepath && source ~/.bashrc"
+  fi
+fi
+
+# ── Step 3: Configure MCP server ──
+info "Configuring MCP server..."
+# Detect platform
+PLATFORM="claude-code"
+if [ -d "$HOME/.cursor" ] || [ -d "$HOME/Library/Application Support/Cursor" ]; then
+  PLATFORM="all"
+fi
+code-review-graph install --platform "$PLATFORM" --no-hooks 2>/dev/null || \
+  code-review-graph install --platform claude-code 2>/dev/null || \
+  warn "Could not auto-configure MCP. Run manually: code-review-graph install"
+ok "MCP server configured for $PLATFORM"
+
+# ── Step 4: Build graph ──
+if [ ! -f ".code-review-graph/graph.db" ]; then
+  info "Building knowledge graph (first build)..."
+  code-review-graph build
+else
+  info "Graph exists. Running incremental update..."
+  code-review-graph update --base HEAD~5 2>/dev/null || code-review-graph build
+fi
+
+# Show stats
+echo ""
+code-review-graph status
+echo ""
+
+# ── Step 5: Install extras ──
+install_extra() {
+  local name="$1"
+  shift
+  local deps=("$@")
+
+  info "Installing $name..."
+  if $USE_PIPX; then
+    pipx inject code-review-graph "${deps[@]}"
+  else
+    $PYTHON -m pip install "code-review-graph[$name]" 2>/dev/null || \
+      $PYTHON -m pip install "${deps[@]}"
+  fi
+  ok "$name installed"
+}
+
+if $INSTALL_COMMUNITIES; then
+  install_extra "communities" igraph leidenalg
+
+  info "Rebuilding graph with community detection..."
+  code-review-graph build
+
+  # Workaround: v2.1.0 may not auto-trigger Leiden
+  info "Running community detection (v2.1.0 workaround)..."
+
+  # Detect the right Python — pipx venv or system
+  CRG_PYTHON="$PYTHON"
+  if $USE_PIPX; then
+    PIPX_PYTHON="$HOME/.local/share/pipx/venvs/code-review-graph/bin/python"
+    if [ -f "$PIPX_PYTHON" ]; then
+      CRG_PYTHON="$PIPX_PYTHON"
+    fi
+  fi
+
+  $CRG_PYTHON -c "
+import sys, glob
+try:
+    from code_review_graph.graph import GraphStore
+    from code_review_graph.communities import detect_communities, store_communities
+    dbs = glob.glob('.code-review-graph/graph.db')
+    if not dbs:
+        print('No graph DB found — skipping community detection')
+        sys.exit(0)
+    gs = GraphStore(dbs[0])
+    comms = detect_communities(gs)
+    store_communities(gs, comms)
+    print(f'Communities detected: {len(comms)}')
+except ImportError as e:
+    print(f'Import failed: {e}')
+    print('Try restarting your AI tool, then run: code-review-graph build')
+except Exception as e:
+    print(f'Community detection failed: {e}')
+" 2>/dev/null || warn "Community detection workaround failed. Restart AI tool + rebuild."
+fi
+
+if $INSTALL_EMBEDDINGS; then
+  warn "Embeddings require PyTorch (~2GB download). This will take 5-10 minutes."
+  read -p "Continue? [y/N] " -n 1 -r
+  echo
+  if [[ $REPLY =~ ^[Yy]$ ]]; then
+    install_extra "embeddings" sentence-transformers
+    ok "Embeddings installed. Run embed_graph MCP tool to compute vectors."
+  else
+    info "Skipped embeddings."
+  fi
+fi
+
+# ── Step 6: Add .gitignore entry ──
+if [ -f ".gitignore" ]; then
+  if ! grep -q "code-review-graph" .gitignore 2>/dev/null; then
+    echo -e "\n# code-review-graph\n.code-review-graph/" >> .gitignore
+    ok "Added .code-review-graph/ to .gitignore"
+  fi
+fi
+
+# ── Step 7: Health check ──
+echo ""
+echo -e "${CYAN}═══════════════════════════════════════${NC}"
+echo -e "${CYAN}  Health Check${NC}"
+echo -e "${CYAN}═══════════════════════════════════════${NC}"
+
+PASS=0; TOTAL=0
+
+check() {
+  TOTAL=$((TOTAL + 1))
+  if eval "$2" &>/dev/null; then
+    ok "$1"
+    PASS=$((PASS + 1))
+  else
+    warn "$1 — FAILED"
+  fi
+}
+
+check "code-review-graph on PATH" "command -v code-review-graph"
+check "Graph DB exists" "test -f .code-review-graph/graph.db"
+check "Nodes > 0" "$PYTHON -c \"
+import sqlite3; db=sqlite3.connect('.code-review-graph/graph.db')
+n=db.execute('SELECT COUNT(*) FROM nodes').fetchone()[0]
+assert n > 0, f'nodes={n}'
+\""
+check "Edges > 0" "$PYTHON -c \"
+import sqlite3; db=sqlite3.connect('.code-review-graph/graph.db')
+n=db.execute('SELECT COUNT(*) FROM edges').fetchone()[0]
+assert n > 0, f'edges={n}'
+\""
+
+if $INSTALL_COMMUNITIES; then
+  check "Communities > 0" "$PYTHON -c \"
+import sqlite3; db=sqlite3.connect('.code-review-graph/graph.db')
+n=db.execute('SELECT COUNT(*) FROM communities').fetchone()[0]
+assert n > 0, f'communities={n}'
+\""
+fi
+
+echo ""
+echo -e "${GREEN}Passed: $PASS/$TOTAL${NC}"
+
+if [ "$PASS" -eq "$TOTAL" ]; then
+  echo ""
+  echo -e "${GREEN}Setup complete. Your AI assistant can now use the knowledge graph.${NC}"
+  echo ""
+  echo "Quick test — ask your AI:"
+  echo '  "Use detect_changes to review my recent changes"'
+  echo '  "Use query_graph to find callers of <function_name>"'
+  echo '  "Use find_large_functions with min_lines=100"'
+else
+  echo ""
+  warn "Some checks failed. See warnings above."
+fi