@winci/local-rag 0.2.1

package/hooks/scripts/session-start.sh

@@ -0,0 +1,11 @@
+#!/bin/bash
+# SessionStart hook: ensure the index is warm on session start.
+# The MCP server handles auto-indexing, so this is a lightweight check
+# that logs index status for visibility.
+
+STATUS=$(bunx @winci/local-rag status 2>/dev/null)
+if [ $? -eq 0 ]; then
+  echo "$STATUS" >&2
+fi
+
+exit 0

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@winci/local-rag",
+  "version": "0.2.1",
+  "description": "Semantic search for your codebase — local-first RAG MCP server with hybrid search, AST-aware chunking, and usage analytics",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/TheWinci/local-rag-mcp.git"
+  },
+  "keywords": [
+    "mcp",
+    "rag",
+    "semantic-search",
+    "vector-search",
+    "sqlite-vec",
+    "embeddings",
+    "claude-code",
+    "model-context-protocol",
+    "local-first",
+    "bun"
+  ],
+  "bin": {
+    "local-rag": "src/main.ts"
+  },
+  "files": [
+    "src/",
+    ".claude-plugin/",
+    ".mcp.json",
+    "skills/",
+    "hooks/",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "server": "bun run src/main.ts serve",
+    "cli": "bun run src/main.ts",
+    "test": "bun test tests/ 2>&1; EXIT=$?; if [ $EXIT -eq 133 ]; then printf '\\n[note] Exit code 133 suppressed — known Bun crash on macOS Silicon during process cleanup (github.com/oven-sh/bun/issues/19917). All tests passed.\\n'; exit 0; else exit $EXIT; fi",
+    "bench": "bun test benchmarks/"
+  },
+  "dependencies": {
+    "@huggingface/transformers": "^3.4.0",
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "code-chunk": "^0.1.13",
+    "gray-matter": "^4.0.3",
+    "sqlite-vec": "^0.1.6",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.3.11"
+  }
+}

package/skills/local-rag/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: local-rag
+description: Semantic search, code navigation, and conversation memory for the current project. Use automatically when searching code, finding usages, navigating dependencies, or recalling past discussions.
+---
+
+This project has a local RAG index (local-rag). Use these MCP tools proactively:
+
+- **`search`**: Discover which files are relevant to a topic. Returns file paths
+  with snippet previews — use this when you need to know *where* something is.
+- **`read_relevant`**: Get the actual content of relevant semantic chunks —
+  individual functions, classes, or markdown sections — ranked by relevance.
+  Results include exact line ranges (`src/db.ts:42-67`) so you can navigate
+  directly to the edit location. Use this instead of `search` + `Read` when
+  you need the content itself.
+- **`project_map`**: When you need to understand how files relate to each other,
+  generate a dependency graph. Use `focus` to zoom into a specific file's
+  neighborhood.
+- **`search_conversation`**: Search past conversation history to recall previous
+  decisions, discussions, and tool outputs. Use this before re-investigating
+  something that may have been discussed in an earlier session.
+- **`create_checkpoint`**: Mark important moments — decisions, milestones,
+  blockers, direction changes. Do this after completing features, making key
+  decisions, or changing direction.
+- **`list_checkpoints`** / **`search_checkpoints`**: Review or search past
+  checkpoints to understand project history and prior decisions.
+- **`index_files`**: If you've created or modified files and want them searchable,
+  re-index the project directory.
+- **`search_analytics`**: Check what queries return no results or low-relevance
+  results — this reveals documentation gaps.
+- **`search_symbols`**: When you know a symbol name (function, class, type, etc.),
+  find it directly by name instead of using semantic search.
+- **`find_usages`**: Before changing a function or type, find all its call sites.
+  Use this to understand the blast radius of a rename or API change.
+- **`git_context`**: At the start of a session, call this to see what files have
+  already been modified, recent commits, and which changed files are in the index.
+- **`annotate`**: Attach a persistent note to a file or symbol — "known race
+  condition", "don't refactor until auth rewrite lands", etc. Notes surface
+  inline in `read_relevant` results automatically.
+- **`get_annotations`**: Retrieve all notes for a file, or search semantically
+  across all annotations.
+- **`write_relevant`**: Before adding new code or docs, find the best insertion
+  point — returns the most semantically appropriate file and anchor.

