@neat.is/core 0.5.2 → 0.5.3

package/dist/cli.cjs

@@ -61,8 +61,8 @@ function mountBearerAuth(app, opts) {
   ]);
   const publicRead = opts.publicRead === true;
   app.addHook("preHandler", (req, reply, done) => {
-    const path61 = (req.url.split("?")[0] ?? "").replace(/\/+$/, "");
-    if (exactUnauthPaths.has(path61) || PROJECT_SCOPED_UNAUTH_PATTERN.test(path61)) {
+    const path62 = (req.url.split("?")[0] ?? "").replace(/\/+$/, "");
+    if (exactUnauthPaths.has(path62) || PROJECT_SCOPED_UNAUTH_PATTERN.test(path62)) {
       done();
       return;
     }
@@ -362,8 +362,8 @@ function websocketChannelPathOf(attrs) {
     const v = attrs[key];
     if (typeof v === "string" && v.length > 0) {
       const q = v.indexOf("?");
-      const path61 = q === -1 ? v : v.slice(0, q);
-      if (path61.length > 0) return path61;
+      const path62 = q === -1 ? v : v.slice(0, q);
+      if (path62.length > 0) return path62;
     }
   }
   return void 0;
@@ -686,12 +686,12 @@ __export(cli_exports, {
   runInit: () => runInit,
   runQueryVerb: () => runQueryVerb,
   runSkill: () => runSkill,
-  usage: () => usage
+  usage: () => usage2
 });
 module.exports = __toCommonJS(cli_exports);
 init_cjs_shims();
-var import_node_path60 = __toESM(require("path"), 1);
-var import_node_fs40 = require("fs");
+var import_node_path61 = __toESM(require("path"), 1);
+var import_node_fs41 = require("fs");
 
 // src/banner.ts
 init_cjs_shims();
@@ -1256,19 +1256,19 @@ function confidenceFromMix(edges, now = Date.now()) {
 function longestIncomingWalk(graph, start, maxDepth) {
   let best = { path: [start], edges: [] };
   const visited = /* @__PURE__ */ new Set([start]);
-  function step(node, path61, edges) {
-    if (path61.length > best.path.length) {
-      best = { path: [...path61], edges: [...edges] };
+  function step(node, path62, edges) {
+    if (path62.length > best.path.length) {
+      best = { path: [...path62], edges: [...edges] };
     }
-    if (path61.length - 1 >= maxDepth) return;
+    if (path62.length - 1 >= maxDepth) return;
     const incoming = bestEdgeBySource(graph, graph.inboundEdges(node));
     for (const [srcId, edge] of incoming) {
       if (visited.has(srcId)) continue;
       visited.add(srcId);
-      path61.push(srcId);
+      path62.push(srcId);
       edges.push(edge);
-      step(srcId, path61, edges);
-      path61.pop();
+      step(srcId, path62, edges);
+      path62.pop();
       edges.pop();
       visited.delete(srcId);
     }
@@ -1462,26 +1462,26 @@ function dominantFailingCall(graph, serviceId6, visited) {
   return best;
 }
 function followFailingCallChain(graph, originServiceId, maxDepth) {
-  const path61 = [originServiceId];
+  const path62 = [originServiceId];
   const edges = [];
   const visited = /* @__PURE__ */ new Set([originServiceId]);
   let current = originServiceId;
   for (let depth = 0; depth < maxDepth; depth++) {
     const hop = dominantFailingCall(graph, current, visited);
     if (!hop) break;
-    path61.push(hop.nextService);
+    path62.push(hop.nextService);
     edges.push(hop.edge);
     visited.add(hop.nextService);
     current = hop.nextService;
   }
   if (edges.length === 0) return null;
-  return { path: path61, edges, culprit: current };
+  return { path: path62, edges, culprit: current };
 }
 function crossServiceRootCause(graph, originId, incidents, errorEvent) {
   const chain = followFailingCallChain(graph, originId, ROOT_CAUSE_MAX_DEPTH);
   if (!chain) return null;
   const culprit = chain.culprit;
-  const path61 = [...chain.path];
+  const path62 = [...chain.path];
   const edgeProvenances = chain.edges.map((e) => e.provenance);
   const baseConfidence = confidenceFromMix(chain.edges);
   const confidence = Math.max(0, Math.min(1, baseConfidence * INCIDENT_ROOT_CAUSE_CONFIDENCE));
@@ -1489,14 +1489,14 @@ function crossServiceRootCause(graph, originId, incidents, errorEvent) {
   if (loc) {
     let rootCauseNode = culprit;
     if (loc.fileNode) {
-      path61.push(loc.fileNode);
+      path62.push(loc.fileNode);
       edgeProvenances.push(import_types.Provenance.OBSERVED);
       rootCauseNode = loc.fileNode;
     }
     return import_types.RootCauseResultSchema.parse({
       rootCauseNode,
       rootCauseReason: loc.rootCauseReason,
-      traversalPath: path61,
+      traversalPath: path62,
       edgeProvenances,
       confidence,
       ...loc.fixRecommendation ? { fixRecommendation: loc.fixRecommendation } : {}
@@ -1508,7 +1508,7 @@ function crossServiceRootCause(graph, originId, incidents, errorEvent) {
   return import_types.RootCauseResultSchema.parse({
     rootCauseNode: culprit,
     rootCauseReason: `${culpritName} is failing downstream calls (${errs} observed error${errs === 1 ? "" : "s"})`,
-    traversalPath: path61,
+    traversalPath: path62,
     edgeProvenances,
     confidence,
     fixRecommendation: `Inspect ${culpritName}'s failing handler`
@@ -4678,14 +4678,21 @@ function engineFromImage(image) {
 // src/extract/databases/dotenv.ts
 var CONNECTION_KEYS = /* @__PURE__ */ new Set([
   "DATABASE_URL",
+  "DATABASE_URI",
   "DB_URL",
+  "DB_URI",
   "POSTGRES_URL",
+  "POSTGRES_URI",
   "POSTGRESQL_URL",
+  "POSTGRESQL_URI",
   "MYSQL_URL",
+  "MYSQL_URI",
+  "MONGODB_URL",
   "MONGODB_URI",
   "MONGO_URL",
   "MONGO_URI",
-  "REDIS_URL"
+  "REDIS_URL",
+  "REDIS_URI"
 ]);
 function parseDotenvLine(line) {
   const trimmed = line.trim();
@@ -8198,11 +8205,42 @@ async function readPackageJson(scanPath) {
   const raw = await import_node_fs28.promises.readFile(pkgPath, "utf8");
   return JSON.parse(raw);
 }
+var HOOK_WALK_SKIP_DIRS = /* @__PURE__ */ new Set([
+  "node_modules",
+  "dist",
+  "build",
+  "out",
+  "coverage",
+  "neat-out"
+]);
 async function findHookFiles(scanPath) {
-  const entries = await import_node_fs28.promises.readdir(scanPath);
-  return entries.filter(
-    (e) => (e.startsWith("instrumentation") || e.startsWith("otel-init")) && /\.(ts|js)$/.test(e)
-  ).sort();
+  const found = [];
+  const walk3 = async (dir) => {
+    const entries = await import_node_fs28.promises.readdir(dir, { withFileTypes: true }).catch(() => []);
+    for (const entry2 of entries) {
+      if (entry2.isDirectory()) {
+        if (entry2.name.startsWith(".") || HOOK_WALK_SKIP_DIRS.has(entry2.name)) continue;
+        await walk3(import_node_path45.default.join(dir, entry2.name));
+      } else if (entry2.isFile()) {
+        if ((entry2.name.startsWith("instrumentation") || entry2.name.startsWith("otel-init")) && /\.(ts|js|cjs|mjs)$/.test(entry2.name)) {
+          const rel = import_node_path45.default.relative(scanPath, import_node_path45.default.join(dir, entry2.name));
+          found.push(rel.split(import_node_path45.default.sep).join("/"));
+        }
+      }
+    }
+  };
+  await walk3(scanPath);
+  return found.sort();
+}
+async function pickPrimaryHookFile(scanPath, hookFiles, snippet2) {
+  let fallback = null;
+  for (const file of hookFiles) {
+    const content = await import_node_fs28.promises.readFile(import_node_path45.default.join(scanPath, file), "utf8");
+    const patched = splicedContent(content, snippet2);
+    if (patched !== null) return { file, content, patched };
+    if (fallback === null) fallback = { file, content };
+  }
+  return { file: fallback.file, content: fallback.content, patched: null };
 }
 function extendLogPath() {
   return process.env.NEAT_EXTEND_LOG ?? import_node_path45.default.join(import_node_os2.default.homedir(), ".neat", "extend-log.ndjson");
@@ -8295,7 +8333,13 @@ async function applyExtension(ctx, args, options) {
       return { library: args.library, filesTouched: [], depsAdded: [], installOutput: "", alreadyApplied: true };
     }
   }
-  const primaryFile = hookFiles[0];
+  const primary = await pickPrimaryHookFile(ctx.scanPath, hookFiles, args.registration_snippet);
+  if (primary.patched === null) {
+    throw new Error(
+      `Could not find instrumentation insertion point in ${hookFiles.join(", ")}. Expected __INSTRUMENTATION_BLOCK__, instrumentations.push(, or new NodeSDK(.`
+    );
+  }
+  const primaryFile = primary.file;
   const primaryPath = import_node_path45.default.join(ctx.scanPath, primaryFile);
   const filesTouched = [];
   const depsAdded = [];
@@ -8307,14 +8351,7 @@ async function applyExtension(ctx, args, options) {
     filesTouched.push("package.json");
     depsAdded.push(`${args.instrumentation_package}@${args.version}`);
   }
-  const hookContent = await import_node_fs28.promises.readFile(primaryPath, "utf8");
-  const patched = splicedContent(hookContent, args.registration_snippet);
-  if (!patched) {
-    throw new Error(
-      `Could not find instrumentation insertion point in ${primaryFile}. Expected __INSTRUMENTATION_BLOCK__, instrumentations.push(, or new NodeSDK(.`
-    );
-  }
-  await import_node_fs28.promises.writeFile(primaryPath, patched, "utf8");
+  await import_node_fs28.promises.writeFile(primaryPath, primary.patched, "utf8");
   filesTouched.push(primaryFile);
   const cmd = await detectPackageManager(ctx.scanPath);
   const installer = options?.runInstall ?? runPackageManagerInstall;
@@ -8356,7 +8393,7 @@ async function dryRunExtension(ctx, args) {
       };
     }
   }
-  const primaryFile = hookFiles[0];
+  const primary = await pickPrimaryHookFile(ctx.scanPath, hookFiles, args.registration_snippet);
   const filesTouched = [];
   const depsToAdd = [];
   let packageJsonPatch = {};
@@ -8367,10 +8404,8 @@ async function dryRunExtension(ctx, args) {
     depsToAdd.push(`${args.instrumentation_package}@${args.version}`);
     filesTouched.push("package.json");
   }
-  const hookContent = await import_node_fs28.promises.readFile(import_node_path45.default.join(ctx.scanPath, primaryFile), "utf8");
-  const patched = splicedContent(hookContent, args.registration_snippet);
-  if (patched) {
-    filesTouched.push(primaryFile);
+  if (primary.patched !== null) {
+    filesTouched.push(primary.file);
     templatePatch = `+ ${args.registration_snippet}`;
   } else {
     templatePatch = "Could not find insertion point in hook file.";
@@ -9943,7 +9978,7 @@ function registerRoutes(scope, ctx) {
   });
 }
 async function buildApi(opts) {
-  const app = (0, import_fastify.default)({ logger: false });
+  const app = (0, import_fastify.default)({ logger: false, routerOptions: { maxParamLength: 1024 } });
   await app.register(import_cors.default, { origin: true });
   const env = readAuthEnv();
   const authToken = opts.authToken ?? env.authToken;
@@ -10451,17 +10486,20 @@ var SUPABASE_RPC_TARGET_KIND = "supabase-rpc";
 // src/connectors/supabase/map.ts
 var REST_RPC_PATH_RE = /^\/rest\/v1\/rpc\/([^/?]+)/;
 var REST_TABLE_PATH_RE = /^\/rest\/v1\/([^/?]+)/;
-function targetFromRestPath(path61) {
-  const rpcMatch = REST_RPC_PATH_RE.exec(path61);
+function targetFromRestPath(path62) {
+  const rpcMatch = REST_RPC_PATH_RE.exec(path62);
   if (rpcMatch) return { targetKind: SUPABASE_RPC_TARGET_KIND, name: rpcMatch[1] };
-  const tableMatch = REST_TABLE_PATH_RE.exec(path61);
+  const tableMatch = REST_TABLE_PATH_RE.exec(path62);
   if (tableMatch) return { targetKind: SUPABASE_TABLE_TARGET_KIND, name: tableMatch[1] };
   return null;
 }
 var ERROR_STATUS_THRESHOLD = 500;
 function mapEdgeLogRowsToSignals(rows) {
   const buckets2 = /* @__PURE__ */ new Map();
+  if (!Array.isArray(rows)) return [];
   for (const row of rows) {
+    if (!row || typeof row !== "object") continue;
+    if (typeof row.path !== "string" || typeof row.timestamp !== "string") continue;
     const target = targetFromRestPath(row.path);
     if (!target) continue;
     const key = `${target.targetKind}:${target.name}`;
@@ -10502,9 +10540,12 @@ function tableNameFromQueryText(query) {
 function diffPgStatStatementsToSignals(rows, previous, nowIso2) {
   const signals = [];
   const seen = /* @__PURE__ */ new Set();
+  if (!Array.isArray(rows)) return signals;
   for (const row of rows) {
-    seen.add(row.queryid);
+    if (!row || typeof row !== "object" || typeof row.queryid !== "string") continue;
     const calls = Number(row.calls);
+    if (!Number.isFinite(calls)) continue;
+    seen.add(row.queryid);
     const prior = previous.get(row.queryid);
     previous.set(row.queryid, { calls });
     if (!prior || calls < prior.calls) continue;
@@ -10828,7 +10869,12 @@ function upsertBucket(buckets2, key, isError, timestamp, build) {
 }
 function mapRailwayHttpLogsToSignals(entries, routeIndex) {
   const buckets2 = /* @__PURE__ */ new Map();
+  if (!Array.isArray(entries)) return [];
   for (const entry2 of entries) {
+    if (!entry2 || typeof entry2 !== "object") continue;
+    if (typeof entry2.method !== "string" || typeof entry2.path !== "string" || typeof entry2.timestamp !== "string") {
+      continue;
+    }
     const method = entry2.method.toUpperCase();
     const normalizedPath = normalizePathTemplate(entry2.path);
     const match = findRailwayRoute(routeIndex, method, normalizedPath);
@@ -10867,8 +10913,11 @@ function mapRailwayHttpLogsToSignals(entries, routeIndex) {
 }
 function mapRailwayNetworkFlowLogsToSignals(entries) {
   const buckets2 = /* @__PURE__ */ new Map();
+  if (!Array.isArray(entries)) return [];
   for (const entry2 of entries) {
-    if (!entry2.peerServiceId) continue;
+    if (!entry2 || typeof entry2 !== "object") continue;
+    if (typeof entry2.peerServiceId !== "string" || entry2.peerServiceId.length === 0) continue;
+    if (typeof entry2.timestamp !== "string") continue;
     const isError = entry2.dropCause !== null && entry2.dropCause !== "";
     upsertBucket(buckets2, entry2.peerServiceId, isError, entry2.timestamp, () => ({
       targetKind: PEER_SERVICE_TARGET_KIND,
@@ -10996,7 +11045,7 @@ async function fetchHttpRequestLogEntries(creds, sinceIso) {
       throw new Error(`Cloud Logging entries.list failed: ${res.status} ${res.statusText}`);
     }
     const json = await res.json();
-    out.push(...json.entries ?? []);
+    if (Array.isArray(json.entries)) out.push(...json.entries);
     if (!json.nextPageToken) break;
     pageToken = json.nextPageToken;
   }
@@ -11017,9 +11066,9 @@ function parseFirebaseTargetName(targetName) {
   const secondSep = rest.indexOf(FIELD_SEP);
   if (secondSep === -1) return null;
   const method = rest.slice(0, secondSep);
-  const path61 = rest.slice(secondSep + 1);
-  if (!resourceName || !method || !path61) return null;
-  return { resourceName, method, path: path61 };
+  const path62 = rest.slice(secondSep + 1);
+  if (!resourceName || !method || !path62) return null;
+  return { resourceName, method, path: path62 };
 }
 function resourceNameFor(type, labels) {
   if (!labels) return null;
@@ -11033,7 +11082,7 @@ function resourceNameFor(type, labels) {
   }
 }
 function pathFromRequestUrl(requestUrl) {
-  if (!requestUrl) return null;
+  if (typeof requestUrl !== "string" || requestUrl.length === 0) return null;
   if (requestUrl.startsWith("/")) {
     const withoutQuery = requestUrl.split("?")[0];
     return withoutQuery && withoutQuery.length > 0 ? withoutQuery : "/";
@@ -11048,22 +11097,23 @@ function pathFromRequestUrl(requestUrl) {
 }
 var ERROR_STATUS_THRESHOLD2 = 500;
 function mapLogEntryToSignal(entry2) {
+  if (!entry2 || typeof entry2 !== "object") return null;
   const resourceType = entry2.resource?.type;
   if (!resourceType || !isFirebaseResourceType(resourceType)) return null;
   const resourceName = resourceNameFor(resourceType, entry2.resource?.labels);
   if (!resourceName) return null;
   const req = entry2.httpRequest;
   if (!req) return null;
-  if (!req.requestMethod) return null;
+  if (typeof req.requestMethod !== "string" || req.requestMethod.length === 0) return null;
   const method = req.requestMethod.toUpperCase();
-  const path61 = pathFromRequestUrl(req.requestUrl);
-  if (path61 === null) return null;
+  const path62 = pathFromRequestUrl(req.requestUrl);
+  if (path62 === null) return null;
   const timestamp = entry2.timestamp;
-  if (!timestamp) return null;
+  if (typeof timestamp !== "string" || timestamp.length === 0) return null;
   const isError = typeof req.status === "number" && req.status >= ERROR_STATUS_THRESHOLD2;
   return {
     targetKind: resourceType,
-    targetName: packFirebaseTargetName({ resourceName, method, path: path61 }),
+    targetName: packFirebaseTargetName({ resourceName, method, path: path62 }),
     callCount: 1,
     errorCount: isError ? 1 : 0,
     lastObservedIso: timestamp
@@ -11211,7 +11261,7 @@ async function queryWorkerInvocations(ctx, config, window, fetchImpl = fetch) {
     throw new Error(`cloudflare connector: telemetry query returned an error (${message})`);
   }
   const events = payload.result?.events?.events;
-  if (events === void 0) {
+  if (!Array.isArray(events)) {
     console.warn(
       "[neat connector] cloudflare: telemetry query returned success:true but no result.events.events array \u2014 the response shape may have changed; treating as zero events this tick"
     );
@@ -11241,7 +11291,7 @@ var HTTP_METHODS = /* @__PURE__ */ new Set([
 ]);
 var LEADING_TOKEN_RE = /^(\S+)\s+\S/;
 function parseHttpMethodFromTrigger(trigger) {
-  if (!trigger) return null;
+  if (typeof trigger !== "string") return null;
   const match = LEADING_TOKEN_RE.exec(trigger.trim());
   const token = match?.[1];
   if (!token) return null;
@@ -11257,25 +11307,28 @@ function parsePathFromTrigger(trigger) {
 }
 var ERROR_STATUS_THRESHOLD3 = 500;
 function mapEventToSignal(event) {
+  if (!event || typeof event !== "object") return null;
   const metadata = event.$metadata;
   const workers = event.$workers;
   const method = parseHttpMethodFromTrigger(metadata?.trigger);
   if (!method) return null;
   const scriptName = workers?.scriptName ?? metadata?.service;
-  if (!scriptName) return null;
+  if (typeof scriptName !== "string" || scriptName.length === 0) return null;
   const timestampMs = event.timestamp ?? metadata?.startTime;
   if (typeof timestampMs !== "number" || !Number.isFinite(timestampMs)) return null;
+  const observedAt = new Date(timestampMs);
+  if (Number.isNaN(observedAt.getTime())) return null;
   const statusCode = metadata?.statusCode;
   const isError = typeof statusCode === "number" && statusCode >= ERROR_STATUS_THRESHOLD3;
-  const path61 = metadata?.trigger ? parsePathFromTrigger(metadata.trigger) : void 0;
+  const path62 = metadata?.trigger ? parsePathFromTrigger(metadata.trigger) : void 0;
   return {
     targetKind: CLOUDFLARE_TARGET_KIND,
     targetName: scriptName,
     callCount: 1,
     errorCount: isError ? 1 : 0,
-    lastObservedIso: new Date(timestampMs).toISOString(),
+    lastObservedIso: observedAt.toISOString(),
     method,
-    ...path61 ? { path: path61 } : {},
+    ...path62 ? { path: path62 } : {},
     ...typeof statusCode === "number" ? { statusCode } : {},
     ...typeof metadata?.duration === "number" ? { duration: metadata.duration } : {}
   };
@@ -11321,8 +11374,8 @@ function findTaggedWorkerFileNode(graph, workerName) {
   });
   return found;
 }
-function findMatchingRouteNode(graph, serviceName, method, path61) {
-  const normalizedPath = normalizePathTemplate(path61);
+function findMatchingRouteNode(graph, serviceName, method, path62) {
+  const normalizedPath = normalizePathTemplate(path62);
   let found = null;
   graph.forEachNode((id, attrs) => {
     if (found) return;
@@ -11339,10 +11392,10 @@ function createCloudflareResolveTarget(config, graph) {
   return (signal) => {
     if (signal.targetKind !== CLOUDFLARE_TARGET_KIND) return null;
     const scriptName = signal.targetName;
-    const { method, path: path61 } = signal;
+    const { method, path: path62 } = signal;
     const resolveRouteGrain = (serviceName, wholeFileId) => {
-      if (!method || !path61) return wholeFileId;
-      return findMatchingRouteNode(graph, serviceName, method, path61) ?? wholeFileId;
+      if (!method || !path62) return wholeFileId;
+      return findMatchingRouteNode(graph, serviceName, method, path62) ?? wholeFileId;
     };
     const mapping = config.workers?.[scriptName];
     if (mapping) {
@@ -15585,9 +15638,183 @@ async function runConnectorCommand(rawArgs, deps = {}) {
   }
 }
 
-// src/cli-verbs.ts
+// src/hooks-cli.ts
 init_cjs_shims();
 var import_node_path59 = __toESM(require("path"), 1);
+var import_node_os5 = __toESM(require("os"), 1);
+var import_node_fs40 = require("fs");
+var import_node_url5 = require("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 : import_node_path59.default.dirname((0, import_node_url5.fileURLToPath)(importMetaUrl));
+}
+async function readSkillAsset(rel) {
+  const here = moduleDir();
+  const candidates = [
+    import_node_path59.default.resolve(here, "../../claude-skill", rel),
+    import_node_path59.default.resolve(here, "../../../claude-skill", rel),
+    import_node_path59.default.resolve(here, "../claude-skill", rel)
+  ];
+  for (const candidate of candidates) {
+    try {
+      return await import_node_fs40.promises.readFile(candidate, "utf8");
+    } catch {
+    }
+  }
+  throw new Error(
+    `neat hooks: could not find @neat.is/claude-skill/${rel} \u2014 is the package installed?`
+  );
+}
+function neatHome3() {
+  const override = process.env.NEAT_HOME;
+  if (override && override.length > 0) return import_node_path59.default.resolve(override);
+  return import_node_path59.default.join(import_node_os5.default.homedir(), ".neat");
+}
+function claudeSettingsPath() {
+  const override = process.env.NEAT_CLAUDE_SETTINGS;
+  if (override && override.length > 0) return import_node_path59.default.resolve(override);
+  const home = process.env.HOME ?? process.env.USERPROFILE ?? import_node_os5.default.homedir();
+  return import_node_path59.default.join(home, ".claude", "settings.json");
+}
+function installedHookPath() {
+  return import_node_path59.default.join(neatHome3(), "hooks", HOOK_FILENAME);
+}
+function isNeatSearchEntry(entry2) {
+  return (entry2.hooks ?? []).some(
+    (h) => typeof h.command === "string" && h.command.includes(HOOK_FILENAME)
+  );
+}
+function neatHookEntry(command) {
+  return { matcher: HOOK_MATCHER, hooks: [{ type: "command", command }] };
+}
+function hookCommand(scriptPath) {
+  return `node "${scriptPath}"`;
+}
+async function runHooks(opts) {
+  if (opts.printHook) {
+    process.stdout.write(await readSkillAsset(`hooks/${HOOK_FILENAME}`));
+    return { exitCode: 0 };
+  }
+  if (opts.printGuide) {
+    process.stdout.write(await readSkillAsset(GUIDE_FILENAME));
+    return { exitCode: 0 };
+  }
+  if (opts.printSettings) {
+    const block = {
+      hooks: { PreToolUse: [neatHookEntry(hookCommand(installedHookPath()))] }
+    };
+    process.stdout.write(JSON.stringify(block, null, 2) + "\n");
+    return { exitCode: 0 };
+  }
+  if (opts.apply) {
+    const hookScript = await readSkillAsset(`hooks/${HOOK_FILENAME}`);
+    const guide = await readSkillAsset(GUIDE_FILENAME);
+    const scriptPath = installedHookPath();
+    await import_node_fs40.promises.mkdir(import_node_path59.default.dirname(scriptPath), { recursive: true });
+    await import_node_fs40.promises.writeFile(scriptPath, hookScript, { mode: 493 });
+    const guidePath = import_node_path59.default.join(neatHome3(), GUIDE_INSTALL_NAME);
+    await import_node_fs40.promises.writeFile(guidePath, guide, "utf8");
+    const settingsFile = claudeSettingsPath();
+    let settings = {};
+    try {
+      settings = JSON.parse(await import_node_fs40.promises.readFile(settingsFile, "utf8"));
+    } catch (err) {
+      if (err.code !== "ENOENT") {
+        console.error(
+          `neat hooks: failed to read ${settingsFile} \u2014 ${err.message}`
+        );
+        return { exitCode: 1 };
+      }
+    }
+    const hooks = settings.hooks ?? {};
+    const preToolUse = Array.isArray(hooks.PreToolUse) ? [...hooks.PreToolUse] : [];
+    const command = hookCommand(scriptPath);
+    const existingIdx = preToolUse.findIndex(isNeatSearchEntry);
+    if (existingIdx >= 0) {
+      preToolUse[existingIdx] = neatHookEntry(command);
+    } else {
+      preToolUse.push(neatHookEntry(command));
+    }
+    const merged = {
+      ...settings,
+      hooks: { ...hooks, PreToolUse: preToolUse }
+    };
+    await import_node_fs40.promises.mkdir(import_node_path59.default.dirname(settingsFile), { recursive: true });
+    await import_node_fs40.promises.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})`);
+    console.log(`  guidance: ${guidePath}`);
+    console.log("");
+    console.log("restart Claude Code to load the hook. On a Grep/Glob or a Bash grep,");
+    console.log("your agent will now be nudged to query NEAT first.");
+    console.log("");
+    console.log("The hook is Claude-Code-specific. For agents on other harnesses, paste");
+    console.log(`the guidance above into your project instructions (CLAUDE.md / AGENTS.md).`);
+    return { exitCode: 0 };
+  }
+  usage();
+  return { exitCode: 0 };
+}
+function usage() {
+  console.log("neat hooks \u2014 wire NEAT into your agent so it queries the graph before grepping");
+  console.log("");
+  console.log("  --apply          install the Claude Code search-nudge hook and write the");
+  console.log("                   graph-first guidance to ~/.neat/, merging into");
+  console.log("                   ~/.claude/settings.json without touching your other hooks");
+  console.log("  --print-hook     print the hook script to stdout");
+  console.log("  --print-guide    print the agent-agnostic graph-first guidance to stdout");
+  console.log("  --print-settings print the settings.json PreToolUse block --apply would add");
+  console.log("");
+  console.log("The hook is a gentle, non-blocking nudge \u2014 searches still run. It is");
+  console.log("Claude-Code-specific; other harnesses get the same steer from the guidance.");
+}
+async function runHooksCommand(args) {
+  const opts = {
+    apply: false,
+    printHook: false,
+    printGuide: false,
+    printSettings: false
+  };
+  for (const arg of args) {
+    switch (arg) {
+      case "--apply":
+        opts.apply = true;
+        break;
+      case "--print-hook":
+        opts.printHook = true;
+        break;
+      case "--print-guide":
+        opts.printGuide = true;
+        break;
+      case "--print-settings":
+        opts.printSettings = true;
+        break;
+      case "-h":
+      case "--help":
+        usage();
+        return 0;
+      default:
+        console.error(`neat hooks: unknown flag "${arg}"`);
+        usage();
+        return 2;
+    }
+  }
+  try {
+    const { exitCode } = await runHooks(opts);
+    return exitCode;
+  } catch (err) {
+    console.error(err.message);
+    return 1;
+  }
+}
+
+// src/cli-verbs.ts
+init_cjs_shims();
+var import_node_path60 = __toESM(require("path"), 1);
 
 // src/cli-client.ts
 init_cjs_shims();
@@ -15616,10 +15843,10 @@ function createHttpClient(baseUrl, bearerToken) {
   const root = baseUrl.replace(/\/$/, "");
   const authHeader = bearerToken && bearerToken.length > 0 ? { authorization: `Bearer ${bearerToken}` } : {};
   return {
-    async get(path61) {
+    async get(path62) {
       let res;
       try {
-        res = await fetch(`${root}${path61}`, {
+        res = await fetch(`${root}${path62}`, {
           headers: { ...authHeader }
         });
       } catch (err) {
@@ -15631,16 +15858,16 @@ function createHttpClient(baseUrl, bearerToken) {
         const body = await res.text().catch(() => "");
         throw new HttpError(
           res.status,
-          `${res.status} ${res.statusText} on GET ${path61}: ${body}`,
+          `${res.status} ${res.statusText} on GET ${path62}: ${body}`,
           body
         );
       }
       return await res.json();
     },
-    async post(path61, body) {
+    async post(path62, body) {
       let res;
       try {
-        res = await fetch(`${root}${path61}`, {
+        res = await fetch(`${root}${path62}`, {
           method: "POST",
           headers: { "content-type": "application/json", ...authHeader },
           body: JSON.stringify(body)
@@ -15654,7 +15881,7 @@ function createHttpClient(baseUrl, bearerToken) {
         const text = await res.text().catch(() => "");
         throw new HttpError(
           res.status,
-          `${res.status} ${res.statusText} on POST ${path61}: ${text}`,
+          `${res.status} ${res.statusText} on POST ${path62}: ${text}`,
           text
         );
       }
@@ -15668,12 +15895,12 @@ function projectPath(project, suffix) {
 }
 async function runRootCause(client, input) {
   const qs = input.errorId ? `?errorId=${encodeURIComponent(input.errorId)}` : "";
-  const path61 = projectPath(
+  const path62 = projectPath(
     input.project,
     `/graph/root-cause/${encodeURIComponent(input.errorNode)}${qs}`
   );
   try {
-    const result = await client.get(path61);
+    const result = await client.get(path62);
     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}.` : "");
@@ -15699,12 +15926,12 @@ async function runRootCause(client, input) {
 }
 async function runBlastRadius(client, input) {
   const qs = input.depth !== void 0 ? `?depth=${input.depth}` : "";
-  const path61 = projectPath(
+  const path62 = projectPath(
     input.project,
     `/graph/blast-radius/${encodeURIComponent(input.nodeId)}${qs}`
   );
   try {
-    const result = await client.get(path61);
+    const result = await client.get(path62);
     if (result.totalAffected === 0) {
       return {
         summary: `${result.origin} has no dependents. Nothing else would break if it failed.`
@@ -15738,12 +15965,12 @@ function formatBlastEntry(n) {
 }
 async function runDependencies(client, input) {
   const depth = input.depth ?? 3;
-  const path61 = projectPath(
+  const path62 = projectPath(
     input.project,
     `/graph/dependencies/${encodeURIComponent(input.nodeId)}?depth=${depth}`
   );
   try {
-    const result = await client.get(path61);
+    const result = await client.get(path62);
     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}).`
@@ -15835,9 +16062,9 @@ function formatDuration(ms) {
   return `${Math.round(h / 24)}d`;
 }
 async function runIncidents(client, input) {
-  const path61 = input.nodeId ? projectPath(input.project, `/incidents/${encodeURIComponent(input.nodeId)}`) : projectPath(input.project, "/incidents");
+  const path62 = input.nodeId ? projectPath(input.project, `/incidents/${encodeURIComponent(input.nodeId)}`) : projectPath(input.project, "/incidents");
   try {
-    const body = await client.get(path61);
+    const body = await client.get(path62);
     const events = body.events;
     if (events.length === 0) {
       return {
@@ -16127,7 +16354,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}${import_node_path59.default.sep}`)) {
+    if (resolvedCwd === entry2.path || resolvedCwd.startsWith(`${entry2.path}${import_node_path60.default.sep}`)) {
       return entry2;
     }
   }
@@ -16292,7 +16519,7 @@ function isNpxInvocation() {
 function commandPrefix() {
   return isNpxInvocation() ? "npx neat.is" : "neat";
 }
-function usage() {
+function usage2() {
   const neat = commandPrefix();
   console.log("Installed via npx? Prefix commands with `npx neat.is`, or install once: `npm i -g neat.is`.");
   console.log("");
@@ -16329,6 +16556,14 @@ function usage() {
   console.log("                 Flags:");
   console.log("                   --print-config   print the JSON snippet to stdout");
   console.log("                   --apply          merge mcpServers.neat into ~/.claude.json");
+  console.log("  hooks          Wire NEAT into your agent so it queries the graph before");
+  console.log("                 grepping. Installs a gentle Claude Code search-nudge hook and");
+  console.log("                 writes agent-agnostic graph-first guidance for other harnesses.");
+  console.log("                 Flags:");
+  console.log("                   --apply          install the hook + guidance");
+  console.log("                   --print-hook     print the hook script");
+  console.log("                   --print-guide    print the graph-first guidance");
+  console.log("                   --print-settings print the settings.json block --apply adds");
   console.log("  deploy         Detect the deploy substrate, generate NEAT_AUTH_TOKEN,");
   console.log("                 emit a docker-compose / systemd / docker run artifact, and");
   console.log("                 print the OTel env-vars block to paste into your platform.");
@@ -16573,7 +16808,7 @@ async function buildPatchSections(services, project) {
 }
 async function runInit(opts) {
   const written = [];
-  const stat = await import_node_fs40.promises.stat(opts.scanPath).catch(() => null);
+  const stat = await import_node_fs41.promises.stat(opts.scanPath).catch(() => null);
   if (!stat || !stat.isDirectory()) {
     console.error(`neat init: ${opts.scanPath} is not a directory`);
     return { exitCode: 2, writtenFiles: written };
@@ -16582,13 +16817,13 @@ async function runInit(opts) {
   printDiscoveryReport(opts, services);
   const sections = opts.noInstall ? [] : await buildPatchSections(services, opts.project);
   const patch = renderPatch(sections);
-  const patchPath = import_node_path60.default.join(opts.scanPath, "neat.patch");
+  const patchPath = import_node_path61.default.join(opts.scanPath, "neat.patch");
   if (opts.dryRun) {
-    await import_node_fs40.promises.writeFile(patchPath, patch, "utf8");
+    await import_node_fs41.promises.writeFile(patchPath, patch, "utf8");
     written.push(patchPath);
     console.log(`dry-run: patch written to ${patchPath}`);
-    const gitignorePath = import_node_path60.default.join(opts.scanPath, ".gitignore");
-    const gitignoreExists = await import_node_fs40.promises.stat(gitignorePath).then(() => true).catch(() => false);
+    const gitignorePath = import_node_path61.default.join(opts.scanPath, ".gitignore");
+    const gitignoreExists = await import_node_fs41.promises.stat(gitignorePath).then(() => true).catch(() => false);
     const verb = gitignoreExists ? "append" : "create";
     console.log(`dry-run: would ${verb} ${gitignorePath} (add neat-out/)`);
     console.log("rerun without --dry-run to register and snapshot.");
@@ -16599,9 +16834,9 @@ async function runInit(opts) {
   const graph = getGraph(graphKey);
   const projectPaths = pathsForProject(
     graphKey,
-    import_node_path60.default.join(opts.scanPath, "neat-out")
+    import_node_path61.default.join(opts.scanPath, "neat-out")
   );
-  const errorsPath = import_node_path60.default.join(import_node_path60.default.dirname(opts.outPath), import_node_path60.default.basename(projectPaths.errorsPath));
+  const errorsPath = import_node_path61.default.join(import_node_path61.default.dirname(opts.outPath), import_node_path61.default.basename(projectPaths.errorsPath));
   const result = await extractFromDirectory(graph, opts.scanPath, { errorsPath });
   await saveGraphToDisk(graph, opts.outPath);
   written.push(opts.outPath);
@@ -16680,7 +16915,7 @@ async function runInit(opts) {
         console.log("Run `npm install` (or your language equivalent) to refresh lockfiles.");
       }
     } else {
-      await import_node_fs40.promises.writeFile(patchPath, patch, "utf8");
+      await import_node_fs41.promises.writeFile(patchPath, patch, "utf8");
       written.push(patchPath);
     }
   }
@@ -16720,9 +16955,9 @@ var CLAUDE_SKILL_CONFIG = {
 };
 function claudeConfigPath() {
   const override = process.env.NEAT_CLAUDE_CONFIG;
-  if (override && override.length > 0) return import_node_path60.default.resolve(override);
+  if (override && override.length > 0) return import_node_path61.default.resolve(override);
   const home = process.env.HOME ?? process.env.USERPROFILE ?? "";
-  return import_node_path60.default.join(home, ".claude.json");
+  return import_node_path61.default.join(home, ".claude.json");
 }
 async function runSkill(opts) {
   const snippet2 = JSON.stringify(CLAUDE_SKILL_CONFIG, null, 2) + "\n";
@@ -16734,7 +16969,7 @@ async function runSkill(opts) {
     const target = claudeConfigPath();
     let existing = {};
     try {
-      existing = JSON.parse(await import_node_fs40.promises.readFile(target, "utf8"));
+      existing = JSON.parse(await import_node_fs41.promises.readFile(target, "utf8"));
     } catch (err) {
       if (err.code !== "ENOENT") {
         console.error(`neat skill: failed to read ${target} \u2014 ${err.message}`);
@@ -16746,10 +16981,13 @@ async function runSkill(opts) {
       ...existing,
       mcpServers: { ...mcp, neat: CLAUDE_SKILL_CONFIG.mcpServers.neat }
     };
-    await import_node_fs40.promises.mkdir(import_node_path60.default.dirname(target), { recursive: true });
-    await import_node_fs40.promises.writeFile(target, JSON.stringify(merged, null, 2) + "\n", "utf8");
+    await import_node_fs41.promises.mkdir(import_node_path61.default.dirname(target), { recursive: true });
+    await import_node_fs41.promises.writeFile(target, JSON.stringify(merged, null, 2) + "\n", "utf8");
     console.log(`neat skill: wrote mcpServers.neat to ${target}`);
     console.log("restart Claude Code to pick up the new MCP server.");
+    console.log("");
+    console.log("Tip: run `neat hooks --apply` to also install the search-nudge hook, so");
+    console.log("your agent reaches for the graph before it grep-scans the repo.");
     return { exitCode: 0 };
   }
   console.log("neat skill \u2014 Claude Code MCP drop-in for NEAT");
@@ -16762,13 +17000,16 @@ async function runSkill(opts) {
   console.log("");
   console.log("The MCP server reads NEAT_CORE_URL for the daemon URL \u2014 point it at a");
   console.log("non-default daemon by editing that value in the generated config.");
+  console.log("");
+  console.log("See also `neat hooks --apply` \u2014 the search-nudge hook + graph-first guidance");
+  console.log("that steer an agent to query the graph before falling back to text search.");
   return { exitCode: 0 };
 }
 async function main() {
   const argv = process.argv.slice(2);
   const cmd0 = argv[0];
   if (cmd0 === "-h" || cmd0 === "--help") {
-    usage();
+    usage2();
     process.exit(0);
   }
   if (cmd0 === "--version" || cmd0 === "-v" || cmd0 === "version") {
@@ -16780,6 +17021,11 @@ async function main() {
     if (code !== 0) process.exit(code);
     return;
   }
+  if (cmd0 === "hooks") {
+    const code = await runHooksCommand(argv.slice(1));
+    if (code !== 0) process.exit(code);
+    return;
+  }
   const argvParsed = parseArgs(argv);
   if (argvParsed.positional.length === 0) {
     const orchestratorCode2 = await tryOrchestrator(process.cwd(), argvParsed);
@@ -16794,19 +17040,19 @@ async function main() {
     const target = positional[0];
     if (!target) {
       console.error("neat init: missing <path>");
-      usage();
+      usage2();
       process.exit(2);
     }
     if (apply3 && dryRun) {
       console.error("neat init: --apply and --dry-run are mutually exclusive");
       process.exit(2);
     }
-    const scanPath = import_node_path60.default.resolve(target);
+    const scanPath = import_node_path61.default.resolve(target);
     const projectExplicit = parsed.project !== null;
-    const projectName = projectExplicit ? project : import_node_path60.default.basename(scanPath);
+    const projectName = projectExplicit ? project : import_node_path61.default.basename(scanPath);
     const projectKey = projectExplicit ? project : DEFAULT_PROJECT;
-    const fallback = pathsForProject(projectKey, import_node_path60.default.join(scanPath, "neat-out")).snapshotPath;
-    const outPath = import_node_path60.default.resolve(process.env.NEAT_OUT_PATH ?? fallback);
+    const fallback = pathsForProject(projectKey, import_node_path61.default.join(scanPath, "neat-out")).snapshotPath;
+    const outPath = import_node_path61.default.resolve(process.env.NEAT_OUT_PATH ?? fallback);
     const result = await runInit({
       scanPath,
       outPath,
@@ -16824,24 +17070,24 @@ async function main() {
     const target = positional[0];
     if (!target) {
       console.error("neat watch: missing <path>");
-      usage();
+      usage2();
       process.exit(2);
     }
-    const scanPath = import_node_path60.default.resolve(target);
-    const stat = await import_node_fs40.promises.stat(scanPath).catch(() => null);
+    const scanPath = import_node_path61.default.resolve(target);
+    const stat = await import_node_fs41.promises.stat(scanPath).catch(() => null);
     if (!stat || !stat.isDirectory()) {
       console.error(`neat watch: ${scanPath} is not a directory`);
       process.exit(2);
     }
-    const projectPaths = pathsForProject(project, import_node_path60.default.join(scanPath, "neat-out"));
-    const outPath = import_node_path60.default.resolve(process.env.NEAT_OUT_PATH ?? projectPaths.snapshotPath);
-    const errorsPath = import_node_path60.default.resolve(
-      process.env.NEAT_ERRORS_PATH ?? import_node_path60.default.join(import_node_path60.default.dirname(outPath), import_node_path60.default.basename(projectPaths.errorsPath))
+    const projectPaths = pathsForProject(project, import_node_path61.default.join(scanPath, "neat-out"));
+    const outPath = import_node_path61.default.resolve(process.env.NEAT_OUT_PATH ?? projectPaths.snapshotPath);
+    const errorsPath = import_node_path61.default.resolve(
+      process.env.NEAT_ERRORS_PATH ?? import_node_path61.default.join(import_node_path61.default.dirname(outPath), import_node_path61.default.basename(projectPaths.errorsPath))
     );
-    const staleEventsPath = import_node_path60.default.resolve(
-      process.env.NEAT_STALE_EVENTS_PATH ?? import_node_path60.default.join(import_node_path60.default.dirname(outPath), import_node_path60.default.basename(projectPaths.staleEventsPath))
+    const staleEventsPath = import_node_path61.default.resolve(
+      process.env.NEAT_STALE_EVENTS_PATH ?? import_node_path61.default.join(import_node_path61.default.dirname(outPath), import_node_path61.default.basename(projectPaths.staleEventsPath))
     );
-    const embeddingsCachePath = process.env.NEAT_EMBEDDINGS_CACHE_PATH ? import_node_path60.default.resolve(process.env.NEAT_EMBEDDINGS_CACHE_PATH) : void 0;
+    const embeddingsCachePath = process.env.NEAT_EMBEDDINGS_CACHE_PATH ? import_node_path61.default.resolve(process.env.NEAT_EMBEDDINGS_CACHE_PATH) : void 0;
     const handle = await startWatch(getGraph(project), {
       scanPath,
       outPath,
@@ -16883,7 +17129,7 @@ async function main() {
     const name = positional[0];
     if (!name) {
       console.error("neat pause: missing <name>");
-      usage();
+      usage2();
       process.exit(2);
     }
     const daemon = await findDaemonByProject(name);
@@ -16908,7 +17154,7 @@ async function main() {
     const name = positional[0];
     if (!name) {
       console.error("neat resume: missing <name>");
-      usage();
+      usage2();
       process.exit(2);
     }
     const daemon = await findDaemonByProject(name);
@@ -16938,7 +17184,7 @@ async function main() {
     const name = positional[0];
     if (!name) {
       console.error("neat uninstall: missing <name>");
-      usage();
+      usage2();
       process.exit(2);
     }
     const daemon = await findDaemonByProject(name);
@@ -17020,15 +17266,15 @@ async function main() {
     return;
   }
   console.error(`neat: unknown command "${cmd}"`);
-  usage();
+  usage2();
   process.exit(1);
 }
 async function tryOrchestrator(cmd, parsed) {
-  const scanPath = import_node_path60.default.resolve(cmd);
-  const stat = await import_node_fs40.promises.stat(scanPath).catch(() => null);
+  const scanPath = import_node_path61.default.resolve(cmd);
+  const stat = await import_node_fs41.promises.stat(scanPath).catch(() => null);
   if (!stat || !stat.isDirectory()) return null;
   const projectExplicit = parsed.project !== null;
-  const projectName = projectExplicit ? parsed.project : import_node_path60.default.basename(scanPath);
+  const projectName = projectExplicit ? parsed.project : import_node_path61.default.basename(scanPath);
   const result = await runOrchestrator({
     scanPath,
     project: projectName,