@monoes/cli 1.2.0 → 1.2.2

package/dist/src/mcp-tools/graphify-tools.js

@@ -1,49 +1,58 @@
 /**
- * Graphify MCP Tools (compiled)
+ * Graphify MCP Tools
  *
  * Bridges @monobrain/graph's knowledge graph into monobrain's MCP tool surface.
+ * Agents can query the codebase knowledge graph without reading files —
+ * god_nodes(), query_graph(), shortest_path() give structural understanding
+ * in milliseconds vs. reading dozens of source files.
+ *
  * Graph is built automatically on `monobrain init` and stored at
  * .monobrain/graph/graph.json (legacy: graphify-out/graph.json).
+ * Rebuild manually: call graphify_build via MCP.
  */
 import { existsSync, readFileSync } from 'fs';
 import { join, resolve } from 'path';
 import { getProjectCwd } from './types.js';
-
 // ── Path helpers ──────────────────────────────────────────────────────────────
-
+/** Resolve graph path: prefer native monobrain path, fall back to legacy graphify path. */
 function getGraphPath(cwd) {
     const nativePath = resolve(join(cwd, '.monobrain', 'graph', 'graph.json'));
     const legacyPath = resolve(join(cwd, 'graphify-out', 'graph.json'));
-    if (existsSync(nativePath)) return nativePath;
-    if (existsSync(legacyPath)) return legacyPath;
-    return nativePath;
+    if (existsSync(nativePath))
+        return nativePath;
+    if (existsSync(legacyPath))
+        return legacyPath;
+    return nativePath; // return expected path even if not yet built
 }
-
 function graphExists(cwd) {
     return existsSync(getGraphPath(cwd));
 }
-
-// ── Graph loading ─────────────────────────────────────────────────────────────
-
+/**
+ * Load the knowledge graph.
+ * Tries @monobrain/graph's loadGraph first; falls back to parsing raw JSON.
+ */
 async function loadKnowledgeGraph(cwd) {
     const graphPath = getGraphPath(cwd);
     let rawNodes = [];
     let rawEdges = [];
-
     try {
+        // Prefer @monobrain/graph's loader which handles format normalization.
         const { loadGraph } = await import('@monoes/graph');
         const loaded = loadGraph(graphPath);
         rawNodes = loaded.nodes;
         rawEdges = loaded.edges;
-    } catch {
+    }
+    catch {
+        // Fallback: parse JSON directly
         const data = JSON.parse(readFileSync(graphPath, 'utf-8'));
         rawNodes = data.nodes || [];
         rawEdges = data.links || data.edges || [];
     }
-
+    // Build in-memory graph structures
     const nodes = new Map();
-    for (const n of rawNodes) nodes.set(n.id, n);
-
+    for (const n of rawNodes) {
+        nodes.set(n.id, n);
+    }
     const adj = new Map();
     const radj = new Map();
     const degree = new Map();
@@ -53,15 +62,16 @@ async function loadKnowledgeGraph(cwd) {
         degree.set(n.id, 0);
     }
     for (const e of rawEdges) {
-        adj.get(e.source)?.push(e.target);
-        radj.get(e.target)?.push(e.source);
-        degree.set(e.source, (degree.get(e.source) ?? 0) + 1);
-        degree.set(e.target, (degree.get(e.target) ?? 0) + 1);
+        const src = e.source;
+        const tgt = e.target;
+        adj.get(src)?.push(tgt);
+        radj.get(tgt)?.push(src);
+        degree.set(src, (degree.get(src) ?? 0) + 1);
+        degree.set(tgt, (degree.get(tgt) ?? 0) + 1);
     }
-
     return { nodes, adj, radj, edges: rawEdges, degree, graphPath };
 }
