@neat.is/core 0.3.6 → 0.3.8

package/dist/cli.cjs

@@ -41,6 +41,43 @@ var init_cjs_shims = __esm({
   }
 });
 
+// src/auth.ts
+function mountBearerAuth(app, opts) {
+  if (!opts.token || opts.token.length === 0) return;
+  if (opts.trustProxy) return;
+  const expected = Buffer.from(opts.token, "utf8");
+  const suffixes = [...DEFAULT_UNAUTH_SUFFIXES, ...opts.extraUnauthenticatedSuffixes ?? []];
+  app.addHook("preHandler", (req, reply, done) => {
+    const path44 = (req.url.split("?")[0] ?? "").replace(/\/+$/, "");
+    for (const suffix of suffixes) {
+      if (path44 === suffix || path44.endsWith(suffix)) {
+        done();
+        return;
+      }
+    }
+    const header = req.headers.authorization;
+    if (typeof header !== "string" || !header.startsWith("Bearer ")) {
+      void reply.code(401).send({ error: "unauthorized" });
+      return;
+    }
+    const provided = Buffer.from(header.slice("Bearer ".length).trim(), "utf8");
+    if (provided.length !== expected.length || !(0, import_node_crypto.timingSafeEqual)(provided, expected)) {
+      void reply.code(401).send({ error: "unauthorized" });
+      return;
+    }
+    done();
+  });
+}
+var import_node_crypto, DEFAULT_UNAUTH_SUFFIXES;
+var init_auth = __esm({
+  "src/auth.ts"() {
+    "use strict";
+    init_cjs_shims();
+    import_node_crypto = require("crypto");
+    DEFAULT_UNAUTH_SUFFIXES = ["/health", "/healthz", "/readyz"];
+  }
+});
+
 // src/otel-grpc.ts
 var otel_grpc_exports = {};
 __export(otel_grpc_exports, {
@@ -101,8 +138,8 @@ function reshapeGrpcRequest(req) {
   };
 }
 function resolveProtoRoot() {
-  const here = import_node_path34.default.dirname((0, import_node_url.fileURLToPath)(importMetaUrl));
-  return import_node_path34.default.resolve(here, "..", "proto");
+  const here = import_node_path35.default.dirname((0, import_node_url.fileURLToPath)(importMetaUrl));
+  return import_node_path35.default.resolve(here, "..", "proto");
 }
 function loadTraceService() {
   const protoRoot = resolveProtoRoot();
@@ -123,8 +160,21 @@ function loadTraceService() {
 async function startOtelGrpcReceiver(opts) {
   const server = new grpc.Server();
   const service = loadTraceService();
+  const requiresAuth = !opts.trustProxy && !!opts.authToken && opts.authToken.length > 0;
+  const expectedHeader = requiresAuth ? `Bearer ${opts.authToken}` : "";
   server.addService(service, {
     Export: (call, callback) => {
+      if (requiresAuth) {
+        const meta = call.metadata.get("authorization");
+        const got = meta.length > 0 ? String(meta[0]) : "";
+        const a = Buffer.from(got, "utf8");
+        const b = Buffer.from(expectedHeader, "utf8");
+        const ok = a.length === b.length && (0, import_node_crypto2.timingSafeEqual)(a, b);
+        if (!ok) {
+          callback({ code: grpc.status.UNAUTHENTICATED, message: "unauthorized" });
+          return;
+        }
+      }
       void (async () => {
         try {
           const reshaped = reshapeGrpcRequest(call.request ?? {});
@@ -157,13 +207,14 @@ async function startOtelGrpcReceiver(opts) {
     })
   };
 }
-var import_node_url, import_node_path34, grpc, protoLoader;
+var import_node_url, import_node_path35, import_node_crypto2, grpc, protoLoader;
 var init_otel_grpc = __esm({
   "src/otel-grpc.ts"() {
     "use strict";
     init_cjs_shims();
     import_node_url = require("url");
-    import_node_path34 = __toESM(require("path"), 1);
+    import_node_path35 = __toESM(require("path"), 1);
+    import_node_crypto2 = require("crypto");
     grpc = __toESM(require("@grpc/grpc-js"), 1);
     protoLoader = __toESM(require("@grpc/proto-loader"), 1);
     init_otel();
@@ -258,21 +309,41 @@ function parseOtlpRequest(body) {
   }
   return out;
 }
-function loadProtobufDecoder() {
-  if (exportTraceServiceRequestType) return exportTraceServiceRequestType;
-  const here = import_node_path35.default.dirname((0, import_node_url2.fileURLToPath)(importMetaUrl));
-  const protoRoot = import_node_path35.default.resolve(here, "..", "proto");
+function loadProtoRoot() {
+  const here = import_node_path36.default.dirname((0, import_node_url2.fileURLToPath)(importMetaUrl));
+  const protoRoot = import_node_path36.default.resolve(here, "..", "proto");
   const root = new import_protobufjs.default.Root();
-  root.resolvePath = (_origin, target) => import_node_path35.default.resolve(protoRoot, target);
+  root.resolvePath = (_origin, target) => import_node_path36.default.resolve(protoRoot, target);
   root.loadSync(
     "opentelemetry/proto/collector/trace/v1/trace_service.proto",
     { keepCase: true }
   );
+  return root;
+}
+function loadProtobufDecoder() {
+  if (exportTraceServiceRequestType) return exportTraceServiceRequestType;
+  const root = loadProtoRoot();
   exportTraceServiceRequestType = root.lookupType(
     "opentelemetry.proto.collector.trace.v1.ExportTraceServiceRequest"
   );
   return exportTraceServiceRequestType;
 }
+function loadProtobufResponseEncoder() {
+  if (exportTraceServiceResponseType) return exportTraceServiceResponseType;
+  const root = loadProtoRoot();
+  exportTraceServiceResponseType = root.lookupType(
+    "opentelemetry.proto.collector.trace.v1.ExportTraceServiceResponse"
+  );
+  return exportTraceServiceResponseType;
+}
+function encodeProtobufResponseBody() {
+  if (cachedProtobufResponseBody) return cachedProtobufResponseBody;
+  const Type = loadProtobufResponseEncoder();
+  const msg = Type.create({});
+  const encoded = Type.encode(msg).finish();
+  cachedProtobufResponseBody = Buffer.from(encoded);
+  return cachedProtobufResponseBody;
+}
 async function decodeProtobufBody(buf) {
   const Type = loadProtobufDecoder();
   const decoded = Type.decode(buf).toJSON();
@@ -284,6 +355,7 @@ async function buildOtelReceiver(opts) {
     logger: false,
     bodyLimit: opts.bodyLimit ?? 16 * 1024 * 1024
   });
+  mountBearerAuth(app, { token: opts.authToken, trustProxy: opts.trustProxy });
   const queue = [];
   let draining = false;
   let drainPromise = Promise.resolve();
@@ -319,7 +391,9 @@ async function buildOtelReceiver(opts) {
   app.post("/v1/traces", async (req, reply) => {
     const ct = (req.headers["content-type"] ?? "").toString().split(";")[0].trim().toLowerCase();
     let body;
+    let responseFlavor;
     if (ct === "application/x-protobuf") {
+      responseFlavor = "protobuf";
       try {
         body = await decodeProtobufBody(req.body);
       } catch (err) {
@@ -328,6 +402,7 @@ async function buildOtelReceiver(opts) {
         });
       }
     } else if (!ct || ct === "application/json") {
+      responseFlavor = "json";
       body = req.body ?? {};
     } else {
       return reply.code(415).send({ error: `unsupported content-type: ${ct}` });
@@ -345,7 +420,11 @@ async function buildOtelReceiver(opts) {
       }
     }
     enqueue(spans);
-    return reply.code(200).send({ partialSuccess: {} });
+    if (responseFlavor === "protobuf") {
+      const buf = encodeProtobufResponseBody();
+      return reply.code(200).header("content-type", "application/x-protobuf").send(buf);
+    }
+    return reply.code(200).header("content-type", "application/json").send({ partialSuccess: {} });
   });
   const decorated = app;
   decorated.flushPending = async () => {
@@ -355,16 +434,19 @@ async function buildOtelReceiver(opts) {
   };
   return decorated;
 }
-var import_node_path35, import_node_url2, import_fastify2, import_protobufjs, exportTraceServiceRequestType;
+var import_node_path36, import_node_url2, import_fastify2, import_protobufjs, exportTraceServiceRequestType, exportTraceServiceResponseType, cachedProtobufResponseBody;
 var init_otel = __esm({
   "src/otel.ts"() {
     "use strict";
     init_cjs_shims();
-    import_node_path35 = __toESM(require("path"), 1);
+    import_node_path36 = __toESM(require("path"), 1);
     import_node_url2 = require("url");
     import_fastify2 = __toESM(require("fastify"), 1);
     import_protobufjs = __toESM(require("protobufjs"), 1);
+    init_auth();
     exportTraceServiceRequestType = null;
+    exportTraceServiceResponseType = null;
+    cachedProtobufResponseBody = null;
   }
 });
 
@@ -380,8 +462,8 @@ __export(cli_exports, {
 });
 module.exports = __toCommonJS(cli_exports);
 init_cjs_shims();
-var import_node_path40 = __toESM(require("path"), 1);
-var import_node_fs25 = require("fs");
+var import_node_path43 = __toESM(require("path"), 1);
+var import_node_fs28 = require("fs");
 
 // src/graph.ts
 init_cjs_shims();
@@ -891,19 +973,19 @@ function confidenceFromMix(edges, now = Date.now()) {
 function longestIncomingWalk(graph, start, maxDepth) {
   let best = { path: [start], edges: [] };
   const visited = /* @__PURE__ */ new Set([start]);
-  function step(node, path41, edges) {
-    if (path41.length > best.path.length) {
-      best = { path: [...path41], edges: [...edges] };
+  function step(node, path44, edges) {
+    if (path44.length > best.path.length) {
+      best = { path: [...path44], edges: [...edges] };
     }
-    if (path41.length - 1 >= maxDepth) return;
+    if (path44.length - 1 >= maxDepth) return;
     const incoming = bestEdgeBySource(graph, graph.inboundEdges(node));
     for (const [srcId, edge] of incoming) {
       if (visited.has(srcId)) continue;
       visited.add(srcId);
-      path41.push(srcId);
+      path44.push(srcId);
       edges.push(edge);
-      step(srcId, path41, edges);
-      path41.pop();
+      step(srcId, path44, edges);
+      path44.pop();
       edges.pop();
       visited.delete(srcId);
     }
@@ -4146,128 +4228,9 @@ async function extractFromDirectory(graph, scanPath, opts = {}) {
   return result;
 }
 
-// src/persist.ts
-init_cjs_shims();
-var import_node_fs18 = require("fs");
-var import_node_path31 = __toESM(require("path"), 1);
-var import_types19 = require("@neat.is/types");
-var SCHEMA_VERSION = 3;
-function migrateV1ToV2(payload) {
-  const nodes = payload.graph.nodes;
-  if (Array.isArray(nodes)) {
-    for (const node of nodes) {
-      if (node.attributes && "pgDriverVersion" in node.attributes) {
-        delete node.attributes.pgDriverVersion;
-      }
-    }
-  }
-  return { ...payload, schemaVersion: 2 };
-}
-function migrateV2ToV3(payload) {
-  const edges = payload.graph.edges;
-  if (Array.isArray(edges)) {
-    for (const edge of edges) {
-      const attrs = edge.attributes;
-      if (!attrs || attrs.provenance !== "FRONTIER") continue;
-      attrs.provenance = import_types19.Provenance.OBSERVED;
-      const type = typeof attrs.type === "string" ? attrs.type : void 0;
-      const source = typeof attrs.source === "string" ? attrs.source : void 0;
-      const target = typeof attrs.target === "string" ? attrs.target : void 0;
-      if (type && source && target) {
-        const newId = (0, import_types19.observedEdgeId)(source, target, type);
-        attrs.id = newId;
-        if (edge.key) edge.key = newId;
-      }
-    }
-  }
-  return { ...payload, schemaVersion: 3 };
-}
-async function ensureDir(filePath) {
-  await import_node_fs18.promises.mkdir(import_node_path31.default.dirname(filePath), { recursive: true });
-}
-async function saveGraphToDisk(graph, outPath) {
-  await ensureDir(outPath);
-  const payload = {
-    schemaVersion: SCHEMA_VERSION,
-    exportedAt: (/* @__PURE__ */ new Date()).toISOString(),
-    graph: graph.export()
-  };
-  const tmp = `${outPath}.tmp`;
-  await import_node_fs18.promises.writeFile(tmp, JSON.stringify(payload), "utf8");
-  await import_node_fs18.promises.rename(tmp, outPath);
-}
-async function loadGraphFromDisk(graph, outPath) {
-  let raw;
-  try {
-    raw = await import_node_fs18.promises.readFile(outPath, "utf8");
-  } catch (err) {
-    if (err.code === "ENOENT") return;
-    throw err;
-  }
-  let payload = JSON.parse(raw);
-  if (payload.schemaVersion === 1) {
-    payload = migrateV1ToV2(payload);
-  }
-  if (payload.schemaVersion === 2) {
-    payload = migrateV2ToV3(payload);
-  }
-  if (payload.schemaVersion !== SCHEMA_VERSION) {
-    throw new Error(
-      `persist: unsupported snapshot schemaVersion ${payload.schemaVersion} (expected ${SCHEMA_VERSION})`
-    );
-  }
-  graph.clear();
-  graph.import(payload.graph);
-}
-function startPersistLoop(graph, outPath, intervalMs = 6e4) {
-  let stopped = false;
-  const tick = async () => {
-    if (stopped) return;
-    try {
-      await saveGraphToDisk(graph, outPath);
-    } catch (err) {
-      console.error("persist: periodic save failed", err);
-    }
-  };
-  const interval = setInterval(() => {
-    void tick();
-  }, intervalMs);
-  const onSignal = (signal) => {
-    void (async () => {
-      try {
-        await saveGraphToDisk(graph, outPath);
-      } catch (err) {
-        console.error(`persist: ${signal} save failed`, err);
-      } finally {
-        process.exit(0);
-      }
-    })();
-  };
-  process.on("SIGTERM", onSignal);
-  process.on("SIGINT", onSignal);
-  return () => {
-    stopped = true;
-    clearInterval(interval);
-    process.off("SIGTERM", onSignal);
-    process.off("SIGINT", onSignal);
-  };
-}
-
-// src/watch.ts
-init_cjs_shims();
-var import_node_fs22 = __toESM(require("fs"), 1);
-var import_node_path37 = __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_types22 = require("@neat.is/types");
-
 // src/divergences.ts
 init_cjs_shims();
-var import_types20 = require("@neat.is/types");
+var import_types19 = require("@neat.is/types");
 function bucketKey(source, target, type) {
   return `${type}|${source}|${target}`;
 }
@@ -4275,22 +4238,22 @@ function bucketEdges(graph) {
   const buckets = /* @__PURE__ */ new Map();
   graph.forEachEdge((id, attrs) => {
     const e = attrs;
-    const parsed = (0, import_types20.parseEdgeId)(id);
+    const parsed = (0, import_types19.parseEdgeId)(id);
     const provenance = parsed?.provenance ?? e.provenance;
     const key = bucketKey(e.source, e.target, e.type);
     const cur = buckets.get(key) ?? { source: e.source, target: e.target, type: e.type };
     switch (provenance) {
-      case import_types20.Provenance.EXTRACTED:
+      case import_types19.Provenance.EXTRACTED:
         cur.extracted = e;
         break;
-      case import_types20.Provenance.OBSERVED:
+      case import_types19.Provenance.OBSERVED:
         cur.observed = e;
         break;
-      case import_types20.Provenance.INFERRED:
+      case import_types19.Provenance.INFERRED:
         cur.inferred = e;
         break;
       default:
-        if (e.provenance === import_types20.Provenance.STALE) cur.stale = e;
+        if (e.provenance === import_types19.Provenance.STALE) cur.stale = e;
     }
     buckets.set(key, cur);
   });
@@ -4299,7 +4262,7 @@ function bucketEdges(graph) {
 function nodeIsFrontier(graph, nodeId) {
   if (!graph.hasNode(nodeId)) return false;
   const attrs = graph.getNodeAttributes(nodeId);
-  return attrs.type === import_types20.NodeType.FrontierNode;
+  return attrs.type === import_types19.NodeType.FrontierNode;
 }
 function clampConfidence(n) {
   if (!Number.isFinite(n)) return 0;
@@ -4360,7 +4323,7 @@ function declaredHostFor(svc) {
 function hasExtractedConfiguredBy(graph, svcId) {
   for (const edgeId of graph.outboundEdges(svcId)) {
     const e = graph.getEdgeAttributes(edgeId);
-    if (e.type === import_types20.EdgeType.CONFIGURED_BY && e.provenance === import_types20.Provenance.EXTRACTED) {
+    if (e.type === import_types19.EdgeType.CONFIGURED_BY && e.provenance === import_types19.Provenance.EXTRACTED) {
       return true;
     }
   }
@@ -4373,10 +4336,10 @@ function detectHostMismatch(graph, svcId, svc) {
   const out = [];
   for (const edgeId of graph.outboundEdges(svcId)) {
     const edge = graph.getEdgeAttributes(edgeId);
-    if (edge.type !== import_types20.EdgeType.CONNECTS_TO) continue;
-    if (edge.provenance !== import_types20.Provenance.OBSERVED) continue;
+    if (edge.type !== import_types19.EdgeType.CONNECTS_TO) continue;
+    if (edge.provenance !== import_types19.Provenance.OBSERVED) continue;
     const target = graph.getNodeAttributes(edge.target);
-    if (target.type !== import_types20.NodeType.DatabaseNode) continue;
+    if (target.type !== import_types19.NodeType.DatabaseNode) continue;
     const observedHost = target.host?.trim();
     if (!observedHost) continue;
     if (observedHost === declaredHost) continue;
@@ -4398,10 +4361,10 @@ function detectCompatDivergences(graph, svcId, svc) {
   const deps = svc.dependencies ?? {};
   for (const edgeId of graph.outboundEdges(svcId)) {
     const edge = graph.getEdgeAttributes(edgeId);
-    if (edge.type !== import_types20.EdgeType.CONNECTS_TO) continue;
-    if (edge.provenance !== import_types20.Provenance.OBSERVED) continue;
+    if (edge.type !== import_types19.EdgeType.CONNECTS_TO) continue;
+    if (edge.provenance !== import_types19.Provenance.OBSERVED) continue;
     const target = graph.getNodeAttributes(edge.target);
-    if (target.type !== import_types20.NodeType.DatabaseNode) continue;
+    if (target.type !== import_types19.NodeType.DatabaseNode) continue;
     for (const pair of compatPairs()) {
       if (pair.engine !== target.engine) continue;
       const declared = deps[pair.driver];
@@ -4462,7 +4425,7 @@ function computeDivergences(graph, opts = {}) {
   }
   graph.forEachNode((nodeId, attrs) => {
     const n = attrs;
-    if (n.type !== import_types20.NodeType.ServiceNode) return;
+    if (n.type !== import_types19.NodeType.ServiceNode) return;
     const svc = n;
     for (const d of detectHostMismatch(graph, nodeId, svc)) all.push(d);
     for (const d of detectCompatDivergences(graph, nodeId, svc)) all.push(d);
@@ -4495,76 +4458,327 @@ function computeDivergences(graph, opts = {}) {
     if (a.source !== b.source) return a.source.localeCompare(b.source);
     return a.target.localeCompare(b.target);
   });
-  return import_types20.DivergenceResultSchema.parse({
+  return import_types19.DivergenceResultSchema.parse({
     divergences: filtered,
     totalAffected: filtered.length,
     computedAt: (/* @__PURE__ */ new Date()).toISOString()
   });
 }
 
-// src/diff.ts
+// src/persist.ts
 init_cjs_shims();
-var import_node_fs19 = require("fs");
-async function loadSnapshotForDiff(target) {
-  if (/^https?:\/\//i.test(target)) {
-    const res = await fetch(target);
-    if (!res.ok) {
-      throw new Error(`fetch ${target} failed: ${res.status} ${res.statusText}`);
+var import_node_fs18 = require("fs");
+var import_node_path31 = __toESM(require("path"), 1);
+var import_types20 = require("@neat.is/types");
+var SCHEMA_VERSION = 3;
+function migrateV1ToV2(payload) {
+  const nodes = payload.graph.nodes;
+  if (Array.isArray(nodes)) {
+    for (const node of nodes) {
+      if (node.attributes && "pgDriverVersion" in node.attributes) {
+        delete node.attributes.pgDriverVersion;
+      }
     }
-    return await res.json();
   }
-  const raw = await import_node_fs19.promises.readFile(target, "utf8");
-  return JSON.parse(raw);
+  return { ...payload, schemaVersion: 2 };
 }
-function indexEntries(entries) {
-  const m = /* @__PURE__ */ new Map();
-  if (!entries) return m;
-  for (const entry2 of entries) {
-    const id = entry2.attributes?.id ?? entry2.key;
-    if (!id) continue;
-    m.set(id, entry2.attributes);
+function migrateV2ToV3(payload) {
+  const edges = payload.graph.edges;
+  if (Array.isArray(edges)) {
+    for (const edge of edges) {
+      const attrs = edge.attributes;
+      if (!attrs || attrs.provenance !== "FRONTIER") continue;
+      attrs.provenance = import_types20.Provenance.OBSERVED;
+      const type = typeof attrs.type === "string" ? attrs.type : void 0;
+      const source = typeof attrs.source === "string" ? attrs.source : void 0;
+      const target = typeof attrs.target === "string" ? attrs.target : void 0;
+      if (type && source && target) {
+        const newId = (0, import_types20.observedEdgeId)(source, target, type);
+        attrs.id = newId;
+        if (edge.key) edge.key = newId;
+      }
+    }
   }
-  return m;
+  return { ...payload, schemaVersion: 3 };
 }
-function computeGraphDiff(liveGraph, baseSnapshot, currentExportedAt = (/* @__PURE__ */ new Date()).toISOString()) {
-  const baseNodes = indexEntries(baseSnapshot.graph?.nodes);
-  const baseEdges = indexEntries(baseSnapshot.graph?.edges);
-  const liveNodes = /* @__PURE__ */ new Map();
-  liveGraph.forEachNode((id, attrs) => liveNodes.set(id, attrs));
-  const liveEdges = /* @__PURE__ */ new Map();
-  liveGraph.forEachEdge((id, attrs) => liveEdges.set(id, attrs));
-  const result = {
-    base: { exportedAt: baseSnapshot.exportedAt },
-    current: { exportedAt: currentExportedAt },
-    added: { nodes: [], edges: [] },
-    removed: { nodes: [], edges: [] },
-    changed: { nodes: [], edges: [] }
+async function ensureDir(filePath) {
+  await import_node_fs18.promises.mkdir(import_node_path31.default.dirname(filePath), { recursive: true });
+}
+async function saveGraphToDisk(graph, outPath) {
+  await ensureDir(outPath);
+  const payload = {
+    schemaVersion: SCHEMA_VERSION,
+    exportedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    graph: graph.export()
   };
-  for (const [id, after] of liveNodes) {
-    const before = baseNodes.get(id);
-    if (!before) {
-      result.added.nodes.push(after);
-    } else if (!shallowEqual(before, after)) {
-      result.changed.nodes.push({ id, before, after });
-    }
+  const tmp = `${outPath}.tmp`;
+  await import_node_fs18.promises.writeFile(tmp, JSON.stringify(payload), "utf8");
+  await import_node_fs18.promises.rename(tmp, outPath);
+}
+async function loadGraphFromDisk(graph, outPath) {
+  let raw;
+  try {
+    raw = await import_node_fs18.promises.readFile(outPath, "utf8");
+  } catch (err) {
+    if (err.code === "ENOENT") return;
+    throw err;
   }
-  for (const [id, before] of baseNodes) {
-    if (!liveNodes.has(id)) result.removed.nodes.push(before);
+  let payload = JSON.parse(raw);
+  if (payload.schemaVersion === 1) {
+    payload = migrateV1ToV2(payload);
   }
-  for (const [id, after] of liveEdges) {
-    const before = baseEdges.get(id);
-    if (!before) {
-      result.added.edges.push(after);
-    } else if (!shallowEqual(before, after)) {
-      result.changed.edges.push({ id, before, after });
-    }
+  if (payload.schemaVersion === 2) {
+    payload = migrateV2ToV3(payload);
   }
-  for (const [id, before] of baseEdges) {
-    if (!liveEdges.has(id)) result.removed.edges.push(before);
+  if (payload.schemaVersion !== SCHEMA_VERSION) {
+    throw new Error(
+      `persist: unsupported snapshot schemaVersion ${payload.schemaVersion} (expected ${SCHEMA_VERSION})`
+    );
   }
-  return result;
+  graph.clear();
+  graph.import(payload.graph);
 }
-function shallowEqual(a, b) {
+function startPersistLoop(graph, outPath, intervalMs = 6e4) {
+  let stopped = false;
+  const tick = async () => {
+    if (stopped) return;
+    try {
+      await saveGraphToDisk(graph, outPath);
+    } catch (err) {
+      console.error("persist: periodic save failed", err);
+    }
+  };
+  const interval = setInterval(() => {
+    void tick();
+  }, intervalMs);
+  const onSignal = (signal) => {
+    void (async () => {
+      try {
+        await saveGraphToDisk(graph, outPath);
+      } catch (err) {
+        console.error(`persist: ${signal} save failed`, err);
+      } finally {
+        process.exit(0);
+      }
+    })();
+  };
+  process.on("SIGTERM", onSignal);
+  process.on("SIGINT", onSignal);
+  return () => {
+    stopped = true;
+    clearInterval(interval);
+    process.off("SIGTERM", onSignal);
+    process.off("SIGINT", onSignal);
+  };
+}
+
+// src/gitignore.ts
+init_cjs_shims();
+var import_node_fs19 = require("fs");
+var import_node_path32 = __toESM(require("path"), 1);
+var NEAT_OUT_LINE = "neat-out/";
+var NEAT_HEADER = "# NEAT \u2014 machine-local snapshots and events";
+function isNeatOutLine(line) {
+  const trimmed = line.trim();
+  return trimmed === "neat-out/" || trimmed === "neat-out";
+}
+async function ensureNeatOutIgnored(projectDir) {
+  const file = import_node_path32.default.join(projectDir, ".gitignore");
+  let existing = null;
+  try {
+    existing = await import_node_fs19.promises.readFile(file, "utf8");
+  } catch (err) {
+    if (err.code !== "ENOENT") throw err;
+  }
+  if (existing === null) {
+    await import_node_fs19.promises.writeFile(file, `${NEAT_HEADER}
+${NEAT_OUT_LINE}
+`, "utf8");
+    return { action: "created", file };
+  }
+  for (const line of existing.split(/\r?\n/)) {
+    if (isNeatOutLine(line)) return { action: "unchanged", file };
+  }
+  const needsLeadingNewline = existing.length > 0 && !existing.endsWith("\n");
+  const appended = `${needsLeadingNewline ? "\n" : ""}
+${NEAT_HEADER}
+${NEAT_OUT_LINE}
+`;
+  await import_node_fs19.promises.writeFile(file, existing + appended, "utf8");
+  return { action: "added", file };
+}
+
+// src/summary.ts
+init_cjs_shims();
+var import_types21 = require("@neat.is/types");
+function renderOtelEnvBlock() {
+  return [
+    "for prod OTel routing, set these in your deploy platform's env:",
+    "  OTEL_EXPORTER_OTLP_ENDPOINT=https://<your-neat-host>:4318",
+    "  OTEL_EXPORTER_OTLP_HEADERS=Authorization=Bearer <NEAT_AUTH_TOKEN>"
+  ].join("\n");
+}
+function findIncompatServices(nodes) {
+  return nodes.filter(
+    (n) => n.type === import_types21.NodeType.ServiceNode && Array.isArray(n.incompatibilities) && (n.incompatibilities ?? []).length > 0
+  );
+}
+function servicesWithoutObserved(nodes, edges) {
+  const seen = /* @__PURE__ */ new Set();
+  for (const e of edges) {
+    if (e.provenance === import_types21.Provenance.OBSERVED) {
+      seen.add(e.source);
+      seen.add(e.target);
+    }
+  }
+  return nodes.filter(
+    (n) => n.type === import_types21.NodeType.ServiceNode && !seen.has(n.id)
+  );
+}
+function formatDivergence(d) {
+  const conf = d.confidence.toFixed(2);
+  return `  [${conf}] ${d.type} ${d.source} \u2192 ${d.target} \u2014 ${d.reason}`;
+}
+function renderValueForwardSummary(input) {
+  const { graph, divergences, verbose } = input;
+  const nodes = [];
+  graph.forEachNode((_id, attrs) => nodes.push(attrs));
+  const edges = [];
+  graph.forEachEdge((_id, attrs) => edges.push(attrs));
+  const lines = [];
+  lines.push("=== neat: findings ===");
+  lines.push("");
+  const incompatServices = findIncompatServices(nodes);
+  const totalIncompats = incompatServices.reduce(
+    (acc, s) => acc + (s.incompatibilities?.length ?? 0),
+    0
+  );
+  lines.push(`compat violations: ${totalIncompats}`);
+  for (const svc of incompatServices) {
+    for (const inc of svc.incompatibilities ?? []) {
+      const detail = formatIncompat(inc);
+      lines.push(`  ${svc.name}: ${detail}`);
+    }
+  }
+  lines.push("");
+  const top = [...divergences].sort((a, b) => b.confidence - a.confidence).slice(0, 3);
+  lines.push(`top divergences: ${divergences.length} total${top.length > 0 ? ", top 3:" : ""}`);
+  for (const d of top) lines.push(formatDivergence(d));
+  lines.push("");
+  const noObserved = servicesWithoutObserved(nodes, edges);
+  if (noObserved.length > 0) {
+    lines.push(`services without OBSERVED coverage: ${noObserved.length}`);
+    for (const svc of noObserved) lines.push(`  ${svc.name}`);
+    lines.push("  \u2192 run your services with the generated otel-init to populate OBSERVED edges.");
+    lines.push("");
+  }
+  lines.push(renderOtelEnvBlock());
+  lines.push("");
+  if (verbose) {
+    const byNode = /* @__PURE__ */ new Map();
+    for (const n of nodes) byNode.set(n.type, (byNode.get(n.type) ?? 0) + 1);
+    const byEdge = /* @__PURE__ */ new Map();
+    for (const e of edges) byEdge.set(e.type, (byEdge.get(e.type) ?? 0) + 1);
+    lines.push("=== graph (verbose) ===");
+    lines.push(`total: ${graph.order} nodes, ${graph.size} edges`);
+    lines.push("nodes:");
+    for (const [t, c] of [...byNode.entries()].sort()) lines.push(`  ${t}: ${c}`);
+    lines.push("edges:");
+    for (const [t, c] of [...byEdge.entries()].sort()) lines.push(`  ${t}: ${c}`);
+    lines.push("");
+  }
+  return lines.join("\n");
+}
+function formatIncompat(inc) {
+  if (inc.kind === "node-engine") {
+    const range = inc.declaredNodeEngine ? ` (engines.node="${inc.declaredNodeEngine}")` : "";
+    return `${inc.package}@${inc.packageVersion ?? "?"} requires Node ${inc.requiredNodeVersion}${range} \u2014 ${inc.reason}`;
+  }
+  if (inc.kind === "package-conflict") {
+    const found = inc.foundVersion ? `@${inc.foundVersion}` : " (missing)";
+    return `${inc.package}@${inc.packageVersion ?? "?"} requires ${inc.requires.name}>=${inc.requires.minVersion}; found ${inc.requires.name}${found} \u2014 ${inc.reason}`;
+  }
+  if (inc.kind === "deprecated-api") {
+    return `${inc.package}@${inc.packageVersion ?? "?"} is deprecated \u2014 ${inc.reason}`;
+  }
+  return `${inc.driver}@${inc.driverVersion} vs ${inc.engine} ${inc.engineVersion} \u2014 ${inc.reason}`;
+}
+
+// src/watch.ts
+init_cjs_shims();
+var import_node_fs23 = __toESM(require("fs"), 1);
+var import_node_path38 = __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_types23 = require("@neat.is/types");
+
+// src/diff.ts
+init_cjs_shims();
+var import_node_fs20 = require("fs");
+async function loadSnapshotForDiff(target) {
+  if (/^https?:\/\//i.test(target)) {
+    const res = await fetch(target);
+    if (!res.ok) {
+      throw new Error(`fetch ${target} failed: ${res.status} ${res.statusText}`);
+    }
+    return await res.json();
+  }
+  const raw = await import_node_fs20.promises.readFile(target, "utf8");
+  return JSON.parse(raw);
+}
+function indexEntries(entries) {
+  const m = /* @__PURE__ */ new Map();
+  if (!entries) return m;
+  for (const entry2 of entries) {
+    const id = entry2.attributes?.id ?? entry2.key;
+    if (!id) continue;
+    m.set(id, entry2.attributes);
+  }
+  return m;
+}
+function computeGraphDiff(liveGraph, baseSnapshot, currentExportedAt = (/* @__PURE__ */ new Date()).toISOString()) {
+  const baseNodes = indexEntries(baseSnapshot.graph?.nodes);
+  const baseEdges = indexEntries(baseSnapshot.graph?.edges);
+  const liveNodes = /* @__PURE__ */ new Map();
+  liveGraph.forEachNode((id, attrs) => liveNodes.set(id, attrs));
+  const liveEdges = /* @__PURE__ */ new Map();
+  liveGraph.forEachEdge((id, attrs) => liveEdges.set(id, attrs));
+  const result = {
+    base: { exportedAt: baseSnapshot.exportedAt },
+    current: { exportedAt: currentExportedAt },
+    added: { nodes: [], edges: [] },
+    removed: { nodes: [], edges: [] },
+    changed: { nodes: [], edges: [] }
+  };
+  for (const [id, after] of liveNodes) {
+    const before = baseNodes.get(id);
+    if (!before) {
+      result.added.nodes.push(after);
+    } else if (!shallowEqual(before, after)) {
+      result.changed.nodes.push({ id, before, after });
+    }
+  }
+  for (const [id, before] of baseNodes) {
+    if (!liveNodes.has(id)) result.removed.nodes.push(before);
+  }
+  for (const [id, after] of liveEdges) {
+    const before = baseEdges.get(id);
+    if (!before) {
+      result.added.edges.push(after);
+    } else if (!shallowEqual(before, after)) {
+      result.changed.edges.push({ id, before, after });
+    }
+  }
+  for (const [id, before] of baseEdges) {
+    if (!liveEdges.has(id)) result.removed.edges.push(before);
+  }
+  return result;
+}
+function shallowEqual(a, b) {
   return canonicalJson(a) === canonicalJson(b);
 }
 function canonicalJson(value) {
@@ -4581,23 +4795,23 @@ function canonicalJson(value) {
 
 // src/projects.ts
 init_cjs_shims();
-var import_node_path32 = __toESM(require("path"), 1);
+var import_node_path33 = __toESM(require("path"), 1);
 function pathsForProject(project, baseDir) {
   if (project === DEFAULT_PROJECT) {
     return {
-      snapshotPath: import_node_path32.default.join(baseDir, "graph.json"),
-      errorsPath: import_node_path32.default.join(baseDir, "errors.ndjson"),
-      staleEventsPath: import_node_path32.default.join(baseDir, "stale-events.ndjson"),
-      embeddingsCachePath: import_node_path32.default.join(baseDir, "embeddings.json"),
-      policyViolationsPath: import_node_path32.default.join(baseDir, "policy-violations.ndjson")
+      snapshotPath: import_node_path33.default.join(baseDir, "graph.json"),
+      errorsPath: import_node_path33.default.join(baseDir, "errors.ndjson"),
+      staleEventsPath: import_node_path33.default.join(baseDir, "stale-events.ndjson"),
+      embeddingsCachePath: import_node_path33.default.join(baseDir, "embeddings.json"),
+      policyViolationsPath: import_node_path33.default.join(baseDir, "policy-violations.ndjson")
     };
   }
   return {
-    snapshotPath: import_node_path32.default.join(baseDir, `${project}.json`),
-    errorsPath: import_node_path32.default.join(baseDir, `errors.${project}.ndjson`),
-    staleEventsPath: import_node_path32.default.join(baseDir, `stale-events.${project}.ndjson`),
-    embeddingsCachePath: import_node_path32.default.join(baseDir, `embeddings.${project}.json`),
-    policyViolationsPath: import_node_path32.default.join(baseDir, `policy-violations.${project}.ndjson`)
+    snapshotPath: import_node_path33.default.join(baseDir, `${project}.json`),
+    errorsPath: import_node_path33.default.join(baseDir, `errors.${project}.ndjson`),
+    staleEventsPath: import_node_path33.default.join(baseDir, `stale-events.${project}.ndjson`),
+    embeddingsCachePath: import_node_path33.default.join(baseDir, `embeddings.${project}.json`),
+    policyViolationsPath: import_node_path33.default.join(baseDir, `policy-violations.${project}.ndjson`)
   };
 }
 var Projects = class {
@@ -4633,49 +4847,49 @@ var Projects = class {
 
 // src/registry.ts
 init_cjs_shims();
-var import_node_fs20 = require("fs");
+var import_node_fs21 = require("fs");
 var import_node_os2 = __toESM(require("os"), 1);
-var import_node_path33 = __toESM(require("path"), 1);
-var import_types21 = require("@neat.is/types");
+var import_node_path34 = __toESM(require("path"), 1);
+var import_types22 = 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");
+  if (override && override.length > 0) return import_node_path34.default.resolve(override);
+  return import_node_path34.default.join(import_node_os2.default.homedir(), ".neat");
 }
 function registryPath() {
-  return import_node_path33.default.join(neatHome(), "projects.json");
+  return import_node_path34.default.join(neatHome(), "projects.json");
 }
 function registryLockPath() {
-  return import_node_path33.default.join(neatHome(), "projects.json.lock");
+  return import_node_path34.default.join(neatHome(), "projects.json.lock");
 }
 async function normalizeProjectPath(input) {
-  const resolved = import_node_path33.default.resolve(input);
+  const resolved = import_node_path34.default.resolve(input);
   try {
-    return await import_node_fs20.promises.realpath(resolved);
+    return await import_node_fs21.promises.realpath(resolved);
   } catch {
     return resolved;
   }
 }
 async function writeAtomically(target, contents) {
-  await import_node_fs20.promises.mkdir(import_node_path33.default.dirname(target), { recursive: true });
+  await import_node_fs21.promises.mkdir(import_node_path34.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_fs20.promises.open(tmp, "w");
+  const fd = await import_node_fs21.promises.open(tmp, "w");
   try {
     await fd.writeFile(contents, "utf8");
     await fd.sync();
   } finally {
     await fd.close();
   }
-  await import_node_fs20.promises.rename(tmp, target);
+  await import_node_fs21.promises.rename(tmp, target);
 }
 async function acquireLock(lockPath, timeoutMs = LOCK_TIMEOUT_MS) {
   const deadline = Date.now() + timeoutMs;
-  await import_node_fs20.promises.mkdir(import_node_path33.default.dirname(lockPath), { recursive: true });
+  await import_node_fs21.promises.mkdir(import_node_path34.default.dirname(lockPath), { recursive: true });
   while (true) {
     try {
-      const fd = await import_node_fs20.promises.open(lockPath, "wx");
+      const fd = await import_node_fs21.promises.open(lockPath, "wx");
       await fd.close();
       return;
     } catch (err) {
@@ -4691,7 +4905,7 @@ async function acquireLock(lockPath, timeoutMs = LOCK_TIMEOUT_MS) {
   }
 }
 async function releaseLock(lockPath) {
-  await import_node_fs20.promises.unlink(lockPath).catch(() => {
+  await import_node_fs21.promises.unlink(lockPath).catch(() => {
   });
 }
 async function withLock(fn) {
@@ -4707,7 +4921,7 @@ async function readRegistry() {
   const file = registryPath();
   let raw;
   try {
-    raw = await import_node_fs20.promises.readFile(file, "utf8");
+    raw = await import_node_fs21.promises.readFile(file, "utf8");
   } catch (err) {
     if (err.code === "ENOENT") {
       return { version: 1, projects: [] };
@@ -4715,10 +4929,10 @@ async function readRegistry() {
     throw err;
   }
   const parsed = JSON.parse(raw);
-  return import_types21.RegistryFileSchema.parse(parsed);
+  return import_types22.RegistryFileSchema.parse(parsed);
 }
 async function writeRegistry(reg) {
-  const validated = import_types21.RegistryFileSchema.parse(reg);
+  const validated = import_types22.RegistryFileSchema.parse(reg);
   await writeAtomically(registryPath(), JSON.stringify(validated, null, 2) + "\n");
 }
 var ProjectNameCollisionError = class extends Error {
@@ -4846,6 +5060,7 @@ data: ${JSON.stringify(envelope.payload)}
 }
 
 // src/api.ts
+init_auth();
 function serializeGraph(graph) {
   const nodes = [];
   graph.forEachNode((_id, attrs) => {
@@ -4969,11 +5184,11 @@ function registerRoutes(scope, ctx) {
       const candidates = req.query.type.split(",").map((s) => s.trim()).filter((s) => s.length > 0);
       const parsed = [];
       for (const c of candidates) {
-        const r = import_types22.DivergenceTypeSchema.safeParse(c);
+        const r = import_types23.DivergenceTypeSchema.safeParse(c);
         if (!r.success) {
           return reply.code(400).send({
             error: `unknown divergence type "${c}"`,
-            allowed: import_types22.DivergenceTypeSchema.options
+            allowed: import_types23.DivergenceTypeSchema.options
           });
         }
         parsed.push(r.data);
@@ -5157,7 +5372,7 @@ function registerRoutes(scope, ctx) {
     const log = new PolicyViolationsLog(proj.paths.policyViolationsPath);
     let violations = await log.readAll();
     if (req.query.severity) {
-      const sev = import_types22.PolicySeveritySchema.safeParse(req.query.severity);
+      const sev = import_types23.PolicySeveritySchema.safeParse(req.query.severity);
       if (!sev.success) {
         return reply.code(400).send({
           error: "invalid severity",
@@ -5174,7 +5389,7 @@ function registerRoutes(scope, ctx) {
   scope.post("/policies/check", async (req, reply) => {
     const proj = resolveProject(registry, req, reply);
     if (!proj) return;
-    const parsed = import_types22.PoliciesCheckBodySchema.safeParse(req.body ?? {});
+    const parsed = import_types23.PoliciesCheckBodySchema.safeParse(req.body ?? {});
     if (!parsed.success) {
       return reply.code(400).send({
         error: "invalid /policies/check body",
@@ -5211,6 +5426,7 @@ function registerRoutes(scope, ctx) {
 async function buildApi(opts) {
   const app = (0, import_fastify.default)({ logger: false });
   await app.register(import_cors.default, { origin: true });
+  mountBearerAuth(app, { token: opts.authToken, trustProxy: opts.trustProxy });
   const startedAt = opts.startedAt ?? Date.now();
   const registry = buildLegacyRegistry(opts);
   const legacyErrorsExplicit = !opts.projects && opts.errorsPath !== void 0;
@@ -5278,9 +5494,9 @@ init_otel_grpc();
 
 // src/search.ts
 init_cjs_shims();
-var import_node_fs21 = require("fs");
-var import_node_path36 = __toESM(require("path"), 1);
-var import_node_crypto = require("crypto");
+var import_node_fs22 = require("fs");
+var import_node_path37 = __toESM(require("path"), 1);
+var import_node_crypto3 = require("crypto");
 var DEFAULT_LIMIT = 10;
 var NOMIC_DIM = 768;
 var MINI_LM_DIM = 384;
@@ -5320,7 +5536,7 @@ function embedText(node) {
   return parts.join(" ");
 }
 function attrsHash(node) {
-  return (0, import_node_crypto.createHash)("sha1").update(embedText(node)).digest("hex").slice(0, 16);
+  return (0, import_node_crypto3.createHash)("sha1").update(embedText(node)).digest("hex").slice(0, 16);
 }
 function cosine(a, b) {
   if (a.length !== b.length) return 0;
@@ -5409,7 +5625,7 @@ async function pickEmbedder() {
 }
 async function readCache(cachePath) {
   try {
-    const raw = await import_node_fs21.promises.readFile(cachePath, "utf8");
+    const raw = await import_node_fs22.promises.readFile(cachePath, "utf8");
     const parsed = JSON.parse(raw);
     if (parsed.version !== 1) return null;
     return parsed;
@@ -5418,8 +5634,8 @@ async function readCache(cachePath) {
   }
 }
 async function writeCache(cachePath, cache) {
-  await import_node_fs21.promises.mkdir(import_node_path36.default.dirname(cachePath), { recursive: true });
-  await import_node_fs21.promises.writeFile(cachePath, JSON.stringify(cache));
+  await import_node_fs22.promises.mkdir(import_node_path37.default.dirname(cachePath), { recursive: true });
+  await import_node_fs22.promises.writeFile(cachePath, JSON.stringify(cache));
 }
 var VectorIndex = class {
   constructor(embedder, cachePath) {
@@ -5574,8 +5790,8 @@ var ALL_PHASES = [
 ];
 function classifyChange(relPath) {
   const phases = /* @__PURE__ */ new Set();
-  const base = import_node_path37.default.basename(relPath).toLowerCase();
-  const segments = relPath.split(import_node_path37.default.sep).map((s) => s.toLowerCase());
+  const base = import_node_path38.default.basename(relPath).toLowerCase();
+  const segments = relPath.split(import_node_path38.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");
@@ -5670,16 +5886,16 @@ function countWatchableDirs(scanPath, limit) {
     if (count >= limit) return;
     let entries;
     try {
-      entries = import_node_fs22.default.readdirSync(dir, { withFileTypes: true });
+      entries = import_node_fs23.default.readdirSync(dir, { withFileTypes: true });
     } catch {
       return;
     }
     for (const e of entries) {
       if (count >= limit) return;
       if (!e.isDirectory()) continue;
-      if (IGNORED_WATCH_PATHS.some((re) => re.test(import_node_path37.default.join(dir, e.name) + import_node_path37.default.sep))) continue;
+      if (IGNORED_WATCH_PATHS.some((re) => re.test(import_node_path38.default.join(dir, e.name) + import_node_path38.default.sep))) continue;
       count++;
-      if (depth < 2) visit(import_node_path37.default.join(dir, e.name), depth + 1);
+      if (depth < 2) visit(import_node_path38.default.join(dir, e.name), depth + 1);
     }
   };
   visit(scanPath, 0);
@@ -5697,8 +5913,8 @@ async function startWatch(graph, opts) {
   const projectName = opts.project ?? DEFAULT_PROJECT;
   await loadGraphFromDisk(graph, opts.outPath);
   const detachEventBus = attachGraphToEventBus(graph, { project: projectName });
-  const policyFilePath = import_node_path37.default.join(opts.scanPath, "policy.json");
-  const policyViolationsPath = import_node_path37.default.join(import_node_path37.default.dirname(opts.outPath), "policy-violations.ndjson");
+  const policyFilePath = import_node_path38.default.join(opts.scanPath, "policy.json");
+  const policyViolationsPath = import_node_path38.default.join(import_node_path38.default.dirname(opts.outPath), "policy-violations.ndjson");
   let policies = [];
   try {
     policies = await loadPolicyFile(policyFilePath);
@@ -5747,7 +5963,7 @@ async function startWatch(graph, opts) {
   const host = opts.host ?? "0.0.0.0";
   const port = opts.port ?? 8080;
   const otelPort = opts.otelPort ?? 4318;
-  const cachePath = opts.embeddingsCachePath ?? import_node_path37.default.join(import_node_path37.default.dirname(opts.outPath), "embeddings.json");
+  const cachePath = opts.embeddingsCachePath ?? import_node_path38.default.join(import_node_path38.default.dirname(opts.outPath), "embeddings.json");
   let searchIndex;
   try {
     searchIndex = await buildSearchIndex(graph, { cachePath });
@@ -5765,7 +5981,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_path37.default.dirname(opts.outPath)),
+      ...pathsForProject(projectName, import_node_path38.default.dirname(opts.outPath)),
       snapshotPath: opts.outPath,
       errorsPath: opts.errorsPath,
       staleEventsPath: opts.staleEventsPath
@@ -5850,9 +6066,9 @@ async function startWatch(graph, opts) {
   };
   const onPath = (absPath) => {
     if (shouldIgnore(absPath)) return;
-    const rel = import_node_path37.default.relative(opts.scanPath, absPath);
+    const rel = import_node_path38.default.relative(opts.scanPath, absPath);
     if (!rel || rel.startsWith("..")) return;
-    pendingPaths.add(rel.split(import_node_path37.default.sep).join("/"));
+    pendingPaths.add(rel.split(import_node_path38.default.sep).join("/"));
     const phases = classifyChange(rel);
     if (phases.size === 0) {
       for (const p of ALL_PHASES) pending.add(p);
@@ -5904,13 +6120,158 @@ async function startWatch(graph, opts) {
   return { api, stop };
 }
 
+// src/deploy/detect.ts
+init_cjs_shims();
+var import_node_fs24 = require("fs");
+var import_node_path39 = __toESM(require("path"), 1);
+var import_node_child_process = require("child_process");
+var import_node_crypto4 = require("crypto");
+function generateToken() {
+  return (0, import_node_crypto4.randomBytes)(32).toString("base64url");
+}
+async function probeBinary(binary, arg) {
+  return new Promise((resolve) => {
+    const child = (0, import_node_child_process.spawn)(binary, [arg], { stdio: "ignore" });
+    const timer = setTimeout(() => {
+      child.kill("SIGKILL");
+      resolve(false);
+    }, 2e3);
+    child.once("error", () => {
+      clearTimeout(timer);
+      resolve(false);
+    });
+    child.once("exit", (code) => {
+      clearTimeout(timer);
+      resolve(code === 0);
+    });
+  });
+}
+async function detectSubstrate(opts = {}) {
+  const hasDocker = opts.hasDocker ?? (() => probeBinary("docker", "version"));
+  const hasSystemd = opts.hasSystemd ?? (() => probeBinary("systemctl", "--version"));
+  if (await hasDocker()) return "docker-compose";
+  if (await hasSystemd()) return "systemd";
+  return "docker-run";
+}
+var IMAGE = "ghcr.io/neat-technologies/neat:latest";
+function emitDockerCompose(cwd) {
+  return [
+    "services:",
+    "  neat:",
+    `    image: ${IMAGE}`,
+    "    restart: unless-stopped",
+    "    environment:",
+    "      NEAT_AUTH_TOKEN: ${NEAT_AUTH_TOKEN:?NEAT_AUTH_TOKEN must be set}",
+    "    ports:",
+    '      - "8080:8080"',
+    '      - "4318:4318"',
+    '      - "6328:6328"',
+    "    volumes:",
+    `      - ${cwd}:/workspace`,
+    "      - ./neat-data:/neat-out",
+    ""
+  ].join("\n");
+}
+function emitSystemdUnit(cwd) {
+  return [
+    "# NEAT_AUTH_TOKEN is read from /etc/neat/neatd.env at startup.",
+    "# Put `NEAT_AUTH_TOKEN=<value>` in that file with mode 0640 root:root.",
+    "[Unit]",
+    "Description=NEAT daemon",
+    "After=network-online.target",
+    "Wants=network-online.target",
+    "",
+    "[Service]",
+    "Type=simple",
+    "ExecStart=/usr/local/bin/neatd start --foreground",
+    `WorkingDirectory=${cwd}`,
+    "EnvironmentFile=/etc/neat/neatd.env",
+    "Restart=always",
+    "RestartSec=5",
+    "",
+    "[Install]",
+    "WantedBy=multi-user.target",
+    ""
+  ].join("\n");
+}
+function emitDockerRunSnippet() {
+  return [
+    "#!/usr/bin/env bash",
+    "set -euo pipefail",
+    "",
+    "# Generate a fresh token once, then store it where your secrets live.",
+    ': "${NEAT_AUTH_TOKEN:?NEAT_AUTH_TOKEN must be set}"',
+    "",
+    `docker run -d --name neat \\`,
+    '  -e NEAT_AUTH_TOKEN="$NEAT_AUTH_TOKEN" \\',
+    "  -p 8080:8080 -p 4318:4318 -p 6328:6328 \\",
+    '  -v "$PWD":/workspace -v /var/lib/neat:/neat-out \\',
+    `  ${IMAGE}`,
+    ""
+  ].join("\n");
+}
+function renderOtelEnvBlock2(token, host = "<host>") {
+  return [
+    `OTEL_EXPORTER_OTLP_ENDPOINT=https://${host}:4318`,
+    `OTEL_EXPORTER_OTLP_HEADERS=Authorization=Bearer ${token}`,
+    "OTEL_SERVICE_NAME=<service>"
+  ].join("\n");
+}
+async function runDeploy(opts = {}) {
+  const cwd = opts.cwd ?? process.cwd();
+  const substrate = await detectSubstrate(opts);
+  const token = generateToken();
+  switch (substrate) {
+    case "docker-compose": {
+      const artifactPath = import_node_path39.default.join(cwd, "docker-compose.neat.yml");
+      const contents = emitDockerCompose(cwd);
+      await import_node_fs24.promises.writeFile(artifactPath, contents, "utf8");
+      return {
+        substrate,
+        artifactPath,
+        token,
+        contents,
+        startCommand: `NEAT_AUTH_TOKEN=${token} docker compose -f ${import_node_path39.default.basename(artifactPath)} up -d`
+      };
+    }
+    case "systemd": {
+      const artifactPath = import_node_path39.default.join(cwd, "neat.service");
+      const contents = emitSystemdUnit(cwd);
+      await import_node_fs24.promises.writeFile(artifactPath, contents, "utf8");
+      return {
+        substrate,
+        artifactPath,
+        token,
+        contents,
+        startCommand: [
+          `sudo install -m 0640 -o root -g root <(echo NEAT_AUTH_TOKEN=${token}) /etc/neat/neatd.env`,
+          `sudo install -m 0644 neat.service /etc/systemd/system/neat.service`,
+          "sudo systemctl daemon-reload && sudo systemctl enable --now neat"
+        ].join(" && ")
+      };
+    }
+    case "docker-run":
+    default: {
+      const contents = emitDockerRunSnippet();
+      return {
+        substrate: "docker-run",
+        token,
+        contents,
+        startCommand: `NEAT_AUTH_TOKEN=${token} bash <(cat <<'EOF'
+${contents}EOF
+)`
+      };
+    }
+  }
+}
+
 // src/installers/index.ts
 init_cjs_shims();
 
 // src/installers/javascript.ts
 init_cjs_shims();
-var import_node_fs23 = require("fs");
-var import_node_path38 = __toESM(require("path"), 1);
+var import_node_fs25 = require("fs");
+var import_node_path40 = __toESM(require("path"), 1);
 
 // src/installers/templates.ts
 init_cjs_shims();
@@ -5958,6 +6319,57 @@ function renderEnvNeat(serviceName) {
     ""
   ].join("\n");
 }
+var NEXT_INSTRUMENTATION_HEADER = "// Generated by `neat init --apply` (ADR-073). Next.js instrumentation hook.";
+var NEXT_INSTRUMENTATION_TS = `${NEXT_INSTRUMENTATION_HEADER}
+export async function register() {
+  if (process.env.NEXT_RUNTIME === 'nodejs') {
+    await import('./instrumentation.node')
+  }
+}
+`;
+var NEXT_INSTRUMENTATION_JS = `${NEXT_INSTRUMENTATION_HEADER}
+export async function register() {
+  if (process.env.NEXT_RUNTIME === 'nodejs') {
+    await import('./instrumentation.node')
+  }
+}
+`;
+var NEXT_INSTRUMENTATION_NODE_TS = `${NEXT_INSTRUMENTATION_HEADER}
+// Loads .env.neat (OTEL_SERVICE_NAME, OTEL_EXPORTER_OTLP_ENDPOINT) before
+// the OTel SDK starts so the exporter target and service name are in scope.
+import { fileURLToPath } from 'node:url'
+import path from 'node:path'
+import dotenv from 'dotenv'
+import { NodeSDK } from '@opentelemetry/sdk-node'
+import { getNodeAutoInstrumentations } from '@opentelemetry/auto-instrumentations-node'
+
+const here = path.dirname(fileURLToPath(import.meta.url))
+dotenv.config({ path: path.join(here, '.env.neat') })
+
+const sdk = new NodeSDK({
+  serviceName: process.env.OTEL_SERVICE_NAME,
+  instrumentations: [getNodeAutoInstrumentations()],
+})
+sdk.start()
+`;
+var NEXT_INSTRUMENTATION_NODE_JS = `${NEXT_INSTRUMENTATION_HEADER}
+// Loads .env.neat (OTEL_SERVICE_NAME, OTEL_EXPORTER_OTLP_ENDPOINT) before
+// the OTel SDK starts so the exporter target and service name are in scope.
+import { fileURLToPath } from 'node:url'
+import path from 'node:path'
+import dotenv from 'dotenv'
+import { NodeSDK } from '@opentelemetry/sdk-node'
+import { getNodeAutoInstrumentations } from '@opentelemetry/auto-instrumentations-node'
+
+const here = path.dirname(fileURLToPath(import.meta.url))
+dotenv.config({ path: path.join(here, '.env.neat') })
+
+const sdk = new NodeSDK({
+  serviceName: process.env.OTEL_SERVICE_NAME,
+  instrumentations: [getNodeAutoInstrumentations()],
+})
+sdk.start()
+`;
 
 // src/installers/javascript.ts
 var SDK_PACKAGES = [
@@ -5980,7 +6392,7 @@ var OTEL_ENV = {
 };
 async function readPackageJson(serviceDir) {
   try {
-    const raw = await import_node_fs23.promises.readFile(import_node_path38.default.join(serviceDir, "package.json"), "utf8");
+    const raw = await import_node_fs25.promises.readFile(import_node_path40.default.join(serviceDir, "package.json"), "utf8");
     return JSON.parse(raw);
   } catch {
     return null;
@@ -5988,7 +6400,7 @@ async function readPackageJson(serviceDir) {
 }
 async function exists2(p) {
   try {
-    await import_node_fs23.promises.stat(p);
+    await import_node_fs25.promises.stat(p);
     return true;
   } catch {
     return false;
@@ -5998,10 +6410,73 @@ async function detect(serviceDir) {
   const pkg = await readPackageJson(serviceDir);
   return pkg !== null && typeof pkg.name === "string";
 }
-var INDEX_CANDIDATES = ["index.ts", "index.tsx", "index.js", "index.mjs", "index.cjs"];
+var NEXT_CONFIG_CANDIDATES = ["next.config.js", "next.config.ts", "next.config.mjs"];
+async function findNextConfig(serviceDir) {
+  for (const name of NEXT_CONFIG_CANDIDATES) {
+    const candidate = import_node_path40.default.join(serviceDir, name);
+    if (await exists2(candidate)) return candidate;
+  }
+  return null;
+}
+function hasNextDependency(pkg) {
+  return pkg.dependencies?.next !== void 0 || pkg.devDependencies?.next !== void 0;
+}
+function parseNextMajor(range) {
+  if (!range) return null;
+  const cleaned = range.trim().replace(/^[\^~>=<\s]+/, "");
+  const match = cleaned.match(/^(\d+)/);
+  if (!match) return null;
+  const n = Number(match[1]);
+  return Number.isFinite(n) ? n : null;
+}
+async function isTypeScriptProject(serviceDir) {
+  return exists2(import_node_path40.default.join(serviceDir, "tsconfig.json"));
+}
+var INDEX_EXTENSIONS = [".ts", ".tsx", ".js", ".mjs", ".cjs"];
+var INDEX_CANDIDATES = INDEX_EXTENSIONS.map((ext) => `index${ext}`);
+var SRC_INDEX_CANDIDATES = INDEX_EXTENSIONS.map((ext) => `src/index${ext}`);
+var SRC_NAMED_CANDIDATES = ["server", "main", "app"].flatMap(
+  (name) => INDEX_EXTENSIONS.map((ext) => `src/${name}${ext}`)
+);
+var SCRIPT_LAUNCHERS = /* @__PURE__ */ new Set([
+  "node",
+  "ts-node",
+  "tsx",
+  "ts-node-dev",
+  "nodemon",
+  "npx",
+  "pnpm",
+  "yarn",
+  "npm",
+  "cross-env",
+  "dotenv",
+  "--"
+]);
+function looksLikeEntryPath(token) {
+  if (token.length === 0) return false;
+  if (token.startsWith("-")) return false;
+  if (token.includes("=")) return false;
+  if (token.includes("/")) return true;
+  return /\.(?:m?[jt]sx?|c[jt]s)$/.test(token);
+}
+function scriptHasShellChain(script) {
+  return /(?:&&|\|\||;|\|(?!\|))/.test(script);
+}
+function entryFromScript(script) {
+  if (!script) return void 0;
+  if (scriptHasShellChain(script)) return void 0;
+  const tokens = script.split(/\s+/).filter((t) => t.length > 0);
+  for (const token of tokens) {
+    const lower = token.toLowerCase();
+    if (SCRIPT_LAUNCHERS.has(lower)) continue;
+    const cleaned = token.startsWith("./") ? token.slice(2) : token;
+    if (looksLikeEntryPath(cleaned)) return cleaned;
+  }
+  return void 0;
+}
 async function resolveEntry(serviceDir, pkg) {
   if (typeof pkg.main === "string" && pkg.main.length > 0) {
-    const candidate = import_node_path38.default.resolve(serviceDir, pkg.main);
+    const candidate = import_node_path40.default.resolve(serviceDir, pkg.main);
     if (await exists2(candidate)) return candidate;
   }
   if (pkg.bin) {
@@ -6015,18 +6490,36 @@ async function resolveEntry(serviceDir, pkg) {
       if (typeof first === "string") binEntry = first;
     }
     if (binEntry) {
-      const candidate = import_node_path38.default.resolve(serviceDir, binEntry);
+      const candidate = import_node_path40.default.resolve(serviceDir, binEntry);
       if (await exists2(candidate)) return candidate;
     }
   }
+  const startEntry = entryFromScript(pkg.scripts?.start);
+  if (startEntry) {
+    const candidate = import_node_path40.default.resolve(serviceDir, startEntry);
+    if (await exists2(candidate)) return candidate;
+  }
+  const devEntry = entryFromScript(pkg.scripts?.dev);
+  if (devEntry) {
+    const candidate = import_node_path40.default.resolve(serviceDir, devEntry);
+    if (await exists2(candidate)) return candidate;
+  }
+  for (const rel of SRC_INDEX_CANDIDATES) {
+    const candidate = import_node_path40.default.join(serviceDir, rel);
+    if (await exists2(candidate)) return candidate;
+  }
+  for (const rel of SRC_NAMED_CANDIDATES) {
+    const candidate = import_node_path40.default.join(serviceDir, rel);
+    if (await exists2(candidate)) return candidate;
+  }
   for (const name of INDEX_CANDIDATES) {
-    const candidate = import_node_path38.default.join(serviceDir, name);
+    const candidate = import_node_path40.default.join(serviceDir, name);
     if (await exists2(candidate)) return candidate;
   }
   return null;
 }
 function dispatchEntry(entryFile, pkg) {
-  const ext = import_node_path38.default.extname(entryFile).toLowerCase();
+  const ext = import_node_path40.default.extname(entryFile).toLowerCase();
   if (ext === ".ts" || ext === ".tsx") return "ts";
   if (ext === ".mjs") return "esm";
   if (ext === ".cjs") return "cjs";
@@ -6043,9 +6536,9 @@ function otelInitContents(flavor) {
   return OTEL_INIT_CJS;
 }
 function injectionLine(flavor, entryFile, otelInitFile) {
-  let rel = import_node_path38.default.relative(import_node_path38.default.dirname(entryFile), otelInitFile);
+  let rel = import_node_path40.default.relative(import_node_path40.default.dirname(entryFile), otelInitFile);
   if (!rel.startsWith(".")) rel = `./${rel}`;
-  rel = rel.split(import_node_path38.default.sep).join("/");
+  rel = rel.split(import_node_path40.default.sep).join("/");
   if (flavor === "cjs") return `require('${rel}')`;
   if (flavor === "esm") return `import '${rel}'`;
   const tsRel = rel.replace(/\.ts$/, "");
@@ -6056,9 +6549,88 @@ function lineIsOtelInjection(line) {
   if (trimmed.length === 0) return false;
   return /(?:require\(|import\s+)['"]\.\/otel-init[^'"]*['"]/.test(trimmed);
 }
+async function planNext(serviceDir, pkg, manifestPath, nextConfigPath) {
+  const useTs = await isTypeScriptProject(serviceDir);
+  const instrumentationFile = import_node_path40.default.join(serviceDir, useTs ? "instrumentation.ts" : "instrumentation.js");
+  const instrumentationNodeFile = import_node_path40.default.join(
+    serviceDir,
+    useTs ? "instrumentation.node.ts" : "instrumentation.node.js"
+  );
+  const envNeatFile = import_node_path40.default.join(serviceDir, ".env.neat");
+  const existingDeps = { ...pkg.dependencies ?? {}, ...pkg.devDependencies ?? {} };
+  const dependencyEdits = [];
+  for (const sdk of SDK_PACKAGES) {
+    if (sdk.name in existingDeps) continue;
+    dependencyEdits.push({
+      file: manifestPath,
+      kind: "add",
+      name: sdk.name,
+      version: sdk.version
+    });
+  }
+  const generatedFiles = [];
+  if (!await exists2(instrumentationFile)) {
+    generatedFiles.push({
+      file: instrumentationFile,
+      contents: useTs ? NEXT_INSTRUMENTATION_TS : NEXT_INSTRUMENTATION_JS,
+      skipIfExists: true
+    });
+  }
+  if (!await exists2(instrumentationNodeFile)) {
+    generatedFiles.push({
+      file: instrumentationNodeFile,
+      contents: useTs ? NEXT_INSTRUMENTATION_NODE_TS : NEXT_INSTRUMENTATION_NODE_JS,
+      skipIfExists: true
+    });
+  }
+  if (!await exists2(envNeatFile)) {
+    generatedFiles.push({
+      file: envNeatFile,
+      contents: renderEnvNeat(pkg.name ?? import_node_path40.default.basename(serviceDir)),
+      skipIfExists: true
+    });
+  }
+  let nextConfigEdit;
+  const nextRange = pkg.dependencies?.next ?? pkg.devDependencies?.next;
+  const nextMajor = parseNextMajor(nextRange);
+  if (nextMajor !== null && nextMajor < 15) {
+    try {
+      const raw = await import_node_fs25.promises.readFile(nextConfigPath, "utf8");
+      if (!raw.includes("instrumentationHook")) {
+        nextConfigEdit = {
+          file: nextConfigPath,
+          reason: `enable experimental.instrumentationHook (Next ${nextMajor} requires the opt-in flag)`
+        };
+      }
+    } catch {
+    }
+  }
+  const empty = dependencyEdits.length === 0 && generatedFiles.length === 0 && nextConfigEdit === void 0;
+  if (empty) {
+    return {
+      language: "javascript",
+      serviceDir,
+      dependencyEdits: [],
+      entrypointEdits: [],
+      envEdits: [],
+      generatedFiles: [],
+      framework: "next"
+    };
+  }
+  return {
+    language: "javascript",
+    serviceDir,
+    dependencyEdits,
+    entrypointEdits: [],
+    envEdits: [OTEL_ENV],
+    generatedFiles,
+    framework: "next",
+    ...nextConfigEdit ? { nextConfigEdit } : {}
+  };
+}
 async function plan(serviceDir) {
   const pkg = await readPackageJson(serviceDir);
-  const manifestPath = import_node_path38.default.join(serviceDir, "package.json");
+  const manifestPath = import_node_path40.default.join(serviceDir, "package.json");
   const empty = {
     language: "javascript",
     serviceDir,
@@ -6068,13 +6640,19 @@ async function plan(serviceDir) {
     generatedFiles: []
   };
   if (!pkg) return empty;
+  if (hasNextDependency(pkg)) {
+    const nextConfig = await findNextConfig(serviceDir);
+    if (nextConfig) {
+      return planNext(serviceDir, pkg, manifestPath, nextConfig);
+    }
+  }
   const entryFile = await resolveEntry(serviceDir, pkg);
   if (!entryFile) {
     return { ...empty, libOnly: true };
   }
   const flavor = dispatchEntry(entryFile, pkg);
-  const otelInitFile = import_node_path38.default.join(import_node_path38.default.dirname(entryFile), otelInitFilename(flavor));
-  const envNeatFile = import_node_path38.default.join(serviceDir, ".env.neat");
+  const otelInitFile = import_node_path40.default.join(import_node_path40.default.dirname(entryFile), otelInitFilename(flavor));
+  const envNeatFile = import_node_path40.default.join(serviceDir, ".env.neat");
   const existingDeps = { ...pkg.dependencies ?? {}, ...pkg.devDependencies ?? {} };
   const dependencyEdits = [];
   for (const sdk of SDK_PACKAGES) {
@@ -6088,7 +6666,7 @@ async function plan(serviceDir) {
   }
   const entrypointEdits = [];
   try {
-    const raw = await import_node_fs23.promises.readFile(entryFile, "utf8");
+    const raw = await import_node_fs25.promises.readFile(entryFile, "utf8");
     const lines = raw.split(/\r?\n/);
     const firstReal = lines[0]?.startsWith("#!") ? lines[1] ?? "" : lines[0] ?? "";
     if (!lineIsOtelInjection(firstReal)) {
@@ -6113,7 +6691,7 @@ async function plan(serviceDir) {
   if (!await exists2(envNeatFile)) {
     generatedFiles.push({
       file: envNeatFile,
-      contents: renderEnvNeat(pkg.name ?? import_node_path38.default.basename(serviceDir)),
+      contents: renderEnvNeat(pkg.name ?? import_node_path40.default.basename(serviceDir)),
       skipIfExists: true
     });
   }
@@ -6132,18 +6710,20 @@ async function plan(serviceDir) {
   };
 }
 function isAllowedWritePath(serviceDir, target) {
-  const rel = import_node_path38.default.relative(serviceDir, target);
+  const rel = import_node_path40.default.relative(serviceDir, target);
   if (rel.startsWith("..")) return false;
-  const base = import_node_path38.default.basename(target);
+  const base = import_node_path40.default.basename(target);
   if (base === "package.json") return true;
   if (base === ".env.neat") return true;
   if (/^otel-init\.(?:js|cjs|mjs|ts)$/.test(base)) return true;
+  if (/^instrumentation(?:\.node)?\.(?:js|cjs|mjs|ts)$/.test(base)) return true;
+  if (/^next\.config\.(?:js|mjs|ts)$/.test(base)) return true;
   return false;
 }
 async function writeAtomic(file, contents) {
   const tmp = `${file}.${process.pid}.${Date.now()}.tmp`;
-  await import_node_fs23.promises.writeFile(tmp, contents, "utf8");
-  await import_node_fs23.promises.rename(tmp, file);
+  await import_node_fs25.promises.writeFile(tmp, contents, "utf8");
+  await import_node_fs25.promises.rename(tmp, file);
 }
 async function apply(installPlan) {
   const { serviceDir } = installPlan;
@@ -6155,7 +6735,7 @@ async function apply(installPlan) {
       writtenFiles: []
     };
   }
-  if (installPlan.dependencyEdits.length === 0 && installPlan.entrypointEdits.length === 0 && (installPlan.generatedFiles?.length ?? 0) === 0) {
+  if (installPlan.dependencyEdits.length === 0 && installPlan.entrypointEdits.length === 0 && (installPlan.generatedFiles?.length ?? 0) === 0 && installPlan.nextConfigEdit === void 0) {
     return {
       serviceDir,
       outcome: "already-instrumented",
@@ -6166,6 +6746,7 @@ async function apply(installPlan) {
   for (const d of installPlan.dependencyEdits) allTargets.add(d.file);
   for (const e of installPlan.entrypointEdits) allTargets.add(e.file);
   for (const g of installPlan.generatedFiles ?? []) allTargets.add(g.file);
+  if (installPlan.nextConfigEdit) allTargets.add(installPlan.nextConfigEdit.file);
   for (const target of allTargets) {
     const isEntryEdit = installPlan.entrypointEdits.some((e) => e.file === target);
     if (isEntryEdit) continue;
@@ -6180,7 +6761,7 @@ async function apply(installPlan) {
   for (const target of allTargets) {
     if (await exists2(target)) {
       try {
-        originals.set(target, await import_node_fs23.promises.readFile(target, "utf8"));
+        originals.set(target, await import_node_fs25.promises.readFile(target, "utf8"));
       } catch {
       }
     }
@@ -6235,6 +6816,17 @@ async function apply(installPlan) {
       await writeAtomic(ep.file, newRaw);
       writtenFiles.push(ep.file);
     }
+    if (installPlan.nextConfigEdit) {
+      const target = installPlan.nextConfigEdit.file;
+      const raw = originals.get(target);
+      if (raw !== void 0 && !raw.includes("instrumentationHook")) {
+        const updated = injectInstrumentationHook(raw);
+        if (updated !== null) {
+          await writeAtomic(target, updated);
+          writtenFiles.push(target);
+        }
+      }
+    }
   } catch (err) {
     await rollback(installPlan, originals, createdFiles);
     throw err;
@@ -6250,14 +6842,14 @@ async function rollback(installPlan, originals, createdFiles) {
   const removed = [];
   for (const [file, raw] of originals.entries()) {
     try {
-      await import_node_fs23.promises.writeFile(file, raw, "utf8");
+      await import_node_fs25.promises.writeFile(file, raw, "utf8");
       restored.push(file);
     } catch {
     }
   }
   for (const file of createdFiles) {
     try {
-      await import_node_fs23.promises.unlink(file);
+      await import_node_fs25.promises.unlink(file);
       removed.push(file);
     } catch {
     }
@@ -6272,8 +6864,26 @@ async function rollback(installPlan, originals, createdFiles) {
     ...removed.map((f) => `removed:  ${f}`),
     ""
   ];
-  const rollbackPath = import_node_path38.default.join(installPlan.serviceDir, "neat-rollback.patch");
-  await import_node_fs23.promises.writeFile(rollbackPath, lines.join("\n"), "utf8");
+  const rollbackPath = import_node_path40.default.join(installPlan.serviceDir, "neat-rollback.patch");
+  await import_node_fs25.promises.writeFile(rollbackPath, lines.join("\n"), "utf8");
+}
+function injectInstrumentationHook(raw) {
+  if (raw.includes("instrumentationHook")) return raw;
+  const anchors = [
+    { pattern: /(module\.exports\s*=\s*\{)/, label: "cjs-default" },
+    { pattern: /(export\s+default\s*\{)/, label: "esm-default" },
+    { pattern: /(?:const|let|var)\s+\w+(?:\s*:\s*[^=]+)?\s*=\s*(\{)/, label: "named-config" }
+  ];
+  for (const { pattern } of anchors) {
+    const match = pattern.exec(raw);
+    if (!match) continue;
+    const insertAfter = match.index + match[0].length;
+    const before = raw.slice(0, insertAfter);
+    const after = raw.slice(insertAfter);
+    const injection = "\n  experimental: { instrumentationHook: true },";
+    return `${before}${injection}${after}`;
+  }
+  return null;
 }
 var javascriptInstaller = {
   name: "javascript",
@@ -6284,8 +6894,8 @@ var javascriptInstaller = {
 
 // src/installers/python.ts
 init_cjs_shims();
-var import_node_fs24 = require("fs");
-var import_node_path39 = __toESM(require("path"), 1);
+var import_node_fs26 = require("fs");
+var import_node_path41 = __toESM(require("path"), 1);
 var SDK_PACKAGES2 = [
   { name: "opentelemetry-distro", version: ">=0.49b0" },
   { name: "opentelemetry-exporter-otlp", version: ">=1.28.0" }
@@ -6297,7 +6907,7 @@ var OTEL_ENV2 = {
 };
 async function exists3(p) {
   try {
-    await import_node_fs24.promises.stat(p);
+    await import_node_fs26.promises.stat(p);
     return true;
   } catch {
     return false;
@@ -6306,7 +6916,7 @@ async function exists3(p) {
 async function detect2(serviceDir) {
   const markers = ["requirements.txt", "pyproject.toml", "setup.py"];
   for (const m of markers) {
-    if (await exists3(import_node_path39.default.join(serviceDir, m))) return true;
+    if (await exists3(import_node_path41.default.join(serviceDir, m))) return true;
   }
   return false;
 }
@@ -6316,9 +6926,9 @@ function reqPackageName(line) {
   return head.replace(/[<>=!~].*$/, "").toLowerCase();
 }
 async function planRequirementsTxtEdits(serviceDir) {
-  const file = import_node_path39.default.join(serviceDir, "requirements.txt");
+  const file = import_node_path41.default.join(serviceDir, "requirements.txt");
   if (!await exists3(file)) return null;
-  const raw = await import_node_fs24.promises.readFile(file, "utf8");
+  const raw = await import_node_fs26.promises.readFile(file, "utf8");
   const presentNames = new Set(
     raw.split(/\r?\n/).map(reqPackageName).filter((n) => n.length > 0)
   );
@@ -6326,9 +6936,9 @@ async function planRequirementsTxtEdits(serviceDir) {
   return { manifest: file, missing: [...missing] };
 }
 async function planProcfileEdits(serviceDir) {
-  const procfile = import_node_path39.default.join(serviceDir, "Procfile");
+  const procfile = import_node_path41.default.join(serviceDir, "Procfile");
   if (!await exists3(procfile)) return [];
-  const raw = await import_node_fs24.promises.readFile(procfile, "utf8");
+  const raw = await import_node_fs26.promises.readFile(procfile, "utf8");
   const edits = [];
   for (const line of raw.split(/\r?\n/)) {
     if (line.length === 0) continue;
@@ -6380,8 +6990,8 @@ async function applyRequirementsTxt(manifest, edits, original) {
   const next = `${original}${trailing}${newlines.join("\n")}
 `;
   const tmp = `${manifest}.${process.pid}.${Date.now()}.tmp`;
-  await import_node_fs24.promises.writeFile(tmp, next, "utf8");
-  await import_node_fs24.promises.rename(tmp, manifest);
+  await import_node_fs26.promises.writeFile(tmp, next, "utf8");
+  await import_node_fs26.promises.rename(tmp, manifest);
 }
 async function applyProcfile(procfile, edits, original) {
   let next = original;
@@ -6390,8 +7000,8 @@ async function applyProcfile(procfile, edits, original) {
     next = next.replace(e.before, e.after);
   }
   const tmp = `${procfile}.${process.pid}.${Date.now()}.tmp`;
-  await import_node_fs24.promises.writeFile(tmp, next, "utf8");
-  await import_node_fs24.promises.rename(tmp, procfile);
+  await import_node_fs26.promises.writeFile(tmp, next, "utf8");
+  await import_node_fs26.promises.rename(tmp, procfile);
 }
 async function apply2(installPlan) {
   const { serviceDir } = installPlan;
@@ -6404,7 +7014,7 @@ async function apply2(installPlan) {
   const originals = /* @__PURE__ */ new Map();
   for (const file of touched) {
     try {
-      originals.set(file, await import_node_fs24.promises.readFile(file, "utf8"));
+      originals.set(file, await import_node_fs26.promises.readFile(file, "utf8"));
     } catch {
     }
   }
@@ -6415,7 +7025,7 @@ async function apply2(installPlan) {
       if (raw === void 0) {
         throw new Error(`python installer: cannot read ${file} during apply`);
       }
-      const base = import_node_path39.default.basename(file);
+      const base = import_node_path41.default.basename(file);
       if (base === "requirements.txt") {
         const edits = installPlan.dependencyEdits.filter((e) => e.file === file);
         if (edits.length > 0) {
@@ -6440,7 +7050,7 @@ async function rollback2(installPlan, originals) {
   const restored = [];
   for (const [file, raw] of originals.entries()) {
     try {
-      await import_node_fs24.promises.writeFile(file, raw, "utf8");
+      await import_node_fs26.promises.writeFile(file, raw, "utf8");
       restored.push(file);
     } catch {
     }
@@ -6454,8 +7064,8 @@ async function rollback2(installPlan, originals) {
     ...restored.map((f) => `restored: ${f}`),
     ""
   ];
-  const rollbackPath = import_node_path39.default.join(installPlan.serviceDir, "neat-rollback.patch");
-  await import_node_fs24.promises.writeFile(rollbackPath, lines.join("\n"), "utf8");
+  const rollbackPath = import_node_path41.default.join(installPlan.serviceDir, "neat-rollback.patch");
+  await import_node_fs26.promises.writeFile(rollbackPath, lines.join("\n"), "utf8");
 }
 var pythonInstaller = {
   name: "python",
@@ -6467,7 +7077,7 @@ var pythonInstaller = {
 // src/installers/shared.ts
 init_cjs_shims();
 function isEmptyPlan(plan3) {
-  return plan3.dependencyEdits.length === 0 && plan3.entrypointEdits.length === 0 && plan3.envEdits.length === 0 && (plan3.generatedFiles?.length ?? 0) === 0;
+  return plan3.dependencyEdits.length === 0 && plan3.entrypointEdits.length === 0 && plan3.envEdits.length === 0 && (plan3.generatedFiles?.length ?? 0) === 0 && plan3.nextConfigEdit === void 0;
 }
 
 // src/installers/index.ts
@@ -6566,16 +7176,231 @@ function renderPatch(sections) {
       }
       lines.push("");
     }
+    if (plan3.nextConfigEdit) {
+      lines.push("### next.config (framework flag)");
+      lines.push(`--- ${plan3.nextConfigEdit.file}`);
+      lines.push(`+ experimental: { instrumentationHook: true }, // ${plan3.nextConfigEdit.reason}`);
+      lines.push("");
+    }
   }
   return lines.join("\n");
 }
 
+// src/orchestrator.ts
+init_cjs_shims();
+var import_node_fs27 = require("fs");
+var import_node_http = __toESM(require("http"), 1);
+var import_node_path42 = __toESM(require("path"), 1);
+var import_node_child_process2 = require("child_process");
+var import_node_readline = __toESM(require("readline"), 1);
+async function promptYesNo(question) {
+  const rl = import_node_readline.default.createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise((resolve) => {
+    rl.question(`${question} [Y/n] `, (answer) => {
+      rl.close();
+      const trimmed = answer.trim().toLowerCase();
+      resolve(trimmed === "" || trimmed === "y" || trimmed === "yes");
+    });
+  });
+}
+var DEFAULT_DAEMON_READY_TIMEOUT_MS = 15e3;
+async function checkDaemonHealth(restPort) {
+  return new Promise((resolve) => {
+    const req = import_node_http.default.get(`http://127.0.0.1:${restPort}/health`, (res) => {
+      const ok = res.statusCode !== void 0 && res.statusCode >= 200 && res.statusCode < 300;
+      res.resume();
+      resolve(ok);
+    });
+    req.on("error", () => resolve(false));
+    req.setTimeout(1e3, () => {
+      req.destroy();
+      resolve(false);
+    });
+  });
+}
+async function waitForDaemonReady(restPort, timeoutMs) {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    if (await checkDaemonHealth(restPort)) return true;
+    await new Promise((r) => setTimeout(r, 300));
+  }
+  return false;
+}
+function spawnDaemonDetached() {
+  const here = import_node_path42.default.dirname(new URL(importMetaUrl).pathname);
+  const candidates = [
+    import_node_path42.default.join(here, "neatd.cjs"),
+    import_node_path42.default.join(here, "neatd.js")
+  ];
+  let entry2 = null;
+  const fsSync = require("fs");
+  for (const c of candidates) {
+    try {
+      fsSync.accessSync(c);
+      entry2 = c;
+      break;
+    } catch {
+    }
+  }
+  if (!entry2) {
+    throw new Error(`orchestrator: cannot locate neatd entry in ${here}`);
+  }
+  const child = (0, import_node_child_process2.spawn)(process.execPath, [entry2, "start"], {
+    detached: true,
+    stdio: "ignore",
+    env: process.env
+  });
+  child.unref();
+}
+function openBrowser(url) {
+  if (!process.stdout.isTTY) return "failed";
+  const platform = process.platform;
+  const cmd = platform === "darwin" ? "open" : platform === "win32" ? "cmd" : "xdg-open";
+  const args = platform === "win32" ? ["/c", "start", "", url] : [url];
+  try {
+    const child = (0, import_node_child_process2.spawn)(cmd, args, { detached: true, stdio: "ignore" });
+    child.on("error", () => {
+    });
+    child.unref();
+    return "opened";
+  } catch {
+    return "failed";
+  }
+}
+async function runOrchestrator(opts) {
+  const result = {
+    exitCode: 0,
+    steps: {
+      discovery: { services: 0, languages: [] },
+      extraction: { nodesAdded: 0, edgesAdded: 0 },
+      gitignore: "unchanged",
+      apply: { instrumented: 0, alreadyInstrumented: 0, libOnly: 0, skipped: false },
+      daemon: "skipped",
+      browser: "skipped"
+    }
+  };
+  const stat = await import_node_fs27.promises.stat(opts.scanPath).catch(() => null);
+  if (!stat || !stat.isDirectory()) {
+    console.error(`neat: ${opts.scanPath} is not a directory`);
+    result.exitCode = 2;
+    return result;
+  }
+  console.log(`neat: ${opts.scanPath}`);
+  console.log("");
+  const services = await discoverServices(opts.scanPath);
+  const languages = [...new Set(services.map((s) => s.node.language))].sort();
+  result.steps.discovery = { services: services.length, languages };
+  console.log(`discovered ${services.length} service(s) across ${languages.length} language(s)`);
+  let runApply = !opts.noInstrument;
+  if (runApply && !opts.yes && process.stdout.isTTY && process.stdin.isTTY) {
+    runApply = await promptYesNo("instrument your services and open the dashboard?");
+  }
+  const graphKey = opts.projectExplicit ? opts.project : DEFAULT_PROJECT;
+  resetGraph(graphKey);
+  const graph = getGraph(graphKey);
+  const projectPaths = pathsForProject(graphKey, import_node_path42.default.join(opts.scanPath, "neat-out"));
+  const errorsPath = projectPaths.errorsPath;
+  const extraction = await extractFromDirectory(graph, opts.scanPath, { errorsPath });
+  await saveGraphToDisk(graph, projectPaths.snapshotPath);
+  result.steps.extraction = {
+    nodesAdded: extraction.nodesAdded,
+    edgesAdded: extraction.edgesAdded
+  };
+  const gi = await ensureNeatOutIgnored(opts.scanPath);
+  result.steps.gitignore = gi.action;
+  if (gi.action !== "unchanged") {
+    console.log(`${gi.action} .gitignore (neat-out/)`);
+  }
+  try {
+    await addProject({
+      name: opts.project,
+      path: opts.scanPath,
+      languages,
+      status: "active"
+    });
+  } catch (err) {
+    if (!(err instanceof ProjectNameCollisionError)) throw err;
+    console.error(`neat: ${err.message}`);
+    console.error("pass --project <other-name> to register under a different name.");
+    result.exitCode = 1;
+    return result;
+  }
+  if (!runApply) {
+    result.steps.apply.skipped = true;
+    console.log("skipped instrumentation (--no-instrument)");
+  } else {
+    let instrumented = 0;
+    let already = 0;
+    let libOnly = 0;
+    for (const svc of services) {
+      const installer = await pickInstaller(svc.dir);
+      if (!installer) continue;
+      const plan3 = await installer.plan(svc.dir);
+      if (isEmptyPlan(plan3) && !plan3.libOnly) {
+        already++;
+        continue;
+      }
+      const outcome = await installer.apply(plan3);
+      if (outcome.outcome === "instrumented") instrumented++;
+      else if (outcome.outcome === "already-instrumented") already++;
+      else if (outcome.outcome === "lib-only") libOnly++;
+    }
+    result.steps.apply = { instrumented, alreadyInstrumented: already, libOnly, skipped: false };
+    console.log(`instrumented ${instrumented}, already ${already}, lib-only ${libOnly}`);
+  }
+  const restPort = Number(process.env.PORT ?? 8080);
+  const timeoutMs = opts.daemonReadyTimeoutMs ?? DEFAULT_DAEMON_READY_TIMEOUT_MS;
+  if (await checkDaemonHealth(restPort)) {
+    result.steps.daemon = "already-running";
+  } else {
+    try {
+      spawnDaemonDetached();
+    } catch (err) {
+      console.error(`neat: daemon spawn failed \u2014 ${err.message}`);
+      result.exitCode = 1;
+      return result;
+    }
+    const ready = await waitForDaemonReady(restPort, timeoutMs);
+    result.steps.daemon = ready ? "spawned" : "timed-out";
+    if (!ready) {
+      console.error(`neat: daemon did not become ready within ${timeoutMs}ms`);
+      result.exitCode = 1;
+      return result;
+    }
+  }
+  const dashboardUrl = opts.dashboardUrl ?? "http://localhost:6328";
+  if (opts.noOpen || !process.stdout.isTTY) {
+    result.steps.browser = "skipped";
+  } else {
+    result.steps.browser = openBrowser(dashboardUrl);
+  }
+  printSummary(result, graph, dashboardUrl);
+  return result;
+}
+function printSummary(result, graph, dashboardUrl) {
+  const nodes = [];
+  graph.forEachNode((_id, attrs) => nodes.push(attrs));
+  const edges = [];
+  graph.forEachEdge((_id, attrs) => edges.push(attrs));
+  const byNode = /* @__PURE__ */ new Map();
+  for (const n of nodes) byNode.set(n.type, (byNode.get(n.type) ?? 0) + 1);
+  const byEdge = /* @__PURE__ */ new Map();
+  for (const e of edges) byEdge.set(e.type, (byEdge.get(e.type) ?? 0) + 1);
+  console.log("");
+  console.log("=== summary ===");
+  console.log(`graph: ${graph.order} nodes, ${graph.size} edges`);
+  for (const [t, c] of [...byNode.entries()].sort()) console.log(`  ${t}: ${c}`);
+  for (const [t, c] of [...byEdge.entries()].sort()) console.log(`  ${t}: ${c}`);
+  console.log("");
+  console.log(`dashboard: ${dashboardUrl}`);
+}
+
 // src/cli.ts
-var import_types24 = require("@neat.is/types");
+var import_types25 = require("@neat.is/types");
 
 // src/cli-client.ts
 init_cjs_shims();
-var import_types23 = require("@neat.is/types");
+var import_types24 = require("@neat.is/types");
 var HttpError = class extends Error {
   constructor(status2, message, responseBody = "") {
     super(message);
@@ -6595,10 +7420,10 @@ var TransportError = class extends Error {
 function createHttpClient(baseUrl) {
   const root = baseUrl.replace(/\/$/, "");
   return {
-    async get(path41) {
+    async get(path44) {
       let res;
       try {
-        res = await fetch(`${root}${path41}`);
+        res = await fetch(`${root}${path44}`);
       } catch (err) {
         throw new TransportError(
           `cannot reach neat-core at ${root}: ${err.message}`
@@ -6608,16 +7433,16 @@ function createHttpClient(baseUrl) {
         const body = await res.text().catch(() => "");
         throw new HttpError(
           res.status,
-          `${res.status} ${res.statusText} on GET ${path41}: ${body}`,
+          `${res.status} ${res.statusText} on GET ${path44}: ${body}`,
           body
         );
       }
       return await res.json();
     },
-    async post(path41, body) {
+    async post(path44, body) {
       let res;
       try {
-        res = await fetch(`${root}${path41}`, {
+        res = await fetch(`${root}${path44}`, {
           method: "POST",
           headers: { "content-type": "application/json" },
           body: JSON.stringify(body)
@@ -6631,7 +7456,7 @@ function createHttpClient(baseUrl) {
         const text = await res.text().catch(() => "");
         throw new HttpError(
           res.status,
-          `${res.status} ${res.statusText} on POST ${path41}: ${text}`,
+          `${res.status} ${res.statusText} on POST ${path44}: ${text}`,
           text
         );
       }
@@ -6645,12 +7470,12 @@ function projectPath(project, suffix) {
 }
 async function runRootCause(client, input) {
   const qs = input.errorId ? `?errorId=${encodeURIComponent(input.errorId)}` : "";
-  const path41 = projectPath(
+  const path44 = projectPath(
     input.project,
     `/graph/root-cause/${encodeURIComponent(input.errorNode)}${qs}`
   );
   try {
-    const result = await client.get(path41);
+    const result = await client.get(path44);
     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}.` : "");
@@ -6676,12 +7501,12 @@ async function runRootCause(client, input) {
 }
 async function runBlastRadius(client, input) {
   const qs = input.depth !== void 0 ? `?depth=${input.depth}` : "";
-  const path41 = projectPath(
+  const path44 = projectPath(
     input.project,
     `/graph/blast-radius/${encodeURIComponent(input.nodeId)}${qs}`
   );
   try {
-    const result = await client.get(path41);
+    const result = await client.get(path44);
     if (result.totalAffected === 0) {
       return {
         summary: `${result.origin} has no downstream dependencies. Nothing else would break if it failed.`
@@ -6710,17 +7535,17 @@ async function runBlastRadius(client, input) {
   }
 }
 function formatBlastEntry(n) {
-  const tag = n.edgeProvenance === import_types23.Provenance.STALE ? " [STALE \u2014 last seen too long ago]" : "";
+  const tag = n.edgeProvenance === import_types24.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 path41 = projectPath(
+  const path44 = projectPath(
     input.project,
     `/graph/dependencies/${encodeURIComponent(input.nodeId)}?depth=${depth}`
   );
   try {
-    const result = await client.get(path41);
+    const result = await client.get(path44);
     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}).`
@@ -6756,9 +7581,9 @@ async function runObservedDependencies(client, input) {
     const edges = await client.get(
       projectPath(input.project, `/graph/edges/${encodeURIComponent(input.nodeId)}`)
     );
-    const observed = edges.outbound.filter((e) => e.provenance === import_types23.Provenance.OBSERVED);
+    const observed = edges.outbound.filter((e) => e.provenance === import_types24.Provenance.OBSERVED);
     if (observed.length === 0) {
-      const hasExtracted = edges.outbound.some((e) => e.provenance === import_types23.Provenance.EXTRACTED);
+      const hasExtracted = edges.outbound.some((e) => e.provenance === import_types24.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}` };
     }
@@ -6766,7 +7591,7 @@ async function runObservedDependencies(client, input) {
     return {
       summary: `${input.nodeId} has ${observed.length} runtime dependenc${observed.length === 1 ? "y" : "ies"} confirmed by OTel.`,
       block: blockLines.join("\n"),
-      provenance: import_types23.Provenance.OBSERVED
+      provenance: import_types24.Provenance.OBSERVED
     };
   } catch (err) {
     if (err instanceof HttpError && err.status === 404) {
@@ -6801,9 +7626,9 @@ function formatDuration(ms) {
   return `${Math.round(h / 24)}d`;
 }
 async function runIncidents(client, input) {
-  const path41 = input.nodeId ? projectPath(input.project, `/incidents/${encodeURIComponent(input.nodeId)}`) : projectPath(input.project, "/incidents");
+  const path44 = input.nodeId ? projectPath(input.project, `/incidents/${encodeURIComponent(input.nodeId)}`) : projectPath(input.project, "/incidents");
   try {
-    const body = await client.get(path41);
+    const body = await client.get(path44);
     const events = body.events;
     if (events.length === 0) {
       return {
@@ -6820,7 +7645,7 @@ async function runIncidents(client, input) {
     return {
       summary: `${target} has ${body.total} recorded incident${body.total === 1 ? "" : "s"}; showing the ${ordered.length} most recent.`,
       block: blockLines.join("\n"),
-      provenance: import_types23.Provenance.OBSERVED
+      provenance: import_types24.Provenance.OBSERVED
     };
   } catch (err) {
     if (err instanceof HttpError && err.status === 404) {
@@ -6929,7 +7754,7 @@ async function runStaleEdges(client, input) {
   return {
     summary: `${events.length} stale-edge transition${events.length === 1 ? "" : "s"} recorded${input.edgeType ? ` for ${input.edgeType}` : ""}.`,
     block: blockLines.join("\n"),
-    provenance: import_types23.Provenance.STALE
+    provenance: import_types24.Provenance.STALE
   };
 }
 async function runPolicies(client, input) {
@@ -7095,6 +7920,9 @@ function usage() {
   console.log("                 Flags:");
   console.log("                   --print-config   print the JSON snippet to stdout");
   console.log("                   --apply          merge mcpServers.neat into ~/.claude.json");
+  console.log("  deploy         Detect the deploy substrate, generate NEAT_AUTH_TOKEN,");
+  console.log("                 emit a docker-compose / systemd / docker run artifact, and");
+  console.log("                 print the OTel env-vars block to paste into your platform.");
   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.");
@@ -7157,6 +7985,10 @@ function parseArgs(rest) {
     apply: false,
     dryRun: false,
     noInstall: false,
+    noInstrument: false,
+    noOpen: false,
+    yes: false,
+    verbose: false,
     printConfig: false,
     json: false,
     depth: null,
@@ -7185,6 +8017,22 @@ function parseArgs(rest) {
       out.noInstall = true;
       continue;
     }
+    if (arg === "--no-instrument") {
+      out.noInstrument = true;
+      continue;
+    }
+    if (arg === "--no-open") {
+      out.noOpen = true;
+      continue;
+    }
+    if (arg === "--yes" || arg === "-y") {
+      out.yes = true;
+      continue;
+    }
+    if (arg === "--verbose" || arg === "-v") {
+      out.verbose = true;
+      continue;
+    }
     if (arg === "--print-config") {
       out.printConfig = true;
       continue;
@@ -7240,34 +8088,6 @@ function assignFlag(out, field, value) {
   ;
   out[field] = value;
 }
-function summarise(nodes, edges) {
-  const byNode = /* @__PURE__ */ new Map();
-  for (const n of nodes) byNode.set(n.type, (byNode.get(n.type) ?? 0) + 1);
-  const byEdge = /* @__PURE__ */ new Map();
-  for (const e of edges) byEdge.set(e.type, (byEdge.get(e.type) ?? 0) + 1);
-  const nodeLines = [...byNode.entries()].sort((a, b) => a[0].localeCompare(b[0])).map(([t, c]) => `    ${t}: ${c}`);
-  const edgeLines = [...byEdge.entries()].sort((a, b) => a[0].localeCompare(b[0])).map(([t, c]) => `    ${t}: ${c}`);
-  return ["nodes:", ...nodeLines, "edges:", ...edgeLines].join("\n");
-}
-function formatIncompat(inc) {
-  if (inc.kind === "node-engine") {
-    const range = inc.declaredNodeEngine ? ` (engines.node="${inc.declaredNodeEngine}")` : "";
-    return `${inc.package}@${inc.packageVersion ?? "?"} requires Node ${inc.requiredNodeVersion}${range} \u2014 ${inc.reason}`;
-  }
-  if (inc.kind === "package-conflict") {
-    const found = inc.foundVersion ? `@${inc.foundVersion}` : " (missing)";
-    return `${inc.package}@${inc.packageVersion ?? "?"} requires ${inc.requires.name}>=${inc.requires.minVersion}; found ${inc.requires.name}${found} \u2014 ${inc.reason}`;
-  }
-  if (inc.kind === "deprecated-api") {
-    return `${inc.package}@${inc.packageVersion ?? "?"} is deprecated \u2014 ${inc.reason}`;
-  }
-  return `${inc.driver}@${inc.driverVersion} vs ${inc.engine} ${inc.engineVersion} \u2014 ${inc.reason}`;
-}
-function findIncompatibilities(nodes) {
-  return nodes.filter(
-    (n) => n.type === "ServiceNode" && Array.isArray(n.incompatibilities) && (n.incompatibilities ?? []).length > 0
-  );
-}
 function printBanner() {
   console.log("\u2588\u2588\u2588\u2557   \u2588\u2588\u2557\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2557 \u2588\u2588\u2588\u2588\u2588\u2557 \u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2557");
   console.log("\u2588\u2588\u2588\u2588\u2557  \u2588\u2588\u2551\u2588\u2588\u2554\u2550\u2550\u2550\u2550\u255D\u2588\u2588\u2554\u2550\u2550\u2588\u2588\u2557\u255A\u2550\u2550\u2588\u2588\u2554\u2550\u2550\u255D");
@@ -7318,7 +8138,7 @@ async function buildPatchSections(services) {
 }
 async function runInit(opts) {
   const written = [];
-  const stat = await import_node_fs25.promises.stat(opts.scanPath).catch(() => null);
+  const stat = await import_node_fs28.promises.stat(opts.scanPath).catch(() => null);
   if (!stat || !stat.isDirectory()) {
     console.error(`neat init: ${opts.scanPath} is not a directory`);
     return { exitCode: 2, writtenFiles: written };
@@ -7327,11 +8147,15 @@ async function runInit(opts) {
   printDiscoveryReport(opts, services);
   const sections = opts.noInstall ? [] : await buildPatchSections(services);
   const patch = renderPatch(sections);
-  const patchPath = import_node_path40.default.join(opts.scanPath, "neat.patch");
+  const patchPath = import_node_path43.default.join(opts.scanPath, "neat.patch");
   if (opts.dryRun) {
-    await import_node_fs25.promises.writeFile(patchPath, patch, "utf8");
+    await import_node_fs28.promises.writeFile(patchPath, patch, "utf8");
     written.push(patchPath);
     console.log(`dry-run: patch written to ${patchPath}`);
+    const gitignorePath = import_node_path43.default.join(opts.scanPath, ".gitignore");
+    const gitignoreExists = await import_node_fs28.promises.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.");
     return { exitCode: 0, writtenFiles: written };
   }
@@ -7340,12 +8164,16 @@ async function runInit(opts) {
   const graph = getGraph(graphKey);
   const projectPaths = pathsForProject(
     graphKey,
-    import_node_path40.default.join(opts.scanPath, "neat-out")
+    import_node_path43.default.join(opts.scanPath, "neat-out")
   );
-  const errorsPath = import_node_path40.default.join(import_node_path40.default.dirname(opts.outPath), import_node_path40.default.basename(projectPaths.errorsPath));
+  const errorsPath = import_node_path43.default.join(import_node_path43.default.dirname(opts.outPath), import_node_path43.default.basename(projectPaths.errorsPath));
   const result = await extractFromDirectory(graph, opts.scanPath, { errorsPath });
   await saveGraphToDisk(graph, opts.outPath);
   written.push(opts.outPath);
+  const gitignoreResult = await ensureNeatOutIgnored(opts.scanPath);
+  if (gitignoreResult.action !== "unchanged") {
+    written.push(gitignoreResult.file);
+  }
   const languages = [...new Set(services.map((s) => s.node.language))].sort();
   try {
     await addProject({
@@ -7388,35 +8216,27 @@ async function runInit(opts) {
         console.log("Run `npm install` (or your language equivalent) to refresh lockfiles.");
       }
     } else {
-      await import_node_fs25.promises.writeFile(patchPath, patch, "utf8");
+      await import_node_fs28.promises.writeFile(patchPath, patch, "utf8");
       written.push(patchPath);
     }
   }
-  const nodes = [];
-  graph.forEachNode((_id, attrs) => nodes.push(attrs));
-  const edges = [];
-  graph.forEachEdge((_id, attrs) => edges.push(attrs));
   console.log("");
-  console.log("=== neat init: summary ===");
   console.log(`snapshot: ${opts.outPath}`);
   console.log(`added: ${result.nodesAdded} nodes, ${result.edgesAdded} edges`);
-  console.log(`total:  ${graph.order} nodes, ${graph.size} edges`);
-  console.log(summarise(nodes, edges));
+  console.log("");
+  const divergenceResult = computeDivergences(graph);
+  console.log(
+    renderValueForwardSummary({
+      graph,
+      divergences: divergenceResult.divergences,
+      verbose: opts.verbose
+    })
+  );
   console.log(formatExtractionBanner(result.extractionErrors));
   if (result.extractionErrors > 0) {
     console.log(`errors:   ${errorsPath}`);
   }
   console.log(formatPrecisionFloorBanner(result.extractedDropped));
-  const incompatibilities = findIncompatibilities(nodes);
-  if (incompatibilities.length > 0) {
-    console.log("");
-    console.log(`incompatibilities found in ${incompatibilities.length} service(s):`);
-    for (const svc of incompatibilities) {
-      for (const inc of svc.incompatibilities ?? []) {
-        console.log(`  ${svc.name}: ${formatIncompat(inc)}`);
-      }
-    }
-  }
   if (result.extractionErrors > 0 && isStrictExtractionEnabled()) {
     return { exitCode: 4, writtenFiles: written };
   }
@@ -7436,9 +8256,9 @@ var CLAUDE_SKILL_CONFIG = {
 };
 function claudeConfigPath() {
   const override = process.env.NEAT_CLAUDE_CONFIG;
-  if (override && override.length > 0) return import_node_path40.default.resolve(override);
+  if (override && override.length > 0) return import_node_path43.default.resolve(override);
   const home = process.env.HOME ?? process.env.USERPROFILE ?? "";
-  return import_node_path40.default.join(home, ".claude.json");
+  return import_node_path43.default.join(home, ".claude.json");
 }
 async function runSkill(opts) {
   const snippet2 = JSON.stringify(CLAUDE_SKILL_CONFIG, null, 2) + "\n";
@@ -7450,7 +8270,7 @@ async function runSkill(opts) {
     const target = claudeConfigPath();
     let existing = {};
     try {
-      existing = JSON.parse(await import_node_fs25.promises.readFile(target, "utf8"));
+      existing = JSON.parse(await import_node_fs28.promises.readFile(target, "utf8"));
     } catch (err) {
       if (err.code !== "ENOENT") {
         console.error(`neat skill: failed to read ${target} \u2014 ${err.message}`);
@@ -7462,8 +8282,8 @@ async function runSkill(opts) {
       ...existing,
       mcpServers: { ...mcp, neat: CLAUDE_SKILL_CONFIG.mcpServers.neat }
     };
-    await import_node_fs25.promises.mkdir(import_node_path40.default.dirname(target), { recursive: true });
-    await import_node_fs25.promises.writeFile(target, JSON.stringify(merged, null, 2) + "\n", "utf8");
+    await import_node_fs28.promises.mkdir(import_node_path43.default.dirname(target), { recursive: true });
+    await import_node_fs28.promises.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.");
     return { exitCode: 0 };
@@ -7497,12 +8317,12 @@ async function main() {
       console.error("neat init: --apply and --dry-run are mutually exclusive");
       process.exit(2);
     }
-    const scanPath = import_node_path40.default.resolve(target);
+    const scanPath = import_node_path43.default.resolve(target);
     const projectExplicit = parsed.project !== null;
-    const projectName = projectExplicit ? project : import_node_path40.default.basename(scanPath);
+    const projectName = projectExplicit ? project : import_node_path43.default.basename(scanPath);
     const projectKey = projectExplicit ? project : DEFAULT_PROJECT;
-    const fallback = pathsForProject(projectKey, import_node_path40.default.join(scanPath, "neat-out")).snapshotPath;
-    const outPath = import_node_path40.default.resolve(process.env.NEAT_OUT_PATH ?? fallback);
+    const fallback = pathsForProject(projectKey, import_node_path43.default.join(scanPath, "neat-out")).snapshotPath;
+    const outPath = import_node_path43.default.resolve(process.env.NEAT_OUT_PATH ?? fallback);
     const result = await runInit({
       scanPath,
       outPath,
@@ -7510,7 +8330,8 @@ async function main() {
       projectExplicit,
       apply: apply3,
       dryRun,
-      noInstall
+      noInstall,
+      verbose: parsed.verbose
     });
     if (result.exitCode !== 0) process.exit(result.exitCode);
     return;
@@ -7522,21 +8343,21 @@ async function main() {
       usage();
       process.exit(2);
     }
-    const scanPath = import_node_path40.default.resolve(target);
-    const stat = await import_node_fs25.promises.stat(scanPath).catch(() => null);
+    const scanPath = import_node_path43.default.resolve(target);
+    const stat = await import_node_fs28.promises.stat(scanPath).catch(() => null);
     if (!stat || !stat.isDirectory()) {
       console.error(`neat watch: ${scanPath} is not a directory`);
       process.exit(2);
     }
-    const projectPaths = pathsForProject(project, import_node_path40.default.join(scanPath, "neat-out"));
-    const outPath = import_node_path40.default.resolve(process.env.NEAT_OUT_PATH ?? projectPaths.snapshotPath);
-    const errorsPath = import_node_path40.default.resolve(
-      process.env.NEAT_ERRORS_PATH ?? import_node_path40.default.join(import_node_path40.default.dirname(outPath), import_node_path40.default.basename(projectPaths.errorsPath))
+    const projectPaths = pathsForProject(project, import_node_path43.default.join(scanPath, "neat-out"));
+    const outPath = import_node_path43.default.resolve(process.env.NEAT_OUT_PATH ?? projectPaths.snapshotPath);
+    const errorsPath = import_node_path43.default.resolve(
+      process.env.NEAT_ERRORS_PATH ?? import_node_path43.default.join(import_node_path43.default.dirname(outPath), import_node_path43.default.basename(projectPaths.errorsPath))
     );
-    const staleEventsPath = import_node_path40.default.resolve(
-      process.env.NEAT_STALE_EVENTS_PATH ?? import_node_path40.default.join(import_node_path40.default.dirname(outPath), import_node_path40.default.basename(projectPaths.staleEventsPath))
+    const staleEventsPath = import_node_path43.default.resolve(
+      process.env.NEAT_STALE_EVENTS_PATH ?? import_node_path43.default.join(import_node_path43.default.dirname(outPath), import_node_path43.default.basename(projectPaths.staleEventsPath))
     );
-    const embeddingsCachePath = process.env.NEAT_EMBEDDINGS_CACHE_PATH ? import_node_path40.default.resolve(process.env.NEAT_EMBEDDINGS_CACHE_PATH) : void 0;
+    const embeddingsCachePath = process.env.NEAT_EMBEDDINGS_CACHE_PATH ? import_node_path43.default.resolve(process.env.NEAT_EMBEDDINGS_CACHE_PATH) : void 0;
     const handle = await startWatch(getGraph(project), {
       scanPath,
       outPath,
@@ -7629,15 +8450,62 @@ async function main() {
     console.log("note: neat-out/, policy.json, and other files at the project path were left in place.");
     return;
   }
+  if (cmd === "deploy") {
+    const artifact = await runDeploy();
+    const block = renderOtelEnvBlock2(artifact.token);
+    console.log();
+    console.log(`Substrate detected: ${artifact.substrate}`);
+    if (artifact.artifactPath) {
+      console.log(`Artifact written:   ${artifact.artifactPath}`);
+    } else {
+      console.log("No on-disk artifact \u2014 copy the snippet below into your substrate.");
+      console.log();
+      console.log(artifact.contents);
+    }
+    console.log();
+    console.log("NEAT_AUTH_TOKEN (store this \u2014 it will not be printed again):");
+    console.log(`  ${artifact.token}`);
+    console.log();
+    console.log("For your application's deploy platform, set these env vars:");
+    console.log(block.split("\n").map((l) => `  ${l}`).join("\n"));
+    console.log();
+    console.log("Once NEAT is running, your dashboard will be at:");
+    console.log("  https://<host>:6328");
+    console.log();
+    console.log("To start NEAT, run:");
+    console.log(`  ${artifact.startCommand}`);
+    return;
+  }
   if (QUERY_VERBS.has(cmd)) {
     const code = await runQueryVerb(cmd, parsed);
     if (code !== 0) process.exit(code);
     return;
   }
+  const orchestratorCode = await tryOrchestrator(cmd, parsed);
+  if (orchestratorCode !== null) {
+    if (orchestratorCode !== 0) process.exit(orchestratorCode);
+    return;
+  }
   console.error(`neat: unknown command "${cmd}"`);
   usage();
   process.exit(1);
 }
+async function tryOrchestrator(cmd, parsed) {
+  const scanPath = import_node_path43.default.resolve(cmd);
+  const stat = await import_node_fs28.promises.stat(scanPath).catch(() => null);
+  if (!stat || !stat.isDirectory()) return null;
+  const projectExplicit = parsed.project !== null;
+  const projectName = projectExplicit ? parsed.project : import_node_path43.default.basename(scanPath);
+  const result = await runOrchestrator({
+    scanPath,
+    project: projectName,
+    projectExplicit,
+    noInstrument: parsed.noInstrument,
+    noOpen: parsed.noOpen,
+    yes: parsed.yes
+  });
+  return result.exitCode;
+}
 var QUERY_VERBS = /* @__PURE__ */ new Set([
   "root-cause",
   "blast-radius",
@@ -7777,10 +8645,10 @@ async function runQueryVerb(cmd, parsed) {
         const parts = parsed.type.split(",").map((s) => s.trim()).filter((s) => s.length > 0);
         const out = [];
         for (const p of parts) {
-          const r = import_types24.DivergenceTypeSchema.safeParse(p);
+          const r = import_types25.DivergenceTypeSchema.safeParse(p);
           if (!r.success) {
             console.error(
-              `neat divergences: unknown --type "${p}". allowed: ${import_types24.DivergenceTypeSchema.options.join(", ")}`
+              `neat divergences: unknown --type "${p}". allowed: ${import_types25.DivergenceTypeSchema.options.join(", ")}`
             );
             return 2;
           }