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

package/dist/cli.js

@@ -8,16 +8,15 @@ import {
   resolveNeatVersion,
   startK8sSubstratePolling,
   writeDaemonRecord
-} from "./chunk-VL7ANDPI.js";
+} from "./chunk-ECBRGTB2.js";
 import {
-  buildSearchIndex
-} from "./chunk-BC53SCT7.js";
+  buildSearchIndex,
+  searchProviderFromEnv
+} from "./chunk-VFZ6CXLI.js";
 import {
   DEFAULT_PROJECT,
   PolicyViolationsLog,
-  ProjectNameCollisionError,
   Projects,
-  RegistryError,
   SCHEMA_VERSION,
   addCallEdges,
   addConfigNodes,
@@ -25,7 +24,6 @@ import {
   addFiles,
   addImports,
   addInfra,
-  addProject,
   addRoutes,
   addServiceAliases,
   addServiceNodes,
@@ -42,59 +40,66 @@ import {
   ensureCompatLoaded,
   evaluateAllPolicies,
   extractFromDirectory,
-  findDaemonByProject,
-  findProjectByPath,
   formatExtractionBanner,
   formatPrecisionFloorBanner,
   formatSkippedBanner,
   getGraph,
-  getProject,
   getProviderFieldSchema,
   isEnvRef,
   isPushProvider,
   isStrictExtractionEnabled,
   knownProviderNames,
-  listMachineProjects,
-  listProjects,
   loadGraphFromDisk,
   loadPolicyFile,
   makeErrorSpanWriter,
   makeSpanHandler,
-  normalizeProjectPath,
   pathsForProject,
   promoteFrontierNodes,
   provisionConnector,
-  pruneRegistry,
   readConnectorsConfig,
   readErrorEvents,
-  readRegistry,
   removeConnectorEntry,
-  removeDaemonRecord,
-  removeProject,
   resetGraph,
   retireEdgesByFile,
   runPackageManagerInstall,
   saveGraphToDisk,
-  setStatus,
-  signalDaemonStop,
   startConnectorPolling,
   startPersistLoop,
   startStalenessLoop,
   upsertConnectorEntry,
   validateConnectorEntry
-} from "./chunk-KTJK2PAH.js";
+} from "./chunk-H2BAPN33.js";
+import {
+  ProjectNameCollisionError,
+  RegistryError,
+  addProject,
+  findDaemonByProject,
+  findProjectByPath,
+  getProject,
+  listMachineProjects,
+  listProjects,
+  normalizeProjectPath,
+  pruneRegistry,
+  readRegistry,
+  removeDaemonRecord,
+  removeProject,
+  setStatus,
+  signalDaemonStop
+} from "./chunk-RGYC5U2Q.js";
 import {
   startOtelGrpcReceiver
-} from "./chunk-LXQCL4MP.js";
+} from "./chunk-TZXSWSHX.js";
 import {
-  __dirname,
-  __require,
   assertBindAuthority,
   buildOtelReceiver,
   isLoopbackHost,
   listenSteppingOtlp,
   readAuthEnv
-} from "./chunk-EFBWQIKG.js";
+} from "./chunk-QPG2QXCW.js";
+import {
+  __dirname,
+  __require
+} from "./chunk-MR64ICXX.js";
 
 // src/cli.ts
 import path21 from "path";
@@ -278,11 +283,19 @@ ${NEAT_OUT_LINE}
 
 // src/summary.ts
 import { EdgeType, NodeType, Provenance as Provenance2 } from "@neat.is/types";
