kirograph 0.15.0 → 0.16.0

package/dist/docs/vectors.js

@@ -0,0 +1,217 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var vectors_exports = {};
+__export(vectors_exports, {
+  DocsVectorManager: () => DocsVectorManager
+});
+module.exports = __toCommonJS(vectors_exports);
+var import_errors = require("../errors");
+const MAX_TOKEN_CHARS = 2e3;
+let transformers = null;
+let pipeline = null;
+let pipelineModel = null;
+async function getTransformers() {
+  if (!transformers) {
+    transformers = await import("@huggingface/transformers");
+  }
+  return transformers;
+}
+async function getPipeline(modelName, cacheDir) {
+  if (pipeline && pipelineModel === modelName) return pipeline;
+  const tf = await getTransformers();
+  pipeline = await tf.pipeline("feature-extraction", modelName, {
+    cache_dir: cacheDir,
+    dtype: "fp32"
+  });
+  pipelineModel = modelName;
+  return pipeline;
+}
+function sectionToText(section) {
+  const parts = [section.title];
+  if (section.summary) parts.push(section.summary);
+  const text = parts.join(": ");
+  return text.length > MAX_TOKEN_CHARS ? text.slice(0, MAX_TOKEN_CHARS) : text;
+}
+function cosine(a, b) {
+  let dot = 0, na = 0, nb = 0;
+  for (let i = 0; i < a.length; i++) {
+    dot += a[i] * b[i];
+    na += a[i] * a[i];
+    nb += b[i] * b[i];
+  }
+  const denom = Math.sqrt(na) * Math.sqrt(nb);
+  return denom === 0 ? 0 : dot / denom;
+}
+class DocsVectorManager {
+  constructor(config, db) {
+    this.config = config;
+    this.db = db;
+    this.modelName = config.embeddingModel ?? "nomic-ai/nomic-embed-text-v1.5";
+    const { homedir } = require("os");
+    const path = require("path");
+    this.cacheDir = path.join(homedir(), ".kirograph", "models");
+  }
+  /**
+   * Check if embeddings are enabled in config.
+   */
+  isEnabled() {
+    return !!this.config.enableEmbeddings;
+  }
+  /**
+   * Embed a single doc section and store in doc_vectors.
+   */
+  async embedSection(section) {
+    if (!this.isEnabled()) return;
+    try {
+      const text = sectionToText(section);
+      const embedding = await this.embed(text);
+      if (embedding) {
+        const buffer = Buffer.from(embedding.buffer);
+        this.db.run(
+          "INSERT OR REPLACE INTO doc_vectors (section_id, embedding, model, created_at) VALUES (?, ?, ?, ?)",
+          [section.id, buffer, this.modelName, Date.now()]
+        );
+      }
+    } catch (err) {
+      (0, import_errors.logWarn)(`Failed to embed doc section ${section.id}: ${err}`);
+    }
+  }
+  /**
+   * Embed multiple sections in batch.
+   */
+  async embedBatch(sections) {
+    if (!this.isEnabled()) return 0;
+    let embedded = 0;
+    for (const section of sections) {
+      try {
+        await this.embedSection(section);
+        embedded++;
+      } catch (err) {
+        (0, import_errors.logWarn)(`Failed to embed doc section ${section.id}: ${err}`);
+      }
+    }
+    return embedded;
+  }
+  /**
+   * Vector search over doc sections.
+   * Returns scored sections sorted by cosine similarity.
+   * Falls back to empty results if embeddings are disabled.
+   */
+  async search(query, limit = 10) {
+    if (!this.isEnabled()) return [];
+    try {
+      const queryEmbedding = await this.embed(query);
+      if (!queryEmbedding) return [];
+      const allVectors = this.db.all(
+        "SELECT section_id, embedding FROM doc_vectors WHERE model = ?",
+        [this.modelName]
+      );
+      if (allVectors.length === 0) return [];
+      const scored = [];
+      for (const { section_id, embedding } of allVectors) {
+        const vec = new Float32Array(
+          embedding.buffer,
+          embedding.byteOffset,
+          embedding.byteLength / 4
+        );
+        const score = cosine(queryEmbedding, vec);
+        scored.push({ sectionId: section_id, score });
+      }
+      scored.sort((a, b) => b.score - a.score);
+      return scored.slice(0, limit);
+    } catch (err) {
+      (0, import_errors.logError)("Docs vector search failed", { error: err });
+      return [];
+    }
+  }
+  /**
+   * Check if there are vectors with a mismatched model.
+   */
+  hasModelMismatch() {
+    const mismatch = this.db.get(
+      "SELECT COUNT(*) as cnt FROM doc_vectors WHERE model != ?",
+      [this.modelName]
+    )?.cnt ?? 0;
+    return mismatch > 0;
+  }
+  /**
+   * Get vector stats.
+   */
+  getStats() {
+    const total = this.db.get("SELECT COUNT(*) as cnt FROM doc_vectors")?.cnt ?? 0;
+    const currentModel = this.db.get(
+      "SELECT COUNT(*) as cnt FROM doc_vectors WHERE model = ?",
+      [this.modelName]
+    )?.cnt ?? 0;
+    return { total, currentModel, mismatch: total - currentModel };
+  }
+  /**
+   * Re-embed all doc sections with the current model.
+   */
+  async reembed(batchSize = 32) {
+    this.db.run("DELETE FROM doc_vectors");
+    const rows = this.db.all("SELECT * FROM doc_sections ORDER BY file_path, position");
+    const sections = rows.map((row) => ({
+      id: row.id,
+      filePath: row.file_path,
+      title: row.title,
+      level: row.level,
+      parentId: row.parent_id ?? null,
+      summary: row.summary ?? null,
+      byteStart: row.byte_start,
+      byteEnd: row.byte_end,
+      contentHash: row.content_hash,
+      tags: row.tags ? JSON.parse(row.tags) : [],
+      position: row.position,
+      updatedAt: row.updated_at
+    }));
+    let embedded = 0;
+    for (let i = 0; i < sections.length; i += batchSize) {
+      const batch = sections.slice(i, i + batchSize);
+      embedded += await this.embedBatch(batch);
+    }
+    return embedded;
+  }
+  // ── Private ────────────────────────────────────────────────────────────────
+  async embed(text) {
+    try {
+      const pipe = await getPipeline(this.modelName, this.cacheDir);
+      const output = await pipe(text, { pooling: "mean", normalize: true });
+      return output.data;
+    } catch (err) {
+      (0, import_errors.logDebug)(`Doc embedding failed: ${err}`);
+      return null;
+    }
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  DocsVectorManager
+});
+//# sourceMappingURL=vectors.js.map