package/src/cli/commands/analytics.ts

@@ -0,0 +1,58 @@
+import { resolve } from "path";
+import { RagDB } from "../../db";
+
+export async function analyticsCommand(args: string[], getFlag: (flag: string) => string | undefined) {
+  const dir = resolve(args[1] && !args[1].startsWith("--") ? args[1] : ".");
+  const days = parseInt(getFlag("--days") || "30", 10);
+  const db = new RagDB(dir);
+  const analytics = db.getAnalytics(days);
+
+  const zeroCount = analytics.zeroResultQueries.reduce((s, q) => s + q.count, 0);
+  const zeroRate = analytics.totalQueries > 0
+    ? ((zeroCount / analytics.totalQueries) * 100).toFixed(0)
+    : "0";
+
+  console.log(`Search analytics (last ${days} days):`);
+  console.log(`  Total queries:    ${analytics.totalQueries}`);
+  console.log(`  Avg results:      ${analytics.avgResultCount.toFixed(1)}`);
+  console.log(`  Avg top score:    ${analytics.avgTopScore?.toFixed(2) ?? "n/a"}`);
+  console.log(`  Zero-result rate: ${zeroRate}% (${zeroCount} queries)`);
+
+  if (analytics.topSearchedTerms.length > 0) {
+    console.log("\nTop searches:");
+    for (const t of analytics.topSearchedTerms) {
+      console.log(`  ${t.count}× "${t.query}"`);
+    }
+  }
+
+  if (analytics.zeroResultQueries.length > 0) {
+    console.log("\nZero-result queries (consider indexing these topics):");
+    for (const q of analytics.zeroResultQueries) {
+      console.log(`  ${q.count}× "${q.query}"`);
+    }
+  }
+
+  if (analytics.lowScoreQueries.length > 0) {
+    console.log("\nLow-relevance queries (top score < 0.3):");
+    for (const q of analytics.lowScoreQueries) {
+      console.log(`  "${q.query}" (score: ${q.topScore.toFixed(2)})`);
+    }
+  }
+
+  // Trend comparison vs prior period
+  const trend = db.getAnalyticsTrend(days);
+  if (trend.previous.totalQueries > 0 || trend.current.totalQueries > 0) {
+    const arrow = (delta: number) => delta > 0 ? `+${delta}` : `${delta}`;
+    const pctArrow = (delta: number) =>
+      delta > 0 ? `+${(delta * 100).toFixed(1)}%` : `${(delta * 100).toFixed(1)}%`;
+
+    console.log(`\nTrend (current ${days}d vs prior ${days}d):`);
+    console.log(`  Queries:          ${trend.current.totalQueries} (${arrow(trend.delta.queries)})`);
+    if (trend.delta.avgTopScore !== null) {
+      console.log(`  Avg top score:    ${trend.current.avgTopScore?.toFixed(2)} (${trend.delta.avgTopScore >= 0 ? "+" : ""}${trend.delta.avgTopScore.toFixed(2)})`);
+    }
+    console.log(`  Zero-result rate: ${(trend.current.zeroResultRate * 100).toFixed(0)}% (${pctArrow(trend.delta.zeroResultRate)})`);
+  }
+
+  db.close();
+}

package/src/cli/commands/benchmark.ts

