@neat.is/core 0.7.9 → 0.7.10

package/dist/cli.js

@@ -6,7 +6,7 @@ import {
   resolveHost,
   resolveNeatVersion,
   writeDaemonRecord
-} from "./chunk-ILG3SMD5.js";
+} from "./chunk-D4OX6MUX.js";
 import {
   buildSearchIndex
 } from "./chunk-BC53SCT7.js";
@@ -74,7 +74,7 @@ import {
   startStalenessLoop,
   upsertConnectorEntry,
   validateConnectorEntry
-} from "./chunk-N5TPODCX.js";
+} from "./chunk-6T7ZHODF.js";
 import {
   startOtelGrpcReceiver
 } from "./chunk-FCO5Z3RW.js";
@@ -88,9 +88,9 @@ import {
 } from "./chunk-UUYCTH2E.js";
 
 // src/cli.ts
-import path13 from "path";
+import path15 from "path";
 import os4 from "os";
-import { promises as fs11 } from "fs";
+import { promises as fs13 } from "fs";
 
 // src/banner.ts
 import path from "path";
@@ -487,6 +487,9 @@ async function startWatch(graph, opts) {
     project: projectName,
     graph,
     projectDir: opts.scanPath,
+    // Incident ledger for an incident-emitting connector (ADR-185), same path
+    // `neat watch`'s own error-span writer already uses.
+    errorsPath: opts.errorsPath,
     ...opts.neatHome ? { home: opts.neatHome } : {},
     onSkip: (skipped, reason) => console.warn(
       `neat watch: connector "${skipped.id}" (${skipped.provider}) skipped for project "${projectName}" \u2014 ${reason}`
@@ -3107,13 +3110,516 @@ async function apply3(installPlan) {
     await fs6.writeFile(generated.file, generated.contents, "utf8");
     writtenFiles.push(generated.file);
   }
-  return { serviceDir: installPlan.serviceDir, outcome: writtenFiles.length ? "instrumented" : "already-instrumented", writtenFiles };
+  const wroteManifest = writtenFiles.some((f) => f.split(/[\\/]/).pop() === "go.mod");
+  return {
+    serviceDir: installPlan.serviceDir,
+    outcome: writtenFiles.length ? "instrumented" : "already-instrumented",
+    writtenFiles,
+    ...wroteManifest ? { followUpInstall: "go mod download" } : {}
+  };
 }
 var goInstaller = { name: "go", detect: detect3, plan: plan3, apply: apply3 };
 
+// src/installers/ruby.ts
+import { promises as fs7 } from "fs";
+import path8 from "path";
+var RUBY_MARKERS = [
+  "Gemfile",
+  "Gemfile.lock"
+];
+var RUBY_GEMS = [
+  { name: "opentelemetry-sdk", version: "~> 1.5" },
+  { name: "opentelemetry-exporter-otlp", version: "~> 0.29" },
+  { name: "opentelemetry-instrumentation-all", version: "~> 0.62" }
+];
+var NEAT_OTEL_STAMP2 = "neat-otel-init v1";
+var INITIALIZER_REL = path8.join("config", "initializers", "neat_otel.rb");
+function neatOtelRb(opts = {}) {
+  const service = opts.project ?? "ruby-service";
+  const endpoint = opts.project ? `http://localhost:4318/projects/${opts.project}/v1/traces` : "http://localhost:4318/v1/traces";
+  return `# ${NEAT_OTEL_STAMP2} \u2014 generated by NEAT. Safe to re-generate; do not edit.
+# Rails auto-loads this at boot (config/initializers/*). It points the
+# OpenTelemetry SDK at your NEAT daemon, enables the Ruby auto-instrumentation
+# set, and installs a span processor that stamps code.file.path /
+# code.line.number / code.function.name on the CLIENT/PRODUCER spans your app
+# issues, so NEAT fuses each runtime span onto the source file that made the
+# call (docs/contracts/file-awareness.md). Absolute paths are emitted here;
+# ingest anchors them against the service root. If the OpenTelemetry gems are
+# not installed this file degrades to a no-op rather than breaking boot.
+
+begin
+  require 'opentelemetry/sdk'
+  require 'opentelemetry/exporter/otlp'
+  require 'opentelemetry/instrumentation/all'
+  _neat_otel_loaded = true
+rescue LoadError
+  _neat_otel_loaded = false
+end
+
+if _neat_otel_loaded && ENV['NEAT_CALLSITE_DISABLED'] != '1'
+  # Walk the Ruby call stack to the first application frame and stamp the stable
+  # OTel source attributes on CLIENT/PRODUCER spans. SERVER spans are created
+  # before the handler runs, so they stay route/service-grained, honestly.
+  class NeatCallSiteSpanProcessor
+    def initialize(root)
+      @root = root.to_s.end_with?(File::SEPARATOR) ? root.to_s : root.to_s + File::SEPARATOR
+    end
+
+    def on_start(span, _parent_context)
+      kind = span.kind
+      return unless kind == OpenTelemetry::Trace::SpanKind::CLIENT ||
+                    kind == OpenTelemetry::Trace::SpanKind::PRODUCER
+      caller_locations(1).each do |loc|
+        file = loc.absolute_path || loc.path
+        next if file.nil?
+        next unless file.start_with?(@root)
+        next if file.include?('/vendor/') || file.include?('/.bundle/')
+        next if file.end_with?('neat_otel.rb')
+        span.set_attribute('code.file.path', file)
+        span.set_attribute('code.line.number', loc.lineno)
+        span.set_attribute('code.function.name', loc.label.to_s)
+        break
+      end
+    rescue StandardError
+      # never break the host application
+    end
+
+    def on_finish(_span); end
+
+    def force_flush(timeout: nil)
+      OpenTelemetry::SDK::Trace::Export::SUCCESS
+    end
+
+    def shutdown(timeout: nil)
+      OpenTelemetry::SDK::Trace::Export::SUCCESS
+    end
+  end
+
+  _neat_root = defined?(Rails) ? Rails.root.to_s : Dir.pwd
+  _neat_service = ENV.fetch('OTEL_SERVICE_NAME', '${service}')
+  _neat_endpoint = ENV.fetch('OTEL_EXPORTER_OTLP_TRACES_ENDPOINT', '${endpoint}')
+
+  OpenTelemetry::SDK.configure do |c|
+    c.service_name = _neat_service
+    c.use_all
+    c.add_span_processor(
+      OpenTelemetry::SDK::Trace::Export::BatchSpanProcessor.new(
+        OpenTelemetry::Exporter::OTLP::Exporter.new(endpoint: _neat_endpoint)
+      )
+    )
+    c.add_span_processor(NeatCallSiteSpanProcessor.new(_neat_root))
+  end
+end
+`;
+}
+async function exists4(p) {
+  try {
+    await fs7.stat(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function detect4(serviceDir) {
+  for (const marker of RUBY_MARKERS) {
+    if (await exists4(path8.join(serviceDir, marker))) return true;
+  }
+  return false;
+}
+async function isRailsApp(serviceDir, gemfile) {
+  if (gemfile && /^\s*gem\s+['"]rails['"]/m.test(gemfile)) return true;
+  for (const marker of ["config/application.rb", "config/environment.rb", "bin/rails"]) {
+    if (await exists4(path8.join(serviceDir, marker))) return true;
+  }
+  return false;
+}
+function gemPresent(gemfile, name) {
+  const escaped = name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  return new RegExp(`^\\s*gem\\s+['"]${escaped}['"]`, "m").test(gemfile);
+}
+async function readGemfile(serviceDir) {
+  const file = path8.join(serviceDir, "Gemfile");
+  if (!await exists4(file)) return null;
+  return { file, body: await fs7.readFile(file, "utf8") };
+}
+async function plan4(serviceDir, opts) {
+  const empty = {
+    language: "ruby",
+    serviceDir,
+    dependencyEdits: [],
+    entrypointEdits: [],
+    envEdits: []
+  };
+  const gemfile = await readGemfile(serviceDir);
+  const dependencyEdits = [];
+  if (gemfile) {
+    for (const gem of RUBY_GEMS) {
+      if (!gemPresent(gemfile.body, gem.name)) {
+        dependencyEdits.push({ file: gemfile.file, kind: "add", name: gem.name, version: gem.version });
+      }
+    }
+  }
+  const rails = await isRailsApp(serviceDir, gemfile?.body ?? null);
+  const initializer = path8.join(serviceDir, INITIALIZER_REL);
+  const generatedFiles = [];
+  if (rails && !await exists4(initializer)) {
+    generatedFiles.push({
+      file: initializer,
+      contents: neatOtelRb({ project: opts?.project }),
+      skipIfExists: true
+    });
+  }
+  if (dependencyEdits.length === 0 && generatedFiles.length === 0) {
+    return empty;
+  }
+  const envEdits = [
+    { file: null, key: "OTEL_EXPORTER_OTLP_ENDPOINT", value: "http://localhost:4318" }
+  ];
+  return {
+    language: "ruby",
+    serviceDir,
+    dependencyEdits,
+    entrypointEdits: [],
+    envEdits,
+    ...generatedFiles.length > 0 ? { generatedFiles } : {}
+  };
+}
+async function writeFileAtomic2(file, contents) {
+  const tmp = `${file}.${process.pid}.${Date.now()}.tmp`;
+  await fs7.writeFile(tmp, contents, "utf8");
+  await fs7.rename(tmp, file);
+}
+async function applyGemfile(file, edits, original) {
+  const lines = edits.filter((e) => e.kind === "add").map((e) => `gem '${e.name}', '${e.version}'`);
+  const banner = `
+# ${NEAT_OTEL_STAMP2} \u2014 OpenTelemetry gems added by NEAT
+`;
+  const trailing = original.endsWith("\n") ? "" : "\n";
+  await writeFileAtomic2(file, `${original}${trailing}${banner}${lines.join("\n")}
+`);
+}
+async function rollback3(serviceDir, language, originals, created) {
+  const restored = [];
+  for (const [file, raw] of originals.entries()) {
+    try {
+      await fs7.writeFile(file, raw, "utf8");
+      restored.push(file);
+    } catch {
+    }
+  }
+  const removed = [];
+  for (const file of created) {
+    try {
+      await fs7.rm(file, { force: true });
+      removed.push(file);
+    } catch {
+    }
+  }
+  const body = [
+    "# neat-rollback.patch",
+    "",
+    `# Generated after a partial apply failure in the ${language} installer.`,
+    "# Files listed below were restored to their pre-apply contents.",
+    "",
+    ...restored.map((f) => `restored: ${f}`),
+    ...removed.map((f) => `removed: ${f}`),
+    ""
+  ];
+  await fs7.writeFile(path8.join(serviceDir, "neat-rollback.patch"), body.join("\n"), "utf8");
+}
+async function apply4(installPlan) {
+  const { serviceDir } = installPlan;
+  const generatedFiles = installPlan.generatedFiles ?? [];
+  const manifests = new Set(installPlan.dependencyEdits.map((e) => e.file));
+  if (manifests.size === 0 && generatedFiles.length === 0) {
+    return { serviceDir, outcome: "already-instrumented", writtenFiles: [] };
+  }
+  const originals = /* @__PURE__ */ new Map();
+  for (const file of manifests) {
+    try {
+      originals.set(file, await fs7.readFile(file, "utf8"));
+    } catch {
+    }
+  }
+  const writtenFiles = [];
+  const created = [];
+  try {
+    for (const gf of generatedFiles) {
+      if (await exists4(gf.file)) continue;
+      await fs7.mkdir(path8.dirname(gf.file), { recursive: true });
+      await writeFileAtomic2(gf.file, gf.contents);
+      writtenFiles.push(gf.file);
+      created.push(gf.file);
+    }
+    for (const file of manifests) {
+      const raw = originals.get(file);
+      if (raw === void 0) throw new Error(`ruby installer: cannot read ${file} during apply`);
+      const edits = installPlan.dependencyEdits.filter((e) => e.file === file);
+      if (edits.length > 0) {
+        await applyGemfile(file, edits, raw);
+        writtenFiles.push(file);
+      }
+    }
+  } catch (err) {
+    await rollback3(serviceDir, installPlan.language, originals, created);
+    throw err;
+  }
+  const wroteManifest = writtenFiles.some((f) => path8.basename(f) === "Gemfile");
+  return {
+    serviceDir,
+    outcome: writtenFiles.length > 0 ? "instrumented" : "already-instrumented",
+    writtenFiles,
+    ...wroteManifest ? { followUpInstall: "bundle install" } : {}
+  };
+}
+var rubyInstaller = { name: "ruby", detect: detect4, plan: plan4, apply: apply4 };
+
+// src/installers/php.ts
+import { promises as fs8 } from "fs";
+import path9 from "path";
+var PHP_MARKERS = [
+  "composer.json",
+  "composer.lock"
+];
+var NEAT_OTEL_FILENAME2 = "neat_otel.php";
+var NEAT_OTEL_STAMP3 = "neat-otel-init v1";
+var LARAVEL_PACKAGE = "open-telemetry/opentelemetry-auto-laravel";
+var PHP_PACKAGES = [
+  { name: "open-telemetry/sdk", version: "^1.0" },
+  { name: "open-telemetry/exporter-otlp", version: "^1.0" },
+  { name: "php-http/guzzle7-adapter", version: "^1.0" },
+  { name: LARAVEL_PACKAGE, version: "^0.1" }
+];
+var PHP_PECL_CAVEAT = "PHP auto-instrumentation requires the `opentelemetry` PECL extension (`pecl install opentelemetry`, then `extension=opentelemetry.so` in php.ini). NEAT cannot install a PECL extension via composer \u2014 until it is loaded no spans are produced. See neat_otel.php and ADR-186.";
+function neatOtelPhp(opts = {}) {
+  const service = opts.project ?? "php-service";
+  const endpoint = opts.project ? `http://localhost:4318/projects/${opts.project}/v1/traces` : "http://localhost:4318/v1/traces";
+  return `<?php
+// ${NEAT_OTEL_STAMP3} \u2014 generated by NEAT. Safe to re-generate; do not edit.
+//
+// REQUIRED SYSTEM STEP \u2014 NEAT CANNOT DO THIS FOR YOU:
+//   PHP OpenTelemetry auto-instrumentation needs the \`opentelemetry\` PECL
+//   extension, a system-level install composer cannot provide:
+//       pecl install opentelemetry
+//   then enable it in your php.ini:
+//       extension=opentelemetry.so
+//   Verify with \`php -m | grep opentelemetry\`. Until the extension is loaded
+//   the Laravel auto-instrumentation hooks never fire and no spans are emitted.
+//
+// Wire this file so it runs before the framework boots \u2014 either set
+//   auto_prepend_file = /absolute/path/to/neat_otel.php
+// in php.ini / .user.ini, or require it at the very top of public/index.php and
+// artisan. It points the exporter at your NEAT daemon and turns on the SDK
+// autoloader; the auto-laravel instrumentation then produces route, DB, cache,
+// and queue spans that fuse onto your extracted routes and Eloquent tables.
+//
+// FILE-GRAIN (code.file.path call-site attribution) is a documented follow-up
+// for PHP \u2014 see ADR-186. Route, table, and service grain land now.
+
+declare(strict_types=1);
+
+// Degrade to a no-op when the extension isn't present, so a bare app still
+// boots (never break the host application).
+if (!extension_loaded('opentelemetry')) {
+    return;
+}
+
+// Point the exporter at NEAT unless the operator already set these. The
+// endpoint is NEAT's project-scoped traces path (ADR-183).
+$neat_defaults = [
+    'OTEL_PHP_AUTOLOAD_ENABLED' => 'true',
+    'OTEL_SERVICE_NAME' => '${service}',
+    'OTEL_TRACES_EXPORTER' => 'otlp',
+    'OTEL_EXPORTER_OTLP_PROTOCOL' => 'http/json',
+    'OTEL_EXPORTER_OTLP_TRACES_ENDPOINT' => '${endpoint}',
+    'OTEL_PROPAGATORS' => 'baggage,tracecontext',
+];
+foreach ($neat_defaults as $neat_key => $neat_value) {
+    if (getenv($neat_key) === false && !isset($_SERVER[$neat_key]) && !isset($_ENV[$neat_key])) {
+        putenv($neat_key . '=' . $neat_value);
+        $_SERVER[$neat_key] = $neat_value;
+        $_ENV[$neat_key] = $neat_value;
+    }
+}
+`;
+}
+async function exists5(p) {
+  try {
+    await fs8.stat(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function detect5(serviceDir) {
+  for (const marker of PHP_MARKERS) {
+    if (await exists5(path9.join(serviceDir, marker))) return true;
+  }
+  return false;
+}
+function readComposerObject(body) {
+  let parsed = null;
+  try {
+    parsed = JSON.parse(body);
+  } catch {
+    parsed = null;
+  }
+  const obj = parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : {};
+  const require2 = obj.require && typeof obj.require === "object" && !Array.isArray(obj.require) ? obj.require : {};
+  const requireDev = obj["require-dev"] && typeof obj["require-dev"] === "object" && !Array.isArray(obj["require-dev"]) ? obj["require-dev"] : {};
+  return { require: require2, requireDev };
+}
+async function plan5(serviceDir, opts) {
+  const empty = {
+    language: "php",
+    serviceDir,
+    dependencyEdits: [],
+    entrypointEdits: [],
+    envEdits: []
+  };
+  const composerPath = path9.join(serviceDir, "composer.json");
+  const hasComposer = await exists5(composerPath);
+  const dependencyEdits = [];
+  if (hasComposer) {
+    const body = await fs8.readFile(composerPath, "utf8");
+    const { require: require2, requireDev } = readComposerObject(body);
+    const laravel = "laravel/framework" in require2 || "laravel/framework" in requireDev || await exists5(path9.join(serviceDir, "artisan"));
+    const wanted = laravel ? PHP_PACKAGES : PHP_PACKAGES.filter((p) => p.name !== LARAVEL_PACKAGE);
+    for (const pkg of wanted) {
+      if (!(pkg.name in require2)) {
+        dependencyEdits.push({ file: composerPath, kind: "add", name: pkg.name, version: pkg.version });
+      }
+    }
+  }
+  const bootstrap = path9.join(serviceDir, NEAT_OTEL_FILENAME2);
+  const generatedFiles = [];
+  if (hasComposer && !await exists5(bootstrap)) {
+    generatedFiles.push({ file: bootstrap, contents: neatOtelPhp({ project: opts?.project }), skipIfExists: true });
+  }
+  if (dependencyEdits.length === 0 && generatedFiles.length === 0) {
+    return empty;
+  }
+  const envEdits = [
+    { file: null, key: "OTEL_PHP_AUTOLOAD_ENABLED", value: "true" },
+    { file: null, key: "OTEL_EXPORTER_OTLP_ENDPOINT", value: "http://localhost:4318" }
+  ];
+  return {
+    language: "php",
+    serviceDir,
+    dependencyEdits,
+    entrypointEdits: [],
+    envEdits,
+    ...generatedFiles.length > 0 ? { generatedFiles } : {}
+  };
+}
+async function writeFileAtomic3(file, contents) {
+  const tmp = `${file}.${process.pid}.${Date.now()}.tmp`;
+  await fs8.writeFile(tmp, contents, "utf8");
+  await fs8.rename(tmp, file);
+}
+async function applyComposerJson(file, edits, original) {
+  let parsed;
+  try {
+    parsed = JSON.parse(original);
+  } catch {
+    throw new Error(`php installer: composer.json at ${file} is not valid JSON`);
+  }
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+    throw new Error(`php installer: composer.json at ${file} is not a JSON object`);
+  }
+  const obj = parsed;
+  const require2 = obj.require && typeof obj.require === "object" && !Array.isArray(obj.require) ? obj.require : {};
+  for (const e of edits) {
+    if (e.kind !== "add") continue;
+    if (!(e.name in require2)) require2[e.name] = e.version;
+  }
+  obj.require = require2;
+  await writeFileAtomic3(file, JSON.stringify(obj, null, 2) + "\n");
+}
+async function rollback4(serviceDir, language, originals, created) {
+  const restored = [];
+  for (const [file, raw] of originals.entries()) {
+    try {
+      await fs8.writeFile(file, raw, "utf8");
+      restored.push(file);
+    } catch {
+    }
+  }
+  const removed = [];
+  for (const file of created) {
+    try {
+      await fs8.rm(file, { force: true });
+      removed.push(file);
+    } catch {
+    }
+  }
+  const body = [
+    "# neat-rollback.patch",
+    "",
+    `# Generated after a partial apply failure in the ${language} installer.`,
+    "# Files listed below were restored to their pre-apply contents.",
+    "",
+    ...restored.map((f) => `restored: ${f}`),
+    ...removed.map((f) => `removed: ${f}`),
+    ""
+  ];
+  await fs8.writeFile(path9.join(serviceDir, "neat-rollback.patch"), body.join("\n"), "utf8");
+}
+async function apply5(installPlan) {
+  const { serviceDir } = installPlan;
+  const generatedFiles = installPlan.generatedFiles ?? [];
+  const manifests = new Set(installPlan.dependencyEdits.map((e) => e.file));
+  if (manifests.size === 0 && generatedFiles.length === 0) {
+    return { serviceDir, outcome: "already-instrumented", writtenFiles: [], reason: PHP_PECL_CAVEAT };
+  }
+  const originals = /* @__PURE__ */ new Map();
+  for (const file of manifests) {
+    try {
+      originals.set(file, await fs8.readFile(file, "utf8"));
+    } catch {
+    }
+  }
+  const writtenFiles = [];
+  const created = [];
+  try {
+    for (const gf of generatedFiles) {
+      if (await exists5(gf.file)) continue;
+      await fs8.mkdir(path9.dirname(gf.file), { recursive: true });
+      await writeFileAtomic3(gf.file, gf.contents);
+      writtenFiles.push(gf.file);
+      created.push(gf.file);
+    }
+    for (const file of manifests) {
+      const raw = originals.get(file);
+      if (raw === void 0) throw new Error(`php installer: cannot read ${file} during apply`);
+      const edits = installPlan.dependencyEdits.filter((e) => e.file === file);
+      if (edits.length > 0) {
+        await applyComposerJson(file, edits, raw);
+        writtenFiles.push(file);
+      }
+    }
+  } catch (err) {
+    await rollback4(serviceDir, installPlan.language, originals, created);
+    throw err;
+  }
+  if (writtenFiles.length > 0) {
+    console.warn(`neat: PHP instrumentation staged in ${path9.basename(serviceDir)}, but a system step remains:
+  ${PHP_PECL_CAVEAT}`);
+  }
+  const wroteManifest = writtenFiles.some((f) => path9.basename(f) === "composer.json");
+  return {
+    serviceDir,
+    outcome: writtenFiles.length > 0 ? "instrumented" : "already-instrumented",
+    writtenFiles,
+    reason: PHP_PECL_CAVEAT,
+    ...wroteManifest ? { followUpInstall: "composer install" } : {}
+  };
+}
+var phpInstaller = { name: "php", detect: detect5, plan: plan5, apply: apply5 };
+
 // src/installers/shared.ts
-function isEmptyPlan(plan4) {
-  return plan4.dependencyEdits.length === 0 && plan4.entrypointEdits.length === 0 && plan4.envEdits.length === 0 && (plan4.generatedFiles?.length ?? 0) === 0 && plan4.nextConfigEdit === void 0;
+function isEmptyPlan(plan6) {
+  return plan6.dependencyEdits.length === 0 && plan6.entrypointEdits.length === 0 && plan6.envEdits.length === 0 && (plan6.generatedFiles?.length ?? 0) === 0 && plan6.nextConfigEdit === void 0;
 }
 
 // src/installers/index.ts
@@ -3125,9 +3631,16 @@ var FORBIDDEN_LOCKFILES = /* @__PURE__ */ new Set([
   "Pipfile.lock",
   "Gemfile.lock",
   "Cargo.lock",
-  "go.sum"
+  "go.sum",
+  "composer.lock"
 ]);
-var INSTALLERS = [javascriptInstaller, pythonInstaller, goInstaller];
+var INSTALLERS = [
+  javascriptInstaller,
+  pythonInstaller,
+  goInstaller,
+  rubyInstaller,
+  phpInstaller
+];
 async function pickInstaller(serviceDir) {
   for (const inst of INSTALLERS) {
     if (await inst.detect(serviceDir)) return inst;
@@ -3142,7 +3655,7 @@ function renderPatch(sections) {
       "No SDK installers matched the discovered services. Two reasons this",
       "normally happens:",
       "  - the project uses a language NEAT does not yet instrument",
-      "    (Java / Ruby / .NET / Rust are out of MVP scope per ADR-047);",
+      "    (Java / .NET / Rust are out of scope per ADR-047);",
       "  - the SDK is already installed, so the installer returned an empty",
       "    plan.",
       "",
@@ -3152,22 +3665,22 @@ function renderPatch(sections) {
   }
   const lines = ["# neat install plan", ""];
   for (const section of sections) {
-    const { installer, plan: plan4 } = section;
-    lines.push(`## ${installer} (${plan4.language}) \u2014 ${plan4.serviceDir}`);
+    const { installer, plan: plan6 } = section;
+    lines.push(`## ${installer} (${plan6.language}) \u2014 ${plan6.serviceDir}`);
     lines.push("");
-    if (plan4.libOnly) {
+    if (plan6.libOnly) {
       lines.push("### skipped \u2014 no resolvable entry point (lib-only)");
       lines.push("");
       continue;
     }
-    if (plan4.entryFile) {
-      lines.push(`entry: ${plan4.entryFile}`);
+    if (plan6.entryFile) {
+      lines.push(`entry: ${plan6.entryFile}`);
       lines.push("");
     }
-    if (plan4.dependencyEdits.length > 0) {
+    if (plan6.dependencyEdits.length > 0) {
       lines.push("### dependencies");
       const byFile = /* @__PURE__ */ new Map();
-      for (const dep of plan4.dependencyEdits) {
+      for (const dep of plan6.dependencyEdits) {
         const base = dep.file.split(/[\\/]/).pop() ?? dep.file;
         if (FORBIDDEN_LOCKFILES.has(base)) {
           throw new Error(
@@ -3186,9 +3699,9 @@ function renderPatch(sections) {
       }
       lines.push("");
     }
-    if (plan4.generatedFiles && plan4.generatedFiles.length > 0) {
+    if (plan6.generatedFiles && plan6.generatedFiles.length > 0) {
       lines.push("### generated files");
-      for (const gen of plan4.generatedFiles) {
+      for (const gen of plan6.generatedFiles) {
         lines.push(`--- (new file) ${gen.file}`);
         for (const ln of gen.contents.split(/\r?\n/)) {
           lines.push(`+ ${ln}`);
@@ -3196,26 +3709,26 @@ function renderPatch(sections) {
       }
       lines.push("");
     }
-    if (plan4.entrypointEdits.length > 0) {
+    if (plan6.entrypointEdits.length > 0) {
       lines.push("### entry-point injection");
-      for (const e of plan4.entrypointEdits) {
+      for (const e of plan6.entrypointEdits) {
         lines.push(`--- ${e.file}`);
         lines.push(`+ ${e.after}`);
         lines.push(`  ${e.before}`);
       }
       lines.push("");
     }
-    if (plan4.envEdits.length > 0) {
+    if (plan6.envEdits.length > 0) {
       lines.push("### env (written to <package-dir>/.env.neat)");
-      for (const env of plan4.envEdits) {
+      for (const env of plan6.envEdits) {
         lines.push(`- ${env.key}=${env.value}`);
       }
       lines.push("");
     }
-    if (plan4.nextConfigEdit) {
+    if (plan6.nextConfigEdit) {
       lines.push("### next.config (framework flag)");
-      lines.push(`--- ${plan4.nextConfigEdit.file}`);
-      lines.push(`+ experimental: { instrumentationHook: true }, // ${plan4.nextConfigEdit.reason}`);
+      lines.push(`--- ${plan6.nextConfigEdit.file}`);
+      lines.push(`+ experimental: { instrumentationHook: true }, // ${plan6.nextConfigEdit.reason}`);
       lines.push("");
     }
   }
@@ -3223,10 +3736,10 @@ function renderPatch(sections) {
 }
 
 // src/orchestrator.ts
-import { promises as fs7 } from "fs";
+import { promises as fs9 } from "fs";
 import http from "http";
 import net from "net";
-import path8 from "path";
+import path10 from "path";
 import { fileURLToPath as fileURLToPath2 } from "url";
 import { spawn as spawn2 } from "child_process";
 import readline from "readline";
@@ -3236,7 +3749,7 @@ async function extractAndPersist(opts) {
   const graphKey = opts.projectExplicit ? opts.project : DEFAULT_PROJECT;
   resetGraph(graphKey);
   const graph = getGraph(graphKey);
-  const projectPaths = pathsForProject(graphKey, path8.join(opts.scanPath, "neat-out"));
+  const projectPaths = pathsForProject(graphKey, path10.join(opts.scanPath, "neat-out"));
   const extraction = await extractFromDirectory(graph, opts.scanPath, {
     errorsPath: projectPaths.errorsPath
   });
@@ -3267,28 +3780,34 @@ async function applyInstallersOver(services, project, options = {}) {
   let cloudflareWorkers = 0;
   let electron = 0;
   const installPlans = /* @__PURE__ */ new Map();
+  const dependencyInstructions = /* @__PURE__ */ new Map();
   for (const svc of services) {
     const installer = await pickInstaller(svc.dir);
     if (!installer) continue;
-    const plan4 = await installer.plan(svc.dir, { project });
-    if (isEmptyPlan(plan4) && !plan4.libOnly && plan4.runtimeKind === void 0) {
+    const plan6 = await installer.plan(svc.dir, { project });
+    if (isEmptyPlan(plan6) && !plan6.libOnly && plan6.runtimeKind === void 0) {
       already++;
       continue;
     }
-    const outcome = await installer.apply(plan4);
+    const outcome = await installer.apply(plan6);
     if (outcome.outcome === "instrumented") {
       instrumented++;
-      if (plan4.dependencyEdits.length > 0) {
-        const cmd = await resolveManager(svc.dir);
-        const key = `${cmd.pm}:${cmd.cwd}`;
-        if (!installPlans.has(key)) installPlans.set(key, cmd);
+      if (plan6.dependencyEdits.length > 0) {
+        const manifest = path10.basename(plan6.dependencyEdits[0].file);
+        if (manifest === "package.json") {
+          const cmd = await resolveManager(svc.dir);
+          const key = `${cmd.pm}:${cmd.cwd}`;
+          if (!installPlans.has(key)) installPlans.set(key, cmd);
+        } else if (outcome.followUpInstall) {
+          dependencyInstructions.set(svc.dir, outcome.followUpInstall);
+        }
       }
     } else if (outcome.outcome === "already-instrumented") already++;
     else if (outcome.outcome === "lib-only") {
       libOnly++;
       const appDeps = svc.pkg ? appFrameworkDependencies(svc.pkg) : [];
       if (appDeps.length > 0) {
-        const svcName = path8.basename(svc.dir);
+        const svcName = path10.basename(svc.dir);
         const list = appDeps.join(", ");
         console.warn(
           `neat: runtime layer won't engage for ${svcName}: no entry point found.
@@ -3301,7 +3820,7 @@ async function applyInstallersOver(services, project, options = {}) {
       console.log(`skipping ${svc.dir}: browser bundle; browser-OTel support lands in a future release.`);
     } else if (outcome.outcome === "react-native") {
       reactNative++;
-      const svcName = path8.basename(svc.dir);
+      const svcName = path10.basename(svc.dir);
       console.log(
         `neat: ${svc.dir} detected as React Native / Expo
   The installer doesn't cover this runtime deterministically.
@@ -3312,7 +3831,7 @@ async function applyInstallersOver(services, project, options = {}) {
       );
     } else if (outcome.outcome === "bun") {
       bun++;
-      const svcName = path8.basename(svc.dir);
+      const svcName = path10.basename(svc.dir);
       console.log(
         `neat: ${svc.dir} detected as Bun
   The installer doesn't cover this runtime deterministically.
@@ -3323,7 +3842,7 @@ async function applyInstallersOver(services, project, options = {}) {
       );
     } else if (outcome.outcome === "deno") {
       deno++;
-      const svcName = path8.basename(svc.dir);
+      const svcName = path10.basename(svc.dir);
       console.log(
         `neat: ${svc.dir} detected as Deno
   The installer doesn't cover this runtime deterministically.
@@ -3334,7 +3853,7 @@ async function applyInstallersOver(services, project, options = {}) {
       );
     } else if (outcome.outcome === "cloudflare-workers") {
       cloudflareWorkers++;
-      const svcName = path8.basename(svc.dir);
+      const svcName = path10.basename(svc.dir);
       console.log(
         `neat: ${svc.dir} detected as Cloudflare Workers
   The installer doesn't cover this runtime deterministically.
@@ -3345,7 +3864,7 @@ async function applyInstallersOver(services, project, options = {}) {
       );
     } else if (outcome.outcome === "electron") {
       electron++;
-      const svcName = path8.basename(svc.dir);
+      const svcName = path10.basename(svc.dir);
       console.log(
         `neat: ${svc.dir} detected as Electron
   The installer doesn't cover this runtime deterministically.
@@ -3358,7 +3877,7 @@ async function applyInstallersOver(services, project, options = {}) {
     if (svc.pkg && (outcome.outcome === "instrumented" || outcome.outcome === "already-instrumented")) {
       const gaps = uninstrumentedLibraries(svc.pkg);
       if (gaps.length > 0) {
-        const svcName = path8.basename(svc.dir);
+        const svcName = path10.basename(svc.dir);
         const list = gaps.join(", ");
         const subject = gaps.length === 1 ? "this library" : "these libraries";
         const aux = gaps.length === 1 ? "isn't" : "aren't";
@@ -3386,6 +3905,11 @@ async function applyInstallersOver(services, project, options = {}) {
       }
     }
   }
+  for (const [dir, command] of dependencyInstructions) {
+    console.log(
+      `neat: dependencies staged in ${dir}; run \`${command}\` to install them \u2014 NEAT does not run it for you.`
+    );
+  }
   return {
     instrumented,
     alreadyInstrumented: already,
@@ -3396,7 +3920,8 @@ async function applyInstallersOver(services, project, options = {}) {
     deno,
     cloudflareWorkers,
     electron,
-    packageManagerInstalls
+    packageManagerInstalls,
+    dependencyInstructions: [...dependencyInstructions].map(([dir, command]) => ({ dir, command }))
   };
 }
 async function promptYesNo(question) {
@@ -3564,24 +4089,24 @@ async function persistedPortsFor(scanPath) {
   return { rest: record.ports.rest, otlp: record.ports.otlp, web: record.ports.web };
 }
 async function acquireSpawnLock(scanPath) {
-  const lockPath = path8.join(scanPath, "neat-out", "daemon.spawn.lock");
-  await fs7.mkdir(path8.dirname(lockPath), { recursive: true });
+  const lockPath = path10.join(scanPath, "neat-out", "daemon.spawn.lock");
+  await fs9.mkdir(path10.dirname(lockPath), { recursive: true });
   const STALE_LOCK_MS = 6e4;
   try {
-    const fd = await fs7.open(lockPath, "wx");
+    const fd = await fs9.open(lockPath, "wx");
     await fd.writeFile(`${process.pid}
 `, "utf8");
     await fd.close();
     return async () => {
-      await fs7.unlink(lockPath).catch(() => {
+      await fs9.unlink(lockPath).catch(() => {
       });
     };
   } catch (err) {
     if (err.code !== "EEXIST") return null;
     try {
-      const stat = await fs7.stat(lockPath);
+      const stat = await fs9.stat(lockPath);
       if (Date.now() - stat.mtimeMs > STALE_LOCK_MS) {
-        await fs7.unlink(lockPath).catch(() => {
+        await fs9.unlink(lockPath).catch(() => {
         });
         return acquireSpawnLock(scanPath);
       }
@@ -3610,13 +4135,13 @@ async function healthIsForProject(restPort, project) {
   return false;
 }
 function daemonLogPath(projectPath3) {
-  return path8.join(projectPath3, "neat-out", "daemon.log");
+  return path10.join(projectPath3, "neat-out", "daemon.log");
 }
 function spawnDaemonDetached(spec) {
-  const here = path8.dirname(fileURLToPath2(import.meta.url));
+  const here = path10.dirname(fileURLToPath2(import.meta.url));
   const candidates = [
-    path8.join(here, "neatd.cjs"),
-    path8.join(here, "neatd.js")
+    path10.join(here, "neatd.cjs"),
+    path10.join(here, "neatd.js")
   ];
   let entry2 = null;
   const fsSync = __require("fs");
@@ -3646,7 +4171,7 @@ function spawnDaemonDetached(spec) {
   let logFd = null;
   if (spec) {
     const logPath = daemonLogPath(spec.projectPath);
-    fsSync.mkdirSync(path8.dirname(logPath), { recursive: true });
+    fsSync.mkdirSync(path10.dirname(logPath), { recursive: true });
     logFd = fsSync.openSync(logPath, "a");
   }
   const child = spawn2(process.execPath, [entry2, "start"], {
@@ -3685,7 +4210,7 @@ async function runOrchestrator(opts) {
       browser: "skipped"
     }
   };
-  const stat = await fs7.stat(opts.scanPath).catch(() => null);
+  const stat = await fs9.stat(opts.scanPath).catch(() => null);
   if (!stat || !stat.isDirectory()) {
     console.error(`neat: ${opts.scanPath} is not a directory`);
     result.exitCode = 2;
@@ -3845,7 +4370,7 @@ async function runOrchestrator(opts) {
     result.steps.browser = openBrowser(dashboardUrl);
   }
   const daemonRunning = result.steps.daemon === "spawned" || result.steps.daemon === "already-running";
-  const daemonLog = daemonRunning ? path8.relative(opts.scanPath, daemonLogPath(opts.scanPath)) : null;
+  const daemonLog = daemonRunning ? path10.relative(opts.scanPath, daemonLogPath(opts.scanPath)) : null;
   printSummary(result, graph, dashboardUrl, daemonLog);
   return result;
 }
@@ -4302,27 +4827,27 @@ async function runConnectorCommand(rawArgs, deps = {}) {
 }
 
 // src/hooks-cli.ts
-import path9 from "path";
+import path11 from "path";
 import os from "os";
-import { promises as fs8 } from "fs";
+import { promises as fs10 } from "fs";
 import { fileURLToPath as fileURLToPath3 } from "url";
 var HOOK_FILENAME = "neat-search-nudge.mjs";
 var GUIDE_FILENAME = "GRAPH_FIRST.md";
 var GUIDE_INSTALL_NAME = "neat-graph-first.md";
 var HOOK_MATCHER = "Grep|Glob|Bash";
 function moduleDir() {
-  return typeof __dirname !== "undefined" ? __dirname : path9.dirname(fileURLToPath3(import.meta.url));
+  return typeof __dirname !== "undefined" ? __dirname : path11.dirname(fileURLToPath3(import.meta.url));
 }
 async function readSkillAsset(rel) {
   const here = moduleDir();
   const candidates = [
-    path9.resolve(here, "../../claude-skill", rel),
-    path9.resolve(here, "../../../claude-skill", rel),
-    path9.resolve(here, "../claude-skill", rel)
+    path11.resolve(here, "../../claude-skill", rel),
+    path11.resolve(here, "../../../claude-skill", rel),
+    path11.resolve(here, "../claude-skill", rel)
   ];
   for (const candidate of candidates) {
     try {
-      return await fs8.readFile(candidate, "utf8");
+      return await fs10.readFile(candidate, "utf8");
     } catch {
     }
   }
@@ -4332,17 +4857,17 @@ async function readSkillAsset(rel) {
 }
 function neatHome() {
   const override = process.env.NEAT_HOME;
-  if (override && override.length > 0) return path9.resolve(override);
-  return path9.join(os.homedir(), ".neat");
+  if (override && override.length > 0) return path11.resolve(override);
+  return path11.join(os.homedir(), ".neat");
 }
 function claudeSettingsPath() {
   const override = process.env.NEAT_CLAUDE_SETTINGS;
-  if (override && override.length > 0) return path9.resolve(override);
+  if (override && override.length > 0) return path11.resolve(override);
   const home = process.env.HOME ?? process.env.USERPROFILE ?? os.homedir();
-  return path9.join(home, ".claude", "settings.json");
+  return path11.join(home, ".claude", "settings.json");
 }
 function installedHookPath() {
-  return path9.join(neatHome(), "hooks", HOOK_FILENAME);
+  return path11.join(neatHome(), "hooks", HOOK_FILENAME);
 }
 function isNeatSearchEntry(entry2) {
   return (entry2.hooks ?? []).some(
@@ -4375,14 +4900,14 @@ async function runHooks(opts) {
     const hookScript = await readSkillAsset(`hooks/${HOOK_FILENAME}`);
     const guide = await readSkillAsset(GUIDE_FILENAME);
     const scriptPath = installedHookPath();
-    await fs8.mkdir(path9.dirname(scriptPath), { recursive: true });
-    await fs8.writeFile(scriptPath, hookScript, { mode: 493 });
-    const guidePath = path9.join(neatHome(), GUIDE_INSTALL_NAME);
-    await fs8.writeFile(guidePath, guide, "utf8");
+    await fs10.mkdir(path11.dirname(scriptPath), { recursive: true });
+    await fs10.writeFile(scriptPath, hookScript, { mode: 493 });
+    const guidePath = path11.join(neatHome(), GUIDE_INSTALL_NAME);
+    await fs10.writeFile(guidePath, guide, "utf8");
     const settingsFile = claudeSettingsPath();
     let settings = {};
     try {
-      settings = JSON.parse(await fs8.readFile(settingsFile, "utf8"));
+      settings = JSON.parse(await fs10.readFile(settingsFile, "utf8"));
     } catch (err) {
       if (err.code !== "ENOENT") {
         console.error(
@@ -4404,8 +4929,8 @@ async function runHooks(opts) {
       ...settings,
       hooks: { ...hooks, PreToolUse: preToolUse }
     };
-    await fs8.mkdir(path9.dirname(settingsFile), { recursive: true });
-    await fs8.writeFile(settingsFile, JSON.stringify(merged, null, 2) + "\n", "utf8");
+    await fs10.mkdir(path11.dirname(settingsFile), { recursive: true });
+    await fs10.writeFile(settingsFile, JSON.stringify(merged, null, 2) + "\n", "utf8");
     console.log(`neat hooks: installed the search-nudge hook`);
     console.log(`  script:   ${scriptPath}`);
     console.log(`  settings: ${settingsFile} (PreToolUse \u2192 ${HOOK_MATCHER})`);
@@ -4475,9 +5000,9 @@ async function runHooksCommand(args) {
 }
 
 // src/codex-cli.ts
-import path10 from "path";
+import path12 from "path";
 import os2 from "os";
-import { promises as fs9 } from "fs";
+import { promises as fs11 } from "fs";
 import { isDeepStrictEqual } from "util";
 import { parse as parseToml, stringify as stringifyToml } from "smol-toml";
 var CODEX_MCP_SERVER = {
@@ -4495,14 +5020,14 @@ var NEAT_GRAPH_FIRST_START = "<!-- neat:graph-first -->";
 var NEAT_GRAPH_FIRST_END = "<!-- /neat:graph-first -->";
 function codexConfigPath() {
   const override = process.env.NEAT_CODEX_CONFIG;
-  if (override && override.length > 0) return path10.resolve(override);
+  if (override && override.length > 0) return path12.resolve(override);
   const home = process.env.HOME ?? process.env.USERPROFILE ?? os2.homedir();
-  return path10.join(home, ".codex", "config.toml");
+  return path12.join(home, ".codex", "config.toml");
 }
 function agentsFilePath() {
   const override = process.env.NEAT_CODEX_AGENTS;
-  if (override && override.length > 0) return path10.resolve(override);
-  return path10.join(process.cwd(), "AGENTS.md");
+  if (override && override.length > 0) return path12.resolve(override);
+  return path12.join(process.cwd(), "AGENTS.md");
 }
 function isTableHeader(line) {
   return /^\s*\[\[?[^\]]+\]\]?\s*$/.test(line);
@@ -4636,7 +5161,7 @@ async function runCodex(opts) {
   const agentsPath = agentsFilePath();
   let configRaw = "";
   try {
-    configRaw = await fs9.readFile(configPath, "utf8");
+    configRaw = await fs11.readFile(configPath, "utf8");
   } catch (err) {
     if (err.code !== "ENOENT") {
       console.error(`neat codex: failed to read ${configPath} \u2014 ${err.message}`);
@@ -4645,7 +5170,7 @@ async function runCodex(opts) {
   }
   let agentsRaw = "";
   try {
-    agentsRaw = await fs9.readFile(agentsPath, "utf8");
+    agentsRaw = await fs11.readFile(agentsPath, "utf8");
   } catch (err) {
     if (err.code !== "ENOENT") {
       console.error(`neat codex: failed to read ${agentsPath} \u2014 ${err.message}`);
@@ -4685,15 +5210,15 @@ async function runCodex(opts) {
     return { exitCode: 0 };
   }
   if (config.changed) {
-    await fs9.mkdir(path10.dirname(configPath), { recursive: true });
-    await fs9.writeFile(configPath, config.text, "utf8");
+    await fs11.mkdir(path12.dirname(configPath), { recursive: true });
+    await fs11.writeFile(configPath, config.text, "utf8");
     console.log(`neat codex: wrote [mcp_servers.neat] to ${configPath}`);
   } else {
     console.log(`neat codex: ${configPath} already has NEAT's MCP server`);
   }
   if (agents.changed) {
-    await fs9.mkdir(path10.dirname(agentsPath), { recursive: true });
-    await fs9.writeFile(agentsPath, agents.text, "utf8");
+    await fs11.mkdir(path12.dirname(agentsPath), { recursive: true });
+    await fs11.writeFile(agentsPath, agents.text, "utf8");
     console.log(`neat codex: wrote the graph-first block to ${agentsPath}`);
   } else {
     console.log(`neat codex: ${agentsPath} already has the graph-first block`);
@@ -4749,9 +5274,9 @@ async function runCodexCommand(args) {
 }
 
 // src/editors-cli.ts
-import path11 from "path";
+import path13 from "path";
 import os3 from "os";
-import { promises as fs10 } from "fs";
+import { promises as fs12 } from "fs";
 import { isDeepStrictEqual as isDeepStrictEqual2 } from "util";
 import * as jsonc from "jsonc-parser";
 var NEAT_MCP_SERVER = {
@@ -4775,17 +5300,17 @@ function homeDir() {
 }
 function xdgConfigDir() {
   const xdg = process.env.XDG_CONFIG_HOME;
-  return xdg && xdg.length > 0 ? path11.resolve(xdg) : path11.join(homeDir(), ".config");
+  return xdg && xdg.length > 0 ? path13.resolve(xdg) : path13.join(homeDir(), ".config");
 }
 function envOverride(name) {
   const v = process.env[name];
-  return v && v.length > 0 ? path11.resolve(v) : void 0;
+  return v && v.length > 0 ? path13.resolve(v) : void 0;
 }
 var CURSOR_CLIENT = {
   id: "cursor",
   label: "Cursor",
   docsUrl: "https://docs.cursor.com/context/mcp",
-  mcpConfigPath: () => envOverride("NEAT_CURSOR_CONFIG") ?? path11.join(homeDir(), ".cursor", "mcp.json"),
+  mcpConfigPath: () => envOverride("NEAT_CURSOR_CONFIG") ?? path13.join(homeDir(), ".cursor", "mcp.json"),
   mcpContainerKey: "mcpServers",
   format: "json",
   // Cursor still reads a single `.cursorrules` at the project root (the modern
@@ -4797,7 +5322,7 @@ var DEVIN_CLIENT = {
   id: "devin",
   label: "Devin Desktop (Cascade)",
   docsUrl: "https://docs.devin.ai/desktop/cascade/mcp",
-  mcpConfigPath: () => envOverride("NEAT_DEVIN_CONFIG") ?? path11.join(homeDir(), ".codeium", "windsurf", "mcp_config.json"),
+  mcpConfigPath: () => envOverride("NEAT_DEVIN_CONFIG") ?? path13.join(homeDir(), ".codeium", "windsurf", "mcp_config.json"),
   mcpContainerKey: "mcpServers",
   format: "json",
   rulesFileName: ".windsurfrules"
@@ -4806,7 +5331,7 @@ var GEMINI_CLIENT = {
   id: "gemini",
   label: "Gemini CLI",
   docsUrl: "https://github.com/google-gemini/gemini-cli/blob/main/docs/tools/mcp-server.md",
-  mcpConfigPath: () => envOverride("NEAT_GEMINI_CONFIG") ?? path11.join(homeDir(), ".gemini", "settings.json"),
+  mcpConfigPath: () => envOverride("NEAT_GEMINI_CONFIG") ?? path13.join(homeDir(), ".gemini", "settings.json"),
   mcpContainerKey: "mcpServers",
   format: "json",
   rulesFileName: "GEMINI.md"
@@ -4815,7 +5340,7 @@ var QWEN_CLIENT = {
   id: "qwen",
   label: "Qwen Code",
   docsUrl: "https://qwenlm.github.io/qwen-code-docs/en/users/features/mcp/",
-  mcpConfigPath: () => envOverride("NEAT_QWEN_CONFIG") ?? path11.join(homeDir(), ".qwen", "settings.json"),
+  mcpConfigPath: () => envOverride("NEAT_QWEN_CONFIG") ?? path13.join(homeDir(), ".qwen", "settings.json"),
   mcpContainerKey: "mcpServers",
   format: "json",
   rulesFileName: "QWEN.md"
@@ -4824,7 +5349,7 @@ var AMAZONQ_CLIENT = {
   id: "amazonq",
   label: "Amazon Q Developer CLI",
   docsUrl: "https://docs.aws.amazon.com/amazonq/latest/qdeveloper-ug/command-line-mcp-configuration.html",
-  mcpConfigPath: () => envOverride("NEAT_AMAZONQ_CONFIG") ?? path11.join(homeDir(), ".aws", "amazonq", "mcp.json"),
+  mcpConfigPath: () => envOverride("NEAT_AMAZONQ_CONFIG") ?? path13.join(homeDir(), ".aws", "amazonq", "mcp.json"),
   mcpContainerKey: "mcpServers",
   format: "json"
 };
@@ -4832,7 +5357,7 @@ var ROOCODE_CLIENT = {
   id: "roocode",
   label: "Roo Code",
   docsUrl: "https://roocodeinc.github.io/Roo-Code/features/mcp/using-mcp-in-roo",
-  mcpConfigPath: () => envOverride("NEAT_ROOCODE_CONFIG") ?? path11.join(process.cwd(), ".roo", "mcp.json"),
+  mcpConfigPath: () => envOverride("NEAT_ROOCODE_CONFIG") ?? path13.join(process.cwd(), ".roo", "mcp.json"),
   mcpContainerKey: "mcpServers",
   format: "json"
 };
@@ -4845,9 +5370,9 @@ var ZED_CLIENT = {
     if (override) return override;
     if (process.platform === "win32") {
       const appData = process.env.APPDATA;
-      if (appData && appData.length > 0) return path11.join(appData, "Zed", "settings.json");
+      if (appData && appData.length > 0) return path13.join(appData, "Zed", "settings.json");
     }
-    return path11.join(homeDir(), ".config", "zed", "settings.json");
+    return path13.join(homeDir(), ".config", "zed", "settings.json");
   },
   mcpContainerKey: "context_servers",
   format: "jsonc",
@@ -4857,7 +5382,7 @@ var OPENCODE_CLIENT = {
   id: "opencode",
   label: "OpenCode",
   docsUrl: "https://opencode.ai/docs/mcp-servers/",
-  mcpConfigPath: () => envOverride("NEAT_OPENCODE_CONFIG") ?? path11.join(xdgConfigDir(), "opencode", "opencode.json"),
+  mcpConfigPath: () => envOverride("NEAT_OPENCODE_CONFIG") ?? path13.join(xdgConfigDir(), "opencode", "opencode.json"),
   mcpContainerKey: "mcp",
   format: "json",
   serverEntry: NEAT_OPENCODE_SERVER,
@@ -4867,7 +5392,7 @@ var CRUSH_CLIENT = {
   id: "crush",
   label: "Crush",
   docsUrl: "https://charmbracelet-crush.mintlify.app/configuration/mcp",
-  mcpConfigPath: () => envOverride("NEAT_CRUSH_CONFIG") ?? path11.join(xdgConfigDir(), "crush", "crush.json"),
+  mcpConfigPath: () => envOverride("NEAT_CRUSH_CONFIG") ?? path13.join(xdgConfigDir(), "crush", "crush.json"),
   mcpContainerKey: "mcp",
   format: "json",
   serverEntry: NEAT_CRUSH_SERVER,
@@ -4930,7 +5455,7 @@ async function planMcp(client, mcpPath) {
   const serverEntry = client.serverEntry ?? NEAT_MCP_SERVER;
   let raw = "";
   try {
-    raw = await fs10.readFile(mcpPath, "utf8");
+    raw = await fs12.readFile(mcpPath, "utf8");
   } catch (err) {
     const e = err;
     if (e.code === "ENOENT") {
@@ -4972,7 +5497,7 @@ async function runEditorInstall(client, opts) {
   const mcpPath = client.mcpConfigPath();
   const serverEntry = client.serverEntry ?? NEAT_MCP_SERVER;
   const hasRules = typeof client.rulesFileName === "string";
-  const rulesPath = hasRules ? path11.join(opts.projectDir, client.rulesFileName) : "";
+  const rulesPath = hasRules ? path13.join(opts.projectDir, client.rulesFileName) : "";
   const mcp = await planMcp(client, mcpPath);
   if (mcp === null) return { exitCode: 1 };
   let existingRules = "";
@@ -4981,7 +5506,7 @@ async function runEditorInstall(client, opts) {
   let block = "";
   if (hasRules) {
     try {
-      existingRules = await fs10.readFile(rulesPath, "utf8");
+      existingRules = await fs12.readFile(rulesPath, "utf8");
     } catch (err) {
       if (err.code !== "ENOENT") {
         console.error(`neat ${client.id}: failed to read ${rulesPath} \u2014 ${err.message}`);
@@ -5015,11 +5540,11 @@ async function runEditorInstall(client, opts) {
     );
     return { exitCode: 0 };
   }
-  await fs10.mkdir(path11.dirname(mcpPath), { recursive: true });
-  await fs10.writeFile(mcpPath, mcp.text, "utf8");
+  await fs12.mkdir(path13.dirname(mcpPath), { recursive: true });
+  await fs12.writeFile(mcpPath, mcp.text, "utf8");
   if (hasRules) {
-    await fs10.mkdir(path11.dirname(rulesPath), { recursive: true });
-    await fs10.writeFile(rulesPath, newRules, "utf8");
+    await fs12.mkdir(path13.dirname(rulesPath), { recursive: true });
+    await fs12.writeFile(rulesPath, newRules, "utf8");
   }
   console.log(`neat ${client.id}: wired NEAT into ${client.label}`);
   console.log(`  MCP server: ${mcpPath} (${client.mcpContainerKey}.neat \u2192 npx -y @neat.is/mcp)`);
@@ -5055,11 +5580,11 @@ function usage3(client) {
 }
 async function runEditorCommand(clientId, args, projectDir = process.cwd()) {
   const client = CLIENTS[clientId];
-  let apply4 = false;
+  let apply6 = false;
   for (const arg of args) {
     switch (arg) {
       case "--apply":
-        apply4 = true;
+        apply6 = true;
         break;
       case "-h":
       case "--help":
@@ -5072,7 +5597,7 @@ async function runEditorCommand(clientId, args, projectDir = process.cwd()) {
     }
   }
   try {
-    const { exitCode } = await runEditorInstall(client, { apply: apply4, projectDir });
+    const { exitCode } = await runEditorInstall(client, { apply: apply6, projectDir });
     return exitCode;
   } catch (err) {
     console.error(err.message);
@@ -5109,10 +5634,10 @@ function createHttpClient(baseUrl, bearerToken) {
   const root = baseUrl.replace(/\/$/, "");
   const authHeader = bearerToken && bearerToken.length > 0 ? { authorization: `Bearer ${bearerToken}` } : {};
   return {
-    async get(path14) {
+    async get(path16) {
       let res;
       try {
-        res = await fetch(`${root}${path14}`, {
+        res = await fetch(`${root}${path16}`, {
           headers: { ...authHeader }
         });
       } catch (err) {
@@ -5124,16 +5649,16 @@ function createHttpClient(baseUrl, bearerToken) {
         const body = await res.text().catch(() => "");
         throw new HttpError(
           res.status,
-          `${res.status} ${res.statusText} on GET ${path14}: ${body}`,
+          `${res.status} ${res.statusText} on GET ${path16}: ${body}`,
           body
         );
       }
       return await res.json();
     },
-    async post(path14, body) {
+    async post(path16, body) {
       let res;
       try {
-        res = await fetch(`${root}${path14}`, {
+        res = await fetch(`${root}${path16}`, {
           method: "POST",
           headers: { "content-type": "application/json", ...authHeader },
           body: JSON.stringify(body)
@@ -5147,7 +5672,7 @@ function createHttpClient(baseUrl, bearerToken) {
         const text = await res.text().catch(() => "");
         throw new HttpError(
           res.status,
-          `${res.status} ${res.statusText} on POST ${path14}: ${text}`,
+          `${res.status} ${res.statusText} on POST ${path16}: ${text}`,
           text
         );
       }
@@ -5161,12 +5686,12 @@ function projectPath(project, suffix) {
 }
 async function runRootCause(client, input) {
   const qs = input.errorId ? `?errorId=${encodeURIComponent(input.errorId)}` : "";
-  const path14 = projectPath(
+  const path16 = projectPath(
     input.project,
     `/graph/root-cause/${encodeURIComponent(input.errorNode)}${qs}`
   );
   try {
-    const result = await client.get(path14);
+    const result = await client.get(path16);
     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}.` : "");
@@ -5192,12 +5717,12 @@ async function runRootCause(client, input) {
 }
 async function runBlastRadius(client, input) {
   const qs = input.depth !== void 0 ? `?depth=${input.depth}` : "";
-  const path14 = projectPath(
+  const path16 = projectPath(
     input.project,
     `/graph/blast-radius/${encodeURIComponent(input.nodeId)}${qs}`
   );
   try {
-    const result = await client.get(path14);
+    const result = await client.get(path16);
     if (result.totalAffected === 0) {
       return {
         summary: `${result.origin} has no dependents. Nothing else would break if it failed.`
@@ -5231,12 +5756,12 @@ function formatBlastEntry(n) {
 }
 async function runDependencies(client, input) {
   const depth = input.depth ?? 3;
-  const path14 = projectPath(
+  const path16 = projectPath(
     input.project,
     `/graph/dependencies/${encodeURIComponent(input.nodeId)}?depth=${depth}`
   );
   try {
-    const result = await client.get(path14);
+    const result = await client.get(path16);
     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}).`
@@ -5328,9 +5853,9 @@ function formatDuration(ms) {
   return `${Math.round(h / 24)}d`;
 }
 async function runIncidents(client, input) {
-  const path14 = input.nodeId ? projectPath(input.project, `/incidents/${encodeURIComponent(input.nodeId)}`) : projectPath(input.project, "/incidents");
+  const path16 = input.nodeId ? projectPath(input.project, `/incidents/${encodeURIComponent(input.nodeId)}`) : projectPath(input.project, "/incidents");
   try {
-    const body = await client.get(path14);
+    const body = await client.get(path16);
     const events = body.events;
     if (events.length === 0) {
       return {
@@ -5983,7 +6508,7 @@ function sleep(ms, signal) {
 }
 
 // src/cli-verbs.ts
-import path12 from "path";
+import path14 from "path";
 async function resolveProjectEntry(opts) {
   const entries = await listProjects();
   if (opts.project) {
@@ -5993,7 +6518,7 @@ async function resolveProjectEntry(opts) {
   const cwd = opts.cwd ?? process.cwd();
   const resolvedCwd = await normalizeProjectPath(cwd);
   for (const entry2 of entries) {
-    if (resolvedCwd === entry2.path || resolvedCwd.startsWith(`${entry2.path}${path12.sep}`)) {
+    if (resolvedCwd === entry2.path || resolvedCwd.startsWith(`${entry2.path}${path14.sep}`)) {
       return entry2;
     }
   }
@@ -6500,15 +7025,15 @@ async function buildPatchSections(services, project) {
   for (const svc of services) {
     const installer = await pickInstaller(svc.dir);
     if (!installer) continue;
-    const plan4 = await installer.plan(svc.dir, { project });
-    if (isEmptyPlan(plan4) && !plan4.libOnly && plan4.runtimeKind === void 0) continue;
-    sections.push({ installer: installer.name, plan: plan4 });
+    const plan6 = await installer.plan(svc.dir, { project });
+    if (isEmptyPlan(plan6) && !plan6.libOnly && plan6.runtimeKind === void 0) continue;
+    sections.push({ installer: installer.name, plan: plan6 });
   }
   return sections;
 }
 async function runInit(opts) {
   const written = [];
-  const stat = await fs11.stat(opts.scanPath).catch(() => null);
+  const stat = await fs13.stat(opts.scanPath).catch(() => null);
   if (!stat || !stat.isDirectory()) {
     console.error(`neat init: ${opts.scanPath} is not a directory`);
     return { exitCode: 2, writtenFiles: written };
@@ -6517,13 +7042,13 @@ async function runInit(opts) {
   printDiscoveryReport(opts, services);
   const sections = opts.noInstall ? [] : await buildPatchSections(services, opts.project);
   const patch = renderPatch(sections);
-  const patchPath = path13.join(opts.scanPath, "neat.patch");
+  const patchPath = path15.join(opts.scanPath, "neat.patch");
   if (opts.dryRun) {
-    await fs11.writeFile(patchPath, patch, "utf8");
+    await fs13.writeFile(patchPath, patch, "utf8");
     written.push(patchPath);
     console.log(`dry-run: patch written to ${patchPath}`);
-    const gitignorePath = path13.join(opts.scanPath, ".gitignore");
-    const gitignoreExists = await fs11.stat(gitignorePath).then(() => true).catch(() => false);
+    const gitignorePath = path15.join(opts.scanPath, ".gitignore");
+    const gitignoreExists = await fs13.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.");
@@ -6534,9 +7059,9 @@ async function runInit(opts) {
   const graph = getGraph(graphKey);
   const projectPaths = pathsForProject(
     graphKey,
-    path13.join(opts.scanPath, "neat-out")
+    path15.join(opts.scanPath, "neat-out")
   );
-  const errorsPath = path13.join(path13.dirname(opts.outPath), path13.basename(projectPaths.errorsPath));
+  const errorsPath = path15.join(path15.dirname(opts.outPath), path15.basename(projectPaths.errorsPath));
   const result = await extractFromDirectory(graph, opts.scanPath, { errorsPath });
   await saveGraphToDisk(graph, opts.outPath);
   written.push(opts.outPath);
@@ -6615,7 +7140,7 @@ async function runInit(opts) {
         console.log("Run `npm install` (or your language equivalent) to refresh lockfiles.");
       }
     } else {
-      await fs11.writeFile(patchPath, patch, "utf8");
+      await fs13.writeFile(patchPath, patch, "utf8");
       written.push(patchPath);
     }
   }
@@ -6655,9 +7180,9 @@ var CLAUDE_SKILL_CONFIG = {
 };
 function claudeConfigPath() {
   const override = process.env.NEAT_CLAUDE_CONFIG;
-  if (override && override.length > 0) return path13.resolve(override);
+  if (override && override.length > 0) return path15.resolve(override);
   const home = process.env.HOME ?? process.env.USERPROFILE ?? "";
-  return path13.join(home, ".claude.json");
+  return path15.join(home, ".claude.json");
 }
 async function runSkill(opts) {
   const snippet = JSON.stringify(CLAUDE_SKILL_CONFIG, null, 2) + "\n";
@@ -6669,7 +7194,7 @@ async function runSkill(opts) {
     const target = claudeConfigPath();
     let existing = {};
     try {
-      existing = JSON.parse(await fs11.readFile(target, "utf8"));
+      existing = JSON.parse(await fs13.readFile(target, "utf8"));
     } catch (err) {
       if (err.code !== "ENOENT") {
         console.error(`neat skill: failed to read ${target} \u2014 ${err.message}`);
@@ -6681,8 +7206,8 @@ async function runSkill(opts) {
       ...existing,
       mcpServers: { ...mcp, neat: CLAUDE_SKILL_CONFIG.mcpServers.neat }
     };
-    await fs11.mkdir(path13.dirname(target), { recursive: true });
-    await fs11.writeFile(target, JSON.stringify(merged, null, 2) + "\n", "utf8");
+    await fs13.mkdir(path15.dirname(target), { recursive: true });
+    await fs13.writeFile(target, JSON.stringify(merged, null, 2) + "\n", "utf8");
     console.log(`neat skill: wrote mcpServers.neat to ${target}`);
     console.log("restart Claude Code to pick up the new MCP server.");
     console.log("");
@@ -6755,7 +7280,7 @@ async function main() {
   }
   const cmd = argvParsed.positional[0];
   const parsed = { ...argvParsed, positional: argvParsed.positional.slice(1) };
-  const { positional, apply: apply4, dryRun, noInstall } = parsed;
+  const { positional, apply: apply6, dryRun, noInstall } = parsed;
   const project = parsed.project ?? DEFAULT_PROJECT;
   if (cmd === "init") {
     const target = positional[0];
@@ -6764,22 +7289,22 @@ async function main() {
       usage4();
       process.exit(2);
     }
-    if (apply4 && dryRun) {
+    if (apply6 && dryRun) {
       console.error("neat init: --apply and --dry-run are mutually exclusive");
       process.exit(2);
     }
-    const scanPath = path13.resolve(target);
+    const scanPath = path15.resolve(target);
     const projectExplicit = parsed.project !== null;
-    const projectName = projectExplicit ? project : path13.basename(scanPath);
+    const projectName = projectExplicit ? project : path15.basename(scanPath);
     const projectKey = projectExplicit ? project : DEFAULT_PROJECT;
-    const fallback = pathsForProject(projectKey, path13.join(scanPath, "neat-out")).snapshotPath;
-    const outPath = path13.resolve(process.env.NEAT_OUT_PATH ?? fallback);
+    const fallback = pathsForProject(projectKey, path15.join(scanPath, "neat-out")).snapshotPath;
+    const outPath = path15.resolve(process.env.NEAT_OUT_PATH ?? fallback);
     const result = await runInit({
       scanPath,
       outPath,
       project: projectName,
       projectExplicit,
-      apply: apply4,
+      apply: apply6,
       dryRun,
       noInstall,
       verbose: parsed.verbose
@@ -6794,21 +7319,21 @@ async function main() {
       usage4();
       process.exit(2);
     }
-    const scanPath = path13.resolve(target);
-    const stat = await fs11.stat(scanPath).catch(() => null);
+    const scanPath = path15.resolve(target);
+    const stat = await fs13.stat(scanPath).catch(() => null);
     if (!stat || !stat.isDirectory()) {
       console.error(`neat watch: ${scanPath} is not a directory`);
       process.exit(2);
     }
-    const projectPaths = pathsForProject(project, path13.join(scanPath, "neat-out"));
-    const outPath = path13.resolve(process.env.NEAT_OUT_PATH ?? projectPaths.snapshotPath);
-    const errorsPath = path13.resolve(
-      process.env.NEAT_ERRORS_PATH ?? path13.join(path13.dirname(outPath), path13.basename(projectPaths.errorsPath))
+    const projectPaths = pathsForProject(project, path15.join(scanPath, "neat-out"));
+    const outPath = path15.resolve(process.env.NEAT_OUT_PATH ?? projectPaths.snapshotPath);
+    const errorsPath = path15.resolve(
+      process.env.NEAT_ERRORS_PATH ?? path15.join(path15.dirname(outPath), path15.basename(projectPaths.errorsPath))
     );
-    const staleEventsPath = path13.resolve(
-      process.env.NEAT_STALE_EVENTS_PATH ?? path13.join(path13.dirname(outPath), path13.basename(projectPaths.staleEventsPath))
+    const staleEventsPath = path15.resolve(
+      process.env.NEAT_STALE_EVENTS_PATH ?? path15.join(path15.dirname(outPath), path15.basename(projectPaths.staleEventsPath))
     );
-    const embeddingsCachePath = process.env.NEAT_EMBEDDINGS_CACHE_PATH ? path13.resolve(process.env.NEAT_EMBEDDINGS_CACHE_PATH) : void 0;
+    const embeddingsCachePath = process.env.NEAT_EMBEDDINGS_CACHE_PATH ? path15.resolve(process.env.NEAT_EMBEDDINGS_CACHE_PATH) : void 0;
     const handle = await startWatch(getGraph(project), {
       scanPath,
       outPath,
@@ -6817,7 +7342,7 @@ async function main() {
       project,
       // Resolve NEAT_HOME so a `neat watch` picks up connectors added to
       // ~/.neat/connectors.json (#871). Same resolution the rest of the CLI uses.
-      neatHome: process.env.NEAT_HOME ? path13.resolve(process.env.NEAT_HOME) : path13.join(os4.homedir(), ".neat"),
+      neatHome: process.env.NEAT_HOME ? path15.resolve(process.env.NEAT_HOME) : path15.join(os4.homedir(), ".neat"),
       ...embeddingsCachePath ? { embeddingsCachePath } : {},
       host: process.env.HOST ?? "0.0.0.0",
       port: Number(process.env.PORT ?? 8080),
@@ -6999,11 +7524,11 @@ async function main() {
   process.exit(1);
 }
 async function tryOrchestrator(cmd, parsed) {
-  const scanPath = path13.resolve(cmd);
-  const stat = await fs11.stat(scanPath).catch(() => null);
+  const scanPath = path15.resolve(cmd);
+  const stat = await fs13.stat(scanPath).catch(() => null);
   if (!stat || !stat.isDirectory()) return null;
   const projectExplicit = parsed.project !== null;
-  const projectName = projectExplicit ? parsed.project : path13.basename(scanPath);
+  const projectName = projectExplicit ? parsed.project : path15.basename(scanPath);
   const result = await runOrchestrator({
     scanPath,
     project: projectName,