@neat.is/core 0.5.2 → 0.5.4-dev.20260721

package/dist/cli.js

@@ -1,15 +1,18 @@
 #!/usr/bin/env node
 import {
-  PROVIDER_DISPATCH,
   clearDaemonRecord,
-  getProviderDispatch,
+  deprovisionConnector,
+  getProviderFieldSchema,
+  isPushProvider,
+  knownProviderNames,
   portFromListenAddress,
+  provisionConnector,
   readDaemonRecord,
   resolveHost,
   resolveNeatVersion,
   validateConnectorEntry,
   writeDaemonRecord
-} from "./chunk-DPEPI2N6.js";
+} from "./chunk-VR73QNJD.js";
 import {
   buildSearchIndex
 } from "./chunk-BIY46Q6U.js";
@@ -68,10 +71,10 @@ import {
   startPersistLoop,
   startStalenessLoop,
   upsertConnectorEntry
-} from "./chunk-BI3XKGVG.js";
+} from "./chunk-PEFX3DBR.js";
 import {
   startOtelGrpcReceiver
-} from "./chunk-I72HTUOG.js";
+} from "./chunk-4RU3AAOI.js";
 import {
   __dirname,
   __require,
@@ -79,11 +82,11 @@ import {
   buildOtelReceiver,
   listenSteppingOtlp,
   readAuthEnv
-} from "./chunk-CFDPIMRP.js";
+} from "./chunk-I4NZ7PSN.js";
 
 // src/cli.ts
-import path9 from "path";
-import { promises as fs7 } from "fs";
+import path10 from "path";
+import { promises as fs8 } from "fs";
 
 // src/banner.ts
 import path from "path";
@@ -3566,6 +3569,8 @@ function parseConnectorArgs(args) {
     positional: [],
     skipValidate: false,
     plaintext: false,
+    help: false,
+    json: false,
     fields: {}
   };
   const positional = [];
@@ -3579,6 +3584,14 @@ function parseConnectorArgs(args) {
       out.plaintext = true;
       continue;
     }
