graph-indexer 1.1.0 → 2.0.0

package/storage.mjs

@@ -0,0 +1,68 @@
+/**
+ * @file storage.mjs
+ * @description Storage backend factory. Selects the in-memory engine (default,
+ *              zero-dependency) or the disk-backed SQLite store based on config,
+ *              and documents the single read contract that the MCP tools depend
+ *              on so they remain backend-agnostic.
+ * @author MaquinaTech <https://github.com/MaquinaTech>
+ * @copyright (c) 2026 MaquinaTech. All rights reserved.
+ * @license MIT
+ *
+ * ── Store contract (implemented by both MemoryGraphIndex and SqliteGraphStore) ──
+ *   load()                                   Prepare for queries (open db / parse json).
+ *   get backend()                            'memory' | 'sqlite'.
+ *   get graph()                              { dependencies, importedBy } (file-level).
+ *   searchHybrid(q, vec, topK, minScore, exactBoost) → [{ score, chunk }]
+ *   getChunk(id)                             → chunk | null
+ *   getChunksByFile(path)                    → chunk[]
+ *   resolveSymbol(name)                      → chunk[]   (exact, case-insensitive)
+ *   findCallers(funcName)                    → chunk[]
+ *   findReferers(symbol)                     → chunk[]   (type_refs / extends matches)
+ *   findRoutes({method, pathPrefix})         → route[]   (HTTP route → handler chunk)
+ *   iterateChunks()                          → Iterable<chunk>  (cursor on SQLite)
+ *   getDependencies(path) / getImportedBy(path) → string[]
+ *   chunkCount() / fileCount() / symbolCount() / vectorCount() → number
+ *   stats()                                  → engine health facts
+ *   close()                                  Release fds / db handles.
+ */
+import fs from 'fs';
+import { MemoryGraphIndex } from './engine/memory.mjs';
+
+// 'auto' storage keeps the index in memory until a repo is large enough that the
+// disk-backed SQLite store earns its slightly higher per-query latency. The indexer
+// decides by the real chunk count it just built; readers decide by which artifact
+// exists on disk (see resolveBackend).
+export const AUTO_SQLITE_CHUNK_THRESHOLD = 15000;
+
+/**
+ * Resolve the abstract storage setting ('auto'|'memory'|'sqlite') to a concrete
+ * read backend. Explicit settings win; 'auto' picks SQLite when a SQLite artifact
+ * is present (the indexer writes one only for large repos and removes the other
+ * backend's artifact, so presence is unambiguous), else the in-memory JSON index.
+ *
+ * @param {object} config  Resolved config from config.mjs.
+ * @returns {'memory'|'sqlite'}
+ */
+export function resolveBackend(config) {
+    if (config.storage === 'sqlite') return 'sqlite';
+    if (config.storage === 'memory') return 'memory';
+    try { if (fs.existsSync(config.sqlitePath)) return 'sqlite'; } catch { /* fall through to memory */ }
+    return 'memory';
+}
+
+/**
+ * Construct (but do not yet load) the configured store.
+ *
+ * @param {object}  config                 Resolved config from config.mjs.
+ * @param {object}  [opts]
+ * @param {boolean} [opts.cacheEmbeddings] Eager vector cache (in-memory backend only).
+ * @returns {Promise<object>} a store implementing the contract above.
+ */
+export async function createStore(config, { cacheEmbeddings = false } = {}) {
+    if (resolveBackend(config) === 'sqlite') {
+        // Imported lazily so the default path never loads node:sqlite.
+        const { SqliteGraphStore } = await import('./engine/sqlite.mjs');
+        return new SqliteGraphStore(config.sqlitePath, { embeddingPath: config.embeddingPath });
+    }
+    return new MemoryGraphIndex(config.indexPath, { cacheEmbeddings });
+}

package/watch-daemon.mjs

