@neat.is/core 0.9.5-dev.20260824 → 0.9.5

package/dist/cli.js

@@ -6,7 +6,7 @@ import {
   resolveHost,
   resolveNeatVersion,
   writeDaemonRecord
-} from "./chunk-TGCWMMF6.js";
+} from "./chunk-4SLKQNG7.js";
 import {
   buildSearchIndex
 } from "./chunk-BC53SCT7.js";
@@ -75,7 +75,7 @@ import {
   startStalenessLoop,
   upsertConnectorEntry,
   validateConnectorEntry
-} from "./chunk-IVVF37OU.js";
+} from "./chunk-DGAI4VOE.js";
 import {
   startOtelGrpcReceiver
 } from "./chunk-ERE47MCR.js";
@@ -89,9 +89,9 @@ import {
 } from "./chunk-GDGUY4T6.js";
 
 // src/cli.ts
-import path16 from "path";
+import path17 from "path";
 import os4 from "os";
-import { promises as fs14 } from "fs";
+import { promises as fs15 } from "fs";
 
 // src/banner.ts
 import path from "path";
@@ -4827,945 +4827,908 @@ async function runConnectorCommand(rawArgs, deps = {}) {
   }
 }
 
-// src/hooks-cli.ts
-import path11 from "path";
-import os from "os";
+// src/doctor-cli.ts
 import { promises as fs10 } from "fs";
-import { fileURLToPath as fileURLToPath3 } from "url";
-var HOOK_FILENAME = "neat-search-nudge.mjs";
-var GUIDE_FILENAME = "GRAPH_FIRST.md";
-var GUIDE_INSTALL_NAME = "neat-graph-first.md";
-var HOOK_MATCHER = "Grep|Glob|Bash";
-function moduleDir() {
-  return typeof __dirname !== "undefined" ? __dirname : path11.dirname(fileURLToPath3(import.meta.url));
-}
-async function readSkillAsset(rel) {
-  const here = moduleDir();
-  const candidates = [
-    path11.resolve(here, "../../claude-skill", rel),
-    path11.resolve(here, "../../../claude-skill", rel),
-    path11.resolve(here, "../claude-skill", rel)
-  ];
-  for (const candidate of candidates) {
-    try {
-      return await fs10.readFile(candidate, "utf8");
-    } catch {
-    }
+import path11 from "path";
+
+// src/cli-client.ts
+import { Provenance as Provenance2 } from "@neat.is/types";
+var HttpError = class extends Error {
+  constructor(status, message, responseBody = "") {
+    super(message);
+    this.status = status;
+    this.responseBody = responseBody;
+    this.name = "HttpError";
   }
-  throw new Error(
-    `neat hooks: could not find @neat.is/claude-skill/${rel} \u2014 is the package installed?`
-  );
-}
-function neatHome() {
-  const override = process.env.NEAT_HOME;
-  if (override && override.length > 0) return path11.resolve(override);
-  return path11.join(os.homedir(), ".neat");
-}
-function claudeSettingsPath() {
-  const override = process.env.NEAT_CLAUDE_SETTINGS;
-  if (override && override.length > 0) return path11.resolve(override);
-  const home = process.env.HOME ?? process.env.USERPROFILE ?? os.homedir();
-  return path11.join(home, ".claude", "settings.json");
+  status;
+  responseBody;
+};
+var TransportError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "TransportError";
+  }
+};
+function resolveAuthToken(env = process.env) {
+  const t = env.NEAT_AUTH_TOKEN;
+  return t && t.length > 0 ? t : void 0;
 }
