@monoes/monomindcli 1.12.0 → 1.14.0

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

@@ -22,6 +22,7 @@ const monographBuildTool = {
             path: { type: 'string', description: 'Absolute path to the repo (defaults to project cwd)' },
             codeOnly: { type: 'boolean', description: 'Only index code files (skip docs, config)' },
             force: { type: 'boolean', description: 'Force full rebuild even if index is fresh' },
+            incremental: { type: 'boolean', description: 'Skip rebuild when index already matches HEAD (default false). Use when you want a no-op if the graph is fresh.' },
         },
     },
     handler: async (input) => {
@@ -31,9 +32,12 @@ const monographBuildTool = {
         await buildAsync(repoPath, {
             codeOnly: input.codeOnly ?? false,
             force: input.force ?? false,
+            incremental: input.incremental ?? false,
             onProgress: (p) => { progressLog += `[${p.phase}] ${p.message ?? ''}\n`; },
         });
-        return text(`Monograph build complete for ${repoPath}\n${progressLog}`);
+        const skipped = progressLog.includes('skipping rebuild');
+        const summary = skipped ? `Index was already fresh — no rebuild needed for ${repoPath}` : `Monograph build complete for ${repoPath}`;
+        return text(`${summary}\n${progressLog}`);
     },
 };
 // ── monograph_query ───────────────────────────────────────────────────────────
@@ -73,13 +77,19 @@ const monographQueryTool = {
                 const results = await hybridQuery(db, query, { limit, label });
                 if (results.length === 0)
                     return text('No results found.');
-                const lines = results.map(r => `[${r.label ?? '?'}] ${r.name ?? r.id}  ${r.filePath ?? ''}  (score: ${r.score.toFixed(4)})`);
+                const lines = results.map(r => {
+                    const loc = r.filePath ? (r.startLine != null ? `${r.filePath}:${r.startLine}` : r.filePath) : '';
+                    return `[${r.label ?? '?'}] ${r.name ?? r.id}  ${loc}  (score: ${r.score.toFixed(4)})`;
+                });
                 return text(lines.join('\n'));
             }
             const results = ftsSearch(db, query, limit, label);
             if (results.length === 0)
                 return text('No results found.');
