@appchy/jarvis 0.1.36 → 0.1.39

package/dist/data/mcp.mjs

@@ -0,0 +1,2624 @@
+import {
+  COVERAGE_VIA,
+  DERIVED_FROM,
+  GraphStore,
+  applyMemoryOverlay,
+  categoryOf,
+  deleteMemory,
+  edgeMatchesConfidence,
+  isPrecise,
+  memoryNode,
+  readMemoryStore,
+  runEnforcers,
+  summarize,
+  writeMemoryStore
+} from "./chunk-AKQQC5IT.mjs";
+import {
+  diversify,
+  isConfident,
+  isSingleTerm,
+  loadSearchRuntime,
+  rankNodes
+} from "./chunk-7REP35VA.mjs";
+import "./chunk-RRJ6KKYL.mjs";
+import "./chunk-AYOJSS2F.mjs";
+import {
+  parseFrontmatter
+} from "./chunk-YWSWQEJN.mjs";
+
+// ../../packages/data/src/mcp/server.ts
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+
+// ../../packages/data/src/mcp/freshness.ts
+import { execFile } from "child_process";
+import { stat } from "fs/promises";
+import { resolve } from "path";
+import { promisify } from "util";
+
+// ../../packages/data/src/context.ts
+function createGraphContext(config, graph, buildDiagnostics, builtAt, options = {}) {
+  return {
+    graph,
+    config,
+    backendName: config.backend.name,
+    buildDiagnostics,
+    builtAt,
+    search: memoize(options.search)
+  };
+}
+function memoize(search2) {
+  if (!search2) return () => Promise.resolve(void 0);
+  if (typeof search2 !== "function") return () => Promise.resolve(search2);
+  let pending;
+  return () => {
+    if (!pending) {
+      pending = search2().catch((err) => {
+        pending = void 0;
+        throw err;
+      });
+    }
+    return pending;
+  };
+}
+function isCode(ctx, node) {
+  return node.owner === ctx.backendName || node.metadata["data.federated.code"] === true;
+}
+function fileOf(node) {
+  const f = node.metadata.sourceFile;
+  return typeof f === "string" ? f : void 0;
+}
+function labelOf(node) {
+  const l = node.metadata.label ?? node.metadata.title;
+  return typeof l === "string" ? l : void 0;
+}
+function statusOf(node) {
+  const raw = node.metadata.status;
+  return typeof raw === "string" && raw.length > 0 ? raw : void 0;
+}
+function lineOf(node) {
+  const raw = node.metadata.sourceLine;
+  if (typeof raw === "number") return Number.isFinite(raw) ? raw : void 0;
+  if (typeof raw !== "string") return void 0;
+  const m = raw.match(/\d+/);
+  return m ? Number(m[0]) : void 0;
+}
+function renderNode(ctx, node, detailed = false) {
+  if (isCode(ctx, node)) {
+    const line = lineOf(node);
+    return {
+      file: fileOf(node),
+      symbol: labelOf(node),
+      ...line !== void 0 ? { line } : {},
+      ...detailed ? { nodeId: node.id, type: node.type } : {}
+    };
+  }
+  return {
+    id: node.id,
+    type: node.type,
+    title: labelOf(node),
+    ...detailed ? { nodeId: node.id } : {}
+  };
+}
+function previewOf(node) {
+  const ex = node.metadata.excerpt;
+  return typeof ex === "string" && ex.length > 0 ? ex : void 0;
+}
+function edgeScore(edge) {
+  const score = edge.metadata?.score;
+  return typeof score === "number" ? score : void 0;
+}
+function originOf(node) {
+  if (node.metadata["data.federated"] !== true) return void 0;
+  const origin = node.metadata["data.origin"];
+  return typeof origin === "string" ? origin : void 0;
+}
+function nodeMatchesOrigin(node, origin) {
+  if (origin === void 0) return true;
+  const o = originOf(node);
+  return o === void 0 || origin.includes(o);
+}
+function hopPasses(ctx, hop, confidence, origin) {
+  if (!edgeMatchesConfidence(hop, ctx.backendName, confidence)) return false;
+  const target = ctx.graph.node(hop.to);
+  return !target || nodeMatchesOrigin(target, origin);
+}
+
+// ../../packages/data/src/mcp/freshness.ts
+var run = promisify(execFile);
+var HEAD_TTL_MS = 1e4;
+var headCache = /* @__PURE__ */ new Map();
+async function gitHeadCached(root) {
+  const now = Date.now();
+  const hit = headCache.get(root);
+  if (hit && now - hit.at < HEAD_TTL_MS) return hit.head;
+  const head = await gitHead(root);
+  headCache.set(root, { at: now, head });
+  return head;
+}
+async function gitHead(root) {
+  try {
+    const { stdout: commit } = await run("git", ["rev-parse", "HEAD"], { cwd: root });
+    const { stdout: ts } = await run("git", ["show", "-s", "--format=%ct", "HEAD"], { cwd: root });
+    const { stdout: dirty } = await run("git", ["status", "--porcelain"], { cwd: root });
+    return {
+      commit: commit.trim(),
+      committedMs: Number(ts.trim()) * 1e3,
+      dirty: dirty.trim().length > 0
+    };
+  } catch {
+    return void 0;
+  }
+}
+var ORIGIN_TTL_MS = 6e4;
+var ORIGIN_TIMEOUT_MS = 1e4;
+var originCache = /* @__PURE__ */ new Map();
+async function git(root, argv, timeout = 5e3) {
+  try {
+    const { stdout } = await run("git", argv, {
+      cwd: root,
+      timeout,
+      env: { ...process.env, GIT_TERMINAL_PROMPT: "0" }
+    });
+    return stdout.trim();
+  } catch {
+    return void 0;
+  }
+}
+async function fetchHeadIso(root) {
+  const path = await git(root, ["rev-parse", "--git-path", "FETCH_HEAD"]);
+  if (!path) return void 0;
+  try {
+    return (await stat(resolve(root, path))).mtime.toISOString();
+  } catch {
+    return void 0;
+  }
+}
+async function originState(root) {
+  const ref = await git(root, ["rev-parse", "--abbrev-ref", "--symbolic-full-name", "@{upstream}"]);
+  if (!ref) return void 0;
+  const reachable = await git(root, ["fetch", "--quiet", "--no-tags"], ORIGIN_TIMEOUT_MS) !== void 0;
+  const lastSyncedIso = await fetchHeadIso(root);
+  if (!reachable) return { ref, reachable: false, ...lastSyncedIso ? { lastSyncedIso } : {} };
+  const behindBy = Number(await git(root, ["rev-list", "--count", `HEAD..${ref}`]));
+  return {
+    ref,
+    reachable: true,
+    ...Number.isFinite(behindBy) ? { behindBy } : {},
+    ...lastSyncedIso ? { lastSyncedIso } : {}
+  };
+}
+async function originStateCached(root) {
+  const now = Date.now();
+  const hit = originCache.get(root);
+  if (hit && now - hit.at < ORIGIN_TTL_MS) return hit.state;
+  const state = await originState(root);
+  originCache.set(root, { at: now, state });
+  return state;
+}
+function nativeGraphJson(ctx) {
+  const g = ctx.config.backend.native?.()?.graphJson;
+  return typeof g === "string" ? g : void 0;
+}
+async function freshness(ctx) {
+  const root = ctx.config.repoRoot;
+  const graphRel = nativeGraphJson(ctx) ?? ".data/graphify/graph.json";
+  const graphPath = resolve(root, graphRel);
+  let mtimeIso;
+  let mtimeMs;
+  try {
+    const s = await stat(graphPath);
+    mtimeIso = s.mtime.toISOString();
+    mtimeMs = s.mtimeMs;
+  } catch {
+  }
+  const head = await gitHeadCached(root);
+  const builtMs = Date.parse(ctx.builtAt);
+  let behindHead;
+  if (head && mtimeMs) behindHead = mtimeMs < head.committedMs;
+  const replacedMs = Math.max(mtimeMs ?? 0, await snapshotMtimeMs(ctx) ?? 0);
+  const rebuiltOnDisk = Boolean(
+    replacedMs && Number.isFinite(builtMs) && replacedMs > builtMs + 1e3
+  );
+  const origin = await originStateCached(root);
+  const behindOrigin = Boolean(origin?.reachable && (origin.behindBy ?? 0) > 0);
+  const originUnknown = Boolean(origin && !origin.reachable);
+  let reason;
+  if (behindOrigin)
+    reason = `this checkout is ${origin?.behindBy} commit(s) behind ${origin?.ref} \u2014 the map and the board both describe an older world than the origin's. Pull, then \`jarvis build graph\`.`;
+  else if (originUnknown)
+    reason = `cannot reach ${origin?.ref}, so I cannot tell whether this is current${origin?.lastSyncedIso ? ` \u2014 last synced at ${origin.lastSyncedIso}` : " and this clone has never fetched"}.`;
+  else if (behindHead)
+    reason = `${graphRel} is older than HEAD \u2014 the code graph is stale; run \`jarvis build graph\` (the incremental update \u2014 it re-extracts in place), then traces and impact are trustworthy again. \`--rebuild\` re-extracts from scratch and relabels; it is for a graph still wrong after a plain build, not for ordinary drift.`;
+  else if (rebuiltOnDisk)
+    reason = `${graphRel} was rebuilt after this MCP server loaded it \u2014 reloading automatically.`;
+  return {
+    graphPath: graphRel,
+    ...mtimeIso ? { mtimeIso } : {},
+    ...head ? { head: { commit: head.commit, dirty: head.dirty } } : {},
+    ...behindHead !== void 0 ? { behindHead } : {},
+    ...rebuiltOnDisk ? { rebuiltOnDisk } : {},
+    ...origin ? { origin } : {},
+    ...behindOrigin ? { behindOrigin } : {},
+    ...originUnknown ? { originUnknown } : {},
+    stale: Boolean(behindHead) || rebuiltOnDisk || behindOrigin || originUnknown,
+    ...reason ? { reason } : {}
+  };
+}
+async function snapshotMtimeMs(ctx) {
+  const path = ctx.config.persistence?.locate?.({ repoRoot: ctx.config.repoRoot }, "snapshot");
+  if (!path) return void 0;
+  try {
+    return (await stat(path)).mtimeMs;
+  } catch {
+    return void 0;
+  }
+}
+async function federatedFreshness(ctx) {
+  const byOrigin = /* @__PURE__ */ new Map();
+  for (const node of ctx.graph.nodes()) {
+    const origin = originOf(node);
+    const builtAt = node.metadata["data.federated.builtAt"];
+    if (origin === void 0 || typeof builtAt !== "string" || byOrigin.has(origin)) continue;
+    const repoPath = node.metadata["data.federated.repoPath"];
+    byOrigin.set(origin, { builtAt, ...typeof repoPath === "string" ? { repoPath } : {} });
+  }
+  const out = [];
+  for (const [origin, { builtAt, repoPath }] of byOrigin) {
+    const head = repoPath ? await gitHeadCached(repoPath) : void 0;
+    const builtMs = Date.parse(builtAt);
+    const behindOwnHead = head && Number.isFinite(builtMs) ? builtMs < head.committedMs : void 0;
+    out.push({ origin, builtAt, ...behindOwnHead !== void 0 ? { behindOwnHead } : {} });
+  }
+  return out;
+}
+
+// ../../packages/data/src/mcp/provider.ts
+function createGraphProvider(build, options = {}) {
+  const checkFreshness = options.checkFreshness ?? freshness;
+  let current = build();
+  current.catch(() => {
+  });
+  let reloading;
+  return async function getCtx() {
+    const ctx = await current;
+    if (reloading) return reloading;
+    const f = await checkFreshness(ctx);
+    if (!f.rebuiltOnDisk) return ctx;
+    if (reloading) return reloading;
+    options.onReload?.(f.reason ?? `${f.graphPath} was rebuilt on disk`);
+    const next = build();
+    next.catch(() => {
+    });
+    reloading = next.then((fresh) => {
+      current = next;
+      return fresh;
+    }).finally(() => {
+      reloading = void 0;
+    });
+    return reloading;
+  };
+}
+function notReadyMs() {
+  const raw = Number(process.env.JARVIS_DATA_MCP_NOT_READY_MS);
+  return Number.isFinite(raw) && raw >= 0 ? raw : 8e3;
+}
+var PENDING = /* @__PURE__ */ Symbol("pending");
+async function readyWithin(pending) {
+  let timer;
+  const timeout = new Promise((resolve4) => {
+    timer = setTimeout(() => resolve4(PENDING), notReadyMs());
+    timer.unref?.();
+  });
+  try {
+    const won = await Promise.race([pending, timeout]);
+    return won === PENDING ? void 0 : won;
+  } finally {
+    if (timer) clearTimeout(timer);
+  }
+}
+var STILL_LOADING = "The graph is still loading \u2014 retry this call in a few seconds.";
+
+// ../../packages/data/src/data.tools.ts
+var CONFIDENCE = {
+  type: "string",
+  enum: ["precise", "fuzzy", "all"],
+  description: "Edge confidence to include. Default 'precise' (deterministic linker/citation edges); 'fuzzy' = discovery-only structural/semantic edges; 'all' = both."
+};
+function limit(description) {
+  return { type: "integer", minimum: 1, maximum: 200, description };
+}
+function dataTools(handlers) {
+  return [
+    briefTool(handlers),
+    scopeTool(handlers),
+    searchTool(handlers),
+    readTool(handlers),
+    graphTool(handlers),
+    connectionsTool(handlers)
+  ];
+}
+function briefTool(handlers) {
+  return {
+    name: "map_brief",
+    title: "Repo briefing",
+    description: `THE SESSION-START CALL. Returns the top-down state of the repo in one bounded response: what work is in flight (with status, priority, dependencies, and which version/milestone it belongs to), the most-cited decisions/docs, governance health, code areas, and graph freshness. Call it FIRST in a new session \u2014 before planning or searching \u2014 so every later call starts oriented; then drill down with map_read / map_connections / map_scope (each section names its follow-up). Freshness + governance health ride every briefing; pass include:['diagnostics'] for the full lint list (formerly lint) or include:['shape'] for the node/edge breakdown + graph.json freshness (formerly status). Use format:"detailed" for longer lists. Examples: {} \xB7 {"format":"detailed"} \xB7 {"include":["diagnostics"],"severity":"error"}.`,
+    metadata: { readOnly: true },
+    input: {
+      type: "object",
+      properties: {
+        format: {
+          type: "string",
+          enum: ["summary", "detailed"],
+          description: "'detailed' lengthens the lists. Default summary."
+        },
+        include: {
+          type: "array",
+          items: { type: "string", enum: ["diagnostics", "shape"] },
+          description: "Opt into heavy sections: 'diagnostics' (the full lint list, formerly lint) or 'shape' (node/edge breakdown + graph.json freshness, formerly status). Default: neither."
+        },
+        severity: {
+          type: "string",
+          enum: ["error", "warn", "info"],
+          description: "When include has 'diagnostics', keep only this severity."
+        }
+      }
+    },
+    call: (ctx, input) => handlers.brief(ctx, input)
+  };
+}
+function scopeTool(handlers) {
+  return {
+    name: "map_scope",
+    title: "Scope a change, or check one",
+    description: 'THE PLANNING FAST PATH, and the check before you commit \u2014 one question at two moments. Pass `task` (prose) to PLAN a change: a plan-shaped As-found in one call \u2014 the ranked EDIT SET, the GOVERNANCE it is under IN FULL (top rules complete, the rest as ids, with a count of each, because a summary is not the rule), the TESTS COVERING it, and its precise BLAST RADIUS. Pass `edits` (repo-relative paths) to VERIFY one: typed findings grounded in the graph \u2014 governance the edits precisely touch that `cites` does not name, what the change ripples into, and any lint finding landing on the edit set \u2014 plus a verdict of \'approve\' | \'revise\' | \'unassessable\' (\'unassessable\' iff no edit is in the graph yet, so \'approve\' never means could not check). Deterministic, not an opinion \u2014 contest a finding you disagree with. Pass NEITHER and it refuses saying which to give. A parameter for the other door is ignored rather than refused: `format`/`confidence` shape planning, `cites`/`coverage` shape verifying. WHEN TO USE: for MODIFYING existing code. For a BUILD-NEW task the code does not exist yet \u2014 prefer map_search + map_read. Examples: {"task":"rework camera framing"} \xB7 {"edits":["src/server.ts"],"cites":["S-F"]}.',
+    metadata: { readOnly: true },
+    input: {
+      type: "object",
+      properties: {
+        task: {
+          type: "string",
+          description: 'PLANNING door. The change in natural language, e.g. "rework camera framing".'
+        },
+        edits: {
+          type: "array",
+          items: { type: "string" },
+          minItems: 1,
+          description: "VERIFYING door. Repo-relative file paths the change edits."
+        },
+        cites: {
+          type: "array",
+          items: { type: "string" },
+          description: 'With `edits`: the decision/standard ids the plan honors (e.g. "D87"). Governance the edits touch that is not listed is flagged.'
+        },
+        rules: {
+          type: "string",
+          enum: ["full", "ids"],
+          description: "With `task`: 'ids' skips the rule text."
+        },
+        coverage: {
+          type: "boolean",
+          description: "With `edits`: also report files no test exercises. Off by default \u2014 it fires on every file of a layer with no colocated tests."
+        },
+        limit: limit(
+          "How many top hits / edit-set entries / findings. Default 5 planning, 50 verifying."
+        ),
+        format: {
+          type: "string",
+          enum: ["summary", "detailed"],
+          description: "'detailed' deepens each hit's trace, adds an impact sample and a fuzzy reachability view. Default summary."
+        },
+        confidence: CONFIDENCE
+      }
+    },
+    call: (ctx, input) => handlers.scope(ctx, input)
+  };
+}
+function searchTool(handlers) {
+  return {
+    name: "map_search",
+    title: "Find or browse the map",
+    description: 'Finds nodes across BOTH governance artifacts and code \u2014 and, with no `query`, LISTS what the map holds at all. One question through two doors, and the answer\'s shape follows what you pass; a parameter meant for the other door is ignored rather than refused. WITH a query: ranked matches, each a semantic id (artifact id / file:line) with a short preview, ready to feed into map_connections, map_read or map_graph. Its edge over plain text search is graph + artifact awareness, so prefer it for CONCEPTUAL queries ("where is framing decided") and use native grep for literal strings. Multi-word queries return one row per file and come back empty with guidance when nothing clears the relevance floor; a single word is an identifier lookup with symbol-level results. Reach for this (+ map_read) FIRST when planning a BUILD-NEW task, where there is no existing code for map_scope or map_connections to work from. WITHOUT a query: one page of everything, in a stable order (type then id, so paging never skips or repeats), each thing saying what it sits inside and, where it declares one, its own status \u2014 plus `types`, every type in the WHOLE map with its count, so a caller can offer a filter without a second call. Ranking is right for FINDING something and wrong for SEEING everything, so use this door to open the map and look at it, to learn what types a repo maps, or to check what one actually holds. Examples: {} \xB7 {"type":"decision"} \xB7 {"limit":50,"offset":50} \xB7 {"query":"camera framing"} \xB7 {"query":"where the graph ends and its overlay begins","deep":true}.',
+    metadata: { readOnly: true },
+    input: {
+      type: "object",
+      properties: {
+        query: {
+          type: "string",
+          description: "Natural-language search terms. ABSENT (or blank) IS the browse: everything, unranked, in a stable order."
+        },
+        type: {
+          type: "string",
+          description: "Restrict to one node type (e.g. 'decision'). Valid at either door; omit for every type."
+        },
+        limit: limit("Max results. Default 10 ranked \xB7 100 browsing."),
+        offset: {
+          type: "integer",
+          minimum: 0,
+          description: "BROWSING ONLY \u2014 skip this many, for paging past `limit`. A ranked list has no stable page to resume from. Default 0."
+        },
+        fields: {
+          type: "array",
+          items: { type: "string" },
+          description: "BROWSING ONLY \u2014 extra keys this repo's own records carry, returned untouched under `fields`. Nothing here is interpreted: ask for what a repo writes (e.g. ['met'], ['priority']) when you want it beside the thing rather than after a read."
+        },
+        expand: {
+          type: "boolean",
+          description: "QUERY ONLY \u2014 broaden recall: pull a 1-hop citation/community frontier around the top semantic matches before ranking (needs semantic search configured; best with a reranker). Default false."
+        },
+        deep: {
+          type: "boolean",
+          description: 'QUERY ONLY \u2014 re-rank the head with a cross-encoder precision pass (needs a configured reranker; slower). Use ONLY for ABSTRACT governance questions \u2014 "why/where is X decided or governed" \u2014 that a plain search buries; it mis-ranks code and identifier lookups. Default false.'
+        }
+      }
+    },
+    call: (ctx, input) => handlers.search(ctx, input)
+  };
+}
+function readTool(handlers) {
+  return {
+    name: "map_read",
+    title: "Read an artifact",
+    description: `Reads the FULL text of a governance artifact (decision, standard, spec, \u2026) by id \u2014 what map_scope or map_connections surfaced as governing some code. Those tell you D87 applies; this tells you what D87 actually SAYS. Returns the artifact's source markdown (frontmatter included), truncated to maxChars. For artifacts only \u2014 read code files directly. Examples: {"id":"D87"} \xB7 {"id":"D87","maxChars":40000}.`,
+    metadata: { readOnly: true },
+    input: {
+      type: "object",
+      properties: {
+        id: {
+          type: "string",
+          description: 'An artifact id, e.g. "D87" (discover ids with map_search/map_connections).'
+        },
+        maxChars: {
+          type: "integer",
+          minimum: 200,
+          maximum: 1e5,
+          description: "Truncate the body to this many chars. Default 20000."
+        }
+      },
+      required: ["id"]
+    },
+    call: (ctx, input) => handlers.read(ctx, input)
+  };
+}
+function graphTool(handlers) {
+  return {
+    name: "map_graph",
+    title: "Explore graph connections",
+    description: 'Explores how the graph connects. action:\'impact\' returns everything reachable within `depth` hops (the blast radius of a change \u2014 run it BEFORE editing), summarised by type; action:\'neighbors\' lists direct links ONE hop out \u2014 every edge, settled or not, in one flat list. When the question is what open WORK touches something, use map_connections instead: a file usually carries no edge to anything tracked because it sits INSIDE something that does, and only that tool takes the second hop; action:\'path\' finds the shortest connection between `node` and `to`; action:\'hubs\' ranks the most-connected nodes (coupling hotspots / god-nodes); action:\'community\' returns the cluster a node belongs to, or \u2014 with no `node` \u2014 the clusters by size. neighbors/impact/path need `node` (a file path or artifact id); hubs/community can scan the whole graph. Outputs are bounded \u2014 page through a large neighbors/impact result with `offset` (offset:0,limit:25 then offset:25,... while `truncated` is true; `total` says when to stop). Examples: {"action":"impact","node":"packages/art/src/camera.ts"} \xB7 {"action":"hubs","type":"code"}.',
+    metadata: { readOnly: true },
+    input: {
+      type: "object",
+      properties: {
+        action: {
+          type: "string",
+          enum: ["neighbors", "impact", "path", "hubs", "community"],
+          description: "neighbors | impact (blast radius) | path | hubs (coupling hotspots) | community (clusters)."
+        },
+        node: {
+          type: "string",
+          description: "Start node (file path or artifact id). Required for neighbors/impact/path; optional for hubs/community."
+        },
+        to: { type: "string", description: "End node for action:'path'." },
+        relation: {
+          type: "string",
+          description: "Restrict traversal to one relation (e.g. 'enforces'). See map_brief {include:[.shape.]}."
+        },
+        depth: {
+          type: "integer",
+          minimum: 1,
+          maximum: 5,
+          description: "Hops for neighbors/impact. Default 1 / 2."
+        },
+        type: {
+          type: "string",
+          description: "Restrict hubs/community to one node type (e.g. 'code')."
+        },
+        limit: limit("Max results. Default 25."),
+        offset: {
+          type: "integer",
+          minimum: 0,
+          description: "Skip this many neighbors/impact results (paging past `limit`). Default 0."
+        },
+        confidence: CONFIDENCE
+      },
+      required: ["action"]
+    },
+    call: (ctx, input) => handlers.graph(ctx, input)
+  };
+}
+function connectionsTool(handlers) {
+  return {
+    name: "map_connections",
+    title: "What one thing connects to",
+    description: 'What ONE thing connects to \u2014 both the work touching it and the governance it is read against. For when you already have a starting point, where map_search with no query is for when you have none. Point it at anything: a rule, a criterion, a file, a work item, a machine. Returns `items` (connected things carrying a status, filtered to those still OPEN by default \u2014 status:\'all\' includes settled ones, whose count is always reported as `settled`) and `context` (things carrying no status \u2014 what this is read against rather than what is being done to it). So one call answers both directions: ask about a RULE and get the open work touching it plus the code enforcing it; ask about a FILE and get why it exists \u2014 the artifacts it cites. Use it BEFORE changing unfamiliar existing code; a build-new task has nothing to connect yet, so prefer map_search + map_read. Direction is inferred from what you pass, and `direction` narrows it to one side. Where nothing carrying a status connects directly \u2014 usually a code file, which sits INSIDE something tracked rather than being tracked itself \u2014 it steps through one statusless neighbour and each result names that neighbour as `via`, so a regional answer is never mistaken for a file-precise one. Two hops and no further. Walks every edge by default because a circumstantial edge is a poor gate and a good lead; pass confidence:\'precise\' to ask the citation question narrowly. Artifact hits carry a short preview; map_read gives the full text. Prefer this over map_graph{action:\'neighbors\'} for what is LIVE; reach for map_graph for raw structure \u2014 blast radius, a shortest path, the most-coupled nodes. Examples: {"node":"D-9"} \xB7 {"node":"src/camera.ts"} \xB7 {"node":"D-9","status":"all"}.',
+    metadata: { readOnly: true },
+    input: {
+      type: "object",
+      properties: {
+        node: {
+          type: "string",
+          description: "The thing to ask about \u2014 an artifact id, or a repo-relative file path."
+        },
+        status: {
+          type: "string",
+          enum: ["open", "all"],
+          description: "Which connected things to return. 'open' (default) drops the ones already settled (done/dropped) and reports how many; 'all' keeps them."
+        },
+        direction: {
+          type: "string",
+          enum: ["auto", "to-code", "to-artifacts"],
+          description: "Narrow `context` to one side. Default auto \u2014 everything one hop out."
+        },
+        confidence: CONFIDENCE,
+        limit: limit("Max connected things returned. Default 25.")
+      },
+      required: ["node"]
+    },
+    call: (ctx, input) => handlers.connections(ctx, input)
+  };
+}
+function memoryTool(handler) {
+  return {
+    name: "map_memory",
+    title: "Record or delete an agent memory",
+    description: `RECORD (op:"write", the default) or DELETE (op:"delete") a generic agent memory \u2014 a fact/connection the extractors can't derive, held as an overlay node + edges in the graph. One tool, one operation param (mirrors map_graph). Two-step by design: call WITHOUT confirm for a preview (writes nothing), then confirm:true to commit (append-only, audited, persisted via the storage seam). Write links a memory to existing files (by path) or artifacts (by id); a link that doesn't resolve is reported, not silently dropped. Reconciled on rebuild \u2014 a memory whose links no longer resolve is kept and flagged, never silently dropped. Delete needs the memory's id. Not for repo task management. Examples: {"text":"Prod DB pool caps at 20 \u2014 tune via DATABASE_POOL_MAX","links":[{"to":"src/config.ts"}]} \xB7 {"op":"write","text":"D87 supersedes the old cache key format","links":[{"to":"D87"}],"confirm":true} \xB7 {"op":"delete","id":"mem-...","confirm":true}.`,
+    metadata: { readOnly: false },
+    input: {
+      type: "object",
+      properties: {
+        op: {
+          type: "string",
+          enum: ["write", "delete"],
+          description: 'The operation. Default "write".'
+        },
+        text: {
+          type: "string",
+          minLength: 1,
+          description: "The memory text (write only \u2014 its title/body)."
+        },
+        type: {
+          type: "string",
+          description: 'The memory node type (data \u2014 note/insight/decision/task/\u2026). Default "note".'
+        },
+        links: {
+          type: "array",
+          items: {
+            type: "object",
+            properties: { to: { type: "string" }, relation: { type: "string" } },
+            required: ["to"]
+          },
+          description: "Connections to existing graph nodes (files by path, artifacts by id). Write only."
+        },
+        id: {
+          type: "string",
+          description: "Stable id. Required for op:delete; for write, derived from text if omitted (re-write updates in place)."
+        },
+        rationale: { type: "string", description: "Rationale recorded in the append-only audit." },
+        confirm: {
+          type: "boolean",
+          description: "COMMIT the operation. Omitted/false \u2192 a dry-run preview, nothing persisted."
+        }
+      }
+    },
+    call: (ctx, input) => handler(ctx, input)
+  };
+}
+
+// ../../packages/data/src/ladder.ts
+function workLadder(graph) {
+  const items = [];
+  for (const node of graph.nodes()) {
+    if (typeof node.metadata.statusCategory === "string") items.push(node);
+  }
+  const isItem = new Set(items.map((item) => item.id));
+  const containers = /* @__PURE__ */ new Set();
+  const holders = /* @__PURE__ */ new Map();
+  for (const item of items) {
+    for (const edge of graph.edges({ from: item.id, relation: "belongs_to" })) {
+      if (!isItem.has(edge.to)) continue;
+      containers.add(edge.to);
+      holders.set(item.id, edge.to);
+    }
+  }
+  const children = /* @__PURE__ */ new Map();
+  const roots = [];
+  for (const item of items) {
+    const home = holders.get(item.id);
+    if (home === void 0) {
+      roots.push(item);
+      continue;
+    }
+    const bucket = children.get(home) ?? { containers: [], leaves: [] };
+    (containers.has(item.id) ? bucket.containers : bucket.leaves).push(item);
+    children.set(home, bucket);
+  }
+  const members = /* @__PURE__ */ new Map();
+  for (const item of items) {
+    if (containers.has(item.id)) continue;
+    const category = String(item.metadata.statusCategory);
+    const seen = /* @__PURE__ */ new Set([item.id]);
+    let home = holders.get(item.id);
+    while (home !== void 0 && !seen.has(home)) {
+      seen.add(home);
+      const rollup = members.get(home) ?? {};
+      rollup[category] = (rollup[category] ?? 0) + 1;
+      members.set(home, rollup);
+      home = holders.get(home);
+    }
+  }
+  return { items, containers, holders, children, members, roots };
+}
+function leavesOf(ladder) {
+  return ladder.items.filter((item) => !ladder.containers.has(item.id));
+}
+
+// ../../packages/data/src/mcp/tools/cache.ts
+import { statSync } from "fs";
+import { resolve as resolve2 } from "path";
+var cache = /* @__PURE__ */ new WeakMap();
+async function cachedEnforcerDiags(ctx, freshPaths) {
+  const hit = cache.get(ctx);
+  if (hit && isFresh(hit, ctx.config.repoRoot, freshPaths)) {
+    process.stderr.write("[data] lint: reused snapshot result\n");
+    return hit.diags;
+  }
+  const snapshot = {
+    at: Date.now(),
+    diags: runEnforcers(ctx.config, ctx.graph)
+  };
+  cache.set(ctx, snapshot);
+  return snapshot.diags;
+}
+function isFresh(snapshot, repoRoot, freshPaths) {
+  if (!freshPaths || freshPaths.length === 0) return true;
+  for (const path of freshPaths) {
+    let mtimeMs;
+    try {
+      mtimeMs = statSync(resolve2(repoRoot, path)).mtimeMs;
+    } catch {
+      return false;
+    }
+    if (mtimeMs > snapshot.at) return false;
+  }
+  return true;
+}
+
+// ../../packages/data/src/mcp/tools/shared.ts
+function hops(ctx, id, relation, edgeOk) {
+  let list = ctx.graph.hops(id);
+  if (relation) list = list.filter((h) => h.relation === relation);
+  if (edgeOk) list = list.filter(edgeOk);
+  return list;
+}
+function bfs(ctx, startIds, depth, relation, edgeOk) {
+  const seen = new Set(startIds);
+  let frontier = [...startIds];
+  const out = [];
+  for (let d = 0; d < depth && frontier.length; d++) {
+    const next = [];
+    for (const id of frontier) {
+      for (const hop of hops(ctx, id, relation, edgeOk)) {
+        if (seen.has(hop.to)) continue;
+        seen.add(hop.to);
+        out.push(hop.to);
+        next.push(hop.to);
+      }
+    }
+    frontier = next;
+  }
+  return out;
+}
+function shortestPath(ctx, startIds, endIds, relation, edgeOk) {
+  const prev = /* @__PURE__ */ new Map();
+  const seen = new Set(startIds);
+  let frontier = [...startIds];
+  let hit = startIds.find((id) => endIds.has(id));
+  while (!hit && frontier.length) {
+    const next = [];
+    for (const id of frontier) {
+      for (const hop of hops(ctx, id, relation, edgeOk)) {
+        if (seen.has(hop.to)) continue;
+        seen.add(hop.to);
+        prev.set(hop.to, { from: id, relation: hop.relation });
+        if (endIds.has(hop.to)) {
+          hit = hop.to;
+          break;
+        }
+        next.push(hop.to);
+      }
+      if (hit) break;
+    }
+    frontier = next;
+  }
+  if (!hit) return null;
+  const chain = [];
+  let cur = hit;
+  while (cur) {
+    const node = ctx.graph.node(cur);
+    const step = prev.get(cur);
+    if (node) chain.unshift({ node, ...step ? { relation: step.relation } : {} });
+    cur = step?.from;
+  }
+  return chain;
+}
+var MAX_LIMIT = 200;
+function clampLimit(value, fallback) {
+  if (value === void 0 || !Number.isFinite(value)) return fallback;
+  return Math.max(1, Math.min(MAX_LIMIT, Math.floor(value)));
+}
+function clampDepth(value, fallback) {
+  if (value === void 0 || !Number.isFinite(value)) return fallback;
+  return Math.max(1, Math.min(5, Math.floor(value)));
+}
+function clampOffset(value, fallback) {
+  if (value === void 0 || !Number.isFinite(value)) return fallback;
+  return Math.max(0, Math.floor(value));
+}
+
+// ../../packages/data/src/mcp/tools/lint.ts
+async function lint(ctx, req) {
+  const limit2 = clampLimit(req.limit, 50);
+  const enforcerDiags = await cachedEnforcerDiags(ctx);
+  const all = [...ctx.buildDiagnostics, ...enforcerDiags];
+  const filtered = all.filter(
+    (d) => (!req.severity || d.severity === req.severity) && (!req.rule || d.code === req.rule || d.plugin === req.rule)
+  );
+  const counts = { error: 0, warn: 0, info: 0 };
+  const byRule = {};
+  for (const d of filtered) {
+    counts[d.severity] += 1;
+    byRule[d.code] = (byRule[d.code] ?? 0) + 1;
+  }
+  const diagnostics = filtered.slice(0, limit2).map((d) => ({
+    severity: d.severity,
+    rule: d.code,
+    message: d.message,
+    ...d.nodeId !== void 0 ? { nodeId: d.nodeId } : {},
+    ...d.file !== void 0 ? { file: d.file } : {},
+    ...d.line !== void 0 ? { line: d.line } : {},
+    ...d.data !== void 0 ? { data: d.data } : {}
+  }));
+  return {
+    summary: `${counts.error} error(s), ${counts.warn} warning(s), ${counts.info} info across ${Object.keys(byRule).length} rule(s).`,
+    counts,
+    byRule,
+    diagnostics,
+    total: filtered.length,
+    truncated: filtered.length > diagnostics.length
+  };
+}
+
+// ../../packages/data/src/mcp/tools/brief.ts
+async function brief(ctx, req) {
+  const detailed = req.format === "detailed";
+  const itemCap = detailed ? 20 : 8;
+  const listCap = detailed ? 10 : 5;
+  const want = new Set(req.include ?? []);
+  const wantDiag = want.has("diagnostics");
+  const wantShape = want.has("shape");
+  const f = await freshness(ctx);
+  const originsFresh = await federatedFreshness(ctx);
+  const staleOrigins = originsFresh.filter((o) => o.behindOwnHead);
+  let artifacts = 0;
+  const communityCounts = /* @__PURE__ */ new Map();
+  const nodesByType = {};
+  for (const n of ctx.graph.nodes()) {
+    if (!isCode(ctx, n)) artifacts += 1;
+    const community2 = n.metadata.community;
+    if (typeof community2 === "string" && community2) {
+      communityCounts.set(community2, (communityCounts.get(community2) ?? 0) + 1);
+    }
+    if (wantShape) nodesByType[n.type] = (nodesByType[n.type] ?? 0) + 1;
+  }
+  const ladder = workLadder(ctx.graph);
+  const leaves = leavesOf(ladder);
+  const byCategory = {};
+  const inFlight = [];
+  for (const item of leaves) {
+    const category = String(item.metadata.statusCategory);
+    byCategory[category] = (byCategory[category] ?? 0) + 1;
+    if (category === "in-progress")
+      inFlight.push(renderWorkItem(ctx, item, ladder.holders.get(item.id)));
+  }
+  const openItems = leaves.filter((i) => i.metadata.statusCategory === "open");
+  for (const item of openItems.slice(0, Math.max(0, itemCap - inFlight.length))) {
+    inFlight.push(renderWorkItem(ctx, item, ladder.holders.get(item.id)));
+  }
+  const shown = inFlight.slice(0, itemCap);
+  const allContainers = [...ladder.containers].map((id) => ctx.graph.node(id)).filter((n) => n !== void 0).map((n) => ({
+    id: n.id,
+    ...labelOf(n) ? { title: labelOf(n) } : {},
+    type: n.type,
+    statusCategory: String(n.metadata.statusCategory ?? "unknown"),
+    members: ladder.members.get(n.id) ?? {},
+    ...ladder.holders.get(n.id) ? { belongsTo: ladder.holders.get(n.id) } : {}
+  })).sort(byContainerRelevance);
+  const containers = allContainers.slice(0, listCap);
+  const cited = [];
+  for (const n of ctx.graph.nodes()) {
+    if (isCode(ctx, n) || typeof n.metadata.statusCategory === "string") continue;
+    const count = ctx.graph.edges({ to: n.id }).filter((e) => isPrecise(e, ctx.backendName)).length;
+    if (count > 0) cited.push({ node: n, citedBy: count });
+  }
+  cited.sort((a, b) => b.citedBy - a.citedBy);
+  const knowledge = cited.slice(0, listCap).map(({ node, citedBy }) => ({
+    id: node.id,
+    ...labelOf(node) ? { title: labelOf(node) } : {},
+    type: node.type,
+    citedBy
+  }));
+  const diagCap = wantDiag ? detailed ? 50 : 20 : 1;
+  const health = await lint(ctx, { limit: diagCap });
+  const diagnostics = wantDiag ? {
+    lints: health.diagnostics.filter((d) => !req.severity || d.severity === req.severity),
+    truncated: health.truncated
+  } : void 0;
+  let shape;
+  if (wantShape) {
+    const edgesByRelation = {};
+    let preciseEdges = 0;
+    for (const e of ctx.graph.edges()) {
+      edgesByRelation[e.relation] = (edgesByRelation[e.relation] ?? 0) + 1;
+      if (isPrecise(e, ctx.backendName)) preciseEdges += 1;
+    }
+    shape = {
+      graphJson: {
+        path: f.graphPath,
+        ...f.mtimeIso ? { mtime: f.mtimeIso } : {},
+        ...f.behindHead !== void 0 ? { stale: f.behindHead } : {}
+      },
+      preciseEdges,
+      nodesByType,
+      edgesByRelation
+    };
+  }
+  const areas = [...communityCounts.entries()].map(([name, size]) => ({ name, size })).sort((a, b) => b.size - a.size).slice(0, listCap);
+  const inProgressCount = byCategory["in-progress"] ?? 0;
+  return {
+    summary: `${leaves.length} work item(s) \u2014 ${inProgressCount} in flight, ${byCategory["open"] ?? 0} open, ${byCategory["done"] ?? 0} done. ${artifacts} knowledge artifact(s); health: ${health.counts.error} error(s), ${health.counts.warn} warning(s)${f.stale ? " \u2014 GRAPH IS STALE, run `jarvis build graph` (incremental) before trusting details" : ""}${staleOrigins.length ? ` \u2014 ${staleOrigins.map((o) => o.origin).join(", ")} behind their own HEAD (re-run \`jarvis build graph\` there, then re-merge)` : ""}.`,
+    freshness: {
+      builtAt: ctx.builtAt,
+      ...f.head ? { head: { commit: f.head.commit, dirty: f.head.dirty } } : {},
+      ...f.stale !== void 0 ? { stale: f.stale } : {},
+      ...originsFresh.length ? { federated: originsFresh } : {}
+    },
+    graph: { nodes: ctx.graph.nodes().length, artifacts, edges: ctx.graph.edges().length },
+    work: {
+      total: leaves.length,
+      byCategory,
+      containers,
+      inFlight: shown,
+      truncated: inFlight.length > shown.length || allContainers.length > containers.length
+    },
+    knowledge,
+    health: { ...health.counts, byRule: health.byRule },
+    ...diagnostics ? { diagnostics } : {},
+    ...wantShape ? { shape } : {},
+    areas,
+    nextSteps: [
+      'scope {"task":"\u2026"} \u2014 edit set + governing decisions + blast radius before editing',
+      'read {"id":"D-nn"} \xB7 trace {"target":"\u2026"} \u2014 the full rule \xB7 why a file exists (a summary is not the rule)',
+      'review {"edits":[\u2026]} \u2014 verify the edit-set against governance before you commit'
+    ]
+  };
+}
+function byContainerRelevance(a, b) {
+  const flight = (c) => c.members["in-progress"] ?? 0;
+  const size = (c) => Object.values(c.members).reduce((sum, n) => sum + n, 0);
+  return flight(b) - flight(a) || size(b) - size(a) || a.id.localeCompare(b.id);
+}
+function renderWorkItem(ctx, item, home) {
+  const priority = item.metadata.priority;
+  const dependsOn = ctx.graph.edges({ from: item.id, relation: "depends_on" }).map((e) => e.to);
+  return {
+    id: item.id,
+    ...labelOf(item) ? { title: labelOf(item) } : {},
+    type: item.type,
+    ...typeof item.metadata.status === "string" ? { status: item.metadata.status } : {},
+    statusCategory: String(item.metadata.statusCategory),
+    ...typeof priority === "string" ? { priority } : {},
+    ...dependsOn.length ? { dependsOn } : {},
+    ...home !== void 0 ? { belongsTo: home } : {}
+  };
+}
+
+// ../../packages/data/src/resolve.ts
+function resolveTarget(ctx, input) {
+  const direct = ctx.graph.node(input);
+  if (direct && !isCode(ctx, direct)) return { type: "artifact", node: direct };
+  const exact = [];
+  const suffix = [];
+  for (const n of ctx.graph.nodes()) {
+    const f = fileOf(n);
+    if (!f) continue;
+    if (f === input) exact.push(n);
+    else if (f.endsWith(`/${input}`) || f.endsWith(input)) suffix.push(n);
+  }
+  const matched = exact.length ? exact : suffix;
+  const first = matched[0];
+  if (first) return { type: "file", path: fileOf(first) ?? input, nodes: matched };
+  return { type: "unknown", input };
+}
+
+// ../../packages/data/src/mcp/tools/connections.ts
+var SETTLED = /* @__PURE__ */ new Set(["done", "dropped"]);
+function render(ctx, node, via) {
+  const preview = previewOf(node);
+  const status2 = statusOf(node);
+  return {
+    ...renderNode(ctx, node),
+    ...preview ? { preview } : {},
+    ...status2 ? { status: status2, statusCategory: categoryOf(status2) } : {},
+    ...via ? { via } : {}
+  };
+}
+function wants(ctx, node, direction) {
+  if (!direction || direction === "auto") return true;
+  return isCode(ctx, node) === (direction === "to-code");
+}
+function listConnections(ctx, req) {
+  const limit2 = clampLimit(req.limit, 25);
+  const keepSettled = req.status === "all";
+  const edgeOk = (hop) => hopPasses(ctx, hop, req.confidence ?? "all", req.origin);
+  const resolved = resolveTarget(ctx, req.node);
+  if (resolved.type === "unknown") {
+    return {
+      summary: `Nothing in the map matched "${req.node}".`,
+      items: [],
+      settled: 0,
+      context: [],
+      total: 0,
+      truncated: false
+    };
+  }
+  const startIds = resolved.type === "artifact" ? [resolved.node.id] : resolved.nodes.map((n) => n.id);
+  const start = ctx.graph.node(startIds[0] ?? "");
+  const statusOf0 = start ? statusOf(start) : void 0;
+  const seen = new Set(startIds);
+  const withStatus = /* @__PURE__ */ new Map();
+  const context = /* @__PURE__ */ new Map();
+  let settled = 0;
+  const take = (id, via) => {
+    if (seen.has(id)) return false;
+    seen.add(id);
+    const node = ctx.graph.node(id);
+    if (!node) return false;
+    const status2 = statusOf(node);
+    if (status2 === void 0) {
+      if (via === void 0 && wants(ctx, node, req.direction)) {
+        const thing = render(ctx, node);
+        const key = thing.id ?? thing.file ?? id;
+        if (!context.has(key)) context.set(key, thing);
+      }
+      return true;
+    }
+    if (!keepSettled && SETTLED.has(categoryOf(status2))) {
+      settled += 1;
+      return false;
+    }
+    withStatus.set(id, render(ctx, node, via));
+    return false;
+  };
+  const stepThrough = [];
+  for (const id of startIds) {
+    for (const hop of ctx.graph.hops(id)) {
+      if (edgeOk(hop) && take(hop.to)) stepThrough.push(hop.to);
+    }
+  }
+  if (statusOf0 === void 0) {
+    for (const step of stepThrough) {
+      for (const hop of ctx.graph.hops(step)) {
+        if (edgeOk(hop)) take(hop.to, step);
+      }
+    }
+  }
+  const ordered = [...withStatus.values()].sort(
+    (a, b) => Number(Boolean(a.via)) - Number(Boolean(b.via)) || (a.type ?? "").localeCompare(b.type ?? "") || (a.id ?? a.file ?? "").localeCompare(b.id ?? b.file ?? "")
+  );
+  const page = ordered.slice(0, limit2);
+  const label = start ? labelOf(start) ?? start.id : req.node;
+  const read2 = [...context.values()];
+  const nothing = ordered.length === 0 && read2.length === 0;
+  return {
+    summary: nothing ? `Nothing in the map connects to ${label}.` : `${label} connects to ${ordered.length} thing(s) still open${settled > 0 ? ` (and ${settled} settled)` : ""}${read2.length > 0 ? `, plus ${read2.length} it is read against` : ""}.${ordered.length === 0 ? " Nothing open is on it." : ""}`,
+    ...start ? { node: renderNode(ctx, start) } : {},
+    items: page,
+    settled,
+    context: read2,
+    total: ordered.length,
+    truncated: page.length < ordered.length
+  };
+}
+
+// ../../packages/data/src/mcp/tools/graph.ts
+function graphExplore(ctx, req) {
+  const limit2 = clampLimit(req.limit, 25);
+  const confidence = req.confidence ?? "precise";
+  const edgeOk = (h) => hopPasses(ctx, h, confidence, req.origin);
+  if (req.action === "hubs") return hubs(ctx, req, limit2);
+  if (req.action === "community") return community(ctx, req, limit2);
+  if (!req.node) {
+    return {
+      summary: `\`${req.action}\` requires a \`node\` (an artifact id or a file path).`,
+      action: req.action
+    };
+  }
+  const resolved = resolveTarget(ctx, req.node);
+  if (resolved.type === "unknown") {
+    return {
+      summary: `No artifact or file matched "${req.node}".`,
+      action: req.action
+    };
+  }
+  const startIds = resolved.type === "artifact" ? [resolved.node.id] : resolved.nodes.map((n) => n.id);
+  if (req.action === "path") {
+    if (!req.to)
+      return {
+        summary: "`path` requires a `to` target.",
+        action: "path",
+        path: null
+      };
+    const end = resolveTarget(ctx, req.to);
+    if (end.type === "unknown")
+      return {
+        summary: `No artifact or file matched "${req.to}".`,
+        action: "path",
+        path: null
+      };
+    const endIds = new Set(end.type === "artifact" ? [end.node.id] : end.nodes.map((n) => n.id));
+    const pathEdgeOk = (h) => endIds.has(h.to) ? edgeMatchesConfidence(h, ctx.backendName, confidence) : hopPasses(ctx, h, confidence, req.origin);
+    const found = shortestPath(ctx, startIds, endIds, req.relation, pathEdgeOk);
+    if (!found) {
+      return {
+        summary: `No path from ${req.node} to ${req.to}.`,
+        action: "path",
+        path: null
+      };
+    }
+    return {
+      summary: `Path of ${found.length - 1} hop(s) from ${req.node} to ${req.to}.`,
+      action: "path",
+      path: found.map((s) => ({
+        node: renderNode(ctx, s.node),
+        ...s.relation ? { relation: s.relation } : {}
+      }))
+    };
+  }
+  const depth = req.action === "impact" ? clampDepth(req.depth, 2) : clampDepth(req.depth, 1);
+  const offset = clampOffset(req.offset, 0);
+  const reached = bfs(ctx, startIds, depth, req.relation, edgeOk);
+  const nodes = reached.map((id) => ctx.graph.node(id)).filter((n) => Boolean(n));
+  const byType = {};
+  for (const n of nodes) byType[n.type] = (byType[n.type] ?? 0) + 1;
+  const page = nodes.slice(offset, offset + limit2);
+  const rendered = page.map((n) => renderNode(ctx, n));
+  return {
+    summary: req.action === "impact" ? `${req.node} reaches ${nodes.length} node(s) within ${depth} hop(s).` : `${req.node} has ${nodes.length} neighbor(s).`,
+    action: req.action,
+    nodes: rendered,
+    byType,
+    total: nodes.length,
+    truncated: offset + rendered.length < nodes.length
+  };
+}
+function hubs(ctx, req, limit2) {
+  const pool = (req.type ? ctx.graph.nodes(req.type) : ctx.graph.nodes()).filter(
+    (n) => nodeMatchesOrigin(n, req.origin)
+  );
+  const ranked = pool.map((n) => ({ node: n, degree: ctx.graph.hops(n.id).length })).filter((r) => r.degree > 0).sort((a, b) => b.degree - a.degree);
+  const top = ranked.slice(0, limit2);
+  const busiest = top[0];
+  return {
+    summary: `Top ${top.length} most-connected node(s)${req.type ? ` of type ${req.type}` : ""} (coupling hotspots)${busiest ? ` \u2014 busiest: ${labelOf(busiest.node) ?? busiest.node.id} (${busiest.degree} edges)` : ""}.`,
+    action: "hubs",
+    hubs: top.map((r) => ({ ...renderNode(ctx, r.node), degree: r.degree })),
+    total: ranked.length,
+    truncated: ranked.length > top.length
+  };
+}
+function community(ctx, req, limit2) {
+  if (req.node) {
+    const resolved = resolveTarget(ctx, req.node);
+    if (resolved.type === "unknown") {
+      return {
+        summary: `No artifact or file matched "${req.node}".`,
+        action: "community"
+      };
+    }
+    const seed = resolved.type === "artifact" ? resolved.node : resolved.nodes[0];
+    const name = seed ? str(seed.metadata.community) : "";
+    if (!name) {
+      return {
+        summary: `${req.node} has no community assigned.`,
+        action: "community"
+      };
+    }
+    const members = ctx.graph.nodes().filter((n) => str(n.metadata.community) === name && nodeMatchesOrigin(n, req.origin));
+    const rendered = members.slice(0, limit2).map((n) => renderNode(ctx, n));
+    return {
+      summary: `Community "${name}" has ${members.length} member(s) (the cluster ${req.node} belongs to).`,
+      action: "community",
+      nodes: rendered,
+      total: members.length,
+      truncated: members.length > rendered.length
+    };
+  }
+  const sizes = /* @__PURE__ */ new Map();
+  for (const n of req.type ? ctx.graph.nodes(req.type) : ctx.graph.nodes()) {
+    if (!nodeMatchesOrigin(n, req.origin)) continue;
+    const name = str(n.metadata.community);
+    if (name) sizes.set(name, (sizes.get(name) ?? 0) + 1);
+  }
+  const ranked = [...sizes.entries()].map(([name, size]) => ({ name, size })).sort((a, b) => b.size - a.size);
+  const top = ranked.slice(0, limit2);
+  const largest = top[0];
+  return {
+    summary: `${ranked.length} communit${ranked.length === 1 ? "y" : "ies"}${largest ? ` \u2014 largest: "${largest.name}" (${largest.size})` : ""}.`,
+    action: "community",
+    communities: top,
+    total: ranked.length,
+    truncated: ranked.length > top.length
+  };
+}
+function str(value) {
+  return typeof value === "string" ? value : "";
+}
+
+// ../../packages/data/src/mcp/tools/memory.ts
+async function memory(ctx, req, options = {}) {
+  return (req.op ?? "write") === "delete" ? deleteOp(ctx, req, options) : writeOp(ctx, req, options);
+}
+async function writeOp(ctx, req, options) {
+  const now = options.now ?? (() => (/* @__PURE__ */ new Date()).toISOString());
+  const actor = options.actor ?? "agent";
+  const type = req.type ?? "note";
+  if (req.text === void 0 || req.text.trim() === "") {
+    return errorResponse("write", 'op:"write" needs `text` (the memory to record).');
+  }
+  const id = req.id ?? memoryIdFromText(req.text);
+  const resolved = [];
+  const unresolvedLinks = [];
+  for (const link of req.links ?? []) {
+    const relation = link.relation ?? "about";
+    const target = resolveTarget(ctx, link.to);
+    if (target.type === "artifact") {
+      resolved.push({ to: link.to, targetId: target.node.id, relation });
+    } else if (target.type === "file") {
+      const rep = target.nodes[0];
+      if (rep) resolved.push({ to: link.to, targetId: rep.id, relation });
+      else unresolvedLinks.push(link.to);
+    } else {
+      unresolvedLinks.push(link.to);
+    }
+  }
+  const edges = resolved.map((r) => ({ from: id, to: r.targetId, relation: r.relation }));
+  const preview = {
+    node: { id, type, title: req.text },
+    edges,
+    unresolvedLinks
+  };
+  if (!req.confirm) {
+    const unresolvedNote = unresolvedLinks.length > 0 ? `, ${unresolvedLinks.length} unresolved` : "";
+    return {
+      summary: `Preview: would remember "${req.text}" (${edges.length} link(s)${unresolvedNote}). Pass confirm:true to write.`,
+      op: "write",
+      persisted: false,
+      preview
+    };
+  }
+  const store = await readMemoryStore(ctx.config);
+  const links = resolved.map((r) => ({ to: r.to, relation: r.relation }));
+  const existingIndex = store.memories.findIndex((m) => m.id === id);
+  const existing = existingIndex >= 0 ? store.memories[existingIndex] : void 0;
+  const rec = {
+    id,
+    type,
+    text: req.text,
+    links,
+    origin: "agent",
+    createdAt: existing?.createdAt ?? now(),
+    updatedAt: now(),
+    ...existing?.orphaned !== void 0 ? { orphaned: existing.orphaned } : {}
+  };
+  if (existingIndex >= 0) store.memories[existingIndex] = rec;
+  else store.memories.push(rec);
+  const audit = {
+    at: now(),
+    actor,
+    action: "write",
+    id,
+    ...req.rationale !== void 0 ? { rationale: req.rationale } : {}
+  };
+  store.audit.push(audit);
+  await writeMemoryStore(ctx.config, store);
+  ctx.graph.addNode(memoryNode(rec), "memory");
+  for (const r of resolved)
+    ctx.graph.addEdge({ from: id, to: r.targetId, relation: r.relation }, "memory");
+  ctx.graph.stitch();
+  return {
+    summary: `Remembered "${req.text}" as ${id} (${edges.length} link(s)).`,
+    op: "write",
+    persisted: true,
+    preview,
+    written: { id },
+    audit
+  };
+}
+async function deleteOp(ctx, req, options) {
+  const now = options.now ?? (() => (/* @__PURE__ */ new Date()).toISOString());
+  const actor = options.actor ?? "agent";
+  if (req.id === void 0 || req.id.trim() === "") {
+    return errorResponse("delete", 'op:"delete" needs `id` (the memory to remove).');
+  }
+  const id = req.id;
+  const store = await readMemoryStore(ctx.config);
+  const rec = store.memories.find((m) => m.id === id);
+  if (!rec) {
+    return {
+      summary: `No memory "${id}" to delete.`,
+      op: "delete",
+      persisted: false,
+      preview: { node: { id, type: "", title: "" }, edges: [], unresolvedLinks: [] }
+    };
+  }
+  const edges = [];
+  const unresolvedLinks = [];
+  for (const link of rec.links) {
+    const target = resolveTarget(ctx, link.to);
+    if (target.type === "artifact")
+      edges.push({ from: id, to: target.node.id, relation: link.relation });
+    else if (target.type === "file" && target.nodes[0])
+      edges.push({ from: id, to: target.nodes[0].id, relation: link.relation });
+    else unresolvedLinks.push(link.to);
+  }
+  const preview = {
+    node: { id, type: rec.type, title: rec.text },
+    edges,
+    unresolvedLinks
+  };
+  if (!req.confirm) {
+    return {
+      summary: `Preview: would delete "${rec.text}" (${id}). Pass confirm:true to remove.`,
+      op: "delete",
+      persisted: false,
+      preview
+    };
+  }
+  deleteMemory(store, id);
+  const audit = {
+    at: now(),
+    actor,
+    action: "delete",
+    id,
+    ...req.rationale !== void 0 ? { rationale: req.rationale } : {}
+  };
+  store.audit.push(audit);
+  await writeMemoryStore(ctx.config, store);
+  ctx.graph.removeNode(id);
+  return {
+    summary: `Deleted memory "${rec.text}" (${id}).`,
+    op: "delete",
+    persisted: true,
+    preview,
+    removed: { id },
+    audit
+  };
+}
+function errorResponse(op, summary) {
+  return {
+    summary,
+    op,
+    persisted: false,
+    preview: { node: { id: "", type: "", title: "" }, edges: [], unresolvedLinks: [] }
+  };
+}
+function memoryIdFromText(text) {
+  const slug = text.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 40) || "memory";
+  return `mem-${slug}-${hashText(text)}`;
+}
+function hashText(text) {
+  let h = 5381;
+  for (let i = 0; i < text.length; i++) h = (h << 5) + h + text.charCodeAt(i) | 0;
+  return (h >>> 0).toString(36);
+}
+
+// ../../packages/data/src/mcp/tools/read.ts
+import { readFile } from "fs/promises";
+import { resolve as resolve3 } from "path";
+
+// ../../packages/data/src/meta.ts
+function stringMeta(metadata, path) {
+  const value = metaValue(metadata, path);
+  return typeof value === "string" ? value : void 0;
+}
+function metaValue(metadata, path) {
+  if (!metadata) return void 0;
+  if (Object.prototype.hasOwnProperty.call(metadata, path)) return metadata[path];
+  let current = metadata;
+  for (const part of path.split(".")) {
+    if (!current || typeof current !== "object" || !Object.prototype.hasOwnProperty.call(current, part))
+      return void 0;
+    current = current[part];
+  }
+  return current;
+}
+
+// ../../packages/data/src/mcp/tools/read.ts
+async function read(ctx, req) {
+  const max = clampChars(req.maxChars, 2e4);
+  const resolved = resolveTarget(ctx, req.id);
+  if (resolved.type === "unknown") {
+    return {
+      summary: `No artifact matched "${req.id}". Pass an artifact id like D87 (find one with search).`,
+      found: false
+    };
+  }
+  if (resolved.type === "file") {
+    return {
+      summary: `"${req.id}" is code, not a governance artifact \u2014 read the file directly. read is for artifacts (decisions, standards, \u2026).`,
+      found: false
+    };
+  }
+  const node = resolved.node;
+  if (isCode(ctx, node)) {
+    return {
+      summary: `"${req.id}" is a code node, not an artifact.`,
+      found: false
+    };
+  }
+  const rel = fileOf(node);
+  const title = labelOf(node);
+  const url = stringMeta(node.metadata, "data.url");
+  const preview = stringMeta(node.metadata, "data.preview");
+  const base = {
+    found: true,
+    id: node.id,
+    type: node.type,
+    ...title ? { title } : {},
+    ...rel ? { file: rel } : {},
+    ...url ? { href: url } : {},
+    ...preview ? { preview } : {}
+  };
+  if (!rel) {
+    const excerpt = previewOf(node);
+    return {
+      ...base,
+      summary: `${node.id}${title ? ` (${title})` : ""} has no source file; returning its excerpt.`,
+      ...excerpt ? { body: excerpt } : {}
+    };
+  }
+  try {
+    const full = await readFile(resolve3(ctx.config.repoRoot, rel), "utf8");
+    const span = sectionSpan(node);
+    const stripped = span ? parseFrontmatter(full).body : full;
+    const text = span ? reanchorSection(stripped, node.id) ?? stripped.slice(span[0], span[1]) : full;
+    const truncated = text.length > max;
+    return {
+      ...base,
+      summary: `${node.id}${title ? ` (${title})` : ""} \u2014 ${text.length} chars from ${rel}${span ? " (section)" : ""}${truncated ? ` (truncated to ${max})` : ""}.`,
+      body: truncated ? `${text.slice(0, max)}
+
+\u2026[truncated; ${text.length - max} more chars \u2014 raise maxChars to read the rest]` : text,
+      truncated
+    };
+  } catch (err) {
+    return {
+      ...base,
+      summary: `${node.id} maps to ${rel} but it could not be read: ${err instanceof Error ? err.message : String(err)}.`
+    };
+  }
+}
+function reanchorSection(body, id) {
+  const escaped = id.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const heading = new RegExp(`^(#{1,6})[ \\t]+${escaped}\\b.*$`, "m").exec(body);
+  if (!heading || heading[1] === void 0) return void 0;
+  const level = heading[1].length;
+  const bodyStart = heading.index + heading[0].length;
+  const boundary = new RegExp(`^#{1,${level}}[ \\t]`, "m").exec(body.slice(bodyStart));
+  const end = boundary ? bodyStart + boundary.index : body.length;
+  return body.slice(heading.index, end);
+}
+function sectionSpan(node) {
+  const span = node.metadata.sourceSpan;
+  if (Array.isArray(span) && span.length === 2) {
+    const [start, end] = span;
+    if (typeof start === "number" && typeof end === "number") return [start, end];
+  }
+  return void 0;
+}
+function clampChars(value, fallback) {
+  if (value === void 0 || !Number.isFinite(value)) return fallback;
+  return Math.max(200, Math.min(1e5, Math.floor(value)));
+}
+
+// ../../packages/data/src/scope.ts
+function resolveScopeGovernance(ctx, members, codeNodes) {
+  const out = /* @__PURE__ */ new Map();
+  for (const member of members) {
+    if (!isCode(ctx, member)) out.set(member.id, member);
+  }
+  for (const code of codeNodes) {
+    for (const hop of ctx.graph.hops(code.id)) {
+      const other = ctx.graph.node(hop.to);
+      if (!other || isCode(ctx, other)) continue;
+      if (isPrecise(hop, ctx.backendName)) out.set(other.id, other);
+    }
+  }
+  return [...out.values()];
+}
+function resolveDirectoryGovernance(ctx, path) {
+  let dir = path.includes("/") ? path.slice(0, path.lastIndexOf("/")) : "";
+  for (; ; ) {
+    const siblings = codeNodesInDir(ctx, dir);
+    if (siblings.length > 0) return resolveScopeGovernance(ctx, [], siblings);
+    if (dir === "") return [];
+    const slash = dir.lastIndexOf("/");
+    dir = slash === -1 ? "" : dir.slice(0, slash);
+  }
+}
+function codeNodesInDir(ctx, dir) {
+  const out = [];
+  for (const node of ctx.graph.nodes()) {
+    if (!isCode(ctx, node)) continue;
+    const file = fileOf(node);
+    if (file === void 0) continue;
+    const fileDir = file.includes("/") ? file.slice(0, file.lastIndexOf("/")) : "";
+    if (fileDir === dir) out.push(node);
+  }
+  return out;
+}
+function resolveCoveringCode(ctx, codeNodes) {
+  const ids = new Set(codeNodes.map((n) => n.id));
+  const out = /* @__PURE__ */ new Map();
+  for (const code of codeNodes) {
+    for (const hop of ctx.graph.hops(code.id)) {
+      if (ids.has(hop.to)) continue;
+      const other = ctx.graph.node(hop.to);
+      if (!other || !isCode(ctx, other)) continue;
+      if (!isPrecise(hop, ctx.backendName)) continue;
+      const bucket = out.get(other.id) ?? { node: other, relations: /* @__PURE__ */ new Set() };
+      bucket.relations.add(hop.relation);
+      out.set(other.id, bucket);
+    }
+  }
+  return [...out.values()].map((b) => ({ node: b.node, relations: [...b.relations] }));
+}
+var COVERAGE_VIA_MARKERS = new Set(Object.values(COVERAGE_VIA));
+function coverageViaOf(ctx, codeId, hop) {
+  const query = hop.dir === "out" ? { from: codeId, to: hop.to } : { from: hop.to, to: codeId };
+  for (const edge of ctx.graph.edges(query)) {
+    const via = edge.metadata?.via;
+    if (typeof via === "string" && COVERAGE_VIA_MARKERS.has(via)) return via;
+  }
+  return void 0;
+}
+function hasTestCoverage(ctx, codeNodes) {
+  if (resolveCoveringCode(ctx, codeNodes).length > 0) return true;
+  const ids = new Set(codeNodes.map((n) => n.id));
+  for (const code of codeNodes) {
+    for (const hop of ctx.graph.hops(code.id)) {
+      if (ids.has(hop.to)) continue;
+      const other = ctx.graph.node(hop.to);
+      if (!other || !isCode(ctx, other)) continue;
+      if (coverageViaOf(ctx, code.id, hop) !== void 0) return true;
+    }
+  }
+  return false;
+}
+
+// ../../packages/data/src/mcp/tools/trace.ts
+function trace(ctx, req) {
+  const res = traceOnce(ctx, req);
+  if (res.total > 0 || (req.confidence ?? "precise") !== "precise") return res;
+  const loose = traceOnce(ctx, { ...req, confidence: "all" });
+  if (loose.total === 0) return res;
+  return {
+    ...res,
+    summary: `${res.summary} ${loose.total} discovery-only link(s) exist \u2014 pass confidence:"all" to see them.`
+  };
+}
+function traceOnce(ctx, req) {
+  const limit2 = clampLimit(req.limit, 20);
+  const detailed = req.format === "detailed";
+  const confidence = req.confidence ?? "precise";
+  const resolved = resolveTarget(ctx, req.target);
+  if (resolved.type === "unknown") {
+    return {
+      summary: `No artifact or file matched "${req.target}". Pass an artifact id (e.g. D87) or a repo-relative file path (e.g. packages/art/src/camera.ts).`,
+      target: { id: req.target },
+      direction: "to-artifacts",
+      results: [],
+      total: 0,
+      truncated: false
+    };
+  }
+  if (resolved.type === "artifact") {
+    const byFile = /* @__PURE__ */ new Map();
+    for (const e of ctx.graph.edges({ to: resolved.node.id })) {
+      if (!edgeMatchesConfidence(e, ctx.backendName, confidence)) continue;
+      const from = ctx.graph.node(e.from);
+      if (!from || !isCode(ctx, from) || !nodeMatchesOrigin(from, req.origin)) continue;
+      const file = fileOf(from) ?? from.id;
+      const bucket = byFile.get(file) ?? {
+        relations: /* @__PURE__ */ new Set(),
+        symbols: /* @__PURE__ */ new Set(),
+        nodeIds: [],
+        count: 0
+      };
+      bucket.relations.add(e.relation);
+      const sym = labelOf(from);
+      if (sym) bucket.symbols.add(sym);
+      bucket.nodeIds.push(from.id);
+      bucket.count += occurrencesOf(e);
+      byFile.set(file, bucket);
+    }
+    const all2 = [...byFile.entries()].map(([file, b]) => ({
+      file,
+      relations: [...b.relations],
+      count: b.count,
+      ...b.symbols.size ? { symbols: [...b.symbols].slice(0, 5) } : {},
+      ...detailed ? { nodeIds: b.nodeIds } : {}
+    }));
+    all2.sort((a, b) => b.count - a.count);
+    const results2 = all2.slice(0, limit2);
+    return {
+      summary: `${resolved.node.id} (${labelOf(resolved.node) ?? resolved.node.type}) is referenced by ${all2.length} file(s) across ${countRefs(all2)} citation(s). NEXT: read ${resolved.node.id} for the full text; open a listed file to see the citation in context.`,
+      target: renderNode(ctx, resolved.node, detailed),
+      direction: "to-code",
+      results: results2,
+      total: all2.length,
+      truncated: all2.length > results2.length
+    };
+  }
+  const byArtifact = /* @__PURE__ */ new Map();
+  for (const cn of resolved.nodes) {
+    for (const e of ctx.graph.edges({ from: cn.id })) {
+      if (!edgeMatchesConfidence(e, ctx.backendName, confidence)) continue;
+      const to = ctx.graph.node(e.to);
+      if (!to || isCode(ctx, to) || !nodeMatchesOrigin(to, req.origin)) continue;
+      const bucket = byArtifact.get(to.id) ?? {
+        node: to,
+        relations: /* @__PURE__ */ new Set(),
+        count: 0
+      };
+      bucket.relations.add(e.relation);
+      bucket.count += occurrencesOf(e);
+      byArtifact.set(to.id, bucket);
+    }
+  }
+  const all = [...byArtifact.values()].map((b) => ({
+    id: b.node.id,
+    title: labelOf(b.node),
+    type: b.node.type,
+    relations: [...b.relations],
+    count: b.count,
+    ...previewOf(b.node) ? { preview: previewOf(b.node) } : {},
+    ...detailed ? { nodeIds: [b.node.id] } : {}
+  }));
+  all.sort((a, b) => b.count - a.count);
+  const results = all.slice(0, limit2);
+  return {
+    summary: `${resolved.path} cites ${all.length} artifact(s)${all.length ? `: ${all.slice(0, 5).map((r) => r.id).join(", ")} \u2014 NEXT: read one for the full rule before you change this file` : ""}.`,
+    target: {
+      file: resolved.path,
+      ...detailed ? { nodeIds: resolved.nodes.map((n) => n.id) } : {}
+    },
+    direction: "to-artifacts",
+    results,
+    total: all.length,
+    truncated: all.length > results.length
+  };
+}
+function countRefs(hits) {
+  return hits.reduce((sum, h) => sum + h.count, 0);
+}
+function occurrencesOf(edge) {
+  const n = edge.metadata?.occurrences;
+  return typeof n === "number" && n > 0 ? n : 1;
+}
+
+// ../../packages/data/src/mcp/tools/scope/plan.ts
+function planScope(ctx, req) {
+  const task = req.task ?? "";
+  const symbols = buildSymbolIndex(ctx);
+  const namedGovIds = namedGovernanceIds(task, req.found);
+  const { ranked, conceptDerived } = buildEditSet(
+    ctx,
+    req.found,
+    req.limit,
+    namedGovIds,
+    req.origin
+  );
+  const definitions = definitionEdits(ctx, symbols, task);
+  const definitionFiles = new Set(definitions.map((e) => e.file));
+  const rankedWithDefs = mergeNamedEdits(definitions, ranked, req.limit);
+  const hasEvidence = req.found.some((h) => h.confident !== void 0);
+  const weakCodeFiles = new Set(
+    req.found.filter((h) => h.confident === false && isCodeHit(h)).map((h) => h.file).filter((f) => f !== void 0)
+  );
+  const isLead = (e) => !definitionFiles.has(e.file) && (weakCodeFiles.has(e.file) || conceptDerived.has(e.file));
+  const editSet = hasEvidence ? rankedWithDefs.filter((e) => !isLead(e)) : rankedWithDefs;
+  const leads = hasEvidence ? rankedWithDefs.filter(isLead) : [];
+  const lowConfidence = hasEvidence && editSet.length === 0;
+  const anticipated = [...leads, ...areaDiverseLeads(ctx, req.found, editSet, leads)];
+  const editCodeNodes = codeNodesOf(ctx, editSet);
+  const precise = buildGovernance(ctx, editCodeNodes, req.detailed, req.origin);
+  const governance = [...precise, ...conceptGovernance(ctx, req.found, precise)];
+  const references = buildReferenceSet(ctx, editCodeNodes, governance, req.origin);
+  const testsCovering = buildTestsCovering(ctx, editCodeNodes, req.detailed, req.origin);
+  const blastRadius = buildBlastRadius(ctx, editCodeNodes, req.confidence, req.origin);
+  return {
+    editSet,
+    anticipated,
+    editCodeNodes,
+    governance,
+    references,
+    testsCovering,
+    blastRadius,
+    lowConfidence
+  };
+}
+function isCodeHit(hit) {
+  return hit.file !== void 0 && hit.id === void 0;
+}
+var AREA_LEAD_CAP = 3;
+function areaDiverseLeads(ctx, found, editSet, leads) {
+  const taken = new Set([...editSet, ...leads].map((e) => e.file));
+  const editAreas = /* @__PURE__ */ new Set();
+  for (const e of editSet) {
+    const area = communityOfFile(ctx, e.file);
+    if (area) editAreas.add(area);
+  }
+  const byArea = /* @__PURE__ */ new Map();
+  for (const hit of found) {
+    if (!hit.file || taken.has(hit.file)) continue;
+    const area = communityOfFile(ctx, hit.file);
+    if (!area || editAreas.has(area)) continue;
+    const existing = byArea.get(area);
+    if (!existing || hit.score > (existing.score ?? -Infinity)) {
+      byArea.set(area, {
+        file: hit.file,
+        ...hit.line !== void 0 ? { line: hit.line } : {},
+        score: hit.score,
+        why: `area: ${area}`
+      });
+    }
+  }
+  return [...byArea.values()].sort((a, b) => (b.score ?? 0) - (a.score ?? 0)).slice(0, AREA_LEAD_CAP);
+}
+function communityOfFile(ctx, file) {
+  const resolved = resolveTarget(ctx, file);
+  if (resolved.type !== "file") return void 0;
+  for (const n of resolved.nodes) {
+    const c = n.metadata.community;
+    if (typeof c === "string" && c.length > 0) return c;
+  }
+  return void 0;
+}
+function namedGovernanceIds(task, found) {
+  const words = new Set(
+    task.toLowerCase().split(/[^a-z0-9-]+/).filter(Boolean)
+  );
+  const out = /* @__PURE__ */ new Set();
+  for (const hit of found) if (hit.id && words.has(hit.id.toLowerCase())) out.add(hit.id);
+  return out;
+}
+var NAMED_SYMBOL_CAP = 4;
+function buildSymbolIndex(ctx) {
+  const index = /* @__PURE__ */ new Map();
+  for (const node of ctx.graph.nodes()) {
+    if (!isCode(ctx, node)) continue;
+    const label = labelOf(node);
+    if (!label) continue;
+    const key = label.toLowerCase();
+    const list = index.get(key);
+    if (list) list.push(node);
+    else index.set(key, [node]);
+  }
+  return index;
+}
+function identifierTokens(task) {
+  return task.split(/[^A-Za-z0-9]+/).filter((t) => t.length >= 3 && /[a-z][A-Z]/.test(t));
+}
+function definitionEdits(ctx, symbols, task) {
+  const out = /* @__PURE__ */ new Map();
+  for (const token of identifierTokens(task)) {
+    for (const node of symbols.get(token.toLowerCase()) ?? []) {
+      const file = fileOf(node);
+      if (!file || out.has(file)) continue;
+      const line = lineOf(node);
+      out.set(file, {
+        file,
+        ...line !== void 0 ? { line } : {},
+        why: `defines ${labelOf(node) ?? token}`
+      });
+      if (out.size >= NAMED_SYMBOL_CAP) return [...out.values()];
+    }
+  }
+  return [...out.values()];
+}
+function mergeNamedEdits(front, rest, limit2) {
+  const byFile = /* @__PURE__ */ new Map();
+  for (const e of front) byFile.set(e.file, { ...e });
+  for (const e of rest) {
+    const existing = byFile.get(e.file);
+    if (!existing) {
+      byFile.set(e.file, { ...e });
+      continue;
+    }
+    if (e.why && existing.why && !existing.why.includes(e.why))
+      existing.why = `${existing.why}; ${e.why}`;
+    if (existing.score === void 0 && e.score !== void 0) existing.score = e.score;
+    if (existing.line === void 0 && e.line !== void 0) existing.line = e.line;
+  }
+  return [...byFile.values()].slice(0, limit2);
+}
+function conceptGovernance(ctx, found, precise) {
+  const seen = new Set(precise.map((g) => g.id));
+  const out = [];
+  for (const hit of found) {
+    if (!hit.id || seen.has(hit.id)) continue;
+    const node = ctx.graph.node(hit.id);
+    if (!node || isCode(ctx, node)) continue;
+    seen.add(node.id);
+    const title = labelOf(node);
+    out.push({
+      id: node.id,
+      type: node.type,
+      ...title ? { title } : {},
+      relations: ["concept-match"],
+      score: hit.score
+    });
+  }
+  return out.sort((a, b) => (b.score ?? 0) - (a.score ?? 0));
+}
+var REFERENCE_CAP = 8;
+function buildReferenceSet(ctx, editCodeNodes, governance, origin) {
+  const govIds = new Set(governance.map((g) => g.id));
+  const out = /* @__PURE__ */ new Map();
+  const preciseHops = (id) => ctx.graph.hops(id).filter((h) => h.dir === "out" && edgeMatchesConfidence(h, ctx.backendName, "precise"));
+  const add = (node, why) => {
+    if (!node || govIds.has(node.id) || out.has(node.id) || isCode(ctx, node) || !nodeMatchesOrigin(node, origin))
+      return;
+    const title = labelOf(node);
+    out.set(node.id, { id: node.id, type: node.type, ...title ? { title } : {}, why });
+  };
+  for (const code of editCodeNodes) {
+    for (const h1 of preciseHops(code.id)) {
+      const via = ctx.graph.node(h1.to);
+      if (!via) continue;
+      add(via, "linked from the edit-set");
+      for (const h2 of preciseHops(via.id)) add(ctx.graph.node(h2.to), `via ${via.id}`);
+    }
+  }
+  for (const g of governance) {
+    for (const h of preciseHops(g.id)) add(ctx.graph.node(h.to), `cited by ${g.id}`);
+  }
+  return [...out.values()].slice(0, REFERENCE_CAP);
+}
+function codeNodesOf(ctx, editSet) {
+  const out = [];
+  for (const target of editSet) {
+    const resolved = resolveTarget(ctx, target.file);
+    if (resolved.type === "file") out.push(...resolved.nodes);
+  }
+  return out;
+}
+function buildEditSet(ctx, found, limit2, namedGovIds, origin) {
+  const byFile = /* @__PURE__ */ new Map();
+  const directFiles = /* @__PURE__ */ new Set();
+  const namedGovFiles = /* @__PURE__ */ new Set();
+  for (const hit of found) {
+    if (!hit.file) continue;
+    directFiles.add(hit.file);
+    const existing = byFile.get(hit.file);
+    if (existing) {
+      if (existing.score === void 0 || hit.score > existing.score) existing.score = hit.score;
+      continue;
+    }
+    byFile.set(hit.file, {
+      file: hit.file,
+      ...hit.line !== void 0 ? { line: hit.line } : {},
+      score: hit.score,
+      why: "direct match"
+      // provenance: the query hit this file itself (vs "enforces X" below)
+    });
+  }
+  for (const hit of found) {
+    if (hit.file || !hit.id) continue;
+    const enforcing = trace(ctx, {
+      target: hit.id,
+      confidence: "precise",
+      ...origin ? { origin } : {}
+    });
+    const named = namedGovIds.has(hit.id);
+    for (const r of enforcing.results) {
+      if (!r.file) continue;
+      if (named) namedGovFiles.add(r.file);
+      const why = `enforces ${hit.id}`;
+      const existing = byFile.get(r.file);
+      if (existing) existing.why = existing.why ? `${existing.why}; ${why}` : why;
+      else byFile.set(r.file, { file: r.file, why });
+    }
+  }
+  const ranked = [...byFile.values()];
+  ranked.sort((a, b) => {
+    if (a.score !== void 0 && b.score !== void 0) return b.score - a.score;
+    if (a.score !== void 0) return -1;
+    if (b.score !== void 0) return 1;
+    return a.file.localeCompare(b.file);
+  });
+  const capped = ranked.slice(0, limit2);
+  const conceptDerived = new Set(
+    capped.filter((e) => !directFiles.has(e.file) && !namedGovFiles.has(e.file)).map((e) => e.file)
+  );
+  return { ranked: capped, conceptDerived };
+}
+function buildGovernance(ctx, editCodeNodes, detailed, origin) {
+  const governanceNodes = resolveScopeGovernance(ctx, [], editCodeNodes).filter(
+    (n) => nodeMatchesOrigin(n, origin)
+  );
+  const ranked = governanceNodes.map((node) => {
+    const relations = /* @__PURE__ */ new Set();
+    let linkCount = 0;
+    let score;
+    for (const code of editCodeNodes) {
+      for (const hop of ctx.graph.hops(code.id)) {
+        if (hop.to !== node.id) continue;
+        if (!edgeMatchesConfidence(hop, ctx.backendName, "precise")) continue;
+        relations.add(hop.relation);
+        linkCount++;
+        if (detailed && score === void 0) score = scoreOfHop(ctx, code.id, hop);
+      }
+    }
+    const title = labelOf(node);
+    const ref = {
+      id: node.id,
+      type: node.type,
+      ...title ? { title } : {},
+      relations: [...relations],
+      ...score !== void 0 ? { score } : {}
+    };
+    return { ref, linkCount };
+  });
+  ranked.sort((a, b) => b.linkCount - a.linkCount);
+  return ranked.map((r) => r.ref);
+}
+var FUZZY_COVERAGE_CAP = 8;
+function buildTestsCovering(ctx, editCodeNodes, detailed, origin) {
+  const editIds = new Set(editCodeNodes.map((n) => n.id));
+  const precise = /* @__PURE__ */ new Map();
+  for (const entry of resolveCoveringCode(ctx, editCodeNodes)) {
+    if (!nodeMatchesOrigin(entry.node, origin)) continue;
+    precise.set(entry.node.id, { node: entry.node, relations: new Set(entry.relations) });
+  }
+  const fuzzy = /* @__PURE__ */ new Map();
+  if (detailed) {
+    for (const code of editCodeNodes) {
+      for (const hop of ctx.graph.hops(code.id)) {
+        if (editIds.has(hop.to)) continue;
+        const other = ctx.graph.node(hop.to);
+        if (!other || !isCode(ctx, other) || !nodeMatchesOrigin(other, origin)) continue;
+        if (coverageViaOf(ctx, code.id, hop) === void 0) continue;
+        const existing = precise.get(other.id);
+        if (existing) {
+          existing.relations.add(hop.relation);
+          continue;
+        }
+        const bucket = fuzzy.get(other.id) ?? { node: other, relations: /* @__PURE__ */ new Set() };
+        bucket.relations.add(hop.relation);
+        fuzzy.set(other.id, bucket);
+      }
+    }
+  }
+  const toRef = (b) => {
+    const line = lineOf(b.node);
+    return {
+      file: fileOf(b.node) ?? b.node.id,
+      ...line !== void 0 ? { line } : {},
+      relations: [...b.relations]
+    };
+  };
+  return [...precise.values()].map(toRef).concat([...fuzzy.values()].slice(0, FUZZY_COVERAGE_CAP).map(toRef));
+}
+function buildBlastRadius(ctx, editCodeNodes, confidence, origin) {
+  const startIds = editCodeNodes.map((n) => n.id);
+  const edgeOk = (h) => hopPasses(ctx, h, confidence, origin);
+  const reached = bfs(ctx, startIds, 2, void 0, edgeOk);
+  const byType = {};
+  for (const id of reached) {
+    const node = ctx.graph.node(id);
+    if (node) byType[node.type] = (byType[node.type] ?? 0) + 1;
+  }
+  return { total: reached.length, byType };
+}
+function scoreOfHop(ctx, fromId, hop) {
+  const query = hop.dir === "out" ? { from: fromId, to: hop.to, relation: hop.relation } : { from: hop.to, to: fromId, relation: hop.relation };
+  for (const edge of ctx.graph.edges(query)) {
+    const score = edgeScore(edge);
+    if (score !== void 0) return score;
+  }
+  return void 0;
+}
+
+// ../../packages/data/src/mcp/tools/review.ts
+function isWorkItem(node) {
+  return node?.metadata.statusCategory !== void 0;
+}
+async function review(ctx, req) {
+  const limit2 = clampLimit(req.limit, 50);
+  const cites = new Set(req.cites ?? []);
+  const findings = [];
+  const resolvedFiles = [];
+  const unresolved = [];
+  for (const input of req.edits) {
+    const r = resolveTarget(ctx, input);
+    if (r.type === "file") resolvedFiles.push(r.path);
+    else unresolved.push(input);
+  }
+  const found = resolvedFiles.map((file) => ({ file, score: 1 }));
+  const plan = planScope(ctx, {
+    found,
+    limit: Math.max(found.length, 1),
+    confidence: "precise",
+    detailed: false
+  });
+  for (const g of plan.governance) {
+    if (cites.has(g.id)) continue;
+    if (isWorkItem(ctx.graph.node(g.id))) continue;
+    const rel = g.relations.join("/");
+    findings.push({
+      code: "uncited-governance",
+      severity: "warn",
+      confidence: "precise",
+      subject: g.id,
+      message: `Edit touches code governed by ${g.id}${g.title ? ` (${g.title})` : ""}${rel ? ` via ${rel}` : ""}, but the plan doesn't cite it.`,
+      cites: [g.id]
+    });
+  }
+  const byFile = /* @__PURE__ */ new Map();
+  for (const n of plan.editCodeNodes) {
+    if (!isCode(ctx, n)) continue;
+    const f = fileOf(n) ?? n.id;
+    const list = byFile.get(f);
+    if (list) list.push(n);
+    else byFile.set(f, [n]);
+  }
+  for (const [file, nodes] of req.coverage ? byFile : []) {
+    if (hasTestCoverage(ctx, nodes)) continue;
+    findings.push({
+      code: "uncovered-code",
+      severity: "info",
+      confidence: "precise",
+      subject: file,
+      message: `${file} has no covering test (no colocated test, and no test imports it).`,
+      cites: []
+    });
+  }
+  const resolvedFileSet = new Set(resolvedFiles);
+  const enforcerDiags = resolvedFileSet.size > 0 ? await cachedEnforcerDiags(ctx, [...resolvedFileSet]) : [];
+  for (const d of enforcerDiags) {
+    if (!d.file || !resolvedFileSet.has(d.file)) continue;
+    findings.push({
+      code: d.code,
+      severity: d.severity,
+      confidence: d.severity === "error" ? "precise" : "fuzzy",
+      subject: d.file,
+      message: d.message,
+      cites: []
+    });
+  }
+  for (const path of unresolved) {
+    const dirGov = resolveDirectoryGovernance(ctx, path).filter((n) => !isWorkItem(n)).map((g) => g.id).filter((id) => !cites.has(id)).slice(0, 3);
+    const hint = dirGov.length ? ` Files in its directory are governed by ${dirGov.join(", ")} \u2014 cite if it applies.` : "";
+    findings.push({
+      code: "unresolved-edit",
+      severity: "info",
+      confidence: "precise",
+      subject: path,
+      message: `${path} isn't in the graph yet (a new file, or a path that doesn't match).${hint || " No governed siblings to assess it by."}`,
+      cites: dirGov
+    });
+  }
+  const rank = { error: 0, warn: 1, info: 2 };
+  findings.sort((a, b) => rank[a.severity] - rank[b.severity]);
+  const truncated = findings.length > limit2;
+  const shown = truncated ? findings.slice(0, limit2) : findings;
+  const coverage = { resolved: resolvedFiles.length, unresolved: unresolved.length };
+  const verdict = resolvedFiles.length === 0 && req.edits.length > 0 ? "unassessable" : shown.some(
+    (f) => f.confidence === "precise" && (f.severity === "warn" || f.severity === "error")
+  ) ? "revise" : "approve";
+  const label = req.task ? ` "${req.task}"` : "";
+  const coverageNote = unresolved.length > 0 ? ` ${unresolved.length} of ${req.edits.length} edit(s) new/unresolved.` : "";
+  const refList = plan.references.slice(0, 5).map((r) => r.id).join(", ");
+  const audit = plan.references.length > 0 ? ` Before finalizing: READ ${refList}${plan.references.length > 5 ? " \u2026" : ""}, then self-audit the diff against them + your repo's smell rules (layering, DRY, hardcoded knobs, task-refs).` : "";
+  const summary = verdict === "unassessable" ? `Reviewed${label} (${req.edits.length} edit(s)): unassessable \u2014 none are in the graph yet (all new files / wrong paths), so governance and coverage can't be checked.${audit}` : shown.length === 0 ? `Reviewed${label} (${req.edits.length} edit(s)): clean \u2014 no governance or coverage gaps. approve.${coverageNote}${audit}` : `Reviewed${label} (${req.edits.length} edit(s)): ${shown.length} finding(s). ${verdict}.${coverageNote}${audit}`;
+  return { summary, verdict, coverage, findings: shown, references: plan.references, truncated };
+}
+
+// ../../packages/data/src/mcp/tools/browse.ts
+function browseMap(ctx, req) {
+  const limit2 = clampLimit(req.limit, 100);
+  const offset = Math.max(0, req.offset ?? 0);
+  const ladder = workLadder(ctx.graph);
+  const matched = ctx.graph.nodes(req.type).filter((node) => nodeMatchesOrigin(node, req.origin));
+  const counts = /* @__PURE__ */ new Map();
+  for (const node of ctx.graph.nodes()) {
+    if (!nodeMatchesOrigin(node, req.origin)) continue;
+    counts.set(node.type, (counts.get(node.type) ?? 0) + 1);
+  }
+  const ordered = [...matched].sort(
+    (a, b) => a.type.localeCompare(b.type) || a.id.localeCompare(b.id)
+  );
+  const page = ordered.slice(offset, offset + limit2);
+  return {
+    summary: `${ordered.length} thing(s) in the map${req.type ? ` of type '${req.type}'` : ""}${ordered.length > page.length ? `, showing ${page.length} from ${offset}` : ""}.${page.length > 0 ? " NEXT: read an artifact id for its full text, or trace a file for why it exists." : ""}`,
+    items: page.map((node) => render2(ctx, node, ladder.holders.get(node.id), req.fields)),
+    total: ordered.length,
+    offset,
+    limit: limit2,
+    hasMore: offset + page.length < ordered.length,
+    types: [...counts.entries()].map(([type, total]) => ({ type, total })).sort((a, b) => b.total - a.total || a.type.localeCompare(b.type))
+  };
+}
+function render2(ctx, node, holder, fields) {
+  const preview = previewOf(node);
+  const status2 = statusOf(node);
+  const derived = node.metadata[DERIVED_FROM];
+  const belongsTo = typeof derived === "string" ? derived : holder;
+  const free = pick(node, fields);
+  return {
+    ...renderNode(ctx, node),
+    ...preview ? { preview } : {},
+    ...belongsTo !== void 0 ? { belongsTo } : {},
+    ...status2 ? { status: status2, statusCategory: categoryOf(status2) } : {},
+    ...free ? { fields: free } : {}
+  };
+}
+function pick(node, fields) {
+  if (fields === void 0 || fields.length === 0) return void 0;
+  const free = {};
+  for (const key of fields) {
+    const value = node.metadata[key];
+    if (value !== void 0) free[key] = value;
+  }
+  return Object.keys(free).length > 0 ? free : void 0;
+}
+
+// ../../packages/data/src/mcp/tools/search.ts
+async function search(ctx, req) {
+  const limit2 = clampLimit(req.limit, 10);
+  if (req.query.trim().length === 0)
+    return { summary: "Empty query.", results: [], total: 0, truncated: false };
+  const runtime = await ctx.search();
+  const candidates = ctx.graph.nodes(req.type).filter((n) => nodeMatchesOrigin(n, req.origin));
+  let ranked = await rankNodes({
+    ...runtime ? { runtime } : {},
+    candidates,
+    query: req.query,
+    graph: ctx.graph,
+    ...req.expand !== void 0 ? { expand: req.expand } : {},
+    ...req.deep !== void 0 ? { deep: req.deep } : {}
+  });
+  if (req.origin !== void 0)
+    ranked = ranked.filter((r) => nodeMatchesOrigin(r.node, req.origin));
+  const conceptual = !isSingleTerm(req.query);
+  if (conceptual) {
+    ranked = diversify(ranked, (node) => isCode(ctx, node) ? fileOf(node) ?? node.id : node.id);
+  }
+  const top = ranked.slice(0, limit2);
+  if (conceptual && top.length > 0 && !top.some((r) => isConfident(r, runtime?.confidence))) {
+    return {
+      summary: `No confident match for "${req.query}"${req.type ? ` (type=${req.type})` : ""} \u2014 the graph has nothing that matches these concepts well. Try more specific words or an identifier (symbol, file path, artifact id), restrict with type, or drop the query entirely to see what this map holds.`,
+      results: [],
+      total: 0,
+      truncated: false
+    };
+  }
+  const expanding = Boolean(runtime && (req.expand ?? runtime.expand));
+  const mode = `${runtime ? runtime.hybrid ? "hybrid" : "semantic" : "lexical"}${expanding ? "+expand" : ""}`;
+  return {
+    summary: `${ranked.length} match(es) for "${req.query}"${req.type ? ` (type=${req.type})` : ""} [${mode}].${ranked.length > 0 ? " NEXT: read an artifact id for the full rule, or trace a file for why it exists." : ""}`,
+    results: top.map((r) => {
+      const { node, score, collapsed } = r;
+      const preview = previewOf(node);
+      return {
+        ...renderNode(ctx, node),
+        ...preview ? { preview } : {},
+        // Scores are rank-scale hints; full float precision is noise in an agent's context.
+        score: Math.round(score * 1e3) / 1e3,
+        // Evidence-based: did this hit clear the relevance floor (not just rank high)? Lets a
+        // caller (scope) tell a strongly-located match from rank-noise.
+        confident: isConfident(r, runtime?.confidence),
+        ...collapsed ? { matches: collapsed + 1 } : {}
+      };
+    }),
+    total: ranked.length,
+    truncated: ranked.length > top.length
+  };
+}
+async function searchMap(ctx, req) {
+  const query = req.query?.trim();
+  return query ? search(ctx, { ...req, query }) : browseMap(ctx, req);
+}
+
+// ../../packages/data/src/mcp/tools/scope/scope.ts
+var RULE_BUDGET = 12e3;
+async function readRules(ctx, governance, mode) {
+  if (mode === "ids" || governance.length === 0) {
+    return { full: 0, ids: governance.length };
+  }
+  let spent = 0;
+  let full = 0;
+  for (const ref of governance) {
+    if (spent >= RULE_BUDGET) break;
+    const node = ctx.graph.node(ref.id);
+    if (node && statusOf(node) !== void 0) continue;
+    try {
+      const artifact = await read(ctx, { id: ref.id, maxChars: RULE_BUDGET - spent });
+      if (!artifact.body) continue;
+      if (spent + artifact.body.length > RULE_BUDGET) continue;
+      ref.body = artifact.body;
+      spent += artifact.body.length;
+      full += 1;
+    } catch {
+    }
+  }
+  return { full, ids: governance.length - full };
+}
+async function scope(ctx, req) {
+  const limit2 = clampLimit(req.limit, 5);
+  const detailed = req.format === "detailed";
+  const confidence = req.confidence ?? "precise";
+  const emptyPlan = {
+    editSet: [],
+    anticipatedIntegrationPoints: [],
+    governance: [],
+    references: [],
+    testsCovering: [],
+    blastRadius: { total: 0, byType: {} },
+    lowConfidence: false,
+    rules: { full: 0, ids: 0 }
+  };
+  if (req.task.trim().length === 0)
+    return {
+      summary: "Empty task.",
+      task: req.task,
+      ...emptyPlan,
+      hits: [],
+      total: 0,
+      truncated: false
+    };
+  const found = await search(ctx, {
+    query: req.task,
+    limit: limit2 * 2,
+    ...req.origin ? { origin: req.origin } : {}
+  });
+  if (found.results.length === 0)
+    return {
+      summary: `No nodes matched "${req.task}". Try different wording, or search with a broader query.`,
+      task: req.task,
+      ...emptyPlan,
+      hits: [],
+      total: found.total,
+      truncated: false
+    };
+  const plan = planScope(ctx, {
+    found: found.results,
+    task: req.task,
+    limit: limit2,
+    confidence,
+    detailed,
+    ...req.origin ? { origin: req.origin } : {}
+  });
+  const traceLimit = detailed ? 8 : 4;
+  const impactDepth = 2;
+  const impactSample = detailed ? 6 : 0;
+  const knownIds = /* @__PURE__ */ new Set([
+    ...plan.governance.map((g) => g.id),
+    ...plan.references.map((r) => r.id),
+    ...found.results.slice(0, limit2).map((n) => n.id).filter((id) => id !== void 0)
+  ]);
+  const renderedAbove = /* @__PURE__ */ new Set([
+    ...plan.governance.map((g) => g.id),
+    ...plan.references.map((r) => r.id)
+  ]);
+  const hits = found.results.slice(0, limit2).map((node) => {
+    const target = node.file ?? node.id;
+    if (!target) {
+      return {
+        target: "",
+        node,
+        ok: false,
+        reason: "search hit had no file path or id to chain from."
+      };
+    }
+    try {
+      const tr = trace(ctx, {
+        target,
+        limit: traceLimit,
+        confidence,
+        ...detailed ? { format: "detailed" } : {},
+        ...req.origin ? { origin: req.origin } : {}
+      });
+      const impact = detailed ? graphExplore(ctx, {
+        action: "impact",
+        node: target,
+        depth: impactDepth,
+        ...req.origin ? { origin: req.origin } : {},
+        // As wide a pool as graphExplore itself ever returns (its own `limit` ceiling) —
+        // pickImpactSample below ranks the 6 most informative out of it; total/byType are
+        // unaffected (computed pre-slice). A narrower, formula-derived cap regressed to the
+        // original bug for any hub with more low-value edges than the cap (oss-review):
+        // this is bounded, not unbounded, but a hub would need MORE non-code edges than
+        // graphExplore's own max page size before its first code edge to still come back
+        // thin — at that point `graph`'s own `offset` pagination is the real escape
+        // hatch, not a bigger magic number here.
+        limit: MAX_LIMIT,
+        confidence
+      }) : void 0;
+      return {
+        target,
+        node: idOnlyForKnown([node], renderedAbove)[0] ?? node,
+        ok: true,
+        ...tr.results.length ? { why: idOnlyForKnown(tr.results, knownIds) } : {},
+        ...impact ? {
+          impact: {
+            total: impact.total ?? 0,
+            byType: impact.byType ?? {},
+            ...impactSample && impact.nodes?.length ? {
+              sample: idOnlyForKnown(
+                pickImpactSample(impact.nodes, impactSample),
+                knownIds
+              )
+            } : {}
+          }
+        } : {}
+      };
+    } catch (err) {
+      return { target, node, ok: false, reason: err instanceof Error ? err.message : String(err) };
+    }
+  });
+  const rules = await readRules(ctx, plan.governance, req.rules);
+  const topFiles = plan.editSet.slice(0, 3).map((e) => e.file).join(", ");
+  const topGov = plan.governance.filter((g) => g.body === void 0).slice(0, 3).map((g) => g.id).join(", ");
+  const summary = plan.lowConfidence ? `Low-confidence (build-new) scope for "${req.task}": no code strongly matched \u2014 ${plan.anticipated.length} integration point(s) to READ, not edit; ${plan.governance.length} concept-matched governance. Lead with search + read.` : `Scoped "${req.task}": ${plan.editSet.length} edit target(s), ${plan.governance.length} governance, ${plan.testsCovering.length} covering test(s), blast radius ${plan.blastRadius.total} (${confidence})${topFiles ? ` \u2014 ${topFiles}` : ""}.${rules.ids > 0 && topGov ? ` ${rules.full} rule(s) came back in full; NEXT: read ${topGov} for the ${rules.ids} that did not,` : rules.full > 0 ? ` All ${rules.full} governing rule(s) came back in FULL \u2014 read them here, not with map_read;` : " NEXT:"} then check the edit-set with map_scope {edits} before you commit.`;
+  return {
+    summary,
+    task: req.task,
+    editSet: plan.editSet,
+    anticipatedIntegrationPoints: plan.anticipated,
+    governance: plan.governance,
+    rules,
+    references: plan.references,
+    testsCovering: plan.testsCovering,
+    blastRadius: plan.blastRadius,
+    lowConfidence: plan.lowConfidence,
+    hits,
+    total: found.total,
+    truncated: found.truncated
+  };
+}
+function pickImpactSample(nodes, count) {
+  const preferred = [];
+  const rest = [];
+  for (const n of nodes) (n.file !== void 0 ? preferred : rest).push(n);
+  return [...preferred, ...rest].slice(0, count);
+}
+function idOnlyForKnown(entries, knownIds) {
+  return entries.map((e) => {
+    const known = e.id !== void 0 && knownIds.has(e.id);
+    const redundantNodeId = e.nodeId !== void 0 && e.nodeId === e.id;
+    const redundantNodeIds = e.nodeIds !== void 0 && e.nodeIds.length === 1 && e.nodeIds[0] === e.id;
+    if (!known && !redundantNodeId && !redundantNodeIds) return e;
+    const trimmed = { ...e };
+    if (known) {
+      delete trimmed.title;
+      delete trimmed.preview;
+    }
+    if (redundantNodeId) delete trimmed.nodeId;
+    if (redundantNodeIds) delete trimmed.nodeIds;
+    return trimmed;
+  });
+}
+async function scopeOrReview(ctx, req) {
+  if (req.edits && req.edits.length > 0) return review(ctx, req);
+  if (req.task) return scope(ctx, req);
+  throw new Error(
+    "map_scope needs either `task` (planning a change) or `edits` (verifying one); it received neither."
+  );
+}
+
+// ../../packages/data/src/mcp/tools/status.ts
+async function status(ctx) {
+  const f = await freshness(ctx);
+  const nodesByType = {};
+  let artifacts = 0;
+  for (const n of ctx.graph.nodes()) {
+    nodesByType[n.type] = (nodesByType[n.type] ?? 0) + 1;
+    if (!isCode(ctx, n)) artifacts += 1;
+  }
+  const edges = ctx.graph.edges();
+  const edgesByRelation = {};
+  let preciseEdges = 0;
+  for (const e of edges) {
+    edgesByRelation[e.relation] = (edgesByRelation[e.relation] ?? 0) + 1;
+    if (isPrecise(e, ctx.backendName)) preciseEdges += 1;
+  }
+  return {
+    summary: `${ctx.graph.nodes().length} nodes (${artifacts} artifacts), ${edges.length} edges (${preciseEdges} precise). Built ${ctx.builtAt}${f.head ? `, HEAD ${f.head.commit.slice(0, 8)}${f.head.dirty ? "-dirty" : ""}` : ""}${f.stale ? ` \u2014 ${f.reason ?? "graph is stale \u2014 run `jarvis build graph` (incremental)"}` : ""}.`,
+    builtAt: ctx.builtAt,
+    ...f.head ? { head: { commit: f.head.commit, dirty: f.head.dirty } } : {},
+    graphJson: {
+      path: f.graphPath,
+      ...f.mtimeIso ? { mtime: f.mtimeIso } : {},
+      ...f.behindHead !== void 0 ? { stale: f.behindHead } : {}
+    },
+    ...f.origin ? { origin: f.origin } : {},
+    counts: {
+      nodes: ctx.graph.nodes().length,
+      artifacts,
+      edges: edges.length,
+      preciseEdges
+    },
+    nodesByType,
+    edgesByRelation
+  };
+}
+
+// ../../packages/data/src/mcp/tools/index.ts
+var HANDLERS = {
+  brief: (ctx, req) => brief(ctx, req),
+  scope: (ctx, req) => scopeOrReview(ctx, req),
+  search: (ctx, req) => searchMap(ctx, req),
+  read: (ctx, req) => read(ctx, req),
+  graph: async (ctx, req) => graphExplore(ctx, req),
+  connections: async (ctx, req) => listConnections(ctx, req)
+};
+var TOOLS = [
+  ...dataTools(HANDLERS),
+  memoryTool((ctx, req) => memory(ctx, req))
+];
+
+// ../../packages/data/src/mcp/tools/schema.ts
+import { z } from "zod";
+function toShape(schema) {
+  if (schema.type !== "object")
+    throw new Error(`a tool's input must be an object, got ${String(schema.type)}`);
+  const properties = schema.properties ?? {};
+  const required = new Set(schema.required ?? []);
+  const shape = {};
+  for (const [name, property] of Object.entries(properties)) {
+    const field = toZod(property);
+    shape[name] = required.has(name) ? field : field.optional();
+  }
+  return shape;
+}
+function toZod(schema) {
+  const described = (type) => typeof schema.description === "string" ? type.describe(schema.description) : type;
+  if (Array.isArray(schema.enum)) {
+    const values = schema.enum;
+    if (values.length > 0 && values.every((each) => typeof each === "number")) {
+      const literals = values.map((each) => z.literal(each));
+      return described(
+        literals.length === 1 ? literals[0] : z.union(literals)
+      );
+    }
+    return described(z.enum(values));
+  }
+  switch (schema.type) {
+    case "string": {
+      let type = z.string();
+      if (typeof schema.minLength === "number") type = type.min(schema.minLength);
+      if (typeof schema.maxLength === "number") type = type.max(schema.maxLength);
+      return described(type);
+    }
+    case "integer":
+    case "number": {
+      let type = schema.type === "integer" ? z.number().int() : z.number();
+      if (typeof schema.minimum === "number") type = type.min(schema.minimum);
+      if (typeof schema.maximum === "number") type = type.max(schema.maximum);
+      return described(type);
+    }
+    case "boolean":
+      return described(z.boolean());
+    case "array": {
+      let type = z.array(toZod(schema.items ?? { type: "string" }));
+      if (typeof schema.minItems === "number") type = type.min(schema.minItems);
+      if (typeof schema.maxItems === "number") type = type.max(schema.maxItems);
+      return described(type);
+    }
+    case "object":
+      return described(z.object(toShape(schema)));
+    default:
+      throw new Error(
+        `unsupported schema type in a tool declaration: ${JSON.stringify(schema.type)}`
+      );
+  }
+}
+
+// ../../packages/data/src/mcp/vocabulary.ts
+function vocabulary(ctx) {
+  const types = /* @__PURE__ */ new Map();
+  const artifactIds = [];
+  for (const n of ctx.graph.nodes()) {
+    types.set(n.type, (types.get(n.type) ?? 0) + 1);
+    if (!isCode(ctx, n) && artifactIds.length < 8) artifactIds.push(n.id);
+  }
+  const relations = /* @__PURE__ */ new Set();
+  for (const e of ctx.graph.edges()) relations.add(e.relation);
+  return {
+    types: [...types.entries()].sort((a, b) => b[1] - a[1]),
+    relations: [...relations],
+    artifactIds
+  };
+}
+function vocabularyLine(ctx) {
+  const v = vocabulary(ctx);
+  return `This repo's graph \u2014 node types: ${v.types.map(([t]) => t).join(", ")}; relations: ${v.relations.join(", ")}. Use these exact strings for the type/relation params (counts + example ids: brief {include:['shape']}).`;
+}
+
+// ../../packages/data/src/mcp/server.ts
+var READ_ONLY = {
+  readOnlyHint: true,
+  openWorldHint: false
+};
+var WRITES = {
+  readOnlyHint: false,
+  destructiveHint: true
+};
+var NOT_READY = {
+  content: [{ type: "text", text: STILL_LOADING }],
+  structuredContent: { summary: STILL_LOADING, ready: false }
+};
+function createServer(ctx, hosted = [], prompts = []) {
+  const getCtx = typeof ctx === "function" ? ctx : () => Promise.resolve(ctx);
+  const server = new McpServer(
+    { name: "jarvis-data", version: "0.1.0" },
+    // Live vocabulary needs the built graph; on the deferred (provider) path it isn't available at
+    // connect time, so instructions stay static and send the agent to `brief` for the vocabulary.
+    {
+      instructions: buildInstructions({
+        ...typeof ctx === "function" ? {} : { ctx },
+        served: [...TOOLS.map((tool) => tool.name), ...hosted.map((tool) => tool.name)]
+      })
+    }
+  );
+  for (const t of TOOLS) {
+    server.registerTool(
+      t.name,
+      {
+        title: t.title,
+        description: t.description,
+        // Converted HERE, not declared here. A tool is declared in JSON Schema, which the
+        // hosted surface serves directly from inside a bundler; this SDK takes a zod raw
+        // shape and nothing else. The conversion belongs at the boundary that needs it,
+        // so the declaration carries no validator for one server to suit the other.
+        inputSchema: toShape(t.input),
+        annotations: t.metadata.readOnly ? READ_ONLY : WRITES
+      },
+      async (input) => {
+        const ready = await readyWithin(getCtx());
+        if (!ready) return NOT_READY;
+        return result(ready, await t.call(ready, input));
+      }
+    );
+  }
+  for (const t of hosted) {
+    server.registerTool(
+      t.name,
+      {
+        title: t.title,
+        description: t.description,
+        inputSchema: t.inputSchema,
+        ...t.annotations ? { annotations: t.annotations } : {}
+      },
+      async (input) => {
+        const structured = await t.call(input);
+        return {
+          content: [{ type: "text", text: structured.summary }],
+          structuredContent: structured
+        };
+      }
+    );
+  }
+  for (const p of prompts) {
+    server.registerPrompt(
+      p.name,
+      { title: p.title, description: p.description },
+      async () => ({
+        messages: [
+          { role: "user", content: { type: "text", text: await p.read() } }
+        ]
+      })
+    );
+  }
+  return server;
+}
+function buildInstructions(req = {}) {
+  const served = req.served ?? TOOLS.map((tool) => tool.name);
+  const has = (prefix) => served.some((name) => name.startsWith(prefix));
+  const lines = [
+    "This repo, through one connection: the work it has to do, and a map of what it knows."
+  ];
+  if (has("work_")) {
+    lines.push(
+      "work_* \u2014 THE BOARD, and what this workspace has to do. Take an item and finish it: work_list, work_take, work_verify (it runs this repo's gates and does not block), work_complete. Hit a decision that is not yours \u2014 architecture, product, design \u2014 and park it with work_update rather than choosing it."
+    );
+  }
+  if (has("map_")) {
+    lines.push(
+      "map_* \u2014 THE MAP: decisions, standards and specs linked to the code that enforces them. PREFER IT OVER GREP for planning any non-trivial change; one map_scope replaces a dozen greps. The loop: map_brief to orient, map_scope {task} for the edit set and what governs it, map_read every rule it named because a summary is not the rule, then map_scope {edits} before you commit."
+    );
+  }
+  if (served.includes("work_start")) {
+    lines.push("work_start \u2014 how work is done here. Once, before planning or editing anything.");
+  }
+  lines.push(
+    "Name things semantically: artifacts by id (S-13), code by repo-relative path. Answers carry file:line, and _meta.data.stale when the map has drifted from HEAD.",
+    req.ctx ? vocabularyLine(req.ctx) : "map_brief {include:['shape']} returns this repo's node types and relations \u2014 the exact strings the type/relation params take. Call it once rather than guessing."
+  );
+  return lines.join("\n");
+}
+async function result(ctx, structured) {
+  const f = await freshness(ctx);
+  const summary = f.stale && !/stale/i.test(structured.summary) ? `${STALE_PREFIX}${structured.summary}` : structured.summary;
+  return {
+    content: [{ type: "text", text: summary }],
+    structuredContent: { ...structured, summary },
+    ...f.stale ? { _meta: { data: { stale: true, ...f.reason ? { reason: f.reason } : {} } } } : {}
+  };
+}
+var STALE_PREFIX = "\u26A0 STALE GRAPH \u2014 results may be wrong; run `jarvis build graph` (the incremental update \u2014 not --rebuild). ";
+
+// ../../packages/data/src/mcp/snapshot.ts
+async function loadSnapshot(config) {
+  const raw = await config.persistence.load({ repoRoot: config.repoRoot }, "snapshot");
+  if (!raw) {
+    throw new Error(
+      "no built graph found \u2014 run `jarvis build graph` first (the incremental update, not a full re-extract). Read surfaces present the graph a build produced; they never produce one themselves."
+    );
+  }
+  let snapshot;
+  try {
+    snapshot = JSON.parse(raw);
+  } catch (err) {
+    throw new Error(
+      `built graph is unreadable (${err instanceof Error ? err.message : String(err)}) \u2014 run \`jarvis build graph\` to rewrite it.`
+    );
+  }
+  const graph = new GraphStore();
+  graph.load({ nodes: snapshot.nodes, edges: snapshot.edges });
+  return { graph, diagnostics: snapshot.diagnostics, builtAt: snapshot.builtAt };
+}
+async function loadQueryContext(config) {
+  const { graph, diagnostics, builtAt } = await loadSnapshot(config);
+  const mem = await applyMemoryOverlay(config, graph);
+  const { errors, warns } = summarize(diagnostics);
+  process.stderr.write(
+    `[data] graph loaded \u2014 ${graph.nodes().length} nodes, ${graph.edges().length} edges (${errors} error(s), ${warns} warning(s)); memory: ${mem.loaded} loaded (${mem.orphaned} orphaned)
+`
+  );
+  return createGraphContext(config, graph, diagnostics, builtAt, {
+    search: () => loadSearchRuntime(config, graph)
+  });
+}
+export {
+  HANDLERS,
+  STILL_LOADING,
+  TOOLS,
+  createGraphContext,
+  createGraphProvider,
+  createServer,
+  graphExplore,
+  lint,
+  loadQueryContext,
+  loadSnapshot,
+  memory,
+  read,
+  readyWithin,
+  scope,
+  search,
+  status,
+  toShape,
+  trace
+};