graph-indexer 1.2.0 → 2.1.0

package/search-sparse.mjs

@@ -0,0 +1,183 @@
+/**
+ * @file search-sparse.mjs
+ * @description B3 — opt-in LEARNED-SPARSE vocabulary-expansion channel. A learned-sparse retriever
+ *              (SPLADE / uniCOIL family) expands a query into a WEIGHTED term set — original terms
+ *              plus learned associates — and fuses that as an extra sparse channel, closing
+ *              lexical-gap misses the Porter-stemming bridge structurally cannot (stemming only
+ *              normalises morphology; it cannot connect "auth" → "credential"/"token").
+ *
+ *              THE AIR-GAPPED, ZERO-DEPENDENCY REALISATION: rather than require a neural MLM
+ *              (which needs a downloaded model + @huggingface/transformers and cannot be measured
+ *              air-gapped), the SHIPPED provider LEARNS the term associations FROM THE CORPUS at
+ *              index time via positive pointwise mutual information (PMI) over chunk co-occurrence.
+ *              It is genuine learned-sparse — learned per-term weights + vocabulary expansion — with
+ *              ZERO new dependency, fully deterministic, and measurable on the honest `test:eval`.
+ *              A neural SPLADE provider is a clean future drop-in behind the same `expandSparseQuery`
+ *              seam (see docs/internals/IMPROVEMENT_LEARNED_SPARSE.md).
+ *
+ *              SOUNDNESS / SACRED DEFAULT: the model is built ONLY with --learned-sparse and
+ *              serialized as an ISOLATED index artifact (like centrality/taint/scip_refs), so it
+ *              cannot perturb the lexical postings or the default path. The channel is
+ *              NL-ASYMMETRIC — it fires only for natural-language queries with a real expansion —
+ *              so symbolic/exact lookups stay byte-identical. Scoring is delegated to a SHARED
+ *              core (search-core.scoreSparseExpanded) that both backends call through their own
+ *              postings accessors → parity by construction.
+ * @author MaquinaTech <https://github.com/MaquinaTech>
+ * @copyright (c) 2026 MaquinaTech. All rights reserved.
+ * @license MIT
+ */
+import { tokenize } from './search-core.mjs';
+
+// ── Model-build knobs (structural, not tuned to any query) ──────────────────────────────────
+const MIN_TOKEN_LEN = 3;          // ignore 1-2 char noise
+const MAX_TOKENS_PER_CHUNK = 40;  // cap co-occurrence fan-out per chunk (most-discriminative first)
+const MIN_DF = 2;                 // a term must occur in ≥2 chunks to carry association signal
+const MAX_DF_RATIO = 0.30;        // skip ultra-common terms (in >30% of chunks → no discriminative value)
+const MIN_COOC = 2;               // a pair must co-occur in ≥2 chunks (kills incidental pairs)
+const TOPK_ASSOC = 8;             // keep the strongest K associates per term
+const PMI_NORM = 6;               // PMI (log2) normaliser → stored weight = clamp(pmi/6, 0..1)
+
+// ── Query-expansion knobs ───────────────────────────────────────────────────────────────────
+const EXPANSION_SCALE = 0.35;     // an associate term contributes ≤0.35× a real query term
+const MAX_QUERY_EXPANSIONS = 12;  // total associate terms added across the whole query
+const MIN_EXPANSION_WEIGHT = 0.05;// drop near-zero associates (no point fusing them)
+
+/** Distinct, length-filtered RAW tokens of a text (no stems — associations are surface-form). */
+function distinctTokens(text) {
+    const out = new Set();
+    for (const t of tokenize(text, false)) if (t.length >= MIN_TOKEN_LEN) out.add(t);
+    return out;
+}
+
+/**
+ * Learn the sparse association model from the corpus. Two passes:
+ *   1. document frequency per token (over distinct per-chunk tokens);
+ *   2. co-occurrence counts over each chunk's top-MAX_TOKENS_PER_CHUNK most-discriminative tokens
+ *      (rarest first by df), then positive PMI per pair, keeping the top-K associates per term.
+ *
+ * Deterministic: every map is materialised through SORTED keys, and stored weights are rounded, so
+ * the serialized model is byte-identical run to run and the two backends read identical bytes.
+ *
+ * @param {Iterable<{code_snippet?:string,name?:string,docstring?:string}>} chunks  the index chunks
+ * @param {object} [opts]
+ * @returns {{ assoc: Record<string, Array<[string, number]>>, meta: object } | null}  null if no signal
+ */
+export function buildSparseModel(chunks, opts = {}) {
+    const minDf = opts.minDf ?? MIN_DF;
+    const maxDfRatio = opts.maxDfRatio ?? MAX_DF_RATIO;
+    const topK = opts.topKAssoc ?? TOPK_ASSOC;
+
+    // The text a chunk contributes its vocabulary from — name + docstring + the snippet.
+    const chunkText = (c) => `${c.name || ''} ${c.docstring || ''} ${c.summary || ''} ${c.code_snippet || ''}`;
+
+    // Pass 1: per-chunk distinct tokens + document frequency.
+    const perChunk = [];
+    const df = new Map();
+    for (const c of chunks) {
+        const toks = distinctTokens(chunkText(c));
+        if (toks.size < 2) { perChunk.push(null); continue; }
+        perChunk.push(toks);
+        for (const t of toks) df.set(t, (df.get(t) || 0) + 1);
+    }
+    const docCount = perChunk.length;
+    if (!docCount) return null;
+    const maxDf = Math.max(minDf, Math.floor(maxDfRatio * docCount));
+
+    // A token carries association signal only inside the df band [minDf, maxDf].
+    const eligible = (t) => { const d = df.get(t) || 0; return d >= minDf && d <= maxDf; };
+
+    // Pass 2: co-occurrence over each chunk's most-discriminative (rarest) eligible tokens.
+    const cooc = new Map();  // term → Map<term, count>
+    const bump = (a, b) => {
+        let m = cooc.get(a); if (!m) { m = new Map(); cooc.set(a, m); }
+        m.set(b, (m.get(b) || 0) + 1);
+    };
+    for (const toks of perChunk) {
+        if (!toks) continue;
+        const elig = [...toks].filter(eligible);
+        if (elig.length < 2) continue;
+        // rarest-first (df asc, then lexical) → cap fan-out deterministically
+        elig.sort((a, b) => (df.get(a) - df.get(b)) || (a < b ? -1 : a > b ? 1 : 0));
+        const top = elig.slice(0, MAX_TOKENS_PER_CHUNK);
+        for (let i = 0; i < top.length; i++) {
+            for (let j = i + 1; j < top.length; j++) {
+                bump(top[i], top[j]); bump(top[j], top[i]);   // symmetric
+            }
+        }
+    }
+
+    // Positive PMI per pair → top-K associates per term, weight = clamp(pmi / PMI_NORM, 0..1).
+    const log2 = (x) => Math.log(x) / Math.LN2;
+    const assoc = {};
+    let pairs = 0;
+    for (const term of [...cooc.keys()].sort()) {
+        const dfa = df.get(term);
+        const row = [];
+        for (const [other, c] of cooc.get(term)) {
+            if (c < MIN_COOC) continue;
+            const dfb = df.get(other);
+            // PMI = log2( P(a,b) / (P(a) P(b)) ) = log2( c·N / (dfa·dfb) )
+            const pmi = log2((c * docCount) / (dfa * dfb));
+            if (pmi <= 0) continue;
+            const w = Math.min(1, pmi / PMI_NORM);
+            if (w < MIN_EXPANSION_WEIGHT) continue;
+            row.push([other, Number(w.toFixed(4))]);
+        }
+        if (!row.length) continue;
+        // strongest first; lexical tie-break for determinism; keep top-K
+        row.sort((a, b) => (b[1] - a[1]) || (a[0] < b[0] ? -1 : 1));
+        assoc[term] = row.slice(0, topK);
+        pairs += assoc[term].length;
+    }
+    if (!pairs) return null;
+
+    return {
+        assoc,
+        meta: { terms: Object.keys(assoc).length, pairs, docs: docCount, metric: 'pmi', version: 1 },
+    };
+}
+
+/**
+ * Expand a natural-language query into a WEIGHTED term set for the sparse channel: the learned
+ * ASSOCIATE terms only (the original query terms already drive the lexical channel, so the sparse
+ * channel is a pure vocabulary-EXPANSION view — it surfaces chunks that match the semantically
+ * associated vocabulary the literal query never mentions). Deterministic insertion order (query-token
+ * order, then per-token associate order) so both backends accumulate scores identically.
+ *
+ * Returns null when nothing fires (no model, no eligible token, no association) — the caller then
+ * runs ZERO sparse channel and the result is byte-identical to the default path.
+ *
+ * @param {string} queryText
+ * @param {{assoc:Record<string,Array<[string,number]>>}} model
+ * @param {object} [opts]
+ * @returns {Map<string, number> | null}  associate term → fusion weight, or null
+ */
+export function expandSparseQuery(queryText, model, opts = {}) {
+    if (!model || !model.assoc) return null;
+    const scale = opts.scale ?? EXPANSION_SCALE;
+    const maxExp = opts.maxExpansions ?? MAX_QUERY_EXPANSIONS;
+    const assoc = model.assoc;
+
+    const qTokens = [...distinctTokens(queryText)];           // raw surface forms, query order via Set
+    const weights = new Map();                                // associate term → best weight seen
+    for (const qt of qTokens) {
+        const row = assoc[qt];
+        if (!row) continue;
+        for (const [term, w] of row) {
+            if (qTokens.includes(term)) continue;             // don't re-add a literal query term
+            const ew = scale * w;
+            if (ew < MIN_EXPANSION_WEIGHT) continue;
+            const prev = weights.get(term);
+            if (prev === undefined || ew > prev) weights.set(term, ew);
+        }
+    }
+    if (!weights.size) return null;
+
+    // Keep the strongest MAX_QUERY_EXPANSIONS, but REBUILD the map in deterministic order
+    // (weight desc, then term asc) so both backends iterate — and float-accumulate — identically.
+    const ranked = [...weights.entries()]
+        .sort((a, b) => (b[1] - a[1]) || (a[0] < b[0] ? -1 : 1))
+        .slice(0, maxExp);
+    if (!ranked.length) return null;
+    return new Map(ranked);
+}