@@ -0,0 +1,30 @@
+import { resolve } from "path";
+import { RagDB } from "../../db";
+import { loadConfig } from "../../config";
+import { loadBenchmarkQueries, runBenchmark, formatBenchmarkReport } from "../../search/benchmark";
+
+export async function benchmarkCommand(args: string[], getFlag: (flag: string) => string | undefined) {
+  const file = args[1];
+  if (!file) {
+    console.error("Usage: local-rag benchmark <file> [--dir D] [--top N]");
+    process.exit(1);
+  }
+
+  const dir = resolve(getFlag("--dir") || ".");
+  const db = new RagDB(dir);
+  const config = await loadConfig(dir);
+  const top = parseInt(getFlag("--top") || String(config.benchmarkTopK), 10);
+
+  const queries = await loadBenchmarkQueries(resolve(file));
+  console.log(`Running ${queries.length} benchmark queries against ${dir}...\n`);
+
+  const summary = await runBenchmark(queries, db, dir, top);
+  console.log(formatBenchmarkReport(summary, top));
+
+  db.close();
+
+  // Exit with non-zero if below thresholds
+  if (summary.recallAtK < config.benchmarkMinRecall || summary.mrr < config.benchmarkMinMrr) {
+    process.exit(1);
+  }
+}

package/src/cli/commands/checkpoint.ts

@@ -0,0 +1,85 @@
+import { resolve } from "path";
+import { RagDB } from "../../db";
+import { embed } from "../../embeddings/embed";
+import { discoverSessions } from "../../conversation/parser";
+
+export async function checkpointCommand(args: string[], getFlag: (flag: string) => string | undefined) {
+  const subCommand = args[1];
+  const dir = resolve(getFlag("--dir") || ".");
+  const db = new RagDB(dir);
+
+  if (subCommand === "create") {
+    const type = args[2];
+    const title = args[3];
+    const summary = args[4];
+    if (!type || !title || !summary) {
+      console.error("Usage: local-rag checkpoint create <type> <title> <summary> [--dir D] [--files f1,f2] [--tags t1,t2]");
+      process.exit(1);
+    }
+
+    const filesStr = getFlag("--files");
+    const tagsStr = getFlag("--tags");
+    const filesInvolved = filesStr ? filesStr.split(",").map((f) => f.trim()) : [];
+    const tags = tagsStr ? tagsStr.split(",").map((t) => t.trim()) : [];
+
+    const sessions = discoverSessions(dir);
+    const sessionId = sessions.length > 0 ? sessions[0].sessionId : "unknown";
+    const turnCount = db.getTurnCount(sessionId);
+    const turnIndex = Math.max(0, turnCount - 1);
+
+    const embedding = await embed(`${title}. ${summary}`);
+    const id = db.createCheckpoint(
+      sessionId, turnIndex, new Date().toISOString(),
+      type, title, summary, filesInvolved, tags, embedding
+    );
+    console.log(`Checkpoint #${id} created: [${type}] ${title}`);
+  } else if (subCommand === "list") {
+    const type = getFlag("--type");
+    const top = parseInt(getFlag("--top") || "20", 10);
+    const checkpoints = db.listCheckpoints(undefined, type, top);
+
+    if (checkpoints.length === 0) {
+      console.log("No checkpoints found.");
+    } else {
+      for (const cp of checkpoints) {
+        const tagStr = cp.tags.length > 0 ? ` [${cp.tags.join(", ")}]` : "";
+        console.log(`#${cp.id} [${cp.type}] ${cp.title}${tagStr}`);
+        console.log(`  ${cp.timestamp} (turn ${cp.turnIndex})`);
+        console.log(`  ${cp.summary}`);
+        if (cp.filesInvolved.length > 0) {
+          console.log(`  Files: ${cp.filesInvolved.join(", ")}`);
+        }
+        console.log();
+      }
+    }
+  } else if (subCommand === "search") {
+    const query = args[2];
+    if (!query) {
+      console.error("Usage: local-rag checkpoint search <query> [--dir D] [--type T] [--top N]");
+      process.exit(1);
+    }
+
+    const type = getFlag("--type");
+    const top = parseInt(getFlag("--top") || "5", 10);
+    const queryEmb = await embed(query);
+    const results = db.searchCheckpoints(queryEmb, top, type);
+
+    if (results.length === 0) {
+      console.log("No matching checkpoints found.");
+    } else {
+      for (const cp of results) {
+        console.log(`${cp.score.toFixed(4)}  #${cp.id} [${cp.type}] ${cp.title}`);
+        console.log(`  ${cp.summary}`);
+        if (cp.filesInvolved.length > 0) {
+          console.log(`  Files: ${cp.filesInvolved.join(", ")}`);
+        }
+        console.log();
+      }
+    }
+  } else {
+    console.error("Usage: local-rag checkpoint <create|list|search>");
+    process.exit(1);
+  }
+
+  db.close();
+}