+    if (arg === "--help" || arg === "-h") {
+      out.help = true;
+      continue;
+    }
+    if (arg === "--json") {
+      out.json = true;
+      continue;
+    }
     if (arg.startsWith("--")) {
       let flag = arg;
       let value;
@@ -3655,19 +3668,20 @@ function plaintextFields(ref) {
 async function connectorAdd(args, deps) {
   let provider = args.positional[0];
   if (!provider && deps.interactive) {
-    provider = (await deps.prompt(`Provider (${Object.keys(PROVIDER_DISPATCH).sort().join(", ")}):`)).trim();
+    provider = (await deps.prompt(`Provider (${knownProviderNames().join(", ")}):`)).trim();
   }
   if (!provider) {
     deps.err("neat connector add: a provider is required (e.g. `neat connector add supabase`)");
     return 2;
   }
-  const dispatch = getProviderDispatch(provider);
+  const dispatch = getProviderFieldSchema(provider);
   if (!dispatch) {
     deps.err(
-      `neat connector add: unknown provider "${provider}". known providers: ${Object.keys(PROVIDER_DISPATCH).sort().join(", ")}`
+      `neat connector add: unknown provider "${provider}". known providers: ${knownProviderNames().join(", ")}`
     );
     return 2;
   }
+  const push = isPushProvider(provider);
   let project = args.project;
   if (project === void 0 && deps.interactive) {
     const answer = (await deps.prompt("Project (blank = the project the daemon is bootstrapping):")).trim();
@@ -3706,7 +3720,7 @@ async function connectorAdd(args, deps) {
     credential,
     ...Object.keys(options).length > 0 ? { options } : {}
   };
-  if (!args.skipValidate) {
+  if (!push && !args.skipValidate) {
     const outcome = await validateConnectorEntry(entry2, deps.env, deps.fetchImpl);
     const code = reportPreWriteValidation(outcome, deps);
     if (code !== 0) return code;
@@ -3717,14 +3731,32 @@ async function connectorAdd(args, deps) {
       `neat connector add: storing a literal secret at rest for ${plaintext.join(", ")} \u2014 prefer an env-var reference like \`$PROVIDER_TOKEN\` (pass --plaintext to silence this).`
     );
   }
+  if (push) {
+    if (args.skipValidate) {
+      deps.out("note: --skip-validate has no effect for a push provider \u2014 provisioning the drain is the add.");
+    }
+    const outcome = await provisionConnector(entry2, deps.env, deps.fetchImpl);
+    if (outcome.status !== "ok") {
+      deps.err(
+        `neat connector add: could not provision the ${provider} connector \u2014 ${outcome.reason}. Nothing was written.`
+      );
+      return 1;
+    }
+    if (outcome.options) entry2.options = { ...entry2.options ?? {}, ...outcome.options };
+    if (outcome.note) deps.out(`note: ${outcome.note}`);
+  }
   const { replaced } = await upsertConnectorEntry(entry2, deps.home);
   const verb = replaced ? "updated" : "added";
   const where = project ? `project "${project}"` : "the bootstrapping project";
   deps.out(`${verb} connector "${id}" (${provider}) for ${where}.`);
-  if (args.skipValidate) {
-    deps.out("skipped validation (--skip-validate) \u2014 the credential is checked at the next daemon poll.");
+  if (push) {
+    deps.out("The drain is live \u2014 traces arrive at the daemon's OTLP receiver. No poll or restart needed.");
+  } else {
+    if (args.skipValidate) {
+      deps.out("skipped validation (--skip-validate) \u2014 the credential is checked at the next daemon poll.");
+    }
+    deps.out("Restart the project's daemon (or start it) to begin polling this connector.");
   }
-  deps.out("Restart the project's daemon (or start it) to begin polling this connector.");
   return 0;
 }
 function reportPreWriteValidation(outcome, deps) {
@@ -3750,10 +3782,26 @@ function reportPreWriteValidation(outcome, deps) {
       return 2;
   }
 }
-async function connectorList(deps, filterProject) {
+async function connectorList(deps, filterProject, json = false) {
   const config = await readConnectorsConfig(deps.home);
   let entries = config.connectors;
   if (filterProject) entries = entries.filter((e) => e.project === filterProject);
+  if (json) {
+    const rows = entries.map((e) => ({
+      id: e.id,
+      provider: e.provider,
+      project: e.project ?? null,
+      kind: isPushProvider(e.provider) ? "push" : "pull",
+      credential: describeCredential(e.credential, deps.env).map((c) => ({
+        ...c.field ? { field: c.field } : {},
+        ref: c.display,
+        ...c.status ? { status: c.status } : { kind: c.kind }
+      })),
+      ...e.options ? { options: e.options } : {}
+    }));
+    deps.out(JSON.stringify(rows, null, 2));
+    return 0;
+  }
   if (entries.length === 0) {
     deps.out(
       filterProject ? `no connectors configured for project "${filterProject}".` : "no connectors configured. run `neat connector add <provider>` to add one."
@@ -3776,6 +3824,22 @@ async function connectorRemove(deps, id) {
     deps.err("neat connector remove: missing <id>. run `neat connector list` to see configured ids.");
     return 2;
   }
+  const config = await readConnectorsConfig(deps.home);
+  const entry2 = config.connectors.find((c) => c.id === id);
+  if (!entry2) {
+    deps.err(`neat connector remove: no connector with id "${id}". run \`neat connector list\` to see configured ids.`);
+    return 1;
+  }
+  if (isPushProvider(entry2.provider)) {
+    const outcome = await deprovisionConnector(entry2, deps.env, deps.fetchImpl);
+    if (outcome.status !== "ok") {
+      deps.err(
+        `neat connector remove: could not delete the ${entry2.provider} drain \u2014 ${outcome.reason}. The entry was kept so you can retry (or delete the drain in the Vercel dashboard, then re-run).`
+      );
+      return 1;
+    }
+    if (outcome.note) deps.out(`note: ${outcome.note}`);
+  }
   const removed = await removeConnectorEntry(id, deps.home);
   if (!removed) {
     deps.err(`neat connector remove: no connector with id "${id}". run \`neat connector list\` to see configured ids.`);
@@ -3816,13 +3880,20 @@ async function connectorTest(deps, id) {
 }
 function printConnectorUsage(write) {
   write("usage: neat connector <add|list|remove|test> [args]");
+  write(`  providers:        ${knownProviderNames().join(", ")}`);
+  write("                    pull (polled): supabase, railway, firebase, cloudflare");
+  write("                    push (drains): vercel \u2014 provisions a Vercel trace Drain that forwards");
+  write("                                   traces to the daemon's OTLP receiver; no app instrumentation");
   write("  add <provider>    add a connector; validates the credential first (--skip-validate to skip)");
   write("                    flags: --project <name>  --credential/--token <$VAR|value>  --id <id>");
   write("                           --<option> <value> (provider-specific)  --plaintext  --skip-validate");
+  write("                    vercel: neat connector add vercel --token $VERCEL_TOKEN \\");
+  write("                              --otel-token $NEAT_OTEL_TOKEN --team-id <teamId> \\");
+  write("                              --endpoint https://<public-host>/v1/traces [--project-ids <id,id>]");
   write("  list              list configured connectors (credentials shown redacted)");
   write("                    flags: --project <name>");
-  write("  remove <id>       remove a connector by id");
-  write("  test <id>         re-run the credential validation for an existing connector");
+  write("  remove <id>       remove a connector by id (a push provider also has its drain deleted)");
+  write("  test <id>         re-run validation for an existing connector (a push provider re-tests its drain)");
 }
 async function runConnectorCommand(rawArgs, deps = {}) {
   const resolved = resolveDeps(deps);
@@ -3832,11 +3903,15 @@ async function runConnectorCommand(rawArgs, deps = {}) {
     return 2;
   }
   const a = parsed.value;
+  if (a.help) {
+    printConnectorUsage(resolved.out);
+    return 0;
+  }
   switch (a.subcommand) {
     case "add":
       return connectorAdd(a, resolved);
     case "list":
-      return connectorList(resolved, a.project);
+      return connectorList(resolved, a.project, a.json);
     case "remove":
       return connectorRemove(resolved, a.positional[0]);
     case "test":
@@ -3852,8 +3927,181 @@ async function runConnectorCommand(rawArgs, deps = {}) {
   }
 }
 
-// src/cli-verbs.ts
+// src/hooks-cli.ts
 import path8 from "path";
+import os from "os";
+import { promises as fs7 } 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 : path8.dirname(fileURLToPath3(import.meta.url));
+}
+async function readSkillAsset(rel) {
+  const here = moduleDir();
+  const candidates = [
+    path8.resolve(here, "../../claude-skill", rel),
+    path8.resolve(here, "../../../claude-skill", rel),
+    path8.resolve(here, "../claude-skill", rel)
+  ];
+  for (const candidate of candidates) {
+    try {
+      return await fs7.readFile(candidate, "utf8");
+    } catch {
+    }
+  }
+  throw new Error(
+    `neat hooks: could not find @neat.is/claude-skill/${rel} \u2014 is the package installed?`
+  );
+}
+function neatHome() {
+  const override = process.env.NEAT_HOME;
+  if (override && override.length > 0) return path8.resolve(override);
+  return path8.join(os.homedir(), ".neat");
+}
+function claudeSettingsPath() {
+  const override = process.env.NEAT_CLAUDE_SETTINGS;
+  if (override && override.length > 0) return path8.resolve(override);
+  const home = process.env.HOME ?? process.env.USERPROFILE ?? os.homedir();
+  return path8.join(home, ".claude", "settings.json");
+}
+function installedHookPath() {
+  return path8.join(neatHome(), "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 fs7.mkdir(path8.dirname(scriptPath), { recursive: true });
+    await fs7.writeFile(scriptPath, hookScript, { mode: 493 });
+    const guidePath = path8.join(neatHome(), GUIDE_INSTALL_NAME);
+    await fs7.writeFile(guidePath, guide, "utf8");
+    const settingsFile = claudeSettingsPath();
+    let settings = {};
+    try {
+      settings = JSON.parse(await fs7.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 fs7.mkdir(path8.dirname(settingsFile), { recursive: true });
+    await fs7.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
+import path9 from "path";
 
 // src/cli-client.ts
 import { Provenance as Provenance2 } from "@neat.is/types";
@@ -3881,10 +4129,10 @@ function createHttpClient(baseUrl, bearerToken) {
   const root = baseUrl.replace(/\/$/, "");
   const authHeader = bearerToken && bearerToken.length > 0 ? { authorization: `Bearer ${bearerToken}` } : {};
   return {
-    async get(path10) {
+    async get(path11) {
       let res;
       try {
-        res = await fetch(`${root}${path10}`, {
+        res = await fetch(`${root}${path11}`, {
           headers: { ...authHeader }
         });
       } catch (err) {
@@ -3896,16 +4144,16 @@ function createHttpClient(baseUrl, bearerToken) {
         const body = await res.text().catch(() => "");
         throw new HttpError(
           res.status,
-          `${res.status} ${res.statusText} on GET ${path10}: ${body}`,
+          `${res.status} ${res.statusText} on GET ${path11}: ${body}`,
           body
         );
       }
       return await res.json();
     },
-    async post(path10, body) {
+    async post(path11, body) {
       let res;
       try {
-        res = await fetch(`${root}${path10}`, {
+        res = await fetch(`${root}${path11}`, {
           method: "POST",
           headers: { "content-type": "application/json", ...authHeader },
           body: JSON.stringify(body)
@@ -3919,7 +4167,7 @@ function createHttpClient(baseUrl, bearerToken) {
         const text = await res.text().catch(() => "");
         throw new HttpError(
           res.status,
-          `${res.status} ${res.statusText} on POST ${path10}: ${text}`,
+          `${res.status} ${res.statusText} on POST ${path11}: ${text}`,
           text
         );
       }
@@ -3933,12 +4181,12 @@ function projectPath(project, suffix) {
 }
 async function runRootCause(client, input) {
   const qs = input.errorId ? `?errorId=${encodeURIComponent(input.errorId)}` : "";
-  const path10 = projectPath(
+  const path11 = projectPath(
     input.project,
     `/graph/root-cause/${encodeURIComponent(input.errorNode)}${qs}`
   );
   try {
-    const result = await client.get(path10);
+    const result = await client.get(path11);
     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}.` : "");
@@ -3964,12 +4212,12 @@ async function runRootCause(client, input) {
 }
 async function runBlastRadius(client, input) {
   const qs = input.depth !== void 0 ? `?depth=${input.depth}` : "";
-  const path10 = projectPath(
+  const path11 = projectPath(
     input.project,
     `/graph/blast-radius/${encodeURIComponent(input.nodeId)}${qs}`
   );
   try {
-    const result = await client.get(path10);
+    const result = await client.get(path11);
     if (result.totalAffected === 0) {
       return {
         summary: `${result.origin} has no dependents. Nothing else would break if it failed.`
@@ -4003,12 +4251,12 @@ function formatBlastEntry(n) {
 }
 async function runDependencies(client, input) {
   const depth = input.depth ?? 3;
-  const path10 = projectPath(
+  const path11 = projectPath(
     input.project,
     `/graph/dependencies/${encodeURIComponent(input.nodeId)}?depth=${depth}`
   );
   try {
-    const result = await client.get(path10);
+    const result = await client.get(path11);
     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}).`
@@ -4100,9 +4348,9 @@ function formatDuration(ms) {
   return `${Math.round(h / 24)}d`;
 }
 async function runIncidents(client, input) {
-  const path10 = input.nodeId ? projectPath(input.project, `/incidents/${encodeURIComponent(input.nodeId)}`) : projectPath(input.project, "/incidents");
+  const path11 = input.nodeId ? projectPath(input.project, `/incidents/${encodeURIComponent(input.nodeId)}`) : projectPath(input.project, "/incidents");
   try {
-    const body = await client.get(path10);
+    const body = await client.get(path11);
     const events = body.events;
     if (events.length === 0) {
       return {
@@ -4392,7 +4640,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}${path8.sep}`)) {
+    if (resolvedCwd === entry2.path || resolvedCwd.startsWith(`${entry2.path}${path9.sep}`)) {
       return entry2;
     }
   }
@@ -4557,7 +4805,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("");
@@ -4594,6 +4842,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.");
@@ -4606,8 +4862,9 @@ function usage() {
   console.log("                   --dry-run          run extraction in-memory; do not write");
   console.log("                   --no-instrument    skip the SDK install apply step");
   console.log("                   --json             emit the delta summary as JSON");
-  console.log("  connector      Configure pull-based OBSERVED connectors (supabase, railway,");
-  console.log("                 firebase, cloudflare). Subcommands:");
+  console.log("  connector      Configure OBSERVED connectors \u2014 pull (supabase, railway,");
+  console.log("                 firebase, cloudflare) and push (vercel, via a trace Drain).");
+  console.log("                 Subcommands:");
   console.log("                   add <provider>   add a connector; validates the credential");
   console.log("                                    against the provider first (--skip-validate to skip)");
   console.log("                                    flags: --project <name>, --credential/--token <$VAR|value>,");
@@ -4838,7 +5095,7 @@ async function buildPatchSections(services, project) {
 }
 async function runInit(opts) {
   const written = [];
-  const stat = await fs7.stat(opts.scanPath).catch(() => null);
+  const stat = await fs8.stat(opts.scanPath).catch(() => null);
   if (!stat || !stat.isDirectory()) {
     console.error(`neat init: ${opts.scanPath} is not a directory`);
     return { exitCode: 2, writtenFiles: written };
@@ -4847,13 +5104,13 @@ async function runInit(opts) {
   printDiscoveryReport(opts, services);
   const sections = opts.noInstall ? [] : await buildPatchSections(services, opts.project);
   const patch = renderPatch(sections);
-  const patchPath = path9.join(opts.scanPath, "neat.patch");
+  const patchPath = path10.join(opts.scanPath, "neat.patch");
   if (opts.dryRun) {
-    await fs7.writeFile(patchPath, patch, "utf8");
+    await fs8.writeFile(patchPath, patch, "utf8");
     written.push(patchPath);
     console.log(`dry-run: patch written to ${patchPath}`);
-    const gitignorePath = path9.join(opts.scanPath, ".gitignore");
-    const gitignoreExists = await fs7.stat(gitignorePath).then(() => true).catch(() => false);
+    const gitignorePath = path10.join(opts.scanPath, ".gitignore");
+    const gitignoreExists = await fs8.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.");
@@ -4864,9 +5121,9 @@ async function runInit(opts) {
   const graph = getGraph(graphKey);
   const projectPaths = pathsForProject(
     graphKey,
-    path9.join(opts.scanPath, "neat-out")
+    path10.join(opts.scanPath, "neat-out")
   );
-  const errorsPath = path9.join(path9.dirname(opts.outPath), path9.basename(projectPaths.errorsPath));
+  const errorsPath = path10.join(path10.dirname(opts.outPath), path10.basename(projectPaths.errorsPath));
   const result = await extractFromDirectory(graph, opts.scanPath, { errorsPath });
   await saveGraphToDisk(graph, opts.outPath);
   written.push(opts.outPath);
@@ -4945,7 +5202,7 @@ async function runInit(opts) {
         console.log("Run `npm install` (or your language equivalent) to refresh lockfiles.");
       }
     } else {
-      await fs7.writeFile(patchPath, patch, "utf8");
+      await fs8.writeFile(patchPath, patch, "utf8");
       written.push(patchPath);
     }
   }
@@ -4985,9 +5242,9 @@ var CLAUDE_SKILL_CONFIG = {
 };
 function claudeConfigPath() {
   const override = process.env.NEAT_CLAUDE_CONFIG;
-  if (override && override.length > 0) return path9.resolve(override);
+  if (override && override.length > 0) return path10.resolve(override);
   const home = process.env.HOME ?? process.env.USERPROFILE ?? "";
-  return path9.join(home, ".claude.json");
+  return path10.join(home, ".claude.json");
 }
 async function runSkill(opts) {
   const snippet = JSON.stringify(CLAUDE_SKILL_CONFIG, null, 2) + "\n";
@@ -4999,7 +5256,7 @@ async function runSkill(opts) {
     const target = claudeConfigPath();
     let existing = {};
     try {
-      existing = JSON.parse(await fs7.readFile(target, "utf8"));
+      existing = JSON.parse(await fs8.readFile(target, "utf8"));
     } catch (err) {
       if (err.code !== "ENOENT") {
         console.error(`neat skill: failed to read ${target} \u2014 ${err.message}`);
@@ -5011,10 +5268,13 @@ async function runSkill(opts) {
       ...existing,
       mcpServers: { ...mcp, neat: CLAUDE_SKILL_CONFIG.mcpServers.neat }
     };
-    await fs7.mkdir(path9.dirname(target), { recursive: true });
-    await fs7.writeFile(target, JSON.stringify(merged, null, 2) + "\n", "utf8");
+    await fs8.mkdir(path10.dirname(target), { recursive: true });
+    await fs8.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");
@@ -5027,13 +5287,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") {
@@ -5045,6 +5308,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);
@@ -5059,19 +5327,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 = path9.resolve(target);
+    const scanPath = path10.resolve(target);
     const projectExplicit = parsed.project !== null;
-    const projectName = projectExplicit ? project : path9.basename(scanPath);
+    const projectName = projectExplicit ? project : path10.basename(scanPath);
     const projectKey = projectExplicit ? project : DEFAULT_PROJECT;
-    const fallback = pathsForProject(projectKey, path9.join(scanPath, "neat-out")).snapshotPath;
-    const outPath = path9.resolve(process.env.NEAT_OUT_PATH ?? fallback);
+    const fallback = pathsForProject(projectKey, path10.join(scanPath, "neat-out")).snapshotPath;
+    const outPath = path10.resolve(process.env.NEAT_OUT_PATH ?? fallback);
     const result = await runInit({
       scanPath,
       outPath,
@@ -5089,24 +5357,24 @@ async function main() {
     const target = positional[0];
     if (!target) {
       console.error("neat watch: missing <path>");
-      usage();
+      usage2();
       process.exit(2);
     }
-    const scanPath = path9.resolve(target);
-    const stat = await fs7.stat(scanPath).catch(() => null);
+    const scanPath = path10.resolve(target);
+    const stat = await fs8.stat(scanPath).catch(() => null);
     if (!stat || !stat.isDirectory()) {
       console.error(`neat watch: ${scanPath} is not a directory`);
       process.exit(2);
     }
-    const projectPaths = pathsForProject(project, path9.join(scanPath, "neat-out"));
-    const outPath = path9.resolve(process.env.NEAT_OUT_PATH ?? projectPaths.snapshotPath);
-    const errorsPath = path9.resolve(
-      process.env.NEAT_ERRORS_PATH ?? path9.join(path9.dirname(outPath), path9.basename(projectPaths.errorsPath))
+    const projectPaths = pathsForProject(project, path10.join(scanPath, "neat-out"));
+    const outPath = path10.resolve(process.env.NEAT_OUT_PATH ?? projectPaths.snapshotPath);
+    const errorsPath = path10.resolve(
+      process.env.NEAT_ERRORS_PATH ?? path10.join(path10.dirname(outPath), path10.basename(projectPaths.errorsPath))
     );
-    const staleEventsPath = path9.resolve(
-      process.env.NEAT_STALE_EVENTS_PATH ?? path9.join(path9.dirname(outPath), path9.basename(projectPaths.staleEventsPath))
+    const staleEventsPath = path10.resolve(
+      process.env.NEAT_STALE_EVENTS_PATH ?? path10.join(path10.dirname(outPath), path10.basename(projectPaths.staleEventsPath))
     );
-    const embeddingsCachePath = process.env.NEAT_EMBEDDINGS_CACHE_PATH ? path9.resolve(process.env.NEAT_EMBEDDINGS_CACHE_PATH) : void 0;
+    const embeddingsCachePath = process.env.NEAT_EMBEDDINGS_CACHE_PATH ? path10.resolve(process.env.NEAT_EMBEDDINGS_CACHE_PATH) : void 0;
     const handle = await startWatch(getGraph(project), {
       scanPath,
       outPath,
@@ -5148,7 +5416,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);
@@ -5173,7 +5441,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);
@@ -5203,7 +5471,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);
@@ -5285,15 +5553,15 @@ async function main() {
     return;
   }
   console.error(`neat: unknown command "${cmd}"`);
-  usage();
+  usage2();
   process.exit(1);
 }
 async function tryOrchestrator(cmd, parsed) {
-  const scanPath = path9.resolve(cmd);
-  const stat = await fs7.stat(scanPath).catch(() => null);
+  const scanPath = path10.resolve(cmd);
+  const stat = await fs8.stat(scanPath).catch(() => null);
   if (!stat || !stat.isDirectory()) return null;
   const projectExplicit = parsed.project !== null;
-  const projectName = projectExplicit ? parsed.project : path9.basename(scanPath);
+  const projectName = projectExplicit ? parsed.project : path10.basename(scanPath);
   const result = await runOrchestrator({
     scanPath,
     project: projectName,
@@ -5549,6 +5817,6 @@ export {
   runInit,
   runQueryVerb,
   runSkill,
-  usage
+  usage2 as usage
 };
 //# sourceMappingURL=cli.js.map