-            const lines = results.map(r => `[${r.label}] ${r.name}  ${r.filePath ?? ''}  (score: ${r.rank.toFixed(3)})`);
+            const lines = results.map(r => {
+                const loc = r.filePath ? (r.startLine != null ? `${r.filePath}:${r.startLine}` : r.filePath) : '';
+                return `[${r.label}] ${r.name}  ${loc}  (score: ${r.rank.toFixed(3)})`;
+            });
             return text(lines.join('\n'));
         }
         finally {
@@ -117,7 +127,9 @@ const monographHealthTool = {
         const { execSync } = await import('child_process');
         const db = openDb(getDbPath());
         try {
-            const meta = db.prepare("SELECT value FROM index_meta WHERE key = 'lastCommit'").get();
+            // The orchestrator writes the key as 'last_commit_hash' (orchestrator.ts:68).
+            // Fall back to legacy 'lastCommit' for indexes built with older versions.
+            const meta = db.prepare("SELECT value FROM index_meta WHERE key = 'last_commit_hash'").get() ?? db.prepare("SELECT value FROM index_meta WHERE key = 'lastCommit'").get();
             const lastCommit = meta?.value ?? null;
             if (!lastCommit)
                 return text('Index has never been built. Run monograph_build first.');
@@ -162,7 +174,7 @@ const monographGodNodesTool = {
                 : 20;
             const excluded = ['File', 'Folder', 'Community', 'Concept'];
             const rows = db.prepare(`
-        SELECT n.id, n.label, n.name, n.file_path,
+        SELECT n.id, n.label, n.name, n.file_path, n.start_line,
                COUNT(DISTINCT e1.id) + COUNT(DISTINCT e2.id) AS degree,
                COUNT(DISTINCT e2.id) AS in_degree,
                COUNT(DISTINCT e1.id) AS out_degree
@@ -175,7 +187,10 @@ const monographGodNodesTool = {
       `).all(...excluded, limit);
             if (rows.length === 0)
                 return text('No god nodes found. Run monograph_build first.');
-            const lines = rows.map(r => `[${r.label}] ${r.name}  degree=${r.degree} (↑${r.out_degree} ↓${r.in_degree})  ${r.file_path ?? ''}`);
+            const lines = rows.map(r => {
+                const loc = r.file_path ? (r.start_line != null ? `${r.file_path}:${r.start_line}` : r.file_path) : '';
+                return `[${r.label}] ${r.name}  degree=${r.degree} (↑${r.out_degree} ↓${r.in_degree})  ${loc}`;
+            });
             return text(lines.join('\n'));
         }
         finally {
@@ -233,7 +248,15 @@ const monographShortestPathTool = {
             const path = getShortestPath(db, input.source, input.target, input.maxDepth ?? 6);
             if (!path)
                 return text(`No path found between ${input.source} and ${input.target}`);
-            return text(`Path (${path.length - 1} hops):\n${path.join(' → ')}`);
+            // Enrich each node ID with file:line for direct LLM navigation
+            const enriched = path.map(nodeId => {
+                const row = db.prepare('SELECT label, name, file_path, start_line FROM nodes WHERE id = ? OR name = ? LIMIT 1').get(nodeId, nodeId);
+                if (!row)
+                    return nodeId;
+                const loc = row.file_path ? (row.start_line != null ? `${row.file_path}:${row.start_line}` : row.file_path) : '';
+                return loc ? `${row.name ?? nodeId}  [${loc}]` : (row.name ?? nodeId);
+            });
+            return text(`Path (${path.length - 1} hops):\n${enriched.join(' → ')}`);
         }
         finally {
             closeDb(db);
@@ -263,10 +286,13 @@ const monographCommunityTool = {
         const { openDb, closeDb } = await import('@monoes/monograph');
         const db = openDb(getDbPath());
         try {
-            const rows = db.prepare('SELECT * FROM nodes WHERE community_id = ?').all(communityId);
+            const rows = db.prepare('SELECT id, label, name, file_path, start_line FROM nodes WHERE community_id = ?').all(communityId);
             if (rows.length === 0)
                 return text(`No nodes in community ${communityId}`);
-            return text(rows.map(r => `[${r.label}] ${r.name}  ${r.file_path ?? ''}`).join('\n'));
+            return text(rows.map(r => {
+                const loc = r.file_path ? (r.start_line != null ? `${r.file_path}:${r.start_line}` : r.file_path) : '';
+                return `[${r.label}] ${r.name}  ${loc}`;
+            }).join('\n'));
         }
         finally {
             closeDb(db);
@@ -292,7 +318,9 @@ const monographSurprisesTool = {
                 ? Math.min(Math.floor(rawSurprisesLimit), MAX_SURPRISES_LIMIT)
                 : 20;
             const rows = db.prepare(`
-        SELECT e.*, n1.name as src_name, n2.name as tgt_name
+        SELECT e.confidence, e.confidence_score, e.relation,
+               n1.name as src_name, n1.file_path as src_file, n1.start_line as src_line,
+               n2.name as tgt_name, n2.file_path as tgt_file, n2.start_line as tgt_line
         FROM edges e
         JOIN nodes n1 ON n1.id = e.source_id
         JOIN nodes n2 ON n2.id = e.target_id
@@ -301,7 +329,12 @@ const monographSurprisesTool = {
       `).all(limit);
             if (rows.length === 0)
                 return text('No surprising connections found.');
-            return text(rows.map(r => `[${r.confidence}] ${r.src_name} --${r.relation}--> ${r.tgt_name} (score: ${r.confidence_score})`).join('\n'));
+            return text(rows.map(r => {
+                const srcLoc = r.src_file ? (r.src_line != null ? `${r.src_file}:${r.src_line}` : r.src_file) : '';
+                const tgtLoc = r.tgt_file ? (r.tgt_line != null ? `${r.tgt_file}:${r.tgt_line}` : r.tgt_file) : '';
+                const locHint = srcLoc || tgtLoc ? `  [${srcLoc}${tgtLoc ? ` → ${tgtLoc}` : ''}]` : '';
+                return `[${r.confidence}] ${r.src_name} --${r.relation}--> ${r.tgt_name} (score: ${r.confidence_score})${locHint}`;
+            }).join('\n'));
         }
         finally {
             closeDb(db);
@@ -336,6 +369,14 @@ const monographSuggestTool = {
             const task = typeof rawTask === 'string' && rawTask.length > MAX_SUGGEST_TASK_LEN
                 ? rawTask.slice(0, MAX_SUGGEST_TASK_LEN)
                 : rawTask;
+            // Format a suggestion row as a navigable string for LLM consumption.
+            // Includes file:line references so the LLM can jump directly to the code.
+            const formatSuggestion = (r) => {
+                const srcLoc = r.src_file ? (r.src_line != null ? `${r.src_file}:${r.src_line}` : r.src_file) : '';
+                const tgtLoc = r.tgt_file ? (r.tgt_line != null ? `${r.tgt_file}:${r.tgt_line}` : r.tgt_file) : '';
+                const locHint = srcLoc ? `  [${srcLoc}${tgtLoc ? ` → ${tgtLoc}` : ''}]` : '';
+                return `Why does ${r.src} ${r.relation.toLowerCase()} ${r.tgt}? (${r.confidence})${locHint}`;
+            };
             // When a task is provided and embeddings are enabled, use semantic search
             // to find relevant nodes and surface edge-level questions about them.
             if (task && process.env['MONOGRAPH_EMBEDDINGS'] === 'true') {
@@ -345,7 +386,9 @@ const monographSuggestTool = {
                     return text('No suggestions for this task. Run monograph_build first or try a different query.');
                 }
                 const rows = db.prepare(`
-          SELECT e.relation, e.confidence, n1.name as src, n2.name as tgt, n1.file_path as src_file
+          SELECT e.relation, e.confidence, n1.name as src, n2.name as tgt,
+                 n1.file_path as src_file, n1.start_line as src_line,
+                 n2.file_path as tgt_file, n2.start_line as tgt_line
           FROM edges e
           JOIN nodes n1 ON n1.id = e.source_id
           JOIN nodes n2 ON n2.id = e.target_id
@@ -354,11 +397,13 @@ const monographSuggestTool = {
           AND e.confidence IN ('AMBIGUOUS', 'INFERRED')
           LIMIT 100
         `).all(...[...hitIds], ...[...hitIds]);
-                const questions = rows.map(r => `Why does ${r.src} ${r.relation.toLowerCase()} ${r.tgt}? (${r.confidence})`);
+                const questions = rows.map(formatSuggestion);
                 return text(questions.slice(0, limit).join('\n') || 'No suggestions for this task. Run monograph_build first.');
             }
             const rows = db.prepare(`
-        SELECT e.relation, e.confidence, n1.name as src, n2.name as tgt, n1.file_path as src_file
+        SELECT e.relation, e.confidence, n1.name as src, n2.name as tgt,
+               n1.file_path as src_file, n1.start_line as src_line,
+               n2.file_path as tgt_file, n2.start_line as tgt_line
         FROM edges e
         JOIN nodes n1 ON n1.id = e.source_id
         JOIN nodes n2 ON n2.id = e.target_id
@@ -366,7 +411,7 @@ const monographSuggestTool = {
         LIMIT 100
       `).all();
             let scored = rows.map(r => ({
-                q: `Why does ${r.src} ${r.relation.toLowerCase()} ${r.tgt}? (${r.confidence})`,
+                q: formatSuggestion(r),
                 relevance: task ? taskRelevance(task, r.src + ' ' + r.tgt + ' ' + (r.src_file ?? '')) : 0,
             }));
             if (task)
@@ -467,7 +512,7 @@ const monographReportTool = {
             const nodeCount = countNodes(db);
             const edgeCount = countEdges(db);
             const topNodes = db.prepare(`
-        SELECT n.name, n.label, n.file_path,
+        SELECT n.name, n.label, n.file_path, n.start_line,
                COUNT(DISTINCT e1.id) + COUNT(DISTINCT e2.id) AS degree
         FROM nodes n
         LEFT JOIN edges e1 ON e1.source_id = n.id
@@ -480,7 +525,10 @@ const monographReportTool = {
                 `**Generated:** ${new Date().toISOString()}`,
                 `**Nodes:** ${nodeCount}  **Edges:** ${edgeCount}\n`,
                 '## Top 10 Most Connected Entities\n',
-                ...topNodes.map((n, i) => `${i + 1}. **${n.name}** (${n.label}) — degree ${n.degree}  \`${n.file_path ?? ''}\``),
+                ...topNodes.map((n, i) => {
+                    const loc = n.file_path ? (n.start_line != null ? `${n.file_path}:${n.start_line}` : n.file_path) : '';
+                    return `${i + 1}. **${n.name}** (${n.label}) — degree ${n.degree}${loc ? `  \`${loc}\`` : ''}`;
+                }),
             ].join('\n');
             const outPath = resolve(input.path ?? join(getProjectCwd(), '.monomind', 'GRAPH_REPORT.md'));
             const allowedRoot = resolve(getProjectCwd());
@@ -489,7 +537,7 @@ const monographReportTool = {
             }
             mkdirSync(join(outPath, '..'), { recursive: true });
             writeFileSync(outPath, report);
-            return text(`Report written to ${outPath}`);
+            return text(`${report}\n\nReport written to ${outPath}`);
         }
         finally {
             closeDb(db);
@@ -509,8 +557,24 @@ const monographStalenessTool = {
     handler: async (input) => {
         const { getMonographStaleness } = await import('@monoes/monograph');
         const repoPath = input.path ?? getProjectCwd();
-        const report = await getMonographStaleness(repoPath);
-        return text(JSON.stringify(report, null, 2));
+        const r = await getMonographStaleness(repoPath);
+        if (!r.indexedCommit && !r.currentCommit) {
+            return text('Index has never been built or repo has no git history. Run monograph_build first.');
+        }
+        const statusLine = r.isStale
+            ? `STALE — index at ${r.indexedCommit}, HEAD at ${r.currentCommit}`
+            : `FRESH — index matches HEAD (${r.currentCommit})`;
+        const lines = [`Staleness: ${statusLine}`];
+        if (r.staleSince)
+            lines.push(`Stale since: ${r.staleSince}`);
+        if (r.changedSince.length > 0) {
+            const shown = r.changedSince.slice(0, 10);
+            const more = r.changedSince.length - shown.length;
+            lines.push(`Changed files (${r.changedSince.length}):${shown.map(f => `\n  ${f}`).join('')}${more > 0 ? `\n  … ${more} more` : ''}`);
+        }
+        if (r.isStale)
+            lines.push('Action: run monograph_build to re-index');
+        return text(lines.join('\n'));
     },
 };
 // ── monograph_snapshot ────────────────────────────────────────────────────────
@@ -604,13 +668,33 @@ const monographDiffTool = {
             }
         }
         const diff = diffSnapshots(before, after);
+        const nodeById = new Map();
+        const indexNodes = (nodes) => {
+            for (const n of nodes) {
+                if (n.id)
+                    nodeById.set(n.id, n);
+            }
+        };
+        indexNodes(before.nodes);
+        indexNodes(after.nodes);
+        const resolveEdgeEnd = (id) => {
+            const ref = nodeById.get(id);
+            if (!ref)
+                return id; // fallback to raw id if not found
+            const loc = ref.filePath ? (ref.startLine != null ? `${ref.filePath}:${ref.startLine}` : ref.filePath) : '';
+            return loc ? `${ref.name}  [${loc}]` : ref.name;
+        };
         const section = (label, items) => items.length > 0 ? `\n${label} (${items.length}):\n${items.slice(0, 10).join('\n')}${items.length > 10 ? `\n  … ${items.length - 10} more` : ''}` : '';
+        const formatNode = (n) => {
+            const loc = n.filePath ? (n.startLine != null ? `${n.filePath}:${n.startLine}` : n.filePath) : '';
+            return `  [${n.label ?? '?'}] ${n.name ?? '?'}${loc ? `  ${loc}` : ''}`;
+        };
         const lines = [
             `Diff: ${diff.summary}`,
-            section('New nodes', diff.newNodes.map(n => `  + [${n.label}] ${n.name}  ${n.filePath ?? ''}`)),
-            section('Removed nodes', diff.removedNodes.map(n => `  - [${n.label}] ${n.name}  ${n.filePath ?? ''}`)),
-            section('New edges', diff.newEdges.map(e => `  + ${e.sourceId} --[${e.relation}]--> ${e.targetId}`)),
-            section('Removed edges', diff.removedEdges.map(e => `  - ${e.sourceId} --[${e.relation}]--> ${e.targetId}`)),
+            section('New nodes', diff.newNodes.map(n => `  + ${formatNode(n)}`)),
+            section('Removed nodes', diff.removedNodes.map(n => `  - ${formatNode(n)}`)),
+            section('New edges', diff.newEdges.map(e => `  + ${resolveEdgeEnd(e.sourceId)} --[${e.relation}]--> ${resolveEdgeEnd(e.targetId)}`)),
+            section('Removed edges', diff.removedEdges.map(e => `  - ${resolveEdgeEnd(e.sourceId)} --[${e.relation}]--> ${resolveEdgeEnd(e.targetId)}`)),
         ].join('');
         return text(lines);
     },
@@ -700,7 +784,38 @@ const monographContextTool = {
                 name: ctxName,
                 filePath: ctxPath,
             });
-            return text(JSON.stringify(result, null, 2));
+            if (!result || !result.node)
+                return text(`No symbol found: ${ctxName}`);
+            // Format context as structured text for direct LLM consumption
+            const n = result.node;
+            const loc = n.filePath ? (n.startLine != null ? `${n.filePath}:${n.startLine}` : n.filePath) : '';
+            const lines = [
+                `[${n.label ?? '?'}] ${n.name}  ${loc}`,
+                '',
+            ];
+            const formatNodes = (nodes, label) => {
+                if (!Array.isArray(nodes) || nodes.length === 0)
+                    return;
+                lines.push(`${label} (${nodes.length}):`);
+                for (const node of nodes.slice(0, 20)) {
+                    const fp = node.filePath ?? node.file_path ?? '';
+                    const ln = node.startLine ?? node.start_line;
+                    const nodeLoc = fp ? (ln != null ? `${fp}:${ln}` : fp) : '';
+                    lines.push(`  [${node.label ?? '?'}] ${node.name ?? node.id}  ${nodeLoc}`);
+                }
+                if (nodes.length > 20)
+                    lines.push(`  … ${nodes.length - 20} more`);
+                lines.push('');
+            };
+            formatNodes(result.callers, 'Callers');
+            formatNodes(result.callees, 'Callees');
+            formatNodes(result.imports, 'Imports');
+            formatNodes(result.importedBy, 'ImportedBy');
+            if (result.community != null)
+                lines.push(`Community: ${result.community}`);
+            if (result.communityName)
+                lines.push(`Community name: ${result.communityName}`);
+            return text(lines.join('\n').trim());
         }
         finally {
             closeDb(db);
@@ -742,7 +857,35 @@ const monographImpactTool = {
                 filePath: impactPath,
                 depth,
             });
-            return text(JSON.stringify(result, null, 2));
+            if (!result || !result.root)
+                return text(`No symbol found: ${impactName}`);
+            // Format impact as structured text for direct LLM consumption
+            const root = result.root;
+            const rootLoc = root.filePath ? (root.startLine != null ? `${root.filePath}:${root.startLine}` : root.filePath) : '';
+            const lines = [
+                `[${root.label ?? '?'}] ${root.name}  ${rootLoc}`,
+                '',
+                `Blast radius: ${result.totalAffected ?? 0} symbols affected`,
+            ];
+            if (result.riskScore != null) {
+                const riskLabel = result.riskScore >= 0.8 ? 'HIGH' : result.riskScore >= 0.5 ? 'MEDIUM' : 'LOW';
+                lines.push(`Risk score: ${result.riskScore.toFixed(2)} (${riskLabel})`);
+            }
+            lines.push('');
+            const affected = (result.affected ?? result.callers ?? []);
+            if (affected.length > 0) {
+                lines.push(`Affected callers (${affected.length}):`);
+                for (const sym of affected.slice(0, 20)) {
+                    const fp = sym.filePath ?? sym.file_path ?? '';
+                    const ln = sym.startLine ?? sym.start_line;
+                    const symLoc = fp ? (ln != null ? `${fp}:${ln}` : fp) : '';
+                    const depth_marker = sym.depth != null ? ` [depth ${sym.depth}]` : '';
+                    lines.push(`  [${sym.label ?? '?'}] ${sym.name ?? sym.id}  ${symLoc}${depth_marker}`);
+                }
+                if (affected.length > 20)
+                    lines.push(`  … ${affected.length - 20} more`);
+            }
+            return text(lines.join('\n').trim());
         }
         finally {
             closeDb(db);
@@ -769,7 +912,35 @@ const monographDetectChangesTool = {
                 baseBranch: input.baseBranch,
                 includeTests: input.includeTests,
             }, getProjectCwd());
-            return text(JSON.stringify(result, null, 2));
+            // Format as structured text for direct LLM navigation instead of raw JSON
+            const r = result;
+            if (!r || (!r.changedFiles?.length && !r.affectedSymbols?.length)) {
+                return text('No changed files found relative to the base branch.');
+            }
+            const lines = [];
+            const base = r.baseBranch ?? 'main';
+            const changedFiles = r.changedFiles ?? [];
+            lines.push(`Changed files vs ${base}: ${changedFiles.length}`);
+            if (changedFiles.length > 0) {
+                for (const f of changedFiles.slice(0, 20))
+                    lines.push(`  ${f}`);
+                if (changedFiles.length > 20)
+                    lines.push(`  … ${changedFiles.length - 20} more`);
+            }
+            lines.push('');
+            const affected = r.affectedSymbols ?? r.affected ?? [];
+            if (affected.length > 0) {
+                lines.push(`Affected symbols (${affected.length}):`);
+                for (const sym of affected.slice(0, 30)) {
+                    const fp = sym.filePath ?? sym.file_path ?? '';
+                    const ln = sym.startLine ?? sym.start_line;
+                    const loc = fp ? (ln != null ? `${fp}:${ln}` : fp) : '';
+                    lines.push(`  [${sym.label ?? '?'}] ${sym.name ?? sym.id}  ${loc}`);
+                }
+                if (affected.length > 30)
+                    lines.push(`  … ${affected.length - 30} more`);
+            }
+            return text(lines.join('\n').trim());
         }
         finally {
             closeDb(db);
@@ -801,7 +972,25 @@ const monographRenameTool = {
                 filePath: input.filePath,
                 dryRun: input.dryRun ?? true,
             });
-            return text(JSON.stringify(result, null, 2));
+            // Format as structured text for direct LLM navigation instead of raw JSON
+            const rn = result;
+            if (!rn)
+                return text(`Symbol not found: ${input.oldName}`);
+            const occurrences = rn.occurrences ?? rn.references ?? [];
+            const lines = [
+                `Rename: ${input.oldName} → ${input.newName}  (dry-run)`,
+                `Occurrences: ${occurrences.length}`,
+                '',
+            ];
+            for (const occ of occurrences.slice(0, 30)) {
+                const fp = occ.filePath ?? occ.file_path ?? '';
+                const ln = occ.line ?? occ.startLine ?? occ.start_line;
+                const loc = fp ? (ln != null ? `${fp}:${ln}` : fp) : '';
+                lines.push(`  ${loc || occ}`);
+            }
+            if (occurrences.length > 30)
+                lines.push(`  … ${occurrences.length - 30} more`);
+            return text(lines.join('\n').trim());
         }
         finally {
             closeDb(db);
@@ -830,7 +1019,17 @@ const monographRouteMapTool = {
                 method: input.method,
                 includeMiddleware: input.includeMiddleware,
             });
-            return text(JSON.stringify(result, null, 2));
+            if (result.routes.length === 0)
+                return text('No routes found. Run monograph_build first or adjust your filters.');
+            const lines = [`Routes (${result.total} total):`];
+            for (const r of result.routes) {
+                const loc = r.handlerFile
+                    ? (r.handlerLine != null ? `${r.handlerFile}:${r.handlerLine}` : r.handlerFile)
+                    : '';
+                const mw = r.middlewareChain.length > 0 ? `  middleware: ${r.middlewareChain.join(' → ')}` : '';
+                lines.push(`  ${r.method} ${r.path}${r.handlerName ? ` → ${r.handlerName}` : ''}${loc ? `  (${loc})` : ''}${mw}`);
+            }
+            return text(lines.join('\n'));
         }
         finally {
             closeDb(db);
@@ -858,7 +1057,33 @@ const monographApiImpactTool = {
                 routePath: input.routePath,
                 method: input.method,
             });
-            return text(JSON.stringify(result, null, 2));
+            if (!result.route)
+                return text(`Route not found: ${input.routePath}. Run monograph_build or check the path.`);
+            const riskLabel = result.riskScore >= 0.7 ? 'HIGH' : result.riskScore >= 0.4 ? 'MEDIUM' : 'LOW';
+            const lines = [
+                `Route: ${result.route.method} ${result.route.path}  risk=${riskLabel} (${result.riskScore.toFixed(2)})`,
+            ];
+            if (result.handler) {
+                const hLoc = result.handler.filePath
+                    ? (result.handler.startLine != null ? `${result.handler.filePath}:${result.handler.startLine}` : result.handler.filePath)
+                    : '';
+                lines.push(`Handler: ${result.handler.name}${hLoc ? `  ${hLoc}` : ''}`);
+            }
+            if (result.callees.length > 0) {
+                lines.push(`Callees (${result.callees.length}):`);
+                for (const c of result.callees.slice(0, 15)) {
+                    const loc = c.node.filePath
+                        ? (c.node.startLine != null ? `${c.node.filePath}:${c.node.startLine}` : c.node.filePath)
+                        : '';
+                    lines.push(`  ${'  '.repeat(c.depth)}→ ${c.node.name} [${c.node.label}]${loc ? `  ${loc}` : ''}`);
+                }
+                if (result.callees.length > 15)
+                    lines.push(`  … ${result.callees.length - 15} more`);
+            }
+            if (result.affectedProcesses.length > 0) {
+                lines.push(`Affected processes: ${result.affectedProcesses.map(p => p.name).join(', ')}`);
+            }
+            return text(lines.join('\n'));
         }
         finally {
             closeDb(db);
@@ -947,7 +1172,15 @@ const monographGroupListTool = {
         const { getGroupList } = await import('@monoes/monograph');
         const configPath = input.configPath ?? join(getProjectCwd(), 'group.yaml');
         const result = await getGroupList(configPath);
-        return text(JSON.stringify(result, null, 2));
+        if (!result.repos || result.repos.length === 0) {
+            return text(`Group: ${result.group?.name ?? 'unknown'}\nNo repos configured. Check ${configPath}`);
+        }
+        const lines = [`Group: ${result.group?.name ?? 'unknown'}  (${result.repos.length} repos)`];
+        for (const r of result.repos) {
+            const indexed = r.indexedAt ? r.indexedAt.slice(0, 10) : 'never';
+            lines.push(`  ${r.name}  nodes=${r.nodeCount}  indexed=${indexed}  ${r.path}`);
+        }
+        return text(lines.join('\n'));
     },
 };
 // ── monograph_group_query ─────────────────────────────────────────────────────
@@ -1000,7 +1233,12 @@ const monographWikiTool = {
         const db = openDb(getDbPath());
         try {
             const result = getWikiToolResult(db, { communityId: input.communityId });
-            return text(JSON.stringify(result, null, 2));
+            if (result.pages.length === 0) {
+                return text('No wiki pages found. Run monograph_wiki_build to generate community wiki pages.');
+            }
+            // Return pages as readable prose — content is already LLM-generated markdown.
+            const sections = result.pages.map(p => `--- Community ${p.communityId} ---\n${p.content}`);
+            return text(sections.join('\n\n'));
         }
         finally {
             closeDb(db);
@@ -1029,7 +1267,16 @@ const monographWikiBuildTool = {
                 force: input.force,
                 model: input.model,
             });
-            return text(JSON.stringify(result, null, 2));
+            if (result.error)
+                return text(`Wiki build failed: ${result.error}`);
+            const parts = [];
+            if (result.generated != null)
+                parts.push(`${result.generated} page(s) generated`);
+            if (result.skipped != null && result.skipped > 0)
+                parts.push(`${result.skipped} skipped (already exist)`);
+            if (result.errors != null && result.errors > 0)
+                parts.push(`${result.errors} error(s)`);
+            return text(`Wiki build complete: ${parts.join(', ') || 'nothing to do'}. Use monograph_wiki to read the pages.`);
         }
         finally {
             closeDb(db);
@@ -1077,7 +1324,13 @@ const monographToolMapTool = {
             const results = getToolMap(db, { tool: input.tool });
             if (results.length === 0)
                 return text('No tools found. Run monograph_build first.');
-            return text(JSON.stringify(results, null, 2));
+            const lines = results.map(r => {
+                const loc = r.handlerFile
+                    ? (r.handlerLine != null ? `${r.handlerFile}:${r.handlerLine}` : r.handlerFile)
+                    : (r.filePath ?? '');
+                return `${r.name}${r.handlerName ? ` → ${r.handlerName}` : ''}${loc ? `  (${loc})` : ''}`;
+            });
+            return text(`Tools (${results.length}):\n${lines.join('\n')}`);
         }
         finally {
             closeDb(db);
@@ -1105,7 +1358,38 @@ const monographShapeCheckTool = {
                 route: input.route,
                 file: input.file,
             });
-            return text(JSON.stringify(result, null, 2));
+            // Render as structured text so LLMs can act on it directly without parsing JSON.
+            const lines = [];
+            lines.push(`Shape check: ${result.message}`);
+            if (result.route) {
+                const handlerLoc = result.route.handlerFile
+                    ? `  Handler: ${result.route.handlerName}  [${result.route.handlerFile}]`
+                    : `  Handler: ${result.route.handlerName}`;
+                lines.push(`Route: ${result.route.method} ${result.route.path}`);
+                lines.push(handlerLoc);
+            }
+            if (result.shape.returnedKeys.length > 0) {
+                lines.push(`  Returned keys: ${result.shape.returnedKeys.join(', ')}`);
+            }
+            if (result.shape.accessedKeys.length > 0) {
+                lines.push(`  Accessed keys: ${result.shape.accessedKeys.join(', ')}`);
+            }
+            if (result.shape.mismatches.length > 0) {
+                lines.push(`  Mismatches (accessed but not returned): ${result.shape.mismatches.join(', ')}`);
+            }
+            if (result.shape.extra.length > 0) {
+                lines.push(`  Unused returned keys: ${result.shape.extra.join(', ')}`);
+            }
+            if (result.consumers.length > 0) {
+                lines.push(`  Consumers (${result.consumers.length}):`);
+                for (const c of result.consumers.slice(0, 10)) {
+                    lines.push(`    - ${c.name}  [${c.filePath}]`);
+                }
+                if (result.consumers.length > 10) {
+                    lines.push(`    … ${result.consumers.length - 10} more`);
+                }
+            }
+            return text(lines.join('\n'));
         }
         finally {
             closeDb(db);
@@ -1430,11 +1714,19 @@ const monographNeighborsTool = {
             });
             if (!result.node)
                 return text(`No node found with name: ${input.name}`);
+            const nodeFilePath = result.node.filePath ?? '';
+            const nodeStartLine = result.node.startLine ?? result.node.start_line;
+            const nodeLoc = nodeFilePath ? (nodeStartLine != null ? `${nodeFilePath}:${nodeStartLine}` : nodeFilePath) : '';
             const lines = [
-                `[${result.node.label}] ${result.node.name}  ${result.node.filePath ?? ''}`,
+                `[${result.node.label}] ${result.node.name}  ${nodeLoc}`,
                 `Neighbors: ${result.neighbors.length}`,
                 '',
-                ...result.neighbors.map(n => `  ${n.direction === 'inbound' ? '←' : '→'} [${n.node.label}] ${n.node.name}  (${n.relation})  ${n.node.filePath ?? ''}`),
+                ...result.neighbors.map(n => {
+                    const fp = n.node.filePath ?? n.node.file_path ?? '';
+                    const ln = n.node.startLine ?? n.node.start_line;
+                    const loc = fp ? (ln != null ? `${fp}:${ln}` : fp) : '';
+                    return `  ${n.direction === 'inbound' ? '←' : '→'} [${n.node.label}] ${n.node.name}  (${n.relation})  ${loc}`;
+                }),
             ];
             return text(lines.join('\n'));
         }