kirograph 0.14.1 → 0.16.0

package/dist/mcp/tools.js

@@ -61,6 +61,19 @@ function writeSessionMarker(projectRoot) {
   } catch {
   }
 }
+function formatAge(timestamp) {
+  const diff = Date.now() - timestamp;
+  const minutes = Math.floor(diff / 6e4);
+  if (minutes < 60) return `${minutes}m ago`;
+  const hours = Math.floor(minutes / 60);
+  if (hours < 24) return `${hours}h ago`;
+  const days = Math.floor(hours / 24);
+  if (days < 7) return `${days}d ago`;
+  const weeks = Math.floor(days / 7);
+  if (weeks < 5) return `${weeks}w ago`;
+  const months = Math.floor(days / 30);
+  return `${months}mo ago`;
+}
 const tools = [
   {
     name: "kirograph_search",
@@ -343,6 +356,130 @@ const tools = [
         projectPath: { type: "string", description: "Project root path (optional)" }
       }
     }
+  },
+  // ── Memory tools (require enableMemory=true) ────────────────────────────────
+  {
+    name: "kirograph_mem_search",
+    description: "Search project memory for past decisions, errors, patterns, and context. Returns observations ranked by relevance.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        query: { type: "string", description: "Natural language search query" },
+        kind: {
+          type: "string",
+          description: "Filter by observation kind",
+          enum: ["decision", "error", "pattern", "architecture", "summary", "note"]
+        },
+        limit: { type: "number", description: "Max results (default: 10)", default: 10 },
+        sessionId: { type: "string", description: "Filter to specific session" },
+        projectPath: { type: "string", description: "Project root path (optional)" }
+      },
+      required: ["query"]
+    }
+  },
+  {
+    name: "kirograph_mem_store",
+    description: "Store an observation in project memory. Content is automatically compressed (if caveman mode is on) and linked to relevant code symbols.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        content: { type: "string", description: "Observation text" },
+        kind: {
+          type: "string",
+          description: "Observation kind",
+          enum: ["decision", "error", "pattern", "architecture", "summary", "note"],
+          default: "note"
+        },
+        projectPath: { type: "string", description: "Project root path (optional)" }
+      },
+      required: ["content"]
+    }
+  },
+  {
+    name: "kirograph_mem_timeline",
+    description: "List recent sessions and their observations chronologically.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        limit: { type: "number", description: "Number of sessions to show (default: 5)", default: 5 },
+        sessionId: { type: "string", description: "Show observations for a specific session" },
+        projectPath: { type: "string", description: "Project root path (optional)" }
+      }
+    }
+  },
+  {
+    name: "kirograph_mem_status",
+    description: "Memory subsystem health: session count, observations, embedding coverage, storage size.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        projectPath: { type: "string", description: "Project root path (optional)" }
+      }
+    }
+  },
+  // ── Docs tools (require enableDocs=true) ────────────────────────────────────
+  {
+    name: "kirograph_docs_toc",
+    description: "Get table of contents for a documentation file or the whole project. Returns section IDs, titles, levels, and summaries.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        file: { type: "string", description: "Filter to a specific doc file (relative path). Omit for project-wide TOC." },
+        tree: { type: "boolean", description: "Return nested tree structure (default: false, flat list)", default: false },
+        projectPath: { type: "string", description: "Project root path (optional)" }
+      }
+    }
+  },
+  {
+    name: "kirograph_docs_search",
+    description: "Search documentation sections by query. Returns matching sections ranked by relevance. Independent from kirograph_search (code-only).",
+    inputSchema: {
+      type: "object",
+      properties: {
+        query: { type: "string", description: "Search query (natural language or keywords)" },
+        file: { type: "string", description: "Narrow search to a specific doc file (relative path)" },
+        limit: { type: "number", description: "Max results (default: 10)", default: 10 },
+        projectPath: { type: "string", description: "Project root path (optional)" }
+      },
+      required: ["query"]
+    }
+  },
+  {
+    name: "kirograph_docs_section",
+    description: "Retrieve full content of a documentation section by its stable ID. Use context=true to also get ancestor headings and child summaries.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        id: { type: "string", description: "Section ID (from kirograph_docs_toc or kirograph_docs_search results)" },
+        context: { type: "boolean", description: "Include ancestor heading chain and child summaries (default: false)", default: false },
+        projectPath: { type: "string", description: "Project root path (optional)" }
+      },
+      required: ["id"]
+    }
+  },
+  {
+    name: "kirograph_docs_outline",
+    description: "Get the heading hierarchy for a single documentation file. Lighter than full TOC when you know which file is relevant.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        file: { type: "string", description: "Relative path to the doc file" },
+        projectPath: { type: "string", description: "Project root path (optional)" }
+      },
+      required: ["file"]
+    }
+  },
+  {
+    name: "kirograph_docs_refs",
+    description: "Find code symbols referenced by a doc section, or doc sections that reference a code symbol. Bidirectional lookup.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        sectionId: { type: "string", description: "Doc section ID (find code symbols it references)" },
+        nodeId: { type: "string", description: "Code symbol qualified name (find doc sections that reference it)" },
+        projectPath: { type: "string", description: "Project root path (optional)" }
+      }
+    }
   }
 ];
 class ToolHandler {
@@ -388,7 +525,13 @@ class ToolHandler {
           const naiveCost = estimateNaiveCost(toolName, outputTokens, args);
           if (naiveCost !== null && naiveCost > outputTokens) {
             const tracker = new import_tracker.TokenTracker(projectRoot);
-            tracker.recordGraphSaving(toolName, outputTokens, naiveCost);
+            if (toolName.startsWith("kirograph_mem_")) {
+              tracker.recordMemorySaving(toolName, outputTokens, naiveCost);
+            } else if (toolName.startsWith("kirograph_docs_")) {
+              tracker.recordDocsSaving(toolName, outputTokens, naiveCost);
+            } else {
+              tracker.recordGraphSaving(toolName, outputTokens, naiveCost);
+            }
           }
         } catch {
         }
@@ -455,14 +598,20 @@ class ToolHandler {
         `  Tokens with KiroGraph:    ~${stats.totalCompressed.toLocaleString()}`,
         `  Saved: ${stats.totalSaved.toLocaleString()} tokens (${stats.savingsPercent}%)`
       ];
-      if (stats.bySource.exec.count > 0 || stats.bySource.graph.count > 0) {
+      if (stats.bySource.exec.count > 0 || stats.bySource.graph.count > 0 || stats.bySource.memory.count > 0 || stats.bySource.docs.count > 0) {
         lines.push("", "By source:");
         if (stats.bySource.graph.count > 0) {
           lines.push(`  Graph tools: ${stats.bySource.graph.count} calls, ~${stats.bySource.graph.saved.toLocaleString()} tokens saved (vs file reads/grep)`);
         }
+        if (stats.bySource.docs.count > 0) {
+          lines.push(`  Docs tools: ${stats.bySource.docs.count} calls, ~${stats.bySource.docs.saved.toLocaleString()} tokens saved (vs reading full doc files)`);
+        }
         if (stats.bySource.exec.count > 0) {
           lines.push(`  Compression: ${stats.bySource.exec.count} calls, ~${stats.bySource.exec.saved.toLocaleString()} tokens saved (vs raw output)`);
         }
+        if (stats.bySource.memory.count > 0) {
+          lines.push(`  Memory: ${stats.bySource.memory.count} calls, ~${stats.bySource.memory.saved.toLocaleString()} tokens saved (vs re-discovering context)`);
+        }
       }
       if (Object.keys(stats.byFamily).length > 0) {
         lines.push("", "Top families:");
@@ -520,6 +669,69 @@ class ToolHandler {
             }
           }
         }
+        try {
+          const { loadConfig } = await Promise.resolve().then(() => require("../config.js"));
+          const projectRoot = cg.getProjectRoot();
+          const config = await loadConfig(projectRoot);
+          if (config.enableMemory) {
+            const { MemoryManager } = await Promise.resolve().then(() => require("../memory/index.js"));
+            const db = cg.getDatabase();
+            db.applyMemorySchema();
+            const mem = new MemoryManager(config, db.getRawDb());
+            mem.initialize();
+            const qualifiedNames = [
+              ...ctx.entryPoints.map((n) => n.qualifiedName),
+              ...ctx.relatedNodes.slice(0, 5).map((n) => n.qualifiedName)
+            ].filter(Boolean);
+            const contextLimit = config.memoryContextLimit ?? 3;
+            const contextThreshold = config.memoryContextThreshold ?? 0.3;
+            let memResults = mem.getLinkedObservations(qualifiedNames, contextLimit, contextThreshold);
+            if (memResults.length === 0) {
+              memResults = (await mem.search(args.task, { limit: contextLimit })).filter((r) => r.score >= contextThreshold);
+            }
+            if (memResults.length > 0) {
+              lines.push("", "## Related Memory");
+              for (const r of memResults.slice(0, contextLimit)) {
+                const age = formatAge(r.observation.createdAt);
+                lines.push(`- [${r.observation.kind}] ${r.observation.content} (${age})`);
+              }
+            }
+          }
+        } catch {
+        }
+        try {
+          const projectRoot2 = cg.getProjectRoot();
+          const config2 = await (await Promise.resolve().then(() => require("../config.js"))).loadConfig(projectRoot2);
+          if (config2.enableDocs && config2.docsContextLimit > 0) {
+            const db2 = cg.getDatabase();
+            db2.applyDocsSchema();
+            const { DocsQueries } = await Promise.resolve().then(() => require("../docs/queries.js"));
+            const docsQueries = new DocsQueries(db2.getRawDb(), projectRoot2);
+            const qNames = ctx.entryPoints.map((n) => n.qualifiedName).filter(Boolean);
+            if (qNames.length > 0) {
+              const docRefs = docsQueries.getRefs({ qualifiedName: qNames[0] });
+              const additionalRefs = qNames.slice(1, 5).flatMap((qn) => docsQueries.getRefs({ qualifiedName: qn }));
+              const allDocRefs = [...docRefs, ...additionalRefs];
+              const seenSections = /* @__PURE__ */ new Set();
+              const uniqueRefs = allDocRefs.filter((r) => {
+                if (seenSections.has(r.sectionId)) return false;
+                seenSections.add(r.sectionId);
+                return r.confidence >= config2.docsContextThreshold;
+              }).slice(0, config2.docsContextLimit);
+              if (uniqueRefs.length > 0) {
+                lines.push("", "## Related Documentation");
+                for (const ref of uniqueRefs) {
+                  const section = docsQueries.getSection(ref.sectionId);
+                  if (section) {
+                    const summary = section.section.summary ?? section.section.title;
+                    lines.push(`- [${ref.refType}] ${summary} \u2014 ${section.section.filePath} (ID: ${ref.sectionId})`);
+                  }
+                }
+              }
+            }
+          }
+        } catch {
+        }
         return lines.join("\n");
       }
       case "kirograph_callers": {
@@ -552,8 +764,37 @@ class ToolHandler {
         const node = results[0].node;
         const affected = await cg.getImpactRadius(node.id, args.depth ?? 2);
         if (affected.length === 0) return `No dependents found for \`${node.name}\`.`;
-        return `Changing \`${node.name}\` may affect ${affected.length} symbol(s):
+        let output = `Changing \`${node.name}\` may affect ${affected.length} symbol(s):
 ` + affected.map((n) => `- ${mapKind(n.kind)} \`${n.name}\` \u2014 ${n.filePath}:${n.startLine}`).join("\n");
+        try {
+          const { loadConfig } = await Promise.resolve().then(() => require("../config.js"));
+          const projectRoot = cg.getProjectRoot();
+          const config = await loadConfig(projectRoot);
+          if (config.enableMemory) {
+            const { MemoryManager } = await Promise.resolve().then(() => require("../memory/index.js"));
+            const db = cg.getDatabase();
+            db.applyMemorySchema();
+            const mem = new MemoryManager(config, db.getRawDb());
+            mem.initialize();
+            const contextLimit = config.memoryContextLimit ?? 3;
+            const contextThreshold = config.memoryContextThreshold ?? 0.3;
+            const memResults = mem.getLinkedObservations(
+              [node.qualifiedName],
+              contextLimit,
+              contextThreshold
+            );
+            if (memResults.length > 0) {
+              output += "\n\nRelated Memory:";
+              for (const r of memResults) {
+                const age = formatAge(r.observation.createdAt);
+                output += `
+- [${r.observation.kind}] ${r.observation.content} (${age})`;
+              }
+            }
+          }
+        } catch {
+        }
+        return output;
       }
       case "kirograph_node": {
         const results = cg.searchNodes(args.symbol, void 0, 5);
@@ -585,6 +826,21 @@ class ToolHandler {
         ] : [`  Semantic search: disabled`];
         const frameworkLine = stats.frameworks.length > 0 ? `  Frameworks: ${stats.frameworks.join(", ")}` : `  Frameworks: none detected`;
         const archLine = stats.architectureEnabled ? stats.architectureStats ? `  Architecture: enabled \u2014 ${stats.architectureStats.packages} packages, ${stats.architectureStats.layers} layers, ${stats.architectureStats.packageDeps} deps` : `  Architecture: enabled (not yet analyzed \u2014 run kirograph index)` : `  Architecture: disabled`;
+        let docsLine = "  Documentation: disabled";
+        try {
+          const { loadConfig: loadCfg } = await Promise.resolve().then(() => require("../config.js"));
+          const cfg = await loadCfg(cg.getProjectRoot());
+          if (cfg.enableDocs) {
+            const db = cg.getDatabase();
+            db.applyDocsSchema();
+            const rawDb = db.getRawDb();
+            const docFiles = rawDb.get("SELECT COUNT(DISTINCT file_path) as cnt FROM doc_sections")?.cnt ?? 0;
+            const docSections = rawDb.get("SELECT COUNT(*) as cnt FROM doc_sections")?.cnt ?? 0;
+            const docRefs = rawDb.get("SELECT COUNT(*) as cnt FROM doc_code_refs")?.cnt ?? 0;
+            docsLine = `  Documentation: enabled \u2014 ${docFiles} files, ${docSections} sections, ${docRefs} code refs`;
+          }
+        } catch {
+        }
         const threshold = stats.syncWarningThreshold ?? 10;
         const pendingFiles = stats.pendingFiles ?? 0;
         const syncRunning = stats.syncRunning ?? false;
@@ -613,6 +869,7 @@ class ToolHandler {
           langLine ? `  By language: ${langLine}` : "",
           frameworkLine,
           archLine,
+          docsLine,
           `  DB size: ${dbMb} MB`,
           ...semanticLines,
           ...syncLines,
@@ -934,6 +1191,222 @@ class ToolHandler {
         }
         return lines.join("\n");
       }
+      // ── Memory tools ────────────────────────────────────────────────────────
+      case "kirograph_mem_search": {
+        const { loadConfig } = await Promise.resolve().then(() => require("../config.js"));
+        const projectRoot = cg.getProjectRoot();
+        const config = await loadConfig(projectRoot);
+        if (!config.enableMemory) return "Memory is not enabled. Set enableMemory: true in .kirograph/config.json";
+        const { MemoryManager } = await Promise.resolve().then(() => require("../memory/index.js"));
+        const db = cg.getDatabase();
+        db.applyMemorySchema();
+        const mem = new MemoryManager(config, db.getRawDb());
+        mem.initialize();
+        const results = await mem.search(args.query, {
+          limit: args.limit ?? 10,
+          kind: args.kind,
+          sessionId: args.sessionId
+        });
+        if (results.length === 0) return `No memory observations found for "${args.query}".`;
+        return results.map((r, i) => {
+          const age = formatAge(r.observation.createdAt);
+          return `${i + 1}. [${r.observation.kind}] ${r.observation.content} (${age})`;
+        }).join("\n");
+      }
+      case "kirograph_mem_store": {
+        const { loadConfig } = await Promise.resolve().then(() => require("../config.js"));
+        const projectRoot = cg.getProjectRoot();
+        const config = await loadConfig(projectRoot);
+        if (!config.enableMemory) return "Memory is not enabled. Set enableMemory: true in .kirograph/config.json";
+        const { MemoryManager } = await Promise.resolve().then(() => require("../memory/index.js"));
+        const db = cg.getDatabase();
+        db.applyMemorySchema();
+        const mem = new MemoryManager(config, db.getRawDb());
+        mem.initialize();
+        const id = await mem.store({
+          content: args.content,
+          kind: args.kind ?? "note",
+          source: "agent"
+        });
+        if (!id) return "Observation already exists (duplicate content).";
+        return `Stored observation ${id} [${args.kind ?? "note"}]`;
+      }
+      case "kirograph_mem_timeline": {
+        const { loadConfig } = await Promise.resolve().then(() => require("../config.js"));
+        const projectRoot = cg.getProjectRoot();
+        const config = await loadConfig(projectRoot);
+        if (!config.enableMemory) return "Memory is not enabled. Set enableMemory: true in .kirograph/config.json";
+        const { MemoryManager } = await Promise.resolve().then(() => require("../memory/index.js"));
+        const db = cg.getDatabase();
+        db.applyMemorySchema();
+        const mem = new MemoryManager(config, db.getRawDb());
+        mem.initialize();
+        const { sessions, observations } = mem.timeline({
+          limit: args.limit ?? 5,
+          sessionId: args.sessionId
+        });
+        if (sessions.length === 0) return "No memory sessions found.";
+        const lines = [];
+        for (const session of sessions) {
+          const start = new Date(session.startedAt).toISOString().slice(0, 16).replace("T", " ");
+          const status = session.endedAt ? "ended" : "active";
+          const obs = observations.get(session.id) ?? [];
+          lines.push(`## ${start} [${session.ide ?? "unknown"}] (${status}, ${obs.length} observations)`);
+          for (const o of obs.slice(0, 5)) {
+            lines.push(`  - [${o.kind}] ${o.content.slice(0, 120)}`);
+          }
+          if (obs.length > 5) lines.push(`  \u2026and ${obs.length - 5} more`);
+        }
+        return lines.join("\n");
+      }
+      case "kirograph_mem_status": {
+        const { loadConfig } = await Promise.resolve().then(() => require("../config.js"));
+        const projectRoot = cg.getProjectRoot();
+        const config = await loadConfig(projectRoot);
+        if (!config.enableMemory) return "Memory is not enabled. Set enableMemory: true in .kirograph/config.json";
+        const { MemoryManager } = await Promise.resolve().then(() => require("../memory/index.js"));
+        const db = cg.getDatabase();
+        db.applyMemorySchema();
+        const mem = new MemoryManager(config, db.getRawDb());
+        mem.initialize();
+        const stats = mem.getStats();
+        const lines = [
+          "KiroGraph Memory Status",
+          `  Sessions: ${stats.sessions} (${stats.activeSessions} active)`,
+          `  Observations: ${stats.observations}`,
+          `  Symbol links: ${stats.links}`,
+          `  Embeddings: ${stats.vectors} / ${stats.embeddableCount}`,
+          `  Model mismatch: ${stats.modelMismatch ? "\u26A0 yes \u2014 run kirograph mem reembed" : "no"}`,
+          `  Caveman compression: ${config.cavemanMode !== "off" ? config.cavemanMode : "off (storing raw)"}`
+        ];
+        return lines.join("\n");
+      }
+      // ── Docs tools ────────────────────────────────────────────────────────────
+      case "kirograph_docs_toc": {
+        const { loadConfig } = await Promise.resolve().then(() => require("../config.js"));
+        const projectRoot = cg.getProjectRoot();
+        const config = await loadConfig(projectRoot);
+        if (!config.enableDocs) return "Documentation indexing is not enabled. Set enableDocs: true in .kirograph/config.json and run kirograph index.";
+        const { DocsQueries } = await Promise.resolve().then(() => require("../docs/queries.js"));
+        const db = cg.getDatabase();
+        db.applyDocsSchema();
+        const docs = new DocsQueries(db.getRawDb(), projectRoot);
+        const toc = docs.getToc({ file: args.file, tree: args.tree });
+        if (toc.length === 0) return args.file ? `No sections found in "${args.file}".` : "No documentation indexed. Run kirograph index.";
+        const lines = [];
+        const renderEntry = (entry, indent) => {
+          const prefix = "#".repeat(entry.level || 1);
+          const summary = entry.summary ? ` \u2014 ${entry.summary}` : "";
+          lines.push(`${indent}${prefix} ${entry.title}${summary}`);
+          lines.push(`${indent}  ID: ${entry.id}`);
+          if (entry.children?.length) {
+            for (const child of entry.children) renderEntry(child, indent + "  ");
+          }
+        };
+        if (args.tree) {
+          for (const entry of toc) renderEntry(entry, "");
+        } else {
+          for (const entry of toc) {
+            const prefix = "#".repeat(entry.level || 1);
+            const summary = entry.summary ? ` \u2014 ${entry.summary}` : "";
+            lines.push(`${prefix} ${entry.title} [${entry.filePath}]${summary}`);
+            lines.push(`  ID: ${entry.id}`);
+          }
+        }
+        return lines.join("\n");
+      }
+      case "kirograph_docs_search": {
+        const { loadConfig } = await Promise.resolve().then(() => require("../config.js"));
+        const projectRoot = cg.getProjectRoot();
+        const config = await loadConfig(projectRoot);
+        if (!config.enableDocs) return "Documentation indexing is not enabled. Set enableDocs: true in .kirograph/config.json and run kirograph index.";
+        const { DocsQueries } = await Promise.resolve().then(() => require("../docs/queries.js"));
+        const db = cg.getDatabase();
+        db.applyDocsSchema();
+        const docs = new DocsQueries(db.getRawDb(), projectRoot, config);
+        const results = await docs.searchSections(args.query, {
+          file: args.file,
+          limit: args.limit ?? 10
+        });
+        if (results.length === 0) return `No documentation sections found matching "${args.query}".`;
+        return results.map((r, i) => {
+          const summary = r.section.summary ? `
+  ${r.section.summary}` : "";
+          return `${i + 1}. ${r.section.title} [${r.section.filePath}]${summary}
+  ID: ${r.section.id}`;
+        }).join("\n\n");
+      }
+      case "kirograph_docs_section": {
+        const { loadConfig } = await Promise.resolve().then(() => require("../config.js"));
+        const projectRoot = cg.getProjectRoot();
+        const config = await loadConfig(projectRoot);
+        if (!config.enableDocs) return "Documentation indexing is not enabled. Set enableDocs: true in .kirograph/config.json and run kirograph index.";
+        const { DocsQueries } = await Promise.resolve().then(() => require("../docs/queries.js"));
+        const db = cg.getDatabase();
+        db.applyDocsSchema();
+        const docs = new DocsQueries(db.getRawDb(), projectRoot);
+        const result = docs.getSection(args.id, { context: args.context });
+        if (!result) return `Section "${args.id}" not found.`;
+        const lines = [];
+        if (result.ancestors?.length) {
+          lines.push("Breadcrumb: " + result.ancestors.map((a) => a.title).join(" > ") + " > " + result.section.title);
+          lines.push("");
+        }
+        lines.push(result.content);
+        if (result.children?.length) {
+          lines.push("", "## Child sections:");
+          for (const child of result.children) {
+            const summary = child.summary ? ` \u2014 ${child.summary}` : "";
+            lines.push(`  - ${child.title}${summary} (ID: ${child.id})`);
+          }
+        }
+        return lines.join("\n");
+      }
+      case "kirograph_docs_outline": {
+        const { loadConfig } = await Promise.resolve().then(() => require("../config.js"));
+        const projectRoot = cg.getProjectRoot();
+        const config = await loadConfig(projectRoot);
+        if (!config.enableDocs) return "Documentation indexing is not enabled. Set enableDocs: true in .kirograph/config.json and run kirograph index.";
+        const { DocsQueries } = await Promise.resolve().then(() => require("../docs/queries.js"));
+        const db = cg.getDatabase();
+        db.applyDocsSchema();
+        const docs = new DocsQueries(db.getRawDb(), projectRoot);
+        const outline = docs.getOutline(args.file);
+        if (outline.length === 0) return `No sections found in "${args.file}". Is the file indexed?`;
+        const lines = [`Outline: ${args.file}`, ""];
+        const renderOutline = (entries, indent) => {
+          for (const entry of entries) {
+            const summary = entry.summary ? ` \u2014 ${entry.summary}` : "";
+            lines.push(`${indent}${"#".repeat(entry.level || 1)} ${entry.title}${summary}`);
+            if (entry.children?.length) renderOutline(entry.children, indent + "  ");
+          }
+        };
+        renderOutline(outline, "");
+        return lines.join("\n");
+      }
+      case "kirograph_docs_refs": {
+        const { loadConfig } = await Promise.resolve().then(() => require("../config.js"));
+        const projectRoot = cg.getProjectRoot();
+        const config = await loadConfig(projectRoot);
+        if (!config.enableDocs) return "Documentation indexing is not enabled. Set enableDocs: true in .kirograph/config.json and run kirograph index.";
+        const { DocsQueries } = await Promise.resolve().then(() => require("../docs/queries.js"));
+        const db = cg.getDatabase();
+        db.applyDocsSchema();
+        const docs = new DocsQueries(db.getRawDb(), projectRoot);
+        const refs = docs.getRefs({
+          sectionId: args.sectionId,
+          qualifiedName: args.nodeId
+        });
+        if (refs.length === 0) {
+          if (args.sectionId) return `No code references found in section "${args.sectionId}".`;
+          if (args.nodeId) return `No documentation sections reference "${args.nodeId}".`;
+          return "Provide either sectionId or nodeId to look up cross-references.";
+        }
+        return refs.map((r) => {
+          const direction = args.sectionId ? `\u2192 ${r.qualifiedName}` : `\u2190 ${r.sectionTitle ?? r.sectionId}`;
+          return `[${r.refType}] ${direction} (confidence: ${r.confidence.toFixed(2)})`;
+        }).join("\n");
+      }
       default:
         return `Unknown tool: ${toolName}`;
     }