-function installedHookPath() {
-  return path11.join(neatHome(), "hooks", HOOK_FILENAME);
+function createHttpClient(baseUrl, bearerToken) {
+  const root = baseUrl.replace(/\/$/, "");
+  const authHeader = bearerToken && bearerToken.length > 0 ? { authorization: `Bearer ${bearerToken}` } : {};
+  return {
+    async get(path18) {
+      let res;
+      try {
+        res = await fetch(`${root}${path18}`, {
+          headers: { ...authHeader }
+        });
+      } catch (err) {
+        throw new TransportError(
+          `cannot reach neat-core at ${root}: ${err.message}`
+        );
+      }
+      if (!res.ok) {
+        const body = await res.text().catch(() => "");
+        throw new HttpError(
+          res.status,
+          `${res.status} ${res.statusText} on GET ${path18}: ${body}`,
+          body
+        );
+      }
+      return await res.json();
+    },
+    async post(path18, body) {
+      let res;
+      try {
+        res = await fetch(`${root}${path18}`, {
+          method: "POST",
+          headers: { "content-type": "application/json", ...authHeader },
+          body: JSON.stringify(body)
+        });
+      } catch (err) {
+        throw new TransportError(
+          `cannot reach neat-core at ${root}: ${err.message}`
+        );
+      }
+      if (!res.ok) {
+        const text = await res.text().catch(() => "");
+        throw new HttpError(
+          res.status,
+          `${res.status} ${res.statusText} on POST ${path18}: ${text}`,
+          text
+        );
+      }
+      return await res.json();
+    }
+  };
 }
-function gateFlagPath() {
-  return path11.join(neatHome(), "hooks", "gate-enabled");
+function projectPath(project, suffix) {
+  if (!project) return suffix;
+  return `/projects/${encodeURIComponent(project)}${suffix}`;
 }
-function isNeatSearchEntry(entry2) {
-  return (entry2.hooks ?? []).some(
-    (h) => typeof h.command === "string" && h.command.includes(HOOK_FILENAME)
+async function runRootCause(client, input) {
+  const qs = input.errorId ? `?errorId=${encodeURIComponent(input.errorId)}` : "";
+  const path18 = projectPath(
+    input.project,
+    `/graph/root-cause/${encodeURIComponent(input.errorNode)}${qs}`
   );
-}
-function neatHookEntry(command) {
-  return { matcher: HOOK_MATCHER, hooks: [{ type: "command", command }] };
-}
-function hookCommand(scriptPath) {
-  return `node "${scriptPath}"`;
-}
-async function runHooks(opts) {
-  if (opts.printHook) {
-    process.stdout.write(await readSkillAsset(`hooks/${HOOK_FILENAME}`));
-    return { exitCode: 0 };
-  }
-  if (opts.printGuide) {
-    process.stdout.write(await readSkillAsset(GUIDE_FILENAME));
-    return { exitCode: 0 };
-  }
-  if (opts.printSettings) {
-    const block = {
-      hooks: { PreToolUse: [neatHookEntry(hookCommand(installedHookPath()))] }
+  try {
+    const result = await client.get(path18);
+    const arrowPath = result.traversalPath.join(" \u2190 ");
+    const provenances = result.edgeProvenances.length ? result.edgeProvenances.join(", ") : "(direct, no edges traversed)";
+    const summary = `Root cause for ${input.errorNode} is ${result.rootCauseNode}. ` + result.rootCauseReason + (result.fixRecommendation ? ` Recommended fix: ${result.fixRecommendation}.` : "");
+    const blockLines = [
+      `Traversal path: ${arrowPath}`,
+      `Edge provenances: ${provenances}`
+    ];
+    if (result.fixRecommendation) blockLines.push(`Recommended fix: ${result.fixRecommendation}`);
+    return {
+      summary,
+      block: blockLines.join("\n"),
+      confidence: result.confidence,
+      provenance: result.edgeProvenances.length ? result.edgeProvenances : void 0
     };
-    process.stdout.write(JSON.stringify(block, null, 2) + "\n");
-    return { exitCode: 0 };
-  }
-  if (opts.apply) {
-    const hookScript = await readSkillAsset(`hooks/${HOOK_FILENAME}`);
-    const guide = await readSkillAsset(GUIDE_FILENAME);
-    const scriptPath = installedHookPath();
-    await fs10.mkdir(path11.dirname(scriptPath), { recursive: true });
-    await fs10.writeFile(scriptPath, hookScript, { mode: 493 });
-    const guidePath = path11.join(neatHome(), GUIDE_INSTALL_NAME);
-    await fs10.writeFile(guidePath, guide, "utf8");
-    const settingsFile = claudeSettingsPath();
-    let settings = {};
-    try {
-      settings = JSON.parse(await fs10.readFile(settingsFile, "utf8"));
-    } catch (err) {
-      if (err.code !== "ENOENT") {
-        console.error(
-          `neat hooks: failed to read ${settingsFile} \u2014 ${err.message}`
-        );
-        return { exitCode: 1 };
-      }
+  } catch (err) {
+    if (err instanceof HttpError && err.status === 404) {
+      return {
+        summary: `No root cause found for ${input.errorNode}. The node may be healthy, or it may not exist in the graph.`
+      };
     }
-    const hooks = settings.hooks ?? {};
-    const preToolUse = Array.isArray(hooks.PreToolUse) ? [...hooks.PreToolUse] : [];
-    const command = hookCommand(scriptPath);
-    const existingIdx = preToolUse.findIndex(isNeatSearchEntry);
-    if (existingIdx >= 0) {
-      preToolUse[existingIdx] = neatHookEntry(command);
-    } else {
-      preToolUse.push(neatHookEntry(command));
+    throw err;
+  }
+}
+async function runBlastRadius(client, input) {
+  const qs = input.depth !== void 0 ? `?depth=${input.depth}` : "";
+  const path18 = projectPath(
+    input.project,
+    `/graph/blast-radius/${encodeURIComponent(input.nodeId)}${qs}`
+  );
+  try {
+    const result = await client.get(path18);
+    if (result.totalAffected === 0) {
+      return {
+        summary: `${result.origin} has no dependents. Nothing else would break if it failed.`
+      };
     }
-    const merged = {
-      ...settings,
-      hooks: { ...hooks, PreToolUse: preToolUse }
+    const sorted = [...result.affectedNodes].sort(
+      (a, b) => a.distance - b.distance || a.nodeId.localeCompare(b.nodeId)
+    );
+    const blockLines = sorted.map(formatBlastEntry);
+    const minConfidence = sorted.reduce(
+      (m, n) => Math.min(m, n.confidence),
+      Number.POSITIVE_INFINITY
+    );
+    const provenances = [...new Set(sorted.map((n) => n.edgeProvenance))];
+    return {
+      summary: `Blast radius for ${result.origin}: ${result.totalAffected} dependent node${result.totalAffected === 1 ? "" : "s"} would break if it changed.`,
+      block: blockLines.join("\n"),
+      confidence: Number.isFinite(minConfidence) ? minConfidence : void 0,
+      provenance: provenances.length ? provenances : void 0
     };
-    await fs10.mkdir(path11.dirname(settingsFile), { recursive: true });
-    await fs10.writeFile(settingsFile, JSON.stringify(merged, null, 2) + "\n", "utf8");
-    const flag = gateFlagPath();
-    if (opts.gate) {
-      await fs10.mkdir(path11.dirname(flag), { recursive: true });
-      await fs10.writeFile(flag, "1\n", "utf8");
-    } else {
-      await fs10.rm(flag, { force: true });
-    }
-    const mode = opts.gate ? "GATE (deny search until you ask the graph)" : "nudge (search still runs)";
-    console.log(`neat hooks: installed the search hook in ${opts.gate ? "gate" : "nudge"} mode`);
-    console.log(`  script:   ${scriptPath}`);
-    console.log(`  settings: ${settingsFile} (PreToolUse \u2192 ${HOOK_MATCHER})`);
-    console.log(`  guidance: ${guidePath}`);
-    console.log(`  mode:     ${mode}`);
-    console.log("");
-    if (opts.gate) {
-      console.log("restart Claude Code to load the hook. A Grep/Glob or Bash grep is now DENIED");
-      console.log('until you run `neat ask "<question>"` (or the ask MCP tool) once this session;');
-      console.log("after that, search is allowed as a fallback. Set NEAT_SEARCH_GATE=0 to fall");
-      console.log("back to nudge-only without re-running.");
-    } else {
-      console.log("restart Claude Code to load the hook. On a Grep/Glob or a Bash grep,");
-      console.log("your agent will now be nudged to query NEAT first (the search still runs).");
-      console.log("Re-run with --gate to hard-force the graph-first orientation.");
+  } catch (err) {
+    if (err instanceof HttpError && err.status === 404) {
+      return { summary: `Node ${input.nodeId} not found in the graph.` };
     }
-    console.log("");
-    console.log("The hook is Claude-Code-specific. For agents on other harnesses, paste");
-    console.log(`the guidance above into your project instructions (CLAUDE.md / AGENTS.md).`);
-    return { exitCode: 0 };
+    throw err;
   }
-  usage();
-  return { exitCode: 0 };
 }
-function usage() {
-  console.log("neat hooks \u2014 wire NEAT into your agent so it queries the graph before grepping");
-  console.log("");
-  console.log("  --apply          install the Claude Code search hook and write the");
-  console.log("                   graph-first guidance to ~/.neat/, merging into");
-  console.log("                   ~/.claude/settings.json without touching your other hooks");
-  console.log("  --gate           with --apply, enable hard-gate mode: DENY Grep/Glob/grep-Bash");
-  console.log("                   until `neat ask` has run this session (default is nudge-only).");
-  console.log("                   Toggle off at run time with NEAT_SEARCH_GATE=0.");
-  console.log("  --print-hook     print the hook script to stdout");
-  console.log("  --print-guide    print the agent-agnostic graph-first guidance to stdout");
-  console.log("  --print-settings print the settings.json PreToolUse block --apply would add");
-  console.log("");
-  console.log("By default the hook is a gentle, non-blocking nudge \u2014 searches still run.");
-  console.log("--gate turns it into a hard forcing mechanism. It is Claude-Code-specific;");
-  console.log("other harnesses get the same steer from the graph-first guidance.");
+function formatBlastEntry(n) {
+  const tag = n.edgeProvenance === Provenance2.STALE ? " [STALE \u2014 last seen too long ago]" : "";
+  return `  \u2022 ${n.nodeId} (distance ${n.distance}, ${n.edgeProvenance})${tag}`;
 }
-async function runHooksCommand(args) {
-  const opts = {
-    apply: false,
-    printHook: false,
-    printGuide: false,
-    printSettings: false,
-    gate: false
-  };
-  for (const arg of args) {
-    switch (arg) {
-      case "--apply":
-        opts.apply = true;
-        break;
-      case "--gate":
-        opts.gate = true;
-        break;
-      case "--print-hook":
-        opts.printHook = true;
-        break;
-      case "--print-guide":
-        opts.printGuide = true;
-        break;
-      case "--print-settings":
-        opts.printSettings = true;
-        break;
-      case "-h":
-      case "--help":
-        usage();
-        return 0;
-      default:
-        console.error(`neat hooks: unknown flag "${arg}"`);
-        usage();
-        return 2;
-    }
-  }
+async function runDependencies(client, input) {
+  const depth = input.depth ?? 3;
+  const path18 = projectPath(
+    input.project,
+    `/graph/dependencies/${encodeURIComponent(input.nodeId)}?depth=${depth}`
+  );
   try {
-    const { exitCode } = await runHooks(opts);
-    return exitCode;
+    const result = await client.get(path18);
+    if (result.total === 0) {
+      return {
+        summary: depth === 1 ? `${input.nodeId} has no direct dependencies in the graph.` : `${input.nodeId} has no dependencies (BFS to depth ${depth}).`
+      };
+    }
+    const byDistance = /* @__PURE__ */ new Map();
+    for (const dep of result.dependencies) {
+      const ring = byDistance.get(dep.distance) ?? [];
+      ring.push(dep);
+      byDistance.set(dep.distance, ring);
+    }
+    const blockLines = [];
+    for (const distance of [...byDistance.keys()].sort((a, b) => a - b)) {
+      const label = distance === 1 ? "Direct (distance 1)" : `Distance ${distance}`;
+      blockLines.push(`${label}:`);
+      for (const dep of byDistance.get(distance)) {
+        blockLines.push(`  \u2022 ${dep.nodeId} \u2014 ${dep.edgeType} (${dep.provenance})`);
+      }
+    }
+    const provenances = [...new Set(result.dependencies.map((d) => d.provenance))];
+    const directCount = byDistance.get(1)?.length ?? 0;
+    const summary = depth === 1 ? `${input.nodeId} has ${directCount} direct dependenc${directCount === 1 ? "y" : "ies"}.` : `${input.nodeId} has ${result.total} dependenc${result.total === 1 ? "y" : "ies"} reachable to depth ${depth} (${directCount} direct).`;
+    return { summary, block: blockLines.join("\n"), provenance: provenances };
   } catch (err) {
-    console.error(err.message);
-    return 1;
-  }
-}
-
-// src/claude-cli.ts
-import path12 from "path";
-import { promises as fs11 } from "fs";
-var NEAT_SECTION_HEADING = "## neat";
-var NEAT_DIRECTIVE_BODY = `This project has NEAT wired in: a live, fused semantic graph of the system \u2014
-code and runtime behaviour (OpenTelemetry) in one model, every fact tagged with
-its provenance (EXTRACTED / OBSERVED / INFERRED / STALE) and a confidence.
-
-For ANY question about this system's behaviour, dependencies, failures, root
-cause, or blast radius, call \`neat ask\` FIRST \u2014 before Read, Grep, Glob, or Bash:
-
-    neat ask "why is checkout failing?"
-    neat ask "what breaks if I change the orders table?"
-    neat ask "what does the payments service depend on at runtime?"
-
-\`ask\` resolves your question to graph nodes and routes it to the right traversal
-\u2014 root cause, dependencies, observed runtime calls, incidents, divergences,
-blast radius \u2014 and returns one compact, provenance-tagged answer. The same door
-is the \`ask\` MCP tool (\`mcp__neat__ask\`) when NEAT's MCP server is wired in.
-
-The graph is live and fused: it is faster and more accurate than scanning files,
-and it can tell you what the system actually does at runtime, not only what the
-source declares. Fall back to Read/Grep only when the graph does not have what
-you need \u2014 comments, string literals, config minutiae. Ask the graph first,
-then scan.
-
-If \`neat ask\` errors, the daemon may not be running (\`neat list\`) \u2014 start it
-with \`neat <path>\`, then re-ask.`;
-function neatSection() {
-  return `${NEAT_SECTION_HEADING}
-
-${NEAT_DIRECTIVE_BODY}
-`;
-}
-function claudeMdPath() {
-  const override = process.env.NEAT_CLAUDE_MD;
-  if (override && override.length > 0) return path12.resolve(override);
-  return path12.join(process.cwd(), "CLAUDE.md");
-}
-function splitAroundSection(raw) {
-  const lines = raw.split("\n");
-  const startIdx = lines.findIndex((l) => l.replace(/\s+$/, "") === NEAT_SECTION_HEADING);
-  if (startIdx === -1) {
-    return { before: raw.replace(/\n*$/, ""), after: "", found: false };
-  }
-  let endIdx = lines.length;
-  for (let i = startIdx + 1; i < lines.length; i++) {
-    if (/^#{1,2}\s+/.test(lines[i] ?? "")) {
-      endIdx = i;
-      break;
+    if (err instanceof HttpError && err.status === 404) {
+      return { summary: `Node ${input.nodeId} not found in the graph.` };
     }
+    throw err;
   }
-  const before = lines.slice(0, startIdx).join("\n").replace(/\n*$/, "");
-  const after = lines.slice(endIdx).join("\n").replace(/^\n*/, "");
-  return { before, after, found: true };
 }
-function compose(before, after) {
-  const parts = [];
-  if (before.length > 0) parts.push(before);
-  parts.push(neatSection().replace(/\n+$/, ""));
-  if (after.length > 0) parts.push(after);
-  return parts.join("\n\n").replace(/\n*$/, "") + "\n";
+function observedDepLine(nodeId, e) {
+  const via = e.source !== nodeId ? ` (via ${e.source})` : "";
+  return `  \u2022 ${e.target} \u2014 ${e.type}${via}${edgeMeta(e)}`;
 }
-async function readIfExists(file) {
+async function runObservedDependencies(client, input) {
   try {
-    return await fs11.readFile(file, "utf8");
+    const result = await client.get(
+      projectPath(
+        input.project,
+        `/graph/observed-dependencies/${encodeURIComponent(input.nodeId)}`
+      )
+    );
+    if (result.dependencies.length === 0) {
+      if (result.observed) {
+        return {
+          summary: `${input.nodeId} makes no outbound runtime calls, but OTel has observed it receiving traffic on ${result.inboundObservedCount} inbound call path${result.inboundObservedCount === 1 ? "" : "s"} \u2014 it's a pure receiver.`,
+          provenance: Provenance2.OBSERVED
+        };
+      }
+      const note = result.hasExtractedOutbound ? " Static (EXTRACTED) dependencies exist but no runtime traffic has been seen \u2014 is OTel running?" : "";
+      return { summary: `No OBSERVED dependencies for ${input.nodeId}.${note}` };
+    }
+    const blockLines = result.dependencies.map((e) => observedDepLine(input.nodeId, e));
+    return {
+      summary: `${input.nodeId} has ${result.dependencies.length} runtime dependenc${result.dependencies.length === 1 ? "y" : "ies"} confirmed by OTel.`,
+      block: blockLines.join("\n"),
+      provenance: Provenance2.OBSERVED
+    };
   } catch (err) {
-    if (err.code === "ENOENT") return null;
+    if (err instanceof HttpError && err.status === 404) {
+      return { summary: `Node ${input.nodeId} not found in the graph.` };
+    }
     throw err;
   }
 }
-async function runInstall() {
-  const file = claudeMdPath();
-  const raw = await readIfExists(file) ?? "";
-  const { before, after, found } = splitAroundSection(raw);
-  const next = compose(before, after);
-  await fs11.mkdir(path12.dirname(file), { recursive: true });
-  await fs11.writeFile(file, next, "utf8");
-  const verb = raw.length === 0 ? "created" : found ? "refreshed" : "added";
-  console.log(`neat claude: ${verb} the \`${NEAT_SECTION_HEADING}\` section in ${file}`);
-  console.log("Your agent will now reach for `neat ask` before Read/Grep/Bash. Restart the");
-  console.log("session (or reload CLAUDE.md) to pick it up.");
-  return { exitCode: 0 };
-}
-async function runUninstall() {
-  const file = claudeMdPath();
-  const raw = await readIfExists(file);
-  if (raw === null) {
-    console.log(`neat claude: no CLAUDE.md at ${file} \u2014 nothing to remove.`);
-    return { exitCode: 0 };
-  }
-  const { before, after, found } = splitAroundSection(raw);
-  if (!found) {
-    console.log(`neat claude: no \`${NEAT_SECTION_HEADING}\` section in ${file} \u2014 nothing to remove.`);
-    return { exitCode: 0 };
+function edgeMeta(e) {
+  const bits = [];
+  if (e.signal) {
+    bits.push(`spans=${e.signal.spanCount}`);
+    if (e.signal.errorCount > 0) bits.push(`errors=${e.signal.errorCount}`);
+    if (e.signal.lastObservedAgeMs !== void 0) {
+      bits.push(`age=${formatDuration(e.signal.lastObservedAgeMs)}`);
+    }
+  } else if (e.callCount !== void 0) {
+    bits.push(`callCount=${e.callCount}`);
   }
-  const remaining = [before, after].filter((s) => s.length > 0).join("\n\n");
-  const next = remaining.length > 0 ? remaining.replace(/\n*$/, "") + "\n" : "";
-  await fs11.writeFile(file, next, "utf8");
-  console.log(`neat claude: removed the \`${NEAT_SECTION_HEADING}\` section from ${file}.`);
-  return { exitCode: 0 };
+  if (e.lastObserved) bits.push(`lastObserved=${e.lastObserved}`);
+  if (e.confidence !== void 0) bits.push(`confidence=${e.confidence}`);
+  return bits.length ? ` [${bits.join(", ")}]` : "";
 }
-function usage2() {
-  console.log("neat claude \u2014 make the query-first directive always-on in Claude Code");
-  console.log("");
-  console.log("  install     write (or refresh) a `## neat` section in ./CLAUDE.md so your");
-  console.log("              agent reaches for `neat ask` before Read/Grep/Bash");
-  console.log("  uninstall   remove the `## neat` section from ./CLAUDE.md");
-  console.log("  print       print the directive block to stdout (for a manual paste)");
-  console.log("");
-  console.log("Idempotent: re-running install replaces its own section, never duplicates it.");
-  console.log("Target file overridable via NEAT_CLAUDE_MD.");
+function formatDuration(ms) {
+  if (ms < 1e3) return `${Math.round(ms)}ms`;
+  const s = Math.round(ms / 1e3);
+  if (s < 60) return `${s}s`;
+  const m = Math.round(s / 60);
+  if (m < 60) return `${m}m`;
+  const h = Math.round(m / 60);
+  if (h < 48) return `${h}h`;
+  return `${Math.round(h / 24)}d`;
 }
-async function runClaudeCommand(args) {
-  const sub = args[0];
-  if (sub === "-h" || sub === "--help" || sub === void 0) {
-    usage2();
-    return sub === void 0 ? 2 : 0;
-  }
+async function runIncidents(client, input) {
+  const path18 = input.nodeId ? projectPath(input.project, `/incidents/${encodeURIComponent(input.nodeId)}`) : projectPath(input.project, "/incidents");
   try {
-    switch (sub) {
-      case "install":
-        return (await runInstall()).exitCode;
-      case "uninstall":
-        return (await runUninstall()).exitCode;
-      case "print":
-        process.stdout.write(neatSection());
-        return 0;
-      default:
-        console.error(`neat claude: unknown subcommand "${sub}"`);
-        usage2();
-        return 2;
+    const body = await client.get(path18);
+    const events = body.events;
+    if (events.length === 0) {
+      return {
+        summary: input.nodeId ? `No incidents recorded against ${input.nodeId}.` : "No incidents recorded."
+      };
+    }
+    const ordered = [...events].reverse().slice(0, input.limit ?? 20);
+    const blockLines = [];
+    for (const ev of ordered) {
+      blockLines.push(`  ${ev.timestamp} \u2014 ${ev.service}: ${ev.errorMessage}`);
+      blockLines.push(`    trace=${ev.traceId} span=${ev.spanId}`);
     }
+    const target = input.nodeId ?? "the project";
+    return {
+      summary: `${target} has ${body.total} recorded incident${body.total === 1 ? "" : "s"}; showing the ${ordered.length} most recent.`,
+      block: blockLines.join("\n"),
+      provenance: Provenance2.OBSERVED
+    };
   } catch (err) {
-    console.error(`neat claude: ${err.message}`);
-    return 1;
+    if (err instanceof HttpError && err.status === 404) {
+      return { summary: `Node ${input.nodeId ?? ""} not found in the graph.` };
+    }
+    throw err;
   }
 }
-
-// src/codex-cli.ts
-import path13 from "path";
-import os2 from "os";
-import { promises as fs12 } from "fs";
-import { isDeepStrictEqual } from "util";
-import { parse as parseToml, stringify as stringifyToml } from "smol-toml";
-var CODEX_MCP_SERVER = {
-  command: "npx",
-  args: ["-y", "@neat.is/mcp"],
-  env: { NEAT_CORE_URL: "http://localhost:8080" }
-};
-var CODEX_NEAT_BLOCK = [
-  "[mcp_servers.neat]",
-  'command = "npx"',
-  'args = ["-y", "@neat.is/mcp"]',
-  'env = { NEAT_CORE_URL = "http://localhost:8080" }'
-].join("\n");
-var NEAT_GRAPH_FIRST_START = "<!-- neat:graph-first -->";
-var NEAT_GRAPH_FIRST_END = "<!-- /neat:graph-first -->";
-function codexConfigPath() {
-  const override = process.env.NEAT_CODEX_CONFIG;
-  if (override && override.length > 0) return path13.resolve(override);
-  const home = process.env.HOME ?? process.env.USERPROFILE ?? os2.homedir();
-  return path13.join(home, ".codex", "config.toml");
-}
-function agentsFilePath() {
-  const override = process.env.NEAT_CODEX_AGENTS;
-  if (override && override.length > 0) return path13.resolve(override);
-  return path13.join(process.cwd(), "AGENTS.md");
-}
-function isTableHeader(line) {
-  return /^\s*\[\[?[^\]]+\]\]?\s*$/.test(line);
-}
-function tableName(line) {
-  return line.trim().replace(/^\[\[?/, "").replace(/\]\]?$/, "").trim();
-}
-function isNeatHeader(line) {
-  return isTableHeader(line) && tableName(line) === "mcp_servers.neat";
-}
-function isNeatChildHeader(line) {
-  if (!isTableHeader(line)) return false;
-  const name = tableName(line);
-  return name === "mcp_servers.neat" || name.startsWith("mcp_servers.neat.");
-}
-function upsertCodexConfig(raw) {
-  const trimmed = raw.trim();
-  const parsed = trimmed.length > 0 ? parseToml(raw) : {};
-  const existingServers = parsed.mcp_servers ?? {};
-  const spliced = spliceNeatBlock(raw);
-  let text;
-  if (verifyPreserved(raw, spliced, parsed)) {
-    text = spliced;
-  } else {
-    const merged = {
-      ...parsed,
-      mcp_servers: { ...existingServers, neat: CODEX_MCP_SERVER }
-    };
-    text = stringifyToml(merged);
-    if (!text.endsWith("\n")) text += "\n";
-  }
-  return { text, changed: text !== raw };
-}
-function spliceNeatBlock(raw) {
-  const block = CODEX_NEAT_BLOCK;
-  const lines = raw.length > 0 ? raw.split("\n") : [];
-  const start = lines.findIndex(isNeatHeader);
-  if (start === -1) {
-    const base = raw.replace(/\n+$/, "");
-    return base.length > 0 ? `${base}
-
-${block}
-` : `${block}
-`;
+async function runSearch(client, input) {
+  const result = await client.get(
+    projectPath(input.project, `/search?q=${encodeURIComponent(input.query)}`)
+  );
+  if (result.matches.length === 0) {
+    return { summary: `No matches for "${input.query}".` };
   }
-  let end = start + 1;
-  for (; ; ) {
-    while (end < lines.length && !isTableHeader(lines[end])) end++;
-    if (end < lines.length && isNeatChildHeader(lines[end])) {
-      end++;
-      continue;
-    }
-    break;
+  const provider = result.provider ?? "substring";
+  const blockLines = [];
+  let topScore;
+  for (const n of result.matches) {
+    const score = provider !== "substring" && typeof n.score === "number" ? n.score : void 0;
+    const scoreBit = score !== void 0 ? ` [score=${score.toFixed(2)}]` : "";
+    if (score !== void 0 && (topScore === void 0 || score > topScore)) topScore = score;
+    blockLines.push(
+      `  \u2022 ${n.id} (${n.type}) \u2014 ${n.name ?? n.id}${scoreBit}`
+    );
   }
-  const before = lines.slice(0, start).join("\n").replace(/\n*$/, "");
-  const after = lines.slice(end).join("\n").replace(/^\n*/, "");
-  let text = "";
-  if (before.length > 0) text += `${before}
-
-`;
-  text += `${block}
-`;
-  if (after.length > 0) text += `
-${after}`;
-  return `${text.replace(/\n*$/, "")}
-`;
+  return {
+    summary: `Found ${result.matches.length} match${result.matches.length === 1 ? "" : "es"} for "${input.query}" via ${provider} provider.`,
+    block: blockLines.join("\n"),
+    confidence: topScore
+  };
 }
-function verifyPreserved(raw, spliced, original) {
-  let next;
-  try {
-    next = parseToml(spliced);
-  } catch {
-    return false;
-  }
-  const origServers = original.mcp_servers ?? {};
-  const nextServers = next.mcp_servers ?? {};
-  if (!isDeepStrictEqual(nextServers.neat, CODEX_MCP_SERVER)) return false;
-  for (const name of Object.keys(origServers)) {
-    if (name === "neat") continue;
-    if (!isDeepStrictEqual(nextServers[name], origServers[name])) return false;
+async function runDiff(client, input) {
+  const result = await client.get(
+    projectPath(
+      input.project,
+      `/graph/diff?against=${encodeURIComponent(input.againstSnapshot)}`
+    )
+  );
+  const total = result.added.nodes.length + result.added.edges.length + result.removed.nodes.length + result.removed.edges.length + result.changed.nodes.length + result.changed.edges.length;
+  const baseLabel = result.base.exportedAt ?? "unknown";
+  if (total === 0) {
+    return {
+      summary: `No differences between the current graph and ${input.againstSnapshot} (base exportedAt=${baseLabel}).`
+    };
   }
-  for (const name of Object.keys(nextServers)) {
-    if (name !== "neat" && !(name in origServers)) return false;
+  const blockLines = [
+    `  base exportedAt:    ${baseLabel}`,
+    `  current exportedAt: ${result.current.exportedAt}`,
+    ""
+  ];
+  if (result.added.nodes.length || result.added.edges.length) {
+    blockLines.push("Added:");
+    for (const n of result.added.nodes) blockLines.push(`  + node ${n.id} (${n.type})`);
+    for (const e of result.added.edges)
+      blockLines.push(`  + edge ${e.id} \u2014 ${e.source} -> ${e.target} (${e.type}, ${e.provenance})`);
+    blockLines.push("");
   }
-  for (const key of Object.keys(original)) {
-    if (key === "mcp_servers") continue;
-    if (!isDeepStrictEqual(next[key], original[key])) return false;
+  if (result.removed.nodes.length || result.removed.edges.length) {
+    blockLines.push("Removed:");
+    for (const n of result.removed.nodes) blockLines.push(`  - node ${n.id} (${n.type})`);
+    for (const e of result.removed.edges)
+      blockLines.push(`  - edge ${e.id} \u2014 ${e.source} -> ${e.target} (${e.type}, ${e.provenance})`);
+    blockLines.push("");
   }
-  for (const key of Object.keys(next)) {
-    if (key !== "mcp_servers" && !(key in original)) return false;
+  if (result.changed.nodes.length || result.changed.edges.length) {
+    blockLines.push("Changed:");
+    for (const c of result.changed.nodes) {
+      blockLines.push(`  ~ node ${c.id} \u2014 ${summariseAttrDiff(c.before, c.after)}`);
+    }
+    for (const c of result.changed.edges) {
+      const provBit = c.before.provenance !== c.after.provenance ? `provenance ${c.before.provenance} \u2192 ${c.after.provenance}` : summariseAttrDiff(c.before, c.after);
+      blockLines.push(`  ~ edge ${c.id} \u2014 ${provBit}`);
+    }
   }
-  return true;
-}
-function agentsBlock(guide) {
-  return `${NEAT_GRAPH_FIRST_START}
-${guide.replace(/\s+$/, "")}
-${NEAT_GRAPH_FIRST_END}
-`;
+  return {
+    summary: `Diff against ${input.againstSnapshot}: ${total} change${total === 1 ? "" : "s"} between the snapshot and the live graph.`,
+    block: blockLines.join("\n").trimEnd()
+  };
 }
-function upsertAgents(raw, guide) {
-  const block = agentsBlock(guide);
-  if (raw.length === 0) return { text: block, changed: true };
-  const startIdx = raw.indexOf(NEAT_GRAPH_FIRST_START);
-  const endIdx = raw.indexOf(NEAT_GRAPH_FIRST_END);
-  if (startIdx !== -1 && endIdx !== -1 && endIdx > startIdx) {
-    const before = raw.slice(0, startIdx);
-    const after = raw.slice(endIdx + NEAT_GRAPH_FIRST_END.length);
-    const text2 = `${before}${block.replace(/\n+$/, "")}${after}`;
-    return { text: text2, changed: text2 !== raw };
+function summariseAttrDiff(before, after) {
+  const keys = /* @__PURE__ */ new Set([...Object.keys(before), ...Object.keys(after)]);
+  const changed = [];
+  for (const k of keys) {
+    if (JSON.stringify(before[k]) !== JSON.stringify(after[k])) changed.push(k);
   }
-  const base = raw.replace(/\n+$/, "");
-  const text = base.length > 0 ? `${base}
-
-${block}` : block;
-  return { text, changed: text !== raw };
-}
-async function readGuide() {
-  return readSkillAsset(GUIDE_FILENAME);
+  return changed.length === 0 ? "attributes differ" : `fields changed: ${changed.sort().join(", ")}`;
 }
-async function runCodex(opts) {
-  if (opts.printConfig) {
-    process.stdout.write(`${CODEX_NEAT_BLOCK}
-`);
-    return { exitCode: 0 };
-  }
-  if (opts.printGuide) {
-    process.stdout.write(agentsBlock(await readGuide()));
-    return { exitCode: 0 };
+async function runStaleEdges(client, input) {
+  const params = new URLSearchParams();
+  if (input.limit !== void 0) params.set("limit", String(input.limit));
+  if (input.edgeType) params.set("edgeType", input.edgeType);
+  const qs = params.size > 0 ? `?${params.toString()}` : "";
+  const body = await client.get(
+    projectPath(input.project, `/stale-events${qs}`)
+  );
+  const events = body.events;
+  if (events.length === 0) {
+    return {
+      summary: input.edgeType ? `No stale ${input.edgeType} edges recorded.` : "No stale-edge transitions recorded yet."
+    };
   }
-  const configPath = codexConfigPath();
-  const agentsPath = agentsFilePath();
-  let configRaw = "";
-  try {
-    configRaw = await fs12.readFile(configPath, "utf8");
-  } catch (err) {
-    if (err.code !== "ENOENT") {
-      console.error(`neat codex: failed to read ${configPath} \u2014 ${err.message}`);
-      return { exitCode: 1 };
+  const blockLines = events.map(
+    (e) => `  ${e.transitionedAt} \u2014 ${e.source} -[${e.edgeType}]-> ${e.target} (last seen ${e.lastObserved}, threshold ${formatDuration(e.thresholdMs)})`
+  );
+  return {
+    summary: `${events.length} stale-edge transition${events.length === 1 ? "" : "s"} recorded${input.edgeType ? ` for ${input.edgeType}` : ""}.`,
+    block: blockLines.join("\n"),
+    provenance: Provenance2.STALE
+  };
+}
+async function runPolicies(client, input) {
+  let violations;
+  let allowed = true;
+  let hypothetical;
+  if (input.hypotheticalAction) {
+    if (typeof client.post !== "function") {
+      throw new Error("HttpClient does not support POST \u2014 required for policies dry-run");
     }
-  }
-  let agentsRaw = "";
-  try {
-    agentsRaw = await fs12.readFile(agentsPath, "utf8");
-  } catch (err) {
-    if (err.code !== "ENOENT") {
-      console.error(`neat codex: failed to read ${agentsPath} \u2014 ${err.message}`);
-      return { exitCode: 1 };
-    }
-  }
-  let config;
-  try {
-    config = upsertCodexConfig(configRaw);
-  } catch (err) {
-    console.error(
-      `neat codex: ${configPath} is not valid TOML \u2014 ${err.message}`
+    const body = await client.post(
+      projectPath(input.project, "/policies/check"),
+      { hypotheticalAction: input.hypotheticalAction }
     );
-    console.error("neat codex: fix the file and re-run; nothing was written.");
-    return { exitCode: 1 };
-  }
-  const guide = await readGuide();
-  const agents = upsertAgents(agentsRaw, guide);
-  if (!opts.apply) {
-    console.log("neat codex \u2014 plan (nothing written; re-run with --apply to write)");
-    console.log("");
-    console.log(`  Codex MCP config: ${configPath}`);
-    console.log(
-      config.changed ? `    ${configRaw ? "update" : "create"} the [mcp_servers.neat] table:` : "    already up to date \u2014 [mcp_servers.neat] matches"
+    violations = body.violations;
+    allowed = body.allowed;
+    hypothetical = body.hypotheticalAction;
+  } else {
+    const params = new URLSearchParams();
+    if (input.policyId) params.set("policyId", input.policyId);
+    const qs = params.size > 0 ? `?${params.toString()}` : "";
+    const body = await client.get(
+      projectPath(input.project, `/policies/violations${qs}`)
     );
-    if (config.changed) {
-      for (const line of CODEX_NEAT_BLOCK.split("\n")) console.log(`      ${line}`);
-    }
-    console.log("");
-    console.log(`  Project instructions: ${agentsPath}`);
-    console.log(
-      agents.changed ? `    ${agentsRaw ? "update" : "create"} the graph-first block (between ${NEAT_GRAPH_FIRST_START} markers)` : "    already up to date \u2014 graph-first block matches"
+    violations = body.violations;
+    allowed = violations.every((v) => v.onViolation !== "block");
+  }
+  if (input.nodeId) {
+    violations = violations.filter(
+      (v) => v.subject.nodeId === input.nodeId || v.subject.path?.includes(input.nodeId)
     );
-    console.log("");
-    console.log("The MCP server reads NEAT_CORE_URL for the daemon URL \u2014 edit that value in");
-    console.log("the generated table to point Codex at a non-default daemon.");
-    return { exitCode: 0 };
   }
-  if (config.changed) {
-    await fs12.mkdir(path13.dirname(configPath), { recursive: true });
-    await fs12.writeFile(configPath, config.text, "utf8");
-    console.log(`neat codex: wrote [mcp_servers.neat] to ${configPath}`);
-  } else {
-    console.log(`neat codex: ${configPath} already has NEAT's MCP server`);
+  if (violations.length === 0) {
+    return {
+      summary: hypothetical ? `No violations would result from the hypothetical action (${hypothetical.kind}).` : "No policy violations recorded."
+    };
   }
-  if (agents.changed) {
-    await fs12.mkdir(path13.dirname(agentsPath), { recursive: true });
-    await fs12.writeFile(agentsPath, agents.text, "utf8");
-    console.log(`neat codex: wrote the graph-first block to ${agentsPath}`);
+  const blockCount = violations.filter((v) => v.onViolation === "block").length;
+  const summaryParts = [];
+  if (hypothetical) {
+    summaryParts.push(
+      `Hypothetical ${hypothetical.kind} would surface ${violations.length} violation${violations.length === 1 ? "" : "s"}`
+    );
   } else {
-    console.log(`neat codex: ${agentsPath} already has the graph-first block`);
+    summaryParts.push(
+      `${violations.length} policy violation${violations.length === 1 ? "" : "s"} currently recorded`
+    );
   }
-  console.log("");
-  console.log("restart Codex to pick up the new MCP server. NEAT_CORE_URL in the table");
-  console.log("points the server at the local daemon \u2014 edit it for a non-default one.");
-  return { exitCode: 0 };
-}
-function usage3() {
-  console.log("neat codex \u2014 install NEAT into the OpenAI Codex CLI (MCP server + AGENTS.md)");
-  console.log("");
-  console.log("  (no flag)        plan: print what would change, write nothing");
-  console.log("  --apply          add [mcp_servers.neat] to ~/.codex/config.toml and write");
-  console.log("                   the graph-first block into ./AGENTS.md, merging into both");
-  console.log("                   without touching your other servers or instructions");
-  console.log("  --print-config   print the [mcp_servers.neat] TOML block to stdout");
-  console.log("  --print-guide    print the AGENTS.md graph-first block to stdout");
-  console.log("");
-  console.log("Existing config is preserved and a re-run is a no-op. A malformed");
-  console.log("config.toml is a clear error with no partial write.");
+  if (blockCount > 0) summaryParts.push(`${blockCount} of which block`);
+  if (!allowed && hypothetical) summaryParts.push("action denied");
+  const summary = summaryParts.join("; ") + ".";
+  const blockLines = violations.map((v) => {
+    const subject = v.subject.nodeId ?? v.subject.edgeId ?? v.subject.path?.[0] ?? "(global)";
+    return `  \u2022 [${v.severity}/${v.onViolation}] ${v.policyName}: ${v.message} \u2014 ${subject}`;
+  });
+  const severities = [...new Set(violations.map((v) => v.severity))];
+  return {
+    summary,
+    block: blockLines.join("\n"),
+    confidence: hypothetical ? 0.7 : 1,
+    provenance: severities.join(" ")
+  };
 }
-async function runCodexCommand(args) {
-  const opts = { apply: false, printConfig: false, printGuide: false };
-  for (const arg of args) {
-    switch (arg) {
-      case "--apply":
-        opts.apply = true;
-        break;
-      case "--print-config":
-        opts.printConfig = true;
-        break;
-      case "--print-guide":
-        opts.printGuide = true;
-        break;
-      case "-h":
-      case "--help":
-        usage3();
-        return 0;
-      default:
-        console.error(`neat codex: unknown flag "${arg}"`);
-        usage3();
-        return 2;
+function formatDivergenceLine(d) {
+  switch (d.type) {
+    case "missing-observed":
+    case "missing-extracted":
+      if (d.column) {
+        return `  \u2022 [${d.type}] ${d.table ?? d.source} column ${d.column} \u2014 confidence ${d.confidence.toFixed(2)}`;
+      }
+      return `  \u2022 [${d.type}] ${d.source} \u2192 ${d.target} (${d.edgeType}) \u2014 confidence ${d.confidence.toFixed(2)}`;
+    case "version-mismatch":
+      return `  \u2022 [${d.type}] ${d.source} \u2192 ${d.target} \u2014 declared ${d.extractedVersion}, observed engine ${d.observedVersion} (${d.compatibility})`;
+    case "host-mismatch":
+      return `  \u2022 [${d.type}] ${d.source} \u2192 ${d.target} \u2014 declared host ${d.extractedHost}, observed host ${d.observedHost}`;
+    case "compat-violation":
+      return `  \u2022 [${d.type}] ${d.source} \u2192 ${d.target} \u2014 ${d.rule.kind}${d.rule.package ? ` (${d.rule.package})` : ""}`;
+    case "observed-symbol-mismatch": {
+      const at = d.location ? ` at ${d.location}` : "";
+      const member = d.symbol ? ` ${d.symbol}` : "";
+      return `  \u2022 [${d.type}] ${d.source}${member}${at} (${d.mismatchKind}) \u2014 confidence ${d.confidence.toFixed(2)}`;
     }
   }
-  try {
-    const { exitCode } = await runCodex(opts);
-    return exitCode;
-  } catch (err) {
-    console.error(err.message);
-    return 1;
+}
+async function runDivergences(client, input) {
+  const params = new URLSearchParams();
+  if (input.type && input.type.length > 0) params.set("type", input.type.join(","));
+  if (input.minConfidence !== void 0) {
+    params.set("minConfidence", String(input.minConfidence));
+  }
+  if (input.node) params.set("node", input.node);
+  const qs = params.size > 0 ? `?${params.toString()}` : "";
+  const result = await client.get(
+    projectPath(input.project, `/graph/divergences${qs}`)
+  );
+  if (result.totalAffected === 0) {
+    return {
+      summary: "No divergences found between the declared (EXTRACTED) and observed (OBSERVED) views of the graph."
+    };
+  }
+  const headline = result.divergences[0];
+  const summary = `Found ${result.totalAffected} divergence${result.totalAffected === 1 ? "" : "s"} between code and production. Highest-confidence: ${headline.type} on ${headline.source} \u2192 ${headline.target}. ${headline.reason}`;
+  const blockLines = [];
+  for (const d of result.divergences) {
+    blockLines.push(formatDivergenceLine(d));
+    blockLines.push(`    reason: ${d.reason}`);
+    blockLines.push(`    recommendation: ${d.recommendation}`);
   }
+  const maxConfidence = result.divergences.reduce(
+    (m, d) => Math.max(m, d.confidence),
+    0
+  );
+  return {
+    summary,
+    block: blockLines.join("\n"),
+    confidence: maxConfidence,
+    provenance: "composite (EXTRACTED + OBSERVED)"
+  };
 }
-
-// src/editors-cli.ts
-import path14 from "path";
-import os3 from "os";
-import { promises as fs13 } from "fs";
-import { isDeepStrictEqual as isDeepStrictEqual2 } from "util";
-import * as jsonc from "jsonc-parser";
-var NEAT_MCP_SERVER = {
-  command: "npx",
-  args: ["-y", "@neat.is/mcp"]
-};
-var NEAT_OPENCODE_SERVER = {
-  type: "local",
-  command: ["npx", "-y", "@neat.is/mcp"],
-  enabled: true
-};
-var NEAT_CRUSH_SERVER = {
-  type: "stdio",
-  command: "npx",
-  args: ["-y", "@neat.is/mcp"]
-};
-var GRAPH_FIRST_MARKER_OPEN = "<!-- neat:graph-first -->";
-var GRAPH_FIRST_MARKER_CLOSE = "<!-- /neat:graph-first -->";
-function homeDir() {
-  return process.env.HOME ?? process.env.USERPROFILE ?? os3.homedir();
+async function runAsk(client, input) {
+  const result = await client.get(
+    projectPath(input.project, `/graph/ask?q=${encodeURIComponent(input.question)}`)
+  );
+  const blockLines = [];
+  if (result.matched.length > 0) {
+    blockLines.push(
+      `Matched: ${result.matched.map((m) => `${m.nodeId} [${m.via} ${m.score.toFixed(2)}]`).join(", ")}`
+    );
+    blockLines.push(`Intent: ${result.intent}`);
+  } else if (result.scope === "global") {
+    blockLines.push(`Graph-wide answer (${result.intent}) \u2014 no entity named.`);
+  }
+  for (const section of result.sections) {
+    blockLines.push("", section.heading + ":");
+    for (const fact of section.facts) {
+      const tag = fact.provenance ? ` [${fact.provenance}${fact.confidence !== void 0 ? ` ${fact.confidence.toFixed(2)}` : ""}]` : fact.confidence !== void 0 ? ` [confidence ${fact.confidence.toFixed(2)}]` : "";
+      blockLines.push(`  \u2022 ${fact.text}${tag}`);
+    }
+  }
+  return {
+    summary: result.answer,
+    block: blockLines.join("\n").trim(),
+    ...result.confidence !== void 0 ? { confidence: result.confidence } : {},
+    ...result.provenance.length > 0 ? { provenance: result.provenance } : {}
+  };
 }
-function xdgConfigDir() {
-  const xdg = process.env.XDG_CONFIG_HOME;
-  return xdg && xdg.length > 0 ? path14.resolve(xdg) : path14.join(homeDir(), ".config");
+function formatFooter(confidence, provenance) {
+  const c = confidence === void 0 ? "n/a" : confidence.toFixed(2);
+  const p = provenance === void 0 ? "n/a" : Array.isArray(provenance) ? [...new Set(provenance)].join(", ") : provenance;
+  return `confidence: ${c} \xB7 provenance: ${p}`;
 }
-function envOverride(name) {
-  const v = process.env[name];
-  return v && v.length > 0 ? path14.resolve(v) : void 0;
+function formatHuman(result) {
+  const sections = [result.summary.trim()];
+  if (result.block && result.block.trim().length > 0) sections.push(result.block.trimEnd());
+  sections.push(formatFooter(result.confidence, result.provenance));
+  return sections.join("\n\n");
 }
-var CURSOR_CLIENT = {
-  id: "cursor",
-  label: "Cursor",
-  docsUrl: "https://docs.cursor.com/context/mcp",
-  mcpConfigPath: () => envOverride("NEAT_CURSOR_CONFIG") ?? path14.join(homeDir(), ".cursor", "mcp.json"),
-  mcpContainerKey: "mcpServers",
-  format: "json",
-  // Cursor still reads a single `.cursorrules` at the project root (the modern
-  // `.cursor/rules/*.mdc` split is one-rule-per-file with frontmatter — a worse
-  // fit for a marker-fenced block). GRAPH_FIRST.md names this file directly.
-  rulesFileName: ".cursorrules"
-};
-var DEVIN_CLIENT = {
-  id: "devin",
-  label: "Devin Desktop (Cascade)",
-  docsUrl: "https://docs.devin.ai/desktop/cascade/mcp",
-  mcpConfigPath: () => envOverride("NEAT_DEVIN_CONFIG") ?? path14.join(homeDir(), ".codeium", "windsurf", "mcp_config.json"),
-  mcpContainerKey: "mcpServers",
-  format: "json",
-  rulesFileName: ".windsurfrules"
-};
-var GEMINI_CLIENT = {
-  id: "gemini",
-  label: "Gemini CLI",
-  docsUrl: "https://github.com/google-gemini/gemini-cli/blob/main/docs/tools/mcp-server.md",
-  mcpConfigPath: () => envOverride("NEAT_GEMINI_CONFIG") ?? path14.join(homeDir(), ".gemini", "settings.json"),
-  mcpContainerKey: "mcpServers",
-  format: "json",
-  rulesFileName: "GEMINI.md"
-};
-var QWEN_CLIENT = {
-  id: "qwen",
-  label: "Qwen Code",
-  docsUrl: "https://qwenlm.github.io/qwen-code-docs/en/users/features/mcp/",
-  mcpConfigPath: () => envOverride("NEAT_QWEN_CONFIG") ?? path14.join(homeDir(), ".qwen", "settings.json"),
-  mcpContainerKey: "mcpServers",
-  format: "json",
-  rulesFileName: "QWEN.md"
-};
-var AMAZONQ_CLIENT = {
-  id: "amazonq",
-  label: "Amazon Q Developer CLI",
-  docsUrl: "https://docs.aws.amazon.com/amazonq/latest/qdeveloper-ug/command-line-mcp-configuration.html",
-  mcpConfigPath: () => envOverride("NEAT_AMAZONQ_CONFIG") ?? path14.join(homeDir(), ".aws", "amazonq", "mcp.json"),
-  mcpContainerKey: "mcpServers",
-  format: "json"
-};
-var ROOCODE_CLIENT = {
-  id: "roocode",
-  label: "Roo Code",
-  docsUrl: "https://roocodeinc.github.io/Roo-Code/features/mcp/using-mcp-in-roo",
-  mcpConfigPath: () => envOverride("NEAT_ROOCODE_CONFIG") ?? path14.join(process.cwd(), ".roo", "mcp.json"),
-  mcpContainerKey: "mcpServers",
-  format: "json"
-};
-var ZED_CLIENT = {
-  id: "zed",
-  label: "Zed",
-  docsUrl: "https://zed.dev/docs/ai/mcp",
-  mcpConfigPath: () => {
-    const override = envOverride("NEAT_ZED_CONFIG");
-    if (override) return override;
-    if (process.platform === "win32") {
-      const appData = process.env.APPDATA;
-      if (appData && appData.length > 0) return path14.join(appData, "Zed", "settings.json");
-    }
-    return path14.join(homeDir(), ".config", "zed", "settings.json");
-  },
-  mcpContainerKey: "context_servers",
-  format: "jsonc",
-  rulesFileName: ".rules"
-};
-var OPENCODE_CLIENT = {
-  id: "opencode",
-  label: "OpenCode",
-  docsUrl: "https://opencode.ai/docs/mcp-servers/",
-  mcpConfigPath: () => envOverride("NEAT_OPENCODE_CONFIG") ?? path14.join(xdgConfigDir(), "opencode", "opencode.json"),
-  mcpContainerKey: "mcp",
-  format: "json",
-  serverEntry: NEAT_OPENCODE_SERVER,
-  rulesFileName: "AGENTS.md"
-};
-var CRUSH_CLIENT = {
-  id: "crush",
-  label: "Crush",
-  docsUrl: "https://charmbracelet-crush.mintlify.app/configuration/mcp",
-  mcpConfigPath: () => envOverride("NEAT_CRUSH_CONFIG") ?? path14.join(xdgConfigDir(), "crush", "crush.json"),
-  mcpContainerKey: "mcp",
-  format: "json",
-  serverEntry: NEAT_CRUSH_SERVER,
-  rulesFileName: "AGENTS.md"
-};
-var CLIENTS = {
-  cursor: CURSOR_CLIENT,
-  devin: DEVIN_CLIENT,
-  gemini: GEMINI_CLIENT,
-  qwen: QWEN_CLIENT,
-  amazonq: AMAZONQ_CLIENT,
-  roocode: ROOCODE_CLIENT,
-  zed: ZED_CLIENT,
-  opencode: OPENCODE_CLIENT,
-  crush: CRUSH_CLIENT
-};
-function mergeJsonMcp(existing, containerKey, serverEntry) {
-  const servers = existing[containerKey] ?? {};
-  const already = isDeepStrictEqual2(servers.neat, serverEntry);
-  const merged = {
-    ...existing,
-    [containerKey]: { ...servers, neat: serverEntry }
-  };
-  return { merged, changed: !already };
-}
-function mergeJsoncMcp(raw, containerKey, serverEntry) {
-  const base = raw.trim().length > 0 ? raw : "{}";
-  const parsed = jsonc.parse(base) ?? {};
-  const servers = parsed[containerKey] ?? {};
-  if (isDeepStrictEqual2(servers.neat, serverEntry)) {
-    return { text: raw, changed: false };
-  }
-  const edits = jsonc.modify(base, [containerKey, "neat"], serverEntry, {
-    formattingOptions: { tabSize: 2, insertSpaces: true }
-  });
-  let text = jsonc.applyEdits(base, edits);
-  if (!text.endsWith("\n")) text += "\n";
-  return { text, changed: text !== raw };
+function formatJson(result) {
+  return JSON.stringify(
+    {
+      summary: result.summary,
+      block: result.block ?? "",
+      confidence: result.confidence ?? null,
+      provenance: result.provenance ?? null
+    },
+    null,
+    2
+  );
 }
-function escapeRegExp(s) {
-  return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+function exitCodeForError(err) {
+  if (err instanceof TransportError) return 3;
+  if (err instanceof HttpError) return 1;
+  return 1;
 }
-function buildGuidanceBlock(guide) {
-  return `${GRAPH_FIRST_MARKER_OPEN}
-${guide.trim()}
-${GRAPH_FIRST_MARKER_CLOSE}
-`;
+function createSnapshotPushClient(baseUrl, token) {
+  return createHttpClient(baseUrl, token && token.length > 0 ? token : void 0);
 }
-function mergeRulesFile(existing, block) {
-  const region = new RegExp(
-    `${escapeRegExp(GRAPH_FIRST_MARKER_OPEN)}[\\s\\S]*?${escapeRegExp(GRAPH_FIRST_MARKER_CLOSE)}\\n?`
+async function pushSnapshotToRemote(input) {
+  const client = createSnapshotPushClient(input.baseUrl, input.token);
+  if (typeof client.post !== "function") {
+    throw new Error("HttpClient does not support POST \u2014 required for snapshot push");
+  }
+  return client.post(
+    `/projects/${encodeURIComponent(input.project)}/snapshot`,
+    { snapshot: input.snapshot }
   );
-  if (region.test(existing)) return existing.replace(region, block);
-  if (existing.trim().length === 0) return block;
-  return `${existing.replace(/\s+$/, "")}
+}
 
-${block}`;
+// src/doctor-cli.ts
+function resolveDeps2(deps) {
+  return {
+    cwd: deps.cwd ?? process.cwd(),
+    env: deps.env ?? process.env,
+    nodeVersion: deps.nodeVersion ?? process.versions.node,
+    fetchImpl: deps.fetchImpl ?? fetch,
+    readRecord: deps.readRecord ?? readDaemonRecord,
+    out: deps.out ?? ((line) => console.log(line))
+  };
 }
-async function planMcp(client, mcpPath) {
-  const serverEntry = client.serverEntry ?? NEAT_MCP_SERVER;
-  let raw = "";
+var NODE_FLOOR = 20;
+var HEALTH_TIMEOUT_MS = 3e3;
+function checkNode(nodeVersion) {
+  const major = Number.parseInt(nodeVersion.split(".")[0] ?? "", 10);
+  const ok = Number.isFinite(major) && major >= NODE_FLOOR;
+  return ok ? { name: "node", ok, detail: `v${nodeVersion} (>= ${NODE_FLOOR} required)` } : {
+    name: "node",
+    ok,
+    detail: `v${nodeVersion} \u2014 NEAT needs Node ${NODE_FLOOR} or newer`,
+    fix: `install Node ${NODE_FLOOR}.x (e.g. \`nvm install ${NODE_FLOOR}\`) and re-run`
+  };
+}
+async function neatOutExists(cwd) {
   try {
-    raw = await fs13.readFile(mcpPath, "utf8");
-  } catch (err) {
-    const e = err;
-    if (e.code === "ENOENT") {
-      raw = "";
-    } else {
-      console.error(`neat ${client.id}: failed to read ${mcpPath} \u2014 ${e.message}`);
-      return null;
-    }
+    const st = await fs10.stat(path11.join(cwd, "neat-out"));
+    return st.isDirectory();
+  } catch {
+    return false;
   }
-  if (client.format === "jsonc") {
-    if (raw.trim().length > 0) {
-      const errors = [];
-      jsonc.parse(raw, errors, { allowTrailingComma: true });
-      if (errors.length > 0) {
-        const first = errors[0];
-        console.error(
-          `neat ${client.id}: ${mcpPath} is not valid JSONC \u2014 ${jsonc.printParseErrorCode(first.error)} at offset ${first.offset}. Fix it (or move it aside) and re-run; nothing was written.`
-        );
-        return null;
-      }
+}
+async function checkProject(cwd, record) {
+  if (record) {
+    return {
+      name: "project",
+      ok: true,
+      detail: `"${record.project}" \u2014 set up in this directory (daemon record on REST ${record.ports.rest})`
+    };
+  }
+  if (await neatOutExists(cwd)) {
+    return {
+      name: "project",
+      ok: true,
+      detail: "set up in this directory (no live daemon record \u2014 it may be stopped)"
+    };
+  }
+  return {
+    name: "project",
+    ok: false,
+    detail: "no NEAT project in this directory",
+    fix: "set one up: `neat .`"
+  };
+}
+function resolveHealthUrl(env, record) {
+  const explicit = env.NEAT_API_URL ?? env.NEAT_CORE_URL;
+  if (explicit && explicit.length > 0) return explicit.replace(/\/$/, "");
+  if (record) return `http://localhost:${record.ports.rest}`;
+  return "http://localhost:8080";
+}
+function summariseHealth(url, body) {
+  const projects = body.projects ?? [];
+  const nodes = projects.reduce((n, p) => n + (p.nodeCount ?? 0), 0);
+  const edges = projects.reduce((n, p) => n + (p.edgeCount ?? 0), 0);
+  const proj = body.project ?? projects[0]?.name;
+  const graph = projects.length > 0 ? ` \u2014 ${nodes} nodes / ${edges} edges` : "";
+  return `up at ${url}${proj ? ` (project "${proj}"${graph})` : ""}`;
+}
+async function checkDaemon(deps, record) {
+  const url = resolveHealthUrl(deps.env, record);
+  const token = resolveAuthToken(deps.env);
+  const headers = token ? { authorization: `Bearer ${token}` } : {};
+  try {
+    const res = await deps.fetchImpl(`${url}/health`, {
+      headers,
+      signal: AbortSignal.timeout(HEALTH_TIMEOUT_MS)
+    });
+    if (res.status === 401 || res.status === 403) {
+      return {
+        name: "daemon",
+        ok: false,
+        detail: `up at ${url}, but rejected the request (${res.status})`,
+        fix: "set NEAT_AUTH_TOKEN to the daemon's token"
+      };
     }
-    return mergeJsoncMcp(raw, client.mcpContainerKey, serverEntry);
+    if (!res.ok) {
+      return {
+        name: "daemon",
+        ok: false,
+        detail: `reachable at ${url} but /health returned ${res.status}`,
+        fix: "check the daemon logs"
+      };
+    }
+    const body = await res.json().catch(() => ({}));
+    return { name: "daemon", ok: true, detail: summariseHealth(url, body) };
+  } catch {
+    return {
+      name: "daemon",
+      ok: false,
+      detail: `down \u2014 nothing answering at ${url}`,
+      fix: "start it: `neat .`  (or `neat watch`)"
+    };
   }
-  let existing = {};
-  if (raw.trim().length > 0) {
-    try {
-      existing = JSON.parse(raw);
-    } catch (err) {
-      console.error(
-        `neat ${client.id}: ${mcpPath} is not valid JSON \u2014 ${err.message}. Fix it (or move it aside) and re-run; nothing was written.`
-      );
-      return null;
+}
+async function runDoctorChecks(deps = {}) {
+  const d = resolveDeps2(deps);
+  const record = await d.readRecord(d.cwd).catch(() => null);
+  return [checkNode(d.nodeVersion), await checkProject(d.cwd, record), await checkDaemon(d, record)];
+}
+var NAME_COL = "project".length;
+function renderHuman(checks, out) {
+  out("neat doctor \u2014 checking this project's setup");
+  out("");
+  for (const c of checks) {
+    const mark = c.ok ? "\u2713" : "\u2717";
+    out(`  ${mark}  ${c.name.padEnd(NAME_COL)}  ${c.detail}`);
+    if (!c.ok && c.fix) out(`  ${" ".repeat(NAME_COL + 3)}fix: ${c.fix}`);
+  }
+  out("");
+  const failed = checks.filter((c) => !c.ok).length;
+  out(failed === 0 ? "all good." : `${failed} check${failed === 1 ? "" : "s"} failed.`);
+}
+async function runDoctorCommand(argv, deps = {}) {
+  const out = deps.out ?? ((line) => console.log(line));
+  let json = false;
+  for (const arg of argv) {
+    if (arg === "--json") json = true;
+    else if (arg === "-h" || arg === "--help") {
+      out("usage: neat doctor [--json]");
+      out("  Probe this directory's NEAT setup: Node version, project, daemon.");
+      out("  Exit 0 when every check passes, 1 when any fails.");
+      return 0;
+    } else {
+      out(`neat doctor: unknown argument "${arg}"`);
+      return 2;
     }
   }
-  const { merged, changed } = mergeJsonMcp(existing, client.mcpContainerKey, serverEntry);
-  return { text: JSON.stringify(merged, null, 2) + "\n", changed };
+  const checks = await runDoctorChecks(deps);
+  if (json) out(JSON.stringify({ ok: checks.every((c) => c.ok), checks }, null, 2));
+  else renderHuman(checks, out);
+  return checks.every((c) => c.ok) ? 0 : 1;
 }
-async function runEditorInstall(client, opts) {
-  const mcpPath = client.mcpConfigPath();
-  const serverEntry = client.serverEntry ?? NEAT_MCP_SERVER;
-  const hasRules = typeof client.rulesFileName === "string";
-  const rulesPath = hasRules ? path14.join(opts.projectDir, client.rulesFileName) : "";
-  const mcp = await planMcp(client, mcpPath);
-  if (mcp === null) return { exitCode: 1 };
-  let existingRules = "";
-  let newRules = "";
-  let rulesChanged = false;
-  let block = "";
-  if (hasRules) {
+
+// src/hooks-cli.ts
+import path12 from "path";
+import os from "os";
+import { promises as fs11 } from "fs";
+import { fileURLToPath as fileURLToPath3 } from "url";
+var HOOK_FILENAME = "neat-search-nudge.mjs";
+var GUIDE_FILENAME = "GRAPH_FIRST.md";
+var GUIDE_INSTALL_NAME = "neat-graph-first.md";
+var HOOK_MATCHER = "Grep|Glob|Bash";
+function moduleDir() {
+  return typeof __dirname !== "undefined" ? __dirname : path12.dirname(fileURLToPath3(import.meta.url));
+}
+async function readSkillAsset(rel) {
+  const here = moduleDir();
+  const candidates = [
+    path12.resolve(here, "../../claude-skill", rel),
+    path12.resolve(here, "../../../claude-skill", rel),
+    path12.resolve(here, "../claude-skill", rel)
+  ];
+  for (const candidate of candidates) {
     try {
-      existingRules = await fs13.readFile(rulesPath, "utf8");
-    } catch (err) {
-      if (err.code !== "ENOENT") {
-        console.error(`neat ${client.id}: failed to read ${rulesPath} \u2014 ${err.message}`);
-        return { exitCode: 1 };
-      }
+      return await fs11.readFile(candidate, "utf8");
+    } catch {
     }
-    const guide = await readSkillAsset(GUIDE_FILENAME);
-    block = buildGuidanceBlock(guide);
-    newRules = mergeRulesFile(existingRules, block);
-    rulesChanged = newRules !== existingRules;
   }
-  if (!opts.apply) {
-    console.log(`neat ${client.id} \u2014 wire NEAT into ${client.label} (plan; nothing written)`);
-    console.log("");
-    console.log(`MCP server \u2192 ${mcpPath}`);
-    console.log(
-      mcp.changed ? `  would add ${client.mcpContainerKey}.neat:` : `  ${client.mcpContainerKey}.neat already present and current \u2014 no change:`
-    );
-    console.log(indent(JSON.stringify({ neat: serverEntry }, null, 2)));
-    if (hasRules) {
-      console.log("");
-      console.log(`Graph-first guidance \u2192 ${rulesPath}`);
-      console.log(
-        rulesChanged ? existingRules.includes(GRAPH_FIRST_MARKER_OPEN) ? "  would refresh the neat:graph-first block:" : "  would add the neat:graph-first block:" : "  neat:graph-first block already present and current \u2014 no change."
-      );
-      if (rulesChanged) console.log(indent(block.trimEnd()));
+  throw new Error(
+    `neat hooks: could not find @neat.is/claude-skill/${rel} \u2014 is the package installed?`
+  );
+}
+function neatHome() {
+  const override = process.env.NEAT_HOME;
+  if (override && override.length > 0) return path12.resolve(override);
+  return path12.join(os.homedir(), ".neat");
+}
+function claudeSettingsPath() {
+  const override = process.env.NEAT_CLAUDE_SETTINGS;
+  if (override && override.length > 0) return path12.resolve(override);
+  const home = process.env.HOME ?? process.env.USERPROFILE ?? os.homedir();
+  return path12.join(home, ".claude", "settings.json");
+}
+function installedHookPath() {
+  return path12.join(neatHome(), "hooks", HOOK_FILENAME);
+}
+function gateFlagPath() {
+  return path12.join(neatHome(), "hooks", "gate-enabled");
+}
+function isNeatSearchEntry(entry2) {
+  return (entry2.hooks ?? []).some(
+    (h) => typeof h.command === "string" && h.command.includes(HOOK_FILENAME)
+  );
+}
+function neatHookEntry(command) {
+  return { matcher: HOOK_MATCHER, hooks: [{ type: "command", command }] };
+}
+function hookCommand(scriptPath) {
+  return `node "${scriptPath}"`;
+}
+async function runHooks(opts) {
+  if (opts.printHook) {
+    process.stdout.write(await readSkillAsset(`hooks/${HOOK_FILENAME}`));
+    return { exitCode: 0 };
+  }
+  if (opts.printGuide) {
+    process.stdout.write(await readSkillAsset(GUIDE_FILENAME));
+    return { exitCode: 0 };
+  }
+  if (opts.printSettings) {
+    const block = {
+      hooks: { PreToolUse: [neatHookEntry(hookCommand(installedHookPath()))] }
+    };
+    process.stdout.write(JSON.stringify(block, null, 2) + "\n");
+    return { exitCode: 0 };
+  }
+  if (opts.apply) {
+    const hookScript = await readSkillAsset(`hooks/${HOOK_FILENAME}`);
+    const guide = await readSkillAsset(GUIDE_FILENAME);
+    const scriptPath = installedHookPath();
+    await fs11.mkdir(path12.dirname(scriptPath), { recursive: true });
+    await fs11.writeFile(scriptPath, hookScript, { mode: 493 });
+    const guidePath = path12.join(neatHome(), GUIDE_INSTALL_NAME);
+    await fs11.writeFile(guidePath, guide, "utf8");
+    const settingsFile = claudeSettingsPath();
+    let settings = {};
+    try {
+      settings = JSON.parse(await fs11.readFile(settingsFile, "utf8"));
+    } catch (err) {
+      if (err.code !== "ENOENT") {
+        console.error(
+          `neat hooks: failed to read ${settingsFile} \u2014 ${err.message}`
+        );
+        return { exitCode: 1 };
+      }
+    }
+    const hooks = settings.hooks ?? {};
+    const preToolUse = Array.isArray(hooks.PreToolUse) ? [...hooks.PreToolUse] : [];
+    const command = hookCommand(scriptPath);
+    const existingIdx = preToolUse.findIndex(isNeatSearchEntry);
+    if (existingIdx >= 0) {
+      preToolUse[existingIdx] = neatHookEntry(command);
+    } else {
+      preToolUse.push(neatHookEntry(command));
+    }
+    const merged = {
+      ...settings,
+      hooks: { ...hooks, PreToolUse: preToolUse }
+    };
+    await fs11.mkdir(path12.dirname(settingsFile), { recursive: true });
+    await fs11.writeFile(settingsFile, JSON.stringify(merged, null, 2) + "\n", "utf8");
+    const flag = gateFlagPath();
+    if (opts.gate) {
+      await fs11.mkdir(path12.dirname(flag), { recursive: true });
+      await fs11.writeFile(flag, "1\n", "utf8");
+    } else {
+      await fs11.rm(flag, { force: true });
     }
+    const mode = opts.gate ? "GATE (deny search until you ask the graph)" : "nudge (search still runs)";
+    console.log(`neat hooks: installed the search hook in ${opts.gate ? "gate" : "nudge"} mode`);
+    console.log(`  script:   ${scriptPath}`);
+    console.log(`  settings: ${settingsFile} (PreToolUse \u2192 ${HOOK_MATCHER})`);
+    console.log(`  guidance: ${guidePath}`);
+    console.log(`  mode:     ${mode}`);
     console.log("");
-    console.log(
-      hasRules ? `Re-run with --apply to write both files. Existing servers and rules are kept.` : `Re-run with --apply to write the config. Existing servers are kept.`
-    );
+    if (opts.gate) {
+      console.log("restart Claude Code to load the hook. A Grep/Glob or Bash grep is now DENIED");
+      console.log('until you run `neat ask "<question>"` (or the ask MCP tool) once this session;');
+      console.log("after that, search is allowed as a fallback. Set NEAT_SEARCH_GATE=0 to fall");
+      console.log("back to nudge-only without re-running.");
+    } else {
+      console.log("restart Claude Code to load the hook. On a Grep/Glob or a Bash grep,");
+      console.log("your agent will now be nudged to query NEAT first (the search still runs).");
+      console.log("Re-run with --gate to hard-force the graph-first orientation.");
+    }
+    console.log("");
+    console.log("The hook is Claude-Code-specific. For agents on other harnesses, paste");
+    console.log(`the guidance above into your project instructions (CLAUDE.md / AGENTS.md).`);
     return { exitCode: 0 };
   }
-  await fs13.mkdir(path14.dirname(mcpPath), { recursive: true });
-  await fs13.writeFile(mcpPath, mcp.text, "utf8");
-  if (hasRules) {
-    await fs13.mkdir(path14.dirname(rulesPath), { recursive: true });
-    await fs13.writeFile(rulesPath, newRules, "utf8");
-  }
-  console.log(`neat ${client.id}: wired NEAT into ${client.label}`);
-  console.log(`  MCP server: ${mcpPath} (${client.mcpContainerKey}.neat \u2192 npx -y @neat.is/mcp)`);
-  if (hasRules) console.log(`  guidance:   ${rulesPath} (neat:graph-first block)`);
-  console.log("");
-  console.log(`restart ${client.label} to pick up the MCP server. Point it at a non-default`);
-  console.log(`daemon by setting NEAT_CORE_URL in the neat server's env in that config.`);
+  usage();
   return { exitCode: 0 };
 }
-function indent(text) {
-  return text.split("\n").map((line) => line.length > 0 ? `    ${line}` : line).join("\n");
-}
-function usage4(client) {
-  const hasRules = typeof client.rulesFileName === "string";
-  console.log(
-    hasRules ? `neat ${client.id} \u2014 install NEAT's MCP server + graph-first guidance into ${client.label}` : `neat ${client.id} \u2014 install NEAT's MCP server into ${client.label}`
-  );
-  console.log("");
-  console.log(
-    hasRules ? "  --apply   write the MCP config and the rules file (default: plan only)" : "  --apply   write the MCP config (default: plan only)"
-  );
+function usage() {
+  console.log("neat hooks \u2014 wire NEAT into your agent so it queries the graph before grepping");
   console.log("");
-  console.log("Writes NEAT's stdio MCP server (npx -y @neat.is/mcp) into");
-  console.log(`  ${client.mcpConfigPath()}`);
-  if (hasRules) {
-    console.log(`and the graph-first guidance block into ./${client.rulesFileName}, both`);
-    console.log("additively \u2014 existing servers and rules are preserved, a re-run is a no-op.");
-  } else {
-    console.log("additively \u2014 existing servers are preserved, a re-run is a no-op.");
-  }
+  console.log("  --apply          install the Claude Code search hook and write the");
+  console.log("                   graph-first guidance to ~/.neat/, merging into");
+  console.log("                   ~/.claude/settings.json without touching your other hooks");
+  console.log("  --gate           with --apply, enable hard-gate mode: DENY Grep/Glob/grep-Bash");
+  console.log("                   until `neat ask` has run this session (default is nudge-only).");
+  console.log("                   Toggle off at run time with NEAT_SEARCH_GATE=0.");
+  console.log("  --print-hook     print the hook script to stdout");
+  console.log("  --print-guide    print the agent-agnostic graph-first guidance to stdout");
+  console.log("  --print-settings print the settings.json PreToolUse block --apply would add");
   console.log("");
-  console.log(`See ${client.docsUrl} for ${client.label}'s MCP config format.`);
+  console.log("By default the hook is a gentle, non-blocking nudge \u2014 searches still run.");
+  console.log("--gate turns it into a hard forcing mechanism. It is Claude-Code-specific;");
+  console.log("other harnesses get the same steer from the graph-first guidance.");
 }
-async function runEditorCommand(clientId, args, projectDir = process.cwd()) {
-  const client = CLIENTS[clientId];
-  let apply6 = false;
+async function runHooksCommand(args) {
+  const opts = {
+    apply: false,
+    printHook: false,
+    printGuide: false,
+    printSettings: false,
+    gate: false
+  };
   for (const arg of args) {
     switch (arg) {
       case "--apply":
-        apply6 = true;
+        opts.apply = true;
+        break;
+      case "--gate":
+        opts.gate = true;
+        break;
+      case "--print-hook":
+        opts.printHook = true;
+        break;
+      case "--print-guide":
+        opts.printGuide = true;
+        break;
+      case "--print-settings":
+        opts.printSettings = true;
         break;
       case "-h":
       case "--help":
-        usage4(client);
+        usage();
         return 0;
       default:
-        console.error(`neat ${client.id}: unknown flag "${arg}"`);
-        usage4(client);
+        console.error(`neat hooks: unknown flag "${arg}"`);
+        usage();
         return 2;
     }
   }
   try {
-    const { exitCode } = await runEditorInstall(client, { apply: apply6, projectDir });
+    const { exitCode } = await runHooks(opts);
     return exitCode;
   } catch (err) {
     console.error(err.message);
@@ -5773,572 +5736,753 @@ async function runEditorCommand(clientId, args, projectDir = process.cwd()) {
   }
 }
 
-// src/monitor.ts
-import { EdgeType, parseEdgeId, Provenance as Provenance3 } from "@neat.is/types";
+// src/claude-cli.ts
+import path13 from "path";
+import { promises as fs12 } from "fs";
+var NEAT_SECTION_HEADING = "## neat";
+var NEAT_DIRECTIVE_BODY = `This project has NEAT wired in: a live, fused semantic graph of the system \u2014
+code and runtime behaviour (OpenTelemetry) in one model, every fact tagged with
+its provenance (EXTRACTED / OBSERVED / INFERRED / STALE) and a confidence.
 
-// src/cli-client.ts
-import { Provenance as Provenance2 } from "@neat.is/types";
-var HttpError = class extends Error {
-  constructor(status, message, responseBody = "") {
-    super(message);
-    this.status = status;
-    this.responseBody = responseBody;
-    this.name = "HttpError";
+For ANY question about this system's behaviour, dependencies, failures, root
+cause, or blast radius, call \`neat ask\` FIRST \u2014 before Read, Grep, Glob, or Bash:
+
+    neat ask "why is checkout failing?"
+    neat ask "what breaks if I change the orders table?"
+    neat ask "what does the payments service depend on at runtime?"
+
+\`ask\` resolves your question to graph nodes and routes it to the right traversal
+\u2014 root cause, dependencies, observed runtime calls, incidents, divergences,
+blast radius \u2014 and returns one compact, provenance-tagged answer. The same door
+is the \`ask\` MCP tool (\`mcp__neat__ask\`) when NEAT's MCP server is wired in.
+
+The graph is live and fused: it is faster and more accurate than scanning files,
+and it can tell you what the system actually does at runtime, not only what the
+source declares. Fall back to Read/Grep only when the graph does not have what
+you need \u2014 comments, string literals, config minutiae. Ask the graph first,
+then scan.
+
+If \`neat ask\` errors, the daemon may not be running (\`neat list\`) \u2014 start it
+with \`neat <path>\`, then re-ask.`;
+function neatSection() {
+  return `${NEAT_SECTION_HEADING}
+
+${NEAT_DIRECTIVE_BODY}
+`;
+}
+function claudeMdPath() {
+  const override = process.env.NEAT_CLAUDE_MD;
+  if (override && override.length > 0) return path13.resolve(override);
+  return path13.join(process.cwd(), "CLAUDE.md");
+}
+function splitAroundSection(raw) {
+  const lines = raw.split("\n");
+  const startIdx = lines.findIndex((l) => l.replace(/\s+$/, "") === NEAT_SECTION_HEADING);
+  if (startIdx === -1) {
+    return { before: raw.replace(/\n*$/, ""), after: "", found: false };
   }
-  status;
-  responseBody;
-};
-var TransportError = class extends Error {
-  constructor(message) {
-    super(message);
-    this.name = "TransportError";
+  let endIdx = lines.length;
+  for (let i = startIdx + 1; i < lines.length; i++) {
+    if (/^#{1,2}\s+/.test(lines[i] ?? "")) {
+      endIdx = i;
+      break;
+    }
   }
-};
-function resolveAuthToken(env = process.env) {
-  const t = env.NEAT_AUTH_TOKEN;
-  return t && t.length > 0 ? t : void 0;
+  const before = lines.slice(0, startIdx).join("\n").replace(/\n*$/, "");
+  const after = lines.slice(endIdx).join("\n").replace(/^\n*/, "");
+  return { before, after, found: true };
 }
-function createHttpClient(baseUrl, bearerToken) {
-  const root = baseUrl.replace(/\/$/, "");
-  const authHeader = bearerToken && bearerToken.length > 0 ? { authorization: `Bearer ${bearerToken}` } : {};
-  return {
-    async get(path17) {
-      let res;
-      try {
-        res = await fetch(`${root}${path17}`, {
-          headers: { ...authHeader }
-        });
-      } catch (err) {
-        throw new TransportError(
-          `cannot reach neat-core at ${root}: ${err.message}`
-        );
-      }
-      if (!res.ok) {
-        const body = await res.text().catch(() => "");
-        throw new HttpError(
-          res.status,
-          `${res.status} ${res.statusText} on GET ${path17}: ${body}`,
-          body
-        );
-      }
-      return await res.json();
-    },
-    async post(path17, body) {
-      let res;
-      try {
-        res = await fetch(`${root}${path17}`, {
-          method: "POST",
-          headers: { "content-type": "application/json", ...authHeader },
-          body: JSON.stringify(body)
-        });
-      } catch (err) {
-        throw new TransportError(
-          `cannot reach neat-core at ${root}: ${err.message}`
-        );
-      }
-      if (!res.ok) {
-        const text = await res.text().catch(() => "");
-        throw new HttpError(
-          res.status,
-          `${res.status} ${res.statusText} on POST ${path17}: ${text}`,
-          text
-        );
-      }
-      return await res.json();
-    }
-  };
-}
-function projectPath(project, suffix) {
-  if (!project) return suffix;
-  return `/projects/${encodeURIComponent(project)}${suffix}`;
+function compose(before, after) {
+  const parts = [];
+  if (before.length > 0) parts.push(before);
+  parts.push(neatSection().replace(/\n+$/, ""));
+  if (after.length > 0) parts.push(after);
+  return parts.join("\n\n").replace(/\n*$/, "") + "\n";
 }
-async function runRootCause(client, input) {
-  const qs = input.errorId ? `?errorId=${encodeURIComponent(input.errorId)}` : "";
-  const path17 = projectPath(
-    input.project,
-    `/graph/root-cause/${encodeURIComponent(input.errorNode)}${qs}`
-  );
+async function readIfExists(file) {
   try {
-    const result = await client.get(path17);
-    const arrowPath = result.traversalPath.join(" \u2190 ");
-    const provenances = result.edgeProvenances.length ? result.edgeProvenances.join(", ") : "(direct, no edges traversed)";
-    const summary = `Root cause for ${input.errorNode} is ${result.rootCauseNode}. ` + result.rootCauseReason + (result.fixRecommendation ? ` Recommended fix: ${result.fixRecommendation}.` : "");
-    const blockLines = [
-      `Traversal path: ${arrowPath}`,
-      `Edge provenances: ${provenances}`
-    ];
-    if (result.fixRecommendation) blockLines.push(`Recommended fix: ${result.fixRecommendation}`);
-    return {
-      summary,
-      block: blockLines.join("\n"),
-      confidence: result.confidence,
-      provenance: result.edgeProvenances.length ? result.edgeProvenances : void 0
-    };
+    return await fs12.readFile(file, "utf8");
   } catch (err) {
-    if (err instanceof HttpError && err.status === 404) {
-      return {
-        summary: `No root cause found for ${input.errorNode}. The node may be healthy, or it may not exist in the graph.`
-      };
-    }
+    if (err.code === "ENOENT") return null;
     throw err;
   }
 }
-async function runBlastRadius(client, input) {
-  const qs = input.depth !== void 0 ? `?depth=${input.depth}` : "";
-  const path17 = projectPath(
-    input.project,
-    `/graph/blast-radius/${encodeURIComponent(input.nodeId)}${qs}`
-  );
-  try {
-    const result = await client.get(path17);
-    if (result.totalAffected === 0) {
-      return {
-        summary: `${result.origin} has no dependents. Nothing else would break if it failed.`
-      };
-    }
-    const sorted = [...result.affectedNodes].sort(
-      (a, b) => a.distance - b.distance || a.nodeId.localeCompare(b.nodeId)
-    );
-    const blockLines = sorted.map(formatBlastEntry);
-    const minConfidence = sorted.reduce(
-      (m, n) => Math.min(m, n.confidence),
-      Number.POSITIVE_INFINITY
-    );
-    const provenances = [...new Set(sorted.map((n) => n.edgeProvenance))];
-    return {
-      summary: `Blast radius for ${result.origin}: ${result.totalAffected} dependent node${result.totalAffected === 1 ? "" : "s"} would break if it changed.`,
-      block: blockLines.join("\n"),
-      confidence: Number.isFinite(minConfidence) ? minConfidence : void 0,
-      provenance: provenances.length ? provenances : void 0
-    };
-  } catch (err) {
-    if (err instanceof HttpError && err.status === 404) {
-      return { summary: `Node ${input.nodeId} not found in the graph.` };
-    }
-    throw err;
+async function runInstall() {
+  const file = claudeMdPath();
+  const raw = await readIfExists(file) ?? "";
+  const { before, after, found } = splitAroundSection(raw);
+  const next = compose(before, after);
+  await fs12.mkdir(path13.dirname(file), { recursive: true });
+  await fs12.writeFile(file, next, "utf8");
+  const verb = raw.length === 0 ? "created" : found ? "refreshed" : "added";
+  console.log(`neat claude: ${verb} the \`${NEAT_SECTION_HEADING}\` section in ${file}`);
+  console.log("Your agent will now reach for `neat ask` before Read/Grep/Bash. Restart the");
+  console.log("session (or reload CLAUDE.md) to pick it up.");
+  return { exitCode: 0 };
+}
+async function runUninstall() {
+  const file = claudeMdPath();
+  const raw = await readIfExists(file);
+  if (raw === null) {
+    console.log(`neat claude: no CLAUDE.md at ${file} \u2014 nothing to remove.`);
+    return { exitCode: 0 };
+  }
+  const { before, after, found } = splitAroundSection(raw);
+  if (!found) {
+    console.log(`neat claude: no \`${NEAT_SECTION_HEADING}\` section in ${file} \u2014 nothing to remove.`);
+    return { exitCode: 0 };
   }
+  const remaining = [before, after].filter((s) => s.length > 0).join("\n\n");
+  const next = remaining.length > 0 ? remaining.replace(/\n*$/, "") + "\n" : "";
+  await fs12.writeFile(file, next, "utf8");
+  console.log(`neat claude: removed the \`${NEAT_SECTION_HEADING}\` section from ${file}.`);
+  return { exitCode: 0 };
 }
-function formatBlastEntry(n) {
-  const tag = n.edgeProvenance === Provenance2.STALE ? " [STALE \u2014 last seen too long ago]" : "";
-  return `  \u2022 ${n.nodeId} (distance ${n.distance}, ${n.edgeProvenance})${tag}`;
+function usage2() {
+  console.log("neat claude \u2014 make the query-first directive always-on in Claude Code");
+  console.log("");
+  console.log("  install     write (or refresh) a `## neat` section in ./CLAUDE.md so your");
+  console.log("              agent reaches for `neat ask` before Read/Grep/Bash");
+  console.log("  uninstall   remove the `## neat` section from ./CLAUDE.md");
+  console.log("  print       print the directive block to stdout (for a manual paste)");
+  console.log("");
+  console.log("Idempotent: re-running install replaces its own section, never duplicates it.");
+  console.log("Target file overridable via NEAT_CLAUDE_MD.");
 }
-async function runDependencies(client, input) {
-  const depth = input.depth ?? 3;
-  const path17 = projectPath(
-    input.project,
-    `/graph/dependencies/${encodeURIComponent(input.nodeId)}?depth=${depth}`
-  );
+async function runClaudeCommand(args) {
+  const sub = args[0];
+  if (sub === "-h" || sub === "--help" || sub === void 0) {
+    usage2();
+    return sub === void 0 ? 2 : 0;
+  }
   try {
-    const result = await client.get(path17);
-    if (result.total === 0) {
-      return {
-        summary: depth === 1 ? `${input.nodeId} has no direct dependencies in the graph.` : `${input.nodeId} has no dependencies (BFS to depth ${depth}).`
-      };
-    }
-    const byDistance = /* @__PURE__ */ new Map();
-    for (const dep of result.dependencies) {
-      const ring = byDistance.get(dep.distance) ?? [];
-      ring.push(dep);
-      byDistance.set(dep.distance, ring);
-    }
-    const blockLines = [];
-    for (const distance of [...byDistance.keys()].sort((a, b) => a - b)) {
-      const label = distance === 1 ? "Direct (distance 1)" : `Distance ${distance}`;
-      blockLines.push(`${label}:`);
-      for (const dep of byDistance.get(distance)) {
-        blockLines.push(`  \u2022 ${dep.nodeId} \u2014 ${dep.edgeType} (${dep.provenance})`);
-      }
+    switch (sub) {
+      case "install":
+        return (await runInstall()).exitCode;
+      case "uninstall":
+        return (await runUninstall()).exitCode;
+      case "print":
+        process.stdout.write(neatSection());
+        return 0;
+      default:
+        console.error(`neat claude: unknown subcommand "${sub}"`);
+        usage2();
+        return 2;
     }
-    const provenances = [...new Set(result.dependencies.map((d) => d.provenance))];
-    const directCount = byDistance.get(1)?.length ?? 0;
-    const summary = depth === 1 ? `${input.nodeId} has ${directCount} direct dependenc${directCount === 1 ? "y" : "ies"}.` : `${input.nodeId} has ${result.total} dependenc${result.total === 1 ? "y" : "ies"} reachable to depth ${depth} (${directCount} direct).`;
-    return { summary, block: blockLines.join("\n"), provenance: provenances };
   } catch (err) {
-    if (err instanceof HttpError && err.status === 404) {
-      return { summary: `Node ${input.nodeId} not found in the graph.` };
-    }
-    throw err;
+    console.error(`neat claude: ${err.message}`);
+    return 1;
   }
 }
-function observedDepLine(nodeId, e) {
-  const via = e.source !== nodeId ? ` (via ${e.source})` : "";
-  return `  \u2022 ${e.target} \u2014 ${e.type}${via}${edgeMeta(e)}`;
+
+// src/codex-cli.ts
+import path14 from "path";
+import os2 from "os";
+import { promises as fs13 } from "fs";
+import { isDeepStrictEqual } from "util";
+import { parse as parseToml, stringify as stringifyToml } from "smol-toml";
+var CODEX_MCP_SERVER = {
+  command: "npx",
+  args: ["-y", "@neat.is/mcp"],
+  env: { NEAT_CORE_URL: "http://localhost:8080" }
+};
+var CODEX_NEAT_BLOCK = [
+  "[mcp_servers.neat]",
+  'command = "npx"',
+  'args = ["-y", "@neat.is/mcp"]',
+  'env = { NEAT_CORE_URL = "http://localhost:8080" }'
+].join("\n");
+var NEAT_GRAPH_FIRST_START = "<!-- neat:graph-first -->";
+var NEAT_GRAPH_FIRST_END = "<!-- /neat:graph-first -->";
+function codexConfigPath() {
+  const override = process.env.NEAT_CODEX_CONFIG;
+  if (override && override.length > 0) return path14.resolve(override);
+  const home = process.env.HOME ?? process.env.USERPROFILE ?? os2.homedir();
+  return path14.join(home, ".codex", "config.toml");
 }
-async function runObservedDependencies(client, input) {
-  try {
-    const result = await client.get(
-      projectPath(
-        input.project,
-        `/graph/observed-dependencies/${encodeURIComponent(input.nodeId)}`
-      )
-    );
-    if (result.dependencies.length === 0) {
-      if (result.observed) {
-        return {
-          summary: `${input.nodeId} makes no outbound runtime calls, but OTel has observed it receiving traffic on ${result.inboundObservedCount} inbound call path${result.inboundObservedCount === 1 ? "" : "s"} \u2014 it's a pure receiver.`,
-          provenance: Provenance2.OBSERVED
-        };
-      }
-      const note = result.hasExtractedOutbound ? " Static (EXTRACTED) dependencies exist but no runtime traffic has been seen \u2014 is OTel running?" : "";
-      return { summary: `No OBSERVED dependencies for ${input.nodeId}.${note}` };
-    }
-    const blockLines = result.dependencies.map((e) => observedDepLine(input.nodeId, e));
-    return {
-      summary: `${input.nodeId} has ${result.dependencies.length} runtime dependenc${result.dependencies.length === 1 ? "y" : "ies"} confirmed by OTel.`,
-      block: blockLines.join("\n"),
-      provenance: Provenance2.OBSERVED
-    };
-  } catch (err) {
-    if (err instanceof HttpError && err.status === 404) {
-      return { summary: `Node ${input.nodeId} not found in the graph.` };
-    }
-    throw err;
-  }
+function agentsFilePath() {
+  const override = process.env.NEAT_CODEX_AGENTS;
+  if (override && override.length > 0) return path14.resolve(override);
+  return path14.join(process.cwd(), "AGENTS.md");
 }
-function edgeMeta(e) {
-  const bits = [];
-  if (e.signal) {
-    bits.push(`spans=${e.signal.spanCount}`);
-    if (e.signal.errorCount > 0) bits.push(`errors=${e.signal.errorCount}`);
-    if (e.signal.lastObservedAgeMs !== void 0) {
-      bits.push(`age=${formatDuration(e.signal.lastObservedAgeMs)}`);
-    }
-  } else if (e.callCount !== void 0) {
-    bits.push(`callCount=${e.callCount}`);
-  }
-  if (e.lastObserved) bits.push(`lastObserved=${e.lastObserved}`);
-  if (e.confidence !== void 0) bits.push(`confidence=${e.confidence}`);
-  return bits.length ? ` [${bits.join(", ")}]` : "";
+function isTableHeader(line) {
+  return /^\s*\[\[?[^\]]+\]\]?\s*$/.test(line);
 }
-function formatDuration(ms) {
-  if (ms < 1e3) return `${Math.round(ms)}ms`;
-  const s = Math.round(ms / 1e3);
-  if (s < 60) return `${s}s`;
-  const m = Math.round(s / 60);
-  if (m < 60) return `${m}m`;
-  const h = Math.round(m / 60);
-  if (h < 48) return `${h}h`;
-  return `${Math.round(h / 24)}d`;
+function tableName(line) {
+  return line.trim().replace(/^\[\[?/, "").replace(/\]\]?$/, "").trim();
 }
-async function runIncidents(client, input) {
-  const path17 = input.nodeId ? projectPath(input.project, `/incidents/${encodeURIComponent(input.nodeId)}`) : projectPath(input.project, "/incidents");
-  try {
-    const body = await client.get(path17);
-    const events = body.events;
-    if (events.length === 0) {
-      return {
-        summary: input.nodeId ? `No incidents recorded against ${input.nodeId}.` : "No incidents recorded."
-      };
-    }
-    const ordered = [...events].reverse().slice(0, input.limit ?? 20);
-    const blockLines = [];
-    for (const ev of ordered) {
-      blockLines.push(`  ${ev.timestamp} \u2014 ${ev.service}: ${ev.errorMessage}`);
-      blockLines.push(`    trace=${ev.traceId} span=${ev.spanId}`);
-    }
-    const target = input.nodeId ?? "the project";
-    return {
-      summary: `${target} has ${body.total} recorded incident${body.total === 1 ? "" : "s"}; showing the ${ordered.length} most recent.`,
-      block: blockLines.join("\n"),
-      provenance: Provenance2.OBSERVED
+function isNeatHeader(line) {
+  return isTableHeader(line) && tableName(line) === "mcp_servers.neat";
+}
+function isNeatChildHeader(line) {
+  if (!isTableHeader(line)) return false;
+  const name = tableName(line);
+  return name === "mcp_servers.neat" || name.startsWith("mcp_servers.neat.");
+}
+function upsertCodexConfig(raw) {
+  const trimmed = raw.trim();
+  const parsed = trimmed.length > 0 ? parseToml(raw) : {};
+  const existingServers = parsed.mcp_servers ?? {};
+  const spliced = spliceNeatBlock(raw);
+  let text;
+  if (verifyPreserved(raw, spliced, parsed)) {
+    text = spliced;
+  } else {
+    const merged = {
+      ...parsed,
+      mcp_servers: { ...existingServers, neat: CODEX_MCP_SERVER }
     };
-  } catch (err) {
-    if (err instanceof HttpError && err.status === 404) {
-      return { summary: `Node ${input.nodeId ?? ""} not found in the graph.` };
-    }
-    throw err;
+    text = stringifyToml(merged);
+    if (!text.endsWith("\n")) text += "\n";
   }
+  return { text, changed: text !== raw };
 }
-async function runSearch(client, input) {
-  const result = await client.get(
-    projectPath(input.project, `/search?q=${encodeURIComponent(input.query)}`)
-  );
-  if (result.matches.length === 0) {
-    return { summary: `No matches for "${input.query}".` };
+function spliceNeatBlock(raw) {
+  const block = CODEX_NEAT_BLOCK;
+  const lines = raw.length > 0 ? raw.split("\n") : [];
+  const start = lines.findIndex(isNeatHeader);
+  if (start === -1) {
+    const base = raw.replace(/\n+$/, "");
+    return base.length > 0 ? `${base}
+
+${block}
+` : `${block}
+`;
   }
-  const provider = result.provider ?? "substring";
-  const blockLines = [];
-  let topScore;
-  for (const n of result.matches) {
-    const score = provider !== "substring" && typeof n.score === "number" ? n.score : void 0;
-    const scoreBit = score !== void 0 ? ` [score=${score.toFixed(2)}]` : "";
-    if (score !== void 0 && (topScore === void 0 || score > topScore)) topScore = score;
-    blockLines.push(
-      `  \u2022 ${n.id} (${n.type}) \u2014 ${n.name ?? n.id}${scoreBit}`
-    );
+  let end = start + 1;
+  for (; ; ) {
+    while (end < lines.length && !isTableHeader(lines[end])) end++;
+    if (end < lines.length && isNeatChildHeader(lines[end])) {
+      end++;
+      continue;
+    }
+    break;
   }
-  return {
-    summary: `Found ${result.matches.length} match${result.matches.length === 1 ? "" : "es"} for "${input.query}" via ${provider} provider.`,
-    block: blockLines.join("\n"),
-    confidence: topScore
-  };
+  const before = lines.slice(0, start).join("\n").replace(/\n*$/, "");
+  const after = lines.slice(end).join("\n").replace(/^\n*/, "");
+  let text = "";
+  if (before.length > 0) text += `${before}
+
+`;
+  text += `${block}
+`;
+  if (after.length > 0) text += `
+${after}`;
+  return `${text.replace(/\n*$/, "")}
+`;
 }
-async function runDiff(client, input) {
-  const result = await client.get(
-    projectPath(
-      input.project,
-      `/graph/diff?against=${encodeURIComponent(input.againstSnapshot)}`
-    )
-  );
-  const total = result.added.nodes.length + result.added.edges.length + result.removed.nodes.length + result.removed.edges.length + result.changed.nodes.length + result.changed.edges.length;
-  const baseLabel = result.base.exportedAt ?? "unknown";
-  if (total === 0) {
-    return {
-      summary: `No differences between the current graph and ${input.againstSnapshot} (base exportedAt=${baseLabel}).`
-    };
+function verifyPreserved(raw, spliced, original) {
+  let next;
+  try {
+    next = parseToml(spliced);
+  } catch {
+    return false;
   }
-  const blockLines = [
-    `  base exportedAt:    ${baseLabel}`,
-    `  current exportedAt: ${result.current.exportedAt}`,
-    ""
-  ];
-  if (result.added.nodes.length || result.added.edges.length) {
-    blockLines.push("Added:");
-    for (const n of result.added.nodes) blockLines.push(`  + node ${n.id} (${n.type})`);
-    for (const e of result.added.edges)
-      blockLines.push(`  + edge ${e.id} \u2014 ${e.source} -> ${e.target} (${e.type}, ${e.provenance})`);
-    blockLines.push("");
+  const origServers = original.mcp_servers ?? {};
+  const nextServers = next.mcp_servers ?? {};
+  if (!isDeepStrictEqual(nextServers.neat, CODEX_MCP_SERVER)) return false;
+  for (const name of Object.keys(origServers)) {
+    if (name === "neat") continue;
+    if (!isDeepStrictEqual(nextServers[name], origServers[name])) return false;
   }
-  if (result.removed.nodes.length || result.removed.edges.length) {
-    blockLines.push("Removed:");
-    for (const n of result.removed.nodes) blockLines.push(`  - node ${n.id} (${n.type})`);
-    for (const e of result.removed.edges)
-      blockLines.push(`  - edge ${e.id} \u2014 ${e.source} -> ${e.target} (${e.type}, ${e.provenance})`);
-    blockLines.push("");
+  for (const name of Object.keys(nextServers)) {
+    if (name !== "neat" && !(name in origServers)) return false;
   }
-  if (result.changed.nodes.length || result.changed.edges.length) {
-    blockLines.push("Changed:");
-    for (const c of result.changed.nodes) {
-      blockLines.push(`  ~ node ${c.id} \u2014 ${summariseAttrDiff(c.before, c.after)}`);
-    }
-    for (const c of result.changed.edges) {
-      const provBit = c.before.provenance !== c.after.provenance ? `provenance ${c.before.provenance} \u2192 ${c.after.provenance}` : summariseAttrDiff(c.before, c.after);
-      blockLines.push(`  ~ edge ${c.id} \u2014 ${provBit}`);
-    }
+  for (const key of Object.keys(original)) {
+    if (key === "mcp_servers") continue;
+    if (!isDeepStrictEqual(next[key], original[key])) return false;
   }
-  return {
-    summary: `Diff against ${input.againstSnapshot}: ${total} change${total === 1 ? "" : "s"} between the snapshot and the live graph.`,
-    block: blockLines.join("\n").trimEnd()
-  };
-}
-function summariseAttrDiff(before, after) {
-  const keys = /* @__PURE__ */ new Set([...Object.keys(before), ...Object.keys(after)]);
-  const changed = [];
-  for (const k of keys) {
-    if (JSON.stringify(before[k]) !== JSON.stringify(after[k])) changed.push(k);
+  for (const key of Object.keys(next)) {
+    if (key !== "mcp_servers" && !(key in original)) return false;
   }
-  return changed.length === 0 ? "attributes differ" : `fields changed: ${changed.sort().join(", ")}`;
+  return true;
 }
-async function runStaleEdges(client, input) {
-  const params = new URLSearchParams();
-  if (input.limit !== void 0) params.set("limit", String(input.limit));
-  if (input.edgeType) params.set("edgeType", input.edgeType);
-  const qs = params.size > 0 ? `?${params.toString()}` : "";
-  const body = await client.get(
-    projectPath(input.project, `/stale-events${qs}`)
-  );
-  const events = body.events;
-  if (events.length === 0) {
-    return {
-      summary: input.edgeType ? `No stale ${input.edgeType} edges recorded.` : "No stale-edge transitions recorded yet."
-    };
+function agentsBlock(guide) {
+  return `${NEAT_GRAPH_FIRST_START}
+${guide.replace(/\s+$/, "")}
+${NEAT_GRAPH_FIRST_END}
+`;
+}
+function upsertAgents(raw, guide) {
+  const block = agentsBlock(guide);
+  if (raw.length === 0) return { text: block, changed: true };
+  const startIdx = raw.indexOf(NEAT_GRAPH_FIRST_START);
+  const endIdx = raw.indexOf(NEAT_GRAPH_FIRST_END);
+  if (startIdx !== -1 && endIdx !== -1 && endIdx > startIdx) {
+    const before = raw.slice(0, startIdx);
+    const after = raw.slice(endIdx + NEAT_GRAPH_FIRST_END.length);
+    const text2 = `${before}${block.replace(/\n+$/, "")}${after}`;
+    return { text: text2, changed: text2 !== raw };
   }
-  const blockLines = events.map(
-    (e) => `  ${e.transitionedAt} \u2014 ${e.source} -[${e.edgeType}]-> ${e.target} (last seen ${e.lastObserved}, threshold ${formatDuration(e.thresholdMs)})`
-  );
-  return {
-    summary: `${events.length} stale-edge transition${events.length === 1 ? "" : "s"} recorded${input.edgeType ? ` for ${input.edgeType}` : ""}.`,
-    block: blockLines.join("\n"),
-    provenance: Provenance2.STALE
-  };
+  const base = raw.replace(/\n+$/, "");
+  const text = base.length > 0 ? `${base}
+
+${block}` : block;
+  return { text, changed: text !== raw };
 }
-async function runPolicies(client, input) {
-  let violations;
-  let allowed = true;
-  let hypothetical;
-  if (input.hypotheticalAction) {
-    if (typeof client.post !== "function") {
-      throw new Error("HttpClient does not support POST \u2014 required for policies dry-run");
-    }
-    const body = await client.post(
-      projectPath(input.project, "/policies/check"),
-      { hypotheticalAction: input.hypotheticalAction }
-    );
-    violations = body.violations;
-    allowed = body.allowed;
-    hypothetical = body.hypotheticalAction;
-  } else {
-    const params = new URLSearchParams();
-    if (input.policyId) params.set("policyId", input.policyId);
-    const qs = params.size > 0 ? `?${params.toString()}` : "";
-    const body = await client.get(
-      projectPath(input.project, `/policies/violations${qs}`)
+async function readGuide() {
+  return readSkillAsset(GUIDE_FILENAME);
+}
+async function runCodex(opts) {
+  if (opts.printConfig) {
+    process.stdout.write(`${CODEX_NEAT_BLOCK}
+`);
+    return { exitCode: 0 };
+  }
+  if (opts.printGuide) {
+    process.stdout.write(agentsBlock(await readGuide()));
+    return { exitCode: 0 };
+  }
+  const configPath = codexConfigPath();
+  const agentsPath = agentsFilePath();
+  let configRaw = "";
+  try {
+    configRaw = await fs13.readFile(configPath, "utf8");
+  } catch (err) {
+    if (err.code !== "ENOENT") {
+      console.error(`neat codex: failed to read ${configPath} \u2014 ${err.message}`);
+      return { exitCode: 1 };
+    }
+  }
+  let agentsRaw = "";
+  try {
+    agentsRaw = await fs13.readFile(agentsPath, "utf8");
+  } catch (err) {
+    if (err.code !== "ENOENT") {
+      console.error(`neat codex: failed to read ${agentsPath} \u2014 ${err.message}`);
+      return { exitCode: 1 };
+    }
+  }
+  let config;
+  try {
+    config = upsertCodexConfig(configRaw);
+  } catch (err) {
+    console.error(
+      `neat codex: ${configPath} is not valid TOML \u2014 ${err.message}`
     );
-    violations = body.violations;
-    allowed = violations.every((v) => v.onViolation !== "block");
+    console.error("neat codex: fix the file and re-run; nothing was written.");
+    return { exitCode: 1 };
   }
-  if (input.nodeId) {
-    violations = violations.filter(
-      (v) => v.subject.nodeId === input.nodeId || v.subject.path?.includes(input.nodeId)
+  const guide = await readGuide();
+  const agents = upsertAgents(agentsRaw, guide);
+  if (!opts.apply) {
+    console.log("neat codex \u2014 plan (nothing written; re-run with --apply to write)");
+    console.log("");
+    console.log(`  Codex MCP config: ${configPath}`);
+    console.log(
+      config.changed ? `    ${configRaw ? "update" : "create"} the [mcp_servers.neat] table:` : "    already up to date \u2014 [mcp_servers.neat] matches"
+    );
+    if (config.changed) {
+      for (const line of CODEX_NEAT_BLOCK.split("\n")) console.log(`      ${line}`);
+    }
+    console.log("");
+    console.log(`  Project instructions: ${agentsPath}`);
+    console.log(
+      agents.changed ? `    ${agentsRaw ? "update" : "create"} the graph-first block (between ${NEAT_GRAPH_FIRST_START} markers)` : "    already up to date \u2014 graph-first block matches"
     );
+    console.log("");
+    console.log("The MCP server reads NEAT_CORE_URL for the daemon URL \u2014 edit that value in");
+    console.log("the generated table to point Codex at a non-default daemon.");
+    return { exitCode: 0 };
   }
-  if (violations.length === 0) {
-    return {
-      summary: hypothetical ? `No violations would result from the hypothetical action (${hypothetical.kind}).` : "No policy violations recorded."
-    };
+  if (config.changed) {
+    await fs13.mkdir(path14.dirname(configPath), { recursive: true });
+    await fs13.writeFile(configPath, config.text, "utf8");
+    console.log(`neat codex: wrote [mcp_servers.neat] to ${configPath}`);
+  } else {
+    console.log(`neat codex: ${configPath} already has NEAT's MCP server`);
   }
-  const blockCount = violations.filter((v) => v.onViolation === "block").length;
-  const summaryParts = [];
-  if (hypothetical) {
-    summaryParts.push(
-      `Hypothetical ${hypothetical.kind} would surface ${violations.length} violation${violations.length === 1 ? "" : "s"}`
-    );
+  if (agents.changed) {
+    await fs13.mkdir(path14.dirname(agentsPath), { recursive: true });
+    await fs13.writeFile(agentsPath, agents.text, "utf8");
+    console.log(`neat codex: wrote the graph-first block to ${agentsPath}`);
   } else {
-    summaryParts.push(
-      `${violations.length} policy violation${violations.length === 1 ? "" : "s"} currently recorded`
-    );
+    console.log(`neat codex: ${agentsPath} already has the graph-first block`);
   }
-  if (blockCount > 0) summaryParts.push(`${blockCount} of which block`);
-  if (!allowed && hypothetical) summaryParts.push("action denied");
-  const summary = summaryParts.join("; ") + ".";
-  const blockLines = violations.map((v) => {
-    const subject = v.subject.nodeId ?? v.subject.edgeId ?? v.subject.path?.[0] ?? "(global)";
-    return `  \u2022 [${v.severity}/${v.onViolation}] ${v.policyName}: ${v.message} \u2014 ${subject}`;
-  });
-  const severities = [...new Set(violations.map((v) => v.severity))];
-  return {
-    summary,
-    block: blockLines.join("\n"),
-    confidence: hypothetical ? 0.7 : 1,
-    provenance: severities.join(" ")
-  };
+  console.log("");
+  console.log("restart Codex to pick up the new MCP server. NEAT_CORE_URL in the table");
+  console.log("points the server at the local daemon \u2014 edit it for a non-default one.");
+  return { exitCode: 0 };
 }
-function formatDivergenceLine(d) {
-  switch (d.type) {
-    case "missing-observed":
-    case "missing-extracted":
-      if (d.column) {
-        return `  \u2022 [${d.type}] ${d.table ?? d.source} column ${d.column} \u2014 confidence ${d.confidence.toFixed(2)}`;
-      }
-      return `  \u2022 [${d.type}] ${d.source} \u2192 ${d.target} (${d.edgeType}) \u2014 confidence ${d.confidence.toFixed(2)}`;
-    case "version-mismatch":
-      return `  \u2022 [${d.type}] ${d.source} \u2192 ${d.target} \u2014 declared ${d.extractedVersion}, observed engine ${d.observedVersion} (${d.compatibility})`;
-    case "host-mismatch":
-      return `  \u2022 [${d.type}] ${d.source} \u2192 ${d.target} \u2014 declared host ${d.extractedHost}, observed host ${d.observedHost}`;
-    case "compat-violation":
-      return `  \u2022 [${d.type}] ${d.source} \u2192 ${d.target} \u2014 ${d.rule.kind}${d.rule.package ? ` (${d.rule.package})` : ""}`;
-    case "observed-symbol-mismatch": {
-      const at = d.location ? ` at ${d.location}` : "";
-      const member = d.symbol ? ` ${d.symbol}` : "";
-      return `  \u2022 [${d.type}] ${d.source}${member}${at} (${d.mismatchKind}) \u2014 confidence ${d.confidence.toFixed(2)}`;
+function usage3() {
+  console.log("neat codex \u2014 install NEAT into the OpenAI Codex CLI (MCP server + AGENTS.md)");
+  console.log("");
+  console.log("  (no flag)        plan: print what would change, write nothing");
+  console.log("  --apply          add [mcp_servers.neat] to ~/.codex/config.toml and write");
+  console.log("                   the graph-first block into ./AGENTS.md, merging into both");
+  console.log("                   without touching your other servers or instructions");
+  console.log("  --print-config   print the [mcp_servers.neat] TOML block to stdout");
+  console.log("  --print-guide    print the AGENTS.md graph-first block to stdout");
+  console.log("");
+  console.log("Existing config is preserved and a re-run is a no-op. A malformed");
+  console.log("config.toml is a clear error with no partial write.");
+}
+async function runCodexCommand(args) {
+  const opts = { apply: false, printConfig: false, printGuide: false };
+  for (const arg of args) {
+    switch (arg) {
+      case "--apply":
+        opts.apply = true;
+        break;
+      case "--print-config":
+        opts.printConfig = true;
+        break;
+      case "--print-guide":
+        opts.printGuide = true;
+        break;
+      case "-h":
+      case "--help":
+        usage3();
+        return 0;
+      default:
+        console.error(`neat codex: unknown flag "${arg}"`);
+        usage3();
+        return 2;
+    }
+  }
+  try {
+    const { exitCode } = await runCodex(opts);
+    return exitCode;
+  } catch (err) {
+    console.error(err.message);
+    return 1;
+  }
+}
+
+// src/editors-cli.ts
+import path15 from "path";
+import os3 from "os";
+import { promises as fs14 } from "fs";
+import { isDeepStrictEqual as isDeepStrictEqual2 } from "util";
+import * as jsonc from "jsonc-parser";
+var NEAT_MCP_SERVER = {
+  command: "npx",
+  args: ["-y", "@neat.is/mcp"]
+};
+var NEAT_OPENCODE_SERVER = {
+  type: "local",
+  command: ["npx", "-y", "@neat.is/mcp"],
+  enabled: true
+};
+var NEAT_CRUSH_SERVER = {
+  type: "stdio",
+  command: "npx",
+  args: ["-y", "@neat.is/mcp"]
+};
+var GRAPH_FIRST_MARKER_OPEN = "<!-- neat:graph-first -->";
+var GRAPH_FIRST_MARKER_CLOSE = "<!-- /neat:graph-first -->";
+function homeDir() {
+  return process.env.HOME ?? process.env.USERPROFILE ?? os3.homedir();
+}
+function xdgConfigDir() {
+  const xdg = process.env.XDG_CONFIG_HOME;
+  return xdg && xdg.length > 0 ? path15.resolve(xdg) : path15.join(homeDir(), ".config");
+}
+function envOverride(name) {
+  const v = process.env[name];
+  return v && v.length > 0 ? path15.resolve(v) : void 0;
+}
+var CURSOR_CLIENT = {
+  id: "cursor",
+  label: "Cursor",
+  docsUrl: "https://docs.cursor.com/context/mcp",
+  mcpConfigPath: () => envOverride("NEAT_CURSOR_CONFIG") ?? path15.join(homeDir(), ".cursor", "mcp.json"),
+  mcpContainerKey: "mcpServers",
+  format: "json",
+  // Cursor still reads a single `.cursorrules` at the project root (the modern
+  // `.cursor/rules/*.mdc` split is one-rule-per-file with frontmatter — a worse
+  // fit for a marker-fenced block). GRAPH_FIRST.md names this file directly.
+  rulesFileName: ".cursorrules"
+};
+var DEVIN_CLIENT = {
+  id: "devin",
+  label: "Devin Desktop (Cascade)",
+  docsUrl: "https://docs.devin.ai/desktop/cascade/mcp",
+  mcpConfigPath: () => envOverride("NEAT_DEVIN_CONFIG") ?? path15.join(homeDir(), ".codeium", "windsurf", "mcp_config.json"),
+  mcpContainerKey: "mcpServers",
+  format: "json",
+  rulesFileName: ".windsurfrules"
+};
+var GEMINI_CLIENT = {
+  id: "gemini",
+  label: "Gemini CLI",
+  docsUrl: "https://github.com/google-gemini/gemini-cli/blob/main/docs/tools/mcp-server.md",
+  mcpConfigPath: () => envOverride("NEAT_GEMINI_CONFIG") ?? path15.join(homeDir(), ".gemini", "settings.json"),
+  mcpContainerKey: "mcpServers",
+  format: "json",
+  rulesFileName: "GEMINI.md"
+};
+var QWEN_CLIENT = {
+  id: "qwen",
+  label: "Qwen Code",
+  docsUrl: "https://qwenlm.github.io/qwen-code-docs/en/users/features/mcp/",
+  mcpConfigPath: () => envOverride("NEAT_QWEN_CONFIG") ?? path15.join(homeDir(), ".qwen", "settings.json"),
+  mcpContainerKey: "mcpServers",
+  format: "json",
+  rulesFileName: "QWEN.md"
+};
+var AMAZONQ_CLIENT = {
+  id: "amazonq",
+  label: "Amazon Q Developer CLI",
+  docsUrl: "https://docs.aws.amazon.com/amazonq/latest/qdeveloper-ug/command-line-mcp-configuration.html",
+  mcpConfigPath: () => envOverride("NEAT_AMAZONQ_CONFIG") ?? path15.join(homeDir(), ".aws", "amazonq", "mcp.json"),
+  mcpContainerKey: "mcpServers",
+  format: "json"
+};
+var ROOCODE_CLIENT = {
+  id: "roocode",
+  label: "Roo Code",
+  docsUrl: "https://roocodeinc.github.io/Roo-Code/features/mcp/using-mcp-in-roo",
+  mcpConfigPath: () => envOverride("NEAT_ROOCODE_CONFIG") ?? path15.join(process.cwd(), ".roo", "mcp.json"),
+  mcpContainerKey: "mcpServers",
+  format: "json"
+};
+var ZED_CLIENT = {
+  id: "zed",
+  label: "Zed",
+  docsUrl: "https://zed.dev/docs/ai/mcp",
+  mcpConfigPath: () => {
+    const override = envOverride("NEAT_ZED_CONFIG");
+    if (override) return override;
+    if (process.platform === "win32") {
+      const appData = process.env.APPDATA;
+      if (appData && appData.length > 0) return path15.join(appData, "Zed", "settings.json");
     }
+    return path15.join(homeDir(), ".config", "zed", "settings.json");
+  },
+  mcpContainerKey: "context_servers",
+  format: "jsonc",
+  rulesFileName: ".rules"
+};
+var OPENCODE_CLIENT = {
+  id: "opencode",
+  label: "OpenCode",
+  docsUrl: "https://opencode.ai/docs/mcp-servers/",
+  mcpConfigPath: () => envOverride("NEAT_OPENCODE_CONFIG") ?? path15.join(xdgConfigDir(), "opencode", "opencode.json"),
+  mcpContainerKey: "mcp",
+  format: "json",
+  serverEntry: NEAT_OPENCODE_SERVER,
+  rulesFileName: "AGENTS.md"
+};
+var CRUSH_CLIENT = {
+  id: "crush",
+  label: "Crush",
+  docsUrl: "https://charmbracelet-crush.mintlify.app/configuration/mcp",
+  mcpConfigPath: () => envOverride("NEAT_CRUSH_CONFIG") ?? path15.join(xdgConfigDir(), "crush", "crush.json"),
+  mcpContainerKey: "mcp",
+  format: "json",
+  serverEntry: NEAT_CRUSH_SERVER,
+  rulesFileName: "AGENTS.md"
+};
+var CLIENTS = {
+  cursor: CURSOR_CLIENT,
+  devin: DEVIN_CLIENT,
+  gemini: GEMINI_CLIENT,
+  qwen: QWEN_CLIENT,
+  amazonq: AMAZONQ_CLIENT,
+  roocode: ROOCODE_CLIENT,
+  zed: ZED_CLIENT,
+  opencode: OPENCODE_CLIENT,
+  crush: CRUSH_CLIENT
+};
+function mergeJsonMcp(existing, containerKey, serverEntry) {
+  const servers = existing[containerKey] ?? {};
+  const already = isDeepStrictEqual2(servers.neat, serverEntry);
+  const merged = {
+    ...existing,
+    [containerKey]: { ...servers, neat: serverEntry }
+  };
+  return { merged, changed: !already };
+}
+function mergeJsoncMcp(raw, containerKey, serverEntry) {
+  const base = raw.trim().length > 0 ? raw : "{}";
+  const parsed = jsonc.parse(base) ?? {};
+  const servers = parsed[containerKey] ?? {};
+  if (isDeepStrictEqual2(servers.neat, serverEntry)) {
+    return { text: raw, changed: false };
   }
+  const edits = jsonc.modify(base, [containerKey, "neat"], serverEntry, {
+    formattingOptions: { tabSize: 2, insertSpaces: true }
+  });
+  let text = jsonc.applyEdits(base, edits);
+  if (!text.endsWith("\n")) text += "\n";
+  return { text, changed: text !== raw };
 }
-async function runDivergences(client, input) {
-  const params = new URLSearchParams();
-  if (input.type && input.type.length > 0) params.set("type", input.type.join(","));
-  if (input.minConfidence !== void 0) {
-    params.set("minConfidence", String(input.minConfidence));
-  }
-  if (input.node) params.set("node", input.node);
-  const qs = params.size > 0 ? `?${params.toString()}` : "";
-  const result = await client.get(
-    projectPath(input.project, `/graph/divergences${qs}`)
+function escapeRegExp(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function buildGuidanceBlock(guide) {
+  return `${GRAPH_FIRST_MARKER_OPEN}
+${guide.trim()}
+${GRAPH_FIRST_MARKER_CLOSE}
+`;
+}
+function mergeRulesFile(existing, block) {
+  const region = new RegExp(
+    `${escapeRegExp(GRAPH_FIRST_MARKER_OPEN)}[\\s\\S]*?${escapeRegExp(GRAPH_FIRST_MARKER_CLOSE)}\\n?`
   );
-  if (result.totalAffected === 0) {
-    return {
-      summary: "No divergences found between the declared (EXTRACTED) and observed (OBSERVED) views of the graph."
-    };
+  if (region.test(existing)) return existing.replace(region, block);
+  if (existing.trim().length === 0) return block;
+  return `${existing.replace(/\s+$/, "")}
+
+${block}`;
+}
+async function planMcp(client, mcpPath) {
+  const serverEntry = client.serverEntry ?? NEAT_MCP_SERVER;
+  let raw = "";
+  try {
+    raw = await fs14.readFile(mcpPath, "utf8");
+  } catch (err) {
+    const e = err;
+    if (e.code === "ENOENT") {
+      raw = "";
+    } else {
+      console.error(`neat ${client.id}: failed to read ${mcpPath} \u2014 ${e.message}`);
+      return null;
+    }
   }
-  const headline = result.divergences[0];
-  const summary = `Found ${result.totalAffected} divergence${result.totalAffected === 1 ? "" : "s"} between code and production. Highest-confidence: ${headline.type} on ${headline.source} \u2192 ${headline.target}. ${headline.reason}`;
-  const blockLines = [];
-  for (const d of result.divergences) {
-    blockLines.push(formatDivergenceLine(d));
-    blockLines.push(`    reason: ${d.reason}`);
-    blockLines.push(`    recommendation: ${d.recommendation}`);
+  if (client.format === "jsonc") {
+    if (raw.trim().length > 0) {
+      const errors = [];
+      jsonc.parse(raw, errors, { allowTrailingComma: true });
+      if (errors.length > 0) {
+        const first = errors[0];
+        console.error(
+          `neat ${client.id}: ${mcpPath} is not valid JSONC \u2014 ${jsonc.printParseErrorCode(first.error)} at offset ${first.offset}. Fix it (or move it aside) and re-run; nothing was written.`
+        );
+        return null;
+      }
+    }
+    return mergeJsoncMcp(raw, client.mcpContainerKey, serverEntry);
   }
-  const maxConfidence = result.divergences.reduce(
-    (m, d) => Math.max(m, d.confidence),
-    0
-  );
-  return {
-    summary,
-    block: blockLines.join("\n"),
-    confidence: maxConfidence,
-    provenance: "composite (EXTRACTED + OBSERVED)"
-  };
+  let existing = {};
+  if (raw.trim().length > 0) {
+    try {
+      existing = JSON.parse(raw);
+    } catch (err) {
+      console.error(
+        `neat ${client.id}: ${mcpPath} is not valid JSON \u2014 ${err.message}. Fix it (or move it aside) and re-run; nothing was written.`
+      );
+      return null;
+    }
+  }
+  const { merged, changed } = mergeJsonMcp(existing, client.mcpContainerKey, serverEntry);
+  return { text: JSON.stringify(merged, null, 2) + "\n", changed };
 }
-async function runAsk(client, input) {
-  const result = await client.get(
-    projectPath(input.project, `/graph/ask?q=${encodeURIComponent(input.question)}`)
-  );
-  const blockLines = [];
-  if (result.matched.length > 0) {
-    blockLines.push(
-      `Matched: ${result.matched.map((m) => `${m.nodeId} [${m.via} ${m.score.toFixed(2)}]`).join(", ")}`
-    );
-    blockLines.push(`Intent: ${result.intent}`);
-  } else if (result.scope === "global") {
-    blockLines.push(`Graph-wide answer (${result.intent}) \u2014 no entity named.`);
+async function runEditorInstall(client, opts) {
+  const mcpPath = client.mcpConfigPath();
+  const serverEntry = client.serverEntry ?? NEAT_MCP_SERVER;
+  const hasRules = typeof client.rulesFileName === "string";
+  const rulesPath = hasRules ? path15.join(opts.projectDir, client.rulesFileName) : "";
+  const mcp = await planMcp(client, mcpPath);
+  if (mcp === null) return { exitCode: 1 };
+  let existingRules = "";
+  let newRules = "";
+  let rulesChanged = false;
+  let block = "";
+  if (hasRules) {
+    try {
+      existingRules = await fs14.readFile(rulesPath, "utf8");
+    } catch (err) {
+      if (err.code !== "ENOENT") {
+        console.error(`neat ${client.id}: failed to read ${rulesPath} \u2014 ${err.message}`);
+        return { exitCode: 1 };
+      }
+    }
+    const guide = await readSkillAsset(GUIDE_FILENAME);
+    block = buildGuidanceBlock(guide);
+    newRules = mergeRulesFile(existingRules, block);
+    rulesChanged = newRules !== existingRules;
   }
-  for (const section of result.sections) {
-    blockLines.push("", section.heading + ":");
-    for (const fact of section.facts) {
-      const tag = fact.provenance ? ` [${fact.provenance}${fact.confidence !== void 0 ? ` ${fact.confidence.toFixed(2)}` : ""}]` : fact.confidence !== void 0 ? ` [confidence ${fact.confidence.toFixed(2)}]` : "";
-      blockLines.push(`  \u2022 ${fact.text}${tag}`);
+  if (!opts.apply) {
+    console.log(`neat ${client.id} \u2014 wire NEAT into ${client.label} (plan; nothing written)`);
+    console.log("");
+    console.log(`MCP server \u2192 ${mcpPath}`);
+    console.log(
+      mcp.changed ? `  would add ${client.mcpContainerKey}.neat:` : `  ${client.mcpContainerKey}.neat already present and current \u2014 no change:`
+    );
+    console.log(indent(JSON.stringify({ neat: serverEntry }, null, 2)));
+    if (hasRules) {
+      console.log("");
+      console.log(`Graph-first guidance \u2192 ${rulesPath}`);
+      console.log(
+        rulesChanged ? existingRules.includes(GRAPH_FIRST_MARKER_OPEN) ? "  would refresh the neat:graph-first block:" : "  would add the neat:graph-first block:" : "  neat:graph-first block already present and current \u2014 no change."
+      );
+      if (rulesChanged) console.log(indent(block.trimEnd()));
     }
+    console.log("");
+    console.log(
+      hasRules ? `Re-run with --apply to write both files. Existing servers and rules are kept.` : `Re-run with --apply to write the config. Existing servers are kept.`
+    );
+    return { exitCode: 0 };
   }
-  return {
-    summary: result.answer,
-    block: blockLines.join("\n").trim(),
-    ...result.confidence !== void 0 ? { confidence: result.confidence } : {},
-    ...result.provenance.length > 0 ? { provenance: result.provenance } : {}
-  };
-}
-function formatFooter(confidence, provenance) {
-  const c = confidence === void 0 ? "n/a" : confidence.toFixed(2);
-  const p = provenance === void 0 ? "n/a" : Array.isArray(provenance) ? [...new Set(provenance)].join(", ") : provenance;
-  return `confidence: ${c} \xB7 provenance: ${p}`;
+  await fs14.mkdir(path15.dirname(mcpPath), { recursive: true });
+  await fs14.writeFile(mcpPath, mcp.text, "utf8");
+  if (hasRules) {
+    await fs14.mkdir(path15.dirname(rulesPath), { recursive: true });
+    await fs14.writeFile(rulesPath, newRules, "utf8");
+  }
+  console.log(`neat ${client.id}: wired NEAT into ${client.label}`);
+  console.log(`  MCP server: ${mcpPath} (${client.mcpContainerKey}.neat \u2192 npx -y @neat.is/mcp)`);
+  if (hasRules) console.log(`  guidance:   ${rulesPath} (neat:graph-first block)`);
+  console.log("");
+  console.log(`restart ${client.label} to pick up the MCP server. Point it at a non-default`);
+  console.log(`daemon by setting NEAT_CORE_URL in the neat server's env in that config.`);
+  return { exitCode: 0 };
 }
-function formatHuman(result) {
-  const sections = [result.summary.trim()];
-  if (result.block && result.block.trim().length > 0) sections.push(result.block.trimEnd());
-  sections.push(formatFooter(result.confidence, result.provenance));
-  return sections.join("\n\n");
+function indent(text) {
+  return text.split("\n").map((line) => line.length > 0 ? `    ${line}` : line).join("\n");
 }
-function formatJson(result) {
-  return JSON.stringify(
-    {
-      summary: result.summary,
-      block: result.block ?? "",
-      confidence: result.confidence ?? null,
-      provenance: result.provenance ?? null
-    },
-    null,
-    2
+function usage4(client) {
+  const hasRules = typeof client.rulesFileName === "string";
+  console.log(
+    hasRules ? `neat ${client.id} \u2014 install NEAT's MCP server + graph-first guidance into ${client.label}` : `neat ${client.id} \u2014 install NEAT's MCP server into ${client.label}`
   );
+  console.log("");
+  console.log(
+    hasRules ? "  --apply   write the MCP config and the rules file (default: plan only)" : "  --apply   write the MCP config (default: plan only)"
+  );
+  console.log("");
+  console.log("Writes NEAT's stdio MCP server (npx -y @neat.is/mcp) into");
+  console.log(`  ${client.mcpConfigPath()}`);
+  if (hasRules) {
+    console.log(`and the graph-first guidance block into ./${client.rulesFileName}, both`);
+    console.log("additively \u2014 existing servers and rules are preserved, a re-run is a no-op.");
+  } else {
+    console.log("additively \u2014 existing servers are preserved, a re-run is a no-op.");
+  }
+  console.log("");
+  console.log(`See ${client.docsUrl} for ${client.label}'s MCP config format.`);
 }
-function exitCodeForError(err) {
-  if (err instanceof TransportError) return 3;
-  if (err instanceof HttpError) return 1;
-  return 1;
-}
-function createSnapshotPushClient(baseUrl, token) {
-  return createHttpClient(baseUrl, token && token.length > 0 ? token : void 0);
-}
-async function pushSnapshotToRemote(input) {
-  const client = createSnapshotPushClient(input.baseUrl, input.token);
-  if (typeof client.post !== "function") {
-    throw new Error("HttpClient does not support POST \u2014 required for snapshot push");
+async function runEditorCommand(clientId, args, projectDir = process.cwd()) {
+  const client = CLIENTS[clientId];
+  let apply6 = false;
+  for (const arg of args) {
+    switch (arg) {
+      case "--apply":
+        apply6 = true;
+        break;
+      case "-h":
+      case "--help":
+        usage4(client);
+        return 0;
+      default:
+        console.error(`neat ${client.id}: unknown flag "${arg}"`);
+        usage4(client);
+        return 2;
+    }
+  }
+  try {
+    const { exitCode } = await runEditorInstall(client, { apply: apply6, projectDir });
+    return exitCode;
+  } catch (err) {
+    console.error(err.message);
+    return 1;
   }
-  return client.post(
-    `/projects/${encodeURIComponent(input.project)}/snapshot`,
-    { snapshot: input.snapshot }
-  );
 }
 
 // src/monitor.ts
+import { EdgeType, parseEdgeId, Provenance as Provenance3 } from "@neat.is/types";
 var OBSERVED_DEP_EDGE_TYPES = /* @__PURE__ */ new Set([
   EdgeType.CALLS,
   EdgeType.CONNECTS_TO,
@@ -6713,7 +6857,7 @@ function sleep(ms, signal) {
 }
 
 // src/cli-verbs.ts
-import path15 from "path";
+import path16 from "path";
 async function resolveProjectEntry(opts) {
   const entries = await listProjects();
   if (opts.project) {
@@ -6723,7 +6867,7 @@ async function resolveProjectEntry(opts) {
   const cwd = opts.cwd ?? process.cwd();
   const resolvedCwd = await normalizeProjectPath(cwd);
   for (const entry2 of entries) {
-    if (resolvedCwd === entry2.path || resolvedCwd.startsWith(`${entry2.path}${path15.sep}`)) {
+    if (resolvedCwd === entry2.path || resolvedCwd.startsWith(`${entry2.path}${path16.sep}`)) {
       return entry2;
     }
   }
@@ -7025,6 +7169,9 @@ function usage5() {
   console.log("                   test <id>        re-check an existing connector's credential");
   console.log("                 Credentials default to an env-var reference ($VAR) resolved at");
   console.log("                 run time; the config file is written owner-only (0600).");
+  console.log("  doctor         Preflight this directory's setup \u2014 Node version, project,");
+  console.log("                 and daemon reachability \u2014 and print a fix for anything down.");
+  console.log("                 Flags: --json. Exits 0 when all pass, 1 when a check fails.");
   console.log("");
   console.log("query commands (mirror the MCP tools, ADR-050):");
   console.log("  ask <question>                   Plain-language door: resolves the question to");
@@ -7250,7 +7397,7 @@ async function buildPatchSections(services, project) {
 }
 async function runInit(opts) {
   const written = [];
-  const stat = await fs14.stat(opts.scanPath).catch(() => null);
+  const stat = await fs15.stat(opts.scanPath).catch(() => null);
   if (!stat || !stat.isDirectory()) {
     console.error(`neat init: ${opts.scanPath} is not a directory`);
     return { exitCode: 2, writtenFiles: written };
@@ -7259,13 +7406,13 @@ async function runInit(opts) {
   printDiscoveryReport(opts, services);
   const sections = opts.noInstall ? [] : await buildPatchSections(services, opts.project);
   const patch = renderPatch(sections);
-  const patchPath = path16.join(opts.scanPath, "neat.patch");
+  const patchPath = path17.join(opts.scanPath, "neat.patch");
   if (opts.dryRun) {
-    await fs14.writeFile(patchPath, patch, "utf8");
+    await fs15.writeFile(patchPath, patch, "utf8");
     written.push(patchPath);
     console.log(`dry-run: patch written to ${patchPath}`);
-    const gitignorePath = path16.join(opts.scanPath, ".gitignore");
-    const gitignoreExists = await fs14.stat(gitignorePath).then(() => true).catch(() => false);
+    const gitignorePath = path17.join(opts.scanPath, ".gitignore");
+    const gitignoreExists = await fs15.stat(gitignorePath).then(() => true).catch(() => false);
     const verb = gitignoreExists ? "append" : "create";
     console.log(`dry-run: would ${verb} ${gitignorePath} (add neat-out/)`);
     console.log("rerun without --dry-run to register and snapshot.");
@@ -7276,9 +7423,9 @@ async function runInit(opts) {
   const graph = getGraph(graphKey);
   const projectPaths = pathsForProject(
     graphKey,
-    path16.join(opts.scanPath, "neat-out")
+    path17.join(opts.scanPath, "neat-out")
   );
-  const errorsPath = path16.join(path16.dirname(opts.outPath), path16.basename(projectPaths.errorsPath));
+  const errorsPath = path17.join(path17.dirname(opts.outPath), path17.basename(projectPaths.errorsPath));
   const result = await extractFromDirectory(graph, opts.scanPath, { errorsPath });
   await saveGraphToDisk(graph, opts.outPath);
   written.push(opts.outPath);
@@ -7357,7 +7504,7 @@ async function runInit(opts) {
         console.log("Run `npm install` (or your language equivalent) to refresh lockfiles.");
       }
     } else {
-      await fs14.writeFile(patchPath, patch, "utf8");
+      await fs15.writeFile(patchPath, patch, "utf8");
       written.push(patchPath);
     }
   }
@@ -7398,9 +7545,9 @@ var CLAUDE_SKILL_CONFIG = {
 };
 function claudeConfigPath() {
   const override = process.env.NEAT_CLAUDE_CONFIG;
-  if (override && override.length > 0) return path16.resolve(override);
+  if (override && override.length > 0) return path17.resolve(override);
   const home = process.env.HOME ?? process.env.USERPROFILE ?? "";
-  return path16.join(home, ".claude.json");
+  return path17.join(home, ".claude.json");
 }
 async function runSkill(opts) {
   const snippet = JSON.stringify(CLAUDE_SKILL_CONFIG, null, 2) + "\n";
@@ -7412,7 +7559,7 @@ async function runSkill(opts) {
     const target = claudeConfigPath();
     let existing = {};
     try {
-      existing = JSON.parse(await fs14.readFile(target, "utf8"));
+      existing = JSON.parse(await fs15.readFile(target, "utf8"));
     } catch (err) {
       if (err.code !== "ENOENT") {
         console.error(`neat skill: failed to read ${target} \u2014 ${err.message}`);
@@ -7424,8 +7571,8 @@ async function runSkill(opts) {
       ...existing,
       mcpServers: { ...mcp, neat: CLAUDE_SKILL_CONFIG.mcpServers.neat }
     };
-    await fs14.mkdir(path16.dirname(target), { recursive: true });
-    await fs14.writeFile(target, JSON.stringify(merged, null, 2) + "\n", "utf8");
+    await fs15.mkdir(path17.dirname(target), { recursive: true });
+    await fs15.writeFile(target, JSON.stringify(merged, null, 2) + "\n", "utf8");
     console.log(`neat skill: wrote mcpServers.neat to ${target}`);
     console.log("restart Claude Code to pick up the new MCP server.");
     console.log("");
@@ -7464,6 +7611,11 @@ async function main() {
     if (code !== 0) process.exit(code);
     return;
   }
+  if (cmd0 === "doctor") {
+    const code = await runDoctorCommand(argv.slice(1));
+    if (code !== 0) process.exit(code);
+    return;
+  }
   if (cmd0 === "hooks") {
     const code = await runHooksCommand(argv.slice(1));
     if (code !== 0) process.exit(code);
@@ -7516,12 +7668,12 @@ async function main() {
       console.error("neat init: --apply and --dry-run are mutually exclusive");
       process.exit(2);
     }
-    const scanPath = path16.resolve(target);
+    const scanPath = path17.resolve(target);
     const projectExplicit = parsed.project !== null;
-    const projectName = projectExplicit ? project : path16.basename(scanPath);
+    const projectName = projectExplicit ? project : path17.basename(scanPath);
     const projectKey = projectExplicit ? project : DEFAULT_PROJECT;
-    const fallback = pathsForProject(projectKey, path16.join(scanPath, "neat-out")).snapshotPath;
-    const outPath = path16.resolve(process.env.NEAT_OUT_PATH ?? fallback);
+    const fallback = pathsForProject(projectKey, path17.join(scanPath, "neat-out")).snapshotPath;
+    const outPath = path17.resolve(process.env.NEAT_OUT_PATH ?? fallback);
     const result = await runInit({
       scanPath,
       outPath,
@@ -7542,21 +7694,21 @@ async function main() {
       usage5();
       process.exit(2);
     }
-    const scanPath = path16.resolve(target);
-    const stat = await fs14.stat(scanPath).catch(() => null);
+    const scanPath = path17.resolve(target);
+    const stat = await fs15.stat(scanPath).catch(() => null);
     if (!stat || !stat.isDirectory()) {
       console.error(`neat watch: ${scanPath} is not a directory`);
       process.exit(2);
     }
-    const projectPaths = pathsForProject(project, path16.join(scanPath, "neat-out"));
-    const outPath = path16.resolve(process.env.NEAT_OUT_PATH ?? projectPaths.snapshotPath);
-    const errorsPath = path16.resolve(
-      process.env.NEAT_ERRORS_PATH ?? path16.join(path16.dirname(outPath), path16.basename(projectPaths.errorsPath))
+    const projectPaths = pathsForProject(project, path17.join(scanPath, "neat-out"));
+    const outPath = path17.resolve(process.env.NEAT_OUT_PATH ?? projectPaths.snapshotPath);
+    const errorsPath = path17.resolve(
+      process.env.NEAT_ERRORS_PATH ?? path17.join(path17.dirname(outPath), path17.basename(projectPaths.errorsPath))
     );
-    const staleEventsPath = path16.resolve(
-      process.env.NEAT_STALE_EVENTS_PATH ?? path16.join(path16.dirname(outPath), path16.basename(projectPaths.staleEventsPath))
+    const staleEventsPath = path17.resolve(
+      process.env.NEAT_STALE_EVENTS_PATH ?? path17.join(path17.dirname(outPath), path17.basename(projectPaths.staleEventsPath))
     );
-    const embeddingsCachePath = process.env.NEAT_EMBEDDINGS_CACHE_PATH ? path16.resolve(process.env.NEAT_EMBEDDINGS_CACHE_PATH) : void 0;
+    const embeddingsCachePath = process.env.NEAT_EMBEDDINGS_CACHE_PATH ? path17.resolve(process.env.NEAT_EMBEDDINGS_CACHE_PATH) : void 0;
     const handle = await startWatch(getGraph(project), {
       scanPath,
       outPath,
@@ -7565,7 +7717,7 @@ async function main() {
       project,
       // Resolve NEAT_HOME so a `neat watch` picks up connectors added to
       // ~/.neat/connectors.json (#871). Same resolution the rest of the CLI uses.
-      neatHome: process.env.NEAT_HOME ? path16.resolve(process.env.NEAT_HOME) : path16.join(os4.homedir(), ".neat"),
+      neatHome: process.env.NEAT_HOME ? path17.resolve(process.env.NEAT_HOME) : path17.join(os4.homedir(), ".neat"),
       ...embeddingsCachePath ? { embeddingsCachePath } : {},
       host: process.env.HOST ?? "0.0.0.0",
       port: Number(process.env.PORT ?? 8080),
@@ -7747,11 +7899,11 @@ async function main() {
   process.exit(1);
 }
 async function tryOrchestrator(cmd, parsed) {
-  const scanPath = path16.resolve(cmd);
-  const stat = await fs14.stat(scanPath).catch(() => null);
+  const scanPath = path17.resolve(cmd);
+  const stat = await fs15.stat(scanPath).catch(() => null);
   if (!stat || !stat.isDirectory()) return null;
   const projectExplicit = parsed.project !== null;
-  const projectName = projectExplicit ? parsed.project : path16.basename(scanPath);
+  const projectName = projectExplicit ? parsed.project : path17.basename(scanPath);
   const result = await runOrchestrator({
     scanPath,
     project: projectName,