@neat.is/core 0.10.6-dev.20261007 → 0.10.6-dev.20261008

package/dist/cli.cjs

@@ -6724,7 +6724,29 @@ function ensureFrontierNode(graph, host, ts) {
   graph.addNode(id, node);
   return id;
 }
-function upsertObservedEdge(graph, type, source, target, ts, isError = false, evidence, durationMs) {
+var EDGE_ERROR_MESSAGE_MAX = 512;
+function buildEdgeErrorExemplar(detail, ts) {
+  return {
+    ...detail.exceptionType !== void 0 ? { exceptionType: detail.exceptionType } : {},
+    ...detail.message !== void 0 ? { message: detail.message.slice(0, EDGE_ERROR_MESSAGE_MAX) } : {},
+    ...detail.httpStatusCode !== void 0 ? { httpStatusCode: detail.httpStatusCode } : {},
+    at: ts
+  };
+}
+function edgeErrorDetailFromSpan(span) {
+  const exceptionType = span.exception?.type;
+  const message = span.exception?.message;
+  const httpStatusCode = httpResponseStatus(span);
+  if (exceptionType === void 0 && message === void 0 && httpStatusCode === void 0) {
+    return void 0;
+  }
+  return {
+    ...exceptionType !== void 0 ? { exceptionType } : {},
+    ...message !== void 0 ? { message } : {},
+    ...httpStatusCode !== void 0 ? { httpStatusCode } : {}
+  };
+}
+function upsertObservedEdge(graph, type, source, target, ts, isError = false, evidence, durationMs, errorDetail) {
   if (!graph.hasNode(source) || !graph.hasNode(target)) return null;
   const grain = source.startsWith("file:") || source.startsWith("symbol:") ? "file" : "service";
   const id = makeObservedEdgeId(type, source, target);
@@ -6734,13 +6756,15 @@ function upsertObservedEdge(graph, type, source, target, ts, isError = false, ev
     const newErrorCount = (existing.signal?.errorCount ?? 0) + (isError ? 1 : 0);
     const latencyHist2 = durationMs !== void 0 ? recordLatency({ ...existing.signal?.latencyHist ?? {} }, durationMs) : existing.signal?.latencyHist;
     const latencyMs2 = latencyPercentiles(latencyHist2) ?? existing.signal?.latencyMs;
+    const lastError2 = isError && errorDetail ? buildEdgeErrorExemplar(errorDetail, ts) : existing.signal?.lastError;
     const newSignal = {
       spanCount: newSpanCount,
       errorCount: newErrorCount,
       lastObservedAgeMs: 0,
       ...latencyHist2 ? { latencyHist: latencyHist2 } : {},
       ...latencyMs2 ? { latencyMs: latencyMs2 } : {},
-      ...existing.signal?.anomalous !== void 0 ? { anomalous: existing.signal.anomalous } : {}
+      ...existing.signal?.anomalous !== void 0 ? { anomalous: existing.signal.anomalous } : {},
+      ...lastError2 ? { lastError: lastError2 } : {}
     };
     const updated = {
       ...existing,
@@ -6757,12 +6781,14 @@ function upsertObservedEdge(graph, type, source, target, ts, isError = false, ev
   }
   const latencyHist = durationMs !== void 0 ? recordLatency({}, durationMs) : void 0;
   const latencyMs = latencyHist ? latencyPercentiles(latencyHist) : void 0;
+  const lastError = isError && errorDetail ? buildEdgeErrorExemplar(errorDetail, ts) : void 0;
   const signal = {
     spanCount: 1,
     errorCount: isError ? 1 : 0,
     lastObservedAgeMs: 0,
     ...latencyHist ? { latencyHist } : {},
-    ...latencyMs ? { latencyMs } : {}
+    ...latencyMs ? { latencyMs } : {},
+    ...lastError ? { lastError } : {}
   };
   const edge = {
     id,
@@ -7103,6 +7129,7 @@ async function handleSpan(ctx, span) {
   const sourceId = ensureServiceNode(ctx.graph, span.service, env);
   const isError = spanRecordsError(span);
   const durationMs = span.durationNanos > 0n && !spanIsStreaming(span) ? Number(span.durationNanos) / 1e6 : void 0;
+  const errorDetail = isError ? edgeErrorDetailFromSpan(span) : void 0;
   const sourceServiceNode = ctx.graph.getNodeAttributes(sourceId);
   const callSite = callSiteFromSpan(span, sourceServiceNode, ctx.scanPath);
   cacheSpanService(span, nowMs, callSite);
@@ -7142,7 +7169,8 @@ async function handleSpan(ctx, span) {
         ts,
         isError,
         callSiteEvidence,
-        durationMs
+        durationMs,
+        errorDetail
       );
       if (result) affectedNode = targetId;
       if (span.dbSystem === "mongodb" && span.dbCollection) {
@@ -7155,7 +7183,8 @@ async function handleSpan(ctx, span) {
           ts,
           isError,
           callSiteEvidence,
-          durationMs
+          durationMs,
+          errorDetail
         );
       }
       if (span.dbTable) {
@@ -7168,7 +7197,8 @@ async function handleSpan(ctx, span) {
           ts,
           isError,
           callSiteEvidence,
-          durationMs
+          durationMs,
+          errorDetail
         );
         mergeObservedColumns(ctx.graph, tableId, span.dbColumns);
       }
@@ -7188,7 +7218,8 @@ async function handleSpan(ctx, span) {
       ts,
       isError,
       callSiteEvidence,
-      durationMs
+      durationMs,
+      errorDetail
     );
     if (result) affectedNode = targetId;
   } else if (span.graphqlOperationName && span.graphqlOperationType && spanServesGraphqlOperation(span.kind)) {
@@ -7206,7 +7237,8 @@ async function handleSpan(ctx, span) {
       ts,
       isError,
       callSiteEvidence,
-      durationMs
+      durationMs,
+      errorDetail
     );
     if (result) affectedNode = targetId;
   } else if (span.rpcSystem === "grpc" && span.rpcService && span.rpcMethod && spanServesGrpcMethod(span.kind)) {
@@ -7219,7 +7251,8 @@ async function handleSpan(ctx, span) {
       ts,
       isError,
       callSiteEvidence,
-      durationMs
+      durationMs,
+      errorDetail
     );
     if (result) affectedNode = targetId;
   } else if (span.websocketChannel && spanServesWebsocketChannel(span.kind)) {
@@ -7236,7 +7269,8 @@ async function handleSpan(ctx, span) {
       ts,
       isError,
       callSiteEvidence,
-      durationMs
+      durationMs,
+      errorDetail
     );
     if (result) affectedNode = targetId;
   } else {
@@ -7253,7 +7287,8 @@ async function handleSpan(ctx, span) {
           ts,
           isError,
           callSiteEvidence,
-          durationMs
+          durationMs,
+          errorDetail
         );
         affectedNode = targetId;
         resolvedViaAddress = true;
@@ -7267,7 +7302,8 @@ async function handleSpan(ctx, span) {
           ts,
           isError,
           callSiteEvidence,
-          durationMs
+          durationMs,
+          errorDetail
         );
         affectedNode = frontierNodeId;
         resolvedViaAddress = true;
@@ -7294,7 +7330,8 @@ async function handleSpan(ctx, span) {
           ts,
           isError,
           fallbackEvidence,
-          durationMs
+          durationMs,
+          errorDetail
         );
       }
     }
@@ -7309,7 +7346,7 @@ async function handleSpan(ctx, span) {
     );
     if (routeNodeId) {
       const routeSvc = ctx.graph.getNodeAttributes(routeNodeId).service;
-      upsertObservedEdge(ctx.graph, import_types9.EdgeType.CONTAINS, (0, import_types9.serviceId)(routeSvc), routeNodeId, ts, isError, void 0, durationMs);
+      upsertObservedEdge(ctx.graph, import_types9.EdgeType.CONTAINS, (0, import_types9.serviceId)(routeSvc), routeNodeId, ts, isError, void 0, durationMs, errorDetail);
     }
   }
   if (span.statusCode === 2) {
@@ -17226,6 +17263,11 @@ function detectObservedFailingEdge(graph, bucket) {
       spanCount,
       errorCount,
       errorRate: clampConfidence(errorRate),
+      // The bounded last-error exemplar rides the finding as evidence (ADR-236):
+      // the error rate says HOW MUCH is failing, the exemplar says WHAT failed —
+      // a timeout vs a deadlock vs a connection-refused, which `errorCount`
+      // alone cannot name. Present only when the observed edge carries one.
+      ...signal.lastError ? { lastError: signal.lastError } : {},
       confidence: OBSERVED_FAILING_CONFIDENCE,
       reason: `Code declares ${bucket.source} \u2192 ${bucket.target} (${bucket.type}) and production observes it, but ${errorCount}/${spanCount} observed calls fail (${pct}% error rate) \u2014 the declared dependency is predominantly failing. The declared intent (EXTRACTED) and the observed behaviour (OBSERVED) diverge.`,
       recommendation: "Treat this as a broken declared dependency, not a coverage gap: production runs the call the code declares and most calls error. Check the dependency\u2019s health, recent deploys, and the observed error responses on this edge."
@@ -17726,11 +17768,20 @@ ${NEAT_OUT_LINE}
 // src/summary.ts
 init_cjs_shims();
 var import_types62 = require("@neat.is/types");
+
+// src/otlp-headers.ts
+init_cjs_shims();
+var OTLP_BEARER_PREFIX = "Authorization=Bearer%20";
+function otlpBearerHeader(token) {
+  return OTLP_BEARER_PREFIX + encodeURIComponent(token);
+}
+
+// src/summary.ts
 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>"
+    `  OTEL_EXPORTER_OTLP_HEADERS=${OTLP_BEARER_PREFIX}<NEAT_AUTH_TOKEN>`
   ].join("\n");
 }
 function findIncompatServices(nodes) {
@@ -20327,7 +20378,7 @@ async function computePrVerdict(req, ctx, deps, deadline) {
       const found = observedBreakFrom(node, getObservedDependencies(ctx.liveGraph, node.id));
       if (found) observedBreaks.push(found);
     }
-    const { marker, body } = renderVerdict({
+    const { marker, body: rendered } = renderVerdict({
       graph: head,
       delta,
       changedFiles,
@@ -20335,6 +20386,7 @@ async function computePrVerdict(req, ctx, deps, deadline) {
       observedBreaks,
       tone: req.tone ?? "loud"
     });
+    const body = rendered.startsWith(marker) ? rendered.slice(marker.length).replace(/^(?:\r?\n)+/, "") : rendered;
     return {
       marker,
       body,
@@ -26147,13 +26199,25 @@ async function makeTransformersEmbedder() {
     }
   };
 }
-async function pickEmbedder() {
-  const host = ollamaHost();
-  if (host && await ollamaReachable(host)) {
-    return makeOllamaEmbedder(host);
+async function pickEmbedder(provider) {
+  if (provider !== "transformers") {
+    const host = ollamaHost();
+    if (host && await ollamaReachable(host)) {
+      return makeOllamaEmbedder(host);
+    }
   }
+  if (provider === "ollama") return null;
   return makeTransformersEmbedder();
 }
+function searchProviderFromEnv(env = process.env, warn2 = console.warn) {
+  const value = env.NEAT_SEARCH_PROVIDER;
+  if (!value) return void 0;
+  if (value === "substring" || value === "ollama" || value === "transformers") return value;
+  warn2(
+    `semantic_search: NEAT_SEARCH_PROVIDER="${value}" is not substring, ollama, or transformers; using automatic selection`
+  );
+  return void 0;
+}
 async function readCache(cachePath) {
   try {
     const raw = await import_node_fs49.promises.readFile(cachePath, "utf8");
@@ -26317,7 +26381,8 @@ async function buildSearchIndex(graph, options = {}) {
   if (options.embedder) {
     embedder = options.embedder;
   } else if (options.forceProvider !== "substring") {
-    const factory = options.embedderFactory ?? pickEmbedder;
+    const forcedProvider = options.forceProvider;
+    const factory = options.embedderFactory ?? (() => pickEmbedder(forcedProvider));
     embedder = await resolveEmbedderBounded(
       factory,
       options.initTimeoutMs ?? searchInitTimeoutMs()
@@ -26596,9 +26661,10 @@ async function startWatch(graph, opts) {
   const port = opts.port ?? 8080;
   const otelPort = opts.otelPort ?? 4318;
   const cachePath = opts.embeddingsCachePath ?? import_node_path86.default.join(import_node_path86.default.dirname(opts.outPath), "embeddings.json");
+  const forceProvider = searchProviderFromEnv();
   let searchIndex;
   try {
-    searchIndex = await buildSearchIndex(graph, { cachePath });
+    searchIndex = await buildSearchIndex(graph, { cachePath, forceProvider });
     console.log(`semantic_search: ${searchIndex.provider} provider`);
   } catch (err) {
     console.warn(
@@ -26882,7 +26948,7 @@ function emitDockerRunSnippet() {
 function renderOtelEnvBlock2(token, host = "<host>") {
   return [
     `OTEL_EXPORTER_OTLP_ENDPOINT=https://${host}:4318`,
-    `OTEL_EXPORTER_OTLP_HEADERS=Authorization=Bearer ${token}`,
+    `OTEL_EXPORTER_OTLP_HEADERS=${otlpBearerHeader(token)}`,
     "OTEL_SERVICE_NAME=<service>"
   ].join("\n");
 }
@@ -26947,7 +27013,7 @@ var import_semver2 = __toESM(require("semver"), 1);
 init_cjs_shims();
 var OTEL_INIT_HEADER = "// Generated by `neat init --apply` (ADR-069). OpenTelemetry auto-instrumentation hook.";
 var OTEL_INIT_STAMP = "// neat-template-version: 8 \u2014 CommonJS TypeScript uses a synchronous bootstrap (#910); OTel init degrades to no-OBSERVED when dependencies are absent (#820); daemon.json endpoint resolution (ADR-096) + layered file-first capture (ADR-090).";
-var OTEL_OTLP_HEADERS_JS = "if (process.env.NEAT_OTEL_TOKEN) process.env.OTEL_EXPORTER_OTLP_HEADERS ||= 'Authorization=Bearer ' + process.env.NEAT_OTEL_TOKEN";
+var OTEL_OTLP_HEADERS_JS = "if (process.env.NEAT_OTEL_TOKEN) process.env.OTEL_EXPORTER_OTLP_HEADERS ||= 'Authorization=Bearer%20' + encodeURIComponent(process.env.NEAT_OTEL_TOKEN)";
 var OTEL_OTLP_PROTOCOL_JS = "process.env.OTEL_EXPORTER_OTLP_PROTOCOL ||= 'http/json'";
 var OTEL_ENDPOINT_RESOLVER_CJS = `;(function () {
   try {
@@ -27392,7 +27458,31 @@ ${registrations.join("\n")}
 `;
   return template.replace(/__SERVICE_NAME__/g, serviceName).replace(/__PROJECT__/g, projectName).replace(/__INSTRUMENTATION_BLOCK__\n?/g, block);
 }
-function renderEnvNeat(serviceName, projectName) {
+function renderEnvNeat(serviceName, projectName, nodeOptions, extraInstrumentations = []) {
+  if (nodeOptions) {
+    return [
+      "# Generated by `neat init --apply` / `neat <path>` (ADR-069, ADR-232).",
+      "# NEAT attaches its OpenTelemetry bootstrap at process start; no source is edited.",
+      "# NODE_OPTIONS is read once when the process starts, so load this file before",
+      "# your start command:",
+      "#   set -a; . ./.env.neat; set +a; <your start command>",
+      "# or copy these settings into your process manager / platform environment.",
+      `OTEL_SERVICE_NAME=${serviceName}`,
+      "# The preload sends spans to this project's daemon, read from",
+      "# <project>/neat-out/daemon.json; NEAT_PROJECT names the route when no record",
+      "# is found. Set OTEL_EXPORTER_OTLP_ENDPOINT only to send spans elsewhere.",
+      `NEAT_PROJECT=${projectName}`,
+      "OTEL_EXPORTER_OTLP_PROTOCOL=http/json",
+      "# Set NEAT_OTEL_TOKEN to the daemon's OTLP secret to authenticate exported spans (#410).",
+      "# NEAT_OTEL_TOKEN=",
+      ...extraInstrumentations.length > 0 ? [
+        "# Instrumentations outside the auto bundle, loaded by the preload (<package>#<export>).",
+        `NEAT_OTEL_INSTRUMENTATIONS=${extraInstrumentations.join(",")}`
+      ] : [],
+      `NODE_OPTIONS="${nodeOptions}"`,
+      ""
+    ].join("\n");
+  }
   return [
     "# Generated by `neat init --apply` (ADR-069).",
     `OTEL_SERVICE_NAME=${serviceName}`,
@@ -27588,14 +27678,16 @@ function detectNonBundledInstrumentations(pkg) {
     out.push({
       pkg: "@prisma/instrumentation",
       version: prismaInstrVersion,
-      registration: "instrumentations.push(new (require('@prisma/instrumentation').PrismaInstrumentation)())"
+      registration: "instrumentations.push(new (require('@prisma/instrumentation').PrismaInstrumentation)())",
+      exportName: "PrismaInstrumentation"
     });
   }
   if (getMajor(deps["@nestjs/core"]) >= 11) {
     out.push({
       pkg: "@opentelemetry/instrumentation-nestjs-core",
       version: "^0.67.0",
-      registration: "instrumentations.push(new (require('@opentelemetry/instrumentation-nestjs-core').NestInstrumentation)())"
+      registration: "instrumentations.push(new (require('@opentelemetry/instrumentation-nestjs-core').NestInstrumentation)())",
+      exportName: "NestInstrumentation"
     });
   }
   return out;
@@ -28406,6 +28498,49 @@ async function findFrameworkDispatch(serviceDir, pkg, manifestPath, project) {
   }
   return null;
 }
+var ATTACH_PACKAGE_NAME = "@neat.is/otel-node";
+function attachPackageRange(coreVersion = readPackageVersion()) {
+  return import_semver2.default.valid(coreVersion) ? `^${coreVersion}` : "latest";
+}
+async function planAttachment(serviceDir, pkg, manifestPath, project) {
+  const svcName = serviceNodeName2(pkg, serviceDir);
+  const projectName = projectToken(pkg, serviceDir, project);
+  const envNeatFile = import_node_path88.default.join(serviceDir, ".env.neat");
+  const flag = pkg.type === "module" ? "--import" : "--require";
+  const nodeOptions = `${flag} @neat.is/otel-node/register`;
+  const existingDeps = { ...pkg.dependencies ?? {}, ...pkg.devDependencies ?? {} };
+  const dependencyEdits = [];
+  if (!(ATTACH_PACKAGE_NAME in existingDeps)) {
+    dependencyEdits.push({ file: manifestPath, kind: "add", name: ATTACH_PACKAGE_NAME, version: attachPackageRange() });
+  }
+  const nonBundled = detectNonBundledInstrumentations(pkg);
+  for (const inst of nonBundled) {
+    if (inst.pkg in existingDeps) {
+      if (needsVersionUpgrade(existingDeps[inst.pkg], inst.version)) {
+        dependencyEdits.push({ file: manifestPath, kind: "upgrade", name: inst.pkg, version: inst.version, fromVersion: existingDeps[inst.pkg] });
+      }
+      continue;
+    }
+    dependencyEdits.push({ file: manifestPath, kind: "add", name: inst.pkg, version: inst.version });
+  }
+  const extraInstrumentations = nonBundled.map((i) => `${i.pkg}#${i.exportName}`);
+  const generatedFiles = [];
+  if (!await exists3(envNeatFile)) {
+    generatedFiles.push({
+      file: envNeatFile,
+      contents: renderEnvNeat(svcName, projectName, nodeOptions, extraInstrumentations),
+      skipIfExists: true
+    });
+  }
+  return {
+    language: "javascript",
+    serviceDir,
+    dependencyEdits,
+    entrypointEdits: [],
+    envEdits: [OTEL_ENV],
+    generatedFiles
+  };
+}
 async function plan(serviceDir, opts) {
   const pkg = await readPackageJson2(serviceDir);
   const manifestPath = import_node_path88.default.join(serviceDir, "package.json");
@@ -28431,14 +28566,17 @@ async function plan(serviceDir, opts) {
     if (!entryFile) {
       return { ...empty, libOnly: true };
     }
+    const runtimeKind = await detectRuntimeKind(serviceDir, pkg);
+    if (runtimeKind !== "node") {
+      return { ...empty, runtimeKind };
+    }
+  }
+  if (!opts?.sourceEdit) {
+    return planAttachment(serviceDir, pkg, manifestPath, project);
   }
   if (frameworkDispatch) {
     return frameworkDispatch();
   }
-  const runtimeKind = await detectRuntimeKind(serviceDir, pkg);
-  if (runtimeKind !== "node") {
-    return { ...empty, runtimeKind };
-  }
   if (!entryFile) {
     return { ...empty, libOnly: true };
   }
@@ -28756,6 +28894,7 @@ var SDK_PACKAGES2 = [
   { name: "opentelemetry-distro", version: ">=0.49b0" },
   { name: "opentelemetry-exporter-otlp", version: ">=1.28.0" }
 ];
+var NEAT_OTEL_PACKAGE = { name: "neat-otel", version: ">=0.1.0" };
 var OTEL_ENV2 = {
   file: null,
   key: "OTEL_EXPORTER_OTLP_ENDPOINT",
@@ -28907,34 +29046,37 @@ function reqPackageName(line) {
   const head = stripped.split(/[\s;]/)[0] ?? "";
   return head.replace(/[<>=!~].*$/, "").toLowerCase();
 }
-async function planRequirementsTxtEdits(serviceDir) {
+async function planRequirementsTxtEdits(serviceDir, packages = SDK_PACKAGES2) {
   const file = import_node_path89.default.join(serviceDir, "requirements.txt");
   if (!await exists4(file)) return null;
   const raw = await import_node_fs53.promises.readFile(file, "utf8");
   const presentNames = new Set(
     raw.split(/\r?\n/).map(reqPackageName).filter((n) => n.length > 0)
   );
-  const missing = SDK_PACKAGES2.filter((p) => !presentNames.has(p.name.toLowerCase()));
+  const missing = packages.filter((p) => !presentNames.has(p.name.toLowerCase()));
   return { manifest: file, missing: [...missing] };
 }
-async function planProcfileEdits(serviceDir) {
+var PY_LAUNCHER_PYTHON = /^python3?\b/;
+var PY_LAUNCHERS_BROAD = /^(python3?|uvicorn|gunicorn|hypercorn|daphne|granian|celery|flask|fastapi)\b/;
+async function planProcfileEdits(serviceDir, broad = false) {
   const procfile = import_node_path89.default.join(serviceDir, "Procfile");
   if (!await exists4(procfile)) return [];
   const raw = await import_node_fs53.promises.readFile(procfile, "utf8");
+  const launcher = broad ? PY_LAUNCHERS_BROAD : PY_LAUNCHER_PYTHON;
   const edits = [];
   for (const line of raw.split(/\r?\n/)) {
     if (line.length === 0) continue;
     const m = line.match(/^([a-zA-Z0-9_-]+):\s*(.+)$/);
     if (!m) continue;
     const cmd = m[2];
-    if (!/^python\b/.test(cmd)) continue;
+    if (!launcher.test(cmd)) continue;
     if (cmd.startsWith("opentelemetry-instrument ")) continue;
     const after = `${m[1]}: opentelemetry-instrument ${cmd}`;
     edits.push({ file: procfile, before: line, after });
   }
   return edits;
 }
-async function plan2(serviceDir) {
+async function plan2(serviceDir, opts) {
   const empty = {
     language: "python",
     serviceDir,
@@ -28942,6 +29084,25 @@ async function plan2(serviceDir) {
     entrypointEdits: [],
     envEdits: []
   };
+  if (!opts?.sourceEdit) {
+    const entrypointEdits2 = await planProcfileEdits(serviceDir, true);
+    const reqs2 = await planRequirementsTxtEdits(serviceDir, [NEAT_OTEL_PACKAGE, ...SDK_PACKAGES2]);
+    const dependencyEdits2 = reqs2 ? reqs2.missing.map((sdk) => ({
+      file: reqs2.manifest,
+      kind: "add",
+      name: sdk.name,
+      version: sdk.version
+    })) : [];
+    if (dependencyEdits2.length === 0 && entrypointEdits2.length === 0) return empty;
+    return {
+      language: "python",
+      serviceDir,
+      dependencyEdits: dependencyEdits2,
+      entrypointEdits: entrypointEdits2,
+      envEdits: [OTEL_ENV2]
+    };
+  }
+  const entrypointEdits = await planProcfileEdits(serviceDir);
   const dependencyEdits = [];
   const reqs = await planRequirementsTxtEdits(serviceDir);
   if (reqs) {
@@ -28954,7 +29115,6 @@ async function plan2(serviceDir) {
       });
     }
   }
-  const entrypointEdits = await planProcfileEdits(serviceDir);
   const entryFile = await resolvePyEntrypoint(serviceDir);
   const generatedFiles = entryFile ? [{ file: import_node_path89.default.join(serviceDir, NEAT_OTEL_FILENAME), contents: neatOtelPy() }] : [];
   if (dependencyEdits.length === 0 && entrypointEdits.length === 0 && !entryFile) {
@@ -29910,7 +30070,7 @@ async function applyInstallersOver(services, project, options = {}) {
   for (const svc of services) {
     const installer = await pickInstaller(svc.dir);
     if (!installer) continue;
-    const plan6 = await installer.plan(svc.dir, { project });
+    const plan6 = await installer.plan(svc.dir, { project, sourceEdit: options.sourceEdit });
     if (isEmptyPlan(plan6) && !plan6.libOnly && plan6.runtimeKind === void 0) {
       already++;
       continue;
@@ -30484,8 +30644,12 @@ async function runOrchestrator(opts) {
     result.steps.apply.skipped = true;
     console.log("skipped instrumentation (--no-instrument)");
   } else {
-    const tally = await applyInstallersOver(services, opts.project);
-    result.steps.apply = { ...tally, skipped: false };
+    const tally = await applyInstallersOver(services, opts.project, { sourceEdit: opts.sourceEdit });
+    result.steps.apply = {
+      ...tally,
+      skipped: false,
+      ...!opts.sourceEdit && tally.instrumented > 0 ? { attached: true } : {}
+    };
     console.log(
       `instrumented ${tally.instrumented}, already ${tally.alreadyInstrumented}, lib-only ${tally.libOnly}`
     );
@@ -30598,6 +30762,12 @@ function printSummary(result, graph, daemonLog) {
     for (const i of failedInstalls) {
       console.log(`      run \`${i.pm} install\` in ${i.cwd}`);
     }
+  } else if (daemonLog !== null && result.steps.apply.attached === true) {
+    console.log("next: start your app with NEAT attached \u2014 OBSERVED edges fill in as it runs,");
+    console.log("      and divergences surface where code and runtime disagree.");
+    console.log("      Node: in the service directory, `set -a; . ./.env.neat; set +a`, then your");
+    console.log("            usual start command (or put its NODE_OPTIONS in your process manager).");
+    console.log("      Python: run your start command under `opentelemetry-instrument`.");
   } else if (daemonLog !== null) {
     console.log(
       "next: run your app or your test suite \u2014 OBSERVED edges fill in as it executes,"
@@ -31772,7 +31942,7 @@ async function runSsoLogin(opts, deps) {
       out("");
       out("To fill the OBSERVED layer, instrument your app to send OpenTelemetry to the hosted daemon:");
       out(`  OTEL_EXPORTER_OTLP_ENDPOINT=${cred.ingestEndpoint}`);
-      out(`  OTEL_EXPORTER_OTLP_HEADERS=Authorization=Bearer ${cred.otelToken}`);
+      out(`  OTEL_EXPORTER_OTLP_HEADERS=${otlpBearerHeader(cred.otelToken)}`);
     }
     await runPostLoginConnect({
       cpUrl: opts.cpUrl,
@@ -33013,6 +33183,12 @@ init_cjs_shims();
 var import_node_fs61 = require("fs");
 var import_node_path98 = __toESM(require("path"), 1);
 var import_promises5 = __toESM(require("readline/promises"), 1);
+
+// src/agent-directive.generated.ts
+init_cjs_shims();
+var AGENT_DIRECTIVE = '## Query NEAT before searching files\n\nThis project has a live NEAT graph: code, data and infrastructure declarations\nfused with runtime traffic, incidents and supported provider telemetry. It can\nshow what exists, what actually ran, where a failure began, and what may break\nwhen a node changes. The graph is deterministic: the agent supplies the model;\nNEAT resolves named nodes and traverses recorded evidence rather than asking an\nLLM to infer architecture from file names.\n\nEvery claim carries provenance and confidence. `EXTRACTED` comes from recognized\nsource or configuration, `OBSERVED` from spans or supported provider signals,\n`INFERRED` from a bridged relationship, and `STALE` marks an observed edge that\nwent quiet. Missing runtime evidence does not prove a path never runs.\n\n**For questions about this system\'s behavior, structure, data dependencies,\nfailures, or change impact, call the MCP `ask` tool (`mcp__neat__ask`) before\nRead/Grep/Glob/Bash.** You do not need an exact node id. `ask` resolves names\nand routes to the relevant graph traversal, returning provenance-tagged facts.\nWhen MCP is unavailable, use the same door through the CLI:\n\n```\nnpx neat.is ask "why is checkout failing?"\nnpx neat.is ask "what breaks if I change the orders table?"\nnpx neat.is ask "what does the payments service depend on at runtime?"\n```\n\nFor a failure, ask first, then call `get_incident_card` on the named service,\nfile or symbol. The card combines the incident, likely cause, blast radius,\npolicies and divergence into a work order. Use `expand` one hop at a time and\n`relate` to test whether the suspected cause and symptom share a signal. Check\nprovenance and confidence before acting.\n\nBefore a change, use `get_blast_radius` and `check_policies` to see dependents\nand advisory architectural rules. Use `get_divergences` to compare declared\nintent with observed behavior, `get_graph_diff` to compare a saved snapshot\nwith the live graph, and `get_recent_stale_edges` when traffic goes quiet.\n`get_dependencies` maps a node\'s outgoing graph; `get_observed_dependencies`\nshows only seen runtime/provider calls. `semantic_search` finds node labels,\nnot arbitrary source text.\n\nRead source when the graph does not model what you need: comments, arbitrary\nstring literals, config details, unsupported syntax, or a repository that has\nnot been extracted or connected. If a graph answer is empty, check the daemon\nwith `npx neat.is list` or restart it with `npx neat.is up`; wire MCP with\n`npx neat.is skill --apply`.\n';
+
+// src/welcome.ts
 var WORDMARK = [
   "\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",
   "\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",
@@ -33021,21 +33197,27 @@ var WORDMARK = [
   "\u2588\u2588\u2551 \u255A\u2588\u2588\u2588\u2588\u2551\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2557\u2588\u2588\u2551  \u2588\u2588\u2551   \u2588\u2588\u2551   ",
   "\u255A\u2550\u255D  \u255A\u2550\u2550\u2550\u255D\u255A\u2550\u2550\u2550\u2550\u2550\u2550\u255D\u255A\u2550\u255D  \u255A\u2550\u255D   \u255A\u2550\u255D   "
 ];
-var AGENT_SETUP_PROMPT = `Set up self-hosted NEAT for this project. NEAT keeps a live graph of the code
-fused with runtime OpenTelemetry data, queryable over MCP \u2014 so you can ask it
-about the system instead of grepping files.
-
-1. Extract the code graph and instrument the services for OpenTelemetry:
-     npx neat.is init . --apply
-   Then install the deps it added (npm install, or your language's equivalent).
-2. Start the NEAT daemon so it watches the code and ingests live traces:
-     npx neat.is watch .
-3. Wire NEAT's MCP server into your agent so it queries the graph first:
+function renderAgentSetupPrompt(project, restPort) {
+  const endpoint2 = restPort === void 0 ? "The daemon endpoint is unavailable; run `npx neat.is up` to start it." : `The local daemon is serving it at http://127.0.0.1:${restPort}.`;
+  return `NEAT is set up for project "${project}". ${endpoint2}
+
+NEAT models this software system as one graph: code, data, infrastructure,
+runtime traffic, incidents, and supported provider telemetry fused where evidence
+permits. Use it to see what exists, what actually ran, where a failure began, and
+what a change could affect. Missing observations do not prove a path never runs.
+
+1. Wire NEAT's MCP server into this agent session:
      npx neat.is skill --apply
-   (other agents: npx neat.is codex|cursor|gemini \u2026 --apply)
+   For Codex: npx neat.is codex --apply
+   For Cursor or Gemini, use the corresponding cursor or gemini subcommand.
+2. Verify the MCP \`ask\` tool answers:
+     ask "what services are in this project and what do they talk to?"
+   If the daemon is unreachable, run \`npx neat.is up\`.
 
-Then ask NEAT instead of reading files, e.g.
-     npx neat.is ask "why is checkout failing?"`;
+${AGENT_DIRECTIVE}
+As the app or tests run, traces fill the OBSERVED layer. Daemon log:
+neat-out/daemon.log. Reopen this door with \`npx neat.is welcome\`.`;
+}
 function printHeader(out) {
   for (const line of WORDMARK) out(line);
   out("");
@@ -33072,15 +33254,38 @@ async function runFrontDoor(deps, out) {
   const cwd = deps.cwd ?? process.cwd();
   const flagGiven = deps.instrumentFlagGiven ?? false;
   const readRegistry2 = deps.readRegistry ?? (() => readRegistry());
+  const readDaemon = deps.readDaemon ?? (async (project) => {
+    const daemon = await findDaemonByProject(project);
+    return daemon?.live ? { projectPath: daemon.record.projectPath, restPort: daemon.record.ports.rest } : void 0;
+  });
   printHeader(out);
   out("Welcome to NEAT. Let's get you a graph of this system.");
   out("");
   const keyReader = deps.readKey !== void 0 ? { read: deps.readKey, done: () => {
   } } : createKeyReader();
   const picked = keyReader !== null ? await selectOption(out, keyReader, deps.moveCursorUp ?? defaultMoveCursorUp) : await selectByNumber(out, readLine);
-  if (picked === void 0) return runSelfHosted(out, readLine, orchestrator, cwd, readRegistry2, flagGiven);
+  if (picked === void 0)
+    return runSelfHosted(
+      out,
+      readLine,
+      orchestrator,
+      cwd,
+      readRegistry2,
+      readDaemon,
+      flagGiven,
+      deps.dryRun === true
+    );
   if (picked === 0) return login(["--browser"]);
-  return runSelfHosted(out, readLine, orchestrator, cwd, readRegistry2, flagGiven);
+  return runSelfHosted(
+    out,
+    readLine,
+    orchestrator,
+    cwd,
+    readRegistry2,
+    readDaemon,
+    flagGiven,
+    deps.dryRun === true
+  );
 }
 var MENU_OPTIONS = [
   "Log me into Hosted Neat",
@@ -33183,17 +33388,7 @@ function decodeKey(buf) {
 function defaultMoveCursorUp(rows) {
   if (rows > 0) process.stdout.write(`\x1B[${rows}A`);
 }
-async function runSelfHosted(out, readLine, orchestrator, cwd, readRegistry2, instrumentFlagGiven) {
-  const wantsPrompt = (await readLine("Print a copy-paste setup prompt for your coding agent? [Y/n]: "))?.trim().toLowerCase();
-  if (wantsPrompt !== "n" && wantsPrompt !== "no") {
-    out("");
-    out("\u2500\u2500\u2500 copy the prompt below into your coding agent \u2500\u2500\u2500");
-    out("");
-    out(AGENT_SETUP_PROMPT);
-    out("");
-    out("\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500");
-    out("");
-  }
+async function runSelfHosted(out, readLine, orchestrator, cwd, readRegistry2, readDaemon, instrumentFlagGiven, dryRun) {
   const project = await resolveProjectName(out, readLine, cwd, readRegistry2);
   const declined = instrumentFlagGiven ? void 0 : await askToInstrument(out, readLine);
   out("Building your local graph now\u2026");
@@ -33203,7 +33398,22 @@ async function runSelfHosted(out, readLine, orchestrator, cwd, readRegistry2, in
     ...project !== void 0 ? { project } : {},
     ...declined === void 0 ? {} : declined ? { noInstrument: true } : { yes: true }
   };
-  return orchestrator(cwd, overrides);
+  const code = await orchestrator(cwd, overrides);
+  if (code !== 0 || dryRun) return code;
+  const wantsPrompt = (await readLine("Print a copy-paste setup prompt for your coding agent? [Y/n]: "))?.trim().toLowerCase();
+  if (wantsPrompt !== "n" && wantsPrompt !== "no") {
+    const projectName = project ?? import_node_path98.default.basename(import_node_path98.default.resolve(cwd));
+    const daemon = await readDaemon(projectName).catch(() => void 0);
+    const port = daemon && import_node_path98.default.resolve(daemon.projectPath) === import_node_path98.default.resolve(cwd) ? daemon.restPort : void 0;
+    out("");
+    out("\u2500\u2500\u2500 copy the directive below into your coding agent \u2500\u2500\u2500");
+    out("");
+    out(renderAgentSetupPrompt(projectName, port));
+    out("");
+    out("\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500");
+    out("");
+  }
+  return code;
 }
 async function askToInstrument(out, readLine) {
   out("Instrument the services for OpenTelemetry now?");
@@ -33213,7 +33423,7 @@ async function askToInstrument(out, readLine) {
   if (declined) {
     out("");
     out("Skipping instrumentation \u2014 the graph will hold the declared side only.");
-    out("Run `neat init . --apply` when you want the runtime half.");
+    out("Run `npx neat.is init . --apply` when you want the runtime half.");
   }
   out("");
   return declined;
@@ -34781,7 +34991,7 @@ async function runSync(opts) {
     snapshotPath = target;
   }
   const skipApply = opts.dryRun || opts.noInstrument;
-  const applyTally = skipApply ? { instrumented: 0, alreadyInstrumented: 0, libOnly: 0, browserBundle: 0, reactNative: 0 } : await applyInstallersOver(persisted.services, entry2.name);
+  const applyTally = skipApply ? { instrumented: 0, alreadyInstrumented: 0, libOnly: 0, browserBundle: 0, reactNative: 0 } : await applyInstallersOver(persisted.services, entry2.name, { sourceEdit: opts.sourceEdit });
   const warnings = [];
   let daemonState = "skipped";
   let exitCode = 0;
@@ -34894,6 +35104,8 @@ function usage5() {
   console.log("                   --apply       run the SDK install patch in place");
   console.log("                   --dry-run     write only neat.patch; do not register or snapshot");
   console.log("                   --no-install  skip SDK install planning entirely");
+  console.log("                   --source-edit inject the OTel init into entry points instead of");
+  console.log("                                 attaching it at process start (ADR-232)");
   console.log("  watch <path>   Start neat-core, watch <path>, re-extract on changes.");
   console.log("                 PORT (default 8080), OTEL_PORT (4318), HOST (0.0.0.0)");
   console.log("                 control listeners. NEAT_OTLP_GRPC=true also opens 4317.");
@@ -35001,6 +35213,7 @@ function usage5() {
   console.log("                   --token <token>    bearer token for --to (or $NEAT_REMOTE_TOKEN)");
   console.log("                   --dry-run          run extraction in-memory; do not write");
   console.log("                   --no-instrument    skip the SDK install apply step");
+  console.log("                   --source-edit      inject into entry points instead of attaching");
   console.log("                   --json             emit the delta summary as JSON");
   console.log("  connector      Configure OBSERVED connectors \u2014 pull (supabase, railway,");
   console.log("                 firebase, cloudflare, neon, cloud-run) and push (vercel,");
@@ -35099,6 +35312,7 @@ function parseArgs(rest) {
     dryRun: false,
     noInstall: false,
     noInstrument: false,
+    sourceEdit: false,
     open: false,
     noOpen: false,
     yes: false,
@@ -35137,6 +35351,10 @@ function parseArgs(rest) {
       out.noInstrument = true;
       continue;
     }
+    if (arg === "--source-edit") {
+      out.sourceEdit = true;
+      continue;
+    }
     if (arg === "--open") {
       out.open = true;
       continue;
@@ -35262,12 +35480,12 @@ function printDiscoveryReport(opts, services) {
   }
   console.log("");
 }
-async function buildPatchSections(services, project) {
+async function buildPatchSections(services, project, sourceEdit) {
   const sections = [];
   for (const svc of services) {
     const installer = await pickInstaller(svc.dir);
     if (!installer) continue;
-    const plan6 = await installer.plan(svc.dir, { project });
+    const plan6 = await installer.plan(svc.dir, { project, sourceEdit });
     if (isEmptyPlan(plan6) && !plan6.libOnly && plan6.runtimeKind === void 0) continue;
     sections.push({ installer: installer.name, plan: plan6 });
   }
@@ -35282,7 +35500,7 @@ async function runInit(opts) {
   }
   const services = await discoverServices(opts.scanPath);
   printDiscoveryReport(opts, services);
-  const sections = opts.noInstall ? [] : await buildPatchSections(services, opts.project);
+  const sections = opts.noInstall ? [] : await buildPatchSections(services, opts.project, opts.sourceEdit);
   const patch = renderPatch(sections);
   const patchPath = import_node_path104.default.join(opts.scanPath, "neat.patch");
   if (opts.dryRun) {
@@ -35586,6 +35804,7 @@ async function main() {
       apply: apply6,
       dryRun,
       noInstall,
+      sourceEdit: parsed.sourceEdit,
       verbose: parsed.verbose
     });
     if (result.exitCode !== 0) process.exit(result.exitCode);
@@ -35778,6 +35997,7 @@ async function main() {
       ...parsed.token ? { token: parsed.token } : {},
       dryRun: parsed.dryRun,
       noInstrument: parsed.noInstrument,
+      sourceEdit: parsed.sourceEdit,
       json: parsed.json
     });
     if (result.exitCode !== 0) process.exit(result.exitCode);
@@ -35813,6 +36033,7 @@ async function tryOrchestrator(cmd, parsed, overrides = {}) {
     project: projectName,
     projectExplicit,
     noInstrument: parsed.noInstrument,
+    sourceEdit: parsed.sourceEdit,
     open: parsed.open,
     noOpen: parsed.noOpen,
     yes: parsed.yes,
@@ -35825,6 +36046,10 @@ async function runWelcomeFlow(parsed) {
     cwd,
     {
       ...parsed,
+      // ADR-232 — the front-door / local-menu run never source-edits, even if
+      // `--source-edit` was on the command line. Source-edit stays an explicit
+      // choice on a deliberately-typed `neat <path> --source-edit`.
+      sourceEdit: false,
       ...opts?.project !== void 0 ? { project: opts.project } : {},
       ...opts?.noInstrument !== void 0 ? { noInstrument: opts.noInstrument } : {},
       ...opts?.yes !== void 0 ? { yes: opts.yes } : {}
@@ -35840,7 +36065,8 @@ async function runWelcomeFlow(parsed) {
     // door's wordmark already opened this run, so the orchestrator's banner is skipped.
     orchestrator: runLocal,
     // An explicit flag is an answer; don't ask again.
-    instrumentFlagGiven: parsed.noInstrument || parsed.dryRun
+    instrumentFlagGiven: parsed.noInstrument || parsed.dryRun,
+    dryRun: parsed.dryRun
   });
 }
 var QUERY_VERBS = /* @__PURE__ */ new Set([