@misterhuydo/cairn-mcp 1.1.1 → 1.2.0

package/.cairn/bundles/full-source.txt

@@ -0,0 +1,2959 @@
+### File: cairn-mcp-plan.md
+# Cairn MCP Server — Implementation Plan
+## Giving Claude Code Persistent Institutional Memory (Polyglot Edition)
+---
+## The Problem
+Claude is **stateless**. Every session starts at zero knowledge. On a multi-repo enterprise system
+with Java backends, TypeScript frontends, and Vue components, this means 50% of every session is
+"Archaeology" — just finding where things live before any real work can begin.
+**The fix:** A local MCP server that acts as a persistent polyglot knowledge graph. Index once, query forever.
+---
+## Supported Languages
+| Language | Extensions | What Cairn Extracts |
+|----------|-----------|---------------------|
+| Java | `.java` | package, class/interface/enum/record, imports, methods |
+| TypeScript | `.ts`, `.tsx` | imports, exports, classes, interfaces, functions, types |
+| JavaScript | `.js`, `.jsx`, `.mjs` | imports, exports, classes, functions |
+| Vue | `.vue` | extracts `<script>` block → parsed as TS/JS |
+| Python | `.py` | imports, classes, functions, decorators |
+| XML/HTML | `.xml`, `.html` | bean ids, component names, key attributes |
+| Config | `.yml`, `.yaml`, `.properties`, `.env` | top-level keys, service names |
+| SQL | `.sql` | table names, stored procedures, views |
+| Markdown | `.md` | headings, used for README/doc indexing |
+| Build files | `pom.xml`, `package.json`, `build.gradle` | dependency declarations |
+---
+## Architecture Overview
+```
+Your Polyglot Repos (Java / TS / Vue / Python / ...)
+            │
+            ├──────────────────────────────────────────┐
+            ▼                                          ▼
+  [NAVIGATION PATH]                          [CONTENT READ PATH]
+  cairn_maintain                             cairn_bundle
+  File Walker → Parser Factory               File Walker → Minifier
+  → SQLite + FTS5                            → .cairn/bundles/<name>.txt
+  (.cairn/index.db)                        (comments, whitespace,
+  answers: WHERE does X live?                 empty lines, styles stripped)
+            │                                          │
+            └──────────────────┬───────────────────────┘
+                               ▼
+                          Claude Code
+               cairn_search  →  WHERE it is
+               cairn_bundle  →  WHAT it says
+```
+**Two complementary paths, one tool:**
+- **Navigation path** (SQLite index) — *"where does X live?"* — symbol graph, FTS5 search, dependency graph
+- **Content path** (bundle file) — *"what does X actually contain?"* — compressed readable source, sized to fit Claude's context window
+> **Mental model: Cairn works like `git`.** You don't tell `git` where your repo is — it finds `.git/` in the current directory. Cairn works identically: all tools read from `.cairn/` in the current working directory. No roots, no config paths. Just `cd` into your project and run.
+**Why SQLite + FTS5?**
+- Zero infrastructure — ships as a single file
+- Full-text search built in (FTS5 extension)
+- Survives session restarts (persistent)
+- Fast enough for 300K+ lines across 40+ mixed repos
+---
+## Project Layout
+### The `.cairn/` directory (auto-created in your project root)
+```
+your-project/          ← wherever Claude Code is opened
+├── .cairn/            ← created automatically on first cairn_maintain
+│   ├── index.db       ← SQLite knowledge graph (navigation path)
+│   ├── bundles/       ← minified content snapshots (content path)
+│   │   ├── default.txt
+│   │   ├── checkout.txt
+│   │   └── *.mtime.json   ← incremental tracking per bundle
+│   └── cairn.json     ← project config (ignore patterns, language overrides)
+├── src/
+├── pom.xml / package.json
+└── CLAUDE.md
+```
+This mirrors exactly how `.git/` works — local, self-contained, no global state.
+> **Tip:** Add `.cairn/` to your `.gitignore`. It's generated data, not source — each developer runs `cairn_maintain` to build their own local index.
+---
+## MCP Server Structure
+```
+cairn-mcp/
+├── package.json
+├── index.js                        ← MCP server entry point
+└── src/
+    ├── indexer/
+    │   ├── fileWalker.js            ← Recursive scanner, extension filter
+    │   ├── parserFactory.js         ← Routes file → correct parser
+    │   ├── parsers/
+    │   │   ├── javaParser.js        ← .java
+    │   │   ├── tsParser.js          ← .ts, .tsx, .js, .jsx, .mjs
+    │   │   ├── vueParser.js         ← .vue  (extracts <script>, delegates to tsParser)
+    │   │   ├── pythonParser.js      ← .py
+    │   │   ├── sqlParser.js         ← .sql
+    │   │   ├── configParser.js      ← .yml, .yaml, .properties, .env
+    │   │   ├── xmlParser.js         ← .xml, .html
+    │   │   └── markdownParser.js    ← .md
+    │   ├── buildParsers/
+    │   │   ├── mavenParser.js       ← pom.xml
+    │   │   ├── npmParser.js         ← package.json
+    │   │   └── gradleParser.js      ← build.gradle (basic)
+    │   └── securityScanner.js       ← Polyglot pattern-based vuln detection
+    ├── graph/
+    │   ├── db.js                    ← SQLite connection + schema
+    │   ├── nodes.js                 ← Symbols, files, repos as nodes
+    │   └── edges.js                 ← Dependency/call/import relationships
+    ├── bundler/
+    │   ├── minifier.js              ← Per-language comment/whitespace stripping
+    │   ├── vueMinifier.js           ← Vue 3-block minifier (<template>/<script>/<style>)
+    │   └── bundleWriter.js          ← Writes ### File: headers, tracks mtime for incremental runs
+    └── tools/
+        ├── search.js                ← cairn_search tool
+        ├── describe.js              ← cairn_describe tool
+        ├── codeGraph.js             ← cairn_code_graph tool
+        ├── security.js              ← cairn_security tool
+        ├── maintain.js              ← cairn_maintain tool (re-index)
+        └── bundle.js                ← cairn_bundle tool (minified content bundle)
+```
+---
+## Phase 1 — Core Infrastructure (Day 1)
+### 1.1 Setup
+```bash
+mkdir cairn-mcp && cd cairn-mcp
+npm init -y
+npm install @modelcontextprotocol/sdk better-sqlite3 fast-glob
+```
+### 1.2 CWD Resolution — The Git-like Core (`src/graph/cwd.js`)
+Every tool resolves `.cairn/` relative to the process working directory — the directory
+Claude Code was opened in. No paths are ever passed by the caller.
+```javascript
+import path from 'path';
+import fs   from 'fs';
+// Called once at startup — finds .cairn/ in cwd or creates it
+export function resolveCairnDir() {
+  const cairnDir = path.join(process.cwd(), '.cairn');
+  fs.mkdirSync(path.join(cairnDir, 'bundles'), { recursive: true });
+  return cairnDir;
+}
+export function dbPath()     { return path.join(resolveCairnDir(), 'index.db'); }
+export function bundleDir()  { return path.join(resolveCairnDir(), 'bundles'); }
+export function configPath() { return path.join(resolveCairnDir(), 'cairn.json'); }
+// Read optional project config (.cairn/cairn.json)
+export function loadConfig() {
+  const p = configPath();
+  if (!fs.existsSync(p)) return {};
+  return JSON.parse(fs.readFileSync(p, 'utf8'));
+}
+```
+### 1.3 SQLite Schema — Language-Aware (`src/graph/db.js`)
+```javascript
+const schema = `
+  -- Every file in every repo
+  CREATE TABLE IF NOT EXISTS files (
+    id           INTEGER PRIMARY KEY,
+    repo         TEXT NOT NULL,
+    path         TEXT NOT NULL UNIQUE,
+    language     TEXT,           -- 'java','typescript','vue','python','sql','config','markdown'
+    file_type    TEXT,           -- 'source','test','config','build','doc'
+    last_indexed INTEGER
+  );
+  -- Every named symbol extracted from any language
+  CREATE TABLE IF NOT EXISTS symbols (
+    id          INTEGER PRIMARY KEY,
+    file_id     INTEGER REFERENCES files(id) ON DELETE CASCADE,
+    fqn         TEXT UNIQUE,     -- fully qualified: com.example.Auth | src/auth/useAuth.ts::useAuth
+    name        TEXT NOT NULL,
+    kind        TEXT,            -- 'class','interface','function','component','table','enum','type','record'
+    language    TEXT,
+    exported    INTEGER DEFAULT 0,  -- 1 if exported/public
+    description TEXT             -- javadoc / JSDoc / docstring if present
+  );
+  -- Import/dependency edges between symbols or files
+  CREATE TABLE IF NOT EXISTS dependencies (
+    from_file_id INTEGER REFERENCES files(id),
+    to_fqn       TEXT,
+    dep_type     TEXT            -- 'imports','extends','implements','calls','uses'
+  );
+  -- Build-level dependencies (Maven, npm, Gradle)
+  CREATE TABLE IF NOT EXISTS build_deps (
+    repo        TEXT,
+    manager     TEXT,            -- 'maven','npm','gradle'
+    group_id    TEXT,            -- groupId (Maven) or scope (npm)
+    artifact    TEXT,            -- artifactId or package name
+    version     TEXT,
+    scope       TEXT             -- compile/test/dev/peer
+  );
+  -- Security findings (polyglot, CWE-mapped)
+  CREATE TABLE IF NOT EXISTS security_findings (
+    id           INTEGER PRIMARY KEY,
+    file_id      INTEGER REFERENCES files(id),
+    line         INTEGER,
+    severity     TEXT,
+    cwe          TEXT,
+    rule_name    TEXT,
+    description  TEXT,
+    code_snippet TEXT
+  );
+  -- Full-text search across ALL languages
+  CREATE VIRTUAL TABLE IF NOT EXISTS fts_index USING fts5(
+    fqn, name, description, path, repo, language, kind,
+    content='symbols',
+    content_rowid='id'
+  );
+`;
+```
+---
+## Phase 2 — The Parser Factory (Day 1-2)
+### 2.1 File Walker + Router (`src/indexer/fileWalker.js`)
+The walker always starts from `process.cwd()` — no root path argument needed.
+```javascript
+import fg   from 'fast-glob';
+import path from 'path';
+import { loadConfig } from '../graph/cwd.js';
+// Files to index by language family
+export const LANGUAGE_MAP = {
+  // JVM
+  '.java':       'java',
+  // JS/TS
+  '.ts':         'typescript',
+  '.tsx':        'typescript',
+  '.js':         'javascript',
+  '.jsx':        'javascript',
+  '.mjs':        'javascript',
+  // Vue
+  '.vue':        'vue',
+  // Python
+  '.py':         'python',
+  // Data / Config
+  '.sql':        'sql',
+  '.yml':        'config',
+  '.yaml':       'config',
+  '.properties': 'config',
+  '.env':        'config',
+  // Markup
+  '.xml':        'xml',
+  '.html':       'html',
+  '.md':         'markdown',
+};
+// Build files (handled separately)
+export const BUILD_FILES = ['pom.xml', 'package.json', 'build.gradle'];
+// Directories to always skip
+const IGNORE = [
+  '**/node_modules/**', '**/.git/**', '**/dist/**',
+  '**/build/**', '**/target/**', '**/.next/**',
+  '**/__pycache__/**', '**/*.min.js'
+];
+// Walk from cwd — like git, no explicit root needed
+export async function walkProject() {
+  const root    = process.cwd();
+  const config  = loadConfig();
+  const ignore  = [...IGNORE, ...( config.ignore || [] ), '.cairn/**'];
+  const patterns = Object.keys(LANGUAGE_MAP).map(ext => `**/*${ext}`);
+  const files   = await fg(patterns, { cwd: root, ignore, absolute: true });
+  return { root, files };
+}
+```
+### 2.2 Parser Factory (`src/indexer/parserFactory.js`)
+```javascript
+import path from 'path';
+import { LANGUAGE_MAP } from './fileWalker.js';
+import { parseJava }     from './parsers/javaParser.js';
+import { parseTS }       from './parsers/tsParser.js';
+import { parseVue }      from './parsers/vueParser.js';
+import { parsePython }   from './parsers/pythonParser.js';
+import { parseSQL }      from './parsers/sqlParser.js';
+import { parseConfig }   from './parsers/configParser.js';
+import { parseXML }      from './parsers/xmlParser.js';
+import { parseMarkdown } from './parsers/markdownParser.js';
+const PARSERS = {
+  java:       parseJava,
+  typescript: parseTS,
+  javascript: parseTS,     // JS uses same parser as TS
+  vue:        parseVue,    // Vue extracts <script> then calls parseTS
+  python:     parsePython,
+  sql:        parseSQL,
+  config:     parseConfig,
+  xml:        parseXML,
+  html:       parseXML,
+  markdown:   parseMarkdown,
+};
+export function getParser(filePath) {
+  const ext = path.extname(filePath).toLowerCase();
+  const language = LANGUAGE_MAP[ext];
+  return { language, parser: PARSERS[language] || null };
+}
+// Returns: { language, kind, symbols: [{name, fqn, kind, exported, description}], imports: [] }
+export async function parseFile(filePath, content, repoName) {
+  const { language, parser } = getParser(filePath);
+  if (!parser) return null;
+  return parser(filePath, content, repoName, language);
+}
+```
+---
+## Phase 3 — Language Parsers (Day 2)
+### 3.1 Java Parser (`src/indexer/parsers/javaParser.js`)
+```javascript
+export function parseJava(filePath, content, repoName) {
+  const pkg     = content.match(/^package\s+([\w.]+);/m)?.[1] || '';
+  const imports = [...content.matchAll(/^import\s+([\w.]+);/gm)].map(m => m[1]);
+  const classMatch = content.match(
+    /(?:public|protected)?\s+(?:abstract\s+)?(?:class|interface|enum|record)\s+(\w+)/
+  );
+  const name = classMatch?.[1] || '';
+  const kind = classMatch?.[0]?.match(/class|interface|enum|record/)?.[0] || 'class';
+  const fqn  = pkg ? `${pkg}.${name}` : name;
+  const methods = [...content.matchAll(
+    /(?:public|protected|private)[^{;]*\s+(\w+)\s*\([^)]*\)\s*(?:throws[^{]*)?\{/gm
+  )].map(m => m[1]);
+  const extendsMatch    = content.match(/extends\s+([\w.]+)/)?.[1];
+  const implementsMatch = content.match(/implements\s+([\w.,\s]+)/)?.[1]
+    ?.split(',').map(s => s.trim());
+  const javadoc = content.match(/\/\*\*([\s\S]*?)\*\//)?.[1]
+    ?.replace(/\s*\*\s?/g, ' ').trim();
+  return {
+    language: 'java',
+    symbols: [{ name, fqn, kind, exported: true, description: javadoc || '' }],
+    imports,
+    extends: extendsMatch ? [extendsMatch] : [],
+    implements: implementsMatch || [],
+    methods,
+  };
+}
+```
+### 3.2 TypeScript / JavaScript Parser (`src/indexer/parsers/tsParser.js`)
+```javascript
+export function parseTS(filePath, content, repoName, language = 'typescript') {
+  const symbols = [];
+  const imports = [];
+  // Named imports: import { Foo, Bar } from './foo'
+  for (const m of content.matchAll(/import\s+\{([^}]+)\}\s+from\s+['"]([^'"]+)['"]/g))
+    imports.push(...m[1].split(',').map(s => s.trim().split(' as ')[0]));
+  // Default imports: import Foo from './foo'
+  for (const m of content.matchAll(/import\s+(\w+)\s+from\s+['"]([^'"]+)['"]/g))
+    imports.push(m[1]);
+  // Classes
+  for (const m of content.matchAll(/(?:export\s+)?(?:abstract\s+)?class\s+(\w+)/g)) {
+    const exported = m[0].startsWith('export');
+    const jsdoc = extractJSDoc(content, m.index);
+    symbols.push({ name: m[1], fqn: `${filePath}::${m[1]}`, kind: 'class', exported, description: jsdoc });
+  }
+  // Interfaces & Types
+  for (const m of content.matchAll(/export\s+(?:interface|type)\s+(\w+)/g))
+    symbols.push({ name: m[1], fqn: `${filePath}::${m[1]}`, kind: 'interface', exported: true, description: '' });
+  // Exported functions (named + arrow)
+  for (const m of content.matchAll(/export\s+(?:async\s+)?function\s+(\w+)/g)) {
+    const jsdoc = extractJSDoc(content, m.index);
+    symbols.push({ name: m[1], fqn: `${filePath}::${m[1]}`, kind: 'function', exported: true, description: jsdoc });
+  }
+  for (const m of content.matchAll(/export\s+const\s+(\w+)\s*=\s*(?:async\s+)?\(/g))
+    symbols.push({ name: m[1], fqn: `${filePath}::${m[1]}`, kind: 'function', exported: true, description: '' });
+  // Enums
+  for (const m of content.matchAll(/export\s+(?:const\s+)?enum\s+(\w+)/g))
+    symbols.push({ name: m[1], fqn: `${filePath}::${m[1]}`, kind: 'enum', exported: true, description: '' });
+  return { language, symbols, imports };
+}
+function extractJSDoc(content, index) {
+  const before = content.substring(0, index);
+  const match  = before.match(/\/\*\*([\s\S]*?)\*\/\s*$/);
+  return match ? match[1].replace(/\s*\*\s?/g, ' ').trim() : '';
+}
+```
+### 3.3 Vue Parser (`src/indexer/parsers/vueParser.js`)
+```javascript
+import { parseTS } from './tsParser.js';
+export function parseVue(filePath, content, repoName) {
+  // Step 1: Extract component name from filename
+  const componentName = filePath.split('/').pop().replace('.vue', '');
+  // Step 2: Extract <script> or <script setup> block
+  const scriptMatch = content.match(/<script(?:\s+setup)?(?:\s+lang=["']ts["'])?>([\s\S]*?)<\/script>/i);
+  const scriptContent = scriptMatch?.[1] || '';
+  // Step 3: Parse script block as TypeScript
+  const parsed = parseTS(filePath, scriptContent, repoName, 'vue');
+  // Step 4: Extract child component refs from template
+  const templateMatch = content.match(/<template>([\s\S]*?)<\/template>/i);
+  const childComponents = [...(templateMatch?.[1]?.matchAll(/<([A-Z][A-Za-z]+)/g) || [])]
+    .map(m => m[1]);
+  // Step 5: Always register the component itself as a symbol
+  parsed.symbols.unshift({
+    name: componentName,
+    fqn: `${filePath}::${componentName}`,
+    kind: 'component',
+    exported: true,
+    description: `Vue component: ${componentName}`
+  });
+  parsed.childComponents = [...new Set(childComponents)];
+  return parsed;
+}
+```
+### 3.4 Python Parser (`src/indexer/parsers/pythonParser.js`)
+```javascript
+export function parsePython(filePath, content, repoName) {
+  const symbols = [];
+  const imports = [];
+  // Imports
+  for (const m of content.matchAll(/^from\s+([\w.]+)\s+import\s+([\w,\s*]+)/gm))
+    imports.push(...m[2].split(',').map(s => s.trim()));
+  for (const m of content.matchAll(/^import\s+([\w.,\s]+)/gm))
+    imports.push(...m[1].split(',').map(s => s.trim()));
+  // Classes
+  for (const m of content.matchAll(/^class\s+(\w+)(?:\(([^)]*)\))?:/gm)) {
+    const docstring = content.slice(m.index).match(/:\s*\n\s+"""([\s\S]*?)"""/)?.[1]?.trim();
+    symbols.push({ name: m[1], fqn: `${filePath}::${m[1]}`, kind: 'class', exported: true, description: docstring || '' });
+  }
+  // Top-level functions (skip private _underscore ones)
+  for (const m of content.matchAll(/^(?:async\s+)?def\s+(\w+)\s*\(/gm)) {
+    if (m[1].startsWith('_')) continue;
+    const docstring = content.slice(m.index).match(/\).*?:\s*\n\s+"""([\s\S]*?)"""/)?.[1]?.trim();
+    symbols.push({ name: m[1], fqn: `${filePath}::${m[1]}`, kind: 'function', exported: true, description: docstring || '' });
+  }
+  // Decorators (FastAPI routes, Django views, Celery tasks, etc.)
+  for (const m of content.matchAll(/^@([\w.]+)(?:\(([^)]*)\))?/gm))
+    symbols.push({ name: m[1], fqn: `${filePath}::@${m[1]}`, kind: 'decorator', exported: false, description: '' });
+  return { language: 'python', symbols, imports };
+}
+```
+### 3.5 SQL Parser (`src/indexer/parsers/sqlParser.js`)
+```javascript
+export function parseSQL(filePath, content, repoName) {
+  const symbols = [];
+  for (const m of content.matchAll(/CREATE\s+TABLE\s+(?:IF NOT EXISTS\s+)?([`"\w.]+)/gi))
+    symbols.push({ name: m[1], fqn: `${filePath}::${m[1]}`, kind: 'table', exported: true, description: '' });
+  for (const m of content.matchAll(/CREATE\s+(?:OR REPLACE\s+)?(?:PROCEDURE|FUNCTION)\s+(\w+)/gi))
+    symbols.push({ name: m[1], fqn: `${filePath}::${m[1]}`, kind: 'function', exported: true, description: '' });
+  for (const m of content.matchAll(/CREATE\s+(?:OR REPLACE\s+)?VIEW\s+(\w+)/gi))
+    symbols.push({ name: m[1], fqn: `${filePath}::${m[1]}`, kind: 'view', exported: true, description: '' });
+  return { language: 'sql', symbols, imports: [] };
+}
+```
+### 3.6 Config Parser (`src/indexer/parsers/configParser.js`)
+```javascript
+export function parseConfig(filePath, content, repoName) {
+  const symbols = [];
+  // YAML/Properties: extract top-level keys
+  for (const m of content.matchAll(/^([\w.-]+)\s*[:=]\s*(.+)/gm)) {
+    const key = m[1].trim();
+    if (key.startsWith('#')) continue;
+    symbols.push({
+      name: key,
+      fqn: `${filePath}::${key}`,
+      kind: 'config-key',
+      exported: false,
+      description: m[2].trim().substring(0, 80)
+    });
+  }
+  return { language: 'config', symbols, imports: [] };
+}
+```
+### 3.7 Markdown Parser (`src/indexer/parsers/markdownParser.js`)
+```javascript
+export function parseMarkdown(filePath, content, repoName) {
+  const symbols = [];
+  // Index each heading as a searchable symbol
+  for (const m of content.matchAll(/^(#{1,3})\s+(.+)/gm)) {
+    const level = m[1].length;
+    const title = m[2].trim();
+    symbols.push({
+      name: title,
+      fqn: `${filePath}::${title.replace(/\s+/g, '-').toLowerCase()}`,
+      kind: level === 1 ? 'doc-title' : 'doc-section',
+      exported: true,
+      description: ''
+    });
+  }
+  return { language: 'markdown', symbols, imports: [] };
+}
+```
+---
+## Phase 4 — Polyglot Security Scanner (Day 3)
+Security patterns are scoped per-language to minimize false positives:
+```javascript
+// src/indexer/securityScanner.js
+export const VULN_PATTERNS = [
+  // ── Java ──────────────────────────────────────────────────────────────
+  { id: "CWE-611", lang: ["java"],                        severity: "HIGH",
+    name: "XXE (XML External Entity)",
+    pattern: /builder\.parse\(/,
+    negPattern: /setFeature.*FEATURE_SECURE_PROCESSING/,
+    fix: "Add dbf.setFeature(XMLConstants.FEATURE_SECURE_PROCESSING, true) before parse()" },
+  { id: "CWE-89",  lang: ["java"],                        severity: "HIGH",
+    name: "SQL Injection",
+    pattern: /"SELECT|INSERT|UPDATE|DELETE.*"\s*\+/i,
+    fix: "Use PreparedStatement with parameterized queries" },
+  { id: "CWE-326", lang: ["java"],                        severity: "HIGH",
+    name: "Weak Cryptography",
+    pattern: /getInstance\("(MD5|SHA1|DES|RC4)"\)/,
+    fix: "Use SHA-256 or AES-256" },
+  { id: "CWE-502", lang: ["java"],                        severity: "HIGH",
+    name: "Unsafe Deserialization",
+    pattern: /new ObjectInputStream|\.readObject\(\)/,
+    fix: "Validate input before deserialization; use safe deserialization libraries" },
+  { id: "CWE-078", lang: ["java"],                        severity: "HIGH",
+    name: "Command Injection",
+    pattern: /Runtime\.getRuntime\(\)\.exec\(/,
+    fix: "Use ProcessBuilder with argument list instead of string concatenation" },
+  // ── JavaScript / TypeScript / Vue ─────────────────────────────────────
+  { id: "CWE-79",  lang: ["javascript","typescript","vue"], severity: "HIGH",
+    name: "XSS via innerHTML / dangerouslySetInnerHTML",
+    pattern: /\.innerHTML\s*=|dangerouslySetInnerHTML/,
+    fix: "Use textContent or sanitize with DOMPurify" },
+  { id: "CWE-89",  lang: ["javascript","typescript"],       severity: "HIGH",
+    name: "SQL Injection (JS)",
+    pattern: /`\s*(SELECT|INSERT|UPDATE|DELETE).*\$\{/i,
+    fix: "Use parameterized queries or an ORM" },
+  { id: "CWE-798", lang: ["javascript","typescript","vue"], severity: "HIGH",
+    name: "Hardcoded Secret",
+    pattern: /(api_key|apikey|secret|password|token)\s*[:=]\s*['"][^'"]{8,}['"]/i,
+    fix: "Move secrets to environment variables or a secrets manager" },
+  { id: "CWE-327", lang: ["javascript","typescript"],       severity: "MEDIUM",
+    name: "Weak Crypto (Node)",
+    pattern: /createHash\(['"]md5['"]\)|createHash\(['"]sha1['"]\)/,
+    fix: "Use SHA-256 or stronger" },
+  { id: "CWE-601", lang: ["javascript","typescript","vue"], severity: "MEDIUM",
+    name: "Open Redirect",
+    pattern: /res\.redirect\([^)]*req\.(query|params|body)/,
+    fix: "Validate redirect URL against an allowlist" },
+  // ── Python ────────────────────────────────────────────────────────────
+  { id: "CWE-089", lang: ["python"],                        severity: "HIGH",
+    name: "SQL Injection (Python)",
+    pattern: /execute\([f"'].*%(s|d)|execute\(.*format\(/,
+    fix: "Use parameterized queries: cursor.execute(sql, params)" },
+  { id: "CWE-078", lang: ["python"],                        severity: "HIGH",
+    name: "Command Injection (Python)",
+    pattern: /os\.system\(|subprocess\.call\(.*shell=True/,
+    fix: "Use subprocess with a list of args and shell=False" },
+  { id: "CWE-798", lang: ["python"],                        severity: "HIGH",
+    name: "Hardcoded Secret (Python)",
+    pattern: /(api_key|secret|password|token)\s*=\s*['"][^'"]{8,}['"]/i,
+    fix: "Use environment variables or a secrets manager like Vault" },
+  // ── Universal (all languages) ─────────────────────────────────────────
+  { id: "CWE-312", lang: null,                              severity: "MEDIUM",
+    name: "Cleartext Sensitive Data in Comments",
+    pattern: /\/\/.*?(password|secret|token)\s*[:=]\s*\S+/i,
+    fix: "Remove sensitive data from comments" },
+];
+export function scanFile(filePath, content, language) {
+  const findings = [];
+  const lines = content.split('\n');
+  for (const rule of VULN_PATTERNS) {
+    if (rule.lang && !rule.lang.includes(language)) continue;
+    lines.forEach((line, i) => {
+      if (!rule.pattern.test(line)) return;
+      if (rule.negPattern) {
+        // Check surrounding 5-line context for the negating pattern
+        const ctx = lines.slice(Math.max(0, i - 5), i + 5).join('\n');
+        if (rule.negPattern.test(ctx)) return;
+      }
+      findings.push({
+        severity: rule.severity,
+        cwe: rule.id,
+        rule_name: rule.name,
+        line: i + 1,
+        code_snippet: line.trim().substring(0, 120),
+        description: rule.fix
+      });
+    });
+  }
+  return findings;
+}
+```
+---
+## Phase 5 — The 5 MCP Tools (Day 3)
+### Tool 1: `cairn_maintain` — Polyglot Indexer
+```javascript
+// Input — NO arguments required
+{}
+// Optional: { languages: ['java','typescript'] }  ← scope to specific languages only
+// What it does:
+// 1. Resolves .cairn/ from process.cwd() — no roots argument
+// 2. Walks cwd recursively, collecting files by extension
+// 3. Routes each file through parserFactory → language-specific parser
+// 4. Writes symbols + dependencies to .cairn/index.db
+// 5. Parses build files (pom.xml, package.json, build.gradle)
+// 6. Rebuilds FTS5 index
+// 7. Runs security scanner, caches findings in .cairn/index.db
+// Output
+{
+  "repos_indexed": 12,
+  "files_by_language": {
+    "java": 412, "typescript": 287, "vue": 94,
+    "python": 33, "sql": 18, "config": 67,
+    "markdown": 24, "xml": 41
+  },
+  "symbols_total": 6841,
+  "dependencies_mapped": 892,
+  "security_findings": 47,
+  "duration_ms": 28400
+}
+```
+### Tool 2: `cairn_search` — Cross-Language Search
+```javascript
+// Input
+{ query: "user authentication", limit: 10, language: "typescript" }  // all args optional except query
+// reads from .cairn/index.db in cwd — no roots needed
+// Output — results ranked across ALL languages by default
+[
+  { lang: "java",       kind: "class",      fqn: "com.example.auth.UserAuthenticator",       score: 1.0  },
+  { lang: "typescript", kind: "function",   fqn: "src/composables/useAuth.ts::useAuth",      score: 0.95 },
+  { lang: "vue",        kind: "component",  fqn: "src/components/LoginForm.vue::LoginForm",  score: 0.9  },
+  { lang: "python",     kind: "class",      fqn: "auth/authenticator.py::UserAuthenticator", score: 0.85 },
+  { lang: "config",     kind: "config-key", fqn: "application.yml::spring.security.oauth2", score: 0.7  }
+]
+```
+### Tool 3: `cairn_describe` — Module/Directory Summary
+```javascript
+// Input
+{ path: "src/components/checkout" }
+// Output — works for any language mix in the directory
+{
+  "path": "src/components/checkout",
+  "languages": ["vue", "typescript"],
+  "symbols": {
+    "components": ["CheckoutForm.vue", "OrderSummary.vue", "PaymentStep.vue"],
+    "composables": ["useCheckout", "usePayment"],
+    "types":       ["CheckoutState", "PaymentMethod"]
+  },
+  "imports_from":  ["src/store/cart.ts", "src/api/orders.ts", "stripe"],
+  "imported_by":   ["src/views/CartView.vue", "src/router/index.ts"],
+  "external_deps": ["stripe", "@stripe/stripe-js"]
+}
+```
+### Tool 4: `cairn_code_graph` — Cross-Language Dependency X-Ray
+```javascript
+// Input
+{ mode: "instability" }
+// Instability = Ce / (Ca + Ce)
+// Ce = efferent (outgoing) deps | Ca = afferent (incoming) deps
+// 0.0 = stable/load-bearing    | 1.0 = unstable/safe to change
+// Output — instability calculated across all module types
+{
+  "modules": [
+    { "name": "src/views",       "language": "vue",        "instability": 1.0, "status": "safe_to_refactor"    },
+    { "name": "com.example.api", "language": "java",       "instability": 0.8, "status": "safe_to_refactor"    },
+    { "name": "src/composables", "language": "typescript", "instability": 0.4, "status": "review_before_change" },
+    { "name": "src/utils",       "language": "typescript", "instability": 0.1, "status": "load_bearing"        },
+    { "name": "com.example.core","language": "java",       "instability": 0.0, "status": "load_bearing"        }
+  ],
+  "cross_language_deps": [
+    { "from": "src/api/client.ts", "to": "com.example.api.OrderController", "type": "http_call" }
+  ],
+  "cycles_detected": [],
+  "god_objects": ["OrderService.java (51 deps)", "useStore.ts (38 imports)"]
+}
+```
+### Tool 5: `cairn_security` — Polyglot Vulnerability Scanner
+```javascript
+// Input
+{ severity: "HIGH" }
+// Output — findings across all languages
+{
+  "total_findings": 71,
+  "by_language": { "java": 23, "typescript": 31, "vue": 12, "python": 5 },
+  "by_severity":  { "HIGH": 29, "MEDIUM": 42 },
+  "findings": [
+    {
+      "severity": "HIGH",   "lang": "typescript", "cwe": "CWE-79",
+      "file": "src/components/UserProfile.vue",   "line": 84,
+      "rule": "XSS via innerHTML",
+      "snippet": "el.innerHTML = userData.bio",
+      "fix": "Use textContent or DOMPurify.sanitize()"
+    },
+    {
+      "severity": "HIGH",   "lang": "java", "cwe": "CWE-611",
+      "file": "backend/src/.../XmlParser.java",   "line": 47,
+      "rule": "XXE (XML External Entity)",
+      "snippet": "Document dDoc = builder.parse(input);",
+      "fix": "Add dbf.setFeature(XMLConstants.FEATURE_SECURE_PROCESSING, true)"
+    }
+  ]
+}
+```
+---
+## Phase 5b — cairn_bundle: The Minified Content Bridge
+This is the **content read path** — complementing the navigation path. When Claude needs to
+actually read and reason about source code (not just find it), `cairn_bundle` produces a
+compressed single-file snapshot sized to fit Claude's context window.
+### How it works
+```
+cairn_bundle called  (no roots argument)
+       │
+       ├── 1. Resolves .cairn/ from process.cwd()
+       ├── 2. Walks cwd recursively (reuses walkProject())
+       ├── 3. Filter by paths/language/extensions requested
+       ├── 4. Check mtime → skip unchanged files (incremental mode)
+       ├── 5. Per-file: route to language minifier
+       │        • Strip comments        (all languages)
+       │        • Strip empty lines     (all languages)
+       │        • Collapse whitespace   (all languages)
+       │        • Strip <style> blocks  (Vue, optional)
+       │        • Aggressive punct.     (optional)
+       ├── 6. Write ### File: <path> header + minified content
+       └── 7. Save to .cairn/bundles/<bundle-name>.txt
+              Return: path + stats (original KB → compressed KB, ratio)
+```
+### Minifier Implementation (`src/bundler/minifier.js`)
+```javascript
+// Per-language minification — ported and extended from minify.py
+export function minifyContent(content, language, options = {}) {
+  const { noComments = true, noEmptyLines = true, aggressive = false } = options;
+  let out = content;
+  if (noComments)   out = removeComments(out, language);
+  if (noEmptyLines) out = removeEmptyLines(out);
+  out = collapseWhitespace(out);
+  if (aggressive)   out = aggressiveMinify(out);
+  return out.trim();
+}
+function removeComments(content, language) {
+  switch (language) {
+    case 'java':
+    case 'typescript':
+    case 'javascript':
+    case 'vue':         // vue script/template block
+      // Single-line and block comments
+      return content
+        .replace(/\/\/.*$/gm, '')
+        .replace(/\/\*[\s\S]*?\*\//g, '');
+    case 'python':
+      return content
+        .replace(/#.*$/gm, '')
+        .replace(/'''[\s\S]*?'''/g, '')
+        .replace(/"""[\s\S]*?"""/g, '');
+    case 'sql':
+      return content
+        .replace(/--.*$/gm, '')
+        .replace(/\/\*[\s\S]*?\*\//g, '');
+    case 'xml':
+    case 'html':
+      return content.replace(/<!--[\s\S]*?-->/g, '');
+    case 'config':      // yaml/properties: strip # lines
+      return content.replace(/#.*$/gm, '');
+    default:
+      return content;
+  }
+}
+function removeEmptyLines(content) {
+  return content
+    .split('
+')
+    .filter(line => line.trim().length > 0)
+    .join('
+');
+}
+function collapseWhitespace(content) {
+  return content
+    .split('
+')
+    .map(line => line.trimEnd())       // strip trailing spaces per line
+    .join('
+')
+    .replace(/
+{3,}/g, '
+');      // max 2 consecutive blank lines → but removeEmptyLines handles this
+}
+function aggressiveMinify(content) {
+  return content
+    .replace(/\s+/g, ' ')
+    .replace(/\s*([=+\-*/%<>!&|^~?:;,{}()[\]])\s*/g, '$1')
+    .replace(/;\s*}/g, '}')
+    .replace(/\(\s+/g, '(')
+    .replace(/\s+\)/g, ')')
+    .trim();
+}
+```
+### Vue Minifier (`src/bundler/vueMinifier.js`)
+Vue needs special handling — 3 separate blocks each minified differently:
+```javascript
+import { minifyContent } from './minifier.js';
+export function minifyVue(content, options = {}) {
+  const { noStyle = false, noComments = true, noEmptyLines = true, aggressive = false } = options;
+  const result = [];
+  // Extract and minify <template>
+  const templateMatch = content.match(/<template>([\s\S]*?)<\/template>/i);
+  if (templateMatch) {
+    let tpl = templateMatch[1];
+    if (noComments)   tpl = tpl.replace(/<!--[\s\S]*?-->/g, '');
+    if (noEmptyLines) tpl = tpl.split('
+').filter(l => l.trim()).join('
+');
+    tpl = tpl.replace(/\s+/g, ' ').trim();
+    if (tpl) result.push(`<template>${tpl}</template>`);
+  }
+  // Extract and minify <script> / <script setup>
+  const scriptMatch = content.match(/<script([^>]*)>([\s\S]*?)<\/script>/i);
+  if (scriptMatch) {
+    const attrs = scriptMatch[1];
+    let code = minifyContent(scriptMatch[2], 'javascript',
+      { noComments, noEmptyLines, aggressive });
+    const tag = /setup/i.test(attrs) ? '<script setup>' : '<script>';
+    if (code) result.push(`${tag}${code}</script>`);
+  }
+  // Extract and minify <style> (unless skipped)
+  if (!noStyle) {
+    const styleMatch = content.match(/<style([^>]*)>([\s\S]*?)<\/style>/i);
+    if (styleMatch) {
+      let css = styleMatch[2]
+        .replace(/\/\*[\s\S]*?\*\//g, '')   // strip css comments
+        .replace(/\s+/g, ' ').trim();
+      if (css) result.push(`<style${styleMatch[1]}>${css}</style>`);
+    }
+  }
+  return result.join('
+');
+}
+```
+### Bundle Writer (`src/bundler/bundleWriter.js`)
+```javascript
+import fs from 'fs';
+import path from 'path';
+import { minifyContent } from './minifier.js';
+import { minifyVue }     from './vueMinifier.js';
+import { walkRepo, LANGUAGE_MAP } from '../indexer/fileWalker.js';
+import { bundleDir } from '../graph/cwd.js';
+export async function writeBundle(options = {}) {
+  const BUNDLE_DIR = bundleDir();
+  const {
+    bundleName   = 'default',
+    noComments   = true,
+    noEmptyLines = true,
+    noStyle      = false,
+    aggressive   = false,
+    onlyChanged  = false,       // incremental: skip files unchanged since last bundle
+    filterLang   = null,        // e.g. 'vue' or ['vue','typescript']
+    filterPaths  = null,        // e.g. ['src/components/checkout']
+    maxSizeKB    = 800,         // safety cap — stop before hitting context window limit
+  } = options;
+  const outPath    = path.join(BUNDLE_DIR, `${bundleName}.txt`);
+  const mtimePath  = path.join(BUNDLE_DIR, `${bundleName}.mtime.json`);
+  const mtimeCache = onlyChanged && fs.existsSync(mtimePath)
+    ? JSON.parse(fs.readFileSync(mtimePath, 'utf8')) : {};
+  const newMtimes  = {};
+  const lines      = [];
+  const stats      = { processed: 0, skipped_unchanged: 0, skipped_size: 0,
+                        original_bytes: 0, compressed_bytes: 0, by_language: {} };
+  const langFilter = filterLang
+    ? (Array.isArray(filterLang) ? filterLang : [filterLang]) : null;
+  const { root, files } = await walkProject();
+  {
+    for (const filePath of files) {
+      // Language filter
+      const ext      = path.extname(filePath).toLowerCase();
+      const language = LANGUAGE_MAP[ext];
+      if (!language) continue;
+      if (langFilter && !langFilter.includes(language)) continue;
+      // Path filter
+      if (filterPaths) {
+        const rel = path.relative(root, filePath);
+        if (!filterPaths.some(fp => rel.startsWith(fp))) continue;
+      }
+      // Incremental: skip unchanged files
+      const mtime = fs.statSync(filePath).mtimeMs;
+      newMtimes[filePath] = mtime;
+      if (onlyChanged && mtimeCache[filePath] === mtime) {
+        stats.skipped_unchanged++;
+        continue;
+      }
+      // Size cap
+      const currentKB = Buffer.byteLength(lines.join('
+'), 'utf8') / 1024;
+      if (currentKB > maxSizeKB) {
+        stats.skipped_size++;
+        continue;
+      }
+      const raw = fs.readFileSync(filePath, 'utf8');
+      stats.original_bytes += Buffer.byteLength(raw, 'utf8');
+      // Minify
+      let minified;
+      if (language === 'vue') {
+        minified = minifyVue(raw, { noStyle, noComments, noEmptyLines, aggressive });
+      } else {
+        minified = minifyContent(raw, language, { noComments, noEmptyLines, aggressive });
+      }
+      if (!minified.trim()) continue;
+      const rel = path.relative(process.cwd(), filePath);
+      lines.push(`### File: ${rel}`);
+      lines.push(minified.trim());
+      lines.push('');   // blank separator between files
+      stats.compressed_bytes += Buffer.byteLength(minified, 'utf8');
+      stats.processed++;
+      stats.by_language[language] = (stats.by_language[language] || 0) + 1;
+    }
+  }
+  const output = lines.join('
+');
+  fs.writeFileSync(outPath, output, 'utf8');
+  if (onlyChanged) fs.writeFileSync(mtimePath, JSON.stringify(newMtimes), 'utf8');
+  const ratio = stats.original_bytes > 0
+    ? Math.round((1 - stats.compressed_bytes / stats.original_bytes) * 100) : 0;
+  return {
+    bundle_path:       outPath,
+    processed:         stats.processed,
+    skipped_unchanged: stats.skipped_unchanged,
+    skipped_size_cap:  stats.skipped_size,
+    original_kb:       Math.round(stats.original_bytes / 1024),
+    compressed_kb:     Math.round(stats.compressed_bytes / 1024),
+    reduction_pct:     ratio,
+    by_language:       stats.by_language,
+  };
+}
+```
+### Tool 6: `cairn_bundle` — MCP Tool Definition
+```javascript
+// In index.js tools list:
+{
+  name: "cairn_bundle",
+  description: `Produce a minified single-file snapshot of source code for Claude to read.
+Strips comments, empty lines, and optionally styles. Returns the bundle file path and compression stats.
+Use AFTER cairn_search to get a readable version of the files Claude needs to work with.
+Typical workflow: cairn_search → find files → cairn_bundle those paths → Claude reads bundle.`,
+  inputSchema: {
+    type: "object",
+    properties: {
+      bundle_name: {
+        type: "string", default: "default",
+        description: "Name for the bundle file (saved to .cairn/bundles/<name>.txt)"
+      },
+      filter_paths: {
+        type: "array", items: { type: "string" },
+        description: "Optional: only include files under these relative paths"
+      },
+      filter_language: {
+        type: "string",
+        description: "Optional: only bundle this language (java/typescript/vue/python/...)"
+      },
+      no_comments:   { type: "boolean", default: true,  description: "Strip code comments" },
+      no_empty_lines:{ type: "boolean", default: true,  description: "Remove empty lines" },
+      no_style:      { type: "boolean", default: false, description: "Skip <style> blocks in Vue files" },
+      aggressive:    { type: "boolean", default: false, description: "Aggressive whitespace/punctuation minification" },
+      only_changed:  { type: "boolean", default: false, description: "Incremental: only re-bundle files changed since last run" },
+      max_size_kb:   { type: "number",  default: 800,   description: "Safety cap in KB to avoid context window overflow" }
+    },
+    required: []
+  }
+}
+// No roots needed — always reads from .cairn/ in cwd
+// Tool output example:
+{
+  "bundle_path":       "/Users/you/.cairn/bundles/checkout.txt",
+  "processed":         47,
+  "skipped_unchanged": 31,
+  "skipped_size_cap":  0,
+  "original_kb":       284,
+  "compressed_kb":     91,
+  "reduction_pct":     68,
+  "by_language":       { "vue": 23, "typescript": 18, "java": 6 }
+}
+```
+---
+### Typical Claude Code Workflow Using Both Paths
+```
+You: "Refactor the checkout flow to support multi-currency"
+Claude:
+  1. cairn_search "checkout payment currency"
+     → finds: src/components/checkout/, com.example.billing.CurrencyService
+  2. cairn_bundle filter_paths=["src/components/checkout"]
+                  filter_language=vue no_comments=true no_style=true
+     → .cairn/bundles/checkout.txt  (284 KB → 91 KB, 68% reduction)
+  3. Reads bundle file — understands full checkout component tree in one shot
+  4. cairn_code_graph --mode=instability --module=src/components/checkout
+     → knows blast radius before touching anything
+  5. Makes targeted, accurate changes — no hallucinations about file locations
+```
+---
+---
+## Phase 5c — Session State: `cairn_checkpoint` + `cairn_resume`
+This is the **"resume" system** — the missing piece that makes Claude feel continuous
+across sessions rather than starting from zero every time.
+### The Problem It Solves
+The index tracks *what exists* in the codebase. But it knows nothing about:
+- What task Claude was working on last session
+- Which files were actively being edited
+- What decisions were made and why
+- What's done vs. still in progress
+Without this, every session starts with Claude asking "so what are we working on?"
+even if you worked together for 3 hours yesterday.
+### How It Works
+```
+End of session:
+  cairn_checkpoint message="Added multi-currency to CheckoutForm, still need PaymentStep"
+       │
+       └── writes to .cairn/session.json:
+             {
+               "last_checkpoint": "2026-02-24T14:30:00Z",
+               "message": "Added multi-currency to CheckoutForm, still need PaymentStep",
+               "active_files": ["src/components/checkout/CheckoutForm.vue",
+                                 "src/components/checkout/PaymentStep.vue"],
+               "symbols_touched": ["useCheckout", "CurrencySelector", "PaymentStep"],
+               "index_snapshot": "sha256-abc123"   ← hash of index.db at checkpoint
+             }
+Start of next session:
+  cairn_resume
+       │
+       ├── 1. Load .cairn/session.json → last checkpoint message + context
+       ├── 2. Compare current file mtimes vs .cairn/mtime.json
+       │        → find files changed since last checkpoint
+       ├── 3. Re-index ONLY changed files (incremental cairn_maintain)
+       ├── 4. Report to Claude:
+       │        "Last session: Added multi-currency to CheckoutForm, still need PaymentStep
+       │         Changed since then: PaymentStep.vue (modified), currencyUtils.ts (new)
+       │         Unchanged: 847 files — index current, no re-index needed"
+       └── 5. Claude can immediately continue — full context restored
+```
+### Session State Schema (`.cairn/session.json`)
+```javascript
+// .cairn/session.json — written by cairn_checkpoint, read by cairn_resume
+{
+  "schema_version": 1,
+  // What was being worked on
+  "message": "Added multi-currency to CheckoutForm, still need PaymentStep",
+  "timestamp": "2026-02-24T14:30:00Z",
+  // Which files were actively open / being modified
+  "active_files": [
+    "src/components/checkout/CheckoutForm.vue",
+    "src/components/checkout/PaymentStep.vue"
+  ],
+  // Which symbols were touched this session
+  "symbols_touched": [
+    "useCheckout",
+    "CurrencySelector",
+    "PaymentMethod",
+    "PaymentStep"
+  ],
+  // Freeform notes Claude wants to remember across sessions
+  "notes": [
+    "CurrencyService in Java backend expects ISO 4217 codes, not symbols",
+    "PaymentStep has a bug with EUR formatting — not fixed yet",
+    "Do NOT touch OrderSummary.vue — it will be rewritten next sprint"
+  ],
+  // Index state at checkpoint — used to detect drift
+  "index_file_count": 847,
+  "mtime_snapshot": {
+    "src/components/checkout/CheckoutForm.vue": 1708785600000,
+    "src/components/checkout/PaymentStep.vue":  1708785600000
+  }
+}
+```
+### Tool 7: `cairn_checkpoint` — Save Session State
+```javascript
+// Input
+{
+  message:       "Added multi-currency to CheckoutForm, still need PaymentStep",
+  active_files:  ["src/components/checkout/CheckoutForm.vue"],   // optional
+  notes:         ["CurrencyService expects ISO 4217 codes"]       // optional
+}
+// What it does:
+// 1. Writes .cairn/session.json with message + context
+// 2. Snapshots mtime of active_files for drift detection
+// 3. Records which symbols were recently searched/described this session
+// Output
+{
+  "saved": true,
+  "checkpoint_at": "2026-02-24T14:30:00Z",
+  "active_files_tracked": 2,
+  "notes_saved": 1
+}
+```
+### Tool 8: `cairn_resume` — Restore Session State + Smart Re-index
+```javascript
+// Input — NO arguments
+{}
+// What it does:
+// 1. Loads .cairn/session.json
+// 2. Compares current file mtimes vs snapshot in session.json
+//    → finds exactly which files changed since last checkpoint
+// 3. Re-indexes ONLY changed files (calls incremental cairn_maintain internally)
+// 4. Returns full resumption context for Claude to read
+// Output
+{
+  "last_checkpoint": "2026-02-24T14:30:00Z",          // when you last saved
+  "message": "Added multi-currency to CheckoutForm, still need PaymentStep",
+  "index_status": "incremental",                        // or "fresh" / "stale"
+  "files_reindexed": 2,                                 // only what changed
+  "files_unchanged": 845,                               // not touched
+  "changed_since_checkpoint": [
+    { "file": "src/components/checkout/PaymentStep.vue", "change": "modified" },
+    { "file": "src/utils/currencyUtils.ts",              "change": "new" }
+  ],
+  "active_files": [
+    "src/components/checkout/CheckoutForm.vue",
+    "src/components/checkout/PaymentStep.vue"
+  ],
+  "notes": [
+    "CurrencyService in Java backend expects ISO 4217 codes, not symbols",
+    "PaymentStep has a bug with EUR formatting — not fixed yet",
+    "Do NOT touch OrderSummary.vue — it will be rewritten next sprint"
+  ],
+  // Ready-to-use summary Claude can speak directly to the user:
+  "resume_summary": "Last session you were adding multi-currency support. CheckoutForm is done. PaymentStep still needs work — and it was modified since your last checkpoint (likely by someone else or a build tool). currencyUtils.ts is a new file that didn't exist last session."
+}
+```
+### Implementation (`src/tools/resume.js`)
+```javascript
+import fs   from 'fs';
+import path from 'path';
+import { resolveCairnDir } from '../graph/cwd.js';
+import { incrementalMaintain } from './maintain.js';
+export async function checkpoint(args) {
+  const cairnDir    = resolveCairnDir();
+  const sessionPath = path.join(cairnDir, 'session.json');
+  const mtimePath   = path.join(cairnDir, 'mtime.json');
+  // Snapshot current mtimes of active files
+  const mtimeSnapshot = {};
+  for (const f of (args.active_files || [])) {
+    const abs = path.resolve(f);
+    if (fs.existsSync(abs))
+      mtimeSnapshot[f] = fs.statSync(abs).mtimeMs;
+  }
+  const session = {
+    schema_version:  1,
+    message:         args.message || '',
+    timestamp:       new Date().toISOString(),
+    active_files:    args.active_files  || [],
+    symbols_touched: args.symbols_touched || [],
+    notes:           args.notes         || [],
+    mtime_snapshot:  mtimeSnapshot,
+  };
+  fs.writeFileSync(sessionPath, JSON.stringify(session, null, 2), 'utf8');
+  return {
+    saved:                 true,
+    checkpoint_at:         session.timestamp,
+    active_files_tracked:  session.active_files.length,
+    notes_saved:           session.notes.length,
+  };
+}
+export async function resume() {
+  const cairnDir    = resolveCairnDir();
+  const sessionPath = path.join(cairnDir, 'session.json');
+  // No checkpoint yet — do a fresh full index and return minimal context
+  if (!fs.existsSync(sessionPath)) {
+    await incrementalMaintain();
+    return {
+      last_checkpoint:  null,
+      message:          'No previous session found. Fresh index complete.',
+      index_status:     'fresh',
+      files_reindexed:  'all',
+      files_unchanged:  0,
+      changed_since_checkpoint: [],
+      active_files:     [],
+      notes:            [],
+      resume_summary:   'No previous session found. Codebase has been freshly indexed. Ready to start.',
+    };
+  }
+  const session = JSON.parse(fs.readFileSync(sessionPath, 'utf8'));
+  const snapshot = session.mtime_snapshot || {};
+  // Detect changed files by comparing current mtimes to snapshot
+  const changed = [];
+  for (const [relPath, oldMtime] of Object.entries(snapshot)) {
+    const abs = path.resolve(relPath);
+    if (!fs.existsSync(abs)) {
+      changed.push({ file: relPath, change: 'deleted' });
+    } else if (fs.statSync(abs).mtimeMs !== oldMtime) {
+      changed.push({ file: relPath, change: 'modified' });
+    }
+  }
+  // Incremental re-index — only changed files
+  const { reindexed, unchanged } = await incrementalMaintain();
+  // Build human-readable summary
+  const changedNames = changed.map(c => `${c.file} (${c.change})`).join(', ');
+  const summary = [
+    `Last session: ${session.message}`,
+    changed.length > 0
+      ? `Changed since checkpoint: ${changedNames}`
+      : 'No files changed since last checkpoint — index is current.',
+    session.notes.length > 0
+      ? `Notes from last session: ${session.notes.join(' | ')}`
+      : ''
+  ].filter(Boolean).join(' ');
+  return {
+    last_checkpoint:           session.timestamp,
+    message:                   session.message,
+    index_status:              reindexed > 0 ? 'incremental' : 'current',
+    files_reindexed:           reindexed,
+    files_unchanged:           unchanged,
+    changed_since_checkpoint:  changed,
+    active_files:              session.active_files,
+    notes:                     session.notes,
+    resume_summary:            summary,
+  };
+}
+```
+---
+## Phase 6 — MCP Server Entry Point (`index.js`)
+```javascript
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+const server = new Server(
+  { name: "cairn", version: "1.0.0" },
+  { capabilities: { tools: {} } }
+);
+server.setRequestHandler("tools/list", async () => ({
+  tools: [
+    {
+      name: "cairn_maintain",
+      description: "Index the current project into Cairn's polyglot knowledge graph. Works like git — no roots needed, reads from .cairn/ in cwd. Supports Java, TypeScript, JavaScript, Vue, Python, SQL, config, and Markdown.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          languages: { type: "array", items: { type: "string" },
+                       description: "Optional: limit to specific languages e.g. ['java','typescript']" }
+        },
+        required: []
+      }
+    },
+    {
+      name: "cairn_search",
+      description: "Search the codebase by concept across all languages. Returns ranked symbols with scores.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          query:    { type: "string" },
+          limit:    { type: "number", default: 10 },
+          language: { type: "string", description: "Optional: filter by language" },
+          kind:     { type: "string", description: "Optional: class/function/component/table/..." }
+        },
+        required: ["query"]
+      }
+    },
+    {
+      name: "cairn_describe",
+      description: "Describe what a directory/module does: symbols, responsibilities, upstream/downstream deps.",
+      inputSchema: {
+        type: "object",
+        properties: { path: { type: "string" } },
+        required: ["path"]
+      }
+    },
+    {
+      name: "cairn_code_graph",
+      description: "Analyze module dependencies and instability metrics across all languages. Use before refactoring.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          module: { type: "string", description: "Optional: scope to a specific module/package" },
+          mode:   { type: "string", enum: ["instability", "health", "cycles"] }
+        },
+        required: ["mode"]
+      }
+    },
+    {
+      name: "cairn_security",
+      description: "Scan for security vulnerabilities across all languages (XSS, XXE, SQLi, weak crypto, hardcoded secrets, etc.)",
+      inputSchema: {
+        type: "object",
+        properties: {
+          paths:    { type: "array", items: { type: "string" }, description: "Optional: scope to specific paths" },
+          severity: { type: "string", enum: ["HIGH", "MEDIUM", "LOW", "ALL"], default: "HIGH" },
+          language: { type: "string", description: "Optional: scope to a specific language" }
+        }
+      }
+    },
+    {
+      name: "cairn_checkpoint",
+      description: "Save current session state — what you were working on, which files, any notes. Call this before ending a session so cairn_resume can restore full context next time.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          message:        { type: "string", description: "What you were working on (required)" },
+          active_files:   { type: "array", items: { type: "string" }, description: "Files actively being worked on" },
+          notes:          { type: "array", items: { type: "string" }, description: "Anything Claude should remember next session" }
+        },
+        required: ["message"]
+      }
+    },
+    {
+      name: "cairn_resume",
+      description: "Restore full session state at the start of a new session. Loads last checkpoint, detects changed files, re-indexes only what changed, and returns a ready-to-use summary. Always call this first — replaces cairn_maintain.",
+      inputSchema: {
+        type: "object",
+        properties: {},
+        required: []
+      }
+    }
+  ]
+}));
+server.setRequestHandler("tools/call", async (request) => {
+  const { name, arguments: args } = request.params;
+  switch (name) {
+    case "cairn_maintain":    return await maintain(args);
+    case "cairn_search":      return await search(args);
+    case "cairn_describe":    return await describe(args);
+    case "cairn_code_graph":  return await codeGraph(args);
+    case "cairn_security":    return await security(args);
+    case "cairn_checkpoint":  return await checkpoint(args);
+    case "cairn_resume":      return await resume();
+  }
+});
+const transport = new StdioServerTransport();
+await server.connect(transport);
+```
+---
+## Phase 7 — Claude Code Integration
+### Register in `~/.claude/claude.json`
+```json
+{
+  "mcpServers": {
+    "cairn": {
+      "command": "node",
+      "args": ["/absolute/path/to/cairn-mcp/index.js"]
+    }
+  }
+}
+// No env vars needed — Cairn resolves .cairn/ from whatever directory
+// Claude Code is opened in. Just like git.
+```
+### CLAUDE.md for your project
+This is the only setup required in each project. No paths, no config, no roots.
+```markdown
+## Cairn
+### START OF EVERY SESSION — run this first, always:
+`cairn_resume`
+This single command does everything needed to restore full working state:
+- Detects changed files since last index → re-indexes only those (incremental)
+- Loads the last session's work log (what you were doing, what files were open)
+- Reports what changed so you can continue exactly where you left off
+You do NOT need to decide whether to re-index. cairn_resume handles it.
+### Before modifying code:
+- `cairn_search` to find relevant symbols
+- `cairn_describe` to understand a module's responsibilities
+- `cairn_code_graph mode=instability` to check blast radius
+### Before reading files:
+- `cairn_bundle` to compress them — saves context window
+### Before security reviews:
+- `cairn_security severity=HIGH`
+### To save session state before ending:
+- `cairn_checkpoint message="what you were working on"`
+```
+---
+## Build Timeline
+| Day | Work |
+|-----|------|
+| **Day 1** | Setup, SQLite schema, file walker, parser factory skeleton |
+| **Day 2** | All language parsers (Java, TS, Vue, Python, SQL, Config, Markdown), `cairn_maintain` |
+| **Day 3** | Polyglot security scanner, `cairn_search`, `cairn_describe`, MCP server wiring |
+| **Day 4** | `cairn_code_graph`, `cairn_security`, `cairn_bundle` (minifier + bundle writer) |
+| **Day 5** | `cairn_checkpoint`, `cairn_resume` (session state + incremental re-index) |
+| **Day 6** | CLAUDE.md template, end-to-end resume testing, tuning |
+---
+## Key Design Decisions
+| Decision | Choice | Why |
+|----------|--------|-----|
+| Storage | SQLite + FTS5 | Zero infra, persistent, built-in full-text search |
+| Parsing | Regex (not full AST) | 10x faster, sufficient for navigation-level extraction |
+| Vue handling | Two-pass (extract `<script>` → parseTS) | Clean separation, no special-case logic |
+| Security patterns | Per-language scoped | Eliminates false positives from cross-language pattern bleeding |
+| MCP transport | stdio | Works natively with Claude Code, zero config |
+| Index location | `.cairn/index.db` (local to project) | Like `.git/` — one index per project, no global state |
+| Bundle location | `.cairn/bundles/<n>.txt` (local to project) | Named bundles per feature/module, isolated per project |
+| Bundle incremental | mtime cache (`.mtime.json`) | Re-bundle only changed files — fast after first run |
+| Bundle size cap | `max_size_kb` (default 800 KB) | Prevents accidental context window overflow |
+| Aggressive minify | Optional, off by default | Safe for orientation; risky if Claude needs to write precise diffs |
+| Language filter | Optional on all tools | Search/bundle everything by default, narrow when needed |
+| Session state | `.cairn/session.json` | Persists work context across sessions — what, why, notes |
+| Resume trigger | Change-based (mtime diff) | Re-index only if files changed, not on arbitrary time interval |
+| Checkpoint | Explicit (`cairn_checkpoint`) | Claude saves state when you're done — you control what's remembered |
+---
+## What This Eliminates
+- ❌ "Where is auth handled in the Vue app?" → ✅ `cairn_search "authentication" --language=vue`
+- ❌ "What Java services does the frontend call?" → ✅ `cairn_code_graph --mode=health`
+- ❌ Explaining folder structure every session → ✅ CLAUDE.md + persistent index
+- ❌ Manual XSS hunting across 90 Vue components → ✅ `cairn_security --language=vue`
+- ❌ Guessing what's safe to refactor → ✅ `cairn_code_graph --mode=instability`
+- ❌ "Where is the SQL schema defined?" → ✅ `cairn_search "orders table" --language=sql`
+- ❌ Hitting context window reading raw files → ✅ `cairn_bundle` (284 KB → 91 KB, 68% smaller)
+- ❌ Re-bundling entire codebase after small edits → ✅ `cairn_bundle only_changed=true` (mtime cache)
+- ❌ "I need to read the checkout module" + context overflow → ✅ `cairn_bundle filter_paths=["src/components/checkout"]`
+- ❌ "Where is the .cairn DB stored?" → ✅ Always `.cairn/` in your project root — like `.git/`
+**The archaeology tax drops from 50% to ~2% — across every language in your stack.**
+**And the context window goes 3x further — on the files that actually matter.**
+**And sessions resume in seconds — not with "so what were we working on?" but with full context.**
+### The Complete Session Lifecycle
+```
+─── START OF SESSION ──────────────────────────────────────────
+You:   "Hey Claude, please resume and continue"
+Claude: cairn_resume
+        → "Last session: adding multi-currency to checkout.
+           PaymentStep.vue was modified since checkpoint (2 files changed, re-indexed).
+           Notes: CurrencyService expects ISO 4217 codes. PaymentStep EUR bug not fixed yet.
+           Ready to continue."
+─── DURING SESSION ────────────────────────────────────────────
+Claude uses: cairn_search, cairn_bundle, cairn_code_graph, cairn_security
+             as needed — all reading from .cairn/index.db in cwd
+─── END OF SESSION ────────────────────────────────────────────
+You:   "Ok let's stop here for today"
+Claude: cairn_checkpoint
+          message="Fixed EUR formatting in PaymentStep, multi-currency complete"
+          active_files=["src/components/checkout/PaymentStep.vue"]
+          notes=["Still need to add JPY — no decimal places", "QA needs to test AED"]
+        → "Session saved. Resume anytime with cairn_resume."
+```
+
+### File: how-to-use.md
+# Cairn — Quick Start
+## 1. Install globally
+```bash
+npm install -g @misterhuydo/cairn-mcp
+```
+That's it — `cairn-mcp` is now available as a global command.
+## 2. Register with Claude Code
+Add to `~/.claude/config.json` (create it if it doesn't exist):
+```json
+{
+  "mcpServers": {
+    "cairn": {
+      "command": "cairn-mcp"
+    }
+  }
+}
+```
+> If you already have other MCP servers, just add `"cairn": { ... }` inside the existing `"mcpServers"` block.
+Restart Claude Code. You should see 8 cairn tools available.
+## 3. Index your project
+Run Claude Code from your project root, then:
+```
+cairn_maintain
+```
+No paths needed — Cairn works like git and finds your project from the current directory. The index is stored in `.cairn/index.db` inside your project.
+Run this once at the start of each session (or use `cairn_resume` to pick up where you left off).
+## 4. Tools at a glance
+| Tool | What to use it for |
+|---|---|
+| `cairn_maintain` | Index the current project (run at session start) |
+| `cairn_search` | Find classes, functions, components by name or concept |
+| `cairn_describe` | Summarize what a folder/module does |
+| `cairn_code_graph` | Check instability, health, or cycles before refactoring |
+| `cairn_security` | Scan for vulnerabilities (XSS, SQLi, hardcoded secrets, etc.) |
+| `cairn_bundle` | Package source files into a minified snapshot for Claude to read |
+| `cairn_checkpoint` | Save what you're working on so the next session can resume |
+| `cairn_resume` | Restore the last checkpoint + incremental re-index of changed files |
+## 5. Typical session
+**Starting fresh:**
+```
+1. cairn_maintain     → index the project
+2. cairn_search       → find what you need
+3. cairn_bundle       → get a readable snapshot of relevant files
+4. cairn_describe     → understand a module before modifying it
+5. cairn_security     → check for issues before a PR
+6. cairn_checkpoint   → save your progress before ending the session
+```
+**Resuming work:**
+```
+1. cairn_resume       → restore last checkpoint + re-index only changed files
+2. cairn_search       → continue where you left off
+```
+## 6. Complete session lifecycle
+```
+─── START OF SESSION ──────────────────────────────────────────
+You:    "Hey Claude, please resume and continue"
+Claude: cairn_resume
+        → "Last session: adding multi-currency to checkout.
+           PaymentStep.vue was modified since checkpoint (2 files changed, re-indexed).
+           Notes: CurrencyService expects ISO 4217 codes. PaymentStep EUR bug not fixed yet.
+           Ready to continue."
+─── DURING SESSION ────────────────────────────────────────────
+Claude uses: cairn_search, cairn_bundle, cairn_code_graph, cairn_security
+             as needed — all reading from .cairn/index.db in cwd
+─── END OF SESSION ────────────────────────────────────────────
+You:    "Ok let's stop here for today"
+Claude: cairn_checkpoint
+          message="Fixed EUR formatting in PaymentStep, multi-currency complete"
+          active_files=["src/components/checkout/PaymentStep.vue"]
+          notes=["Still need to add JPY — no decimal places", "QA needs to test AED"]
+        → "Session saved. Resume anytime with cairn_resume."
+```
+---
+**Requirements:** Node.js >= 22.15.0
+
+### File: index.js
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+import { openDB }       from './src/graph/db.js';
+import { maintain }     from './src/tools/maintain.js';
+import { search }       from './src/tools/search.js';
+import { describe }     from './src/tools/describe.js';
+import { codeGraph }    from './src/tools/codeGraph.js';
+import { security }     from './src/tools/security.js';
+import { bundle }       from './src/tools/bundle.js';
+import { checkpoint }   from './src/tools/checkpoint.js';
+import { resume }       from './src/tools/resume.js';
+const db = openDB();
+const server = new Server(
+  { name: 'cairn', version: '1.0.0' },
+  { capabilities: { tools: {} } }
+);
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+  tools: [
+    {
+      name: 'cairn_maintain',
+      description: 'Index the current project into Cairn\'s polyglot knowledge graph. Supports Java, TypeScript, JavaScript, Vue, Python, SQL, config, and Markdown. Indexes from the current working directory. Run at session start or after major changes.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          languages: {
+            type: 'array', items: { type: 'string' },
+            description: 'Optional: limit to specific languages e.g. ["java","typescript"]',
+          },
+        },
+      },
+    },
+    {
+      name: 'cairn_search',
+      description: 'Search the codebase by concept across all languages. Returns ranked symbols with scores.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          query:    { type: 'string' },
+          limit:    { type: 'number', default: 10 },
+          language: { type: 'string', description: 'Optional: filter by language' },
+          kind:     { type: 'string', description: 'Optional: class/function/component/table/...' },
+        },
+        required: ['query'],
+      },
+    },
+    {
+      name: 'cairn_describe',
+      description: 'Describe what a directory/module does: symbols, responsibilities, upstream/downstream deps.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          path: { type: 'string', description: 'Directory or file path to describe' },
+        },
+        required: ['path'],
+      },
+    },
+    {
+      name: 'cairn_code_graph',
+      description: 'Analyze module dependencies and instability metrics across all languages. Use before refactoring.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          module: { type: 'string', description: 'Optional: scope to a specific module/package' },
+          mode:   { type: 'string', enum: ['instability', 'health', 'cycles'] },
+        },
+        required: ['mode'],
+      },
+    },
+    {
+      name: 'cairn_security',
+      description: 'Scan for security vulnerabilities across all languages (XSS, XXE, SQLi, weak crypto, hardcoded secrets, etc.)',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          paths:    { type: 'array', items: { type: 'string' }, description: 'Optional: scope to specific paths' },
+          severity: { type: 'string', enum: ['HIGH', 'MEDIUM', 'LOW', 'ALL'], default: 'HIGH' },
+          language: { type: 'string', description: 'Optional: scope to a specific language' },
+        },
+      },
+    },
+    {
+      name: 'cairn_bundle',
+      description: `Produce a minified single-file snapshot of source code for Claude to read.
+Strips comments, empty lines, and optionally styles. Returns the bundle file path and compression stats.
+Use AFTER cairn_search to get a readable version of the files Claude needs to work with.
+Typical workflow: cairn_search → find files → cairn_bundle those paths → Claude reads bundle.`,
+      inputSchema: {
+        type: 'object',
+        properties: {
+          bundle_name: {
+            type: 'string', default: 'default',
+            description: 'Name for the bundle file (saved to .cairn/bundles/<name>.txt)',
+          },
+          filter_paths: {
+            type: 'array', items: { type: 'string' },
+            description: 'Optional: only include files under these relative paths',
+          },
+          filter_language: {
+            type: 'string',
+            description: 'Optional: only bundle this language (java/typescript/vue/python/...)',
+          },
+          no_comments:    { type: 'boolean', default: true,  description: 'Strip code comments' },
+          no_empty_lines: { type: 'boolean', default: true,  description: 'Remove empty lines' },
+          no_style:       { type: 'boolean', default: false, description: 'Skip <style> blocks in Vue files' },
+          aggressive:     { type: 'boolean', default: false, description: 'Aggressive whitespace/punctuation minification' },
+          only_changed:   { type: 'boolean', default: false, description: 'Incremental: only re-bundle files changed since last run' },
+          max_size_kb:    { type: 'number',  default: 800,   description: 'Safety cap in KB to avoid context window overflow' },
+        },
+      },
+    },
+    {
+      name: 'cairn_checkpoint',
+      description: 'Save current session state to .cairn/session.json so it can be restored next session with cairn_resume.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          message: {
+            type: 'string',
+            description: 'What you were working on — will be shown on resume',
+          },
+          active_files: {
+            type: 'array', items: { type: 'string' },
+            description: 'Optional: absolute paths to files actively being worked on',
+          },
+          notes: {
+            type: 'array', items: { type: 'string' },
+            description: 'Optional: things Claude should remember next session',
+          },
+        },
+        required: ['message'],
+      },
+    },
+    {
+      name: 'cairn_resume',
+      description: 'Restore the last saved session state. Detects which files changed since the checkpoint and incrementally re-indexes only those files. Call at the start of a session instead of cairn_maintain when resuming work.',
+      inputSchema: {
+        type: 'object',
+        properties: {},
+      },
+    },
+  ],
+}));
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  const { name, arguments: args } = request.params;
+  switch (name) {
+    case 'cairn_maintain':    return await maintain(db, args);
+    case 'cairn_search':      return search(db, args);
+    case 'cairn_describe':    return describe(db, args);
+    case 'cairn_code_graph':  return codeGraph(db, args);
+    case 'cairn_security':    return security(db, args);
+    case 'cairn_bundle':      return await bundle(db, args);
+    case 'cairn_checkpoint':  return checkpoint(db, args);
+    case 'cairn_resume':      return await resume(db);
+    default: throw new Error(`Unknown tool: ${name}`);
+  }
+});
+const transport = new StdioServerTransport();
+await server.connect(transport);
+
+### File: README.md
+# Cairn MCP
+> Persistent polyglot knowledge graph for Claude Code. Index once, query forever.
+Claude is stateless — every session starts at zero. On a multi-repo codebase with Java backends, TypeScript frontends, and Vue components, that means 50% of every session is archaeology: finding where things live before any real work can begin.
+**Cairn fixes this.** It indexes your project into a local SQLite knowledge graph (stored in `.cairn/`) and exposes 8 MCP tools that give Claude instant, persistent memory across sessions.
+---
+## Install
+```bash
+npm install -g @misterhuydo/cairn-mcp
+```
+**Requirements:** Node.js >= 22.15.0
+---
+## Setup
+Add to `~/.claude/config.json`:
+```json
+{
+  "mcpServers": {
+    "cairn": {
+      "command": "cairn-mcp"
+    }
+  }
+}
+```
+Restart Claude Code. Done.
+---
+## How it works
+Cairn works like git — it looks for `.cairn/` in your current working directory. Run Claude Code from your project root and Cairn automatically stores the index at `.cairn/index.db` and bundles at `.cairn/bundles/`.
+No root paths needed. No global config. Just `cd` to your project and go.
+---
+## Tools
+### `cairn_maintain` — Index your project
+Run once at the start of each session. The index persists in `.cairn/index.db`.
+```
+cairn_maintain()
+cairn_maintain({ languages: ["typescript", "vue"] })  // limit to specific languages
+```
+```json
+{
+  "repos_indexed": 1,
+  "files_by_language": { "java": 412, "typescript": 287, "vue": 94 },
+  "symbols_total": 6841,
+  "security_findings": 47,
+  "duration_ms": 4200
+}
+```
+---
+### `cairn_search` — Find anything across all languages
+```
+cairn_search({ query: "user authentication", language: "typescript" })
+```
+```json
+[
+  { "lang": "typescript", "kind": "function",  "fqn": "src/composables/useAuth.ts::useAuth" },
+  { "lang": "vue",        "kind": "component", "fqn": "src/components/LoginForm.vue::LoginForm" },
+  { "lang": "java",       "kind": "class",     "fqn": "com.example.auth.UserAuthenticator" }
+]
+```
+---
+### `cairn_bundle` — Minified source snapshot for Claude to read
+Strips comments and empty lines, writes a compressed `### File:` bundle. Use after `cairn_search` to give Claude readable source without blowing the context window.
+```
+cairn_bundle({ filter_paths: ["src/components/checkout"], bundle_name: "checkout" })
+```
+```json
+{
+  "bundle_path": "/your/project/.cairn/bundles/checkout.txt",
+  "original_kb": 284,
+  "compressed_kb": 91,
+  "reduction_pct": 68
+}
+```
+---
+### `cairn_describe` — Summarize a module
+```
+cairn_describe({ path: "src/components/checkout" })
+```
+```json
+{
+  "languages": ["vue", "typescript"],
+  "symbols": {
+    "component": ["CheckoutForm", "OrderSummary", "PaymentStep"],
+    "function":  ["useCheckout", "usePayment"]
+  },
+  "imports_from":  ["src/store/cart.ts", "src/api/orders.ts"],
+  "imported_by":   ["src/views/CartView.vue"],
+  "external_deps": ["stripe", "@stripe/stripe-js"]
+}
+```
+---
+### `cairn_code_graph` — Dependency health
+```
+cairn_code_graph({ mode: "instability" })
+```
+```json
+{
+  "modules": [
+    { "name": "src/views",       "instability": 1.0, "status": "safe_to_refactor" },
+    { "name": "src/composables", "instability": 0.4, "status": "review_before_change" },
+    { "name": "src/utils",       "instability": 0.1, "status": "load_bearing" }
+  ]
+}
+```
+Modes: `instability` · `health` · `cycles`
+---
+### `cairn_security` — Vulnerability scan
+```
+cairn_security({ severity: "HIGH" })
+```
+```json
+{
+  "total_findings": 12,
+  "by_language": { "typescript": 7, "java": 5 },
+  "findings": [
+    { "severity": "HIGH", "cwe": "CWE-79",  "file": "src/components/UserProfile.vue", "line": 84, "rule": "XSS via innerHTML" },
+    { "severity": "HIGH", "cwe": "CWE-611", "file": "backend/src/.../XmlParser.java",  "line": 47, "rule": "XXE" }
+  ]
+}
+```
+Covers: XSS · XXE · SQL injection · command injection · weak crypto · hardcoded secrets · open redirect · unsafe deserialization
+---
+### `cairn_checkpoint` — Save session state
+Tell Cairn what you were working on so the next session can pick up where you left off.
+```
+cairn_checkpoint({
+  message: "Added multi-currency to CheckoutForm, still need PaymentStep",
+  active_files: ["src/components/checkout/CheckoutForm.vue"],
+  notes: ["CurrencyService expects ISO 4217 codes, not symbols"]
+})
+```
+```json
+{
+  "saved": true,
+  "checkpoint_at": "2026-02-25T14:30:00Z",
+  "active_files_tracked": 1,
+  "notes_saved": 1
+}
+```
+---
+### `cairn_resume` — Restore session + smart re-index
+Call instead of `cairn_maintain` when resuming work. Detects which files changed and only re-indexes those.
+```
+cairn_resume()
+```
+```json
+{
+  "last_checkpoint": "2026-02-25T14:30:00Z",
+  "message": "Added multi-currency to CheckoutForm, still need PaymentStep",
+  "index_status": "incremental",
+  "files_reindexed": 2,
+  "files_unchanged": 845,
+  "changed_since_checkpoint": [
+    { "file": "src/components/checkout/PaymentStep.vue", "change": "modified" }
+  ],
+  "active_files": ["src/components/checkout/CheckoutForm.vue"],
+  "notes": ["CurrencyService expects ISO 4217 codes, not symbols"],
+  "resume_summary": "Last session you were adding multi-currency support..."
+}
+```
+---
+## Supported Languages
+| Language | What Cairn extracts |
+|---|---|
+| Java | packages, classes, interfaces, enums, records, methods |
+| TypeScript / JavaScript | classes, interfaces, functions, types, enums |
+| Vue | components, composables, script block symbols |
+| Python | classes, functions, decorators |
+| SQL | tables, views, stored procedures |
+| XML / HTML | bean ids, component names |
+| Config (YAML, properties, .env) | top-level keys |
+| Markdown | headings |
+| Build files (pom.xml, package.json, build.gradle) | dependencies |
+---
+## Typical session
+**Fresh start:**
+```
+1. cairn_maintain     → index project (persists between sessions)
+2. cairn_search       → find the symbols you need
+3. cairn_bundle       → get a readable snapshot of relevant files
+4. cairn_describe     → understand a module before modifying it
+5. cairn_security     → check for issues before a PR
+6. cairn_checkpoint   → save what you were working on
+```
+**Resuming work:**
+```
+1. cairn_resume       → restore session + incremental re-index
+2. cairn_search       → continue where you left off
+```
+## Complete session lifecycle
+```
+─── START OF SESSION ──────────────────────────────────────────
+You:    "Hey Claude, please resume and continue"
+Claude: cairn_resume
+        → "Last session: adding multi-currency to checkout.
+           PaymentStep.vue was modified since checkpoint (2 files changed, re-indexed).
+           Notes: CurrencyService expects ISO 4217 codes. PaymentStep EUR bug not fixed yet.
+           Ready to continue."
+─── DURING SESSION ────────────────────────────────────────────
+Claude uses: cairn_search, cairn_bundle, cairn_code_graph, cairn_security
+             as needed — all reading from .cairn/index.db in cwd
+─── END OF SESSION ────────────────────────────────────────────
+You:    "Ok let's stop here for today"
+Claude: cairn_checkpoint
+          message="Fixed EUR formatting in PaymentStep, multi-currency complete"
+          active_files=["src/components/checkout/PaymentStep.vue"]
+          notes=["Still need to add JPY — no decimal places", "QA needs to test AED"]
+        → "Session saved. Resume anytime with cairn_resume."
+```
+---
+## License
+MIT
+
+### File: bin/cairn-mcp.js
+#!/usr/bin/env node
+import { spawn } from 'child_process';
+import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const indexPath  = join(__dirname, '..', 'index.js');
+const child = spawn(
+  process.execPath,
+  ['--experimental-sqlite', '--no-warnings=ExperimentalWarning', indexPath],
+  { stdio: 'inherit', env: process.env }
+);
+child.on('exit', (code, signal) => {
+  if (signal) process.kill(process.pid, signal);
+  else process.exit(code ?? 0);
+});
+process.on('SIGTERM', () => child.kill('SIGTERM'));
+process.on('SIGINT',  () => child.kill('SIGINT'));
+
+### File: src/bundler/bundleWriter.js
+import fs from 'fs';
+import path from 'path';
+import { minifyContent } from './minifier.js';
+import { minifyVue }     from './vueMinifier.js';
+import { walkRepo, LANGUAGE_MAP } from '../indexer/fileWalker.js';
+import { getCairnDir } from '../graph/cwd.js';
+export async function writeBundle(options = {}) {
+  const {
+    bundleName   = 'default',
+    noComments   = true,
+    noEmptyLines = true,
+    noStyle      = false,
+    aggressive   = false,
+    onlyChanged  = false,
+    filterLang   = null,
+    filterPaths  = null,
+    maxSizeKB    = 800,
+  } = options;
+  const bundleDir = path.join(getCairnDir(), 'bundles');
+  const root      = process.cwd();
+  const outPath    = path.join(bundleDir, `${bundleName}.txt`);
+  const mtimePath  = path.join(bundleDir, `${bundleName}.mtime.json`);
+  const mtimeCache = onlyChanged && fs.existsSync(mtimePath)
+    ? JSON.parse(fs.readFileSync(mtimePath, 'utf8')) : {};
+  const newMtimes = {};
+  const lines     = [];
+  const stats     = {
+    processed: 0, skipped_unchanged: 0, skipped_size: 0,
+    original_bytes: 0, compressed_bytes: 0, by_language: {},
+  };
+  const langFilter = filterLang
+    ? (Array.isArray(filterLang) ? filterLang : [filterLang]) : null;
+  const files = await walkRepo(root);
+  for (const filePath of files) {
+    const ext      = path.extname(filePath).toLowerCase();
+    const language = LANGUAGE_MAP[ext];
+    if (!language) continue;
+    if (langFilter && !langFilter.includes(language)) continue;
+    if (filterPaths) {
+      const rel = path.relative(root, filePath).replace(/\\/g, '/');
+      if (!filterPaths.some(p => rel.startsWith(p))) continue;
+    }
+    const mtime = fs.statSync(filePath).mtimeMs;
+    newMtimes[filePath] = mtime;
+    if (onlyChanged && mtimeCache[filePath] === mtime) {
+      stats.skipped_unchanged++;
+      continue;
+    }
+    const currentKB = Buffer.byteLength(lines.join('\n'), 'utf8') / 1024;
+    if (currentKB > maxSizeKB) {
+      stats.skipped_size++;
+      continue;
+    }
+    let raw;
+    try {
+      raw = fs.readFileSync(filePath, 'utf8');
+    } catch {
+      continue;
+    }
+    stats.original_bytes += Buffer.byteLength(raw, 'utf8');
+    const minified = language === 'vue'
+      ? minifyVue(raw, { noStyle, noComments, noEmptyLines, aggressive })
+      : minifyContent(raw, language, { noComments, noEmptyLines, aggressive });
+    if (!minified.trim()) continue;
+    const rel = path.relative(root, filePath).replace(/\\/g, '/');
+    lines.push(`### File: ${rel}`);
+    lines.push(minified.trim());
+    lines.push('');
+    stats.compressed_bytes += Buffer.byteLength(minified, 'utf8');
+    stats.processed++;
+    stats.by_language[language] = (stats.by_language[language] || 0) + 1;
+  }
+  const output = lines.join('\n');
+  fs.writeFileSync(outPath, output, 'utf8');
+  if (onlyChanged) fs.writeFileSync(mtimePath, JSON.stringify(newMtimes), 'utf8');
+  const ratio = stats.original_bytes > 0
+    ? Math.round((1 - stats.compressed_bytes / stats.original_bytes) * 100) : 0;
+  return {
+    bundle_path:       outPath,
+    processed:         stats.processed,
+    skipped_unchanged: stats.skipped_unchanged,
+    skipped_size_cap:  stats.skipped_size,
+    original_kb:       Math.round(stats.original_bytes / 1024),
+    compressed_kb:     Math.round(stats.compressed_bytes / 1024),
+    reduction_pct:     ratio,
+    by_language:       stats.by_language,
+  };
+}
+
+### File: src/bundler/minifier.js
+export function minifyContent(content, language, options = {}) {
+  const { noComments = true, noEmptyLines = true, aggressive = false } = options;
+  let out = content;
+  if (noComments)   out = removeComments(out, language);
+  if (noEmptyLines) out = removeEmptyLines(out);
+  out = collapseWhitespace(out);
+  if (aggressive)   out = aggressiveMinify(out);
+  return out.trim();
+}
+function removeComments(content, language) {
+  switch (language) {
+    case 'java':
+    case 'typescript':
+    case 'javascript':
+    case 'vue':
+      return content
+        .replace(/\/\/.*$/gm, '')
+        .replace(/\/\*[\s\S]*?\*\
+    case 'python':
+      return content
+        .replace(/#.*$/gm, '')
+        .replace(/'''[\s\S]*?'''/g, '')
+        .replace(/"""[\s\S]*?"""/g, '');
+    case 'sql':
+      return content
+        .replace(/--.*$/gm, '')
+        .replace(/\/\*[\s\S]*?\*\
+    case 'xml':
+    case 'html':
+      return content.replace(/<!--[\s\S]*?-->/g, '');
+    case 'config':
+      return content.replace(/#.*$/gm, '');
+    default:
+      return content;
+  }
+}
+function removeEmptyLines(content) {
+  return content
+    .split('\n')
+    .filter(line => line.trim().length > 0)
+    .join('\n');
+}
+function collapseWhitespace(content) {
+  return content
+    .split('\n')
+    .map(line => line.trimEnd())
+    .join('\n');
+}
+function aggressiveMinify(content) {
+  return content
+    .replace(/\s+/g, ' ')
+    .replace(/\s*([=+\-*/%<>!&|^~?:;,{}()[\]])\s*/g, '$1')
+    .replace(/;\s*}/g, '}')
+    .replace(/\(\s+/g, '(')
+    .replace(/\s+\)/g, ')')
+    .trim();
+}
+
+### File: src/bundler/vueMinifier.js
+import { minifyContent } from './minifier.js';
+export function minifyVue(content, options = {}) {
+  const { noStyle = false, noComments = true, noEmptyLines = true, aggressive = false } = options;
+  const result = [];
+  const templateMatch = content.match(/<template>([\s\S]*?)<\/template>/i);
+  if (templateMatch) {
+    let tpl = templateMatch[1];
+    if (noComments)   tpl = tpl.replace(/<!--[\s\S]*?-->/g, '');
+    if (noEmptyLines) tpl = tpl.split('\n').filter(l => l.trim()).join('\n');
+    tpl = tpl.replace(/\s+/g, ' ').trim();
+    if (tpl) result.push(`<template>${tpl}</template>`);
+  }
+  const scriptMatch = content.match(/<script([^>]*)>([\s\S]*?)<\/script>/i);
+  if (scriptMatch) {
+    const attrs = scriptMatch[1];
+    const code = minifyContent(scriptMatch[2], 'javascript',
+      { noComments, noEmptyLines, aggressive });
+    const tag = /setup/i.test(attrs) ? '<script setup>' : '<script>';
+    if (code) result.push(`${tag}${code}</script>`);
+  }
+  if (!noStyle) {
+    const styleMatch = content.match(/<style([^>]*)>([\s\S]*?)<\/style>/i);
+    if (styleMatch) {
+      const css = styleMatch[2]
+        .replace(/\/\*[\s\S]*?\*\
+        .replace(/\s+/g, ' ').trim();
+      if (css) result.push(`<style${styleMatch[1]}>${css}</style>`);
+    }
+  }
+  return result.join('\n\n');
+}
+
+### File: src/graph/cwd.js
+import fs from 'fs';
+import path from 'path';
+export function getCairnDir() {
+  const cairnDir = path.join(process.cwd(), '.cairn');
+  fs.mkdirSync(path.join(cairnDir, 'bundles'), { recursive: true });
+  return cairnDir;
+}
+
+### File: src/graph/db.js
+import { DatabaseSync } from 'node:sqlite';
+import path from 'path';
+import { getCairnDir } from './cwd.js';
+const SCHEMA = `
+  CREATE TABLE IF NOT EXISTS files (
+    id           INTEGER PRIMARY KEY,
+    repo         TEXT NOT NULL,
+    path         TEXT NOT NULL UNIQUE,
+    language     TEXT,
+    file_type    TEXT,
+    last_indexed INTEGER
+  );
+  CREATE TABLE IF NOT EXISTS symbols (
+    id          INTEGER PRIMARY KEY,
+    file_id     INTEGER REFERENCES files(id) ON DELETE CASCADE,
+    fqn         TEXT UNIQUE,
+    name        TEXT NOT NULL,
+    kind        TEXT,
+    language    TEXT,
+    exported    INTEGER DEFAULT 0,
+    description TEXT
+  );
+  CREATE TABLE IF NOT EXISTS dependencies (
+    from_file_id INTEGER REFERENCES files(id),
+    to_fqn       TEXT,
+    dep_type     TEXT
+  );
+  CREATE TABLE IF NOT EXISTS build_deps (
+    repo        TEXT,
+    manager     TEXT,
+    group_id    TEXT,
+    artifact    TEXT,
+    version     TEXT,
+    scope       TEXT
+  );
+  CREATE TABLE IF NOT EXISTS security_findings (
+    id           INTEGER PRIMARY KEY,
+    file_id      INTEGER REFERENCES files(id),
+    line         INTEGER,
+    severity     TEXT,
+    cwe          TEXT,
+    rule_name    TEXT,
+    description  TEXT,
+    code_snippet TEXT
+  );
+  CREATE VIRTUAL TABLE IF NOT EXISTS fts_index USING fts5(
+    fqn, name, description, path, repo, language, kind
+  );
+`;
+export function openDB() {
+  const dbPath = path.join(getCairnDir(), 'index.db');
+  const db = new DatabaseSync(dbPath);
+  db.exec('PRAGMA journal_mode = WAL');
+  db.exec('PRAGMA synchronous = NORMAL');
+  db.exec(SCHEMA);
+  return db;
+}
+
+### File: src/graph/edges.js
+export function insertDependency(db, { from_file_id, to_fqn, dep_type }) {
+  db.prepare('INSERT INTO dependencies (from_file_id, to_fqn, dep_type) VALUES (?, ?, ?)')
+    .run(from_file_id, to_fqn, dep_type);
+}
+export function insertBuildDep(db, { repo, manager, group_id, artifact, version, scope }) {
+  const existing = db.prepare(
+    'SELECT rowid FROM build_deps WHERE repo=? AND manager=? AND artifact=?'
+  ).get(repo, manager, artifact);
+  if (!existing) {
+    db.prepare(
+      'INSERT INTO build_deps (repo, manager, group_id, artifact, version, scope) VALUES (?, ?, ?, ?, ?, ?)'
+    ).run(repo, manager, group_id, artifact, version, scope);
+  }
+}
+export function insertSecurityFinding(db, { file_id, line, severity, cwe, rule_name, description, code_snippet }) {
+  db.prepare(
+    'INSERT INTO security_findings (file_id, line, severity, cwe, rule_name, description, code_snippet) VALUES (?, ?, ?, ?, ?, ?, ?)'
+  ).run(file_id, line, severity, cwe, rule_name, description, code_snippet);
+}
+
+### File: src/graph/nodes.js
+export function upsertFile(db, { repo, path, language, file_type }) {
+  const existing = db.prepare('SELECT id FROM files WHERE path = ?').get(path);
+  if (existing) {
+    db.prepare('UPDATE files SET language = ?, file_type = ?, last_indexed = ? WHERE id = ?')
+      .run(language, file_type, Date.now(), existing.id);
+    return existing.id;
+  }
+  const result = db.prepare(
+    'INSERT INTO files (repo, path, language, file_type, last_indexed) VALUES (?, ?, ?, ?, ?)'
+  ).run(repo, path, language, file_type, Date.now());
+  return result.lastInsertRowid;
+}
+export function upsertSymbol(db, { file_id, fqn, name, kind, language, exported, description }) {
+  const existing = db.prepare('SELECT id FROM symbols WHERE fqn = ?').get(fqn);
+  if (existing) {
+    db.prepare(
+      'UPDATE symbols SET file_id=?, name=?, kind=?, language=?, exported=?, description=? WHERE id=?'
+    ).run(file_id, name, kind, language, exported ? 1 : 0, description || '', existing.id);
+  } else {
+    db.prepare(
+      'INSERT INTO symbols (file_id, fqn, name, kind, language, exported, description) VALUES (?, ?, ?, ?, ?, ?, ?)'
+    ).run(file_id, fqn, name, kind, language, exported ? 1 : 0, description || '');
+  }
+}
+export function clearFileData(db, fileId) {
+  db.prepare('DELETE FROM dependencies WHERE from_file_id = ?').run(fileId);
+  db.prepare('DELETE FROM security_findings WHERE file_id = ?').run(fileId);
+}
+
+### File: src/indexer/fileWalker.js
+import fg from 'fast-glob';
+export const LANGUAGE_MAP = {
+  '.java':       'java',
+  '.ts':         'typescript',
+  '.tsx':        'typescript',
+  '.js':         'javascript',
+  '.jsx':        'javascript',
+  '.mjs':        'javascript',
+  '.vue':        'vue',
+  '.py':         'python',
+  '.sql':        'sql',
+  '.yml':        'config',
+  '.yaml':       'config',
+  '.properties': 'config',
+  '.env':        'config',
+  '.xml':        'xml',
+  '.html':       'html',
+  '.md':         'markdown',
+};
+export const BUILD_FILES = ['pom.xml', 'package.json', 'build.gradle'];
+const IGNORE = [
+  '**/node_modules.gitdistbuildtarget.next__pycache__*.min.js',
+];
+export async function walkRepo(repoRoot) {
+  const patterns = Object.keys(LANGUAGE_MAP).map(ext => `**/*${ext}`);
+  const files = await fg(patterns, { cwd: repoRoot, ignore: IGNORE, absolute: true });
+  return files;
+}
+
+### File: src/indexer/parserFactory.js
+import path from 'path';
+import { LANGUAGE_MAP } from './fileWalker.js';
+import { parseJava }     from './parsers/javaParser.js';
+import { parseTS }       from './parsers/tsParser.js';
+import { parseVue }      from './parsers/vueParser.js';
+import { parsePython }   from './parsers/pythonParser.js';
+import { parseSQL }      from './parsers/sqlParser.js';
+import { parseConfig }   from './parsers/configParser.js';
+import { parseXML }      from './parsers/xmlParser.js';
+import { parseMarkdown } from './parsers/markdownParser.js';
+const PARSERS = {
+  java:       parseJava,
+  typescript: parseTS,
+  javascript: parseTS,
+  vue:        parseVue,
+  python:     parsePython,
+  sql:        parseSQL,
+  config:     parseConfig,
+  xml:        parseXML,
+  html:       parseXML,
+  markdown:   parseMarkdown,
+};
+export function getParser(filePath) {
+  const ext = path.extname(filePath).toLowerCase();
+  const language = LANGUAGE_MAP[ext];
+  return { language, parser: PARSERS[language] || null };
+}
+export async function parseFile(filePath, content, repoName) {
+  const { language, parser } = getParser(filePath);
+  if (!parser) return null;
+  return parser(filePath, content, repoName, language);
+}
+
+### File: src/indexer/securityScanner.js
+export const VULN_PATTERNS = [
+  { id: 'CWE-611', lang: ['java'],                          severity: 'HIGH',
+    name: 'XXE (XML External Entity)',
+    pattern: /builder\.parse\(/,
+    negPattern: /setFeature.*FEATURE_SECURE_PROCESSING/,
+    fix: 'Add dbf.setFeature(XMLConstants.FEATURE_SECURE_PROCESSING, true) before parse()' },
+  { id: 'CWE-89',  lang: ['java'],                          severity: 'HIGH',
+    name: 'SQL Injection',
+    pattern: /"SELECT|INSERT|UPDATE|DELETE.*"\s*\+/i,
+    fix: 'Use PreparedStatement with parameterized queries' },
+  { id: 'CWE-326', lang: ['java'],                          severity: 'HIGH',
+    name: 'Weak Cryptography',
+    pattern: /getInstance\("(MD5|SHA1|DES|RC4)"\)/,
+    fix: 'Use SHA-256 or AES-256' },
+  { id: 'CWE-502', lang: ['java'],                          severity: 'HIGH',
+    name: 'Unsafe Deserialization',
+    pattern: /new ObjectInputStream|\.readObject\(\)/,
+    fix: 'Validate input before deserialization; use safe deserialization libraries' },
+  { id: 'CWE-078', lang: ['java'],                          severity: 'HIGH',
+    name: 'Command Injection',
+    pattern: /Runtime\.getRuntime\(\)\.exec\(/,
+    fix: 'Use ProcessBuilder with argument list instead of string concatenation' },
+  { id: 'CWE-79',  lang: ['javascript', 'typescript', 'vue'], severity: 'HIGH',
+    name: 'XSS via innerHTML / dangerouslySetInnerHTML',
+    pattern: /\.innerHTML\s*=|dangerouslySetInnerHTML/,
+    fix: 'Use textContent or sanitize with DOMPurify' },
+  { id: 'CWE-89',  lang: ['javascript', 'typescript'],       severity: 'HIGH',
+    name: 'SQL Injection (JS)',
+    pattern: /`\s*(SELECT|INSERT|UPDATE|DELETE).*\$\{/i,
+    fix: 'Use parameterized queries or an ORM' },
+  { id: 'CWE-798', lang: ['javascript', 'typescript', 'vue'], severity: 'HIGH',
+    name: 'Hardcoded Secret',
+    pattern: /(api_key|apikey|secret|password|token)\s*[:=]\s*['"][^'"]{8,}['"]/i,
+    fix: 'Move secrets to environment variables or a secrets manager' },
+  { id: 'CWE-327', lang: ['javascript', 'typescript'],        severity: 'MEDIUM',
+    name: 'Weak Crypto (Node)',
+    pattern: /createHash\(['"]md5['"]\)|createHash\(['"]sha1['"]\)/,
+    fix: 'Use SHA-256 or stronger' },
+  { id: 'CWE-601', lang: ['javascript', 'typescript', 'vue'], severity: 'MEDIUM',
+    name: 'Open Redirect',
+    pattern: /res\.redirect\([^)]*req\.(query|params|body)/,
+    fix: 'Validate redirect URL against an allowlist' },
+  { id: 'CWE-089', lang: ['python'],                          severity: 'HIGH',
+    name: 'SQL Injection (Python)',
+    pattern: /execute\([f"'].*%(s|d)|execute\(.*format\(/,
+    fix: 'Use parameterized queries: cursor.execute(sql, params)' },
+  { id: 'CWE-078', lang: ['python'],                          severity: 'HIGH',
+    name: 'Command Injection (Python)',
+    pattern: /os\.system\(|subprocess\.call\(.*shell=True/,
+    fix: 'Use subprocess with a list of args and shell=False' },
+  { id: 'CWE-798', lang: ['python'],                          severity: 'HIGH',
+    name: 'Hardcoded Secret (Python)',
+    pattern: /(api_key|secret|password|token)\s*=\s*['"][^'"]{8,}['"]/i,
+    fix: 'Use environment variables or a secrets manager like Vault' },
+  { id: 'CWE-312', lang: null,                                severity: 'MEDIUM',
+    name: 'Cleartext Sensitive Data in Comments',
+    pattern: /\/\/.*?(password|secret|token)\s*[:=]\s*\S+/i,
+    fix: 'Remove sensitive data from comments' },
+];
+export function scanFile(filePath, content, language) {
+  const findings = [];
+  const lines = content.split('\n');
+  for (const rule of VULN_PATTERNS) {
+    if (rule.lang && !rule.lang.includes(language)) continue;
+    lines.forEach((line, i) => {
+      if (!rule.pattern.test(line)) return;
+      if (rule.negPattern) {
+        const ctx = lines.slice(Math.max(0, i - 5), i + 5).join('\n');
+        if (rule.negPattern.test(ctx)) return;
+      }
+      findings.push({
+        severity:     rule.severity,
+        cwe:          rule.id,
+        rule_name:    rule.name,
+        line:         i + 1,
+        code_snippet: line.trim().substring(0, 120),
+        description:  rule.fix,
+      });
+    });
+  }
+  return findings;
+}
+
+### File: src/tools/bundle.js
+import { writeBundle } from '../bundler/bundleWriter.js';
+export async function bundle(_db, args) {
+  const {
+    bundle_name      = 'default',
+    filter_paths     = null,
+    filter_language  = null,
+    no_comments      = true,
+    no_empty_lines   = true,
+    no_style         = false,
+    aggressive       = false,
+    only_changed     = false,
+    max_size_kb      = 800,
+  } = args;
+  const result = await writeBundle({
+    bundleName:   bundle_name,
+    noComments:   no_comments,
+    noEmptyLines: no_empty_lines,
+    noStyle:      no_style,
+    aggressive,
+    onlyChanged:  only_changed,
+    filterLang:   filter_language,
+    filterPaths:  filter_paths,
+    maxSizeKB:    max_size_kb,
+  });
+  return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+}
+
+### File: src/tools/checkpoint.js
+import fs from 'fs';
+import path from 'path';
+import { getCairnDir } from '../graph/cwd.js';
+export function checkpoint(_db, { message, active_files = [], notes = [] }) {
+  const cairnDir = getCairnDir();
+  const sessionPath = path.join(cairnDir, 'session.json');
+  const mtimeSnapshot = {};
+  for (const filePath of active_files) {
+    try {
+      mtimeSnapshot[filePath] = fs.statSync(filePath).mtimeMs;
+    } catch {
+    }
+  }
+  const session = {
+    message,
+    checkpoint_at: new Date().toISOString(),
+    active_files,
+    notes,
+    mtime_snapshot: mtimeSnapshot,
+  };
+  fs.writeFileSync(sessionPath, JSON.stringify(session, null, 2), 'utf8');
+  return {
+    content: [{
+      type: 'text',
+      text: JSON.stringify({
+        saved: true,
+        checkpoint_at: session.checkpoint_at,
+        active_files_tracked: active_files.length,
+        notes_saved: notes.length,
+      }, null, 2),
+    }],
+  };
+}
+
+### File: src/tools/codeGraph.js
+export function codeGraph(db, { module: modFilter, mode }) {
+  if (mode === 'health') {
+    const fileCount    = db.prepare('SELECT COUNT(*) as c FROM files').get()?.c || 0;
+    const symbolCount  = db.prepare('SELECT COUNT(*) as c FROM symbols').get()?.c || 0;
+    const depCount     = db.prepare('SELECT COUNT(*) as c FROM dependencies').get()?.c || 0;
+    const findingCount = db.prepare('SELECT COUNT(*) as c FROM security_findings').get()?.c || 0;
+    const byLang       = db.prepare('SELECT language, COUNT(*) as count FROM files GROUP BY language').all();
+    const lastIndexed  = db.prepare('SELECT MAX(last_indexed) as t FROM files').get()?.t;
+    return {
+      content: [{
+        type: 'text',
+        text: JSON.stringify({
+          files: fileCount, symbols: symbolCount,
+          dependencies: depCount, security_findings: findingCount,
+          by_language: byLang,
+          last_indexed: lastIndexed ? new Date(lastIndexed).toISOString() : null,
+        }, null, 2),
+      }],
+    };
+  }
+  if (mode === 'instability') {
+    const files = db.prepare('SELECT id, path, language FROM files').all();
+    const modules = {};
+    for (const f of files) {
+      const parts = f.path.replace(/\\/g, '/').split('/');
+      const moduleName = parts.slice(0, -1).join('/') || '/';
+      if (modFilter && !moduleName.includes(modFilter)) continue;
+      if (!modules[moduleName]) modules[moduleName] = { name: moduleName, language: f.language, fileIds: [] };
+      modules[moduleName].fileIds.push(f.id);
+    }
+    const results = [];
+    for (const [, mod] of Object.entries(modules)) {
+      if (mod.fileIds.length === 0) continue;
+      const ph = mod.fileIds.map(() => '?').join(',');
+      const ce = db.prepare(
+        `SELECT COUNT(DISTINCT to_fqn) as c FROM dependencies WHERE from_file_id IN (${ph})`
+      ).get(...mod.fileIds)?.c || 0;
+      const fqns = db.prepare(
+        `SELECT fqn FROM symbols WHERE file_id IN (${ph})`
+      ).all(...mod.fileIds).map(s => s.fqn);
+      let ca = 0;
+      if (fqns.length > 0) {
+        const sph = fqns.map(() => '?').join(',');
+        ca = db.prepare(
+          `SELECT COUNT(DISTINCT from_file_id) as c FROM dependencies WHERE to_fqn IN (${sph})`
+        ).get(...fqns)?.c || 0;
+      }
+      const instability = (ca + ce) === 0 ? 0 : ce / (ca + ce);
+      const status = instability >= 0.8 ? 'safe_to_refactor'
+                   : instability >= 0.3 ? 'review_before_change'
+                   : 'load_bearing';
+      results.push({
+        name: mod.name,
+        language: mod.language,
+        instability: Math.round(instability * 100) / 100,
+        status,
+      });
+    }
+    results.sort((a, b) => b.instability - a.instability);
+    const godObjects = db.prepare(`
+      SELECT s.name || ' (' || COALESCE(s.language,'?') || ')' as label, COUNT(*) as dep_count
+      FROM dependencies d JOIN symbols s ON d.to_fqn = s.fqn
+      GROUP BY d.to_fqn ORDER BY dep_count DESC LIMIT 5
+    `).all().map(r => `${r.label} (${r.dep_count} deps)`);
+    return {
+      content: [{
+        type: 'text',
+        text: JSON.stringify({
+          modules: results.slice(0, 50),
+          god_objects: godObjects,
+          cycles_detected: [],
+        }, null, 2),
+      }],
+    };
+  }
+  if (mode === 'cycles') {
+    const cycles = db.prepare(`
+      SELECT DISTINCT f1.path as from_path, f2.path as to_path
+      FROM dependencies d1
+      JOIN symbols s1 ON d1.to_fqn = s1.fqn
+      JOIN files f1 ON d1.from_file_id = f1.id
+      JOIN files f2 ON s1.file_id = f2.id
+      JOIN dependencies d2 ON d2.from_file_id = f2.id
+      JOIN symbols s2 ON d2.to_fqn = s2.fqn
+      WHERE s2.file_id = d1.from_file_id
+      LIMIT 20
+    `).all();
+    return {
+      content: [{ type: 'text', text: JSON.stringify({ cycles_detected: cycles }, null, 2) }],
+    };
+  }
+  return { content: [{ type: 'text', text: JSON.stringify({ error: `Unknown mode: ${mode}` }) }] };
+}
+
+### File: src/tools/describe.js
+export function describe(db, { path: dirPath }) {
+  const files = db.prepare('SELECT * FROM files WHERE path LIKE ?').all(`${dirPath}%`);
+  if (files.length === 0) {
+    return { content: [{ type: 'text', text: JSON.stringify({ path: dirPath, error: 'No files found' }) }] };
+  }
+  const fileIds = files.map(f => f.id);
+  const languages = [...new Set(files.map(f => f.language).filter(Boolean))];
+  const ph = fileIds.map(() => '?').join(',');
+  const symbols = db.prepare(`SELECT * FROM symbols WHERE file_id IN (${ph})`).all(...fileIds);
+  const grouped = {};
+  for (const sym of symbols) {
+    const key = sym.kind || 'other';
+    if (!grouped[key]) grouped[key] = [];
+    grouped[key].push(sym.name);
+  }
+  const outgoing = db.prepare(
+    `SELECT DISTINCT to_fqn FROM dependencies WHERE from_file_id IN (${ph}) AND dep_type = 'imports'`
+  ).all(...fileIds).map(r => r.to_fqn);
+  let incomingPaths = [];
+  if (symbols.length > 0) {
+    const fqns = symbols.map(s => s.fqn);
+    const sph  = fqns.map(() => '?').join(',');
+    incomingPaths = db.prepare(
+      `SELECT DISTINCT f.path FROM dependencies d JOIN files f ON d.from_file_id = f.id WHERE d.to_fqn IN (${sph})`
+    ).all(...fqns).map(r => r.path);
+  }
+  const allFqns = new Set(db.prepare('SELECT fqn FROM symbols').all().map(s => s.fqn));
+  const externalDeps = [...new Set(outgoing.filter(fqn => !allFqns.has(fqn)))].slice(0, 20);
+  const result = {
+    path: dirPath,
+    languages,
+    symbols: grouped,
+    imports_from:  outgoing.slice(0, 20),
+    imported_by:   incomingPaths.slice(0, 20),
+    external_deps: externalDeps,
+  };
+  return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+}
+
+### File: src/tools/maintain.js
+import fs from 'fs/promises';
+import path from 'path';
+import { walkRepo, BUILD_FILES } from '../indexer/fileWalker.js';
+import { parseFile } from '../indexer/parserFactory.js';
+import { scanFile } from '../indexer/securityScanner.js';
+import { parseMaven } from '../indexer/buildParsers/mavenParser.js';
+import { parseNpm }   from '../indexer/buildParsers/npmParser.js';
+import { parseGradle } from '../indexer/buildParsers/gradleParser.js';
+import { upsertFile, upsertSymbol, clearFileData } from '../graph/nodes.js';
+import { insertDependency, insertBuildDep, insertSecurityFinding } from '../graph/edges.js';
+function inferFileType(filePath) {
+  const fp = filePath.toLowerCase();
+  if (fp.includes('test') || fp.includes('spec')) return 'test';
+  if (fp.endsWith('pom.xml') || fp.endsWith('package.json') || fp.endsWith('build.gradle')) return 'build';
+  if (fp.endsWith('.yml') || fp.endsWith('.yaml') || fp.endsWith('.properties') || fp.endsWith('.env')) return 'config';
+  if (fp.endsWith('.md') || fp.endsWith('.html')) return 'doc';
+  return 'source';
+}
+async function indexFile(db, filePath, repoName, languages, stats) {
+  try {
+    const content = await fs.readFile(filePath, 'utf-8');
+    const result = await parseFile(filePath, content, repoName);
+    if (!result) return;
+    const { language } = result;
+    if (languages && !languages.includes(language)) return;
+    stats.files_by_language[language] = (stats.files_by_language[language] || 0) + 1;
+    const fileId = upsertFile(db, {
+      repo: repoName,
+      path: filePath,
+      language,
+      file_type: inferFileType(filePath),
+    });
+    clearFileData(db, fileId);
+    for (const sym of (result.symbols || [])) {
+      upsertSymbol(db, { ...sym, file_id: fileId, language });
+      stats.symbols_total++;
+    }
+    for (const imp of (result.imports || [])) {
+      insertDependency(db, { from_file_id: fileId, to_fqn: imp, dep_type: 'imports' });
+      stats.dependencies_mapped++;
+    }
+    const findings = scanFile(filePath, content, language);
+    for (const f of findings) {
+      insertSecurityFinding(db, { file_id: fileId, ...f });
+      stats.security_findings++;
+    }
+  } catch {
+  }
+}
+function rebuildFts(db) {
+  db.exec(`
+    DELETE FROM fts_index;
+    INSERT INTO fts_index(fqn, name, description, path, repo, language, kind)
+    SELECT s.fqn, s.name, COALESCE(s.description,''), f.path, f.repo, s.language, s.kind
+    FROM symbols s JOIN files f ON s.file_id = f.id;
+  `);
+}
+export async function maintain(db, { languages } = {}) {
+  const startTime = Date.now();
+  const root = process.cwd();
+  const repoName = path.basename(root);
+  const stats = {
+    repos_indexed: 1,
+    files_by_language: {},
+    symbols_total: 0,
+    dependencies_mapped: 0,
+    security_findings: 0,
+  };
+  const files = await walkRepo(root);
+  for (const filePath of files) {
+    await indexFile(db, filePath, repoName, languages, stats);
+  }
+  for (const buildFile of BUILD_FILES) {
+    const buildPath = path.join(root, buildFile);
+    try {
+      const content = await fs.readFile(buildPath, 'utf-8');
+      let deps = [];
+      if (buildFile === 'pom.xml')           deps = parseMaven(buildPath, content, repoName);
+      else if (buildFile === 'package.json') deps = parseNpm(buildPath, content, repoName);
+      else if (buildFile === 'build.gradle') deps = parseGradle(buildPath, content, repoName);
+      for (const dep of deps) insertBuildDep(db, { repo: repoName, ...dep });
+    } catch {
+    }
+  }
+  rebuildFts(db);
+  stats.duration_ms = Date.now() - startTime;
+  return { content: [{ type: 'text', text: JSON.stringify(stats, null, 2) }] };
+}
+export async function incrementalMaintain(db, changedFiles) {
+  const root = process.cwd();
+  const repoName = path.basename(root);
+  const stats = {
+    files_by_language: {},
+    symbols_total: 0,
+    dependencies_mapped: 0,
+    security_findings: 0,
+  };
+  for (const filePath of changedFiles) {
+    await indexFile(db, filePath, repoName, null, stats);
+  }
+  rebuildFts(db);
+  return stats;
+}
+
+### File: src/tools/resume.js
+import fs from 'fs';
+import path from 'path';
+import { getCairnDir } from '../graph/cwd.js';
+import { walkRepo } from '../indexer/fileWalker.js';
+import { incrementalMaintain } from './maintain.js';
+export async function resume(db) {
+  const cairnDir = getCairnDir();
+  const sessionPath = path.join(cairnDir, 'session.json');
+  if (!fs.existsSync(sessionPath)) {
+    return {
+      content: [{
+        type: 'text',
+        text: JSON.stringify({
+          error: 'No checkpoint found. Run cairn_maintain to index the project, then cairn_checkpoint to save session state.',
+        }, null, 2),
+      }],
+    };
+  }
+  const session = JSON.parse(fs.readFileSync(sessionPath, 'utf8'));
+  const snapshot = session.mtime_snapshot || {};
+  const changed = [];
+  for (const [filePath, savedMtime] of Object.entries(snapshot)) {
+    try {
+      const currentMtime = fs.statSync(filePath).mtimeMs;
+      if (currentMtime !== savedMtime) {
+        changed.push({ file: filePath, change: 'modified' });
+      }
+    } catch {
+      changed.push({ file: filePath, change: 'deleted' });
+    }
+  }
+  try {
+    const allFiles = await walkRepo(process.cwd());
+    for (const filePath of allFiles) {
+      if (!(filePath in snapshot)) {
+        changed.push({ file: filePath, change: 'new' });
+      }
+    }
+  } catch {
+  }
+  const filesToReindex = changed
+    .filter(c => c.change !== 'deleted')
+    .map(c => c.file);
+  let reindexStats = { files_reindexed: 0, files_unchanged: 0 };
+  if (filesToReindex.length > 0) {
+    const stats = await incrementalMaintain(db, filesToReindex);
+    reindexStats.files_reindexed = filesToReindex.length;
+  }
+  reindexStats.files_unchanged = Object.keys(snapshot).length - changed.filter(c => c.change !== 'new').length;
+  const changedSummary = changed.length > 0
+    ? changed.slice(0, 10).map(c => `${c.change}: ${path.relative(process.cwd(), c.file).replace(/\\/g, '/')}`).join(', ')
+    : 'none';
+  const resumeSummary = [
+    `Last session: ${session.message}`,
+    changed.length > 0 ? `Files changed since checkpoint: ${changedSummary}` : 'No files changed since checkpoint.',
+    session.notes?.length > 0 ? `Notes: ${session.notes.join(' | ')}` : '',
+  ].filter(Boolean).join(' ');
+  return {
+    content: [{
+      type: 'text',
+      text: JSON.stringify({
+        last_checkpoint: session.checkpoint_at,
+        message: session.message,
+        index_status: filesToReindex.length > 0 ? 'incremental' : 'up_to_date',
+        files_reindexed: reindexStats.files_reindexed,
+        files_unchanged: Math.max(0, reindexStats.files_unchanged),
+        changed_since_checkpoint: changed.slice(0, 20),
+        active_files: session.active_files || [],
+        notes: session.notes || [],
+        resume_summary: resumeSummary,
+      }, null, 2),
+    }],
+  };
+}
+
+### File: src/tools/search.js
+export function search(db, { query, limit = 10, language, kind }) {
+  if (!query?.trim()) {
+    return { content: [{ type: 'text', text: '[]' }] };
+  }
+  let sql = `
+    SELECT fqn, name, kind, language, description, path, repo,
+           bm25(fts_index) as score
+    FROM fts_index
+    WHERE fts_index MATCH ?
+  `;
+  const params = [query];
+  if (language) { sql += ' AND language = ?'; params.push(language); }
+  if (kind)     { sql += ' AND kind = ?';     params.push(kind); }
+  sql += ' ORDER BY bm25(fts_index) LIMIT ?';
+  params.push(limit);
+  try {
+    const results = db.prepare(sql).all(...params);
+    return { content: [{ type: 'text', text: JSON.stringify(results, null, 2) }] };
+  } catch (err) {
+    return { content: [{ type: 'text', text: JSON.stringify({ error: err.message }) }] };
+  }
+}
+
+### File: src/tools/security.js
+export function security(db, { paths, severity = 'HIGH', language }) {
+  let sql = `
+    SELECT sf.severity, sf.cwe, sf.rule_name as rule, sf.line,
+           sf.code_snippet as snippet, sf.description as fix,
+           f.path as file, f.language as lang
+    FROM security_findings sf
+    JOIN files f ON sf.file_id = f.id
+    WHERE 1=1
+  `;
+  const params = [];
+  if (severity === 'HIGH') {
+    sql += ` AND sf.severity = 'HIGH'`;
+  } else if (severity === 'MEDIUM') {
+    sql += ` AND sf.severity IN ('HIGH','MEDIUM')`;
+  } else if (severity !== 'ALL') {
+    sql += ' AND sf.severity = ?';
+    params.push(severity);
+  }
+  if (language) {
+    sql += ' AND f.language = ?';
+    params.push(language);
+  }
+  if (paths && paths.length > 0) {
+    sql += ` AND (${paths.map(() => 'f.path LIKE ?').join(' OR ')})`;
+    params.push(...paths.map(p => `${p}%`));
+  }
+  sql += ' ORDER BY sf.severity, f.path';
+  const findings = db.prepare(sql).all(...params);
+  const byLanguage = {};
+  const bySeverity = {};
+  for (const f of findings) {
+    byLanguage[f.lang]     = (byLanguage[f.lang]     || 0) + 1;
+    bySeverity[f.severity] = (bySeverity[f.severity] || 0) + 1;
+  }
+  return {
+    content: [{
+      type: 'text',
+      text: JSON.stringify({
+        total_findings: findings.length,
+        by_language: byLanguage,
+        by_severity: bySeverity,
+        findings: findings.slice(0, 100),
+      }, null, 2),
+    }],
+  };
+}
+
+### File: src/indexer/buildParsers/gradleParser.js
+export function parseGradle(filePath, content, repoName) {
+  const deps = [];
+  for (const m of content.matchAll(/(\w+)\s+['"]([^:'"]+):([^:'"]+):([^'"]+)['"]/g)) {
+    const scope    = m[1];
+    const group    = m[2];
+    const artifact = m[3];
+    const version  = m[4];
+    deps.push({ manager: 'gradle', group_id: group, artifact, version, scope });
+  }
+  return deps;
+}
+
+### File: src/indexer/buildParsers/mavenParser.js
+export function parseMaven(filePath, content, repoName) {
+  const deps = [];
+  for (const m of content.matchAll(/<dependency>([\s\S]*?)<\/dependency>/g)) {
+    const block      = m[1];
+    const groupId    = block.match(/<groupId>([^<]+)<\/groupId>/)?.[1] || '';
+    const artifactId = block.match(/<artifactId>([^<]+)<\/artifactId>/)?.[1] || '';
+    const version    = block.match(/<version>([^<]+)<\/version>/)?.[1] || '';
+    const scope      = block.match(/<scope>([^<]+)<\/scope>/)?.[1] || 'compile';
+    if (groupId && artifactId)
+      deps.push({ manager: 'maven', group_id: groupId, artifact: artifactId, version, scope });
+  }
+  return deps;
+}
+
+### File: src/indexer/buildParsers/npmParser.js
+export function parseNpm(filePath, content, repoName) {
+  const deps = [];
+  try {
+    const pkg = JSON.parse(content);
+    for (const [name, version] of Object.entries(pkg.dependencies || {}))
+      deps.push({ manager: 'npm', group_id: 'dependencies', artifact: name, version, scope: 'runtime' });
+    for (const [name, version] of Object.entries(pkg.devDependencies || {}))
+      deps.push({ manager: 'npm', group_id: 'devDependencies', artifact: name, version, scope: 'dev' });
+    for (const [name, version] of Object.entries(pkg.peerDependencies || {}))
+      deps.push({ manager: 'npm', group_id: 'peerDependencies', artifact: name, version, scope: 'peer' });
+  } catch {
+  }
+  return deps;
+}
+
+### File: src/indexer/parsers/configParser.js
+export function parseConfig(filePath, content, repoName) {
+  const symbols = [];
+  for (const m of content.matchAll(/^([\w.-]+)\s*[:=]\s*(.+)/gm)) {
+    const key = m[1].trim();
+    if (key.startsWith('#')) continue;
+    symbols.push({
+      name: key,
+      fqn: `${filePath}::${key}`,
+      kind: 'config-key',
+      exported: false,
+      description: m[2].trim().substring(0, 80),
+    });
+  }
+  return { language: 'config', symbols, imports: [] };
+}
+
+### File: src/indexer/parsers/javaParser.js
+export function parseJava(filePath, content, repoName) {
+  const pkg     = content.match(/^package\s+([\w.]+);/m)?.[1] || '';
+  const imports = [...content.matchAll(/^import\s+([\w.]+);/gm)].map(m => m[1]);
+  const classMatch = content.match(
+    /(?:public|protected)?\s+(?:abstract\s+)?(?:class|interface|enum|record)\s+(\w+)/
+  );
+  const name = classMatch?.[1] || '';
+  const kind = classMatch?.[0]?.match(/class|interface|enum|record/)?.[0] || 'class';
+  const fqn  = pkg ? `${pkg}.${name}` : name;
+  const methods = [...content.matchAll(
+    /(?:public|protected|private)[^{;]*\s+(\w+)\s*\([^)]*\)\s*(?:throws[^{]*)?\{/gm
+  )].map(m => m[1]);
+  const extendsMatch    = content.match(/extends\s+([\w.]+)/)?.[1];
+  const implementsMatch = content.match(/implements\s+([\w.,\s]+)/)?.[1]
+    ?.split(',').map(s => s.trim());
+  const javadoc = content.match(/\/\*\*([\s\S]*?)\*\
+    ?.replace(/\s*\*\s?/g, ' ').trim();
+  return {
+    language: 'java',
+    symbols: [{ name, fqn, kind, exported: true, description: javadoc || '' }],
+    imports,
+    extends: extendsMatch ? [extendsMatch] : [],
+    implements: implementsMatch || [],
+    methods,
+  };
+}
+
+### File: src/indexer/parsers/markdownParser.js
+export function parseMarkdown(filePath, content, repoName) {
+  const symbols = [];
+  for (const m of content.matchAll(/^(#{1,3})\s+(.+)/gm)) {
+    const level = m[1].length;
+    const title = m[2].trim();
+    symbols.push({
+      name: title,
+      fqn: `${filePath}::${title.replace(/\s+/g, '-').toLowerCase()}`,
+      kind: level === 1 ? 'doc-title' : 'doc-section',
+      exported: true,
+      description: '',
+    });
+  }
+  return { language: 'markdown', symbols, imports: [] };
+}
+
+### File: src/indexer/parsers/pythonParser.js
+export function parsePython(filePath, content, repoName) {
+  const symbols = [];
+  const imports = [];
+  for (const m of content.matchAll(/^from\s+([\w.]+)\s+import\s+([\w,\s*]+)/gm))
+    imports.push(...m[2].split(',').map(s => s.trim()).filter(Boolean));
+  for (const m of content.matchAll(/^import\s+([\w.,\s]+)/gm))
+    imports.push(...m[1].split(',').map(s => s.trim()).filter(Boolean));
+  for (const m of content.matchAll(/^class\s+(\w+)(?:\(([^)]*)\))?:/gm)) {
+    const docstring = content.slice(m.index).match(/:\s*\n\s+"""([\s\S]*?)"""/)?.[1]?.trim();
+    symbols.push({ name: m[1], fqn: `${filePath}::${m[1]}`, kind: 'class', exported: true, description: docstring || '' });
+  }
+  for (const m of content.matchAll(/^(?:async\s+)?def\s+(\w+)\s*\(/gm)) {
+    if (m[1].startsWith('_')) continue;
+    const docstring = content.slice(m.index).match(/\).*?:\s*\n\s+"""([\s\S]*?)"""/)?.[1]?.trim();
+    symbols.push({ name: m[1], fqn: `${filePath}::${m[1]}`, kind: 'function', exported: true, description: docstring || '' });
+  }
+  for (const m of content.matchAll(/^@([\w.]+)(?:\(([^)]*)\))?/gm))
+    symbols.push({ name: m[1], fqn: `${filePath}::@${m[1]}`, kind: 'decorator', exported: false, description: '' });
+  return { language: 'python', symbols, imports };
+}
+
+### File: src/indexer/parsers/sqlParser.js
+export function parseSQL(filePath, content, repoName) {
+  const symbols = [];
+  for (const m of content.matchAll(/CREATE\s+TABLE\s+(?:IF\s+NOT\s+EXISTS\s+)?([`"\w.]+)/gi))
+    symbols.push({ name: m[1], fqn: `${filePath}::${m[1]}`, kind: 'table', exported: true, description: '' });
+  for (const m of content.matchAll(/CREATE\s+(?:OR\s+REPLACE\s+)?(?:PROCEDURE|FUNCTION)\s+(\w+)/gi))
+    symbols.push({ name: m[1], fqn: `${filePath}::${m[1]}`, kind: 'function', exported: true, description: '' });
+  for (const m of content.matchAll(/CREATE\s+(?:OR\s+REPLACE\s+)?VIEW\s+(\w+)/gi))
+    symbols.push({ name: m[1], fqn: `${filePath}::${m[1]}`, kind: 'view', exported: true, description: '' });
+  return { language: 'sql', symbols, imports: [] };
+}
+
+### File: src/indexer/parsers/tsParser.js
+export function parseTS(filePath, content, repoName, language = 'typescript') {
+  const symbols = [];
+  const imports = [];
+  for (const m of content.matchAll(/import\s+\{([^}]+)\}\s+from\s+['"]([^'"]+)['"]/g))
+    imports.push(...m[1].split(',').map(s => s.trim().split(' as ')[0]).filter(Boolean));
+  for (const m of content.matchAll(/import\s+(\w+)\s+from\s+['"]([^'"]+)['"]/g))
+    imports.push(m[1]);
+  for (const m of content.matchAll(/(?:export\s+)?(?:abstract\s+)?class\s+(\w+)/g)) {
+    const exported = m[0].startsWith('export');
+    const jsdoc = extractJSDoc(content, m.index);
+    symbols.push({ name: m[1], fqn: `${filePath}::${m[1]}`, kind: 'class', exported, description: jsdoc });
+  }
+  for (const m of content.matchAll(/export\s+(?:interface|type)\s+(\w+)/g))
+    symbols.push({ name: m[1], fqn: `${filePath}::${m[1]}`, kind: 'interface', exported: true, description: '' });
+  for (const m of content.matchAll(/export\s+(?:async\s+)?function\s+(\w+)/g)) {
+    const jsdoc = extractJSDoc(content, m.index);
+    symbols.push({ name: m[1], fqn: `${filePath}::${m[1]}`, kind: 'function', exported: true, description: jsdoc });
+  }
+  for (const m of content.matchAll(/export\s+const\s+(\w+)\s*=\s*(?:async\s+)?\(/g))
+    symbols.push({ name: m[1], fqn: `${filePath}::${m[1]}`, kind: 'function', exported: true, description: '' });
+  for (const m of content.matchAll(/export\s+(?:const\s+)?enum\s+(\w+)/g))
+    symbols.push({ name: m[1], fqn: `${filePath}::${m[1]}`, kind: 'enum', exported: true, description: '' });
+  return { language, symbols, imports };
+}
+function extractJSDoc(content, index) {
+  const before = content.substring(0, index);
+  const match  = before.match(/\/\*\*([\s\S]*?)\*\/\s*$/);
+  return match ? match[1].replace(/\s*\*\s?/g, ' ').trim() : '';
+}
+
+### File: src/indexer/parsers/vueParser.js
+import { parseTS } from './tsParser.js';
+export function parseVue(filePath, content, repoName) {
+  const componentName = filePath.split('/').pop().replace('.vue', '');
+  const scriptMatch = content.match(/<script(?:\s+setup)?(?:\s+lang=["']ts["'])?>([\s\S]*?)<\/script>/i);
+  const scriptContent = scriptMatch?.[1] || '';
+  const parsed = parseTS(filePath, scriptContent, repoName, 'vue');
+  const templateMatch = content.match(/<template>([\s\S]*?)<\/template>/i);
+  const childComponents = [...(templateMatch?.[1]?.matchAll(/<([A-Z][A-Za-z]+)/g) || [])]
+    .map(m => m[1]);
+  parsed.symbols.unshift({
+    name: componentName,
+    fqn: `${filePath}::${componentName}`,
+    kind: 'component',
+    exported: true,
+    description: `Vue component: ${componentName}`,
+  });
+  parsed.childComponents = [...new Set(childComponents)];
+  return parsed;
+}
+
+### File: src/indexer/parsers/xmlParser.js
+const HTML_TAGS = new Set([
+  'div','span','p','a','ul','ol','li','table','tr','td','th','thead','tbody',
+  'form','input','button','select','option','textarea','label','img','br','hr',
+  'h1','h2','h3','h4','h5','h6','head','body','html','script','style','link',
+  'meta','nav','header','footer','main','section','article','aside','figure',
+]);
+export function parseXML(filePath, content, repoName) {
+  const symbols = [];
+  for (const m of content.matchAll(/\bid\s*=\s*["']([^"']+)["']/g))
+    symbols.push({ name: m[1], fqn: `${filePath}::${m[1]}`, kind: 'bean', exported: true, description: '' });
+  const seen = new Set();
+  for (const m of content.matchAll(/<([a-z][a-z0-9-]*)(?:\s|\/?>)/gi)) {
+    const tag = m[1].toLowerCase();
+    if (HTML_TAGS.has(tag) || seen.has(tag)) continue;
+    seen.add(tag);
+    symbols.push({ name: tag, fqn: `${filePath}::${tag}`, kind: 'component', exported: true, description: '' });
+  }
+  return { language: 'xml', symbols, imports: [] };
+}