-
+// ── Shared output helpers ─────────────────────────────────────────────────────
 function nodeOut(g, id) {
     const d = g.nodes.get(id) ?? { id };
     return {
@@ -74,21 +84,25 @@ function nodeOut(g, id) {
         file_type: d.file_type ?? '',
     };
 }
-
+/** Score a node against search terms. */
 function scoreNode(g, id, terms) {
     const d = g.nodes.get(id);
-    if (!d) return 0;
+    if (!d)
+        return 0;
     const label = (d.label ?? id).toLowerCase();
     const file = (d.source_file ?? '').toLowerCase();
     return terms.reduce((s, t) => {
-        if (label.includes(t)) s += 1;
-        if (file.includes(t)) s += 0.5;
+        if (label.includes(t))
+            s += 1;
+        if (file.includes(t))
+            s += 0.5;
         return s;
     }, 0);
 }
-
 // ── Tool Definitions ──────────────────────────────────────────────────────────
-
+/**
+ * Build or rebuild the knowledge graph for a directory.
+ */
 export const graphifyBuildTool = {
     name: 'graphify_build',
     description: 'Build (or rebuild) the knowledge graph for a project directory. ' +
@@ -100,8 +114,15 @@ export const graphifyBuildTool = {
     inputSchema: {
         type: 'object',
         properties: {
-            path: { type: 'string', description: 'Path to analyse (defaults to current project root)' },
-            codeOnly: { type: 'boolean', description: 'Only re-extract changed code files — fast rebuild', default: false },
+            path: {
+                type: 'string',
+                description: 'Path to analyse (defaults to current project root)',
+            },
+            codeOnly: {
+                type: 'boolean',
+                description: 'Only re-extract changed code files — no LLM, fast rebuild',
+                default: false,
+            },
         },
     },
     handler: async (params) => {
@@ -122,16 +143,19 @@ export const graphifyBuildTool = {
                 edges: result.analysis.stats.edges,
                 message: `Knowledge graph built at ${result.graphPath}`,
             };
-        } catch (err) {
+        }
+        catch (err) {
             return {
                 error: true,
                 message: String(err),
-                hint: '@monoes/graph package not available — ensure it is installed and built.',
+                hint: '@monobrain/graph package not available — ensure it is installed and built.',
             };
         }
     },
 };
-
+/**
+ * Query the knowledge graph with natural language.
+ */
 export const graphifyQueryTool = {
     name: 'graphify_query',
     description: 'Search the knowledge graph with a natural language question or keywords. ' +
@@ -143,29 +167,52 @@ export const graphifyQueryTool = {
     inputSchema: {
         type: 'object',
         properties: {
-            question: { type: 'string', description: 'Natural language question or keyword' },
-            mode: { type: 'string', enum: ['bfs', 'dfs'], default: 'bfs' },
-            depth: { type: 'integer', default: 3 },
-            tokenBudget: { type: 'integer', default: 2000 },
+            question: {
+                type: 'string',
+                description: 'Natural language question or keyword (e.g. "authentication flow", "how does caching work")',
+            },
+            mode: {
+                type: 'string',
+                enum: ['bfs', 'dfs'],
+                default: 'bfs',
+                description: 'bfs = broad context, dfs = trace specific path',
+            },
+            depth: {
+                type: 'integer',
+                default: 3,
+                description: 'Traversal depth (1–6)',
+            },
+            tokenBudget: {
+                type: 'integer',
+                default: 2000,
+                description: 'Approximate max output tokens',
+            },
         },
         required: ['question'],
     },
     handler: async (params) => {
         const cwd = getProjectCwd();
-        if (!graphExists(cwd)) return { error: true, message: 'No graph found. Run graphify_build first.', hint: `Expected: ${getGraphPath(cwd)}` };
+        if (!graphExists(cwd)) {
+            return {
+                error: true,
+                message: 'No graph found. Run graphify_build first.',
+                hint: `Expected: ${getGraphPath(cwd)}`,
+            };
+        }
         const question = params.question;
         const mode = params.mode || 'bfs';
         const depth = params.depth || 3;
         try {
             const g = await loadKnowledgeGraph(cwd);
             const terms = question.toLowerCase().split(/\s+/).filter(t => t.length > 2);
-
+            // Score nodes; fall back to highest-degree nodes if no match
             let startNodes = [];
             if (terms.length > 0) {
                 const scored = [];
                 for (const id of g.nodes.keys()) {
                     const s = scoreNode(g, id, terms);
-                    if (s > 0) scored.push([s, id]);
+                    if (s > 0)
+                        scored.push([s, id]);
                 }
                 scored.sort((a, b) => b[0] - a[0]);
                 startNodes = scored.slice(0, 5).map(([, id]) => id);
@@ -175,10 +222,8 @@ export const graphifyQueryTool = {
                     .sort((a, b) => (g.degree.get(b) ?? 0) - (g.degree.get(a) ?? 0))
                     .slice(0, 3);
             }
-
             const visited = new Set(startNodes);
             const edgesSeen = [];
-
             if (mode === 'bfs') {
                 let frontier = new Set(startNodes);
                 for (let d = 0; d < depth; d++) {
@@ -191,15 +236,20 @@ export const graphifyQueryTool = {
                             }
                         }
                     }
-                    for (const n of next) visited.add(n);
+                    for (const n of next)
+                        visited.add(n);
                     frontier = next;
                 }
-            } else {
+            }
+            else {
+                // DFS
                 const stack = startNodes.map(n => [n, 0]);
                 while (stack.length > 0) {
                     const [node, d] = stack.pop();
-                    if (visited.has(node) && d > 0) continue;
-                    if (d > depth) continue;
+                    if (visited.has(node) && d > 0)
+                        continue;
+                    if (d > depth)
+                        continue;
                     visited.add(node);
                     for (const nbr of g.adj.get(node) ?? []) {
                         if (!visited.has(nbr)) {
@@ -209,33 +259,45 @@ export const graphifyQueryTool = {
                     }
                 }
             }
-
             const nodesOut = [...visited]
                 .sort((a, b) => (g.degree.get(b) ?? 0) - (g.degree.get(a) ?? 0))
                 .slice(0, 60)
                 .map(id => nodeOut(g, id));
-
+            // Build edge lookup for attribute access
             const edgeLookup = new Map();
-            for (const e of g.edges) edgeLookup.set(`${e.source}__${e.target}`, e);
-
+            for (const e of g.edges) {
+                edgeLookup.set(`${e.source}__${e.target}`, e);
+            }
             const edgesOut = edgesSeen
                 .filter(([u, v]) => visited.has(u) && visited.has(v))
                 .slice(0, 80)
                 .map(([u, v]) => {
-                    const e = edgeLookup.get(`${u}__${v}`) ?? {};
-                    return {
-                        from: g.nodes.get(u)?.label ?? u,
-                        to: g.nodes.get(v)?.label ?? v,
-                        relation: e.relation ?? '',
-                        confidence: e.confidence ?? '',
-                    };
-                });
-
-            return { question, mode, depth, nodes: nodesOut, edges: edgesOut, total_nodes: visited.size, total_edges: edgesSeen.length };
-        } catch (err) { return { error: true, message: String(err) }; }
+                const e = edgeLookup.get(`${u}__${v}`) ?? {};
+                return {
+                    from: (g.nodes.get(u)?.label ?? u),
+                    to: (g.nodes.get(v)?.label ?? v),
+                    relation: e.relation ?? '',
+                    confidence: e.confidence ?? '',
+                };
+            });
+            return {
+                question,
+                mode,
+                depth,
+                nodes: nodesOut,
+                edges: edgesOut,
+                total_nodes: visited.size,
+                total_edges: edgesSeen.length,
+            };
+        }
+        catch (err) {
+            return { error: true, message: String(err) };
+        }
     },
 };
