@shrkcrft/mcp-server 0.1.0-alpha.17 → 0.1.0-alpha.18

package/dist/tools/all-tools.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"all-tools.d.ts","sourceRoot":"","sources":["../../src/tools/all-tools.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAC;AA+UpE,eAAO,MAAM,SAAS,EAAE,SAAS,eAAe,EAyR9C,CAAC"}
+{"version":3,"file":"all-tools.d.ts","sourceRoot":"","sources":["../../src/tools/all-tools.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAC;AAkVpE,eAAO,MAAM,SAAS,EAAE,SAAS,eAAe,EA4R9C,CAAC"}

package/dist/tools/all-tools.js

@@ -46,7 +46,10 @@ import { getGraphStatusTool } from "./get-graph-status.tool.js";
 import { getGraphSearchTool } from "./get-graph-search.tool.js";
 import { getGraphContextTool } from "./get-graph-context.tool.js";
 import { getGraphImpactTool } from "./get-graph-impact.tool.js";
+import { getGraphPathTool } from "./get-graph-path.tool.js";
+import { getGraphHubsTool } from "./get-graph-hubs.tool.js";
 import { getGraphCallersTool } from "./get-graph-callers.tool.js";
+import { delegateTaskTool } from "./delegate-task.tool.js";
 import { getGraphCyclesTool } from "./get-graph-cycles.tool.js";
 import { getGraphUnresolvedTool } from "./get-graph-unresolved.tool.js";
 import { getGraphDepsTool } from "./get-graph-deps.tool.js";
@@ -227,7 +230,10 @@ export const ALL_TOOLS = Object.freeze([
     getGraphSearchTool,
     getGraphContextTool,
     getGraphImpactTool,
+    getGraphPathTool,
+    getGraphHubsTool,
     getGraphCallersTool,
+    delegateTaskTool,
     getGraphCyclesTool,
     getGraphUnresolvedTool,
     getGraphDepsTool,

package/dist/tools/code-find-usages.tool.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"code-find-usages.tool.d.ts","sourceRoot":"","sources":["../../src/tools/code-find-usages.tool.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAC;AAGpE;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,kBAAkB,EAAE,eAmGhC,CAAC"}
+{"version":3,"file":"code-find-usages.tool.d.ts","sourceRoot":"","sources":["../../src/tools/code-find-usages.tool.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAC;AAIpE;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,kBAAkB,EAAE,eAuIhC,CAAC"}

package/dist/tools/code-find-usages.tool.js

@@ -1,7 +1,8 @@
 import { existsSync } from 'node:fs';
 import * as nodePath from 'node:path';
-import { EdgeKind, GraphQueryApi, GraphStore, NodeKind } from '@shrkcrft/graph';
+import { EdgeKind, GraphQueryApi, GraphStore, NodeKind, loadGraphApiCached } from '@shrkcrft/graph';
 import { FORMAT_INPUT_PROPERTY, formatObjectArrays } from "../server/columnar-format.js";
+import { callGraphLanguageNote } from "./graph-staleness.js";
 /**
  * `code_find_usages` — structured usage finder backed by the
  * SharkCraft graph (file + symbol nodes + import/declare edges).
@@ -17,7 +18,7 @@ import { FORMAT_INPUT_PROPERTY, formatObjectArrays } from "../server/columnar-fo
  */
 export const codeFindUsagesTool = {
     name: 'code_find_usages',
-    description: 'Find structured usages of a symbol via the SharkCraft graph (file + symbol nodes). Read-only. Distinguishes definition, import-of-declaring-file, and neighbouring symbols. Pass `format:"table"` for a token-efficient columnar encoding of the definitions/importers/neighbours arrays.',
+    description: 'Find where a symbol is used (use this instead of grep). Returns the definition site and exact use sites as path:line via the SharkCraft graph, plus files that import the declaring file and neighbouring symbols. Read-only; needs `shrk graph index`. Pass `format:"table"` for a token-efficient columnar encoding.',
     inputSchema: {
         type: 'object',
         properties: {
@@ -40,12 +41,12 @@ export const codeFindUsagesTool = {
             return {
                 data: {
                     error: 'no-graph',
-                    message: 'The SharkCraft graph index has not been built yet. Build it with `shrk graph build`.',
-                    nextCommand: 'shrk graph build',
+                    message: 'The SharkCraft graph index has not been built yet. Build it with `shrk graph index`.',
+                    nextCommand: 'shrk graph index',
                 },
             };
         }
-        const api = GraphQueryApi.fromStore(ctx.cwd);
+        const api = loadGraphApiCached(ctx.cwd) ?? GraphQueryApi.fromStore(ctx.cwd);
         const matches = api.findSymbol(symbolName, { exact: true, limit: maxResults });
         if (matches.length === 0) {
             return {
@@ -62,13 +63,29 @@ export const codeFindUsagesTool = {
         const definitions = [];
         const importerSet = new Map();
         const neighbours = [];
+        const useSites = [];
         for (const sym of matches) {
             const declaringFile = declaringFileOf(api, sym.id);
             definitions.push({
                 symbolId: sym.id,
                 file: declaringFile?.path ?? null,
+                ...(sym.line ? { line: sym.line } : {}),
                 kind: String(sym.label && sym.label.length > 0 ? sym.label : sym.kind),
             });
+            // Exact use sites (path:line) from the symbol's own call/reference
+            // edges, so the agent jumps straight to where it's used rather than
+            // grepping inside each importing file.
+            for (const site of api.referenceSitesOf(sym.id)) {
+                if (!site.node.path)
+                    continue;
+                // Prune use sites whose file no longer exists — uniformly with
+                // importersOfDeclaringFile below, so the payload never lists a deleted
+                // file in one field while dropping it in another (a self-contradicting,
+                // authoritative-looking result is worse than a uniformly-stale one).
+                if (!pathExists(ctx.cwd, site.node.path))
+                    continue;
+                useSites.push({ file: site.node.path, ...(site.line ? { line: site.line } : {}) });
+            }
             if (declaringFile) {
                 for (const importer of api.importersOf(declaringFile.id)) {
                     if (!importer.path)
@@ -98,13 +115,34 @@ export const codeFindUsagesTool = {
                 }
             }
         }
+        // Result-file staleness: which surviving result files changed content
+        // since indexing (deleted ones are already pruned above). Flags a payload
+        // whose line numbers / membership may be out of date for files the agent
+        // just edited. Read-only.
+        const resultPaths = [
+            ...definitions.map((d) => d.file),
+            ...useSites.map((u) => u.file),
+            ...[...importerSet.values()].map((i) => i.file),
+        ].filter((p) => !!p);
+        const stale = api.staleFilesAmong(ctx.cwd, resultPaths);
+        // Non-TS languages have no call/reference extraction, so empty useSites must
+        // not be read as "no usages".
+        const langNote = matches[0] ? callGraphLanguageNote(api, matches[0]) : undefined;
         const data = {
             symbol: { name: symbolName, kind: matches[0]?.kind ?? 'unknown' },
             definitions,
+            useSites,
             importersOfDeclaringFile: [...importerSet.values()],
             neighbouringSymbols: neighbours.slice(0, 12),
             totalSymbolMatches: matches.length,
-            note: 'importersOfDeclaringFile = files that import the declaring file. This is a structural signal — it may include type-only imports and unused references. Pair with `shrk impact` for a tighter blast radius.',
+            note: (langNote ? langNote + ' ' : '') +
+                'useSites = exact file:line of each call/reference to the symbol (first use per file). importersOfDeclaringFile = files that import the declaring file (coarser; may include type-only/unused imports). Pair with `shrk impact` for a tighter blast radius.',
+            ...(stale.modified.length > 0
+                ? {
+                    stale: { modified: stale.modified },
+                    staleHint: 'Some result files changed since indexing — run `shrk graph index --changed` for fresh line numbers.',
+                }
+                : {}),
         };
         // `format:"table"` columnar-encodes the homogeneous object-array fields
         // (definitions, importersOfDeclaringFile, neighbouringSymbols); the scalar

package/dist/tools/delegate-task.tool.d.ts

@@ -0,0 +1,3 @@
+import type { IToolDefinition } from '../server/tool-definition.js';
+export declare const delegateTaskTool: IToolDefinition;
+//# sourceMappingURL=delegate-task.tool.d.ts.map

package/dist/tools/delegate-task.tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"delegate-task.tool.d.ts","sourceRoot":"","sources":["../../src/tools/delegate-task.tool.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAC;AAUpE,eAAO,MAAM,gBAAgB,EAAE,eA0E9B,CAAC"}

package/dist/tools/delegate-task.tool.js

@@ -0,0 +1,94 @@
+import { compressMarkdown } from '@shrkcrft/compress';
+import { loadProjectConfig } from '@shrkcrft/config';
+const READONLY_NOTE = 'Read-only. The CLI is the only write path. The worker may emit ONLY the allowed ops and touch ONLY the guardrail globs; the edit is verified deterministically and auto-reverted on failure — so it lands only if it passes the recipe verification.';
+export const delegateTaskTool = {
+    name: 'delegate_task',
+    description: 'Get a compact brief for delegating a MECHANICAL, deterministically-verifiable edit to the local-LLM worker (read-only). Returns the recipe fence — allowed ops, guardrail globs, verification — and the exact `shrk delegate run` next command. Hand the grunt edit to the local worker instead of spending your own tokens reading the whole file and writing the edit. Never writes; needs a `delegation` block in sharkcraft.config.ts.',
+    cliCommand: 'delegate',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            task: { type: 'string' },
+            recipe: { type: 'string' },
+        },
+        required: ['task', 'recipe'],
+        additionalProperties: false,
+    },
+    async handler(input, ctx) {
+        const args = input;
+        const task = (args.task ?? '').trim();
+        const recipeId = (args.recipe ?? '').trim();
+        if (!task || !recipeId) {
+            return { isError: true, error: { code: 'invalid-input', message: 'task and recipe are required' } };
+        }
+        const loaded = await loadProjectConfig(ctx.inspection.projectRoot);
+        if (!loaded.ok) {
+            return { isError: true, error: { code: 'config-error', message: loaded.error.message } };
+        }
+        const delegation = loaded.value.config.delegation;
+        if (!delegation || delegation.enabled === false) {
+            return {
+                isError: true,
+                error: {
+                    code: 'not-enabled',
+                    message: 'delegation is not enabled in sharkcraft.config.ts',
+                    details: { nextCommand: 'add a delegation { recipes: [...] } block to sharkcraft.config.ts' },
+                },
+            };
+        }
+        const recipes = delegation.recipes ?? [];
+        const recipe = recipes.find((r) => r.id === recipeId);
+        if (!recipe) {
+            return {
+                isError: true,
+                error: {
+                    code: 'not-found',
+                    message: `unknown recipe "${recipeId}". Available: ${recipes.map((r) => r.id).join(', ') || '(none)'}`,
+                    details: { available: recipes.map((r) => r.id) },
+                },
+            };
+        }
+        const provider = recipe.provider ?? delegation.provider ?? 'auto';
+        const briefMarkdown = buildBriefMarkdown(task, recipe, provider);
+        // Compress the brief body (CCR-reversible when the server store is present).
+        // Small briefs pass through unchanged via the net-loss guard.
+        const compressed = compressMarkdown(briefMarkdown, ctx.ccrStore ? { store: ctx.ccrStore, query: task } : { query: task });
+        return {
+            data: {
+                schema: 'sharkcraft.delegate-task/v1',
+                recipeId: recipe.id,
+                title: recipe.title ?? recipe.id,
+                task,
+                allowedOps: recipe.allowedOps,
+                guardrailGlobs: recipe.guardrailGlobs,
+                verificationIds: recipe.verificationIds,
+                provider,
+                riskCeiling: recipe.riskCeiling ?? null,
+                brief: compressed.compressed,
+                ...(compressed.ccrKey ? { ccrKey: compressed.ccrKey } : {}),
+                next: `shrk delegate run "${task}" --recipe ${recipe.id} --apply`,
+                note: READONLY_NOTE,
+            },
+        };
+    },
+};
+function buildBriefMarkdown(task, recipe, provider) {
+    return [
+        `# Delegate brief: ${recipe.title ?? recipe.id}`,
+        '',
+        `**Task:** ${task}`,
+        '',
+        `**Recipe:** \`${recipe.id}\``,
+        `**Allowed ops:** ${recipe.allowedOps.join(', ')}`,
+        `**Guardrail globs (the worker may ONLY touch files matching these):** ${recipe.guardrailGlobs.join(', ')}`,
+        `**Verification (must pass or the edit is reverted):** ${recipe.verificationIds.join(', ') || '(none)'}`,
+        `**Provider:** ${provider}${recipe.model ? ` (${recipe.model})` : ''}`,
+        '',
+        '## How to delegate',
+        '',
+        'The CLI is the only write path. Run the `next` command: the local worker generates the edit,',
+        'the deterministic engine verifies it against the recipe verification, and auto-reverts on failure —',
+        'so the edit lands only if it is correct. You pay for this brief and the compact result, not for',
+        'reading the whole file or writing the edit yourself.',
+    ].join('\n');
+}

package/dist/tools/deps-audit.tool.js

@@ -1,6 +1,6 @@
 import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
 import * as nodePath from 'node:path';
-import { GraphQueryApi, GraphStore, NodeKind } from '@shrkcrft/graph';
+import { GraphQueryApi, GraphStore, NodeKind, loadGraphApiCached } from '@shrkcrft/graph';
 import { FORMAT_INPUT_PROPERTY, formatObjectArrays, COLUMNAR_LEGEND } from "../server/columnar-format.js";
 import { fitArrayToBudget } from "../server/fit-array-to-budget.js";
 /**
@@ -34,11 +34,11 @@ export const depsAuditTool = {
                 data: {
                     error: 'no-graph',
                     message: 'The SharkCraft graph index is required for deps-audit.',
-                    nextCommand: 'shrk graph build',
+                    nextCommand: 'shrk graph index',
                 },
             };
         }
-        const api = GraphQueryApi.fromStore(ctx.cwd);
+        const api = loadGraphApiCached(ctx.cwd) ?? GraphQueryApi.fromStore(ctx.cwd);
         const packages = listWorkspacePackages(ctx.cwd, onlyPackage);
         const reports = packages.map((p) => buildPackageReport(api, ctx.cwd, p));
         const totals = reports.reduce((acc, r) => {

package/dist/tools/get-graph-callers.tool.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"get-graph-callers.tool.d.ts","sourceRoot":"","sources":["../../src/tools/get-graph-callers.tool.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAC;AAUpE,eAAO,MAAM,mBAAmB,EAAE,eA0DjC,CAAC"}
+{"version":3,"file":"get-graph-callers.tool.d.ts","sourceRoot":"","sources":["../../src/tools/get-graph-callers.tool.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAC;AAWpE,eAAO,MAAM,mBAAmB,EAAE,eAsEjC,CAAC"}

package/dist/tools/get-graph-callers.tool.js

@@ -1,9 +1,10 @@
-import { GraphQueryApi, GraphStore } from '@shrkcrft/graph';
+import { GraphQueryApi, GraphStore, loadGraphApiCached } from '@shrkcrft/graph';
 import { FORMAT_INPUT_PROPERTY, formatObjectArrays } from "../server/columnar-format.js";
+import { callGraphLanguageNote, graphResultStaleness } from "./graph-staleness.js";
 const NEXT = 'shrk graph index';
 export const getGraphCallersTool = {
     name: 'get_graph_callers',
-    description: 'Return files that call or reference the given symbol. Mode "call" → calls-symbol edges; mode "reference" → both references-symbol and calls-symbol. Read-only.',
+    description: 'Find who calls/references a symbol (use this instead of grep before changing a function/type). Returns each caller as path:line of the first call site. Mode "call" → calls-symbol edges; mode "reference" → both references-symbol and calls-symbol. Read-only; needs `shrk graph index`.',
     cliCommand: 'graph callers',
     inputSchema: {
         type: 'object',
@@ -36,7 +37,7 @@ export const getGraphCallersTool = {
                 },
             };
         }
-        const api = GraphQueryApi.fromStore(ctx.inspection.projectRoot);
+        const api = loadGraphApiCached(ctx.inspection.projectRoot) ?? GraphQueryApi.fromStore(ctx.inspection.projectRoot);
         const sym = resolveSymbol(api, target);
         if (!sym) {
             return {
@@ -48,13 +49,25 @@ export const getGraphCallersTool = {
                 },
             };
         }
-        const hits = mode === 'reference' ? api.referencesOf(sym.id) : api.callersOf(sym.id);
+        const cwd = ctx.inspection.projectRoot;
+        const sites = mode === 'reference' ? api.referenceSitesOf(sym.id) : api.callerSitesOf(sym.id);
+        // Targeted staleness over the result files: drop callers whose file was
+        // deleted on disk, flag those whose content changed since indexing — so a
+        // stale index never silently serves a wrong/dead caller. Read-only.
+        const fresh = graphResultStaleness(api, cwd, [sym.path, ...sites.map((s) => s.node.path)]);
+        const live = sites.filter((s) => !s.node.path || !fresh.deletedSet.has(s.node.path));
+        const note = callGraphLanguageNote(api, sym);
         const data = {
             schema: 'sharkcraft.graph-callers/v1',
             symbol: summarise(sym),
             mode,
-            total: hits.length,
-            callers: hits.slice(0, 200).map(summarise),
+            total: live.length,
+            callers: live.slice(0, 200).map((s) => ({
+                ...summarise(s.node),
+                ...(s.line ? { line: s.line } : {}),
+            })),
+            ...(note ? { note } : {}),
+            ...(fresh.field ?? {}),
         };
         return { data: formatObjectArrays(data, input) };
     },

package/dist/tools/get-graph-context.tool.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"get-graph-context.tool.d.ts","sourceRoot":"","sources":["../../src/tools/get-graph-context.tool.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAC;AASpE,eAAO,MAAM,mBAAmB,EAAE,eAgEjC,CAAC"}
+{"version":3,"file":"get-graph-context.tool.d.ts","sourceRoot":"","sources":["../../src/tools/get-graph-context.tool.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAC;AAUpE,eAAO,MAAM,mBAAmB,EAAE,eAsGjC,CAAC"}

package/dist/tools/get-graph-context.tool.js

@@ -1,5 +1,6 @@
-import { GraphQueryApi, GraphStore, NodeKind, } from '@shrkcrft/graph';
+import { GraphQueryApi, GraphStore, NodeKind, loadGraphApiCached, } from '@shrkcrft/graph';
 import { FORMAT_INPUT_PROPERTY, formatObjectArrays } from "../server/columnar-format.js";
+import { dropDeleted, graphResultStaleness } from "./graph-staleness.js";
 const NEXT = 'shrk graph index';
 export const getGraphContextTool = {
     name: 'get_graph_context',
@@ -31,7 +32,7 @@ export const getGraphContextTool = {
                 },
             };
         }
-        const api = GraphQueryApi.fromStore(ctx.inspection.projectRoot);
+        const api = loadGraphApiCached(ctx.inspection.projectRoot) ?? GraphQueryApi.fromStore(ctx.inspection.projectRoot);
         const anchor = resolveAnchor(api, target);
         if (!anchor) {
             return {
@@ -43,24 +44,57 @@ export const getGraphContextTool = {
                 },
             };
         }
-        const neighbours = api.neighbours(anchor.id);
+        // A SYMBOL has no imports-file edges (those are file→file), so its import
+        // context is the DECLARING FILE's imports — compute neighbours on that file
+        // (mirrors the CLI; otherwise importsFrom/importedBy are wrongly empty).
+        const declaringFile = anchor.kind === NodeKind.Symbol
+            ? api.declaringFileOf(anchor.id) ?? (anchor.path ? api.findFile(anchor.path) : undefined)
+            : undefined;
+        const subjectId = anchor.kind === NodeKind.File ? anchor.id : declaringFile?.id ?? anchor.id;
+        const neighbours = api.neighbours(subjectId);
         const symbols = anchor.kind === NodeKind.File ? api.symbolsIn(anchor.id) : [];
+        // Who uses this symbol — references + calls (the CLI provides these; the MCP
+        // previously omitted them, returning a confidently-wrong "nothing uses this").
+        const referencedBy = anchor.kind === NodeKind.Symbol ? api.referencesOf(anchor.id) : [];
+        const calledBy = anchor.kind === NodeKind.Symbol ? api.callersOf(anchor.id) : [];
+        // Typed subtype/supertype edges (extends / implements) — the precise
+        // "who implements this interface" answer for a symbol anchor.
+        const subtypes = anchor.kind === NodeKind.Symbol ? api.subtypesOf(anchor.id) : [];
+        const supertypes = anchor.kind === NodeKind.Symbol ? api.supertypesOf(anchor.id) : [];
+        const importsFrom = neighbours.out
+            .filter((o) => o.edge.kind === 'imports-file')
+            .slice(0, 50)
+            .map((o) => 'resolved' in o.target
+            ? { id: o.target.id, resolved: false }
+            : { ...summarise(o.target), resolved: true });
+        const importedBy = neighbours.in
+            .filter((i) => i.edge.kind === 'imports-file')
+            .slice(0, 50)
+            .map((i) => 'resolved' in i.source
+            ? { id: i.source.id, resolved: false }
+            : { ...summarise(i.source), resolved: true });
+        const referencedByRows = referencedBy.slice(0, 50).map(summarise);
+        const calledByRows = calledBy.slice(0, 50).map(summarise);
+        // Drop imports/refs to/from files deleted on disk; flag the rest if changed.
+        const fresh = graphResultStaleness(api, ctx.inspection.projectRoot, [
+            anchor.path,
+            ...importsFrom.map((x) => ('path' in x ? x.path : undefined)),
+            ...importedBy.map((x) => ('path' in x ? x.path : undefined)),
+            ...referencedByRows.map((x) => x.path),
+            ...calledByRows.map((x) => x.path),
+        ]);
         const data = {
             schema: 'sharkcraft.graph-context/v1',
             anchor: summarise(anchor),
-            importsFrom: neighbours.out
-                .filter((o) => o.edge.kind === 'imports-file')
-                .slice(0, 50)
-                .map((o) => ('resolved' in o.target
-                ? { id: o.target.id, resolved: false }
-                : { ...summarise(o.target), resolved: true })),
-            importedBy: neighbours.in
-                .filter((i) => i.edge.kind === 'imports-file')
-                .slice(0, 50)
-                .map((i) => ('resolved' in i.source
-                ? { id: i.source.id, resolved: false }
-                : { ...summarise(i.source), resolved: true })),
+            ...(declaringFile ? { declaredIn: summarise(declaringFile) } : {}),
+            importsFrom: dropDeleted(importsFrom, fresh.deletedSet),
+            importedBy: dropDeleted(importedBy, fresh.deletedSet),
             symbols: symbols.slice(0, 50).map(summarise),
+            ...(referencedByRows.length > 0 ? { referencedBy: dropDeleted(referencedByRows, fresh.deletedSet) } : {}),
+            ...(calledByRows.length > 0 ? { calledBy: dropDeleted(calledByRows, fresh.deletedSet) } : {}),
+            ...(subtypes.length > 0 ? { subtypes: subtypes.slice(0, 50).map(summarise) } : {}),
+            ...(supertypes.length > 0 ? { supertypes: supertypes.slice(0, 50).map(summarise) } : {}),
+            ...(fresh.field ?? {}),
         };
         return { data: formatObjectArrays(data, input) };
     },

package/dist/tools/get-graph-cycles.tool.js

@@ -1,4 +1,4 @@
-import { GraphQueryApi, GraphStore } from '@shrkcrft/graph';
+import { GraphQueryApi, GraphStore, loadGraphApiCached } from '@shrkcrft/graph';
 import { FORMAT_INPUT_PROPERTY, formatObjectArrays } from "../server/columnar-format.js";
 const NEXT = 'shrk graph index';
 /**
@@ -40,7 +40,7 @@ export const getGraphCyclesTool = {
                 },
             };
         }
-        const api = GraphQueryApi.fromStore(ctx.inspection.projectRoot);
+        const api = loadGraphApiCached(ctx.inspection.projectRoot) ?? GraphQueryApi.fromStore(ctx.inspection.projectRoot);
         const all = api.cycles();
         const filtered = all.filter((c) => c.size >= minSize);
         const limited = filtered.slice(0, rawLimit);

package/dist/tools/get-graph-deps.tool.js

@@ -1,4 +1,4 @@
-import { EdgeKind, GraphQueryApi, GraphStore } from '@shrkcrft/graph';
+import { EdgeKind, GraphQueryApi, GraphStore, loadGraphApiCached } from '@shrkcrft/graph';
 const NEXT = 'shrk graph index';
 /**
  * Read-only MCP mirror of `shrk graph deps`. Returns the workspace
@@ -41,7 +41,7 @@ export const getGraphDepsTool = {
                 },
             };
         }
-        const api = GraphQueryApi.fromStore(ctx.inspection.projectRoot);
+        const api = loadGraphApiCached(ctx.inspection.projectRoot) ?? GraphQueryApi.fromStore(ctx.inspection.projectRoot);
         const pkgId = `package:${target}`;
         const pkgNode = api.neighbours(pkgId)?.node;
         if (!pkgNode) {

package/dist/tools/get-graph-hubs.tool.d.ts

@@ -0,0 +1,3 @@
+import type { IToolDefinition } from '../server/tool-definition.js';
+export declare const getGraphHubsTool: IToolDefinition;
+//# sourceMappingURL=get-graph-hubs.tool.d.ts.map

package/dist/tools/get-graph-hubs.tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"get-graph-hubs.tool.d.ts","sourceRoot":"","sources":["../../src/tools/get-graph-hubs.tool.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAC;AAWpE,eAAO,MAAM,gBAAgB,EAAE,eA4C9B,CAAC"}

package/dist/tools/get-graph-hubs.tool.js

@@ -0,0 +1,61 @@
+import { GraphQueryApi, GraphStore, loadGraphApiCached } from '@shrkcrft/graph';
+import { FORMAT_INPUT_PROPERTY, formatObjectArrays } from "../server/columnar-format.js";
+const NEXT = 'shrk graph index';
+export const getGraphHubsTool = {
+    name: 'get_graph_hubs',
+    description: 'The most-depended-on code: symbols ranked by how many DISTINCT files reference them, files by how many import them. The "load-bearing code" to change most carefully (biggest blast radius) and understand first when onboarding — the companion to get_graph_impact. Pass `path` (e.g. "packages/foo") to scope to one subsystem. Read-only; needs `shrk graph index`.',
+    cliCommand: 'graph hubs',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            limit: { type: 'number' },
+            path: { type: 'string' },
+            ...FORMAT_INPUT_PROPERTY,
+        },
+        additionalProperties: false,
+    },
+    handler(input, ctx) {
+        const args = input;
+        const limit = clampLimit(args.limit);
+        const projectRoot = ctx.inspection.projectRoot;
+        const store = new GraphStore(projectRoot);
+        if (!store.exists()) {
+            return {
+                isError: true,
+                error: {
+                    code: 'graph-missing',
+                    message: `Code-intelligence index is missing. Run '${NEXT}'.`,
+                    details: { nextCommand: NEXT },
+                },
+            };
+        }
+        const api = loadGraphApiCached(projectRoot) ?? GraphQueryApi.fromStore(projectRoot);
+        const pathScope = typeof args.path === 'string' && args.path.trim().length > 0 ? args.path.trim() : undefined;
+        const hubs = api.topHubs(limit, pathScope);
+        const row = (h) => ({
+            ...summarise(h.node),
+            inDegree: h.inDegree,
+        });
+        const data = {
+            schema: 'sharkcraft.graph-hubs/v1',
+            ...(pathScope ? { path: pathScope } : {}),
+            symbols: hubs.symbols.map(row),
+            files: hubs.files.map(row),
+        };
+        return { data: formatObjectArrays(data, input) };
+    },
+};
+function clampLimit(raw) {
+    if (typeof raw !== 'number' || !Number.isFinite(raw))
+        return 15;
+    return Math.max(1, Math.min(100, Math.floor(raw)));
+}
+function summarise(n) {
+    return {
+        id: n.id,
+        kind: n.kind,
+        label: n.label,
+        ...(n.path ? { path: n.path } : {}),
+        ...(n.line ? { line: n.line } : {}),
+    };
+}

package/dist/tools/get-graph-impact.tool.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"get-graph-impact.tool.d.ts","sourceRoot":"","sources":["../../src/tools/get-graph-impact.tool.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAC;AAWpE,eAAO,MAAM,kBAAkB,EAAE,eAmEhC,CAAC"}
+{"version":3,"file":"get-graph-impact.tool.d.ts","sourceRoot":"","sources":["../../src/tools/get-graph-impact.tool.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAC;AAYpE,eAAO,MAAM,kBAAkB,EAAE,eA4EhC,CAAC"}

package/dist/tools/get-graph-impact.tool.js

@@ -1,5 +1,6 @@
-import { GraphQueryApi, GraphStore } from '@shrkcrft/graph';
+import { GraphQueryApi, GraphStore, loadGraphApiCached } from '@shrkcrft/graph';
 import { FORMAT_INPUT_PROPERTY, formatObjectArrays } from "../server/columnar-format.js";
+import { dropDeleted, graphResultStaleness } from "./graph-staleness.js";
 const NEXT = 'shrk graph index';
 export const getGraphImpactTool = {
     name: 'get_graph_impact',
@@ -38,7 +39,7 @@ export const getGraphImpactTool = {
                 },
             };
         }
-        const api = GraphQueryApi.fromStore(ctx.inspection.projectRoot);
+        const api = loadGraphApiCached(ctx.inspection.projectRoot) ?? GraphQueryApi.fromStore(ctx.inspection.projectRoot);
         const anchor = resolveAnchor(api, target);
         if (!anchor) {
             return {
@@ -50,20 +51,29 @@ export const getGraphImpactTool = {
                 },
             };
         }
-        const closure = reverseClosure(api, anchor.id, maxDepth, limit);
+        const closure = reverseClosure(api, anchor, maxDepth, limit);
         const direct = closure.layer[1] ?? [];
         const transitive = closure.all.filter((id) => id !== anchor.id && !direct.includes(id));
+        const directNodes = direct.map((id) => summarise(api.neighbours(id).node));
+        const transitiveNodes = transitive.slice(0, limit).map((id) => summarise(api.neighbours(id).node));
+        // Targeted staleness over the blast-radius files: drop dependents whose
+        // file was deleted (they can't break), flag those whose content changed —
+        // so a stale index never misroutes which tests/files the agent trusts.
+        const fresh = graphResultStaleness(api, ctx.inspection.projectRoot, [
+            anchor.path,
+            ...directNodes.map((n) => n.path),
+            ...transitiveNodes.map((n) => n.path),
+        ]);
         const data = {
             schema: 'sharkcraft.graph-impact/v1',
             anchor: summarise(anchor),
             maxDepth,
             limit,
             truncated: closure.truncated,
-            directDependents: direct.map((id) => summarise(api.neighbours(id).node)),
-            transitiveDependents: transitive
-                .slice(0, limit)
-                .map((id) => summarise(api.neighbours(id).node)),
+            directDependents: dropDeleted(directNodes, fresh.deletedSet),
+            transitiveDependents: dropDeleted(transitiveNodes, fresh.deletedSet),
             totalReached: closure.all.length - 1,
+            ...(fresh.field ?? {}),
         };
         return { data: formatObjectArrays(data, input) };
     },
@@ -83,13 +93,23 @@ function resolveAnchor(api, target) {
         return syms[0];
     return undefined;
 }
-function reverseClosure(api, startId, maxDepth, limit) {
-    const seen = new Set([startId]);
+function reverseClosure(api, anchor, maxDepth, limit) {
+    const seen = new Set([anchor.id]);
     const layer = {};
-    let frontier = [startId];
-    let depth = 1;
     let truncated = false;
-    while (depth <= maxDepth && frontier.length > 0) {
+    // Layer 1 uses the anchor-kind-aware direct dependents (importersOf alone
+    // returns NOTHING for a symbol anchor — symbols have no import edges).
+    let frontier = directDependents(api, anchor).filter((id) => !seen.has(id));
+    if (frontier.length > limit) {
+        frontier = frontier.slice(0, limit);
+        truncated = true;
+    }
+    for (const id of frontier)
+        seen.add(id);
+    if (frontier.length > 0)
+        layer[1] = frontier;
+    let depth = 2;
+    while (depth <= maxDepth && frontier.length > 0 && !truncated) {
         const next = [];
         for (const id of frontier) {
             for (const imp of api.importersOf(id)) {
@@ -109,11 +129,13 @@ function reverseClosure(api, startId, maxDepth, limit) {
             layer[depth] = next;
         frontier = next;
         depth += 1;
-        if (truncated)
-            break;
     }
     return { all: [...seen], layer, truncated };
 }
+/** Kind-aware direct dependents — the shared `GraphQueryApi` implementation. */
+function directDependents(api, anchor) {
+    return api.directDependentsOf(anchor).map((n) => n.id);
+}
 function summarise(n) {
     return {
         id: n.id,

package/dist/tools/get-graph-path.tool.d.ts

@@ -0,0 +1,3 @@
+import type { IToolDefinition } from '../server/tool-definition.js';
+export declare const getGraphPathTool: IToolDefinition;
+//# sourceMappingURL=get-graph-path.tool.d.ts.map

package/dist/tools/get-graph-path.tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"get-graph-path.tool.d.ts","sourceRoot":"","sources":["../../src/tools/get-graph-path.tool.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAC;AAYpE,eAAO,MAAM,gBAAgB,EAAE,eAgG9B,CAAC"}

package/dist/tools/get-graph-path.tool.js

@@ -0,0 +1,144 @@
+import { EdgeKind, GraphQueryApi, GraphStore, loadGraphApiCached, NodeKind, } from '@shrkcrft/graph';
+import { FORMAT_INPUT_PROPERTY, formatObjectArrays } from "../server/columnar-format.js";
+import { callGraphLanguageNote, graphResultStaleness } from "./graph-staleness.js";
+const NEXT = 'shrk graph index';
+export const getGraphPathTool = {
+    name: 'get_graph_path',
+    description: 'Is code A actually wired to code B? Returns the shortest directed CODE path (import/call/reference/declare/re-export/extends/implements edges) from `from` to `to`, hop by hop with edge kind and call-site line — the deterministic answer to "is X wired to Y" that grep cannot give. If A does not reach B it also checks B→A and reports the direction. Each endpoint is a file path or a symbol name. Read-only; needs `shrk graph index`.',
+    cliCommand: 'graph path',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            from: { type: 'string' },
+            to: { type: 'string' },
+            maxDepth: { type: 'number' },
+            ...FORMAT_INPUT_PROPERTY,
+        },
+        required: ['from', 'to'],
+        additionalProperties: false,
+    },
+    handler(input, ctx) {
+        const args = input;
+        const fromArg = (args.from ?? '').trim();
+        const toArg = (args.to ?? '').trim();
+        if (!fromArg || !toArg) {
+            return { isError: true, error: { code: 'invalid-input', message: 'from and to are required' } };
+        }
+        const maxDepth = clampDepth(args.maxDepth);
+        const cwd = ctx.inspection.projectRoot;
+        const store = new GraphStore(cwd);
+        if (!store.exists()) {
+            return {
+                isError: true,
+                error: {
+                    code: 'graph-missing',
+                    message: `Code-intelligence index is missing. Run '${NEXT}'.`,
+                    details: { nextCommand: NEXT },
+                },
+            };
+        }
+        const api = loadGraphApiCached(cwd) ?? GraphQueryApi.fromStore(cwd);
+        const from = resolveAnchor(api, fromArg);
+        const to = resolveAnchor(api, toArg);
+        if (!from || !to) {
+            const missing = !from ? fromArg : toArg;
+            return {
+                isError: true,
+                error: { code: 'not-found', message: `No graph node matched "${missing}".`, details: { target: missing } },
+            };
+        }
+        // A symbol has no OUTGOING code edges (references are recorded file→symbol),
+        // so trace from its declaring file. The target may stay a symbol.
+        const fromStart = bfsStartNode(api, from);
+        const toStart = bfsStartNode(api, to);
+        const forward = api.pathBetween(fromStart.id, to.id, { maxDepth });
+        const reverse = forward.found ? null : api.pathBetween(toStart.id, from.id, { maxDepth });
+        const direction = forward.found
+            ? 'forward'
+            : reverse?.found
+                ? 'reverse'
+                : 'none';
+        const chosen = forward.found ? forward : reverse?.found ? reverse : forward;
+        const startEndpoint = direction === 'reverse' ? to : from;
+        const startFile = direction === 'reverse' ? toStart : fromStart;
+        const startNote = direction !== 'none' && startFile.id !== startEndpoint.id && startEndpoint.kind === NodeKind.Symbol
+            ? `\`${startEndpoint.label}\` is declared in ${startFile.path ?? startFile.id}; path traced from that file (per-symbol out-edges are not tracked).`
+            : undefined;
+        const hops = chosen.hops.map((h) => ({
+            from: h.from.path ?? h.from.id,
+            to: h.to.path ?? h.to.id,
+            kind: h.kind,
+            label: h.to.label,
+            ...(h.line ? { line: h.line } : {}),
+        }));
+        const fresh = graphResultStaleness(api, cwd, [
+            from.path,
+            to.path,
+            ...chosen.hops.map((h) => h.from.path),
+            ...chosen.hops.map((h) => h.to.path),
+        ]);
+        // A no-path answer between non-TS endpoints may just be missing call edges.
+        const langNote = direction === 'none' ? callGraphLanguageNote(api, from) ?? callGraphLanguageNote(api, to) : undefined;
+        const data = {
+            schema: 'sharkcraft.graph-path/v1',
+            from: summarise(from),
+            to: summarise(to),
+            found: direction !== 'none',
+            direction,
+            ...(direction !== 'none' && startFile.id !== startEndpoint.id ? { tracedFrom: summarise(startFile) } : {}),
+            hops,
+            hopCount: hops.length,
+            explored: forward.found ? forward.explored : reverse?.explored ?? forward.explored,
+            ...(direction === 'none' && chosen.reason ? { reason: chosen.reason } : {}),
+            ...(startNote ?? langNote ? { note: startNote ?? langNote } : {}),
+            ...(fresh.field ?? {}),
+        };
+        return { data: formatObjectArrays(data, input) };
+    },
+};
+function clampDepth(raw) {
+    if (typeof raw !== 'number' || !Number.isFinite(raw))
+        return 16;
+    return Math.max(1, Math.min(32, Math.floor(raw)));
+}
+function resolveAnchor(api, target) {
+    const direct = api.neighbours(target);
+    if (direct)
+        return direct.node;
+    if (target.startsWith('file:') || target.startsWith('symbol:') || target.startsWith('package:')) {
+        return undefined;
+    }
+    const f = api.findFile(target);
+    if (f)
+        return f;
+    const syms = api.findSymbol(target, { exact: true, limit: 1 });
+    if (syms.length > 0)
+        return syms[0];
+    return undefined;
+}
+/** A file is its own BFS start; a symbol resolves to its declaring file. */
+function bfsStartNode(api, node) {
+    if (node.kind !== NodeKind.Symbol)
+        return node;
+    const neighbours = api.neighbours(node.id);
+    if (neighbours) {
+        for (const incoming of neighbours.in) {
+            if (incoming.edge.kind !== EdgeKind.DeclaresSymbol)
+                continue;
+            if ('resolved' in incoming.source)
+                continue;
+            if (incoming.source.kind === NodeKind.File)
+                return incoming.source;
+        }
+    }
+    return (node.path ? api.findFile(node.path) : undefined) ?? node;
+}
+function summarise(n) {
+    return {
+        id: n.id,
+        kind: n.kind,
+        label: n.label,
+        ...(n.path ? { path: n.path } : {}),
+        ...(n.line ? { line: n.line } : {}),
+    };
+}

package/dist/tools/get-graph-search.tool.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"get-graph-search.tool.d.ts","sourceRoot":"","sources":["../../src/tools/get-graph-search.tool.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAC;AAYpE,eAAO,MAAM,kBAAkB,EAAE,eA6DhC,CAAC"}
+{"version":3,"file":"get-graph-search.tool.d.ts","sourceRoot":"","sources":["../../src/tools/get-graph-search.tool.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAC;AAYpE,eAAO,MAAM,kBAAkB,EAAE,eA8EhC,CAAC"}

package/dist/tools/get-graph-search.tool.js

@@ -1,4 +1,4 @@
-import { GraphQueryApi, GraphStore } from '@shrkcrft/graph';
+import { GraphQueryApi, GraphStore, loadGraphApiCached } from '@shrkcrft/graph';
 import { FORMAT_INPUT_PROPERTY, formatObjectArrays } from "../server/columnar-format.js";
 const NEXT = 'shrk graph index';
 export const getGraphSearchTool = {
@@ -38,15 +38,34 @@ export const getGraphSearchTool = {
                 },
             };
         }
-        const api = GraphQueryApi.fromStore(ctx.inspection.projectRoot);
+        const api = loadGraphApiCached(ctx.inspection.projectRoot) ?? GraphQueryApi.fromStore(ctx.inspection.projectRoot);
+        const exact = args.exact ?? false;
         const matches = [];
         if (!args.kind || args.kind === 'file') {
             const f = api.findFile(query);
             if (f)
                 matches.push(f);
+            // Fuzzy fallback (mirrors the CLI): substring match on path/basename so a
+            // bare name like `Foo` finds `packages/x/Foo.ts` without the full path —
+            // otherwise the MCP returned an empty list where the CLI found the file.
+            if (!exact && matches.length < limit) {
+                const q = query.toLowerCase();
+                const seen = new Set(matches.map((n) => n.id));
+                for (const node of api.allFiles()) {
+                    if (seen.has(node.id))
+                        continue;
+                    const p = node.path?.toLowerCase() ?? '';
+                    const base = p.includes('/') ? p.slice(p.lastIndexOf('/') + 1) : p;
+                    if (base.includes(q) || p.includes(q)) {
+                        matches.push(node);
+                        seen.add(node.id);
+                        if (matches.length >= limit)
+                            break;
+                    }
+                }
+            }
         }
         if (!args.kind || args.kind === 'symbol') {
-            const exact = args.exact ?? false;
             for (const s of api.findSymbol(query, { exact, limit }))
                 matches.push(s);
         }

package/dist/tools/get-graph-status.tool.d.ts

@@ -1,9 +1,11 @@
 import type { IToolDefinition } from '../server/tool-definition.js';
 /**
  * Read-only status for the on-disk code graph. Returns
- * { state: 'fresh' | 'corrupt' | 'missing' } and counters.
- * On 'missing', `isError` + `error.details.nextCommand` direct the
- * caller (CLI or human) to refresh.
+ * { state: 'fresh' | 'stale' | 'corrupt' | 'missing' } and counters.
+ * `corrupt` (store self-integrity) and `stale` (files changed on disk since
+ * indexing) are orthogonal — a store can be digest-valid yet stale — so
+ * precedence is corrupt > stale > fresh. On 'missing', `isError` +
+ * `nextCommand` direct the caller to refresh.
  */
 export declare const getGraphStatusTool: IToolDefinition;
 //# sourceMappingURL=get-graph-status.tool.d.ts.map

package/dist/tools/get-graph-status.tool.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"get-graph-status.tool.d.ts","sourceRoot":"","sources":["../../src/tools/get-graph-status.tool.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAC;AAKpE;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB,EAAE,eAqChC,CAAC"}
+{"version":3,"file":"get-graph-status.tool.d.ts","sourceRoot":"","sources":["../../src/tools/get-graph-status.tool.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAC;AAKpE;;;;;;;GAOG;AACH,eAAO,MAAM,kBAAkB,EAAE,eA4ChC,CAAC"}

package/dist/tools/get-graph-status.tool.js

@@ -1,15 +1,17 @@
-import { GraphStore } from '@shrkcrft/graph';
+import { detectGraphFreshness, GraphStore } from '@shrkcrft/graph';
 const NEXT = 'shrk graph index';
 const STALE_HINT = `Code-intelligence index is missing or stale. Run '${NEXT}' to build it.`;
 /**
  * Read-only status for the on-disk code graph. Returns
- * { state: 'fresh' | 'corrupt' | 'missing' } and counters.
- * On 'missing', `isError` + `error.details.nextCommand` direct the
- * caller (CLI or human) to refresh.
+ * { state: 'fresh' | 'stale' | 'corrupt' | 'missing' } and counters.
+ * `corrupt` (store self-integrity) and `stale` (files changed on disk since
+ * indexing) are orthogonal — a store can be digest-valid yet stale — so
+ * precedence is corrupt > stale > fresh. On 'missing', `isError` +
+ * `nextCommand` direct the caller to refresh.
  */
 export const getGraphStatusTool = {
     name: 'get_graph_status',
-    description: 'Read-only status of the SharkCraft code-intelligence graph: file/node/edge counts, schema, last indexed time, digest verification. Returns nextCommand when missing.',
+    description: 'Read-only status of the SharkCraft code-intelligence graph: state (fresh/stale/corrupt/missing), file/node/edge counts, and how many files changed/added/deleted since indexing. Returns nextCommand when stale or missing so the agent knows to refresh before trusting graph answers.',
     cliCommand: 'graph status',
     inputSchema: { type: 'object', properties: {}, additionalProperties: false },
     handler(_input, ctx) {
@@ -26,10 +28,13 @@ export const getGraphStatusTool = {
         }
         const verify = store.verifyDigest();
         const snap = store.loadSnapshot();
+        const fresh = detectGraphFreshness(ctx.inspection.projectRoot);
+        const behind = fresh.modified.length + fresh.added.length + fresh.deleted.length;
+        const state = !verify.ok ? 'corrupt' : behind > 0 ? 'stale' : 'fresh';
         return {
             data: {
                 schema: snap.manifest.schema,
-                state: verify.ok ? 'fresh' : 'corrupt',
+                state,
                 digestOk: verify.ok,
                 fileCount: snap.manifest.filesIndexed,
                 nodeCount: snap.nodes.size,
@@ -39,6 +44,10 @@ export const getGraphStatusTool = {
                 workspacePackages: snap.manifest.workspacePackages,
                 lastIndexedAt: snap.manifest.lastIndexedAt,
                 lastIndexDurationMs: snap.manifest.lastIndexDurationMs,
+                modifiedSinceIndex: fresh.modified.length,
+                newSinceIndex: fresh.added.length,
+                deletedSinceIndex: fresh.deleted.length,
+                ...(behind > 0 ? { nextCommand: 'shrk graph index --changed' } : {}),
                 ...(verify.ok ? {} : { expectedDigest: verify.expected, actualDigest: verify.actual }),
             },
         };

package/dist/tools/graph-staleness.d.ts

@@ -0,0 +1,34 @@
+import { type GraphQueryApi, type INode } from '@shrkcrft/graph';
+/**
+ * A note when a symbol's file language has no call-graph extraction (Go/Python/
+ * Java/…) — only TS/JS build call/reference edges — so an empty caller/usage
+ * result isn't read as "nothing calls it". Returns undefined for TS/JS.
+ */
+export declare function callGraphLanguageNote(api: GraphQueryApi, sym: INode): string | undefined;
+export declare const GRAPH_STALE_HINT = "Result files changed since indexing \u2014 run `shrk graph index --changed` for fresh results.";
+export interface IGraphStaleSurface {
+    /** Result file paths deleted on disk — drop entries whose `path` is in this set. */
+    deletedSet: ReadonlySet<string>;
+    /** Spread into the tool `data` object; null when every result file is fresh. */
+    field: {
+        stale: {
+            modified: readonly string[];
+            deleted: readonly string[];
+        };
+        staleHint: string;
+    } | null;
+}
+/**
+ * Targeted, read-only staleness over a query's result file paths. The graph
+ * MCP tools use it to DROP deleted result files and FLAG modified ones, so a
+ * stale index never silently serves a wrong/dead answer for a file the agent
+ * just edited. Cheap: stats only the handful of result files (mtime+size gate,
+ * sha1 only on mismatch) — never a whole-tree walk.
+ */
+export declare function graphResultStaleness(api: GraphQueryApi, cwd: string, paths: ReadonlyArray<string | undefined>): IGraphStaleSurface;
+/** Filter out result entries whose file path was deleted on disk. */
+export declare function dropDeleted<T extends {
+    id: string;
+    path?: string;
+}>(rows: readonly T[], deletedSet: ReadonlySet<string>): T[];
+//# sourceMappingURL=graph-staleness.d.ts.map

package/dist/tools/graph-staleness.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph-staleness.d.ts","sourceRoot":"","sources":["../../src/tools/graph-staleness.ts"],"names":[],"mappings":"AAAA,OAAO,EAA0B,KAAK,aAAa,EAAE,KAAK,KAAK,EAAE,MAAM,iBAAiB,CAAC;AAEzF;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,aAAa,EAAE,GAAG,EAAE,KAAK,GAAG,MAAM,GAAG,SAAS,CAKxF;AAED,eAAO,MAAM,gBAAgB,mGACgE,CAAC;AAE9F,MAAM,WAAW,kBAAkB;IACjC,oFAAoF;IACpF,UAAU,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IAChC,gFAAgF;IAChF,KAAK,EACD;QAAE,KAAK,EAAE;YAAE,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;YAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAA;SAAE,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,GACzF,IAAI,CAAC;CACV;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAClC,GAAG,EAAE,aAAa,EAClB,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,aAAa,CAAC,MAAM,GAAG,SAAS,CAAC,GACvC,kBAAkB,CAUpB;AAED,qEAAqE;AACrE,wBAAgB,WAAW,CAAC,CAAC,SAAS;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,EACjE,IAAI,EAAE,SAAS,CAAC,EAAE,EAClB,UAAU,EAAE,WAAW,CAAC,MAAM,CAAC,GAC9B,CAAC,EAAE,CAEL"}

package/dist/tools/graph-staleness.js

@@ -0,0 +1,36 @@
+import { hasCallGraphReferences } from '@shrkcrft/graph';
+/**
+ * A note when a symbol's file language has no call-graph extraction (Go/Python/
+ * Java/…) — only TS/JS build call/reference edges — so an empty caller/usage
+ * result isn't read as "nothing calls it". Returns undefined for TS/JS.
+ */
+export function callGraphLanguageNote(api, sym) {
+    const file = sym.path ? api.findFile(sym.path) : undefined;
+    const lang = file?.data?.['language'];
+    if (hasCallGraphReferences(lang))
+        return undefined;
+    return `Call/reference edges are extracted for TS/JS only — \`${sym.label}\` is in a ${lang} file, so callers/usages are not tracked here (an empty result does NOT mean none).`;
+}
+export const GRAPH_STALE_HINT = 'Result files changed since indexing — run `shrk graph index --changed` for fresh results.';
+/**
+ * Targeted, read-only staleness over a query's result file paths. The graph
+ * MCP tools use it to DROP deleted result files and FLAG modified ones, so a
+ * stale index never silently serves a wrong/dead answer for a file the agent
+ * just edited. Cheap: stats only the handful of result files (mtime+size gate,
+ * sha1 only on mismatch) — never a whole-tree walk.
+ */
+export function graphResultStaleness(api, cwd, paths) {
+    const rel = paths.filter((p) => !!p);
+    const stale = api.staleFilesAmong(cwd, rel);
+    const has = stale.modified.length > 0 || stale.deleted.length > 0;
+    return {
+        deletedSet: new Set(stale.deleted),
+        field: has
+            ? { stale: { modified: stale.modified, deleted: stale.deleted }, staleHint: GRAPH_STALE_HINT }
+            : null,
+    };
+}
+/** Filter out result entries whose file path was deleted on disk. */
+export function dropDeleted(rows, deletedSet) {
+    return rows.filter((r) => !r.path || !deletedSet.has(r.path));
+}

package/dist/tools/primary-tools.d.ts

@@ -1,5 +1,5 @@
 /**
- * Primary MCP tools — the ~30 tools advertised to a connected agent
+ * Primary MCP tools — the core set advertised to a connected agent
  * by default. Every tool in {@link ALL_TOOLS} stays callable (so an
  * agent that already knows the name can use it), but `tools/list`
  * only advertises the primary set. Smaller surface = better

package/dist/tools/primary-tools.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"primary-tools.d.ts","sourceRoot":"","sources":["../../src/tools/primary-tools.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,iBAAiB,EAAE,WAAW,CAAC,MAAM,CAiDhD,CAAC;AAEH;;;;GAIG;AACH,wBAAgB,0BAA0B,IAAI,OAAO,CAGpD"}
+{"version":3,"file":"primary-tools.d.ts","sourceRoot":"","sources":["../../src/tools/primary-tools.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,iBAAiB,EAAE,WAAW,CAAC,MAAM,CA4DhD,CAAC;AAEH;;;;GAIG;AACH,wBAAgB,0BAA0B,IAAI,OAAO,CAGpD"}

package/dist/tools/primary-tools.js

@@ -1,5 +1,5 @@
 /**
- * Primary MCP tools — the ~30 tools advertised to a connected agent
+ * Primary MCP tools — the core set advertised to a connected agent
  * by default. Every tool in {@link ALL_TOOLS} stays callable (so an
  * agent that already knows the name can use it), but `tools/list`
  * only advertises the primary set. Smaller surface = better
@@ -54,6 +54,17 @@ export const PRIMARY_MCP_TOOLS = new Set([
     // Doctor / readiness
     'get_ai_readiness_report',
     'doctor_packs',
+    // Code-intelligence graph — the agent's grep replacement for understanding
+    // existing code: who calls X, where is X used (path:line), what breaks if I
+    // change X, is X wired. Verifiable file:line truth from the indexed graph.
+    'get_graph_callers',
+    'code_find_usages',
+    'get_graph_impact',
+    'get_graph_path',
+    'get_graph_hubs',
+    'graph_why',
+    'get_graph_node',
+    'get_graph_search',
     // Search
     'search_all',
     'search_knowledge',

package/dist/tools/start-here.tool.js

@@ -1,13 +1,13 @@
 import { buildStartHereReport, buildPrimaryCommandsReport, } from '@shrkcrft/inspector';
 export const getStartHereTool = {
     name: 'get_start_here',
-    description: 'Return the SharkCraft start-here flow list (30-second explanation + 5 primary flows + safety pledge). Read-only.',
+    description: 'Return the SharkCraft start-here flow list (30-second explanation + primary flows incl. "investigate existing code" + safety pledge). Read-only.',
     inputSchema: {
         type: 'object',
         properties: {
             flow: {
                 type: 'string',
-                enum: ['onboard', 'brief', 'dev', 'review', 'governance', 'packs', 'release'],
+                enum: ['onboard', 'investigate', 'brief', 'dev', 'review', 'governance', 'packs', 'release'],
             },
         },
         additionalProperties: false,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shrkcrft/mcp-server",
-  "version": "0.1.0-alpha.17",
+  "version": "0.1.0-alpha.18",
   "description": "SharkCraft MCP server: 25 tools over @modelcontextprotocol/sdk's stdio transport.",
   "license": "MIT",
   "author": "SharkCraft contributors",
@@ -44,32 +44,32 @@
     "typecheck": "tsc --noEmit -p tsconfig.json"
   },
   "dependencies": {
-    "@shrkcrft/core": "^0.1.0-alpha.17",
-    "@shrkcrft/compress": "^0.1.0-alpha.17",
-    "@shrkcrft/config": "^0.1.0-alpha.17",
-    "@shrkcrft/workspace": "^0.1.0-alpha.17",
-    "@shrkcrft/knowledge": "^0.1.0-alpha.17",
-    "@shrkcrft/context": "^0.1.0-alpha.17",
-    "@shrkcrft/rules": "^0.1.0-alpha.17",
-    "@shrkcrft/paths": "^0.1.0-alpha.17",
-    "@shrkcrft/templates": "^0.1.0-alpha.17",
-    "@shrkcrft/pipelines": "^0.1.0-alpha.17",
-    "@shrkcrft/presets": "^0.1.0-alpha.17",
-    "@shrkcrft/boundaries": "^0.1.0-alpha.17",
-    "@shrkcrft/graph": "^0.1.0-alpha.17",
-    "@shrkcrft/rule-graph": "^0.1.0-alpha.17",
-    "@shrkcrft/structural-search": "^0.1.0-alpha.17",
-    "@shrkcrft/impact-engine": "^0.1.0-alpha.17",
-    "@shrkcrft/context-planner": "^0.1.0-alpha.17",
-    "@shrkcrft/architecture-guard": "^0.1.0-alpha.17",
-    "@shrkcrft/framework-scanners": "^0.1.0-alpha.17",
-    "@shrkcrft/api-surface-diff": "^0.1.0-alpha.17",
-    "@shrkcrft/quality-gates": "^0.1.0-alpha.17",
-    "@shrkcrft/migrate": "^0.1.0-alpha.17",
-    "@shrkcrft/packs": "^0.1.0-alpha.17",
-    "@shrkcrft/generator": "^0.1.0-alpha.17",
-    "@shrkcrft/inspector": "^0.1.0-alpha.17",
-    "@shrkcrft/embeddings": "^0.1.0-alpha.17",
+    "@shrkcrft/core": "^0.1.0-alpha.18",
+    "@shrkcrft/compress": "^0.1.0-alpha.18",
+    "@shrkcrft/config": "^0.1.0-alpha.18",
+    "@shrkcrft/workspace": "^0.1.0-alpha.18",
+    "@shrkcrft/knowledge": "^0.1.0-alpha.18",
+    "@shrkcrft/context": "^0.1.0-alpha.18",
+    "@shrkcrft/rules": "^0.1.0-alpha.18",
+    "@shrkcrft/paths": "^0.1.0-alpha.18",
+    "@shrkcrft/templates": "^0.1.0-alpha.18",
+    "@shrkcrft/pipelines": "^0.1.0-alpha.18",
+    "@shrkcrft/presets": "^0.1.0-alpha.18",
+    "@shrkcrft/boundaries": "^0.1.0-alpha.18",
+    "@shrkcrft/graph": "^0.1.0-alpha.18",
+    "@shrkcrft/rule-graph": "^0.1.0-alpha.18",
+    "@shrkcrft/structural-search": "^0.1.0-alpha.18",
+    "@shrkcrft/impact-engine": "^0.1.0-alpha.18",
+    "@shrkcrft/context-planner": "^0.1.0-alpha.18",
+    "@shrkcrft/architecture-guard": "^0.1.0-alpha.18",
+    "@shrkcrft/framework-scanners": "^0.1.0-alpha.18",
+    "@shrkcrft/api-surface-diff": "^0.1.0-alpha.18",
+    "@shrkcrft/quality-gates": "^0.1.0-alpha.18",
+    "@shrkcrft/migrate": "^0.1.0-alpha.18",
+    "@shrkcrft/packs": "^0.1.0-alpha.18",
+    "@shrkcrft/generator": "^0.1.0-alpha.18",
+    "@shrkcrft/inspector": "^0.1.0-alpha.18",
+    "@shrkcrft/embeddings": "^0.1.0-alpha.18",
     "@modelcontextprotocol/sdk": "^1.0.0",
     "zod": "^3.25.0 || ^4.0.0"
   },