package/dist/docs/vectors.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/docs/vectors.ts"],
+  "sourcesContent": ["/**\n * KiroGraph Docs \u2014 Vector embedding and search\n *\n * Reuses the same embedding model and pipeline as the memory module,\n * but operates on doc_vectors table independently.\n */\n\nimport type { KiroGraphConfig } from '../config';\nimport type { DocSection, DocSearchResult } from './types';\nimport { logDebug, logWarn, logError } from '../errors';\n\nconst MAX_TOKEN_CHARS = 2000;\n\n// \u2500\u2500 Embedder (reuses the same pipeline as memory/code vectors) \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n\nlet transformers: typeof import('@huggingface/transformers') | null = null;\nlet pipeline: any = null;\nlet pipelineModel: string | null = null;\n\nasync function getTransformers() {\n  if (!transformers) {\n    transformers = await import('@huggingface/transformers');\n  }\n  return transformers;\n}\n\nasync function getPipeline(modelName: string, cacheDir: string) {\n  if (pipeline && pipelineModel === modelName) return pipeline;\n\n  const tf = await getTransformers();\n  pipeline = await tf.pipeline('feature-extraction', modelName, {\n    cache_dir: cacheDir,\n    dtype: 'fp32',\n  } as any);\n  pipelineModel = modelName;\n  return pipeline;\n}\n\n/**\n * Build searchable text from a doc section.\n * Uses title + summary for embedding (concise, semantically rich).\n */\nfunction sectionToText(section: DocSection): string {\n  const parts = [section.title];\n  if (section.summary) parts.push(section.summary);\n  const text = parts.join(': ');\n  return text.length > MAX_TOKEN_CHARS ? text.slice(0, MAX_TOKEN_CHARS) : text;\n}\n\n/** Cosine similarity between two Float32Arrays */\nfunction cosine(a: Float32Array, b: Float32Array): number {\n  let dot = 0, na = 0, nb = 0;\n  for (let i = 0; i < a.length; i++) {\n    dot += a[i] * b[i];\n    na += a[i] * a[i];\n    nb += b[i] * b[i];\n  }\n  const denom = Math.sqrt(na) * Math.sqrt(nb);\n  return denom === 0 ? 0 : dot / denom;\n}\n\n// \u2500\u2500 DocsVectorManager \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n\nexport class DocsVectorManager {\n  private config: KiroGraphConfig;\n  private db: any; // raw SQLite handle\n  private modelName: string;\n  private cacheDir: string;\n\n  constructor(config: KiroGraphConfig, db: any) {\n    this.config = config;\n    this.db = db;\n    this.modelName = config.embeddingModel ?? 'nomic-ai/nomic-embed-text-v1.5';\n\n    const { homedir } = require('os');\n    const path = require('path');\n    this.cacheDir = path.join(homedir(), '.kirograph', 'models');\n  }\n\n  /**\n   * Check if embeddings are enabled in config.\n   */\n  isEnabled(): boolean {\n    return !!this.config.enableEmbeddings;\n  }\n\n  /**\n   * Embed a single doc section and store in doc_vectors.\n   */\n  async embedSection(section: DocSection): Promise<void> {\n    if (!this.isEnabled()) return;\n\n    try {\n      const text = sectionToText(section);\n      const embedding = await this.embed(text);\n      if (embedding) {\n        const buffer = Buffer.from(embedding.buffer);\n        this.db.run(\n          'INSERT OR REPLACE INTO doc_vectors (section_id, embedding, model, created_at) VALUES (?, ?, ?, ?)',\n          [section.id, buffer, this.modelName, Date.now()],\n        );\n      }\n    } catch (err) {\n      logWarn(`Failed to embed doc section ${section.id}: ${err}`);\n    }\n  }\n\n  /**\n   * Embed multiple sections in batch.\n   */\n  async embedBatch(sections: DocSection[]): Promise<number> {\n    if (!this.isEnabled()) return 0;\n\n    let embedded = 0;\n    for (const section of sections) {\n      try {\n        await this.embedSection(section);\n        embedded++;\n      } catch (err) {\n        logWarn(`Failed to embed doc section ${section.id}: ${err}`);\n      }\n    }\n    return embedded;\n  }\n\n  /**\n   * Vector search over doc sections.\n   * Returns scored sections sorted by cosine similarity.\n   * Falls back to empty results if embeddings are disabled.\n   */\n  async search(query: string, limit = 10): Promise<Array<{ sectionId: string; score: number }>> {\n    if (!this.isEnabled()) return [];\n\n    try {\n      const queryEmbedding = await this.embed(query);\n      if (!queryEmbedding) return [];\n\n      // Get all doc vectors with matching model\n      const allVectors = this.db.all(\n        'SELECT section_id, embedding FROM doc_vectors WHERE model = ?',\n        [this.modelName],\n      ) as Array<{ section_id: string; embedding: Buffer }>;\n\n      if (allVectors.length === 0) return [];\n\n      // Compute cosine similarity for each\n      const scored: Array<{ sectionId: string; score: number }> = [];\n      for (const { section_id, embedding } of allVectors) {\n        const vec = new Float32Array(\n          embedding.buffer,\n          embedding.byteOffset,\n          embedding.byteLength / 4,\n        );\n        const score = cosine(queryEmbedding, vec);\n        scored.push({ sectionId: section_id, score });\n      }\n\n      // Sort by score descending, take top N\n      scored.sort((a, b) => b.score - a.score);\n      return scored.slice(0, limit);\n    } catch (err) {\n      logError('Docs vector search failed', { error: err });\n      return [];\n    }\n  }\n\n  /**\n   * Check if there are vectors with a mismatched model.\n   */\n  hasModelMismatch(): boolean {\n    const mismatch = this.db.get(\n      'SELECT COUNT(*) as cnt FROM doc_vectors WHERE model != ?',\n      [this.modelName],\n    )?.cnt ?? 0;\n    return mismatch > 0;\n  }\n\n  /**\n   * Get vector stats.\n   */\n  getStats(): { total: number; currentModel: number; mismatch: number } {\n    const total = this.db.get('SELECT COUNT(*) as cnt FROM doc_vectors')?.cnt ?? 0;\n    const currentModel = this.db.get(\n      'SELECT COUNT(*) as cnt FROM doc_vectors WHERE model = ?',\n      [this.modelName],\n    )?.cnt ?? 0;\n    return { total, currentModel, mismatch: total - currentModel };\n  }\n\n  /**\n   * Re-embed all doc sections with the current model.\n   */\n  async reembed(batchSize = 32): Promise<number> {\n    // Delete all existing doc vectors\n    this.db.run('DELETE FROM doc_vectors');\n\n    // Get all sections\n    const rows = this.db.all('SELECT * FROM doc_sections ORDER BY file_path, position') as any[];\n    const sections: DocSection[] = rows.map((row: any) => ({\n      id: row.id,\n      filePath: row.file_path,\n      title: row.title,\n      level: row.level,\n      parentId: row.parent_id ?? null,\n      summary: row.summary ?? null,\n      byteStart: row.byte_start,\n      byteEnd: row.byte_end,\n      contentHash: row.content_hash,\n      tags: row.tags ? JSON.parse(row.tags) : [],\n      position: row.position,\n      updatedAt: row.updated_at,\n    }));\n\n    let embedded = 0;\n    for (let i = 0; i < sections.length; i += batchSize) {\n      const batch = sections.slice(i, i + batchSize);\n      embedded += await this.embedBatch(batch);\n    }\n\n    return embedded;\n  }\n\n  // \u2500\u2500 Private \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n\n  private async embed(text: string): Promise<Float32Array | null> {\n    try {\n      const pipe = await getPipeline(this.modelName, this.cacheDir);\n      const output = await pipe(text, { pooling: 'mean', normalize: true });\n      return output.data as Float32Array;\n    } catch (err) {\n      logDebug(`Doc embedding failed: ${err}`);\n      return null;\n    }\n  }\n}\n"],
+  "mappings": "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",
+  "names": []
+}