package/src/cli/commands/conversation.ts

@@ -0,0 +1,102 @@
+import { resolve } from "path";
+import { RagDB } from "../../db";
+import { loadConfig } from "../../config";
+import { embed } from "../../embeddings/embed";
+import { discoverSessions } from "../../conversation/parser";
+import { indexConversation } from "../../conversation/indexer";
+
+export async function conversationCommand(args: string[], getFlag: (flag: string) => string | undefined) {
+  const subCommand = args[1];
+  const dir = resolve(getFlag("--dir") || ".");
+  const db = new RagDB(dir);
+
+  if (subCommand === "search") {
+    const query = args[2];
+    if (!query) {
+      console.error("Usage: local-rag conversation search <query> [--dir D] [--top N]");
+      process.exit(1);
+    }
+
+    const config = await loadConfig(dir);
+    const top = parseInt(getFlag("--top") || String(config.searchTopK), 10);
+
+    // Ensure conversations are indexed
+    const sessions = discoverSessions(dir);
+    for (const session of sessions) {
+      const existing = db.getSession(session.sessionId);
+      if (!existing || existing.mtime < session.mtime) {
+        await indexConversation(session.jsonlPath, session.sessionId, db);
+      }
+    }
+
+    // Hybrid search
+    const queryEmb = await embed(query);
+    const vecResults = db.searchConversation(queryEmb, top);
+    let bm25Results: typeof vecResults = [];
+    try {
+      bm25Results = db.textSearchConversation(query, top);
+    } catch { /* FTS can fail on special chars */ }
+
+    const merged = new Map<number, (typeof vecResults)[0]>();
+    for (const r of vecResults) {
+      merged.set(r.turnId, { ...r, score: r.score * config.hybridWeight });
+    }
+    for (const r of bm25Results) {
+      const existing = merged.get(r.turnId);
+      if (existing) {
+        existing.score += r.score * (1 - config.hybridWeight);
+      } else {
+        merged.set(r.turnId, { ...r, score: r.score * (1 - config.hybridWeight) });
+      }
+    }
+
+    const results = [...merged.values()].sort((a, b) => b.score - a.score).slice(0, top);
+
+    if (results.length === 0) {
+      console.log("No conversation results found.");
+    } else {
+      for (const r of results) {
+        const tools = r.toolsUsed.length > 0 ? ` [${r.toolsUsed.join(", ")}]` : "";
+        console.log(`Turn ${r.turnIndex} (${r.timestamp})${tools}`);
+        console.log(`  ${r.snippet.slice(0, 200)}`);
+        if (r.filesReferenced.length > 0) {
+          console.log(`  Files: ${r.filesReferenced.slice(0, 5).join(", ")}`);
+        }
+        console.log();
+      }
+    }
+  } else if (subCommand === "sessions") {
+    const sessions = discoverSessions(dir);
+    if (sessions.length === 0) {
+      console.log("No conversation sessions found for this project.");
+    } else {
+      for (const s of sessions) {
+        const indexed = db.getSession(s.sessionId);
+        const status = indexed ? `${indexed.turnCount} turns indexed` : "not indexed";
+        const date = new Date(s.mtime).toISOString().slice(0, 19);
+        console.log(`  ${s.sessionId.slice(0, 8)}...  ${date}  ${status}  (${(s.size / 1024).toFixed(0)}KB)`);
+      }
+    }
+  } else if (subCommand === "index") {
+    const sessions = discoverSessions(dir);
+    if (sessions.length === 0) {
+      console.log("No conversation sessions found for this project.");
+    } else {
+      console.log(`Found ${sessions.length} sessions, indexing...`);
+      let totalTurns = 0;
+      for (const session of sessions) {
+        const result = await indexConversation(session.jsonlPath, session.sessionId, db);
+        totalTurns += result.turnsIndexed;
+        if (result.turnsIndexed > 0) {
+          console.log(`  ${session.sessionId.slice(0, 8)}...: ${result.turnsIndexed} turns`);
+        }
+      }
+      console.log(`Done: ${totalTurns} turns indexed across ${sessions.length} sessions`);
+    }
+  } else {
+    console.error("Usage: local-rag conversation <search|sessions|index>");
+    process.exit(1);
+  }
+
+  db.close();
+}