+
+// src/otlp-headers.ts
+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) {
@@ -698,9 +711,10 @@ async function startWatch(graph, opts) {
   const port = opts.port ?? 8080;
   const otelPort = opts.otelPort ?? 4318;
   const cachePath = opts.embeddingsCachePath ?? path3.join(path3.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(
@@ -983,7 +997,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");
 }
@@ -1043,7 +1057,7 @@ import semver from "semver";
 // src/installers/templates.ts
 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 {
@@ -1488,7 +1502,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}`,
@@ -1684,14 +1722,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;
@@ -2502,6 +2542,49 @@ async function findFrameworkDispatch(serviceDir, pkg, manifestPath, project) {
   }
   return null;
 }
+var ATTACH_PACKAGE_NAME = "@neat.is/otel-node";
+function attachPackageRange(coreVersion = readPackageVersion()) {
+  return semver.valid(coreVersion) ? `^${coreVersion}` : "latest";
+}
+async function planAttachment(serviceDir, pkg, manifestPath, project) {
+  const svcName = serviceNodeName(pkg, serviceDir);
+  const projectName = projectToken(pkg, serviceDir, project);
+  const envNeatFile = path5.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 exists(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 readPackageJson(serviceDir);
   const manifestPath = path5.join(serviceDir, "package.json");
@@ -2527,14 +2610,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 };
   }
@@ -2851,6 +2937,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",
@@ -3002,34 +3089,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 = path6.join(serviceDir, "requirements.txt");
   if (!await exists2(file)) return null;
   const raw = await fs5.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 = path6.join(serviceDir, "Procfile");
   if (!await exists2(procfile)) return [];
   const raw = await fs5.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,
@@ -3037,6 +3127,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) {
@@ -3049,7 +3158,6 @@ async function plan2(serviceDir) {
       });
     }
   }
-  const entrypointEdits = await planProcfileEdits(serviceDir);
   const entryFile = await resolvePyEntrypoint(serviceDir);
   const generatedFiles = entryFile ? [{ file: path6.join(serviceDir, NEAT_OTEL_FILENAME), contents: neatOtelPy() }] : [];
   if (dependencyEdits.length === 0 && entrypointEdits.length === 0 && !entryFile) {
@@ -4000,7 +4108,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;
@@ -4574,8 +4682,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}`
     );
@@ -4688,6 +4800,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,"
@@ -5856,7 +5974,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,
@@ -7092,6 +7210,11 @@ async function defaultReadSecret(prompt) {
 import { promises as fs13 } from "fs";
 import path15 from "path";
 import readline4 from "readline/promises";
+
+// src/agent-directive.generated.ts
+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",
@@ -7100,21 +7223,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.
+function renderAgentSetupPrompt(project, restPort) {
+  const endpoint = 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}". ${endpoint}
 
-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:
+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("");
@@ -7151,15 +7280,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",
@@ -7262,17 +7414,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");
@@ -7282,7 +7424,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 ?? path15.basename(path15.resolve(cwd));
+    const daemon = await readDaemon(projectName).catch(() => void 0);
+    const port = daemon && path15.resolve(daemon.projectPath) === path15.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?");
@@ -7292,7 +7449,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;
@@ -8451,7 +8608,8 @@ function formatIncidentLine(card) {
     const cls = rc.classification ? `${rc.classification} ` : "";
     tag = `  \xB7 ${cls}${rc.confidence.toFixed(2)}${provs ? ` [${provs}]` : ""}`;
   }
-  return `\u2716 incident [${card.incidentKind}]  ${card.headline}${tag}`;
+  const grade = card.grade ? `  \xB7 grade ${card.grade.G.toFixed(2)} ${card.grade.band}` : "";
+  return `\u2716 incident [${card.incidentKind}]  ${card.headline}${tag}${grade}`;
 }
 function incidentJson(card) {
   return JSON.stringify(card);
@@ -8854,7 +9012,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;
@@ -8966,6 +9124,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.");
@@ -9073,6 +9233,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,");
@@ -9171,6 +9332,7 @@ function parseArgs(rest) {
     dryRun: false,
     noInstall: false,
     noInstrument: false,
+    sourceEdit: false,
     open: false,
     noOpen: false,
     yes: false,
@@ -9209,6 +9371,10 @@ function parseArgs(rest) {
       out.noInstrument = true;
       continue;
     }
+    if (arg === "--source-edit") {
+      out.sourceEdit = true;
+      continue;
+    }
     if (arg === "--open") {
       out.open = true;
       continue;
@@ -9334,12 +9500,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 });
   }
@@ -9354,7 +9520,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 = path21.join(opts.scanPath, "neat.patch");
   if (opts.dryRun) {
@@ -9658,6 +9824,7 @@ async function main() {
       apply: apply6,
       dryRun,
       noInstall,
+      sourceEdit: parsed.sourceEdit,
       verbose: parsed.verbose
     });
     if (result.exitCode !== 0) process.exit(result.exitCode);
@@ -9850,6 +10017,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);
@@ -9885,6 +10053,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,
@@ -9897,6 +10066,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 } : {}
@@ -9912,7 +10085,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([