@neat.is/core 0.2.6 → 0.2.8

package/dist/cli.cjs

@@ -101,8 +101,8 @@ function reshapeGrpcRequest(req) {
   };
 }
 function resolveProtoRoot() {
-  const here = import_node_path29.default.dirname((0, import_node_url.fileURLToPath)(importMetaUrl));
-  return import_node_path29.default.resolve(here, "..", "proto");
+  const here = import_node_path30.default.dirname((0, import_node_url.fileURLToPath)(importMetaUrl));
+  return import_node_path30.default.resolve(here, "..", "proto");
 }
 function loadTraceService() {
   const protoRoot = resolveProtoRoot();
@@ -157,13 +157,13 @@ async function startOtelGrpcReceiver(opts) {
     })
   };
 }
-var import_node_url, import_node_path29, grpc, protoLoader;
+var import_node_url, import_node_path30, grpc, protoLoader;
 var init_otel_grpc = __esm({
   "src/otel-grpc.ts"() {
     "use strict";
     init_cjs_shims();
     import_node_url = require("url");
-    import_node_path29 = __toESM(require("path"), 1);
+    import_node_path30 = __toESM(require("path"), 1);
     grpc = __toESM(require("@grpc/grpc-js"), 1);
     protoLoader = __toESM(require("@grpc/proto-loader"), 1);
     init_otel();
@@ -260,10 +260,10 @@ function parseOtlpRequest(body) {
 }
 function loadProtobufDecoder() {
   if (exportTraceServiceRequestType) return exportTraceServiceRequestType;
-  const here = import_node_path30.default.dirname((0, import_node_url2.fileURLToPath)(importMetaUrl));
-  const protoRoot = import_node_path30.default.resolve(here, "..", "proto");
+  const here = import_node_path31.default.dirname((0, import_node_url2.fileURLToPath)(importMetaUrl));
+  const protoRoot = import_node_path31.default.resolve(here, "..", "proto");
   const root = new import_protobufjs.default.Root();
-  root.resolvePath = (_origin, target) => import_node_path30.default.resolve(protoRoot, target);
+  root.resolvePath = (_origin, target) => import_node_path31.default.resolve(protoRoot, target);
   root.loadSync(
     "opentelemetry/proto/collector/trace/v1/trace_service.proto",
     { keepCase: true }
@@ -355,12 +355,12 @@ async function buildOtelReceiver(opts) {
   };
   return decorated;
 }
-var import_node_path30, import_node_url2, import_fastify2, import_protobufjs, exportTraceServiceRequestType;
+var import_node_path31, import_node_url2, import_fastify2, import_protobufjs, exportTraceServiceRequestType;
 var init_otel = __esm({
   "src/otel.ts"() {
     "use strict";
     init_cjs_shims();
-    import_node_path30 = __toESM(require("path"), 1);
+    import_node_path31 = __toESM(require("path"), 1);
     import_node_url2 = require("url");
     import_fastify2 = __toESM(require("fastify"), 1);
     import_protobufjs = __toESM(require("protobufjs"), 1);
@@ -372,7 +372,10 @@ var init_otel = __esm({
 var cli_exports = {};
 __export(cli_exports, {
   CLAUDE_SKILL_CONFIG: () => CLAUDE_SKILL_CONFIG,
+  QUERY_VERBS: () => QUERY_VERBS,
+  parseArgs: () => parseArgs,
   runInit: () => runInit,
+  runQueryVerb: () => runQueryVerb,
   runSkill: () => runSkill
 });
 module.exports = __toCommonJS(cli_exports);
@@ -735,6 +738,68 @@ function deprecatedApis() {
   return currentMatrix().deprecatedApis ?? [];
 }
 
+// src/events.ts
+init_cjs_shims();
+var import_node_events = require("events");
+var EVENT_BUS_CHANNEL = "event";
+var NeatEventBus = class extends import_node_events.EventEmitter {
+};
+var eventBus = new NeatEventBus();
+eventBus.setMaxListeners(0);
+function emitNeatEvent(envelope) {
+  eventBus.emit(EVENT_BUS_CHANNEL, envelope);
+}
+function attachGraphToEventBus(graph, opts) {
+  const { project } = opts;
+  const onNodeAdded = (payload) => {
+    emitNeatEvent({
+      type: "node-added",
+      project,
+      payload: { node: payload.attributes }
+    });
+  };
+  const onNodeDropped = (payload) => {
+    emitNeatEvent({
+      type: "node-removed",
+      project,
+      payload: { id: payload.key }
+    });
+  };
+  const onEdgeAdded = (payload) => {
+    emitNeatEvent({
+      type: "edge-added",
+      project,
+      payload: { edge: payload.attributes }
+    });
+  };
+  const onEdgeDropped = (payload) => {
+    emitNeatEvent({
+      type: "edge-removed",
+      project,
+      payload: { id: payload.key }
+    });
+  };
+  const onNodeAttrsUpdated = (payload) => {
+    emitNeatEvent({
+      type: "node-updated",
+      project,
+      payload: { id: payload.key, changes: payload.attributes }
+    });
+  };
+  graph.on("nodeAdded", onNodeAdded);
+  graph.on("nodeDropped", onNodeDropped);
+  graph.on("edgeAdded", onEdgeAdded);
+  graph.on("edgeDropped", onEdgeDropped);
+  graph.on("nodeAttributesUpdated", onNodeAttrsUpdated);
+  return () => {
+    graph.off("nodeAdded", onNodeAdded);
+    graph.off("nodeDropped", onNodeDropped);
+    graph.off("edgeAdded", onEdgeAdded);
+    graph.off("edgeDropped", onEdgeDropped);
+    graph.off("nodeAttributesUpdated", onNodeAttrsUpdated);
+  };
+}
+
 // src/traverse.ts
 init_cjs_shims();
 var import_types = require("@neat.is/types");
@@ -1298,9 +1363,11 @@ async function loadPolicyFile(policyPath) {
 }
 var PolicyViolationsLog = class {
   path;
+  project;
   seen = null;
-  constructor(logPath) {
+  constructor(logPath, project = DEFAULT_PROJECT) {
     this.path = logPath;
+    this.project = project;
   }
   async append(v) {
     if (!this.seen) await this.hydrate();
@@ -1308,6 +1375,11 @@ var PolicyViolationsLog = class {
     this.seen.add(v.id);
     await import_node_fs2.promises.mkdir(import_node_path2.default.dirname(this.path), { recursive: true });
     await import_node_fs2.promises.appendFile(this.path, JSON.stringify(v) + "\n", "utf8");
+    emitNeatEvent({
+      type: "policy-violation",
+      project: this.project,
+      payload: { violation: v }
+    });
     return true;
   }
   async readAll() {
@@ -1777,6 +1849,7 @@ async function markStaleEdges(graph, options = {}) {
   const thresholds = options.thresholds ?? loadStaleThresholdsFromEnv();
   const now = options.now ?? Date.now();
   const events = [];
+  const project = options.project ?? DEFAULT_PROJECT;
   graph.forEachEdge((id, attrs) => {
     const e = attrs;
     if (e.provenance !== import_types3.Provenance.OBSERVED) return;
@@ -1796,6 +1869,15 @@ async function markStaleEdges(graph, options = {}) {
         lastObserved: e.lastObserved,
         transitionedAt: new Date(now).toISOString()
       });
+      emitNeatEvent({
+        type: "stale-transition",
+        project,
+        payload: {
+          edgeId: id,
+          from: import_types3.Provenance.OBSERVED,
+          to: import_types3.Provenance.STALE
+        }
+      });
     }
   });
   if (options.staleEventsPath && events.length > 0) {
@@ -1826,7 +1908,8 @@ function startStalenessLoop(graph, options = {}) {
       try {
         await markStaleEdges(graph, {
           thresholds: options.thresholds,
-          staleEventsPath: options.staleEventsPath
+          staleEventsPath: options.staleEventsPath,
+          project: options.project
         });
         if (options.onPolicyTrigger) await options.onPolicyTrigger(graph);
       } catch (err) {
@@ -3056,7 +3139,15 @@ async function addHttpCallEdges(graph, services) {
     const seenTargets = /* @__PURE__ */ new Map();
     for (const file of files) {
       const parser = import_node_path18.default.extname(file.path) === ".py" ? pyParser : jsParser;
-      const targets = callsFromSource(file.content, parser, knownHosts);
+      let targets;
+      try {
+        targets = callsFromSource(file.content, parser, knownHosts);
+      } catch (err) {
+        console.warn(
+          `[neat] http call extraction skipped ${file.path}: ${err.message}`
+        );
+        continue;
+      }
       for (const t of targets) {
         const targetId = hostToNodeId.get(t);
         if (!targetId || targetId === service.node.id) continue;
@@ -3585,11 +3676,22 @@ async function extractFromDirectory(graph, scanPath, opts = {}) {
   const phase5 = await addInfra(graph, scanPath, services);
   const frontiersPromoted = promoteFrontierNodes(graph);
   if (opts.onPolicyTrigger) await opts.onPolicyTrigger(graph);
-  return {
+  const result = {
     nodesAdded: phase1Nodes + phase2.nodesAdded + phase3.nodesAdded + phase4.nodesAdded + phase5.nodesAdded,
     edgesAdded: phase2.edgesAdded + phase3.edgesAdded + phase4.edgesAdded + phase5.edgesAdded,
     frontiersPromoted
   };
+  emitNeatEvent({
+    type: "extraction-complete",
+    project: opts.project ?? DEFAULT_PROJECT,
+    payload: {
+      project: opts.project ?? DEFAULT_PROJECT,
+      fileCount: services.length,
+      nodesAdded: result.nodesAdded,
+      edgesAdded: result.edgesAdded
+    }
+  });
+  return result;
 }
 
 // src/persist.ts
@@ -3678,14 +3780,14 @@ function startPersistLoop(graph, outPath, intervalMs = 6e4) {
 
 // src/watch.ts
 init_cjs_shims();
-var import_node_path32 = __toESM(require("path"), 1);
+var import_node_path33 = __toESM(require("path"), 1);
 var import_chokidar = __toESM(require("chokidar"), 1);
 
 // src/api.ts
 init_cjs_shims();
 var import_fastify = __toESM(require("fastify"), 1);
 var import_cors = __toESM(require("@fastify/cors"), 1);
-var import_types18 = require("@neat.is/types");
+var import_types19 = require("@neat.is/types");
 
 // src/diff.ts
 init_cjs_shims();
@@ -3816,6 +3918,216 @@ var Projects = class {
   }
 };
 
+// src/registry.ts
+init_cjs_shims();
+var import_node_fs17 = require("fs");
+var import_node_os2 = __toESM(require("os"), 1);
+var import_node_path29 = __toESM(require("path"), 1);
+var import_types18 = require("@neat.is/types");
+var LOCK_TIMEOUT_MS = 5e3;
+var LOCK_RETRY_MS = 50;
+function neatHome() {
+  const override = process.env.NEAT_HOME;
+  if (override && override.length > 0) return import_node_path29.default.resolve(override);
+  return import_node_path29.default.join(import_node_os2.default.homedir(), ".neat");
+}
+function registryPath() {
+  return import_node_path29.default.join(neatHome(), "projects.json");
+}
+function registryLockPath() {
+  return import_node_path29.default.join(neatHome(), "projects.json.lock");
+}
+async function normalizeProjectPath(input) {
+  const resolved = import_node_path29.default.resolve(input);
+  try {
+    return await import_node_fs17.promises.realpath(resolved);
+  } catch {
+    return resolved;
+  }
+}
+async function writeAtomically(target, contents) {
+  await import_node_fs17.promises.mkdir(import_node_path29.default.dirname(target), { recursive: true });
+  const tmp = `${target}.${process.pid}.${Date.now()}.${Math.random().toString(36).slice(2, 8)}.tmp`;
+  const fd = await import_node_fs17.promises.open(tmp, "w");
+  try {
+    await fd.writeFile(contents, "utf8");
+    await fd.sync();
+  } finally {
+    await fd.close();
+  }
+  await import_node_fs17.promises.rename(tmp, target);
+}
+async function acquireLock(lockPath, timeoutMs = LOCK_TIMEOUT_MS) {
+  const deadline = Date.now() + timeoutMs;
+  await import_node_fs17.promises.mkdir(import_node_path29.default.dirname(lockPath), { recursive: true });
+  while (true) {
+    try {
+      const fd = await import_node_fs17.promises.open(lockPath, "wx");
+      await fd.close();
+      return;
+    } catch (err) {
+      const code = err.code;
+      if (code !== "EEXIST") throw err;
+      if (Date.now() >= deadline) {
+        throw new Error(
+          `neat registry: timed out after ${timeoutMs}ms waiting for ${lockPath}. Another neat process is holding the lock; if no such process exists, remove the file by hand.`
+        );
+      }
+      await new Promise((r) => setTimeout(r, LOCK_RETRY_MS));
+    }
+  }
+}
+async function releaseLock(lockPath) {
+  await import_node_fs17.promises.unlink(lockPath).catch(() => {
+  });
+}
+async function withLock(fn) {
+  const lock = registryLockPath();
+  await acquireLock(lock);
+  try {
+    return await fn();
+  } finally {
+    await releaseLock(lock);
+  }
+}
+async function readRegistry() {
+  const file = registryPath();
+  let raw;
+  try {
+    raw = await import_node_fs17.promises.readFile(file, "utf8");
+  } catch (err) {
+    if (err.code === "ENOENT") {
+      return { version: 1, projects: [] };
+    }
+    throw err;
+  }
+  const parsed = JSON.parse(raw);
+  return import_types18.RegistryFileSchema.parse(parsed);
+}
+async function writeRegistry(reg) {
+  const validated = import_types18.RegistryFileSchema.parse(reg);
+  await writeAtomically(registryPath(), JSON.stringify(validated, null, 2) + "\n");
+}
+var ProjectNameCollisionError = class extends Error {
+  projectName;
+  constructor(name) {
+    super(`neat registry: a project named "${name}" is already registered`);
+    this.name = "ProjectNameCollisionError";
+    this.projectName = name;
+  }
+};
+async function addProject(opts) {
+  const resolvedPath = await normalizeProjectPath(opts.path);
+  return withLock(async () => {
+    const reg = await readRegistry();
+    const byName = reg.projects.find((p) => p.name === opts.name);
+    const byPath = reg.projects.find((p) => p.path === resolvedPath);
+    if (byName && byName.path !== resolvedPath) {
+      throw new ProjectNameCollisionError(opts.name);
+    }
+    const now = (/* @__PURE__ */ new Date()).toISOString();
+    if (byName && byName.path === resolvedPath) {
+      byName.lastSeenAt = now;
+      if (opts.languages) byName.languages = opts.languages;
+      if (opts.status) byName.status = opts.status;
+      await writeRegistry(reg);
+      return byName;
+    }
+    if (byPath && byPath.name !== opts.name) {
+      throw new ProjectNameCollisionError(byPath.name);
+    }
+    const entry2 = {
+      name: opts.name,
+      path: resolvedPath,
+      registeredAt: now,
+      languages: opts.languages ?? [],
+      status: opts.status ?? "active"
+    };
+    reg.projects.push(entry2);
+    await writeRegistry(reg);
+    return entry2;
+  });
+}
+async function listProjects() {
+  const reg = await readRegistry();
+  return reg.projects;
+}
+async function setStatus(name, status2) {
+  return withLock(async () => {
+    const reg = await readRegistry();
+    const entry2 = reg.projects.find((p) => p.name === name);
+    if (!entry2) throw new Error(`neat registry: no project named "${name}"`);
+    entry2.status = status2;
+    await writeRegistry(reg);
+    return entry2;
+  });
+}
+async function removeProject(name) {
+  return withLock(async () => {
+    const reg = await readRegistry();
+    const idx = reg.projects.findIndex((p) => p.name === name);
+    if (idx < 0) return void 0;
+    const [removed] = reg.projects.splice(idx, 1);
+    await writeRegistry(reg);
+    return removed;
+  });
+}
+
+// src/streaming.ts
+init_cjs_shims();
+var SSE_HEARTBEAT_MS = 3e4;
+var SSE_BACKPRESSURE_CAP = 1e3;
+function handleSse(req, reply, opts) {
+  const heartbeatMs = opts.heartbeatMs ?? SSE_HEARTBEAT_MS;
+  const backpressureCap = opts.backpressureCap ?? SSE_BACKPRESSURE_CAP;
+  reply.raw.setHeader("Content-Type", "text/event-stream");
+  reply.raw.setHeader("Cache-Control", "no-cache, no-transform");
+  reply.raw.setHeader("Connection", "keep-alive");
+  reply.raw.setHeader("X-Accel-Buffering", "no");
+  reply.raw.flushHeaders?.();
+  let pending = 0;
+  let dropped = false;
+  const closeConnection = () => {
+    if (dropped) return;
+    dropped = true;
+    eventBus.off(EVENT_BUS_CHANNEL, listener);
+    clearInterval(heartbeat);
+    if (!reply.raw.writableEnded) reply.raw.end();
+  };
+  const writeFrame = (frame) => {
+    if (dropped) return;
+    if (pending >= backpressureCap) {
+      const errFrame = `event: error
+data: ${JSON.stringify({ reason: "backpressure" })}
+
+`;
+      reply.raw.write(errFrame);
+      closeConnection();
+      return;
+    }
+    pending++;
+    reply.raw.write(frame, () => {
+      pending = Math.max(0, pending - 1);
+    });
+  };
+  const listener = (envelope) => {
+    if (envelope.project !== opts.project) return;
+    writeFrame(`event: ${envelope.type}
+data: ${JSON.stringify(envelope.payload)}
+
+`);
+  };
+  eventBus.on(EVENT_BUS_CHANNEL, listener);
+  const heartbeat = setInterval(() => {
+    if (dropped) return;
+    reply.raw.write(":heartbeat\n\n");
+  }, heartbeatMs);
+  if (typeof heartbeat.unref === "function") heartbeat.unref();
+  req.raw.on("close", closeConnection);
+  reply.raw.on("close", closeConnection);
+  reply.raw.on("error", closeConnection);
+}
+
 // src/api.ts
 function serializeGraph(graph) {
   const nodes = [];
@@ -3864,6 +4176,11 @@ function buildLegacyRegistry(opts) {
 }
 function registerRoutes(scope, ctx) {
   const { registry, startedAt, errorsPathFor, staleEventsPathFor } = ctx;
+  scope.get("/events", (req, reply) => {
+    const proj = resolveProject(registry, req, reply);
+    if (!proj) return;
+    handleSse(req, reply, { project: proj.name });
+  });
   scope.get("/health", async (req, reply) => {
     const proj = resolveProject(registry, req, reply);
     if (!proj) return;
@@ -4074,7 +4391,7 @@ function registerRoutes(scope, ctx) {
     const log = new PolicyViolationsLog(proj.paths.policyViolationsPath);
     let violations = await log.readAll();
     if (req.query.severity) {
-      const sev = import_types18.PolicySeveritySchema.safeParse(req.query.severity);
+      const sev = import_types19.PolicySeveritySchema.safeParse(req.query.severity);
       if (!sev.success) {
         return reply.code(400).send({
           error: "invalid severity",
@@ -4091,7 +4408,7 @@ function registerRoutes(scope, ctx) {
   scope.post("/policies/check", async (req, reply) => {
     const proj = resolveProject(registry, req, reply);
     if (!proj) return;
-    const parsed = import_types18.PoliciesCheckBodySchema.safeParse(req.body ?? {});
+    const parsed = import_types19.PoliciesCheckBodySchema.safeParse(req.body ?? {});
     if (!parsed.success) {
       return reply.code(400).send({
         error: "invalid /policies/check body",
@@ -4155,17 +4472,16 @@ async function buildApi(opts) {
     staleEventsPathFor,
     policyFilePathFor
   };
-  app.get("/projects", async () => ({
-    projects: registry.list().map((name) => {
-      const proj = registry.get(name);
-      return {
-        name,
-        nodeCount: proj.graph.order,
-        edgeCount: proj.graph.size,
-        scanPath: proj.scanPath
-      };
-    })
-  }));
+  app.get("/projects", async (_req, reply) => {
+    try {
+      return await listProjects();
+    } catch (err) {
+      return reply.code(500).send({
+        error: "failed to read project registry",
+        details: err.message
+      });
+    }
+  });
   registerRoutes(app, routeCtx);
   await app.register(
     async (scope) => {
@@ -4178,13 +4494,13 @@ async function buildApi(opts) {
 
 // src/extract/retire.ts
 init_cjs_shims();
-var import_types19 = require("@neat.is/types");
+var import_types20 = require("@neat.is/types");
 function retireEdgesByFile(graph, file) {
   const normalized = file.split("\\").join("/");
   const toDrop = [];
   graph.forEachEdge((id, attrs) => {
     const edge = attrs;
-    if (edge.provenance !== import_types19.Provenance.EXTRACTED) return;
+    if (edge.provenance !== import_types20.Provenance.EXTRACTED) return;
     if (!edge.evidence?.file) return;
     if (edge.evidence.file === normalized) toDrop.push(id);
   });
@@ -4198,8 +4514,8 @@ init_otel_grpc();
 
 // src/search.ts
 init_cjs_shims();
-var import_node_fs17 = require("fs");
-var import_node_path31 = __toESM(require("path"), 1);
+var import_node_fs18 = require("fs");
+var import_node_path32 = __toESM(require("path"), 1);
 var import_node_crypto = require("crypto");
 var DEFAULT_LIMIT = 10;
 var NOMIC_DIM = 768;
@@ -4329,7 +4645,7 @@ async function pickEmbedder() {
 }
 async function readCache(cachePath) {
   try {
-    const raw = await import_node_fs17.promises.readFile(cachePath, "utf8");
+    const raw = await import_node_fs18.promises.readFile(cachePath, "utf8");
     const parsed = JSON.parse(raw);
     if (parsed.version !== 1) return null;
     return parsed;
@@ -4338,8 +4654,8 @@ async function readCache(cachePath) {
   }
 }
 async function writeCache(cachePath, cache) {
-  await import_node_fs17.promises.mkdir(import_node_path31.default.dirname(cachePath), { recursive: true });
-  await import_node_fs17.promises.writeFile(cachePath, JSON.stringify(cache));
+  await import_node_fs18.promises.mkdir(import_node_path32.default.dirname(cachePath), { recursive: true });
+  await import_node_fs18.promises.writeFile(cachePath, JSON.stringify(cache));
 }
 var VectorIndex = class {
   constructor(embedder, cachePath) {
@@ -4494,8 +4810,8 @@ var ALL_PHASES = [
 ];
 function classifyChange(relPath) {
   const phases = /* @__PURE__ */ new Set();
-  const base = import_node_path32.default.basename(relPath).toLowerCase();
-  const segments = relPath.split(import_node_path32.default.sep).map((s) => s.toLowerCase());
+  const base = import_node_path33.default.basename(relPath).toLowerCase();
+  const segments = relPath.split(import_node_path33.default.sep).map((s) => s.toLowerCase());
   if (base === "package.json" || base === "requirements.txt" || base === "pyproject.toml" || base === "setup.py") {
     phases.add("services");
     phases.add("aliases");
@@ -4518,7 +4834,8 @@ function classifyChange(relPath) {
   }
   return phases;
 }
-async function runExtractPhases(graph, scanPath, phases) {
+async function runExtractPhases(graph, scanPath, phases, project = DEFAULT_PROJECT) {
+  void project;
   const started = Date.now();
   await ensureCompatLoaded();
   const services = await discoverServices(scanPath);
@@ -4574,9 +4891,11 @@ function shouldIgnore(absPath) {
 }
 async function startWatch(graph, opts) {
   const debounceMs = opts.debounceMs ?? 1e3;
+  const projectName = opts.project ?? DEFAULT_PROJECT;
   await loadGraphFromDisk(graph, opts.outPath);
-  const policyFilePath = import_node_path32.default.join(opts.scanPath, "policy.json");
-  const policyViolationsPath = import_node_path32.default.join(import_node_path32.default.dirname(opts.outPath), "policy-violations.ndjson");
+  const detachEventBus = attachGraphToEventBus(graph, { project: projectName });
+  const policyFilePath = import_node_path33.default.join(opts.scanPath, "policy.json");
+  const policyViolationsPath = import_node_path33.default.join(import_node_path33.default.dirname(opts.outPath), "policy-violations.ndjson");
   let policies = [];
   try {
     policies = await loadPolicyFile(policyFilePath);
@@ -4586,7 +4905,7 @@ async function startWatch(graph, opts) {
   } catch (err) {
     console.warn(`policies: failed to load ${policyFilePath} \u2014 ${err.message}`);
   }
-  const policyLog = new PolicyViolationsLog(policyViolationsPath);
+  const policyLog = new PolicyViolationsLog(policyViolationsPath, projectName);
   const onPolicyTrigger = async (g) => {
     if (policies.length === 0) return;
     try {
@@ -4596,20 +4915,36 @@ async function startWatch(graph, opts) {
       console.warn(`policies: evaluation failed \u2014 ${err.message}`);
     }
   };
-  const initial = await runExtractPhases(graph, opts.scanPath, new Set(ALL_PHASES));
+  const initial = await runExtractPhases(
+    graph,
+    opts.scanPath,
+    new Set(ALL_PHASES),
+    projectName
+  );
   console.log(
     `extract: ${initial.nodesAdded} new nodes, ${initial.edgesAdded} new edges (graph total ${graph.order}/${graph.size})`
   );
+  emitNeatEvent({
+    type: "extraction-complete",
+    project: projectName,
+    payload: {
+      project: projectName,
+      fileCount: 0,
+      nodesAdded: initial.nodesAdded,
+      edgesAdded: initial.edgesAdded
+    }
+  });
   await onPolicyTrigger(graph);
   const stopPersist = startPersistLoop(graph, opts.outPath);
   const stopStaleness = startStalenessLoop(graph, {
     staleEventsPath: opts.staleEventsPath,
+    project: projectName,
     onPolicyTrigger
   });
   const host = opts.host ?? "0.0.0.0";
   const port = opts.port ?? 8080;
   const otelPort = opts.otelPort ?? 4318;
-  const cachePath = opts.embeddingsCachePath ?? import_node_path32.default.join(import_node_path32.default.dirname(opts.outPath), "embeddings.json");
+  const cachePath = opts.embeddingsCachePath ?? import_node_path33.default.join(import_node_path33.default.dirname(opts.outPath), "embeddings.json");
   let searchIndex;
   try {
     searchIndex = await buildSearchIndex(graph, { cachePath });
@@ -4619,7 +4954,6 @@ async function startWatch(graph, opts) {
       `semantic_search: index build failed (${err.message}); falling back to inline substring`
     );
   }
-  const projectName = opts.project ?? DEFAULT_PROJECT;
   const registry = new Projects();
   registry.set(projectName, {
     graph,
@@ -4628,7 +4962,7 @@ async function startWatch(graph, opts) {
       // Paths are derived from the explicit options the watch caller passes
       // — pathsForProject is only used to fill in the embeddings/snapshot
       // fields so the registry shape is complete.
-      ...pathsForProject(projectName, import_node_path32.default.dirname(opts.outPath)),
+      ...pathsForProject(projectName, import_node_path33.default.dirname(opts.outPath)),
       snapshotPath: opts.outPath,
       errorsPath: opts.errorsPath,
       staleEventsPath: opts.staleEventsPath
@@ -4644,6 +4978,7 @@ async function startWatch(graph, opts) {
   const onSpan = makeSpanHandler({
     graph,
     errorsPath: opts.errorsPath,
+    project: projectName,
     writeErrorEventInline: false,
     onPolicyTrigger
   });
@@ -4657,6 +4992,7 @@ async function startWatch(graph, opts) {
     const onSpanGrpc = makeSpanHandler({
       graph,
       errorsPath: opts.errorsPath,
+      project: projectName,
       onPolicyTrigger
     });
     const r = await startOtelGrpcReceiver({ onSpan: onSpanGrpc, host, port: grpcPort });
@@ -4676,10 +5012,20 @@ async function startWatch(graph, opts) {
     try {
       let retired = 0;
       for (const p of paths) retired += retireEdgesByFile(graph, p);
-      const result = await runExtractPhases(graph, opts.scanPath, phases);
+      const result = await runExtractPhases(graph, opts.scanPath, phases, projectName);
       console.log(
         `[watch] re-extract phases=${result.phases.join(",")} retired=${retired} +${result.nodesAdded}n/+${result.edgesAdded}e in ${result.durationMs}ms`
       );
+      emitNeatEvent({
+        type: "extraction-complete",
+        project: projectName,
+        payload: {
+          project: projectName,
+          fileCount: paths.size,
+          nodesAdded: result.nodesAdded,
+          edgesAdded: result.edgesAdded
+        }
+      });
       if (searchIndex) {
         try {
           await searchIndex.refresh(graph);
@@ -4701,9 +5047,9 @@ async function startWatch(graph, opts) {
   };
   const onPath = (absPath) => {
     if (shouldIgnore(absPath)) return;
-    const rel = import_node_path32.default.relative(opts.scanPath, absPath);
+    const rel = import_node_path33.default.relative(opts.scanPath, absPath);
     if (!rel || rel.startsWith("..")) return;
-    pendingPaths.add(rel.split(import_node_path32.default.sep).join("/"));
+    pendingPaths.add(rel.split(import_node_path33.default.sep).join("/"));
     const phases = classifyChange(rel);
     if (phases.size === 0) {
       for (const p of ALL_PHASES) pending.add(p);
@@ -4738,6 +5084,7 @@ async function startWatch(graph, opts) {
     await watcher.close();
     stopStaleness();
     stopPersist();
+    detachEventBus();
     await api.close();
     await otelHttp.close();
     if (grpcReceiver) await grpcReceiver.stop();
@@ -4745,182 +5092,27 @@ async function startWatch(graph, opts) {
   return { api, stop };
 }
 
-// src/registry.ts
+// src/installers/index.ts
 init_cjs_shims();
-var import_node_fs18 = require("fs");
-var import_node_os2 = __toESM(require("os"), 1);
-var import_node_path33 = __toESM(require("path"), 1);
-var import_types20 = require("@neat.is/types");
-var LOCK_TIMEOUT_MS = 5e3;
-var LOCK_RETRY_MS = 50;
-function neatHome() {
-  const override = process.env.NEAT_HOME;
-  if (override && override.length > 0) return import_node_path33.default.resolve(override);
-  return import_node_path33.default.join(import_node_os2.default.homedir(), ".neat");
-}
-function registryPath() {
-  return import_node_path33.default.join(neatHome(), "projects.json");
-}
-function registryLockPath() {
-  return import_node_path33.default.join(neatHome(), "projects.json.lock");
-}
-async function normalizeProjectPath(input) {
-  const resolved = import_node_path33.default.resolve(input);
-  try {
-    return await import_node_fs18.promises.realpath(resolved);
-  } catch {
-    return resolved;
-  }
-}
-async function writeAtomically(target, contents) {
-  await import_node_fs18.promises.mkdir(import_node_path33.default.dirname(target), { recursive: true });
-  const tmp = `${target}.${process.pid}.${Date.now()}.${Math.random().toString(36).slice(2, 8)}.tmp`;
-  const fd = await import_node_fs18.promises.open(tmp, "w");
-  try {
-    await fd.writeFile(contents, "utf8");
-    await fd.sync();
-  } finally {
-    await fd.close();
-  }
-  await import_node_fs18.promises.rename(tmp, target);
-}
-async function acquireLock(lockPath, timeoutMs = LOCK_TIMEOUT_MS) {
-  const deadline = Date.now() + timeoutMs;
-  await import_node_fs18.promises.mkdir(import_node_path33.default.dirname(lockPath), { recursive: true });
-  while (true) {
-    try {
-      const fd = await import_node_fs18.promises.open(lockPath, "wx");
-      await fd.close();
-      return;
-    } catch (err) {
-      const code = err.code;
-      if (code !== "EEXIST") throw err;
-      if (Date.now() >= deadline) {
-        throw new Error(
-          `neat registry: timed out after ${timeoutMs}ms waiting for ${lockPath}. Another neat process is holding the lock; if no such process exists, remove the file by hand.`
-        );
-      }
-      await new Promise((r) => setTimeout(r, LOCK_RETRY_MS));
-    }
-  }
-}
-async function releaseLock(lockPath) {
-  await import_node_fs18.promises.unlink(lockPath).catch(() => {
-  });
-}
-async function withLock(fn) {
-  const lock = registryLockPath();
-  await acquireLock(lock);
-  try {
-    return await fn();
-  } finally {
-    await releaseLock(lock);
-  }
-}
-async function readRegistry() {
-  const file = registryPath();
-  let raw;
-  try {
-    raw = await import_node_fs18.promises.readFile(file, "utf8");
-  } catch (err) {
-    if (err.code === "ENOENT") {
-      return { version: 1, projects: [] };
-    }
-    throw err;
-  }
-  const parsed = JSON.parse(raw);
-  return import_types20.RegistryFileSchema.parse(parsed);
-}
-async function writeRegistry(reg) {
-  const validated = import_types20.RegistryFileSchema.parse(reg);
-  await writeAtomically(registryPath(), JSON.stringify(validated, null, 2) + "\n");
-}
-var ProjectNameCollisionError = class extends Error {
-  projectName;
-  constructor(name) {
-    super(`neat registry: a project named "${name}" is already registered`);
-    this.name = "ProjectNameCollisionError";
-    this.projectName = name;
-  }
-};
-async function addProject(opts) {
-  const resolvedPath = await normalizeProjectPath(opts.path);
-  return withLock(async () => {
-    const reg = await readRegistry();
-    const byName = reg.projects.find((p) => p.name === opts.name);
-    const byPath = reg.projects.find((p) => p.path === resolvedPath);
-    if (byName && byName.path !== resolvedPath) {
-      throw new ProjectNameCollisionError(opts.name);
-    }
-    const now = (/* @__PURE__ */ new Date()).toISOString();
-    if (byName && byName.path === resolvedPath) {
-      byName.lastSeenAt = now;
-      if (opts.languages) byName.languages = opts.languages;
-      if (opts.status) byName.status = opts.status;
-      await writeRegistry(reg);
-      return byName;
-    }
-    if (byPath && byPath.name !== opts.name) {
-      throw new ProjectNameCollisionError(byPath.name);
-    }
-    const entry2 = {
-      name: opts.name,
-      path: resolvedPath,
-      registeredAt: now,
-      languages: opts.languages ?? [],
-      status: opts.status ?? "active"
-    };
-    reg.projects.push(entry2);
-    await writeRegistry(reg);
-    return entry2;
-  });
-}
-async function listProjects() {
-  const reg = await readRegistry();
-  return reg.projects;
-}
-async function setStatus(name, status2) {
-  return withLock(async () => {
-    const reg = await readRegistry();
-    const entry2 = reg.projects.find((p) => p.name === name);
-    if (!entry2) throw new Error(`neat registry: no project named "${name}"`);
-    entry2.status = status2;
-    await writeRegistry(reg);
-    return entry2;
-  });
-}
-async function removeProject(name) {
-  return withLock(async () => {
-    const reg = await readRegistry();
-    const idx = reg.projects.findIndex((p) => p.name === name);
-    if (idx < 0) return void 0;
-    const [removed] = reg.projects.splice(idx, 1);
-    await writeRegistry(reg);
-    return removed;
-  });
-}
-
-// src/installers/index.ts
-init_cjs_shims();
-
-// src/installers/javascript.ts
-init_cjs_shims();
-var import_node_fs19 = require("fs");
-var import_node_path34 = __toESM(require("path"), 1);
-var SDK_PACKAGES = [
-  { name: "@opentelemetry/api", version: "^1.9.0" },
-  { name: "@opentelemetry/sdk-node", version: "^0.57.0" },
-  { name: "@opentelemetry/auto-instrumentations-node", version: "^0.55.0" }
-];
-var AUTO_INSTRUMENT_REQUIRE = "--require @opentelemetry/auto-instrumentations-node/register";
-var OTEL_ENV = {
-  // null target — NEAT does not write `.env` itself; the user sets the env
-  // var in their orchestration layer.
-  file: null,
-  key: "OTEL_EXPORTER_OTLP_ENDPOINT",
-  value: "http://localhost:4318"
-};
-async function readPackageJson(serviceDir) {
+
+// src/installers/javascript.ts
+init_cjs_shims();
+var import_node_fs19 = require("fs");
+var import_node_path34 = __toESM(require("path"), 1);
+var SDK_PACKAGES = [
+  { name: "@opentelemetry/api", version: "^1.9.0" },
+  { name: "@opentelemetry/sdk-node", version: "^0.57.0" },
+  { name: "@opentelemetry/auto-instrumentations-node", version: "^0.55.0" }
+];
+var AUTO_INSTRUMENT_REQUIRE = "--require @opentelemetry/auto-instrumentations-node/register";
+var OTEL_ENV = {
+  // null target — NEAT does not write `.env` itself; the user sets the env
+  // var in their orchestration layer.
+  file: null,
+  key: "OTEL_EXPORTER_OTLP_ENDPOINT",
+  value: "http://localhost:4318"
+};
+async function readPackageJson(serviceDir) {
   try {
     const raw = await import_node_fs19.promises.readFile(import_node_path34.default.join(serviceDir, "package.json"), "utf8");
     return JSON.parse(raw);
@@ -5300,11 +5492,457 @@ function renderPatch(sections) {
   return lines.join("\n");
 }
 
+// src/cli-client.ts
+init_cjs_shims();
+var import_types21 = require("@neat.is/types");
+var HttpError = class extends Error {
+  constructor(status2, message, responseBody = "") {
+    super(message);
+    this.status = status2;
+    this.responseBody = responseBody;
+    this.name = "HttpError";
+  }
+  status;
+  responseBody;
+};
+var TransportError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "TransportError";
+  }
+};
+function createHttpClient(baseUrl) {
+  const root = baseUrl.replace(/\/$/, "");
+  return {
+    async get(path37) {
+      let res;
+      try {
+        res = await fetch(`${root}${path37}`);
+      } 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 ${path37}: ${body}`,
+          body
+        );
+      }
+      return await res.json();
+    },
+    async post(path37, body) {
+      let res;
+      try {
+        res = await fetch(`${root}${path37}`, {
+          method: "POST",
+          headers: { "content-type": "application/json" },
+          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 ${path37}: ${text}`,
+          text
+        );
+      }
+      return await res.json();
+    }
+  };
+}
+function projectPath(project, suffix) {
+  if (!project) return suffix;
+  return `/projects/${encodeURIComponent(project)}${suffix}`;
+}
+async function runRootCause(client, input) {
+  const qs = input.errorId ? `?errorId=${encodeURIComponent(input.errorId)}` : "";
+  const path37 = projectPath(
+    input.project,
+    `/traverse/root-cause/${encodeURIComponent(input.errorNode)}${qs}`
+  );
+  try {
+    const result = await client.get(path37);
+    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
+    };
+  } 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.`
+      };
+    }
+    throw err;
+  }
+}
+async function runBlastRadius(client, input) {
+  const qs = input.depth !== void 0 ? `?depth=${input.depth}` : "";
+  const path37 = projectPath(
+    input.project,
+    `/traverse/blast-radius/${encodeURIComponent(input.nodeId)}${qs}`
+  );
+  try {
+    const result = await client.get(path37);
+    if (result.totalAffected === 0) {
+      return {
+        summary: `${result.origin} has no downstream dependencies. 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} affected node${result.totalAffected === 1 ? "" : "s"} reachable downstream.`,
+      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;
+  }
+}
+function formatBlastEntry(n) {
+  const tag = n.edgeProvenance === import_types21.Provenance.STALE ? " [STALE \u2014 last seen too long ago]" : "";
+  return `  \u2022 ${n.nodeId} (distance ${n.distance}, ${n.edgeProvenance})${tag}`;
+}
+async function runDependencies(client, input) {
+  const depth = input.depth ?? 3;
+  const path37 = projectPath(
+    input.project,
+    `/graph/node/${encodeURIComponent(input.nodeId)}/dependencies?depth=${depth}`
+  );
+  try {
+    const result = await client.get(path37);
+    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) {
+    if (err instanceof HttpError && err.status === 404) {
+      return { summary: `Node ${input.nodeId} not found in the graph.` };
+    }
+    throw err;
+  }
+}
+async function runObservedDependencies(client, input) {
+  try {
+    const edges = await client.get(
+      projectPath(input.project, `/graph/edges/${encodeURIComponent(input.nodeId)}`)
+    );
+    const observed = edges.outbound.filter((e) => e.provenance === import_types21.Provenance.OBSERVED);
+    if (observed.length === 0) {
+      const hasExtracted = edges.outbound.some((e) => e.provenance === import_types21.Provenance.EXTRACTED);
+      const note = hasExtracted ? " 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 = observed.map((e) => `  \u2022 ${e.target} \u2014 ${e.type}${edgeMeta(e)}`);
+    return {
+      summary: `${input.nodeId} has ${observed.length} runtime dependenc${observed.length === 1 ? "y" : "ies"} confirmed by OTel.`,
+      block: blockLines.join("\n"),
+      provenance: import_types21.Provenance.OBSERVED
+    };
+  } catch (err) {
+    if (err instanceof HttpError && err.status === 404) {
+      return { summary: `Node ${input.nodeId} not found in the graph.` };
+    }
+    throw err;
+  }
+}
+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 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 runIncidents(client, input) {
+  const path37 = input.nodeId ? projectPath(input.project, `/incidents/${encodeURIComponent(input.nodeId)}`) : projectPath(input.project, "/incidents");
+  try {
+    const events = await client.get(path37);
+    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 ${events.length} recorded incident${events.length === 1 ? "" : "s"}; showing the ${ordered.length} most recent.`,
+      block: blockLines.join("\n"),
+      provenance: import_types21.Provenance.OBSERVED
+    };
+  } catch (err) {
+    if (err instanceof HttpError && err.status === 404) {
+      return { summary: `Node ${input.nodeId ?? ""} not found in the graph.` };
+    }
+    throw err;
+  }
+}
+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}".` };
+  }
+  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}`
+    );
+  }
+  return {
+    summary: `Found ${result.matches.length} match${result.matches.length === 1 ? "" : "es"} for "${input.query}" via ${provider} provider.`,
+    block: blockLines.join("\n"),
+    confidence: topScore
+  };
+}
+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}).`
+    };
+  }
+  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("");
+  }
+  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("");
+  }
+  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 {
+    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);
+  }
+  return changed.length === 0 ? "attributes differ" : `fields changed: ${changed.sort().join(", ")}`;
+}
+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 events = await client.get(
+    projectPath(input.project, `/incidents/stale${qs}`)
+  );
+  if (events.length === 0) {
+    return {
+      summary: input.edgeType ? `No stale ${input.edgeType} edges recorded.` : "No stale-edge transitions recorded yet."
+    };
+  }
+  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: import_types21.Provenance.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");
+    }
+    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()}` : "";
+    violations = await client.get(
+      projectPath(input.project, `/policies/violations${qs}`)
+    );
+    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)
+    );
+  }
+  if (violations.length === 0) {
+    return {
+      summary: hypothetical ? `No violations would result from the hypothetical action (${hypothetical.kind}).` : "No policy violations recorded."
+    };
+  }
+  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 {
+    summaryParts.push(
+      `${violations.length} policy violation${violations.length === 1 ? "" : "s"} currently recorded`
+    );
+  }
+  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(" ")
+  };
+}
+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 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 formatJson(result) {
+  return JSON.stringify(
+    {
+      summary: result.summary,
+      block: result.block ?? "",
+      confidence: result.confidence ?? null,
+      provenance: result.provenance ?? null
+    },
+    null,
+    2
+  );
+}
+function exitCodeForError(err) {
+  if (err instanceof TransportError) return 3;
+  if (err instanceof HttpError) return 1;
+  return 1;
+}
+
 // src/cli.ts
 function usage() {
   console.log("usage: neat <command> [args] [--project <name>]");
   console.log("");
-  console.log("commands:");
+  console.log("lifecycle commands:");
   console.log("  init <path>    One-time install: discover, extract, register, plan SDK install.");
   console.log("                 Snapshot lands in <path>/neat-out/graph.json by default");
   console.log("                 (or <path>/neat-out/<project>.json for non-default).");
@@ -5326,51 +5964,133 @@ function usage() {
   console.log("                   --print-config   print the JSON snippet to stdout");
   console.log("                   --apply          merge mcpServers.neat into ~/.claude.json");
   console.log("");
+  console.log("query commands (mirror the MCP tools, ADR-050):");
+  console.log("  root-cause <node-id>             Walk inbound edges to find what broke first.");
+  console.log("                                   example: neat root-cause service:<name>");
+  console.log("  blast-radius <node-id>           BFS outbound \u2014 what would break if this dies.");
+  console.log("                                   example: neat blast-radius database:<host>");
+  console.log("  dependencies <node-id>           Transitive outbound dependencies.");
+  console.log("                                   Flags: --depth N (default 3, max 10)");
+  console.log("                                   example: neat dependencies service:<name> --depth 2");
+  console.log("  observed-dependencies <node-id>  OBSERVED-only outbound edges (runtime traffic).");
+  console.log("                                   example: neat observed-dependencies service:<name>");
+  console.log("  incidents [<node-id>]            Recent error events; per-node when an id is given.");
+  console.log("                                   Flags: --limit N (default 20)");
+  console.log("                                   example: neat incidents service:<name> --limit 5");
+  console.log("  search <query>                   Semantic (or substring) match on node names/ids.");
+  console.log('                                   example: neat search "checkout"');
+  console.log("  diff --against <snapshot>        Compare the live graph to a saved snapshot.");
+  console.log("                                   example: neat diff --against ./snapshots/baseline.json");
+  console.log("  stale-edges                      Recent OBSERVED \u2192 STALE transitions.");
+  console.log("                                   Flags: --limit N, --edge-type CALLS|CONNECTS_TO|...");
+  console.log("                                   example: neat stale-edges --edge-type CALLS");
+  console.log("  policies                         Current policy violations.");
+  console.log("                                   Flags: --node <id>, --hypothetical-action <json>");
+  console.log("                                   example: neat policies --node service:<name> --json");
+  console.log("");
   console.log("flags:");
   console.log('  --project <name>   Name the project this command targets. Default: "default".');
-}
+  console.log("  --json             Emit machine-readable JSON instead of human text. Query verbs only.");
+  console.log("");
+  console.log("exit codes:");
+  console.log("  0  success");
+  console.log("  1  server error (4xx/5xx body printed to stderr)");
+  console.log("  2  misuse (missing args, bad flags) \u2014 handled before any network call");
+  console.log("  3  daemon not reachable (connection refused / timeout)");
+  console.log("");
+  console.log("environment:");
+  console.log("  NEAT_API_URL    base URL for the core REST API (default http://localhost:8080)");
+  console.log("  NEAT_PROJECT    project name when --project isn't passed");
+}
+var STRING_FLAGS = [
+  ["--project", "project"],
+  ["--depth", "depth"],
+  ["--limit", "limit"],
+  ["--edge-type", "edgeType"],
+  ["--node", "node"],
+  ["--since", "since"],
+  ["--against", "against"],
+  ["--error-id", "errorId"],
+  ["--hypothetical-action", "hypotheticalAction"]
+];
 function parseArgs(rest) {
   const positional = [];
-  let project = null;
-  let apply3 = false;
-  let dryRun = false;
-  let noInstall = false;
-  let printConfig = false;
+  const out = {
+    project: null,
+    apply: false,
+    dryRun: false,
+    noInstall: false,
+    printConfig: false,
+    json: false,
+    depth: null,
+    limit: null,
+    edgeType: null,
+    node: null,
+    since: null,
+    against: null,
+    errorId: null,
+    hypotheticalAction: null,
+    positional: []
+  };
   for (let i = 0; i < rest.length; i++) {
     const arg = rest[i];
-    if (arg === "--project") {
-      const next = rest[i + 1];
-      if (!next) {
-        console.error("neat: --project requires a value");
-        process.exit(2);
-      }
-      project = next;
-      i++;
-      continue;
-    }
-    if (arg.startsWith("--project=")) {
-      project = arg.slice("--project=".length);
-      continue;
-    }
     if (arg === "--apply") {
-      apply3 = true;
+      out.apply = true;
       continue;
     }
     if (arg === "--dry-run") {
-      dryRun = true;
+      out.dryRun = true;
       continue;
     }
     if (arg === "--no-install") {
-      noInstall = true;
+      out.noInstall = true;
       continue;
     }
     if (arg === "--print-config") {
-      printConfig = true;
+      out.printConfig = true;
+      continue;
+    }
+    if (arg === "--json") {
+      out.json = true;
       continue;
     }
+    let matched = false;
+    for (const [flag, field] of STRING_FLAGS) {
+      if (arg === flag) {
+        const next = rest[i + 1];
+        if (next === void 0) {
+          console.error(`neat: ${flag} requires a value`);
+          process.exit(2);
+        }
+        assignFlag(out, field, next);
+        i++;
+        matched = true;
+        break;
+      }
+      if (arg.startsWith(`${flag}=`)) {
+        assignFlag(out, field, arg.slice(flag.length + 1));
+        matched = true;
+        break;
+      }
+    }
+    if (matched) continue;
     positional.push(arg);
   }
-  return { project, apply: apply3, dryRun, noInstall, printConfig, positional };
+  out.positional = positional;
+  return out;
+}
+function assignFlag(out, field, value) {
+  if (field === "depth" || field === "limit") {
+    const n = Number(value);
+    if (!Number.isFinite(n) || !Number.isInteger(n) || n < 1) {
+      console.error(`neat: --${field === "depth" ? "depth" : "limit"} must be a positive integer`);
+      process.exit(2);
+    }
+    out[field] = n;
+    return;
+  }
+  ;
+  out[field] = value;
 }
 function summarise(nodes, edges) {
   const byNode = /* @__PURE__ */ new Map();
@@ -5734,10 +6454,167 @@ async function main() {
     console.log("note: neat-out/, policy.json, and other files at the project path were left in place.");
     return;
   }
+  if (QUERY_VERBS.has(cmd)) {
+    const code = await runQueryVerb(cmd, parsed);
+    if (code !== 0) process.exit(code);
+    return;
+  }
   console.error(`neat: unknown command "${cmd}"`);
   usage();
   process.exit(1);
 }
+var QUERY_VERBS = /* @__PURE__ */ new Set([
+  "root-cause",
+  "blast-radius",
+  "dependencies",
+  "observed-dependencies",
+  "incidents",
+  "search",
+  "diff",
+  "stale-edges",
+  "policies"
+]);
+function resolveProjectFlag(parsed) {
+  if (parsed.project) return parsed.project;
+  const env = process.env.NEAT_PROJECT;
+  if (env && env.length > 0 && env !== DEFAULT_PROJECT) return env;
+  return void 0;
+}
+async function runQueryVerb(cmd, parsed) {
+  const baseUrl = process.env.NEAT_API_URL ?? "http://localhost:8080";
+  const client = createHttpClient(baseUrl);
+  const project = resolveProjectFlag(parsed);
+  const positional = parsed.positional;
+  let work;
+  switch (cmd) {
+    case "root-cause": {
+      const node = positional[0];
+      if (!node) {
+        console.error("neat root-cause: missing <node-id>");
+        return 2;
+      }
+      work = runRootCause(client, {
+        errorNode: node,
+        ...parsed.errorId ? { errorId: parsed.errorId } : {},
+        ...project ? { project } : {}
+      });
+      break;
+    }
+    case "blast-radius": {
+      const node = positional[0];
+      if (!node) {
+        console.error("neat blast-radius: missing <node-id>");
+        return 2;
+      }
+      work = runBlastRadius(client, {
+        nodeId: node,
+        ...parsed.depth !== null ? { depth: parsed.depth } : {},
+        ...project ? { project } : {}
+      });
+      break;
+    }
+    case "dependencies": {
+      const node = positional[0];
+      if (!node) {
+        console.error("neat dependencies: missing <node-id>");
+        return 2;
+      }
+      work = runDependencies(client, {
+        nodeId: node,
+        ...parsed.depth !== null ? { depth: parsed.depth } : {},
+        ...project ? { project } : {}
+      });
+      break;
+    }
+    case "observed-dependencies": {
+      const node = positional[0];
+      if (!node) {
+        console.error("neat observed-dependencies: missing <node-id>");
+        return 2;
+      }
+      work = runObservedDependencies(client, {
+        nodeId: node,
+        ...project ? { project } : {}
+      });
+      break;
+    }
+    case "incidents": {
+      work = runIncidents(client, {
+        ...positional[0] ? { nodeId: positional[0] } : {},
+        ...parsed.limit !== null ? { limit: parsed.limit } : {},
+        ...project ? { project } : {}
+      });
+      break;
+    }
+    case "search": {
+      const q = positional.join(" ").trim();
+      if (!q) {
+        console.error("neat search: missing <query>");
+        return 2;
+      }
+      work = runSearch(client, { query: q, ...project ? { project } : {} });
+      break;
+    }
+    case "diff": {
+      const against = parsed.against ?? parsed.since;
+      if (!against) {
+        console.error("neat diff: --against <snapshot-path> is required");
+        return 2;
+      }
+      work = runDiff(client, {
+        againstSnapshot: against,
+        ...project ? { project } : {}
+      });
+      break;
+    }
+    case "stale-edges": {
+      work = runStaleEdges(client, {
+        ...parsed.limit !== null ? { limit: parsed.limit } : {},
+        ...parsed.edgeType ? { edgeType: parsed.edgeType } : {},
+        ...project ? { project } : {}
+      });
+      break;
+    }
+    case "policies": {
+      let hypothetical;
+      if (parsed.hypotheticalAction) {
+        try {
+          hypothetical = JSON.parse(parsed.hypotheticalAction);
+        } catch (err) {
+          console.error(
+            `neat policies: --hypothetical-action must be valid JSON: ${err.message}`
+          );
+          return 2;
+        }
+      }
+      work = runPolicies(client, {
+        ...parsed.node ? { nodeId: parsed.node } : {},
+        ...hypothetical ? { hypotheticalAction: hypothetical } : {},
+        ...project ? { project } : {}
+      });
+      break;
+    }
+    default:
+      console.error(`neat: unknown query verb "${cmd}"`);
+      return 2;
+  }
+  try {
+    const result = await work;
+    if (parsed.json) process.stdout.write(formatJson(result) + "\n");
+    else process.stdout.write(formatHuman(result) + "\n");
+    return 0;
+  } catch (err) {
+    if (err instanceof HttpError) {
+      const detail = err.responseBody.length > 0 ? err.responseBody : err.message;
+      console.error(`neat ${cmd}: ${detail.trim()}`);
+    } else if (err instanceof TransportError) {
+      console.error(`neat ${cmd}: ${err.message}. Is the daemon running? (NEAT_API_URL=${process.env.NEAT_API_URL ?? "http://localhost:8080"})`);
+    } else {
+      console.error(`neat ${cmd}: ${err.message}`);
+    }
+    return exitCodeForError(err);
+  }
+}
 var entry = process.argv[1] ?? "";
 if (/[\\/]cli\.(?:cjs|js)$/.test(entry) || entry.endsWith("/cli") || entry.endsWith("/neat")) {
   main().catch((err) => {
@@ -5748,7 +6625,10 @@ if (/[\\/]cli\.(?:cjs|js)$/.test(entry) || entry.endsWith("/cli") || entry.endsW
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   CLAUDE_SKILL_CONFIG,
+  QUERY_VERBS,
+  parseArgs,
   runInit,
+  runQueryVerb,
   runSkill
 });
 //# sourceMappingURL=cli.cjs.map