package/src/cli/commands/demo.ts

@@ -0,0 +1,119 @@
+import { resolve } from "path";
+import { RagDB } from "../../db";
+import { loadConfig } from "../../config";
+import { indexDirectory } from "../../indexing/indexer";
+import { search, searchChunks } from "../../search/hybrid";
+import { cliProgress } from "../progress";
+
+const CYAN = "\x1b[36m";
+const GREEN = "\x1b[32m";
+const YELLOW = "\x1b[33m";
+const DIM = "\x1b[2m";
+const BOLD = "\x1b[1m";
+const RESET = "\x1b[0m";
+
+function header(text: string) {
+  console.log(`\n${BOLD}${CYAN}--- ${text} ---${RESET}\n`);
+}
+
+function pause(ms: number): Promise<void> {
+  return new Promise((r) => setTimeout(r, ms));
+}
+
+export async function demoCommand(args: string[]) {
+  const dir = resolve(args[1] && !args[1].startsWith("--") ? args[1] : ".");
+
+  console.log(`${BOLD}local-rag demo${RESET}`);
+  console.log(`${DIM}Running against: ${dir}${RESET}`);
+
+  // Step 1: Index
+  header("1. Index your project");
+  console.log("Indexing files with AST-aware chunking...\n");
+
+  const db = new RagDB(dir);
+  const config = await loadConfig(dir);
+  const result = await indexDirectory(dir, db, config, cliProgress);
+  console.log(
+    `\n${GREEN}Done:${RESET} ${result.indexed} indexed, ${result.skipped} skipped, ${result.pruned} pruned`
+  );
+  await pause(500);
+
+  // Step 2: Semantic search
+  header("2. Semantic search");
+  const demoQuery = "how does search work";
+  console.log(`${DIM}> search "${demoQuery}"${RESET}\n`);
+
+  const searchResults = await search(demoQuery, db, 3, 0, config.hybridWeight, config.enableReranking);
+  if (searchResults.length > 0) {
+    for (const r of searchResults) {
+      console.log(`  ${YELLOW}${r.score.toFixed(4)}${RESET}  ${r.path}`);
+      const preview = r.snippets[0]?.slice(0, 100).replace(/\n/g, " ");
+      console.log(`  ${DIM}${preview}...${RESET}\n`);
+    }
+  } else {
+    console.log("  No results — try a query related to your project.");
+  }
+  await pause(500);
+
+  // Step 3: Chunk-level retrieval
+  header("3. Chunk-level retrieval (read_relevant)");
+  console.log(`${DIM}> read_relevant "${demoQuery}"${RESET}\n`);
+
+  const chunks = await searchChunks(demoQuery, db, 2, 0.3, config.hybridWeight, config.enableReranking);
+  if (chunks.length > 0) {
+    for (const r of chunks) {
+      const lineRange = r.startLine != null && r.endLine != null ? `:${r.startLine}-${r.endLine}` : "";
+      const entity = r.entityName ? `  ${CYAN}${r.entityName}${RESET}` : "";
+      console.log(`  ${YELLOW}[${r.score.toFixed(2)}]${RESET} ${r.path}${lineRange}${entity}`);
+      // Show first 3 lines of content
+      const lines = r.content.split("\n").slice(0, 3);
+      for (const line of lines) {
+        console.log(`  ${DIM}${line}${RESET}`);
+      }
+      console.log();
+    }
+  } else {
+    console.log("  No chunks above threshold.");
+  }
+  await pause(500);
+
+  // Step 4: Symbol search
+  header("4. Symbol search (find_usages)");
+  const symbols = db.searchSymbols("search", false, undefined, 3);
+  if (symbols.length > 0) {
+    console.log(`${DIM}> search_symbols "search"${RESET}\n`);
+    for (const s of symbols) {
+      console.log(`  ${s.path}  ${CYAN}${s.symbolName}${RESET} (${s.symbolType})`);
+    }
+  } else {
+    console.log("  No exported symbols found matching 'search'.");
+  }
+  await pause(500);
+
+  // Step 5: Project map
+  header("5. Project map");
+  console.log(
+    `${DIM}The project_map tool generates a Mermaid dependency graph\n` +
+    `showing how files import from each other. Run:${RESET}\n\n` +
+    `  local-rag map ${dir}\n`
+  );
+
+  // Step 6: Unique features summary
+  header("6. What no other tool does");
+  console.log(`  ${GREEN}search_conversation${RESET}  Search past AI session history`);
+  console.log(`  ${GREEN}create_checkpoint${RESET}    Mark decisions, milestones, blockers`);
+  console.log(`  ${GREEN}annotate${RESET}             Attach notes to files/symbols (surface in search)`);
+  console.log(`  ${GREEN}find_usages${RESET}          Find all call sites before refactoring`);
+  console.log(`  ${GREEN}project_map${RESET}          Mermaid dependency graph`);
+  console.log(`  ${GREEN}git_context${RESET}          Uncommitted changes + index status`);
+  console.log(`  ${GREEN}search_analytics${RESET}     Find documentation gaps`);
+  console.log(`  ${GREEN}write_relevant${RESET}       Find best insertion point for new code`);
+
+  console.log(`\n${BOLD}Done.${RESET} Add to your editor with:\n`);
+  console.log(`  ${DIM}# Claude Code (plugin)${RESET}`);
+  console.log(`  /plugin install local-rag@claude-plugins-official\n`);
+  console.log(`  ${DIM}# Any MCP client${RESET}`);
+  console.log(`  bunx @winci/local-rag serve\n`);
+
+  db.close();
+}

