@neat.is/core 0.9.2-dev.20260821 → 0.9.2

package/dist/cli.js

@@ -6,7 +6,7 @@ import {
   resolveHost,
   resolveNeatVersion,
   writeDaemonRecord
-} from "./chunk-L4SZIIER.js";
+} from "./chunk-TMHCS4ZY.js";
 import {
   buildSearchIndex
 } from "./chunk-BC53SCT7.js";
@@ -74,7 +74,7 @@ import {
   startStalenessLoop,
   upsertConnectorEntry,
   validateConnectorEntry
-} from "./chunk-RQQUI3NQ.js";
+} from "./chunk-HD5X5TWY.js";
 import {
   startOtelGrpcReceiver
 } from "./chunk-ERE47MCR.js";
@@ -88,9 +88,9 @@ import {
 } from "./chunk-GDGUY4T6.js";
 
 // src/cli.ts
-import path15 from "path";
+import path16 from "path";
 import os4 from "os";
-import { promises as fs13 } from "fs";
+import { promises as fs14 } from "fs";
 
 // src/banner.ts
 import path from "path";
@@ -3769,7 +3769,7 @@ async function extractAndPersist(opts) {
 }
 async function applyInstallersOver(services, project, options = {}) {
   const resolveManager = options.resolveManager ?? detectPackageManager;
-  const runInstall = options.runInstall ?? runPackageManagerInstall;
+  const runInstall2 = options.runInstall ?? runPackageManagerInstall;
   let instrumented = 0;
   let already = 0;
   let libOnly = 0;
@@ -3892,7 +3892,7 @@ async function applyInstallersOver(services, project, options = {}) {
   const packageManagerInstalls = [];
   for (const cmd of installPlans.values()) {
     console.log(`running \`${cmd.pm} ${cmd.args.join(" ")}\` in ${cmd.cwd}`);
-    const result = await runInstall(cmd);
+    const result = await runInstall2(cmd);
     packageManagerInstalls.push(result);
     if (result.exitCode !== 0) {
       console.error(
@@ -4869,6 +4869,9 @@ function claudeSettingsPath() {
 function installedHookPath() {
   return path11.join(neatHome(), "hooks", HOOK_FILENAME);
 }
+function gateFlagPath() {
+  return path11.join(neatHome(), "hooks", "gate-enabled");
+}
 function isNeatSearchEntry(entry2) {
   return (entry2.hooks ?? []).some(
     (h) => typeof h.command === "string" && h.command.includes(HOOK_FILENAME)
@@ -4931,13 +4934,30 @@ async function runHooks(opts) {
     };
     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`);
+    const flag = gateFlagPath();
+    if (opts.gate) {
+      await fs10.mkdir(path11.dirname(flag), { recursive: true });
+      await fs10.writeFile(flag, "1\n", "utf8");
+    } else {
+      await fs10.rm(flag, { force: true });
+    }
+    const mode = opts.gate ? "GATE (deny search until you ask the graph)" : "nudge (search still runs)";
+    console.log(`neat hooks: installed the search hook in ${opts.gate ? "gate" : "nudge"} mode`);
     console.log(`  script:   ${scriptPath}`);
     console.log(`  settings: ${settingsFile} (PreToolUse \u2192 ${HOOK_MATCHER})`);
     console.log(`  guidance: ${guidePath}`);
+    console.log(`  mode:     ${mode}`);
     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.");
+    if (opts.gate) {
+      console.log("restart Claude Code to load the hook. A Grep/Glob or Bash grep is now DENIED");
+      console.log('until you run `neat ask "<question>"` (or the ask MCP tool) once this session;');
+      console.log("after that, search is allowed as a fallback. Set NEAT_SEARCH_GATE=0 to fall");
+      console.log("back to nudge-only without re-running.");
+    } else {
+      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 (the search still runs).");
+      console.log("Re-run with --gate to hard-force the graph-first orientation.");
+    }
     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).`);
@@ -4949,28 +4969,36 @@ async function runHooks(opts) {
 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("  --apply          install the Claude Code search 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("  --gate           with --apply, enable hard-gate mode: DENY Grep/Glob/grep-Bash");
+  console.log("                   until `neat ask` has run this session (default is nudge-only).");
+  console.log("                   Toggle off at run time with NEAT_SEARCH_GATE=0.");
   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.");
+  console.log("By default the hook is a gentle, non-blocking nudge \u2014 searches still run.");
+  console.log("--gate turns it into a hard forcing mechanism. It is Claude-Code-specific;");
+  console.log("other harnesses get the same steer from the graph-first guidance.");
 }
 async function runHooksCommand(args) {
   const opts = {
     apply: false,
     printHook: false,
     printGuide: false,
-    printSettings: false
+    printSettings: false,
+    gate: false
   };
   for (const arg of args) {
     switch (arg) {
       case "--apply":
         opts.apply = true;
         break;
+      case "--gate":
+        opts.gate = true;
+        break;
       case "--print-hook":
         opts.printHook = true;
         break;
@@ -4999,10 +5027,149 @@ async function runHooksCommand(args) {
   }
 }
 
-// src/codex-cli.ts
+// src/claude-cli.ts
 import path12 from "path";
-import os2 from "os";
 import { promises as fs11 } from "fs";
+var NEAT_SECTION_HEADING = "## neat";
+var NEAT_DIRECTIVE_BODY = `This project has NEAT wired in: a live, fused semantic graph of the system \u2014
+code and runtime behaviour (OpenTelemetry) in one model, every fact tagged with
+its provenance (EXTRACTED / OBSERVED / INFERRED / STALE) and a confidence.
+
+For ANY question about this system's behaviour, dependencies, failures, root
+cause, or blast radius, call \`neat ask\` FIRST \u2014 before Read, Grep, Glob, or Bash:
+
+    neat ask "why is checkout failing?"
+    neat ask "what breaks if I change the orders table?"
+    neat ask "what does the payments service depend on at runtime?"
+
+\`ask\` resolves your question to graph nodes and routes it to the right traversal
+\u2014 root cause, dependencies, observed runtime calls, incidents, divergences,
+blast radius \u2014 and returns one compact, provenance-tagged answer. The same door
+is the \`ask\` MCP tool (\`mcp__neat__ask\`) when NEAT's MCP server is wired in.
+
+The graph is live and fused: it is faster and more accurate than scanning files,
+and it can tell you what the system actually does at runtime, not only what the
+source declares. Fall back to Read/Grep only when the graph does not have what
+you need \u2014 comments, string literals, config minutiae. Ask the graph first,
+then scan.
+
+If \`neat ask\` errors, the daemon may not be running (\`neat list\`) \u2014 start it
+with \`neat <path>\`, then re-ask.`;
+function neatSection() {
+  return `${NEAT_SECTION_HEADING}
+
+${NEAT_DIRECTIVE_BODY}
+`;
+}
+function claudeMdPath() {
+  const override = process.env.NEAT_CLAUDE_MD;
+  if (override && override.length > 0) return path12.resolve(override);
+  return path12.join(process.cwd(), "CLAUDE.md");
+}
+function splitAroundSection(raw) {
+  const lines = raw.split("\n");
+  const startIdx = lines.findIndex((l) => l.replace(/\s+$/, "") === NEAT_SECTION_HEADING);
+  if (startIdx === -1) {
+    return { before: raw.replace(/\n*$/, ""), after: "", found: false };
+  }
+  let endIdx = lines.length;
+  for (let i = startIdx + 1; i < lines.length; i++) {
+    if (/^#{1,2}\s+/.test(lines[i] ?? "")) {
+      endIdx = i;
+      break;
+    }
+  }
+  const before = lines.slice(0, startIdx).join("\n").replace(/\n*$/, "");
+  const after = lines.slice(endIdx).join("\n").replace(/^\n*/, "");
+  return { before, after, found: true };
+}
+function compose(before, after) {
+  const parts = [];
+  if (before.length > 0) parts.push(before);
+  parts.push(neatSection().replace(/\n+$/, ""));
+  if (after.length > 0) parts.push(after);
+  return parts.join("\n\n").replace(/\n*$/, "") + "\n";
+}
+async function readIfExists(file) {
+  try {
+    return await fs11.readFile(file, "utf8");
+  } catch (err) {
+    if (err.code === "ENOENT") return null;
+    throw err;
+  }
+}
+async function runInstall() {
+  const file = claudeMdPath();
+  const raw = await readIfExists(file) ?? "";
+  const { before, after, found } = splitAroundSection(raw);
+  const next = compose(before, after);
+  await fs11.mkdir(path12.dirname(file), { recursive: true });
+  await fs11.writeFile(file, next, "utf8");
+  const verb = raw.length === 0 ? "created" : found ? "refreshed" : "added";
+  console.log(`neat claude: ${verb} the \`${NEAT_SECTION_HEADING}\` section in ${file}`);
+  console.log("Your agent will now reach for `neat ask` before Read/Grep/Bash. Restart the");
+  console.log("session (or reload CLAUDE.md) to pick it up.");
+  return { exitCode: 0 };
+}
+async function runUninstall() {
+  const file = claudeMdPath();
+  const raw = await readIfExists(file);
+  if (raw === null) {
+    console.log(`neat claude: no CLAUDE.md at ${file} \u2014 nothing to remove.`);
+    return { exitCode: 0 };
+  }
+  const { before, after, found } = splitAroundSection(raw);
+  if (!found) {
+    console.log(`neat claude: no \`${NEAT_SECTION_HEADING}\` section in ${file} \u2014 nothing to remove.`);
+    return { exitCode: 0 };
+  }
+  const remaining = [before, after].filter((s) => s.length > 0).join("\n\n");
+  const next = remaining.length > 0 ? remaining.replace(/\n*$/, "") + "\n" : "";
+  await fs11.writeFile(file, next, "utf8");
+  console.log(`neat claude: removed the \`${NEAT_SECTION_HEADING}\` section from ${file}.`);
+  return { exitCode: 0 };
+}
+function usage2() {
+  console.log("neat claude \u2014 make the query-first directive always-on in Claude Code");
+  console.log("");
+  console.log("  install     write (or refresh) a `## neat` section in ./CLAUDE.md so your");
+  console.log("              agent reaches for `neat ask` before Read/Grep/Bash");
+  console.log("  uninstall   remove the `## neat` section from ./CLAUDE.md");
+  console.log("  print       print the directive block to stdout (for a manual paste)");
+  console.log("");
+  console.log("Idempotent: re-running install replaces its own section, never duplicates it.");
+  console.log("Target file overridable via NEAT_CLAUDE_MD.");
+}
+async function runClaudeCommand(args) {
+  const sub = args[0];
+  if (sub === "-h" || sub === "--help" || sub === void 0) {
+    usage2();
+    return sub === void 0 ? 2 : 0;
+  }
+  try {
+    switch (sub) {
+      case "install":
+        return (await runInstall()).exitCode;
+      case "uninstall":
+        return (await runUninstall()).exitCode;
+      case "print":
+        process.stdout.write(neatSection());
+        return 0;
+      default:
+        console.error(`neat claude: unknown subcommand "${sub}"`);
+        usage2();
+        return 2;
+    }
+  } catch (err) {
+    console.error(`neat claude: ${err.message}`);
+    return 1;
+  }
+}
+
+// src/codex-cli.ts
+import path13 from "path";
+import os2 from "os";
+import { promises as fs12 } from "fs";
 import { isDeepStrictEqual } from "util";
 import { parse as parseToml, stringify as stringifyToml } from "smol-toml";
 var CODEX_MCP_SERVER = {
@@ -5020,14 +5187,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 path12.resolve(override);
+  if (override && override.length > 0) return path13.resolve(override);
   const home = process.env.HOME ?? process.env.USERPROFILE ?? os2.homedir();
-  return path12.join(home, ".codex", "config.toml");
+  return path13.join(home, ".codex", "config.toml");
 }
 function agentsFilePath() {
   const override = process.env.NEAT_CODEX_AGENTS;
-  if (override && override.length > 0) return path12.resolve(override);
-  return path12.join(process.cwd(), "AGENTS.md");
+  if (override && override.length > 0) return path13.resolve(override);
+  return path13.join(process.cwd(), "AGENTS.md");
 }
 function isTableHeader(line) {
   return /^\s*\[\[?[^\]]+\]\]?\s*$/.test(line);
@@ -5161,7 +5328,7 @@ async function runCodex(opts) {
   const agentsPath = agentsFilePath();
   let configRaw = "";
   try {
-    configRaw = await fs11.readFile(configPath, "utf8");
+    configRaw = await fs12.readFile(configPath, "utf8");
   } catch (err) {
     if (err.code !== "ENOENT") {
       console.error(`neat codex: failed to read ${configPath} \u2014 ${err.message}`);
@@ -5170,7 +5337,7 @@ async function runCodex(opts) {
   }
   let agentsRaw = "";
   try {
-    agentsRaw = await fs11.readFile(agentsPath, "utf8");
+    agentsRaw = await fs12.readFile(agentsPath, "utf8");
   } catch (err) {
     if (err.code !== "ENOENT") {
       console.error(`neat codex: failed to read ${agentsPath} \u2014 ${err.message}`);
@@ -5210,15 +5377,15 @@ async function runCodex(opts) {
     return { exitCode: 0 };
   }
   if (config.changed) {
-    await fs11.mkdir(path12.dirname(configPath), { recursive: true });
-    await fs11.writeFile(configPath, config.text, "utf8");
+    await fs12.mkdir(path13.dirname(configPath), { recursive: true });
+    await fs12.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 fs11.mkdir(path12.dirname(agentsPath), { recursive: true });
-    await fs11.writeFile(agentsPath, agents.text, "utf8");
+    await fs12.mkdir(path13.dirname(agentsPath), { recursive: true });
+    await fs12.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`);
@@ -5228,7 +5395,7 @@ async function runCodex(opts) {
   console.log("points the server at the local daemon \u2014 edit it for a non-default one.");
   return { exitCode: 0 };
 }
-function usage2() {
+function usage3() {
   console.log("neat codex \u2014 install NEAT into the OpenAI Codex CLI (MCP server + AGENTS.md)");
   console.log("");
   console.log("  (no flag)        plan: print what would change, write nothing");
@@ -5256,11 +5423,11 @@ async function runCodexCommand(args) {
         break;
       case "-h":
       case "--help":
-        usage2();
+        usage3();
         return 0;
       default:
         console.error(`neat codex: unknown flag "${arg}"`);
-        usage2();
+        usage3();
         return 2;
     }
   }
@@ -5274,9 +5441,9 @@ async function runCodexCommand(args) {
 }
 
 // src/editors-cli.ts
-import path13 from "path";
+import path14 from "path";
 import os3 from "os";
-import { promises as fs12 } from "fs";
+import { promises as fs13 } from "fs";
 import { isDeepStrictEqual as isDeepStrictEqual2 } from "util";
 import * as jsonc from "jsonc-parser";
 var NEAT_MCP_SERVER = {
@@ -5300,17 +5467,17 @@ function homeDir() {
 }
 function xdgConfigDir() {
   const xdg = process.env.XDG_CONFIG_HOME;
-  return xdg && xdg.length > 0 ? path13.resolve(xdg) : path13.join(homeDir(), ".config");
+  return xdg && xdg.length > 0 ? path14.resolve(xdg) : path14.join(homeDir(), ".config");
 }
 function envOverride(name) {
   const v = process.env[name];
-  return v && v.length > 0 ? path13.resolve(v) : void 0;
+  return v && v.length > 0 ? path14.resolve(v) : void 0;
 }
 var CURSOR_CLIENT = {
   id: "cursor",
   label: "Cursor",
   docsUrl: "https://docs.cursor.com/context/mcp",
-  mcpConfigPath: () => envOverride("NEAT_CURSOR_CONFIG") ?? path13.join(homeDir(), ".cursor", "mcp.json"),
+  mcpConfigPath: () => envOverride("NEAT_CURSOR_CONFIG") ?? path14.join(homeDir(), ".cursor", "mcp.json"),
   mcpContainerKey: "mcpServers",
   format: "json",
   // Cursor still reads a single `.cursorrules` at the project root (the modern
@@ -5322,7 +5489,7 @@ var DEVIN_CLIENT = {
   id: "devin",
   label: "Devin Desktop (Cascade)",
   docsUrl: "https://docs.devin.ai/desktop/cascade/mcp",
-  mcpConfigPath: () => envOverride("NEAT_DEVIN_CONFIG") ?? path13.join(homeDir(), ".codeium", "windsurf", "mcp_config.json"),
+  mcpConfigPath: () => envOverride("NEAT_DEVIN_CONFIG") ?? path14.join(homeDir(), ".codeium", "windsurf", "mcp_config.json"),
   mcpContainerKey: "mcpServers",
   format: "json",
   rulesFileName: ".windsurfrules"
@@ -5331,7 +5498,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") ?? path13.join(homeDir(), ".gemini", "settings.json"),
+  mcpConfigPath: () => envOverride("NEAT_GEMINI_CONFIG") ?? path14.join(homeDir(), ".gemini", "settings.json"),
   mcpContainerKey: "mcpServers",
   format: "json",
   rulesFileName: "GEMINI.md"
@@ -5340,7 +5507,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") ?? path13.join(homeDir(), ".qwen", "settings.json"),
+  mcpConfigPath: () => envOverride("NEAT_QWEN_CONFIG") ?? path14.join(homeDir(), ".qwen", "settings.json"),
   mcpContainerKey: "mcpServers",
   format: "json",
   rulesFileName: "QWEN.md"
@@ -5349,7 +5516,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") ?? path13.join(homeDir(), ".aws", "amazonq", "mcp.json"),
+  mcpConfigPath: () => envOverride("NEAT_AMAZONQ_CONFIG") ?? path14.join(homeDir(), ".aws", "amazonq", "mcp.json"),
   mcpContainerKey: "mcpServers",
   format: "json"
 };
@@ -5357,7 +5524,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") ?? path13.join(process.cwd(), ".roo", "mcp.json"),
+  mcpConfigPath: () => envOverride("NEAT_ROOCODE_CONFIG") ?? path14.join(process.cwd(), ".roo", "mcp.json"),
   mcpContainerKey: "mcpServers",
   format: "json"
 };
@@ -5370,9 +5537,9 @@ var ZED_CLIENT = {
     if (override) return override;
     if (process.platform === "win32") {
       const appData = process.env.APPDATA;
-      if (appData && appData.length > 0) return path13.join(appData, "Zed", "settings.json");
+      if (appData && appData.length > 0) return path14.join(appData, "Zed", "settings.json");
     }
-    return path13.join(homeDir(), ".config", "zed", "settings.json");
+    return path14.join(homeDir(), ".config", "zed", "settings.json");
   },
   mcpContainerKey: "context_servers",
   format: "jsonc",
@@ -5382,7 +5549,7 @@ var OPENCODE_CLIENT = {
   id: "opencode",
   label: "OpenCode",
   docsUrl: "https://opencode.ai/docs/mcp-servers/",
-  mcpConfigPath: () => envOverride("NEAT_OPENCODE_CONFIG") ?? path13.join(xdgConfigDir(), "opencode", "opencode.json"),
+  mcpConfigPath: () => envOverride("NEAT_OPENCODE_CONFIG") ?? path14.join(xdgConfigDir(), "opencode", "opencode.json"),
   mcpContainerKey: "mcp",
   format: "json",
   serverEntry: NEAT_OPENCODE_SERVER,
@@ -5392,7 +5559,7 @@ var CRUSH_CLIENT = {
   id: "crush",
   label: "Crush",
   docsUrl: "https://charmbracelet-crush.mintlify.app/configuration/mcp",
-  mcpConfigPath: () => envOverride("NEAT_CRUSH_CONFIG") ?? path13.join(xdgConfigDir(), "crush", "crush.json"),
+  mcpConfigPath: () => envOverride("NEAT_CRUSH_CONFIG") ?? path14.join(xdgConfigDir(), "crush", "crush.json"),
   mcpContainerKey: "mcp",
   format: "json",
   serverEntry: NEAT_CRUSH_SERVER,
@@ -5455,7 +5622,7 @@ async function planMcp(client, mcpPath) {
   const serverEntry = client.serverEntry ?? NEAT_MCP_SERVER;
   let raw = "";
   try {
-    raw = await fs12.readFile(mcpPath, "utf8");
+    raw = await fs13.readFile(mcpPath, "utf8");
   } catch (err) {
     const e = err;
     if (e.code === "ENOENT") {
@@ -5497,7 +5664,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 ? path13.join(opts.projectDir, client.rulesFileName) : "";
+  const rulesPath = hasRules ? path14.join(opts.projectDir, client.rulesFileName) : "";
   const mcp = await planMcp(client, mcpPath);
   if (mcp === null) return { exitCode: 1 };
   let existingRules = "";
@@ -5506,7 +5673,7 @@ async function runEditorInstall(client, opts) {
   let block = "";
   if (hasRules) {
     try {
-      existingRules = await fs12.readFile(rulesPath, "utf8");
+      existingRules = await fs13.readFile(rulesPath, "utf8");
     } catch (err) {
       if (err.code !== "ENOENT") {
         console.error(`neat ${client.id}: failed to read ${rulesPath} \u2014 ${err.message}`);
@@ -5540,11 +5707,11 @@ async function runEditorInstall(client, opts) {
     );
     return { exitCode: 0 };
   }
-  await fs12.mkdir(path13.dirname(mcpPath), { recursive: true });
-  await fs12.writeFile(mcpPath, mcp.text, "utf8");
+  await fs13.mkdir(path14.dirname(mcpPath), { recursive: true });
+  await fs13.writeFile(mcpPath, mcp.text, "utf8");
   if (hasRules) {
-    await fs12.mkdir(path13.dirname(rulesPath), { recursive: true });
-    await fs12.writeFile(rulesPath, newRules, "utf8");
+    await fs13.mkdir(path14.dirname(rulesPath), { recursive: true });
+    await fs13.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)`);
@@ -5557,7 +5724,7 @@ async function runEditorInstall(client, opts) {
 function indent(text) {
   return text.split("\n").map((line) => line.length > 0 ? `    ${line}` : line).join("\n");
 }
-function usage3(client) {
+function usage4(client) {
   const hasRules = typeof client.rulesFileName === "string";
   console.log(
     hasRules ? `neat ${client.id} \u2014 install NEAT's MCP server + graph-first guidance into ${client.label}` : `neat ${client.id} \u2014 install NEAT's MCP server into ${client.label}`
@@ -5588,11 +5755,11 @@ async function runEditorCommand(clientId, args, projectDir = process.cwd()) {
         break;
       case "-h":
       case "--help":
-        usage3(client);
+        usage4(client);
         return 0;
       default:
         console.error(`neat ${client.id}: unknown flag "${arg}"`);
-        usage3(client);
+        usage4(client);
         return 2;
     }
   }
@@ -5634,10 +5801,10 @@ function createHttpClient(baseUrl, bearerToken) {
   const root = baseUrl.replace(/\/$/, "");
   const authHeader = bearerToken && bearerToken.length > 0 ? { authorization: `Bearer ${bearerToken}` } : {};
   return {
-    async get(path16) {
+    async get(path17) {
       let res;
       try {
-        res = await fetch(`${root}${path16}`, {
+        res = await fetch(`${root}${path17}`, {
           headers: { ...authHeader }
         });
       } catch (err) {
@@ -5649,16 +5816,16 @@ function createHttpClient(baseUrl, bearerToken) {
         const body = await res.text().catch(() => "");
         throw new HttpError(
           res.status,
-          `${res.status} ${res.statusText} on GET ${path16}: ${body}`,
+          `${res.status} ${res.statusText} on GET ${path17}: ${body}`,
           body
         );
       }
       return await res.json();
     },
-    async post(path16, body) {
+    async post(path17, body) {
       let res;
       try {
-        res = await fetch(`${root}${path16}`, {
+        res = await fetch(`${root}${path17}`, {
           method: "POST",
           headers: { "content-type": "application/json", ...authHeader },
           body: JSON.stringify(body)
@@ -5672,7 +5839,7 @@ function createHttpClient(baseUrl, bearerToken) {
         const text = await res.text().catch(() => "");
         throw new HttpError(
           res.status,
-          `${res.status} ${res.statusText} on POST ${path16}: ${text}`,
+          `${res.status} ${res.statusText} on POST ${path17}: ${text}`,
           text
         );
       }
@@ -5686,12 +5853,12 @@ function projectPath(project, suffix) {
 }
 async function runRootCause(client, input) {
   const qs = input.errorId ? `?errorId=${encodeURIComponent(input.errorId)}` : "";
-  const path16 = projectPath(
+  const path17 = projectPath(
     input.project,
     `/graph/root-cause/${encodeURIComponent(input.errorNode)}${qs}`
   );
   try {
-    const result = await client.get(path16);
+    const result = await client.get(path17);
     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}.` : "");
@@ -5717,12 +5884,12 @@ async function runRootCause(client, input) {
 }
 async function runBlastRadius(client, input) {
   const qs = input.depth !== void 0 ? `?depth=${input.depth}` : "";
-  const path16 = projectPath(
+  const path17 = projectPath(
     input.project,
     `/graph/blast-radius/${encodeURIComponent(input.nodeId)}${qs}`
   );
   try {
-    const result = await client.get(path16);
+    const result = await client.get(path17);
     if (result.totalAffected === 0) {
       return {
         summary: `${result.origin} has no dependents. Nothing else would break if it failed.`
@@ -5756,12 +5923,12 @@ function formatBlastEntry(n) {
 }
 async function runDependencies(client, input) {
   const depth = input.depth ?? 3;
-  const path16 = projectPath(
+  const path17 = projectPath(
     input.project,
     `/graph/dependencies/${encodeURIComponent(input.nodeId)}?depth=${depth}`
   );
   try {
-    const result = await client.get(path16);
+    const result = await client.get(path17);
     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}).`
@@ -5853,9 +6020,9 @@ function formatDuration(ms) {
   return `${Math.round(h / 24)}d`;
 }
 async function runIncidents(client, input) {
-  const path16 = input.nodeId ? projectPath(input.project, `/incidents/${encodeURIComponent(input.nodeId)}`) : projectPath(input.project, "/incidents");
+  const path17 = input.nodeId ? projectPath(input.project, `/incidents/${encodeURIComponent(input.nodeId)}`) : projectPath(input.project, "/incidents");
   try {
-    const body = await client.get(path16);
+    const body = await client.get(path17);
     const events = body.events;
     if (events.length === 0) {
       return {
@@ -6096,6 +6263,33 @@ async function runDivergences(client, input) {
     provenance: "composite (EXTRACTED + OBSERVED)"
   };
 }
+async function runAsk(client, input) {
+  const result = await client.get(
+    projectPath(input.project, `/graph/ask?q=${encodeURIComponent(input.question)}`)
+  );
+  const blockLines = [];
+  if (result.matched.length > 0) {
+    blockLines.push(
+      `Matched: ${result.matched.map((m) => `${m.nodeId} [${m.via} ${m.score.toFixed(2)}]`).join(", ")}`
+    );
+    blockLines.push(`Intent: ${result.intent}`);
+  } else if (result.scope === "global") {
+    blockLines.push(`Graph-wide answer (${result.intent}) \u2014 no entity named.`);
+  }
+  for (const section of result.sections) {
+    blockLines.push("", section.heading + ":");
+    for (const fact of section.facts) {
+      const tag = fact.provenance ? ` [${fact.provenance}${fact.confidence !== void 0 ? ` ${fact.confidence.toFixed(2)}` : ""}]` : fact.confidence !== void 0 ? ` [confidence ${fact.confidence.toFixed(2)}]` : "";
+      blockLines.push(`  \u2022 ${fact.text}${tag}`);
+    }
+  }
+  return {
+    summary: result.answer,
+    block: blockLines.join("\n").trim(),
+    ...result.confidence !== void 0 ? { confidence: result.confidence } : {},
+    ...result.provenance.length > 0 ? { provenance: result.provenance } : {}
+  };
+}
 function formatFooter(confidence, provenance) {
   const c = confidence === void 0 ? "n/a" : confidence.toFixed(2);
   const p = provenance === void 0 ? "n/a" : Array.isArray(provenance) ? [...new Set(provenance)].join(", ") : provenance;
@@ -6508,7 +6702,7 @@ function sleep(ms, signal) {
 }
 
 // src/cli-verbs.ts
-import path14 from "path";
+import path15 from "path";
 async function resolveProjectEntry(opts) {
   const entries = await listProjects();
   if (opts.project) {
@@ -6518,7 +6712,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}${path14.sep}`)) {
+    if (resolvedCwd === entry2.path || resolvedCwd.startsWith(`${entry2.path}${path15.sep}`)) {
       return entry2;
     }
   }
@@ -6683,7 +6877,7 @@ function isNpxInvocation() {
 function commandPrefix() {
   return isNpxInvocation() ? "npx neat.is" : "neat";
 }
-function usage4() {
+function usage5() {
   const neat = commandPrefix();
   console.log("Installed via npx? Prefix commands with `npx neat.is`, or install once: `npm i -g neat.is`.");
   console.log("");
@@ -6731,13 +6925,21 @@ function usage4() {
   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("                 grepping. Installs a Claude Code search hook (nudge by default,");
+  console.log("                 or a hard gate) and agent-agnostic graph-first guidance.");
   console.log("                 Flags:");
   console.log("                   --apply          install the hook + guidance");
+  console.log("                   --gate           with --apply: DENY search until `neat ask`");
+  console.log("                                    has run this session (default: nudge-only)");
   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("  claude         Write the query-first directive into ./CLAUDE.md as a `## neat`");
+  console.log("                 section so an agent reaches for `neat ask` before Read/Grep/Bash.");
+  console.log("                 Subcommands:");
+  console.log("                   install     write (or refresh) the `## neat` section");
+  console.log("                   uninstall   remove the `## neat` section");
+  console.log("                   print       print the directive block to stdout");
   console.log("  codex          Install NEAT into the OpenAI Codex CLI: add [mcp_servers.neat]");
   console.log("                 to ~/.codex/config.toml and the graph-first block to ./AGENTS.md.");
   console.log("                 Plan by default; --apply to write.");
@@ -6814,6 +7016,10 @@ function usage4() {
   console.log("                 run time; the config file is written owner-only (0600).");
   console.log("");
   console.log("query commands (mirror the MCP tools, ADR-050):");
+  console.log("  ask <question>                   Plain-language door: resolves the question to");
+  console.log("                                   nodes and routes it to the right traversal, with");
+  console.log("                                   a compact provenance-tagged answer. Reach here first.");
+  console.log(`                                   example: ${neat} ask "why is checkout failing?"`);
   console.log("  root-cause <node-id>             Walk inbound edges to find what broke first.");
   console.log(`                                   example: ${neat} root-cause service:<name>`);
   console.log("  blast-radius <node-id>           BFS inbound \u2014 the dependents that break if this dies.");
@@ -7033,7 +7239,7 @@ async function buildPatchSections(services, project) {
 }
 async function runInit(opts) {
   const written = [];
-  const stat = await fs13.stat(opts.scanPath).catch(() => null);
+  const stat = await fs14.stat(opts.scanPath).catch(() => null);
   if (!stat || !stat.isDirectory()) {
     console.error(`neat init: ${opts.scanPath} is not a directory`);
     return { exitCode: 2, writtenFiles: written };
@@ -7042,13 +7248,13 @@ async function runInit(opts) {
   printDiscoveryReport(opts, services);
   const sections = opts.noInstall ? [] : await buildPatchSections(services, opts.project);
   const patch = renderPatch(sections);
-  const patchPath = path15.join(opts.scanPath, "neat.patch");
+  const patchPath = path16.join(opts.scanPath, "neat.patch");
   if (opts.dryRun) {
-    await fs13.writeFile(patchPath, patch, "utf8");
+    await fs14.writeFile(patchPath, patch, "utf8");
     written.push(patchPath);
     console.log(`dry-run: patch written to ${patchPath}`);
-    const gitignorePath = path15.join(opts.scanPath, ".gitignore");
-    const gitignoreExists = await fs13.stat(gitignorePath).then(() => true).catch(() => false);
+    const gitignorePath = path16.join(opts.scanPath, ".gitignore");
+    const gitignoreExists = await fs14.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.");
@@ -7059,9 +7265,9 @@ async function runInit(opts) {
   const graph = getGraph(graphKey);
   const projectPaths = pathsForProject(
     graphKey,
-    path15.join(opts.scanPath, "neat-out")
+    path16.join(opts.scanPath, "neat-out")
   );
-  const errorsPath = path15.join(path15.dirname(opts.outPath), path15.basename(projectPaths.errorsPath));
+  const errorsPath = path16.join(path16.dirname(opts.outPath), path16.basename(projectPaths.errorsPath));
   const result = await extractFromDirectory(graph, opts.scanPath, { errorsPath });
   await saveGraphToDisk(graph, opts.outPath);
   written.push(opts.outPath);
@@ -7140,7 +7346,7 @@ async function runInit(opts) {
         console.log("Run `npm install` (or your language equivalent) to refresh lockfiles.");
       }
     } else {
-      await fs13.writeFile(patchPath, patch, "utf8");
+      await fs14.writeFile(patchPath, patch, "utf8");
       written.push(patchPath);
     }
   }
@@ -7180,9 +7386,9 @@ var CLAUDE_SKILL_CONFIG = {
 };
 function claudeConfigPath() {
   const override = process.env.NEAT_CLAUDE_CONFIG;
-  if (override && override.length > 0) return path15.resolve(override);
+  if (override && override.length > 0) return path16.resolve(override);
   const home = process.env.HOME ?? process.env.USERPROFILE ?? "";
-  return path15.join(home, ".claude.json");
+  return path16.join(home, ".claude.json");
 }
 async function runSkill(opts) {
   const snippet = JSON.stringify(CLAUDE_SKILL_CONFIG, null, 2) + "\n";
@@ -7194,7 +7400,7 @@ async function runSkill(opts) {
     const target = claudeConfigPath();
     let existing = {};
     try {
-      existing = JSON.parse(await fs13.readFile(target, "utf8"));
+      existing = JSON.parse(await fs14.readFile(target, "utf8"));
     } catch (err) {
       if (err.code !== "ENOENT") {
         console.error(`neat skill: failed to read ${target} \u2014 ${err.message}`);
@@ -7206,8 +7412,8 @@ async function runSkill(opts) {
       ...existing,
       mcpServers: { ...mcp, neat: CLAUDE_SKILL_CONFIG.mcpServers.neat }
     };
-    await fs13.mkdir(path15.dirname(target), { recursive: true });
-    await fs13.writeFile(target, JSON.stringify(merged, null, 2) + "\n", "utf8");
+    await fs14.mkdir(path16.dirname(target), { recursive: true });
+    await fs14.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("");
@@ -7234,7 +7440,7 @@ async function main() {
   const argv = process.argv.slice(2);
   const cmd0 = argv[0];
   if (cmd0 === "-h" || cmd0 === "--help") {
-    usage4();
+    usage5();
     process.exit(0);
   }
   if (cmd0 === "--version" || cmd0 === "-v" || cmd0 === "version") {
@@ -7256,6 +7462,11 @@ async function main() {
     if (code !== 0) process.exit(code);
     return;
   }
+  if (cmd0 === "claude") {
+    const code = await runClaudeCommand(argv.slice(1));
+    if (code !== 0) process.exit(code);
+    return;
+  }
   const EDITOR_VERBS = [
     "cursor",
     "devin",
@@ -7286,19 +7497,19 @@ async function main() {
     const target = positional[0];
     if (!target) {
       console.error("neat init: missing <path>");
-      usage4();
+      usage5();
       process.exit(2);
     }
     if (apply6 && dryRun) {
       console.error("neat init: --apply and --dry-run are mutually exclusive");
       process.exit(2);
     }
-    const scanPath = path15.resolve(target);
+    const scanPath = path16.resolve(target);
     const projectExplicit = parsed.project !== null;
-    const projectName = projectExplicit ? project : path15.basename(scanPath);
+    const projectName = projectExplicit ? project : path16.basename(scanPath);
     const projectKey = projectExplicit ? project : DEFAULT_PROJECT;
-    const fallback = pathsForProject(projectKey, path15.join(scanPath, "neat-out")).snapshotPath;
-    const outPath = path15.resolve(process.env.NEAT_OUT_PATH ?? fallback);
+    const fallback = pathsForProject(projectKey, path16.join(scanPath, "neat-out")).snapshotPath;
+    const outPath = path16.resolve(process.env.NEAT_OUT_PATH ?? fallback);
     const result = await runInit({
       scanPath,
       outPath,
@@ -7316,24 +7527,24 @@ async function main() {
     const target = positional[0];
     if (!target) {
       console.error("neat watch: missing <path>");
-      usage4();
+      usage5();
       process.exit(2);
     }
-    const scanPath = path15.resolve(target);
-    const stat = await fs13.stat(scanPath).catch(() => null);
+    const scanPath = path16.resolve(target);
+    const stat = await fs14.stat(scanPath).catch(() => null);
     if (!stat || !stat.isDirectory()) {
       console.error(`neat watch: ${scanPath} is not a directory`);
       process.exit(2);
     }
-    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 projectPaths = pathsForProject(project, path16.join(scanPath, "neat-out"));
+    const outPath = path16.resolve(process.env.NEAT_OUT_PATH ?? projectPaths.snapshotPath);
+    const errorsPath = path16.resolve(
+      process.env.NEAT_ERRORS_PATH ?? path16.join(path16.dirname(outPath), path16.basename(projectPaths.errorsPath))
     );
-    const staleEventsPath = path15.resolve(
-      process.env.NEAT_STALE_EVENTS_PATH ?? path15.join(path15.dirname(outPath), path15.basename(projectPaths.staleEventsPath))
+    const staleEventsPath = path16.resolve(
+      process.env.NEAT_STALE_EVENTS_PATH ?? path16.join(path16.dirname(outPath), path16.basename(projectPaths.staleEventsPath))
     );
-    const embeddingsCachePath = process.env.NEAT_EMBEDDINGS_CACHE_PATH ? path15.resolve(process.env.NEAT_EMBEDDINGS_CACHE_PATH) : void 0;
+    const embeddingsCachePath = process.env.NEAT_EMBEDDINGS_CACHE_PATH ? path16.resolve(process.env.NEAT_EMBEDDINGS_CACHE_PATH) : void 0;
     const handle = await startWatch(getGraph(project), {
       scanPath,
       outPath,
@@ -7342,7 +7553,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 ? path15.resolve(process.env.NEAT_HOME) : path15.join(os4.homedir(), ".neat"),
+      neatHome: process.env.NEAT_HOME ? path16.resolve(process.env.NEAT_HOME) : path16.join(os4.homedir(), ".neat"),
       ...embeddingsCachePath ? { embeddingsCachePath } : {},
       host: process.env.HOST ?? "0.0.0.0",
       port: Number(process.env.PORT ?? 8080),
@@ -7378,7 +7589,7 @@ async function main() {
     const name = positional[0];
     if (!name) {
       console.error("neat pause: missing <name>");
-      usage4();
+      usage5();
       process.exit(2);
     }
     const daemon = await findDaemonByProject(name);
@@ -7403,7 +7614,7 @@ async function main() {
     const name = positional[0];
     if (!name) {
       console.error("neat resume: missing <name>");
-      usage4();
+      usage5();
       process.exit(2);
     }
     const daemon = await findDaemonByProject(name);
@@ -7433,7 +7644,7 @@ async function main() {
     const name = positional[0];
     if (!name) {
       console.error("neat uninstall: missing <name>");
-      usage4();
+      usage5();
       process.exit(2);
     }
     const daemon = await findDaemonByProject(name);
@@ -7520,15 +7731,15 @@ async function main() {
     return;
   }
   console.error(`neat: unknown command "${cmd}"`);
-  usage4();
+  usage5();
   process.exit(1);
 }
 async function tryOrchestrator(cmd, parsed) {
-  const scanPath = path15.resolve(cmd);
-  const stat = await fs13.stat(scanPath).catch(() => null);
+  const scanPath = path16.resolve(cmd);
+  const stat = await fs14.stat(scanPath).catch(() => null);
   if (!stat || !stat.isDirectory()) return null;
   const projectExplicit = parsed.project !== null;
-  const projectName = projectExplicit ? parsed.project : path15.basename(scanPath);
+  const projectName = projectExplicit ? parsed.project : path16.basename(scanPath);
   const result = await runOrchestrator({
     scanPath,
     project: projectName,
@@ -7550,7 +7761,10 @@ var QUERY_VERBS = /* @__PURE__ */ new Set([
   "stale-edges",
   "policies",
   // Tenth verb (ADR-060) — amends ADR-050's locked allowlist of nine.
-  "divergences"
+  "divergences",
+  // Twelfth verb (ADR-198) — the plain-language door over the whole tool
+  // surface. Amends ADR-050's locked allowlist the same way `divergences` did.
+  "ask"
 ]);
 function resolveProjectFlag(parsed) {
   if (parsed.project) return parsed.project;
@@ -7672,6 +7886,15 @@ async function runQueryVerb(cmd, parsed) {
       makeWork = (project) => runSearch(client, { query: q, ...project ? { project } : {} });
       break;
     }
+    case "ask": {
+      const question = positional.join(" ").trim();
+      if (!question) {
+        console.error("neat ask: missing <question>");
+        return 2;
+      }
+      makeWork = (project) => runAsk(client, { question, ...project ? { project } : {} });
+      break;
+    }
     case "diff": {
       const against = parsed.against ?? parsed.since;
       if (!against) {
@@ -7816,6 +8039,6 @@ export {
   runMonitorVerb,
   runQueryVerb,
   runSkill,
-  usage4 as usage
+  usage5 as usage
 };
 //# sourceMappingURL=cli.js.map