-
+/**
+ * Get the most connected (god) nodes — the core abstractions.
+ */
 export const graphifyGodNodesTool = {
     name: 'graphify_god_nodes',
     description: 'Return the most connected nodes in the knowledge graph — the core abstractions ' +
@@ -243,10 +305,24 @@ export const graphifyGodNodesTool = {
         'to understand what the most important components are before diving into details.',
     category: 'graphify',
     tags: ['knowledge-graph', 'architecture', 'abstractions', 'codebase'],
-    inputSchema: { type: 'object', properties: { topN: { type: 'integer', default: 15 } } },
+    inputSchema: {
+        type: 'object',
+        properties: {
+            topN: {
+                type: 'integer',
+                default: 15,
+                description: 'Number of god nodes to return',
+            },
+        },
+    },
     handler: async (params) => {
         const cwd = getProjectCwd();
-        if (!graphExists(cwd)) return { error: true, message: 'No graph found. Run graphify_build first.' };
+        if (!graphExists(cwd)) {
+            return {
+                error: true,
+                message: 'No graph found. Run graphify_build first.',
+            };
+        }
         const topN = params.topN || 15;
         try {
             const g = await loadKnowledgeGraph(cwd);
@@ -255,7 +331,9 @@ export const graphifyGodNodesTool = {
                 .slice(0, topN);
             const godNodes = sortedIds.map(id => {
                 const d = g.nodes.get(id) ?? { id };
-                const neighbors = (g.adj.get(id) ?? []).slice(0, 8).map(nid => g.nodes.get(nid)?.label ?? nid);
+                const neighbors = (g.adj.get(id) ?? [])
+                    .slice(0, 8)
+                    .map(nid => g.nodes.get(nid)?.label ?? nid);
                 return {
                     label: d.label ?? id,
                     degree: g.degree.get(id) ?? 0,
@@ -267,20 +345,37 @@ export const graphifyGodNodesTool = {
                 };
             });
             return { god_nodes: godNodes, total_nodes: g.nodes.size };
-        } catch (err) { return { error: true, message: String(err) }; }
+        }
+        catch (err) {
+            return { error: true, message: String(err) };
+        }
     },
 };
-
+/**
+ * Get full details for a specific node.
+ */
 export const graphifyGetNodeTool = {
     name: 'graphify_get_node',
     description: 'Get all details for a specific concept/node in the knowledge graph: ' +
-        'its source location, community, all relationships, and confidence levels.',
+        'its source location, community, all relationships, and confidence levels. ' +
+        'Use this when you need to deeply understand one specific component.',
     category: 'graphify',
     tags: ['knowledge-graph', 'node', 'details'],
-    inputSchema: { type: 'object', properties: { label: { type: 'string', description: 'Node label or ID (case-insensitive)' } }, required: ['label'] },
+    inputSchema: {
+        type: 'object',
+        properties: {
+            label: {
+                type: 'string',
+                description: 'Node label or ID to look up (case-insensitive)',
+            },
+        },
+        required: ['label'],
+    },
     handler: async (params) => {
         const cwd = getProjectCwd();
-        if (!graphExists(cwd)) return { error: true, message: 'No graph found. Run graphify_build first.' };
+        if (!graphExists(cwd)) {
+            return { error: true, message: 'No graph found. Run graphify_build first.' };
+        }
         try {
             const g = await loadKnowledgeGraph(cwd);
             const term = params.label.toLowerCase();
@@ -288,23 +383,41 @@ export const graphifyGetNodeTool = {
                 .filter(([id, d]) => (d.label ?? id).toLowerCase().includes(term) || id.toLowerCase() === term)
                 .sort(([aId], [bId]) => (g.degree.get(bId) ?? 0) - (g.degree.get(aId) ?? 0))
                 .map(([id]) => id);
-            if (matches.length === 0) return { error: 'Node not found', searched: term };
+            if (matches.length === 0) {
+                return { error: 'Node not found', searched: term };
+            }
             const id = matches[0];
             const d = g.nodes.get(id) ?? { id };
+            // Build edge lookup
             const edgeLookup = new Map();
-            for (const e of g.edges) edgeLookup.set(`${e.source}__${e.target}`, e);
+            for (const e of g.edges) {
+                edgeLookup.set(`${e.source}__${e.target}`, e);
+            }
             const outEdges = (g.adj.get(id) ?? []).slice(0, 40).map(tgt => {
                 const e = edgeLookup.get(`${id}__${tgt}`) ?? {};
-                return { direction: 'outgoing', to: g.nodes.get(tgt)?.label ?? tgt, relation: e.relation ?? '', confidence: e.confidence ?? '', confidence_score: e.confidence_score ?? null };
+                return {
+                    direction: 'outgoing',
+                    to: g.nodes.get(tgt)?.label ?? tgt,
+                    relation: e.relation ?? '',
+                    confidence: e.confidence ?? '',
+                    confidence_score: e.confidence_score ?? null,
+                };
             });
             const inEdges = (g.radj.get(id) ?? []).slice(0, 40).map(src => {
                 const e = edgeLookup.get(`${src}__${id}`) ?? {};
-                return { direction: 'incoming', from: g.nodes.get(src)?.label ?? src, relation: e.relation ?? '', confidence: e.confidence ?? '' };
+                return {
+                    direction: 'incoming',
+                    from: g.nodes.get(src)?.label ?? src,
+                    relation: e.relation ?? '',
+                    confidence: e.confidence ?? '',
+                };
             });
+            // Strip well-known fields from attributes output to avoid duplication
             const knownKeys = new Set(['label', 'source_file', 'source_location', 'community', 'file_type', 'id']);
             const attributes = {};
             for (const [k, v] of Object.entries(d)) {
-                if (!knownKeys.has(k)) attributes[k] = v;
+                if (!knownKeys.has(k))
+                    attributes[k] = v;
             }
             return {
                 id,
@@ -318,14 +431,20 @@ export const graphifyGetNodeTool = {
                 edges: [...outEdges, ...inEdges],
                 all_matches: matches.slice(0, 10).map(m => g.nodes.get(m)?.label ?? m),
             };
-        } catch (err) { return { error: true, message: String(err) }; }
+        }
+        catch (err) {
+            return { error: true, message: String(err) };
+        }
     },
 };
-
+/**
+ * Find shortest path between two concepts.
+ */
 export const graphifyShortestPathTool = {
     name: 'graphify_shortest_path',
     description: 'Find the shortest relationship path between two concepts in the knowledge graph. ' +
-        'Reveals coupling chains between any two components.',
+        'Use this to trace how component A depends on or relates to component B, ' +
+        'revealing hidden coupling chains (e.g. "how does the router connect to the database?").',
     category: 'graphify',
     tags: ['knowledge-graph', 'path', 'dependencies', 'coupling'],
     inputSchema: {
@@ -333,17 +452,19 @@ export const graphifyShortestPathTool = {
         properties: {
             source: { type: 'string', description: 'Source concept label' },
             target: { type: 'string', description: 'Target concept label' },
-            maxHops: { type: 'integer', default: 8 },
+            maxHops: { type: 'integer', default: 8, description: 'Maximum hops to search' },
         },
         required: ['source', 'target'],
     },
     handler: async (params) => {
         const cwd = getProjectCwd();
-        if (!graphExists(cwd)) return { error: true, message: 'No graph found. Run graphify_build first.' };
+        if (!graphExists(cwd)) {
+            return { error: true, message: 'No graph found. Run graphify_build first.' };
+        }
         try {
             const g = await loadKnowledgeGraph(cwd);
             const maxHops = params.maxHops || 8;
-
+            /** Find node ids matching a search term, sorted by degree descending. */
             function findNodes(term) {
                 const t = term.toLowerCase();
                 return [...g.nodes.entries()]
@@ -351,12 +472,15 @@ export const graphifyShortestPathTool = {
                     .sort(([aId], [bId]) => (g.degree.get(bId) ?? 0) - (g.degree.get(aId) ?? 0))
                     .map(([id]) => id);
             }
-
             const srcNodes = findNodes(params.source);
             const tgtNodes = findNodes(params.target);
-            if (!srcNodes.length) return { error: true, message: `Source not found: ${params.source}` };
-            if (!tgtNodes.length) return { error: true, message: `Target not found: ${params.target}` };
-
+            if (srcNodes.length === 0) {
+                return { error: true, message: `Source not found: ${params.source}` };
+            }
+            if (tgtNodes.length === 0) {
+                return { error: true, message: `Target not found: ${params.target}` };
+            }
+            // BFS on undirected graph (use both adj and radj as neighbours)
             function bfsPath(start, end) {
                 const prev = new Map();
                 const queue = [start];
@@ -364,42 +488,56 @@ export const graphifyShortestPathTool = {
                 while (queue.length > 0) {
                     const cur = queue.shift();
                     if (cur === end) {
+                        // Reconstruct path
                         const path = [];
                         let node = end;
-                        while (node !== undefined) { path.unshift(node); node = prev.get(node); }
+                        while (node !== undefined) {
+                            path.unshift(node);
+                            node = prev.get(node);
+                        }
                         return path.length - 1 <= maxHops ? path : null;
                     }
+                    // Treat edges as undirected
                     const nbrs = [...(g.adj.get(cur) ?? []), ...(g.radj.get(cur) ?? [])];
                     for (const nbr of nbrs) {
                         if (!visited.has(nbr)) {
                             visited.add(nbr);
                             prev.set(nbr, cur);
-                            if (queue.length < 100000) queue.push(nbr);
+                            if (queue.length < 100000)
+                                queue.push(nbr);
                         }
                     }
                 }
                 return null;
             }
-
             let bestPath = null;
             for (const src of srcNodes.slice(0, 3)) {
                 for (const tgt of tgtNodes.slice(0, 3)) {
                     const p = bfsPath(src, tgt);
-                    if (p && (!bestPath || p.length < bestPath.length)) bestPath = p;
+                    if (p && (!bestPath || p.length < bestPath.length)) {
+                        bestPath = p;
+                    }
                 }
             }
-
-            if (!bestPath) return { found: false, message: `No path within ${maxHops} hops between "${params.source}" and "${params.target}"` };
-
+            if (!bestPath) {
+                return {
+                    found: false,
+                    message: `No path within ${maxHops} hops between "${params.source}" and "${params.target}"`,
+                };
+            }
+            // Build edge lookup
             const edgeLookup = new Map();
             for (const e of g.edges) {
                 edgeLookup.set(`${e.source}__${e.target}`, e);
-                edgeLookup.set(`${e.target}__${e.source}`, e);
+                edgeLookup.set(`${e.target}__${e.source}`, e); // bidirectional lookup
             }
-
             const steps = bestPath.map((id, i) => {
                 const d = g.nodes.get(id) ?? { id };
-                const step = { label: d.label ?? id, file: d.source_file ?? '', location: d.source_location ?? '' };
+                const step = {
+                    label: d.label ?? id,
+                    file: d.source_file ?? '',
+                    location: d.source_location ?? '',
+                };
                 if (i < bestPath.length - 1) {
                     const nextId = bestPath[i + 1];
                     const e = edgeLookup.get(`${id}__${nextId}`) ?? edgeLookup.get(`${nextId}__${id}`) ?? {};
@@ -408,22 +546,38 @@ export const graphifyShortestPathTool = {
                 }
                 return step;
             });
-
             return { found: true, hops: bestPath.length - 1, path: steps };
-        } catch (err) { return { error: true, message: String(err) }; }
+        }
+        catch (err) {
+            return { error: true, message: String(err) };
+        }
     },
 };
-
+/**
+ * Get all nodes in a community (cluster of related components).
+ */
 export const graphifyGetCommunityTool = {
     name: 'graphify_community',
     description: 'Get all nodes in a specific community cluster. Communities are groups of ' +
-        'tightly related components detected by graph clustering. Use graphify_stats first to see community count.',
+        'tightly related components detected by graph clustering. Use graph_stats first to ' +
+        'see community count, then explore communities to understand subsystem boundaries.',
     category: 'graphify',
     tags: ['knowledge-graph', 'community', 'clusters', 'subsystems'],
-    inputSchema: { type: 'object', properties: { communityId: { type: 'integer', description: 'Community ID (0 = largest)' } }, required: ['communityId'] },
+    inputSchema: {
+        type: 'object',
+        properties: {
+            communityId: {
+                type: 'integer',
+                description: 'Community ID (0 = largest community)',
+            },
+        },
+        required: ['communityId'],
+    },
     handler: async (params) => {
         const cwd = getProjectCwd();
-        if (!graphExists(cwd)) return { error: true, message: 'No graph found. Run graphify_build first.' };
+        if (!graphExists(cwd)) {
+            return { error: true, message: 'No graph found. Run graphify_build first.' };
+        }
         try {
             const g = await loadKnowledgeGraph(cwd);
             const cid = params.communityId;
@@ -432,49 +586,84 @@ export const graphifyGetCommunityTool = {
                 .sort(([aId], [bId]) => (g.degree.get(bId) ?? 0) - (g.degree.get(aId) ?? 0))
                 .slice(0, 50)
                 .map(([id, d]) => ({
-                    label: d.label ?? id,
-                    file: d.source_file ?? '',
-                    location: d.source_location ?? '',
-                    degree: g.degree.get(id) ?? 0,
-                    file_type: d.file_type ?? '',
-                }));
+                label: d.label ?? id,
+                file: d.source_file ?? '',
+                location: d.source_location ?? '',
+                degree: g.degree.get(id) ?? 0,
+                file_type: d.file_type ?? '',
+            }));
+            // Build edge lookup
             const edgeLookup = new Map();
-            for (const e of g.edges) edgeLookup.set(`${e.source}__${e.target}`, e);
+            for (const e of g.edges) {
+                edgeLookup.set(`${e.source}__${e.target}`, e);
+            }
             const externalEdges = [];
             for (const [id, d] of g.nodes.entries()) {
-                if (d.community !== cid) continue;
+                if (d.community !== cid)
+                    continue;
                 for (const nbr of g.adj.get(id) ?? []) {
                     const nbrD = g.nodes.get(nbr);
                     if (nbrD?.community !== cid) {
                         const e = edgeLookup.get(`${id}__${nbr}`) ?? {};
-                        externalEdges.push({ from: d.label ?? id, to: nbrD?.label ?? nbr, to_community: nbrD?.community ?? null, relation: e.relation ?? '' });
+                        externalEdges.push({
+                            from: d.label ?? id,
+                            to: nbrD?.label ?? nbr,
+                            to_community: nbrD?.community ?? null,
+                            relation: e.relation ?? '',
+                        });
                     }
                 }
             }
-            return { community_id: cid, member_count: members.length, members, external_connections: externalEdges.slice(0, 30) };
-        } catch (err) { return { error: true, message: String(err) }; }
+            return {
+                community_id: cid,
+                member_count: members.length,
+                members,
+                external_connections: externalEdges.slice(0, 30),
+            };
+        }
+        catch (err) {
+            return { error: true, message: String(err) };
+        }
     },
 };
-
+/**
+ * Get graph statistics: node/edge counts, communities, confidence breakdown.
+ */
 export const graphifyStatsTool = {
     name: 'graphify_stats',
     description: 'Get summary statistics for the knowledge graph: node count, edge count, ' +
-        'community count, confidence breakdown, and top god nodes. Use this first to understand graph size.',
+        'community count, confidence breakdown (EXTRACTED/INFERRED/AMBIGUOUS), ' +
+        'and top god nodes. Use this first to understand graph size and structure.',
     category: 'graphify',
     tags: ['knowledge-graph', 'stats', 'overview'],
-    inputSchema: { type: 'object', properties: {} },
+    inputSchema: {
+        type: 'object',
+        properties: {},
+    },
     handler: async (_params) => {
         const cwd = getProjectCwd();
-        if (!graphExists(cwd)) return { error: true, message: 'No graph found. Run graphify_build first.', hint: `Expected: ${getGraphPath(cwd)}` };
+        if (!graphExists(cwd)) {
+            return {
+                error: true,
+                message: 'No graph found. Run graphify_build first.',
+                hint: `Expected: ${getGraphPath(cwd)}`,
+            };
+        }
         try {
             const g = await loadKnowledgeGraph(cwd);
+            // Community sizes
             const communities = new Map();
             for (const d of g.nodes.values()) {
-                if (d.community != null) communities.set(d.community, (communities.get(d.community) ?? 0) + 1);
+                if (d.community != null) {
+                    communities.set(d.community, (communities.get(d.community) ?? 0) + 1);
+                }
             }
             const communitySizes = {};
-            [...communities.entries()].sort((a, b) => b[1] - a[1]).slice(0, 10)
+            [...communities.entries()]
+                .sort((a, b) => b[1] - a[1])
+                .slice(0, 10)
                 .forEach(([cid, count]) => { communitySizes[String(cid)] = count; });
+            // Confidence and relation counts
             const confidenceCounts = {};
             const relationCounts = {};
             const fileTypeCounts = {};
@@ -489,7 +678,8 @@ export const graphifyStatsTool = {
                 fileTypeCounts[ft] = (fileTypeCounts[ft] ?? 0) + 1;
             }
             const topRelations = Object.entries(relationCounts)
-                .sort((a, b) => b[1] - a[1]).slice(0, 10)
+                .sort((a, b) => b[1] - a[1])
+                .slice(0, 10)
                 .reduce((acc, [k, v]) => { acc[k] = v; return acc; }, {});
             const topGodNodes = [...g.nodes.keys()]
                 .sort((a, b) => (g.degree.get(b) ?? 0) - (g.degree.get(a) ?? 0))
@@ -507,20 +697,37 @@ export const graphifyStatsTool = {
                 top_god_nodes: topGodNodes,
                 is_directed: true,
             };
-        } catch (err) { return { error: true, message: String(err) }; }
+        }
+        catch (err) {
+            return { error: true, message: String(err) };
+        }
     },
 };
-
+/**
+ * Find surprising cross-community connections (architectural insights).
+ */
 export const graphifySurprisesTool = {
     name: 'graphify_surprises',
-    description: 'Find surprising connections between components in different communities with strong relationships. ' +
-        'These unexpected couplings often reveal hidden dependencies or important architectural patterns.',
+    description: 'Find surprising connections between components that are in different communities ' +
+        'but have strong relationships. These unexpected couplings often reveal hidden dependencies, ' +
+        'design smells, or important architectural patterns worth understanding.',
     category: 'graphify',
     tags: ['knowledge-graph', 'architecture', 'coupling', 'surprises'],
-    inputSchema: { type: 'object', properties: { topN: { type: 'integer', default: 10 } } },
+    inputSchema: {
+        type: 'object',
+        properties: {
+            topN: {
+                type: 'integer',
+                default: 10,
+                description: 'Number of surprising connections to return',
+            },
+        },
+    },
     handler: async (params) => {
         const cwd = getProjectCwd();
-        if (!graphExists(cwd)) return { error: true, message: 'No graph found. Run graphify_build first.' };
+        if (!graphExists(cwd)) {
+            return { error: true, message: 'No graph found. Run graphify_build first.' };
+        }
         try {
             const g = await loadKnowledgeGraph(cwd);
             const topN = params.topN || 10;
@@ -531,8 +738,9 @@ export const graphifySurprisesTool = {
                 const cu = uD?.community ?? null;
                 const cv = vD?.community ?? null;
                 if (cu != null && cv != null && cu !== cv) {
+                    const score = (g.degree.get(e.source) ?? 0) * (g.degree.get(e.target) ?? 0);
                     surprises.push({
-                        score: (g.degree.get(e.source) ?? 0) * (g.degree.get(e.target) ?? 0),
+                        score,
                         from: uD?.label ?? e.source,
                         from_community: cu,
                         from_file: uD?.source_file ?? '',
@@ -545,11 +753,271 @@ export const graphifySurprisesTool = {
                 }
             }
             surprises.sort((a, b) => b.score - a.score);
-            return { surprises: surprises.slice(0, topN), total_cross_community_edges: surprises.length };
-        } catch (err) { return { error: true, message: String(err) }; }
+            return {
+                surprises: surprises.slice(0, topN),
+                total_cross_community_edges: surprises.length,
+            };
+        }
+        catch (err) {
+            return { error: true, message: String(err) };
+        }
     },
 };
+/**
+ * Generate or open the interactive HTML visualization of the knowledge graph.
+ */
+export const graphifyVisualizeTool = {
+    name: 'graphify_visualize',
+    description: 'Generate (and optionally open) the interactive HTML knowledge graph explorer. ' +
+        'Produces graph.html alongside graph.json — a self-contained visualization with force-directed ' +
+        'layout, community coloring, god-node panel, sidebar details, minimap, and search. ' +
+        'No internet connection or server required — just open the HTML file in a browser.',
+    category: 'graphify',
+    tags: ['knowledge-graph', 'visualization', 'html', 'browser'],
+    inputSchema: {
+        type: 'object',
+        properties: {
+            open: {
+                type: 'boolean',
+                description: 'Open the HTML file in the default browser after generating (macOS/Linux)',
+                default: false,
+            },
+            path: {
+                type: 'string',
+                description: 'Project path (defaults to current project root)',
+            },
+        },
+    },
+    handler: async (params) => {
+        const cwd = getProjectCwd();
+        const targetPath = params.path || cwd;
+        if (!graphExists(targetPath)) {
+            return {
+                error: true,
+                message: 'No graph found. Run graphify_build first.',
+                hint: `Expected: ${getGraphPath(targetPath)}`,
+            };
+        }
+        try {
+            const graphPath = getGraphPath(targetPath);
+            const { readFileSync } = await import('fs');
+            const { join, dirname } = await import('path');
+            const outputDir = dirname(graphPath);
+            const { exportHTML } = await import('@monoes/graph');
+            const raw = JSON.parse(readFileSync(graphPath, 'utf-8'));
+            const htmlPath = exportHTML(raw, outputDir);
+            if (params.open) {
+                const { spawn } = await import('child_process');
+                const opener = process.platform === 'darwin' ? 'open'
+                    : process.platform === 'win32' ? 'start' : 'xdg-open';
+                spawn(opener, [htmlPath], { detached: true, stdio: 'ignore' }).unref();
+            }
+            return {
+                success: true,
+                htmlPath,
+                message: `Interactive visualization generated at ${htmlPath}`,
+                hint: params.open ? 'Opening in browser…' : `Open in browser: open "${htmlPath}"`,
+            };
+        }
+        catch (err) {
+            return { error: true, message: String(err) };
+        }
+    },
+};
+// ── Watch PID helpers ─────────────────────────────────────────────────────────
+function getPidPath(cwd) {
+    return resolve(join(cwd, '.monobrain', 'graph', 'watch.pid'));
+}
+function readWatchPid(cwd) {
+    const pidPath = getPidPath(cwd);
+    if (!existsSync(pidPath))
+        return null;
+    try {
+        const pid = parseInt(readFileSync(pidPath, 'utf-8').trim(), 10);
+        return isNaN(pid) ? null : pid;
+    }
+    catch {
+        return null;
+    }
+}
+function isProcessRunning(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+// ── Watch tools ───────────────────────────────────────────────────────────────
+export const graphifyWatchTool = {
+    name: 'graphify_watch',
+    description: 'Start a background file watcher that automatically rebuilds the knowledge graph ' +
+        '(graph.json + graph.html) whenever source files change. Uses a 2-second debounce ' +
+        'so rapid saves do not trigger repeated rebuilds. The watcher runs as a detached ' +
+        'background process — call graphify_watch_stop to stop it.',
+    category: 'graphify',
+    tags: ['knowledge-graph', 'watch', 'auto-rebuild'],
+    inputSchema: {
+        type: 'object',
+        properties: {
+            path: {
+                type: 'string',
+                description: 'Project root to watch (defaults to current project root)',
+            },
+            debounce: {
+                type: 'number',
+                description: 'Debounce delay in milliseconds (default 2000)',
+                default: 2000,
+            },
+            extensions: {
+                type: 'string',
+                description: 'Comma-separated list of file extensions to watch (default: ts,js,tsx,jsx,py,go,rs,java,cs,rb,cpp,c)',
+                default: 'ts,js,tsx,jsx,py,go,rs,java,cs,rb,cpp,c',
+            },
+        },
+    },
+    handler: async (params) => {
+        const cwd = getProjectCwd();
+        const targetPath = params.path || cwd;
+        const debounceMs = params.debounce || 2000;
+        const extensions = ((params.extensions) || 'ts,js,tsx,jsx,py,go,rs,java,cs,rb,cpp,c')
+            .split(',')
+            .map((e) => e.trim())
+            .filter(Boolean);
+        // Check if already running
+        const existingPid = readWatchPid(targetPath);
+        if (existingPid !== null && isProcessRunning(existingPid)) {
+            return {
+                success: false,
+                message: `Watcher already running (PID ${existingPid})`,
+                hint: 'Call graphify_watch_stop first to restart.',
+            };
+        }
+        const pidPath = getPidPath(targetPath);
+        const outputDir = resolve(join(targetPath, '.monobrain', 'graph'));
+        const watcherScript = `
+import { watch } from 'chokidar';
+import { writeFileSync, mkdirSync } from 'fs';
+
+const TARGET = ${JSON.stringify(targetPath)};
+const OUTPUT_DIR = ${JSON.stringify(outputDir)};
+const PID_PATH = ${JSON.stringify(pidPath)};
+const DEBOUNCE_MS = ${debounceMs};
+const EXTS = new Set(${JSON.stringify(extensions)});
+const IGNORE = [/node_modules/, /\\.git/, /\\.monobrain/, /dist[\\/]/, /\\.next/, /\\.turbo/, /coverage/];
+
+mkdirSync(OUTPUT_DIR, { recursive: true });
+writeFileSync(PID_PATH, String(process.pid));
+console.log('[graphify-watch] PID', process.pid, '— watching', TARGET);
+
+let timer = null;
+
+async function rebuild() {
+  const start = Date.now();
+  console.log('[graphify-watch] Change detected — rebuilding graph…');
+  try {
+    const { buildGraph } = await import('@monoes/graph');
+    const { exportHTML } = await import('@monoes/graph');
+    const { graph: serialized } = await buildGraph(TARGET, { outputDir: OUTPUT_DIR });
+    exportHTML(serialized, OUTPUT_DIR);
+    console.log('[graphify-watch] Done in', Date.now() - start, 'ms');
+  } catch (err) {
+    console.error('[graphify-watch] Build error:', err.message ?? err);
+  }
+}
+
+const watcher = watch(TARGET, {
+  ignored: (p) => IGNORE.some((r) => r.test(p)),
+  persistent: true,
+  ignoreInitial: true,
+  awaitWriteFinish: { stabilityThreshold: 300, pollInterval: 100 },
+});
 
+watcher.on('all', (event, filePath) => {
+  const ext = filePath.split('.').pop() ?? '';
+  if (!EXTS.has(ext)) return;
+  if (timer) clearTimeout(timer);
+  timer = setTimeout(rebuild, DEBOUNCE_MS);
+});
+
+watcher.on('error', (err) => console.error('[graphify-watch] Watcher error:', err));
+process.on('SIGINT', () => process.exit(0));
+process.on('SIGTERM', () => process.exit(0));
+`;
+        try {
+            const { spawn } = await import('child_process');
+            const { writeFileSync, mkdirSync } = await import('fs');
+            mkdirSync(outputDir, { recursive: true });
+            const scriptPath = resolve(join(outputDir, '_watcher.mjs'));
+            writeFileSync(scriptPath, watcherScript);
+            const child = spawn(process.execPath, [scriptPath], {
+                detached: true,
+                stdio: 'ignore',
+                env: { ...process.env },
+            });
+            child.unref();
+            await new Promise((r) => setTimeout(r, 500));
+            const pid = readWatchPid(targetPath) ?? child.pid;
+            return {
+                success: true,
+                pid,
+                watching: targetPath,
+                debounceMs,
+                extensions,
+                message: `Graph watcher started (PID ${pid}). graph.json + graph.html will rebuild on file changes.`,
+                hint: 'Call graphify_watch_stop to stop.',
+            };
+        }
+        catch (err) {
+            return { error: true, message: String(err) };
+        }
+    },
+};
+export const graphifyWatchStopTool = {
+    name: 'graphify_watch_stop',
+    description: 'Stop the background file watcher started by graphify_watch.',
+    category: 'graphify',
+    tags: ['knowledge-graph', 'watch'],
+    inputSchema: {
+        type: 'object',
+        properties: {
+            path: {
+                type: 'string',
+                description: 'Project root (defaults to current project root)',
+            },
+        },
+    },
+    handler: async (params) => {
+        const cwd = getProjectCwd();
+        const targetPath = params.path || cwd;
+        const pid = readWatchPid(targetPath);
+        if (pid === null) {
+            return { success: false, message: 'No watcher PID found — watcher may not be running.' };
+        }
+        if (!isProcessRunning(pid)) {
+            try {
+                const { unlinkSync } = await import('fs');
+                unlinkSync(getPidPath(targetPath));
+            }
+            catch { /* ignore */ }
+            return { success: false, message: `Process ${pid} is not running (stale PID cleaned up).` };
+        }
+        try {
+            process.kill(pid, 'SIGTERM');
+            try {
+                const { unlinkSync } = await import('fs');
+                unlinkSync(getPidPath(targetPath));
+            }
+            catch { /* ignore */ }
+            return { success: true, message: `Watcher (PID ${pid}) stopped.` };
+        }
+        catch (err) {
+            return { error: true, message: `Failed to stop PID ${pid}: ${String(err)}` };
+        }
+    },
+};
+// ── Exports ───────────────────────────────────────────────────────────────────
 export const graphifyTools = [
     graphifyBuildTool,
     graphifyQueryTool,
@@ -559,6 +1027,9 @@ export const graphifyTools = [
     graphifyGetCommunityTool,
     graphifyStatsTool,
     graphifySurprisesTool,
+    graphifyVisualizeTool,
+    graphifyWatchTool,
+    graphifyWatchStopTool,
 ];
-
 export default graphifyTools;
+//# sourceMappingURL=graphify-tools.js.map