package/src/cli/commands/eval.ts

@@ -0,0 +1,31 @@
+import { resolve } from "path";
+import { RagDB } from "../../db";
+import { loadConfig } from "../../config";
+import { loadEvalTasks, runEval, formatEvalReport, saveEvalTraces } from "../../search/eval";
+
+export async function evalCommand(args: string[], getFlag: (flag: string) => string | undefined) {
+  const file = args[1];
+  if (!file) {
+    console.error("Usage: local-rag eval <file> [--dir D] [--top N] [--out F]");
+    process.exit(1);
+  }
+
+  const dir = resolve(getFlag("--dir") || ".");
+  const outPath = getFlag("--out");
+  const db = new RagDB(dir);
+  const config = await loadConfig(dir);
+  const top = parseInt(getFlag("--top") || String(config.benchmarkTopK), 10);
+
+  const tasks = await loadEvalTasks(resolve(file));
+  console.log(`Running A/B eval with ${tasks.length} tasks against ${dir}...\n`);
+
+  const summary = await runEval(tasks, db, dir, top);
+  console.log(formatEvalReport(summary));
+
+  if (outPath) {
+    await saveEvalTraces(summary.traces, resolve(outPath));
+    console.log(`\nTraces saved to ${outPath}`);
+  }
+
+  db.close();
+}

package/src/cli/commands/index-cmd.ts