package/dist/mcp/tool-names.js

@@ -45,7 +45,12 @@ const KIROGRAPH_TOOL_NAMES = [
   "kirograph_mem_search",
   "kirograph_mem_store",
   "kirograph_mem_timeline",
-  "kirograph_mem_status"
+  "kirograph_mem_status",
+  "kirograph_docs_toc",
+  "kirograph_docs_search",
+  "kirograph_docs_section",
+  "kirograph_docs_outline",
+  "kirograph_docs_refs"
 ];
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {

package/dist/mcp/tool-names.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../src/mcp/tool-names.ts"],
-  "sourcesContent": ["export const KIROGRAPH_TOOL_NAMES = [\n  'kirograph_search',\n  'kirograph_context',\n  'kirograph_callers',\n  'kirograph_callees',\n  'kirograph_impact',\n  'kirograph_node',\n  'kirograph_status',\n  'kirograph_files',\n  'kirograph_dead_code',\n  'kirograph_circular_deps',\n  'kirograph_path',\n  'kirograph_architecture',\n  'kirograph_coupling',\n  'kirograph_package',\n  'kirograph_hotspots',\n  'kirograph_surprising',\n  'kirograph_diff',\n  'kirograph_type_hierarchy',\n  'kirograph_exec',\n  'kirograph_gain',\n  'kirograph_mem_search',\n  'kirograph_mem_store',\n  'kirograph_mem_timeline',\n  'kirograph_mem_status',\n];\n\n"],
-  "mappings": ";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAO,MAAM,uBAAuB;AAAA,EAClC;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF;",
+  "sourcesContent": ["export const KIROGRAPH_TOOL_NAMES = [\n  'kirograph_search',\n  'kirograph_context',\n  'kirograph_callers',\n  'kirograph_callees',\n  'kirograph_impact',\n  'kirograph_node',\n  'kirograph_status',\n  'kirograph_files',\n  'kirograph_dead_code',\n  'kirograph_circular_deps',\n  'kirograph_path',\n  'kirograph_architecture',\n  'kirograph_coupling',\n  'kirograph_package',\n  'kirograph_hotspots',\n  'kirograph_surprising',\n  'kirograph_diff',\n  'kirograph_type_hierarchy',\n  'kirograph_exec',\n  'kirograph_gain',\n  'kirograph_mem_search',\n  'kirograph_mem_store',\n  'kirograph_mem_timeline',\n  'kirograph_mem_status',\n  'kirograph_docs_toc',\n  'kirograph_docs_search',\n  'kirograph_docs_section',\n  'kirograph_docs_outline',\n  'kirograph_docs_refs',\n];\n\n"],
+  "mappings": ";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAO,MAAM,uBAAuB;AAAA,EAClC;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF;",
   "names": []
 }

package/dist/mcp/tools.js

@@ -416,6 +416,70 @@ const tools = [
         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 {
@@ -463,6 +527,8 @@ class ToolHandler {
             const tracker = new import_tracker.TokenTracker(projectRoot);
             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);
             }
@@ -532,11 +598,14 @@ 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 || stats.bySource.memory.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)`);
         }
@@ -630,6 +699,39 @@ class ToolHandler {
           }
         } 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": {
@@ -724,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;
@@ -752,6 +869,7 @@ class ToolHandler {
           langLine ? `  By language: ${langLine}` : "",
           frameworkLine,
           archLine,
+          docsLine,
           `  DB size: ${dbMb} MB`,
           ...semanticLines,
           ...syncLines,
@@ -1163,6 +1281,132 @@ class ToolHandler {
         ];
         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}`;
     }