@@ -1,7 +1,14 @@
 #!/usr/bin/env node
 /**
  * @file watch-daemon.mjs
- * @description Native FileSystem Watcher Daemon to maintain an in-memory graph index. Utilizes Tree-sitter for AST parsing and local embedding generation.
+ * @description Native FileSystem Watcher Daemon that keeps the configured index
+ *              backend fresh incrementally. Backend-agnostic: file changes are
+ *              parsed once (Tree-sitter), optionally enriched (LLM cache-first)
+ *              and embedded (Ollama), then handed to the store's applyFileUpdate
+ *              — the in-memory engine persists a debounced JSON snapshot, the
+ *              SQLite store commits a per-file WAL transaction that running MCP
+ *              servers pick up live via PRAGMA data_version. No more "SQLite
+ *              requires a full re-index on every change".
  * @author MaquinaTech <https://github.com/MaquinaTech>
  * @copyright (c) 2026 MaquinaTech. All rights reserved.
  * @license MIT
@@ -19,36 +26,158 @@
 import fs from 'fs';
 import path from 'path';
 import chokidar from 'chokidar';
-import { MemoryGraphIndex } from './core-engine.mjs';
+import { resolveConfig } from './config.mjs';
+import { ensureDataDir, migrateLegacyLayout } from './layout.mjs';
+import { acquireLock, releaseLock, readPid } from './daemon-lock.mjs';
+import { createStore, resolveBackend } from './storage.mjs';
 import {
-    MAX_FILE_SIZE_BYTES, EXTENSIONS, getParserForFile, buildIgnoreFilter,
-    extractImportsFromAST, extractSemanticChunks, resolveLocalImports, getLocalEmbeddingsBatch,
-    buildEmbeddingPayload
-} from './parser-utils.mjs';
+    embeddingKeyFor, computePageRank, TEST_FILE_RE, EXAMPLE_DIR_RE,
+    summaryEmbeddingText, SUMMARY_VEC_SUFFIX, WINDOW_VEC_SUFFIX, embeddingWindows,
+} from './search-core.mjs';
+import { MAX_FILE_SIZE_BYTES, buildIgnoreFilter, extractImportsFromAST, extractSemanticChunks } from './parse/extractor.mjs';
+import { getParserForFile } from './parse/languages.mjs';
+import { resolveLocalImports, buildEmbeddingPayload, fullBodyForEmbedding } from './parse/imports.mjs';
+import { createEmbedder, readEmbedMeta } from './embeddings.mjs';
+import {
+    loadEnrichmentCache, saveEnrichmentCache, attachEnrichment,
+    ollamaGenerate, parseEnrichResponse, buildEnrichPrompt, resolveEnrichModel,
+} from './enrichment.mjs';
+
+const config = resolveConfig();
+const PROJECT_ROOT = config.projectRoot;
 
-const PROJECT_ROOT = process.env.MCP_PROJECT_ROOT || process.cwd();
-const INDEX_PATH = path.join(PROJECT_ROOT, 'code-index.json');
+// Embed incremental updates with the SAME provider/model the index was built with
+// (stamped in the embeddings-bin sidecar), so live vectors match the bootstrap
+// ones. Built lazily and cached for the daemon's lifetime.
+let _embedder = null;
+async function getEmbedder() {
+    if (_embedder) return _embedder;
+    const m = readEmbedMeta(config.embeddingPath);
+    _embedder = await createEmbedder(config, m?.provider
+        ? { provider: m.provider, model: m.model }
+        : { provider: config.embeddingsEnabled ? 'ollama' : 'off', model: config.embedModel });
+    return _embedder;
+}
+
+// ─── Single-instance guard ──────────────────────────────────────────────────────
+// Exactly one daemon may run per project. Acquire the PID lock BEFORE doing any
+// work (loading the store, opening the db) so a redundant launch — via the MCP
+// server, `idx-daemon start`, or a stray `idx-watch` — exits immediately instead
+// of racing a second watcher onto the same index.
+ensureDataDir(PROJECT_ROOT);
+migrateLegacyLayout(PROJECT_ROOT);
+if (!acquireLock(config.pidFile)) {
+    process.stderr.write(
+        `✋ A graph-indexer daemon is already running for this project `
+        + `(PID ${readPid(config.pidFile)}). Exiting — only one runs per project.\n`
+    );
+    process.exit(0);
+}
 
 const ignoreFilter = buildIgnoreFilter(PROJECT_ROOT);
-const db = new MemoryGraphIndex(INDEX_PATH);
+const db = await createStore(config, { cacheEmbeddings: true });
 db.load();
 
+// ─── Enrichment (cache-first, live for core files) ──────────────────────────────
+// Cached entries re-attach for free on every change. When enrichment is enabled
+// and the changed file sits in the PageRank core, new/changed chunks are enriched
+// live (best-effort, low concurrency) so edits don't silently lose their semantic
+// metadata until the next full index run.
+const enrichCache = config.enrichment.enabled
+    ? loadEnrichmentCache(config.enrichmentCachePath)
+    : null;
+let enrichCacheDirty = false;
+let saveCacheTimer = null;
+function scheduleEnrichCacheSave() {
+    if (!enrichCacheDirty) return;
+    if (saveCacheTimer) clearTimeout(saveCacheTimer);
+    saveCacheTimer = setTimeout(() => {
+        saveCacheTimer = null;
+        try { saveEnrichmentCache(config.enrichmentCachePath, enrichCache); enrichCacheDirty = false; }
+        catch (err) { process.stderr.write(`[daemon] ⚠️ enrichment cache save failed: ${err.message}\n`); }
+    }, 3000);
+}
+
+// "auto" resolves to the strongest available local code model, same policy as the bootstrap indexer.
+let _enrichModel = null;
+async function getEnrichModel() {
+    if (_enrichModel) return _enrichModel;
+    _enrichModel = await resolveEnrichModel(config.enrichment.model, config.ollamaHost);
+    return _enrichModel;
+}
+
+let _coreFiles = null;
+function isEnrichableFile(filename) {
+    if (TEST_FILE_RE.test(filename) || EXAMPLE_DIR_RE.test(filename)) return false;
+    if (config.enrichment.coreRatio >= 1) return true; // all production files
+    if (!_coreFiles) {
+        const pr = computePageRank(db.graph);
+        const files = Array.from(pr.keys()).sort((a, b) => (pr.get(b) ?? 0) - (pr.get(a) ?? 0));
+        const coreCount = Math.max(1, Math.ceil(files.length * config.enrichment.coreRatio));
+        _coreFiles = new Set(files.slice(0, coreCount));
+    }
+    return _coreFiles.has(filename);
+}
+
+async function enrichChunks(filename, chunks) {
+    if (!enrichCache) return;
+    const pending = [];
+    for (const chunk of chunks) {
+        if (!chunk.content_hash) continue;
+        if (attachEnrichment(chunk, enrichCache.get(chunk.content_hash))) continue;
+        pending.push(chunk);
+    }
+    if (pending.length === 0 || !isEnrichableFile(filename)) return;
+    // Live enrichment of changed core chunks: sequential and best-effort — a file
+    // save touches a handful of chunks, so latency stays low and failures only
+    // mean "no enrichment until the next full index run".
+    const model = await getEnrichModel();
+    for (const chunk of pending) {
+        if ((chunk.end_line - chunk.start_line) < 4) continue; // trivial stubs
+        const raw = await ollamaGenerate(buildEnrichPrompt(chunk), {
+            model, ollamaHost: config.ollamaHost, timeoutMs: 20000,
+        });
+        const parsed = parseEnrichResponse(raw);
+        if (!parsed) break; // model unreachable — stop trying for this batch
+        chunk.summary  = parsed.summary;
+        chunk.concepts = parsed.concepts;
+        chunk.hyde     = parsed.hyde;
+        enrichCache.set(chunk.content_hash, {
+            summary: parsed.summary, concepts: parsed.concepts, model,
+        });
+        enrichCacheDirty = true;
+    }
+    scheduleEnrichCacheSave();
+}
+
+// ─── Incremental file sync ──────────────────────────────────────────────────────
+
+// Catch-up scan: chokidar fires 'add' for every existing file at startup. Files
+// not modified since the index artifact was last written are already indexed —
+// skipping them turns daemon start from O(repo) parse work into O(changed files),
+// while still picking up edits made while the daemon was down.
+const BACKEND = resolveBackend(config); // 'auto' → concrete backend by artifact presence.
+const ARTIFACT_PATH = BACKEND === 'sqlite' ? config.sqlitePath : config.indexPath;
+let indexBuiltAt = 0;
+try { indexBuiltAt = fs.statSync(ARTIFACT_PATH).mtimeMs; } catch { /* no index yet → full scan */ }
+let initialScan = true;
+
 async function processFileChange(absolutePath) {
     const filename = path.relative(PROJECT_ROOT, absolutePath).replace(/\\/g, '/');
     if (ignoreFilter.ignores(filename)) return;
     if (filename.includes('.bundle.') || filename.includes('.min.')) return;
+    if (filename.startsWith('code-index.')) return; // never index our own artifacts
 
     try {
+        if (initialScan && indexBuiltAt > 0 && fs.existsSync(absolutePath)
+            && fs.statSync(absolutePath).mtimeMs <= indexBuiltAt) {
+            return; // unchanged since the last index write
+        }
+
         if (!fs.existsSync(absolutePath)) {
-            for (const [id, chunk] of db.chunks.entries()) {
-                if (chunk.file_path === filename) {
-                    db._removeLexical(id);
-                    db.chunks.delete(id);
-                    db.removeVector(id);
-                }
-            }
-            db.updateFileGraph(filename, []);
-            db.saveDebounced();
+            if (typeof db.removeFile === 'function') db.removeFile(filename);
+            else db.applyFileUpdate(filename, { chunks: [], imports: [] });
+            _coreFiles = null;
             process.stderr.write(`[daemon] 🗑️  Purged: ${filename}\n`);
             return;
         }
@@ -56,7 +185,7 @@ async function processFileChange(absolutePath) {
         const stats = fs.statSync(absolutePath);
         if (stats.size > MAX_FILE_SIZE_BYTES) return;
 
-        let content = fs.readFileSync(absolutePath, 'utf-8');
+        const content = fs.readFileSync(absolutePath, 'utf-8');
         if (!content.trim()) return;
 
         const ext = path.extname(absolutePath);
@@ -65,67 +194,57 @@ async function processFileChange(absolutePath) {
 
         const tree = parser.parse((offset) => offset < content.length ? content.slice(offset, offset + 4096) : null);
         const imports = resolveLocalImports(extractImportsFromAST(tree.rootNode, ext), filename, PROJECT_ROOT);
-        db.updateFileGraph(filename, imports);
-
         const newChunks = extractSemanticChunks(tree.rootNode, filename, content, ext);
+        _coreFiles = null; // dependency graph may change → PageRank core set is stale
 
-        for (const [id, chunk] of db.chunks.entries()) {
-            if (chunk.file_path === filename) {
-                db._removeLexical(id);
-                db.chunks.delete(id);
-                db.removeVector(id); // invalidates flat matrix so next search rebuilds it
-            }
-        }
-
-        const chunksToEmbed = newChunks.filter(c => !db.embeddingCache.has(c.content_hash));
+        // Enrichment BEFORE embedding: summary rides the vector payload and
+        // embeddingKeyFor accounts for it, so cache lookups stay correct.
+        await enrichChunks(filename, newChunks);
 
+        // Identical embedding payloads to indexer.mjs (shared helpers) so incremental
+        // updates match the bootstrap index, including summary-only vectors for enriched chunks.
+        const chunksToEmbed = newChunks.filter(c => !db.hasEmbedding(embeddingKeyFor(c)));
+        const embeddings = new Map();
         if (chunksToEmbed.length > 0) {
-            // 🥇 STRICT PAYLOAD PARITY: identical embedding payload to indexer.mjs
-            // (shared helper) so incremental updates match the bootstrap index.
-            const textsToEmbed = chunksToEmbed.map(c =>
-                buildEmbeddingPayload(c, db.graph.dependencies[c.file_path] || [])
-            );
-
-            const embeddingsMatrix = await getLocalEmbeddingsBatch(textsToEmbed, true);
-            if (embeddingsMatrix) {
-                chunksToEmbed.forEach((chunk, j) => {
-                    if (embeddingsMatrix[j]) {
-                        db.embeddingCache.set(chunk.content_hash, new Float32Array(embeddingsMatrix[j]));
-                    }
-                });
+            const entries = [];
+            for (const c of chunksToEmbed) {
+                const baseKey = embeddingKeyFor(c);
+                // Oversized definitions embed their full body (windowed) while the lexical path
+                // keeps the 3000-char snippet — parity with how indexer.mjs builds payloads.
+                const payload = buildEmbeddingPayload(c, imports, fullBodyForEmbedding(c, content));
+                entries.push({ key: baseKey, text: payload });
+                const windows = embeddingWindows(payload); // tail windows for oversized chunks
+                for (let i = 1; i < windows.length; i++) entries.push({ key: baseKey + WINDOW_VEC_SUFFIX + i, text: windows[i] });
+                const sText = summaryEmbeddingText(c);
+                if (sText) entries.push({ key: baseKey + SUMMARY_VEC_SUFFIX, text: sText });
             }
-        }
-
-        for (const chunk of newChunks) {
-            if (db.embeddingCache.has(chunk.content_hash)) {
-                db.addVector(chunk.id, db.embeddingCache.get(chunk.content_hash));
+            const embedder = await getEmbedder();
+            const embeddingsMatrix = await embedder.embedDocuments(entries.map(e => e.text));
+            if (embeddingsMatrix && embeddingsMatrix.length === entries.length) {
+                entries.forEach((entry, j) => {
+                    if (embeddingsMatrix[j]) embeddings.set(entry.key, new Float32Array(embeddingsMatrix[j]));
+                });
             }
-
-            // Unified lexical re-indexing of neighborhood
-            const cleanDeps = imports.map(d => d.split('/').pop().split('.')[0]);
-            const enrichedContext = [
-                chunk.name,
-                chunk.docstring || '',
-                cleanDeps.join(' '),
-                (chunk.calls || []).join(' '),
-                (chunk.params || []).join(' '),
-                chunk.return_type || '',
-                chunk.class_context ? `${chunk.class_context}.${chunk.name}` : '',
-                chunk.code_snippet
-            ].join(' ');
-
-            db._indexLexical(chunk.id, enrichedContext, chunk.file_path);
-            db.chunks.set(chunk.id, chunk);
         }
 
-        db.saveDebounced();
-        process.stderr.write(`[daemon] 🔄 Synced: ${filename} (Cache Hit: ${newChunks.length - chunksToEmbed.length}/${newChunks.length})\n`);
+        db.applyFileUpdate(filename, { chunks: newChunks, imports, embeddings });
+        process.stderr.write(
+            `[daemon] 🔄 Synced: ${filename} (${newChunks.length} chunks, `
+            + `${newChunks.length - chunksToEmbed.length} cached vectors, ${BACKEND})\n`
+        );
     } catch (err) {
         process.stderr.write(`[daemon] ❌ Error in ${filename}: ${err.message}\n`);
     }
 }
 
-process.stderr.write(`🚀 Chokidar Watcher Daemon started in: ${PROJECT_ROOT}\n`);
+// Serialize updates: chokidar can fire bursts (git checkout, format-on-save across
+// files); per-file work must not interleave inside the store.
+let queue = Promise.resolve();
+function enqueue(absolutePath) {
+    queue = queue.then(() => processFileChange(absolutePath)).catch(() => {});
+}
+
+process.stderr.write(`🚀 Watcher Daemon started in: ${PROJECT_ROOT} (backend: ${BACKEND})\n`);
 
 // Only watch source files we can actually index. Critically, this prevents
 // chokidar from descending into node_modules / dist / .git / .gitignored dirs —
@@ -136,6 +255,7 @@ function shouldIgnore(absPath) {
     const rel = path.relative(PROJECT_ROOT, absPath).replace(/\\/g, '/');
     if (!rel) return false;                       // the project root itself
     if (path.basename(absPath).startsWith('.')) return true; // dotfiles / dot-dirs
+    if (rel.startsWith('code-index.')) return true;          // our own artifacts (.db/-wal/.bin/.json)
     try { return ignoreFilter.ignores(rel); }     // node_modules, dist, .gitignore, …
     catch { return false; }
 }
@@ -145,5 +265,20 @@ const watcher = chokidar.watch(PROJECT_ROOT, {
     persistent: true,
     awaitWriteFinish: { stabilityThreshold: 300, pollInterval: 100 }
 });
-watcher.on('add', processFileChange).on('change', processFileChange).on('unlink', (p) => processFileChange(p));
-watcher.on('error', (err) => process.stderr.write(`[daemon] 💥 OS Watcher panic: ${err.message}\n`));
+watcher.on('add', enqueue).on('change', enqueue).on('unlink', enqueue);
+watcher.on('ready', () => { queue = queue.then(() => { initialScan = false; }); });
+watcher.on('error', (err) => process.stderr.write(`[daemon] 💥 OS Watcher panic: ${err.message}\n`));
+
+function shutdown() {
+    watcher.close().catch(() => {});
+    if (enrichCache && enrichCacheDirty) {
+        try { saveEnrichmentCache(config.enrichmentCachePath, enrichCache); } catch { /* best effort */ }
+    }
+    if (typeof db.close === 'function') db.close();
+    process.exit(0);
+}
+process.on('SIGTERM', shutdown);
+process.on('SIGINT', shutdown);
+// Always relinquish the single-instance lock on the way out (covers shutdown(),
+// uncaught exits and normal termination) so the next launch can take over cleanly.
+process.on('exit', () => releaseLock(config.pidFile));

package/PROMPT.md

@@ -1,143 +0,0 @@
-<agent_instructions name="graph-indexer-system-prompt">
-  <context>
-    You have access to a graph-indexer MCP server that has pre-indexed this entire codebase into a searchable AST graph. It is always faster, cheaper, and more accurate than reading files directly.
-  </context>
-
-  <absolute_rules>
-    <rule id="1" name="Search before you read">NEVER use readFile, listDir, grep, find, or any native file tool as your first step. Every code discovery task starts with a graph-indexer tool. Violating this wastes 10-100x more tokens and is strictly forbidden.</rule>
-    <rule id="2" name="Never read a full file to find one function">If you know a chunk ID from search results, call get_chunk(id) directly. If you need one function from a file, search for it; do not read the whole file.</rule>
-    <rule id="3" name="Never modify an exported function without checking its callers">Before changing any function or class signature, call get_call_graph(functionName) to find all callers repo-wide. This takes 1 tool call. Skipping it risks breaking code you cannot see.</rule>
-    <rule id="4" name="Use resolve_symbol for exact names, not search">If you know the exact function or class name (e.g., validateToken, UserService), call resolve_symbol(validateToken). It is O(1) and returns the definition instantly. Do not use search_code for names you already know.</rule>
-  </absolute_rules>
-
-  <decision_tree>
-    <task name="Unfamiliar codebase, need overview" tool="get_repo_map()" />
-    <task name="Focus on a subsystem" tool="get_repo_map(path_filter='auth')" />
-    <task name="Know exact symbol name" tool="resolve_symbol('ExactName')" />
-    <task name="Find concept or behavior" tool="search_code(query, detail='signatures')" />
-    <task name="Need interface only (no body)" tool="get_chunk_summary(chunk_id)" />
-    <task name="Need full implementation" tool="get_chunk(chunk_id)" />
-    <task name="See all exports in one file" tool="get_file_skeleton('src/file.ts')" />
-    <task name="Find who calls a function" tool="get_call_graph('functionName')" />
-    <task name="Check index health or search mode" tool="list_index_stats()" />
-    <task name="Browse file dependencies" tool="resource graph://dependencies/{file_path}" />
-  </decision_tree>
-
-  <token_management>
-    <costs>
-      <action tool="get_repo_map()" tokens="1500" context="Orienting in an unknown codebase" />
-      <action tool="resolve_symbol('Name')" tokens="50" context="You know the exact name" />
-      <action tool="search_code(detail='signatures', top_k=5)" tokens="100" context="Finding candidates to inspect" />
-      <action tool="get_chunk_summary(id)" tokens="50" context="You need the interface, not the body" />
-      <action tool="search_code(detail='smart', top_k=5)" tokens="750" context="You need to understand the logic" />
-      <action tool="get_chunk(id)" tokens="300" context="You need the complete implementation" />
-      <action tool="get_file_skeleton('file.ts')" tokens="80" context="You need all exports in one file" />
-      <action tool="search_code(detail='full', top_k=5)" tokens="1500" context="Rarely; full bodies for all results" />
-      <action tool="Direct file read" tokens="5000" context="Never - use the tools above" />
-    </costs>
-    <escalation_ladder>
-      <step level="1" tool="search_code(detail='signatures')">Start here: names and types only</step>
-      <step level="2" tool="get_chunk_summary(id)">Escalate: add docstring and calls</step>
-      <step level="3" tool="search_code(detail='smart')">Escalate: add query-relevant snippets</step>
-      <step level="4" tool="get_chunk(id)">Last resort: full body when you must</step>
-    </escalation_ladder>
-  </token_management>
-
-  <workflows>
-    <workflow name="Orienting in a new codebase">
-      <step>get_repo_map() -> files sorted by importance (PageRank)</step>
-      <step>identify key files, pick relevant ones</step>
-      <step>resolve_symbol or search_code to drill in</step>
-    </workflow>
-    <workflow name="Finding where a concept is implemented">
-      <step>search_code(query='semantic description', detail='signatures', top_k=5) -> read signature cards and topology</step>
-      <step>if a result looks right: get_chunk_summary(id) to check interface</step>
-      <step>if confirmed: get_chunk(id) for the full body</step>
-    </workflow>
-    <workflow name="Looking up a specific function or class">
-      <step>resolve_symbol('ExactName') -> definition, type signature, cross-file topology</step>
-      <step>get_chunk(id) if you need the body</step>
-    </workflow>
-    <workflow name="Understanding a file structure">
-      <step>get_file_skeleton('src/module.ts') -> all exported symbols with line numbers (no bodies)</step>
-      <step>resolve_symbol or get_chunk for specific items</step>
-    </workflow>
-    <workflow name="Safe refactoring">
-      <step>get_call_graph('targetFunction') -> all callers repo-wide</step>
-      <step>review impact before changing signature</step>
-      <step>get_chunk for each caller if you need to update call sites</step>
-    </workflow>
-  </workflows>
-
-  <query_guidelines>
-    <description>search_code uses BM25 hybrid search. Query quality determines result quality.</description>
-    <examples type="good">
-      <example>JWT token validation and expiry check middleware</example>
-      <example>HTTP adapter XMLHttpRequest browser send request</example>
-      <example>dependency injection container resolve provider</example>
-      <example>route registration path method handler</example>
-    </examples>
-    <examples type="bad">
-      <example reason="matches everything with the word auth">auth</example>
-      <example reason="thousands of results, meaningless ranking">request</example>
-      <example reason="too broad">handler</example>
-    </examples>
-    <rules>
-      <rule>Describe the behavior, not just the noun: 'parse and validate request body schema' not 'validation'</rule>
-      <rule>Include language context: 'TypeScript interface generic constraint' not 'interface'</rule>
-      <rule>If you know the name, use exact_tokens: search_code(query='token validation', exact_tokens='validateToken')</rule>
-      <rule>For files: include path segments in query: 'middleware auth route' will boost auth/middleware.ts</rule>
-    </rules>
-  </query_guidelines>
-
-  <detail_parameter tool="search_code">
-    <option value="signatures" tokens="20">Name, type, params, return, topology (no body). Use for first pass finding candidates.</option>
-    <option value="smart" default="true" tokens="150">Signature + query-matching lines only, boilerplate removed. Use for understanding logic without full body.</option>
-    <option value="full" tokens="300">Complete source body. Use when you must see the full implementation.</option>
-    <instruction>Always start with signatures, escalate only when you need more.</instruction>
-  </detail_parameter>
-
-  <anti_patterns>
-    <anti_pattern action="readFile('src/auth/jwt.ts')">WRONG: Reading files to discover code. Never use as a first step.</anti_pattern>
-    <anti_pattern action="search_code('validateToken')">WRONG: Searching for what you already have. You already have the chunk ID from search results.</anti_pattern>
-    <anti_pattern action="search_code(query='...', detail='full')">WRONG: Using full detail by default. Only use when you need all bodies.</anti_pattern>
-    <anti_pattern action="Edit function -> push -> find 12 other files break">WRONG: Modifying exported functions without impact check. Correct: get_call_graph('functionName') first.</anti_pattern>
-    <anti_pattern action="search_code(query='error')">WRONG: Generic one-word queries. Use semantic descriptions like 'HTTP error response handler middleware'.</anti_pattern>
-    <anti_pattern action="Ignoring topology in search results">WRONG: If results show 'Used by: auth.ts, routes.ts', read that, do not re-search.</anti_pattern>
-    <anti_pattern action="Re-searching for the same concept">WRONG: search_code returns chunk ID -> call get_chunk(id), not another search_code.</anti_pattern>
-  </anti_patterns>
-
-  <topology_info>
-    <description>Every search_code and resolve_symbol result includes topology for free. Use this topology to navigate without additional tool calls.</description>
-    <fields>
-      <field name="Deps">What this file imports (and which symbols it uses from each)</field>
-      <field name="Used by">Which other files import this file</field>
-      <field name="Calls">Functions this chunk calls directly</field>
-    </fields>
-  </topology_info>
-
-  <index_health>
-    <troubleshooting>
-      <step>Call list_index_stats() to check chunk count, vector status, daemon status, index age.</step>
-      <step>If index age > 1h with no activity, ask the user to run npm run mcp:index.</step>
-      <step>If a symbol is missing from resolve_symbol, fall back to search_code.</step>
-    </troubleshooting>
-    <search_modes>
-      <mode name="Hybrid">semantic + lexical RRF, full quality, Ollama running</mode>
-      <mode name="Lexical only">BM25 only, Ollama unavailable; still high quality (R@5=1.00)</mode>
-    </search_modes>
-  </index_health>
-
-  <quick_reference>
-    <command name="get_repo_map()" returns="full codebase overview (~1500 tok)" />
-    <command name="get_repo_map(path_filter='auth')" returns="subsystem overview (~300 tok)" />
-    <command name="resolve_symbol('ExactName')" returns="instant definition + topology" />
-    <command name="search_code('concept', 'signatures')" returns="find candidates (~100 tok)" />
-    <command name="get_chunk_summary(id)" returns="interface view (~50 tok)" />
-    <command name="get_chunk(id)" returns="full body (~300 tok)" />
-    <command name="get_file_skeleton('path/file.ts')" returns="all exports in file (~80 tok)" />
-    <command name="get_call_graph('name')" returns="all callers, pre-refactor check" />
-    <command name="list_index_stats()" returns="index health" />
-    <command name="graph://dependencies/{file_path}" returns="bidirectional dep graph" />
-  </quick_reference>
-</agent_instructions>