@@ -0,0 +1,26 @@
+import { resolve } from "path";
+import { RagDB } from "../../db";
+import { loadConfig } from "../../config";
+import { indexDirectory } from "../../indexing/indexer";
+import { cliProgress } from "../progress";
+
+export async function indexCommand(args: string[], getFlag: (flag: string) => string | undefined) {
+  const dir = resolve(args[1] && !args[1].startsWith("--") ? args[1] : ".");
+  const db = new RagDB(dir);
+  const config = await loadConfig(dir);
+
+  const patternsStr = getFlag("--patterns");
+  if (patternsStr) {
+    config.include = patternsStr.split(",").map((p) => p.trim());
+  }
+
+  console.log(`Indexing ${dir}...`);
+  const result = await indexDirectory(dir, db, config, cliProgress);
+  console.log(
+    `\nDone: ${result.indexed} indexed, ${result.skipped} skipped, ${result.pruned} pruned`
+  );
+  if (result.errors.length > 0) {
+    console.error(`Errors: ${result.errors.join("\n  ")}`);
+  }
+  db.close();
+}

package/src/cli/commands/init.ts

@@ -0,0 +1,35 @@
+import { resolve } from "path";
+import { RagDB } from "../../db";
+import { loadConfig } from "../../config";
+import { indexDirectory } from "../../indexing/indexer";
+import { runSetup, mcpConfigSnippet, detectAgentHints, confirm } from "../setup";
+import { cliProgress } from "../progress";
+
+export async function initCommand(args: string[], getFlag: (flag: string) => string | undefined) {
+  const dir = resolve(args[1] && !args[1].startsWith("--") ? args[1] : ".");
+  const { actions } = await runSetup(dir);
+  if (actions.length === 0) {
+    console.log("Already set up — nothing to do.");
+  } else {
+    for (const action of actions) console.log(action);
+  }
+
+  console.log("\nAdd this to your agent's MCP config (mcpServers):\n");
+  console.log(mcpConfigSnippet(dir));
+  const hints = detectAgentHints(dir);
+  console.log();
+  for (const hint of hints) console.log(`  ${hint}`);
+
+  console.log();
+  const shouldIndex = await confirm("Index project now? [Y/n] ");
+  if (shouldIndex) {
+    const db = new RagDB(dir);
+    const config = await loadConfig(dir);
+    console.log(`Indexing ${dir}...`);
+    const result = await indexDirectory(dir, db, config, cliProgress);
+    console.log(
+      `\nDone: ${result.indexed} indexed, ${result.skipped} skipped, ${result.pruned} pruned`
+    );
+    db.close();
+  }
+}

package/src/cli/commands/map.ts

@@ -0,0 +1,21 @@
+import { resolve } from "path";
+import { RagDB } from "../../db";
+import { generateProjectMap } from "../../graph/resolver";
+
+export async function mapCommand(args: string[], getFlag: (flag: string) => string | undefined) {
+  const dir = resolve(args[1] && !args[1].startsWith("--") ? args[1] : ".");
+  const db = new RagDB(dir);
+  const focus = getFlag("--focus");
+  const zoom = (getFlag("--zoom") || "file") as "file" | "directory";
+  const max = parseInt(getFlag("--max") || "50", 10);
+
+  const map = generateProjectMap(db, {
+    projectDir: dir,
+    focus: focus ?? undefined,
+    zoom,
+    maxNodes: max,
+  });
+
+  console.log(map);
+  db.close();
+}

package/src/cli/commands/remove.ts

@@ -0,0 +1,15 @@
+import { resolve } from "path";
+import { RagDB } from "../../db";
+
+export async function removeCommand(args: string[]) {
+  const file = args[1];
+  if (!file) {
+    console.error("Usage: local-rag remove <file> [dir]");
+    process.exit(1);
+  }
+  const dir = resolve(args[2] && !args[2].startsWith("--") ? args[2] : ".");
+  const db = new RagDB(dir);
+  const removed = db.removeFile(resolve(file));
+  console.log(removed ? `Removed ${file}` : `${file} was not in the index`);
+  db.close();
+}