package/storage.mjs

@@ -17,13 +17,43 @@
  *   getChunksByFile(path)                    → chunk[]
  *   resolveSymbol(name)                      → chunk[]   (exact, case-insensitive)
  *   findCallers(funcName)                    → chunk[]
+ *   findReferers(symbol)                     → chunk[]   (type_refs / extends matches)
+ *   getEdges(chunkId, {kind?, direction})    → edge[]    (A4 resolved symbol graph; [] when off)
+ *   hasSymbolGraph() / hasCentrality()       → boolean   (opt-in A4 / A5 layers present?)
+ *   getCentrality(chunkId)                   → { score, rank, total } | null   (A5 symbol PageRank)
+ *   topCentral(limit)                        → [{ chunk, score, rank }]         (A5, rank-ascending)
+ *   hasTaint() / getTaintFlows()             → boolean / { flows, meta } | null (C2 serialized taint, --taint)
+ *   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 { MemoryGraphIndex } from './core-engine.mjs';
+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.
@@ -34,9 +64,9 @@ import { MemoryGraphIndex } from './core-engine.mjs';
  * @returns {Promise<object>} a store implementing the contract above.
  */
 export async function createStore(config, { cacheEmbeddings = false } = {}) {
-    if (config.storage === 'sqlite') {
+    if (resolveBackend(config) === 'sqlite') {
         // Imported lazily so the default path never loads node:sqlite.
-        const { SqliteGraphStore } = await import('./sqlite-store.mjs');
+        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

@@ -27,24 +27,53 @@ import fs from 'fs';
 import path from 'path';
 import chokidar from 'chokidar';
 import { resolveConfig } from './config.mjs';
-import { createStore } from './storage.mjs';
+import { ensureDataDir, migrateLegacyLayout } from './layout.mjs';
+import { acquireLock, releaseLock, readPid } from './daemon-lock.mjs';
+import { createStore, resolveBackend } from './storage.mjs';
 import {
     embeddingKeyFor, computePageRank, TEST_FILE_RE, EXAMPLE_DIR_RE,
-    summaryEmbeddingText, SUMMARY_VEC_SUFFIX,
+    summaryEmbeddingText, SUMMARY_VEC_SUFFIX, WINDOW_VEC_SUFFIX, embeddingWindows,
 } from './search-core.mjs';
-import {
-    MAX_FILE_SIZE_BYTES, getParserForFile, buildIgnoreFilter,
-    extractImportsFromAST, extractSemanticChunks, resolveLocalImports, getLocalEmbeddingsBatch,
-    buildEmbeddingPayload,
-} from './parser-utils.mjs';
+import { MAX_FILE_SIZE_BYTES, buildIgnoreFilter, extractImportsFromAST, extractSemanticChunks } from './parse/extractor.mjs';
+import { getParserForFile, ensureLanguagesReady } 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,
+    ollamaGenerate, parseEnrichResponse, buildEnrichPrompt, resolveEnrichModel,
 } from './enrichment.mjs';
 
 const config = resolveConfig();
 const PROJECT_ROOT = config.projectRoot;
 
+// 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 = await createStore(config, { cacheEmbeddings: true });
 db.load();
@@ -69,6 +98,14 @@ function scheduleEnrichCacheSave() {
     }, 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;
@@ -94,10 +131,11 @@ async function enrichChunks(filename, chunks) {
     // 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: config.enrichment.model, ollamaHost: config.ollamaHost, timeoutMs: 20000,
+            model, ollamaHost: config.ollamaHost, timeoutMs: 20000,
         });
         const parsed = parseEnrichResponse(raw);
         if (!parsed) break; // model unreachable — stop trying for this batch
@@ -105,7 +143,7 @@ async function enrichChunks(filename, chunks) {
         chunk.concepts = parsed.concepts;
         chunk.hyde     = parsed.hyde;
         enrichCache.set(chunk.content_hash, {
-            summary: parsed.summary, concepts: parsed.concepts, model: config.enrichment.model,
+            summary: parsed.summary, concepts: parsed.concepts, model,
         });
         enrichCacheDirty = true;
     }
@@ -118,7 +156,8 @@ async function enrichChunks(filename, chunks) {
 // 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 ARTIFACT_PATH = config.storage === 'sqlite' ? config.sqlitePath : config.indexPath;
+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;
@@ -158,25 +197,29 @@ async function processFileChange(absolutePath) {
         const newChunks = extractSemanticChunks(tree.rootNode, filename, content, ext);
         _coreFiles = null; // dependency graph may change → PageRank core set is stale
 
-        // Enrichment BEFORE embedding so the summary rides the vector payload
-        // (embeddingKeyFor accounts for it, so cache lookups stay correct).
+        // Enrichment BEFORE embedding: summary rides the vector payload and
+        // embeddingKeyFor accounts for it, so cache lookups stay correct.
         await enrichChunks(filename, newChunks);
 
-        // 🥇 STRICT PAYLOAD PARITY: identical embedding payloads to indexer.mjs
-        // (shared helpers) so incremental updates match the bootstrap index —
-        // including the summary-only second vector for enriched chunks.
+        // 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) {
             const entries = [];
             for (const c of chunksToEmbed) {
-                entries.push({ key: embeddingKeyFor(c), text: buildEmbeddingPayload(c, imports) });
+                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: embeddingKeyFor(c) + SUMMARY_VEC_SUFFIX, text: sText });
+                if (sText) entries.push({ key: baseKey + SUMMARY_VEC_SUFFIX, text: sText });
             }
-            const embeddingsMatrix = await getLocalEmbeddingsBatch(entries.map(e => e.text), true, {
-                ollamaHost: config.ollamaHost, model: config.embedModel,
-            });
+            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]));
@@ -187,7 +230,7 @@ async function processFileChange(absolutePath) {
         db.applyFileUpdate(filename, { chunks: newChunks, imports, embeddings });
         process.stderr.write(
             `[daemon] 🔄 Synced: ${filename} (${newChunks.length} chunks, `
-            + `${newChunks.length - chunksToEmbed.length} cached vectors, ${config.storage})\n`
+            + `${newChunks.length - chunksToEmbed.length} cached vectors, ${BACKEND})\n`
         );
     } catch (err) {
         process.stderr.write(`[daemon] ❌ Error in ${filename}: ${err.message}\n`);
@@ -196,12 +239,17 @@ async function processFileChange(absolutePath) {
 
 // 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();
+// Seeds the update chain: the daemon inherits its language set from whatever the
+// last `idx-index` run resolved, and won't autoInstall (grammars are provisioned
+// at index time, not silently mid-watch) — a language added after the daemon
+// started is picked up on the next full `idx-index`, same as other whole-program
+// passes (see interprocedural.mjs).
+let queue = ensureLanguagesReady({ projectRoot: PROJECT_ROOT, enabledLangs: config.languages, autoInstall: false, log: (msg) => process.stderr.write(msg + '\n') });
 function enqueue(absolutePath) {
     queue = queue.then(() => processFileChange(absolutePath)).catch(() => {});
 }
 
-process.stderr.write(`🚀 Watcher Daemon started in: ${PROJECT_ROOT} (backend: ${config.storage})\n`);
+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 —
@@ -236,3 +284,6 @@ function shutdown() {
 }
 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,182 +0,0 @@
-# graph-indexer — Agent Instructions
-
----
-
-## Prime directive
-
-This codebase is **pre-indexed**. The `graph-indexer` MCP server answers code
-questions from an AST-precise search index in tens of tokens, with cross-file
-topology your file tools cannot see.
-
-**Every code discovery task starts with a graph-indexer tool. Never start with
-a native file tool** — no `read file`, `list directory`, `grep`, `codebase
-search`, `find`, or equivalent — regardless of what your IDE calls them.
-Reading a file to "look around" costs 5,000–15,000 tokens; the same answer via
-the index costs 50–700. The difference compounds over every step of your
-session.
-
-Native tools are a **last resort**, permitted only under the fallback rules at
-the end of this document. Editing files is unaffected — write code with your
-normal tools; *discovery* belongs to the index.
-
----
-
-## The five rules
-
-1. **Search before you read.** First step of any discovery task is
-   `search_code`, `resolve_symbol`, or `get_repo_map` — never a file read.
-2. **Know the name? Don't search it.** `resolve_symbol("validateToken")` is an
-   O(1) exact lookup with topology included. Use it whenever you know the
-   symbol's exact name. Use `search_code` only for concepts and behaviour.
-3. **Never read a whole file to get one function.** Search results give you a
-   chunk ID → `get_chunk(id)` returns exactly that function's body.
-4. **Never change a signature blind.** Before modifying any exported
-   function/class, `get_call_graph("name")` lists every caller repo-wide in
-   one call. Skipping this breaks code you cannot see.
-5. **Escalate token spend stepwise.** signatures → summary → smart → full
-   body. Start cheap; pay for bodies only when you must (ladder below).
-
----
-
-## Tool selection — decision table
-
-| You need… | Call | ~Tokens |
-| :--- | :--- | ---: |
-| Orientation in an unfamiliar repo | `get_repo_map()` | 1,500 |
-| Orientation in one subsystem | `get_repo_map(path_filter: "auth")` | 300 |
-| A symbol you can name exactly | `resolve_symbol("UserService")` | 50 |
-| Code for a concept/behaviour | `search_code(query, detail: "signatures")` | 100 |
-| The interface of a found chunk | `get_chunk_summary(id)` | 50 |
-| Interfaces of everything a chunk calls | `get_chunk_summary(id, expand_calls: true)` | 150 |
-| The full implementation | `get_chunk(id)` | 300 |
-| All exports of one known file | `get_file_skeleton("src/file.ts")` | 80 |
-| Who calls a function (pre-refactor) | `get_call_graph("name")` | 100 |
-| What a file imports / who imports it | resource `graph://dependencies/{path}` | 100 |
-| Index health / why results look off | `list_index_stats()` | 100 |
-| *(comparison)* reading one file directly | — | 5,000+ |
-
-### Escalation ladder (token budget)
-
-```
-1. search_code(query, detail: "signatures", top_k: 5)   ~100 tok — find candidates
-2. get_chunk_summary(id)                                 ~50 tok — confirm the interface
-3. search_code(query, detail: "smart")                  ~750 tok — see query-relevant lines
-4. get_chunk(id)                                        ~300 tok — full body, last resort
-```
-
-Stop climbing as soon as you can answer. Most questions die at step 1–2.
-
----
-
-## Writing queries that hit
-
-`search_code` is hybrid (BM25 keywords + semantic vectors) and **detects your
-query style automatically**. Both styles are first-class:
-
-**Keyword style** — when you know domain words or partial names:
-- `JWT token validation expiry middleware`
-- `route registration path method handler`
-- Partial name known? Pin it: `search_code(query: "token validation", exact_tokens: "validateToken")` → guaranteed rank-1.
-- Use resolve_symbol("Name") when you ONLY need the definition of that specific symbol. Use search_code(query: "...", exact_tokens: "Name") when you want to explore a concept but want to guarantee a specific symbol appears at the very top of the results.
-
-**Natural-language style** — when you only know the behaviour:
-- `How does the application parse incoming JSON payloads from the client?`
-- `the logic that decides whether a requested URL matches a registered route`
-- `stopping an HTTP call that takes too long or is no longer needed`
-
-Rules of thumb:
-- Describe **behaviour, not nouns**: `parse and validate request body schema`, not `validation`.
-- One-word queries (`auth`, `request`, `handler`) are useless — thousands of matches.
-- Include path hints when you have them: `middleware auth route` boosts `auth/middleware.ts`.
-- **A keyword miss is not a dead end**: rephrase the same need as a full
-  behavioural sentence — the semantic channel finds code that shares none of
-  your words. This rephrase is *mandatory* before any native-tool fallback.
-- Slow-but-smarter option: `search_code(..., rerank: true)` has a local LLM
-  judge reorder the top results (~1–2 s). Use it when a natural-language query
-  returns plausible-but-not-quite results.
-
-### Reading results
-
-Every result card includes **free topology** — use it instead of new searches:
-- `Deps:` what this file imports (with key symbols per import)
-- `Used by:` which files import this one
-- `Calls:` functions this chunk invokes
-- `ID:` pass to `get_chunk` / `get_chunk_summary` — never re-search what you already found.
-
-A result with node type `re_export` means the symbol is re-exported from a
-dependency (e.g. `fastapi` re-exporting Starlette's `BackgroundTasks`): the
-implementation lives outside this repo — do not hunt for it in the codebase.
-
----
-
-## Standard workflows
-
-**Unfamiliar codebase** → `get_repo_map()` → pick files → `resolve_symbol` /
-`search_code` to drill in.
-
-**"Where is X implemented?"** → `search_code(behavioural query, detail:
-"signatures")` → `get_chunk_summary(best id)` → `get_chunk(id)` only if you
-must see the body.
-
-**Safe refactor** → `get_call_graph("target")` → review callers →
-`get_chunk(callerId)` for each call site you need to update → edit with your
-normal tools.
-
-**Understanding one file** → `get_file_skeleton(path)` (all exports + line
-numbers, no bodies) → drill into specific symbols.
-
-**Debugging a behaviour** → natural-language `search_code` describing the
-symptom's mechanism → follow `Calls:` topology instead of re-searching.
-
----
-
-## Anti-patterns (each of these is a bug in your behaviour)
-
-- ❌ Reading a file as your *first* move on any question.
-- ❌ `search_code("validateToken")` — you know the name; that's `resolve_symbol`.
-- ❌ Re-searching a concept you already have a chunk ID for.
-- ❌ `detail: "full"` by default — signatures first, always.
-- ❌ Editing an exported signature without `get_call_graph` first.
-- ❌ Giving up after one keyword query without trying a behavioural rephrase.
-- ❌ Ignoring `Used by:` / `Calls:` topology and issuing new searches for it.
-- ❌ Re-indexing after edits: Do not tell the user to re-index or attempt to re-index after you modify a file. Graph Indexer has a live daemon (watch-daemon.mjs) that instantly updates the index in the background using SQLite WAL. Your next search will automatically see your changes.
-
----
-
-## Fallback to native tools — the ONLY permitted cases
-
-You may use native file/search tools **only** when one of these is true:
-
-1. **The index says no.** You tried BOTH query styles (keyword + behavioural
-   sentence) and `resolve_symbol`, and the target genuinely isn't returned.
-2. **The index is unhealthy.** `list_index_stats()` shows 0 chunks, a missing
-   index, or a clearly stale index that the daemon isn't updating — tell the
-   user to run `npm run mcp:index`, then fall back for now.
-3. **Non-code files.** Configs, lockfiles, markdown, data files, generated
-   artifacts — the index covers source code chunks; plain files are fair game.
-4. **You need exact current file state for an edit** you are about to make
-   (e.g. precise surrounding lines to produce a diff) — *after* the index
-   located the file and line range for you.
-
-When you do fall back, scope it: read the one file the index pointed you to —
-never directory-walk or repo-grep what the index already answered.
-
----
-
-## Quick reference
-
-```
-search_code(query, exact_tokens?, detail?, top_k?, rerank?)  hybrid search, topology included
-resolve_symbol(symbol)                                       O(1) exact definition lookup
-get_chunk(chunk_id, view?)                                   full body of one chunk
-get_chunk_summary(chunk_id, expand_calls?)                   interface only, ~50 tok
-get_file_skeleton(file_path)                                 all exports of a file, no bodies
-get_call_graph(target_function)                              every caller repo-wide
-get_repo_map(path_filter?, max_files?)                       PageRank-ordered codebase map
-list_index_stats()                                           index health + search mode
-graph://dependencies/{file_path}                             bidirectional import topology
-```
-
-**Detail levels:** `signatures` ~20 tok/result · `smart` (default) ~150 ·
-`full` ~300. **Search modes:** hybrid (semantic + lexical) when Ollama runs;
-lexical-only otherwise — in lexical-only mode prefer keyword-style queries.