@dadado/agent-kit-cli 5.4.0 → 5.5.0

package/dist/index.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 // src/index.ts
-import { defineCommand as defineCommand19, runMain, showUsage } from "citty";
+import { defineCommand as defineCommand20, runMain, showUsage } from "citty";
 
 // src/commands/add.ts
 import { defineCommand } from "citty";
@@ -216,7 +216,10 @@ var KNOWN_SHIPPED_OVERLAY_HASHES = /* @__PURE__ */ new Set([
   "86afbea8f64de68a79ad5e374f3132bdbe2582b94321fb3d438314838e36c776",
   "65cc1c0293b145e48ed73ad0ca9ab33cbba5ed834a5bfb31f195ed30c2f143df",
   "f04fcfe31354d1b09aeb256a17e4aab91c98ea48a5cff25e4a0281af3cfb289f",
-  "34e559ad9036d93d9cbc96d394bc2bbeb10ce50ead00d58a914158ae19daa76c"
+  "34e559ad9036d93d9cbc96d394bc2bbeb10ce50ead00d58a914158ae19daa76c",
+  "359a142aeadd769a9b89ac909ae5129940e7e6b0892b70256098c584d97631ce",
+  "8eab94f7a78149db1bbbc0fd45f21dc2d874209d534bcff39077fd6e1d2c42fb",
+  "9be406f92f7dca71f3af814b14fb26b011f9f12c37c789f7ddc3d647b1a7ab60"
 ]);
 
 // src/lifecycle/paths.ts
@@ -239,7 +242,8 @@ var MANAGED_HASHES_REL = ".cursor/agent-kit.managed-hashes.json";
 var CONSUMER_OVERLAY_PREFIXES = [
   ".cursor/agents/",
   ".cursor/skills/",
-  ".cursor/commands/"
+  ".cursor/commands/",
+  ".claude/commands/"
 ];
 function isConsumerOverlayPath(relPath) {
   const norm = relPath.split(path3.sep).join("/");
@@ -742,8 +746,8 @@ async function hasRegistryIndex(root) {
   return fileExists(path5.join(root, "registry", "registry.json"));
 }
 async function cloneRegistry(url, ref, dest) {
-  const { mkdir: mkdir7 } = await import("fs/promises");
-  await mkdir7(path5.dirname(dest), { recursive: true });
+  const { mkdir: mkdir8 } = await import("fs/promises");
+  await mkdir8(path5.dirname(dest), { recursive: true });
   try {
     await execFileAsync("git", ["clone", "--depth", "1", "--branch", ref, "--", url, dest], {
       env: gitEnv()
@@ -2383,7 +2387,7 @@ var CONFIG_REVIEW_PREFLIGHT = Object.freeze(["off", "warn", "block"]);
 function resolveContextConfigPath(repoRoot, fsHooks = {}) {
   const exists2 = fsHooks.existsSync;
   const realpath = fsHooks.realpathSync;
-  const mkdir7 = fsHooks.mkdirSync;
+  const mkdir8 = fsHooks.mkdirSync;
   if (typeof repoRoot !== "string" || !repoRoot) {
     return { ok: false, error: "invalid repo root" };
   }
@@ -2394,8 +2398,8 @@ function resolveContextConfigPath(repoRoot, fsHooks = {}) {
     return { ok: false, error: "path escape" };
   }
   try {
-    if (typeof mkdir7 === "function" && typeof exists2 === "function" && !exists2(contextDir)) {
-      mkdir7(contextDir, { recursive: true });
+    if (typeof mkdir8 === "function" && typeof exists2 === "function" && !exists2(contextDir)) {
+      mkdir8(contextDir, { recursive: true });
     }
     if (typeof realpath === "function" && typeof exists2 === "function" && exists2(abs)) {
       const fileReal = String(realpath(abs)).replace(/\\/g, "/");
@@ -2452,13 +2456,13 @@ function readPreferredBrowserFromConfig(configPath, fsHooks = {}) {
 }
 
 // src/commands/dashboard.ts
-function readPreferredBrowserFromWorkspace(cwd, readFile22 = readFileSync2) {
+function readPreferredBrowserFromWorkspace(cwd, readFile26 = readFileSync2) {
   const resolved = resolveContextConfigPath(path11.resolve(cwd), {
     existsSync,
     realpathSync
   });
   if (!resolved.ok) return null;
-  const value = readPreferredBrowserFromConfig(resolved.path, { readFileSync: readFile22 });
+  const value = readPreferredBrowserFromConfig(resolved.path, { readFileSync: readFile26 });
   return normalizePreferredBrowser(value);
 }
 function applyDashboardOpenEnv(env, opts) {
@@ -2876,7 +2880,7 @@ var diffCommand = defineCommand6({
 });
 
 // src/commands/doctor.ts
-import path24 from "path";
+import path25 from "path";
 import { defineCommand as defineCommand7 } from "citty";
 
 // src/invariants/hooks-health.ts
@@ -3092,6 +3096,142 @@ async function assessHooksHealth(rootDir) {
   };
 }
 
+// src/readiness/env-checks.ts
+import { constants as constants3, access as access6, readFile as readFile10, stat as stat3 } from "fs/promises";
+import { homedir as homedir2 } from "os";
+import path15 from "path";
+var MIN_NODE_MAJOR = 20;
+async function checkBinOnPath(binName, env, platform) {
+  const pathVar = env.PATH ?? env.Path ?? "";
+  if (!pathVar) return false;
+  const dirs = pathVar.split(path15.delimiter).filter(Boolean);
+  const candidates = platform === "win32" ? [binName, `${binName}.cmd`, `${binName}.exe`, `${binName}.bat`] : [binName];
+  for (const dir of dirs) {
+    for (const candidate2 of candidates) {
+      try {
+        await access6(path15.join(dir, candidate2), platform === "win32" ? void 0 : constants3.X_OK);
+        return true;
+      } catch {
+      }
+    }
+  }
+  return false;
+}
+function isNodeVersionOk(nodeVersion, minMajor = MIN_NODE_MAJOR) {
+  const match = /^v?(\d+)/.exec(nodeVersion);
+  if (!match) return false;
+  const major = Number(match[1]);
+  return Number.isFinite(major) && major >= minMajor;
+}
+function detectShellName(env, platform) {
+  if (platform === "win32") {
+    if (env.PSModulePath) return "powershell";
+    if (env.ComSpec) return "cmd";
+    return null;
+  }
+  const shellPath = env.SHELL;
+  if (!shellPath) return null;
+  const base = path15.basename(shellPath).trim();
+  return base || null;
+}
+function detectShellProfile(env, platform, homeDir) {
+  const shellName = detectShellName(env, platform);
+  if (shellName === "zsh") return path15.join(homeDir, ".zshrc");
+  if (shellName === "bash") return path15.join(homeDir, ".bashrc");
+  return null;
+}
+function parseNpmrcPrefix(content, homeDir) {
+  const match = /^\s*prefix\s*=\s*(.+?)\s*$/m.exec(content);
+  const captured = match?.[1];
+  if (!captured) return null;
+  let value = captured.trim().replace(/^["']|["']$/g, "");
+  if (value.startsWith("~")) {
+    value = path15.join(homeDir, value.slice(1));
+  }
+  return value || null;
+}
+function heuristicPrefixFromExecPath(execPath, platform) {
+  const p = platform === "win32" ? path15.win32 : path15.posix;
+  return platform === "win32" ? p.dirname(execPath) : p.dirname(p.dirname(execPath));
+}
+async function detectNpmPrefix(options = {}) {
+  const env = options.env ?? process.env;
+  const platform = options.platform ?? process.platform;
+  const homeDir = options.homeDir ?? homedir2();
+  const execPath = options.execPath ?? process.execPath;
+  const readFileImpl = options.readFileImpl ?? ((filePath) => readFile10(filePath, "utf8"));
+  const envPrefix = env.npm_config_prefix ?? env.NPM_CONFIG_PREFIX;
+  if (envPrefix?.trim()) {
+    return { prefix: envPrefix.trim(), source: "env" };
+  }
+  const userconfigPath = env.NPM_CONFIG_USERCONFIG ?? path15.join(homeDir, ".npmrc");
+  try {
+    const content = await readFileImpl(userconfigPath);
+    const npmrcPrefix = parseNpmrcPrefix(content, homeDir);
+    if (npmrcPrefix) {
+      return { prefix: npmrcPrefix, source: "npmrc" };
+    }
+  } catch {
+  }
+  return { prefix: heuristicPrefixFromExecPath(execPath, platform), source: "heuristic" };
+}
+async function describeUnwritablePrefix(prefix) {
+  try {
+    const info = await stat3(prefix);
+    const currentUid = typeof process.getuid === "function" ? process.getuid() : void 0;
+    if (process.platform !== "win32" && currentUid !== void 0 && info.uid === 0 && currentUid !== 0) {
+      return `root-owned prefix (${prefix}); the classic fresh-install PATH/EACCES blocker`;
+    }
+  } catch {
+  }
+  return `npm prefix is not writable: ${prefix}`;
+}
+async function checkNpmPrefixWritable(options = {}) {
+  let detected;
+  try {
+    detected = await detectNpmPrefix(options);
+  } catch {
+    return { prefix: null, writable: false, reason: "npm prefix could not be determined" };
+  }
+  try {
+    await access6(detected.prefix, constants3.W_OK);
+    return { prefix: detected.prefix, writable: true, source: detected.source };
+  } catch {
+    return {
+      prefix: detected.prefix,
+      writable: false,
+      source: detected.source,
+      reason: await describeUnwritablePrefix(detected.prefix)
+    };
+  }
+}
+async function assessEnvironment(options = {}) {
+  const env = options.env ?? process.env;
+  const platform = options.platform ?? process.platform;
+  const nodeVersion = options.nodeVersion ?? process.version;
+  const homeDir = options.homeDir ?? homedir2();
+  const binName = options.binName ?? "agent-kit";
+  const [binOnPath, npmPrefix] = await Promise.all([
+    checkBinOnPath(binName, env, platform).catch(() => false),
+    checkNpmPrefixWritable(options).catch(
+      () => ({
+        prefix: null,
+        writable: false,
+        reason: "npm prefix check failed unexpectedly"
+      })
+    )
+  ]);
+  return {
+    binOnPath,
+    npmPrefixWritable: npmPrefix.writable,
+    npmPrefix,
+    nodeVersionOk: isNodeVersionOk(nodeVersion),
+    nodeVersion,
+    shell: detectShellName(env, platform),
+    shellProfile: detectShellProfile(env, platform, homeDir)
+  };
+}
+
 // src/scanner/readiness.ts
 import { createHash as createHash3 } from "crypto";
 function action(id, status, recommendation, owner) {
@@ -3339,12 +3479,12 @@ function createReadinessReport(scan, options) {
 }
 
 // src/scanner/safe-fixes.ts
-import { readFile as readFile12, writeFile as writeFile5 } from "fs/promises";
-import path22 from "path";
+import { readFile as readFile13, writeFile as writeFile5 } from "fs/promises";
+import path23 from "path";
 
 // src/scanner/detect-repository.ts
-import { readFile as readFile10 } from "fs/promises";
-import path15 from "path";
+import { readFile as readFile11 } from "fs/promises";
+import path16 from "path";
 var CONTEXT_PATHS = [
   ["README.md", "README"],
   ["README", "README"],
@@ -3363,7 +3503,7 @@ var CONTEXT_PATHS = [
 async function existingEvidence(rootDir, candidates) {
   const evidence = await Promise.all(
     candidates.map(
-      async ([relativePath, label]) => await fileExists(path15.join(rootDir, relativePath)) ? { source: "file", value: `${relativePath}:${label}` } : void 0
+      async ([relativePath, label]) => await fileExists(path16.join(rootDir, relativePath)) ? { source: "file", value: `${relativePath}:${label}` } : void 0
     )
   );
   return evidence.flatMap((item) => item ? [item] : []);
@@ -3384,7 +3524,7 @@ async function detectContext(rootDir) {
 async function detectPurpose(rootDir, stack) {
   const entries = await listDirectory(rootDir);
   const lowerEntries = entries.map((entry) => entry.toLowerCase());
-  const packageJson = await readJson(path15.join(rootDir, "package.json"));
+  const packageJson = await readJson(path16.join(rootDir, "package.json"));
   const categories = [];
   const evidence = [];
   const add = (category, value2) => {
@@ -3424,16 +3564,16 @@ async function detectPurpose(rootDir, stack) {
 }
 async function detectAgentKit(rootDir) {
   const manifestRelativePath = ".cursor/agent-kit.json";
-  const manifestPath = path15.join(rootDir, manifestRelativePath);
+  const manifestPath = path16.join(rootDir, manifestRelativePath);
   const installed = await fileExists(manifestPath);
   const manifest = installed ? await readJson(manifestPath) : null;
   return {
     installed,
     manifestPath: installed ? manifestRelativePath : void 0,
     version: manifest?.version,
-    hasPlans: await fileExists(path15.join(rootDir, ".cursor/plans")),
-    hasHandoff: await fileExists(path15.join(rootDir, ".cursor/HANDOFF.md")),
-    hasMemory: await fileExists(path15.join(rootDir, ".cursor/memory"))
+    hasPlans: await fileExists(path16.join(rootDir, ".cursor/plans")),
+    hasHandoff: await fileExists(path16.join(rootDir, ".cursor/HANDOFF.md")),
+    hasMemory: await fileExists(path16.join(rootDir, ".cursor/memory"))
   };
 }
 var REQUIRED_SECRET_PATTERNS = [
@@ -3447,9 +3587,9 @@ var REQUIRED_SECRET_PATTERNS = [
   "*service-account*.json"
 ];
 async function detectSafety(rootDir, trackedFiles) {
-  const gitignorePath = path15.join(rootDir, ".gitignore");
+  const gitignorePath = path16.join(rootDir, ".gitignore");
   const hasGitignore = await fileExists(gitignorePath);
-  const gitignore = hasGitignore ? await readFile10(gitignorePath, "utf8") : "";
+  const gitignore = hasGitignore ? await readFile11(gitignorePath, "utf8") : "";
   const lines = gitignore.split(/\r?\n/).map((line) => line.trim()).filter((line) => line && !line.startsWith("#"));
   const ignoredSecretPatterns = REQUIRED_SECRET_PATTERNS.filter(
     (pattern) => lines.includes(pattern)
@@ -3458,7 +3598,7 @@ async function detectSafety(rootDir, trackedFiles) {
     (file) => /(^|\/)(\.env(\..+)?|.*\.(key|pem|p12|pfx)|.*credentials.*\.json)$/i.test(file)
   );
   const hookPaths = [".husky", ".git/hooks/pre-commit", "git-hooks/pre-commit"];
-  const hasHooks = (await Promise.all(hookPaths.map((item) => fileExists(path15.join(rootDir, item))))).some(Boolean);
+  const hasHooks = (await Promise.all(hookPaths.map((item) => fileExists(path16.join(rootDir, item))))).some(Boolean);
   const guardCandidates = [
     ".husky/pre-commit",
     ".husky/pre-push",
@@ -3467,7 +3607,7 @@ async function detectSafety(rootDir, trackedFiles) {
   ];
   const guardContents = await Promise.all(
     guardCandidates.map(
-      async (item) => await fileExists(path15.join(rootDir, item)) ? readFile10(path15.join(rootDir, item), "utf8") : ""
+      async (item) => await fileExists(path16.join(rootDir, item)) ? readFile11(path16.join(rootDir, item), "utf8") : ""
     )
   );
   return {
@@ -3485,11 +3625,11 @@ async function detectSafety(rootDir, trackedFiles) {
 }
 
 // src/scanner/scan.ts
-import path21 from "path";
+import path22 from "path";
 
 // src/scanner/detect-git.ts
 import { execFile as execFile3 } from "child_process";
-import path16 from "path";
+import path17 from "path";
 import { promisify as promisify3 } from "util";
 var exec = promisify3(execFile3);
 function remoteHostname(remoteUrl) {
@@ -3513,7 +3653,7 @@ function sanitizeRemoteUrl(remoteUrl) {
 }
 async function detectProvider(rootDir, remoteUrl) {
   const configuration = await readJson(
-    path16.join(rootDir, ".cursor", "agent-kit.config.json")
+    path17.join(rootDir, ".cursor", "agent-kit.config.json")
   );
   const configuredProvider = configuration?.git?.provider;
   if (configuredProvider) {
@@ -3570,7 +3710,7 @@ async function detectProvider(rootDir, remoteUrl) {
       evidence: remoteEvidence
     };
   }
-  if (await fileExists(path16.join(rootDir, ".gitlab-ci.yml"))) {
+  if (await fileExists(path17.join(rootDir, ".gitlab-ci.yml"))) {
     return {
       provider: "gitlab",
       providerKind: "gitlab-self-hosted",
@@ -3659,11 +3799,11 @@ async function detectGit(rootDir) {
 }
 
 // src/scanner/detect-ide.ts
-import path17 from "path";
+import path18 from "path";
 async function detectIde(rootDir) {
-  const hasCursor = await fileExists(path17.join(rootDir, ".cursor"));
-  const hasVSCode = await fileExists(path17.join(rootDir, ".vscode"));
-  const hasWindsurf = await fileExists(path17.join(rootDir, ".windsurfrules"));
+  const hasCursor = await fileExists(path18.join(rootDir, ".cursor"));
+  const hasVSCode = await fileExists(path18.join(rootDir, ".vscode"));
+  const hasWindsurf = await fileExists(path18.join(rootDir, ".windsurfrules"));
   if (hasCursor) return { ide: "cursor", plan: "cursor-pro" };
   if (hasVSCode) return { ide: "vscode", plan: "vscode-pro" };
   if (hasWindsurf) return { ide: "windsurf", plan: "windsurf" };
@@ -3671,7 +3811,7 @@ async function detectIde(rootDir) {
 }
 
 // src/scanner/detect-infra.ts
-import path18 from "path";
+import path19 from "path";
 
 // src/types.ts
 var GIT_PLATFORM_META = {
@@ -3727,12 +3867,12 @@ var PM_TOOL_LABELS = {
 
 // src/scanner/detect-infra.ts
 async function detectInfra(rootDir) {
-  const docker = await fileExists(path18.join(rootDir, "Dockerfile")) || await fileExists(path18.join(rootDir, "docker-compose.yml")) || await fileExists(path18.join(rootDir, "docker-compose.yaml"));
-  const kubernetes = await fileExists(path18.join(rootDir, "k8s")) || await fileExists(path18.join(rootDir, "kubernetes"));
+  const docker = await fileExists(path19.join(rootDir, "Dockerfile")) || await fileExists(path19.join(rootDir, "docker-compose.yml")) || await fileExists(path19.join(rootDir, "docker-compose.yaml"));
+  const kubernetes = await fileExists(path19.join(rootDir, "k8s")) || await fileExists(path19.join(rootDir, "kubernetes"));
   let ci = "none";
   const ciFiles = [];
   for (const [platform, filePath] of Object.entries(CI_PLATFORM_FILES)) {
-    if (await fileExists(path18.join(rootDir, filePath))) {
+    if (await fileExists(path19.join(rootDir, filePath))) {
       if (ci === "none") ci = platform;
       ciFiles.push(filePath);
     }
@@ -3757,30 +3897,30 @@ async function detectInfra(rootDir) {
   ];
   const infrastructureFiles = (await Promise.all(
     infrastructureCandidates.map(
-      async (file) => await fileExists(path18.join(rootDir, file)) ? file : void 0
+      async (file) => await fileExists(path19.join(rootDir, file)) ? file : void 0
     )
   )).filter((file) => file !== void 0);
   const deploymentFiles = (await Promise.all(
     deploymentCandidates.map(
-      async (file) => await fileExists(path18.join(rootDir, file)) ? file : void 0
+      async (file) => await fileExists(path19.join(rootDir, file)) ? file : void 0
     )
   )).filter((file) => file !== void 0);
   return { docker, kubernetes, ci, ciFiles, infrastructureFiles, deploymentFiles };
 }
 
 // src/scanner/detect-services.ts
-import { readFile as readFile11 } from "fs/promises";
-import path19 from "path";
+import { readFile as readFile12 } from "fs/promises";
+import path20 from "path";
 async function detectProjectManagement(rootDir) {
   const tools = [];
   const mcpConfigPaths = [
-    path19.join(rootDir, ".cursor", "mcp.json"),
-    path19.join(rootDir, "mcp.json")
+    path20.join(rootDir, ".cursor", "mcp.json"),
+    path20.join(rootDir, "mcp.json")
   ];
   for (const configPath of mcpConfigPaths) {
     if (!await fileExists(configPath)) continue;
     try {
-      const raw = await readFile11(configPath, "utf8");
+      const raw = await readFile12(configPath, "utf8");
       const lower = raw.toLowerCase();
       if (lower.includes("clickup")) tools.push("clickup");
       if (lower.includes("jira") || lower.includes("atlassian")) tools.push("jira");
@@ -3791,20 +3931,20 @@ async function detectProjectManagement(rootDir) {
     } catch {
     }
   }
-  if (await fileExists(path19.join(rootDir, ".github", "ISSUE_TEMPLATE"))) {
+  if (await fileExists(path20.join(rootDir, ".github", "ISSUE_TEMPLATE"))) {
     tools.push("github-issues");
   }
-  if (await fileExists(path19.join(rootDir, ".github", "projects"))) {
+  if (await fileExists(path20.join(rootDir, ".github", "projects"))) {
     tools.push("github-projects");
   }
   return [...new Set(tools)];
 }
 async function detectServices(rootDir) {
-  const hasPrisma = await fileExists(path19.join(rootDir, "prisma/schema.prisma"));
-  const hasSequelize = await fileExists(path19.join(rootDir, "sequelize"));
-  const hasDrizzle = await fileExists(path19.join(rootDir, "drizzle.config.ts"));
-  const hasKnex = await fileExists(path19.join(rootDir, "knexfile.ts"));
-  const hasTypeorm = await fileExists(path19.join(rootDir, "ormconfig.json"));
+  const hasPrisma = await fileExists(path20.join(rootDir, "prisma/schema.prisma"));
+  const hasSequelize = await fileExists(path20.join(rootDir, "sequelize"));
+  const hasDrizzle = await fileExists(path20.join(rootDir, "drizzle.config.ts"));
+  const hasKnex = await fileExists(path20.join(rootDir, "knexfile.ts"));
+  const hasTypeorm = await fileExists(path20.join(rootDir, "ormconfig.json"));
   const database = hasPrisma || hasSequelize || hasDrizzle || hasKnex || hasTypeorm ? "postgresql" : void 0;
   const orm = hasPrisma ? "prisma" : hasDrizzle ? "drizzle" : hasSequelize ? "sequelize" : hasKnex ? "knex" : hasTypeorm ? "typeorm" : void 0;
   const projectManagement = await detectProjectManagement(rootDir);
@@ -3816,7 +3956,7 @@ async function detectServices(rootDir) {
 }
 
 // src/scanner/detect-stack.ts
-import path20 from "path";
+import path21 from "path";
 var PROJECT_MARKERS = [
   "package.json",
   "requirements.txt",
@@ -3845,7 +3985,7 @@ async function detectPackageManager(rootDir, packageJson) {
     };
   }
   for (const [lockfile, packageManager] of LOCKFILES) {
-    if (await fileExists(path20.join(rootDir, lockfile))) {
+    if (await fileExists(path21.join(rootDir, lockfile))) {
       return {
         packageManager,
         evidence: [{ source: "file", value: lockfile }]
@@ -3862,27 +4002,27 @@ function commandsForScripts(scripts, packageManager) {
   return { testCommands, validationCommands };
 }
 async function detectStack(rootDir) {
-  const hasAnyProjectMarker = (await Promise.all(PROJECT_MARKERS.map((item) => fileExists(path20.join(rootDir, item))))).some(Boolean);
-  const hasPackageJson = await fileExists(path20.join(rootDir, "package.json"));
+  const hasAnyProjectMarker = (await Promise.all(PROJECT_MARKERS.map((item) => fileExists(path21.join(rootDir, item))))).some(Boolean);
+  const hasPackageJson = await fileExists(path21.join(rootDir, "package.json"));
   if (hasPackageJson) {
-    const packageJson = await readJson(path20.join(rootDir, "package.json")) ?? {};
+    const packageJson = await readJson(path21.join(rootDir, "package.json")) ?? {};
     const scripts = packageJson.scripts ?? {};
     const packageManager = await detectPackageManager(rootDir, packageJson);
     const commands = commandsForScripts(scripts, packageManager.packageManager);
-    const hasNextConfig = await fileExists(path20.join(rootDir, "next.config.js")) || await fileExists(path20.join(rootDir, "next.config.mjs")) || await fileExists(path20.join(rootDir, "next.config.ts"));
-    const hasNestConfig = await fileExists(path20.join(rootDir, "nest-cli.json"));
+    const hasNextConfig = await fileExists(path21.join(rootDir, "next.config.js")) || await fileExists(path21.join(rootDir, "next.config.mjs")) || await fileExists(path21.join(rootDir, "next.config.ts"));
+    const hasNestConfig = await fileExists(path21.join(rootDir, "nest-cli.json"));
     return {
       language: "node",
       framework: hasNextConfig ? "nextjs" : hasNestConfig ? "nestjs" : "node",
       packageManager: packageManager.packageManager,
       packageManagerEvidence: packageManager.evidence,
       scripts,
-      workspaces: packageJson.workspaces !== void 0 || await fileExists(path20.join(rootDir, "pnpm-workspace.yaml")),
+      workspaces: packageJson.workspaces !== void 0 || await fileExists(path21.join(rootDir, "pnpm-workspace.yaml")),
       ...commands,
       hasProjectFiles: hasAnyProjectMarker
     };
   }
-  if (await fileExists(path20.join(rootDir, "pyproject.toml"))) {
+  if (await fileExists(path21.join(rootDir, "pyproject.toml"))) {
     return {
       language: "python",
       framework: "python",
@@ -3892,7 +4032,7 @@ async function detectStack(rootDir) {
       hasProjectFiles: hasAnyProjectMarker
     };
   }
-  if (await fileExists(path20.join(rootDir, "go.mod"))) {
+  if (await fileExists(path21.join(rootDir, "go.mod"))) {
     return {
       language: "go",
       framework: "go",
@@ -3902,7 +4042,7 @@ async function detectStack(rootDir) {
       hasProjectFiles: hasAnyProjectMarker
     };
   }
-  if (await fileExists(path20.join(rootDir, "Cargo.toml"))) {
+  if (await fileExists(path21.join(rootDir, "Cargo.toml"))) {
     return {
       language: "rust",
       framework: "rust",
@@ -3912,7 +4052,7 @@ async function detectStack(rootDir) {
       hasProjectFiles: hasAnyProjectMarker
     };
   }
-  if (await fileExists(path20.join(rootDir, "composer.json"))) {
+  if (await fileExists(path21.join(rootDir, "composer.json"))) {
     return {
       language: "php",
       framework: "php",
@@ -3945,7 +4085,7 @@ function isGreenfieldByEntries(entries) {
   return meaningful.length === 0;
 }
 async function runScanner(rootDir) {
-  const normalizedRoot = path21.resolve(rootDir);
+  const normalizedRoot = path22.resolve(rootDir);
   const entries = await listDirectory(normalizedRoot);
   const stack = await detectStack(normalizedRoot);
   const purpose = await detectPurpose(normalizedRoot, stack);
@@ -4149,7 +4289,7 @@ async function executeSafeReadinessFixes(rootDir, options) {
   });
   const changes = [];
   for (const relativePath of ESSENTIAL_DIRECTORIES) {
-    const absolutePath = path22.join(beforeScan.rootDir, relativePath);
+    const absolutePath = path23.join(beforeScan.rootDir, relativePath);
     const exists2 = await fileExists(absolutePath);
     if (!exists2 && !dryRun) await ensureDir(absolutePath);
     recordChange(
@@ -4162,8 +4302,8 @@ async function executeSafeReadinessFixes(rootDir, options) {
     );
   }
   const gitignoreRelativePath = ".gitignore";
-  const gitignorePath = path22.join(beforeScan.rootDir, gitignoreRelativePath);
-  const existingGitignore = await fileExists(gitignorePath) ? await readFile12(gitignorePath, "utf8") : "";
+  const gitignorePath = path23.join(beforeScan.rootDir, gitignoreRelativePath);
+  const existingGitignore = await fileExists(gitignorePath) ? await readFile13(gitignorePath, "utf8") : "";
   const mergedGitignore = mergeSecretIgnores(existingGitignore);
   const gitignoreChanged = mergedGitignore !== existingGitignore;
   if (gitignoreChanged && !dryRun) await writeFile5(gitignorePath, mergedGitignore, "utf8");
@@ -4178,7 +4318,7 @@ async function executeSafeReadinessFixes(rootDir, options) {
       gitignoreChanged ? "required secret patterns are missing" : "required patterns are present"
     )
   );
-  const profilePath = path22.join(beforeScan.rootDir, PROFILE_RELATIVE_PATH);
+  const profilePath = path23.join(beforeScan.rootDir, PROFILE_RELATIVE_PATH);
   const existingProfile = await readJson(profilePath) ?? {};
   const desiredProfile = createProfile(beforeScan, before, generatedAt);
   const mergedProfile = mergeMissing(existingProfile, desiredProfile);
@@ -4200,7 +4340,7 @@ async function executeSafeReadinessFixes(rootDir, options) {
     generatorVersion: options.generatorVersion,
     generatedAt
   });
-  const contextConfigPath = path22.join(beforeScan.rootDir, CONTEXT_CONFIG_RELATIVE_PATH);
+  const contextConfigPath = path23.join(beforeScan.rootDir, CONTEXT_CONFIG_RELATIVE_PATH);
   const existingContextConfig = await readJson(contextConfigPath) ?? {};
   const onboarding = reconcileOnboardingState(evidenceReport, existingContextConfig, generatedAt);
   const defaults = preferenceDefaults(onboarding, existingContextConfig.onboarded);
@@ -4229,10 +4369,10 @@ async function executeSafeReadinessFixes(rootDir, options) {
 }
 
 // src/scanner/snapshot.ts
-import path23 from "path";
+import path24 from "path";
 var READINESS_SNAPSHOT_RELATIVE_PATH = ".cursor/context/readiness.json";
 async function writeReadinessSnapshot(rootDir, report) {
-  const snapshotPath = path23.join(rootDir, READINESS_SNAPSHOT_RELATIVE_PATH);
+  const snapshotPath = path24.join(rootDir, READINESS_SNAPSHOT_RELATIVE_PATH);
   await writeJson(snapshotPath, report);
   return snapshotPath;
 }
@@ -4402,15 +4542,16 @@ async function withCliProgress(label, fn, opts) {
 
 // src/commands/doctor.ts
 async function runDoctor(cwd, options = {}) {
-  const rootDir = path24.resolve(cwd);
+  const rootDir = path25.resolve(cwd);
   const hooks = await assessHooksHealth(rootDir);
+  const env = await assessEnvironment();
   if (options.fixSafe) {
     const execution = await executeSafeReadinessFixes(rootDir, {
       generatorVersion: KIT_VERSION,
       generatedAt: options.generatedAt
     });
     await writeReadinessSnapshot(rootDir, execution.after);
-    return { report: execution.after, safeChanges: execution.changes, hooks };
+    return { report: execution.after, safeChanges: execution.changes, hooks, env };
   }
   const scan = await runScanner(rootDir);
   const report = createReadinessReport(scan, {
@@ -4418,7 +4559,7 @@ async function runDoctor(cwd, options = {}) {
     generatedAt: options.generatedAt
   });
   await writeReadinessSnapshot(rootDir, report);
-  return { report, safeChanges: [], hooks };
+  return { report, safeChanges: [], hooks, env };
 }
 function printDoctorSummary(result) {
   const { summary, pendingActions } = result.report;
@@ -4442,6 +4583,20 @@ function printDoctorSummary(result) {
       console.log(`  - ${tip}`);
     }
   }
+  console.log("environment:");
+  console.log(`  - bin on PATH (agent-kit): ${result.env.binOnPath ? "ok" : "MISSING"}`);
+  console.log(
+    `  - npm prefix writable: ${result.env.npmPrefixWritable ? "ok" : "BLOCKED"}${result.env.npmPrefix.prefix ? ` (${result.env.npmPrefix.prefix})` : ""}`
+  );
+  if (!result.env.npmPrefixWritable && result.env.npmPrefix.reason) {
+    console.log(`    - ${result.env.npmPrefix.reason}`);
+  }
+  console.log(
+    `  - node version >= 20: ${result.env.nodeVersionOk ? "ok" : "TOO OLD"} (${result.env.nodeVersion})`
+  );
+  console.log(
+    `  - shell profile: ${result.env.shellProfile ?? "not detected (zsh/bash only)"}${result.env.shell ? ` (shell: ${result.env.shell})` : ""}`
+  );
   if (process.env.ALLOW_MAIN_PUSH === "1") {
     console.log("\u26A0\uFE0F  WARNING: ALLOW_MAIN_PUSH=1 is set in environment");
     console.log("   This disables main-push protection for agent Shell commands.");
@@ -4522,13 +4677,21 @@ var SECRET_PATTERNS2 = [
     id: "github-pat",
     re: /\bghp_[A-Za-z0-9_]{36,}\b/
   },
+  // Hyphenated vendor keys (`sk-ant-api03-…`, `sk-proj-…`) cannot be matched by
+  // `openai-sk`: its body class excludes `-`, so it stops at the first separator.
+  // Listed before `openai-sk`; the two cannot both hit the same span.
   {
+    id: "sk-hyphenated-vendor",
+    re: /\bsk-[A-Za-z0-9]{2,12}-[A-Za-z0-9_-]{16,}\b/
+  },
+  {
+    // Single-segment `sk-` bodies only (no `-` in the class) — see `sk-hyphenated-vendor`.
     id: "openai-sk",
     re: /\bsk-[A-Za-z0-9]{20,}\b/
   }
 ];
 function maskSecretExcerpt(raw) {
-  return raw.replace(/\b(ghp_|sk-|AKIA)([A-Za-z0-9_]{4,})/g, (_m, p1, p2) => {
+  return raw.replace(/\b(ghp_|sk-|AKIA)([A-Za-z0-9_-]{4,})/g, (_m, p1, p2) => {
     return `${p1}${"*".repeat(Math.min(8, p2.length))}`;
   }).replace(
     /(=\s*['"]?)([^\s'"]{4,})/g,
@@ -4752,7 +4915,7 @@ var guardCommand = defineCommand8({
     shell: defineCommand8({
       meta: {
         name: "shell",
-        description: "Evaluate a shell command against the destructive deny-list"
+        description: "Evaluate a shell command against the git-workflow / protected-branch deny-list (git checkout|restore|reset --hard|clean -fd + pushes to main/master/prod). Not a general destructive-command guard: rm -rf, chmod, dd are allowed."
       },
       args: {
         json: {
@@ -4810,8 +4973,8 @@ var guardCommand = defineCommand8({
 
 // src/commands/handoff.ts
 import { spawn as spawn4 } from "child_process";
-import { readFile as readFile13, readdir as readdir5, writeFile as writeFile6 } from "fs/promises";
-import path25 from "path";
+import { readFile as readFile14, readdir as readdir5, writeFile as writeFile6 } from "fs/promises";
+import path26 from "path";
 import { defineCommand as defineCommand9 } from "citty";
 function parsePlanFrontmatter(raw) {
   const match = raw.match(/^---\n([\s\S]*?)\n---/);
@@ -4831,19 +4994,19 @@ async function findActivePlan(plansDir) {
   if (!await fileExists(plansDir)) return null;
   const files = (await readdir5(plansDir)).filter((f) => f.endsWith(".plan.md")).sort().reverse();
   for (const file of files) {
-    const raw = await readFile13(path25.join(plansDir, file), "utf8");
+    const raw = await readFile14(path26.join(plansDir, file), "utf8");
     const fm = parsePlanFrontmatter(raw);
     if (fm?.todos?.some((t) => t.status !== "completed" && t.status !== "cancelled")) {
       return { file, raw };
     }
   }
-  return files[0] ? { file: files[0], raw: await readFile13(path25.join(plansDir, files[0]), "utf8") } : null;
+  return files[0] ? { file: files[0], raw: await readFile14(path26.join(plansDir, files[0]), "utf8") } : null;
 }
 function now() {
   return (/* @__PURE__ */ new Date()).toISOString().replace("T", " ").slice(0, 16);
 }
 async function loadProfile(rootDir) {
-  const configPath = path25.join(rootDir, ".cursor", "agent-kit.config.json");
+  const configPath = path26.join(rootDir, ".cursor", "agent-kit.config.json");
   try {
     return await readJson(configPath);
   } catch {
@@ -4943,13 +5106,13 @@ var handoffCommand = defineCommand9({
   },
   async run({ args }) {
     const profile = await loadProfile(args.cwd);
-    const plansDir = path25.join(args.cwd, ".cursor", "plans");
-    const handoffPath = path25.join(args.cwd, ".cursor", "HANDOFF.md");
+    const plansDir = path26.join(args.cwd, ".cursor", "plans");
+    const handoffPath = path26.join(args.cwd, ".cursor", "HANDOFF.md");
     const plan = await findActivePlan(plansDir);
     if (plan) {
       const fm = parsePlanFrontmatter(plan.raw);
       if (fm) {
-        await ensureDir(path25.join(args.cwd, ".cursor"));
+        await ensureDir(path26.join(args.cwd, ".cursor"));
         const content = buildHandoff(plan.file, fm, profile);
         await writeFile6(handoffPath, content, "utf8");
         logger.success("HANDOFF.md updated: .cursor/HANDOFF.md");
@@ -4969,7 +5132,7 @@ var handoffCommand = defineCommand9({
       }
       logger.warn(`Plan ${plan.file} without valid frontmatter; trying legacy flow.`);
     }
-    const scriptPath = path25.join(args.cwd, "cursor-handoff");
+    const scriptPath = path26.join(args.cwd, "cursor-handoff");
     if (!await fileExists(scriptPath)) {
       printV3Guidance();
       return;
@@ -4994,9 +5157,19 @@ var handoffCommand = defineCommand9({
 });
 
 // src/commands/hook.ts
-import path27 from "path";
+import path28 from "path";
 import { defineCommand as defineCommand10 } from "citty";
 
+// src/hooks/format-session-start.ts
+function resolveSessionStartFormat(value) {
+  return value === "claude" ? "claude" : "cursor";
+}
+function formatSessionStartOutput(additionalContext, format) {
+  if (format === "claude") return additionalContext;
+  return JSON.stringify({ additional_context: additionalContext });
+}
+var SESSION_START_DEGRADED_MESSAGE = "Agent Kit session-start context is unavailable this session (internal error, fail-open mode). Nothing else is affected; retry next session.";
+
 // src/hooks/pre-compact.ts
 function buildPreCompactUserMessage(payload = {}) {
   const pct = payload.context_usage_percent;
@@ -5008,8 +5181,8 @@ function buildPreCompactUserMessage(payload = {}) {
 
 // src/hooks/session-start.ts
 import { spawn as spawn5 } from "child_process";
-import { access as access6, readFile as readFile14 } from "fs/promises";
-import path26 from "path";
+import { access as access7, readFile as readFile15, stat as stat4 } from "fs/promises";
+import path27 from "path";
 
 // src/invariants/handoff-schema.ts
 var MACHINE_LIST_CHECKS = [
@@ -5083,7 +5256,7 @@ var NONE_PLACEHOLDERS = /* @__PURE__ */ new Set(["none", "n/a", "empty", "nil"])
 var CURSOR_AWARENESS_SPAWN_TIMEOUT_MS = CHANGELOG_FETCH_TIMEOUT_MS + 3e3;
 async function readTextLimited(filePath, limit = 60) {
   try {
-    const lines = (await readFile14(filePath, "utf8")).split(/\r?\n/);
+    const lines = (await readFile15(filePath, "utf8")).split(/\r?\n/);
     return lines.slice(0, limit).join("\n").trim();
   } catch {
     return "";
@@ -5091,14 +5264,14 @@ async function readTextLimited(filePath, limit = 60) {
 }
 async function readFull(filePath) {
   try {
-    return await readFile14(filePath, "utf8");
+    return await readFile15(filePath, "utf8");
   } catch {
     return "";
   }
 }
 async function fileExists2(p) {
   try {
-    await access6(p);
+    await access7(p);
     return true;
   } catch {
     return false;
@@ -5165,8 +5338,8 @@ function extractUnprocessedDogfoodLine(line) {
   return raw;
 }
 async function l0Present(root) {
-  const cursor = path26.join(root, ".cursor");
-  return await fileExists2(path26.join(cursor, "agent-kit.json")) || await fileExists2(path26.join(cursor, "commands", "agent-kit-onboard.md")) || await fileExists2(path26.join(cursor, "commands", "start-project.md"));
+  const cursor = path27.join(root, ".cursor");
+  return await fileExists2(path27.join(cursor, "agent-kit.json")) || await fileExists2(path27.join(cursor, "commands", "agent-kit-onboard.md")) || await fileExists2(path27.join(cursor, "commands", "start-project.md"));
 }
 function checkLabelAndRecommendation(check2) {
   const checkId = check2.id;
@@ -5205,10 +5378,10 @@ function unresolvedReadinessChecks(data) {
   return { essential, nonessential };
 }
 async function readinessSection(root) {
-  const snapshotPath = path26.join(root, ".cursor", "context", "readiness.json");
+  const snapshotPath = path27.join(root, ".cursor", "context", "readiness.json");
   let data;
   try {
-    data = JSON.parse(await readFile14(snapshotPath, "utf8"));
+    data = JSON.parse(await readFile15(snapshotPath, "utf8"));
   } catch {
     return null;
   }
@@ -5239,13 +5412,13 @@ Optional readiness item: \`${first.id}\`. ${first.recommendation} This does not
 }
 async function dogfoodInboxSection(root) {
   const candidateReadmes = [
-    path26.join(root, "dogfood", "README.md"),
-    path26.join(root, ".cursor", "dogfood", "README.md")
+    path27.join(root, "dogfood", "README.md"),
+    path27.join(root, ".cursor", "dogfood", "README.md")
   ];
   for (const readme of candidateReadmes) {
     if (!await fileExists2(readme)) continue;
     try {
-      const text = await readFile14(readme, "utf8");
+      const text = await readFile15(readme, "utf8");
       if (parseUnprocessedDogfoodItems(text).length) return DOGFOOD_INBOX_HINT;
     } catch {
     }
@@ -5255,7 +5428,7 @@ async function dogfoodInboxSection(root) {
 async function loadUpdateCheckPrefs(root) {
   try {
     const data = JSON.parse(
-      await readFile14(path26.join(root, ".cursor", "context", "config.json"), "utf8")
+      await readFile15(path27.join(root, ".cursor", "context", "config.json"), "utf8")
     );
     const uc = data.updateCheck;
     if (!uc || typeof uc !== "object" || uc.enabled !== true) {
@@ -5333,7 +5506,7 @@ async function updateCheckSection(root) {
 async function loadCursorUpdateCheckPrefs(root) {
   try {
     const data = JSON.parse(
-      await readFile14(path26.join(root, ".cursor", "context", "config.json"), "utf8")
+      await readFile15(path27.join(root, ".cursor", "context", "config.json"), "utf8")
     );
     const uc = data.cursorUpdateCheck;
     if (!uc || typeof uc !== "object" || uc.enabled !== true) {
@@ -5432,9 +5605,101 @@ async function cursorAwarenessSection(root, deps = {}) {
   if (!shouldEmitCursorAwarenessNudge(result)) return null;
   return CURSOR_AWARENESS_NUDGE;
 }
+var AUDIT_SESSION_NS_PREFIX = "agent-kit-audit-";
+var AUDIT_SESSION_LIST_TIMEOUT_MS = 2e3;
+function runAuditSessionCommand(cmd, args) {
+  return new Promise((resolve2) => {
+    const child = spawn5(cmd, args, {
+      stdio: ["ignore", "pipe", "ignore"],
+      timeout: AUDIT_SESSION_LIST_TIMEOUT_MS,
+      shell: false
+    });
+    let out = "";
+    child.stdout?.on("data", (chunk) => {
+      out += chunk.toString("utf8");
+    });
+    child.on("error", () => resolve2(null));
+    child.on("close", () => resolve2(out));
+  });
+}
+function parseTmuxDetachedAuditSessions(out, nowEpochSeconds) {
+  const sessions = [];
+  for (const line of out.split(/\r?\n/)) {
+    const m = /^(\S+)\s+(\d+)\s+(\d+)$/.exec(line.trim());
+    if (!m) continue;
+    const [, name, attached, created] = m;
+    if (!name || !name.startsWith(AUDIT_SESSION_NS_PREFIX)) continue;
+    if (Number(attached) > 0) continue;
+    const createdEpoch = Number(created);
+    const ageSeconds = Number.isFinite(createdEpoch) && nowEpochSeconds >= createdEpoch ? nowEpochSeconds - createdEpoch : -1;
+    sessions.push({ channel: "tmux", name, ageSeconds });
+  }
+  return sessions;
+}
+function parseScreenDetachedAuditSessions(listing) {
+  const lines = listing.split(/\r?\n/);
+  let sockdir = null;
+  for (const line of lines) {
+    const dirMatch = /^\d+\s+Sockets?\s+in\s+(.+)\.$/.exec(line);
+    if (dirMatch?.[1]) sockdir = dirMatch[1];
+  }
+  const entries = [];
+  for (const line of lines) {
+    const m = /^\s+(\d+)\.(\S+)\s+\((.*)\)/.exec(line);
+    if (!m) continue;
+    const [, pid, name, marker] = m;
+    if (!name || !name.startsWith(AUDIT_SESSION_NS_PREFIX)) continue;
+    if (marker && /[Aa]ttached/.test(marker)) continue;
+    entries.push({ name, socketPath: sockdir ? path27.join(sockdir, `${pid}.${name}`) : null });
+  }
+  return entries;
+}
+function formatSessionAge(seconds) {
+  if (seconds >= 86400) return `${Math.floor(seconds / 86400)}d`;
+  if (seconds >= 3600) return `${Math.floor(seconds / 3600)}h`;
+  if (seconds >= 60) return `${Math.floor(seconds / 60)}m`;
+  return `${seconds}s`;
+}
+async function detachedAuditSessionsSection(deps = {}) {
+  try {
+    const run = deps.runCommand ?? runAuditSessionCommand;
+    const nowMs = (deps.now ?? Date.now)();
+    const [tmuxOut, screenOut] = await Promise.all([
+      run("tmux", [
+        "list-sessions",
+        "-F",
+        "#{session_name} #{session_attached} #{session_created}"
+      ]),
+      run("screen", ["-ls"])
+    ]);
+    const sessions = tmuxOut ? parseTmuxDetachedAuditSessions(tmuxOut, Math.floor(nowMs / 1e3)) : [];
+    if (screenOut) {
+      for (const entry of parseScreenDetachedAuditSessions(screenOut)) {
+        let ageSeconds = -1;
+        if (entry.socketPath) {
+          try {
+            const { mtimeMs } = await stat4(entry.socketPath);
+            if (nowMs >= mtimeMs) ageSeconds = Math.floor((nowMs - mtimeMs) / 1e3);
+          } catch {
+          }
+        }
+        sessions.push({ channel: "screen", name: entry.name, ageSeconds });
+      }
+    }
+    if (sessions.length === 0) return null;
+    const knownAges = sessions.map((s) => s.ageSeconds).filter((a) => a >= 0);
+    const oldest = knownAges.length ? `oldest ~${formatSessionAge(Math.max(...knownAges))}` : "oldest age unknown";
+    const noun = sessions.length === 1 ? "session" : "sessions";
+    return `## Detached audit sessions (host)
+
+${sessions.length} detached \`agent-kit-audit-*\` PTY ${noun} on this host (${oldest}). These are external plan-review terminals: inspect with \`tmux attach -t <name>\` / \`screen -r <name>\`, or let the audit launcher's session GC dispose of them on the next spawn.`;
+  } catch {
+    return null;
+  }
+}
 async function buildSessionStartAdditionalContext(rootDir, _payload = {}) {
-  const root = path26.resolve(rootDir);
-  const handoffPath = path26.join(root, ".cursor", "HANDOFF.md");
+  const root = path27.resolve(rootDir);
+  const handoffPath = path27.join(root, ".cursor", "HANDOFF.md");
   const handoffFull = await readFull(handoffPath);
   const handoff = await readTextLimited(handoffPath);
   const parts = [HARD_RULES];
@@ -5448,6 +5713,8 @@ async function buildSessionStartAdditionalContext(rootDir, _payload = {}) {
   if (updateNudge) parts.push(updateNudge);
   const cursorNudge = await cursorAwarenessSection(root);
   if (cursorNudge) parts.push(cursorNudge);
+  const auditSessions = await detachedAuditSessionsSection().catch(() => null);
+  if (auditSessions) parts.push(auditSessions);
   const formatWarnings = validateHandoffText(handoffFull);
   if (formatWarnings.length) {
     const bullet = formatWarnings.map((w) => `- ${w.message}`).join("\n");
@@ -5479,29 +5746,44 @@ function resolveSessionRoot(payload, cwd = process.cwd()) {
 }
 
 // src/commands/hook.ts
+async function runSessionStartHook(cwd, formatArg, deps = {}) {
+  const format = resolveSessionStartFormat(formatArg);
+  try {
+    const readStdin = deps.readStdin ?? readStdinJson;
+    const buildContext = deps.buildContext ?? buildSessionStartAdditionalContext;
+    const payload = await readStdin();
+    const root = resolveSessionRoot(payload, path28.resolve(cwd));
+    const out = await buildContext(root, payload);
+    return formatSessionStartOutput(out.additional_context, format);
+  } catch {
+    return formatSessionStartOutput(SESSION_START_DEGRADED_MESSAGE, format);
+  }
+}
 var hookCommand = defineCommand10({
   meta: {
     name: "hook",
-    description: "Cursor hook adapters (session-start, pre-compact). CLI is SoT."
+    description: "Cursor + Claude Code hook adapters (session-start, pre-compact). CLI is SoT."
   },
   subCommands: {
     "session-start": defineCommand10({
       meta: {
         name: "session-start",
-        description: "Emit sessionStart additional_context JSON (stdin: Cursor payload)"
+        description: "Emit sessionStart context (stdin: host payload). --format cursor (default, JSON additional_context) | claude (plain stdout)"
       },
       args: {
         cwd: {
           type: "string",
           default: process.cwd()
+        },
+        format: {
+          type: "string",
+          default: "cursor",
+          description: "cursor (default) | claude"
         }
       },
       async run({ args }) {
-        const payload = await readStdinJson();
         const cwd = typeof args.cwd === "string" ? args.cwd : process.cwd();
-        const root = resolveSessionRoot(payload, path27.resolve(cwd));
-        const out = await buildSessionStartAdditionalContext(root, payload);
-        console.log(JSON.stringify(out));
+        console.log(await runSessionStartHook(cwd, args.format));
       }
     }),
     "pre-compact": defineCommand10({
@@ -5522,45 +5804,96 @@ import { intro, outro } from "@clack/prompts";
 import { defineCommand as defineCommand12 } from "citty";
 
 // src/utils/terminal.ts
-import { homedir as homedir2 } from "os";
-import path28 from "path";
+import { readdir as readdir6 } from "fs/promises";
+import { homedir as homedir3 } from "os";
+import path29 from "path";
 import { confirm, isCancel } from "@clack/prompts";
 function isNonInteractive() {
   if (process.env.CI === "true" || process.env.CI === "1") return true;
   if (process.env.AGENT_KIT_YES === "1") return true;
   return !process.stdin.isTTY;
 }
+var NESTED_REPO_AMBIGUITY_THRESHOLD = 2;
+var NESTED_REPO_SCAN_LIMIT = 200;
+async function findNestedRepoChildren(resolved) {
+  let entries;
+  try {
+    entries = await readdir6(resolved, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  const nested = [];
+  let scanned = 0;
+  for (const entry of entries) {
+    if (nested.length >= NESTED_REPO_AMBIGUITY_THRESHOLD) break;
+    if (scanned >= NESTED_REPO_SCAN_LIMIT) break;
+    if (!entry.isDirectory()) continue;
+    if (entry.name.startsWith(".") || entry.name === "node_modules") continue;
+    scanned += 1;
+    if (await fileExists(path29.join(resolved, entry.name, ".git"))) {
+      nested.push(entry.name);
+    }
+  }
+  return nested;
+}
 async function validateProjectRoot(resolved) {
-  const home = path28.resolve(homedir2());
+  const home = path29.resolve(homedir3());
   if (resolved === "/" || resolved === home) {
-    return { ok: false, reason: `Refused to use ${resolved} as a project root.` };
+    return {
+      ok: false,
+      reason: `Refused to use ${resolved} as a project root.`,
+      recovery: "Change into a project directory and re-run. Agent Kit installs per project."
+    };
   }
-  const hasGit = await fileExists(path28.join(resolved, ".git"));
-  const hasManifest = await fileExists(path28.join(resolved, ".cursor", "agent-kit.json"));
+  const hasGit = await fileExists(path29.join(resolved, ".git"));
+  const hasManifest = await fileExists(path29.join(resolved, ".cursor", "agent-kit.json"));
   if (!hasGit && !hasManifest) {
     return {
       ok: false,
-      reason: `Refused ${resolved}: no .git and no .cursor/agent-kit.json. Run from a project directory or use --force-root.`
+      reason: `Refused ${resolved}: no .git and no .cursor/agent-kit.json.`,
+      recovery: [
+        "Starting from an empty folder? Pick one of these:",
+        "  1. git init          - then re-run. Recommended: readiness and the",
+        "                         staging -> prod flow both want Git.",
+        "  2. --force-root      - install without Git. /agent-kit-onboard will",
+        "                         still offer to initialize it later.",
+        "  3. Answer yes to the 'Proceed anyway?' prompt in an interactive terminal.",
+        "Or re-run from the project directory you actually meant."
+      ].join("\n")
     };
   }
+  if (hasGit && !hasManifest) {
+    const nested = await findNestedRepoChildren(resolved);
+    if (nested.length >= NESTED_REPO_AMBIGUITY_THRESHOLD) {
+      return {
+        ok: false,
+        reason: `Refused ${resolved}: it has .git but also contains child repositories (${nested.join(", ")}). This looks like a parent-of-repos folder, not a project root.`,
+        recovery: [
+          "L0 belongs in one project, not in the folder that holds several.",
+          "  1. cd into the project you meant, then re-run.",
+          "  2. --force-root - only if this parent folder really is the project root."
+        ].join("\n")
+      };
+    }
+  }
   return { ok: true };
 }
 async function confirmProjectRoot(cwd, opts) {
-  const resolved = path28.resolve(cwd);
+  const resolved = path29.resolve(cwd);
   if (opts.forceRoot) {
     return resolved;
   }
   const validation = await validateProjectRoot(resolved);
   if (!validation.ok) {
     if (opts.nonInteractive) {
-      throw new RootRefusedError(resolved, validation.reason);
+      throw new RootRefusedError(resolved, validation.reason, validation.recovery);
     }
     const ok2 = await confirm({
       message: `${validation.reason} Proceed anyway?`,
       initialValue: false
     });
     if (isCancel(ok2) || !ok2) {
-      throw new RootRefusedError(resolved, validation.reason);
+      throw new RootRefusedError(resolved, validation.reason, validation.recovery);
     }
     return resolved;
   }
@@ -5577,16 +5910,38 @@ async function confirmProjectRoot(cwd, opts) {
   return resolved;
 }
 var RootRefusedError = class extends Error {
-  constructor(root, reason) {
+  constructor(root, reason, recovery) {
     super(reason ?? `Refused to write into ${root}. Re-run from the correct project directory.`);
     this.root = root;
+    this.recovery = recovery;
     this.name = "RootRefusedError";
   }
   root;
+  recovery;
 };
+var NPM_GLOBAL_PREFIX_PATH_RE = /\/lib\/node_modules|Program Files\\nodejs\\node_modules/;
+var NPM_GLOBAL_NODE_MODULES_RE = /node_modules/;
+function isNpmGlobalPrefixError(msg, code) {
+  const isPermissionError = code === "EPERM" || code === "EACCES" || /EPERM|EACCES/.test(msg);
+  if (!isPermissionError) return false;
+  return NPM_GLOBAL_PREFIX_PATH_RE.test(msg) || NPM_GLOBAL_NODE_MODULES_RE.test(msg);
+}
 function classifyInstallError(err) {
   const msg = err instanceof Error ? err.message : String(err);
   const code = err?.code;
+  if (isNpmGlobalPrefixError(msg, code)) {
+    return {
+      kind: "npm-global-eacces",
+      message: `Permission error (root-owned npm prefix): ${msg}`,
+      recovery: [
+        "npm's global install prefix (e.g. /usr/local/lib/node_modules) is owned by root, so global installs fail.",
+        "Recovery options:",
+        "  1. Run: npx @dadado/agent-kit-cli setup-global (relocates npm's prefix to a folder you own, fixes PATH, reinstalls)",
+        '  2. Manual fix: mkdir -p ~/.npm-global && npm config set prefix "~/.npm-global" && export PATH="~/.npm-global/bin:$PATH" (add to your shell profile) && npm i -g @dadado/agent-kit-cli',
+        "  3. Use Port B fallback: drag install.md into the Cursor chat"
+      ].join("\n")
+    };
+  }
   if (code === "EPERM" || code === "EACCES" || /EPERM|EACCES/.test(msg)) {
     return {
       kind: "eperm",
@@ -5634,16 +5989,108 @@ function classifyInstallError(err) {
 }
 
 // src/commands/install.ts
-import path33 from "path";
+import path36 from "path";
 import { defineCommand as defineCommand11 } from "citty";
+import { bold, cyan as cyan3, green as green2, options as koloristOptions2 } from "kolorist";
 
 // src/generator/personalization.ts
-import { readFile as readFile15, writeFile as writeFile9 } from "fs/promises";
-import path31 from "path";
+import { readFile as readFile18, writeFile as writeFile11 } from "fs/promises";
+import path34 from "path";
+
+// src/generator/claude-command-adapters.ts
+import { readFile as readFile16, readdir as readdir7, writeFile as writeFile7 } from "fs/promises";
+import path30 from "path";
+var CURSOR_COMMANDS_DIR_REL = ".cursor/commands";
+var CLAUDE_COMMANDS_DIR_REL = ".claude/commands";
+var RESERVED_ADAPTER_NAMES = /* @__PURE__ */ new Set(["agent-kit"]);
+function parseCommandFrontmatter(name, raw) {
+  const match = /^---\r?\n([\s\S]*?)\r?\n---/.exec(raw);
+  if (!match) return null;
+  const body = match[1] ?? "";
+  const descMatch = /^description:\s*(.+)$/m.exec(body);
+  if (!descMatch) return null;
+  const description = (descMatch[1] ?? "").trim();
+  if (!description) return null;
+  return { name, description };
+}
+function renderClaudeCommandAdapter(command) {
+  return `---
+description: ${command.description}
+---
+
+Read \`.cursor/commands/${command.name}.md\` now and follow that contract exactly \u2014 it is the source of truth for /${command.name}; this file is only a thin adapter for Claude Code.
+
+Adapter rules (Claude Code CLI):
+- Cursor "Ask questions" is unavailable here: use AskUserQuestion when possible, else present the same labels as one numbered list per message and WAIT for the answer.
+- Skip or cancel means stop.
+- Never \`/git-prod\` without an explicit operator yes.
+- Do not clone Cursor hooks or invent behavior beyond the SoT file.
+`;
+}
+async function discoverInstalledCommands(rootDir) {
+  const dir = path30.join(rootDir, CURSOR_COMMANDS_DIR_REL);
+  let entries;
+  try {
+    entries = (await readdir7(dir)).filter((f) => f.endsWith(".md"));
+  } catch {
+    return [];
+  }
+  const commands = [];
+  for (const file of entries.sort()) {
+    const name = file.slice(0, -3);
+    if (RESERVED_ADAPTER_NAMES.has(name)) continue;
+    try {
+      const raw = await readFile16(path30.join(dir, file), "utf8");
+      const parsed = parseCommandFrontmatter(name, raw);
+      if (parsed) commands.push(parsed);
+    } catch {
+    }
+  }
+  return commands;
+}
+async function generateClaudeCommandAdapters(rootDir) {
+  const commands = await discoverInstalledCommands(rootDir);
+  if (commands.length === 0) return [];
+  const ledger = await loadManagedHashLedger(rootDir);
+  const results = [];
+  let ledgerDirty = false;
+  for (const command of commands) {
+    const relPath = path30.posix.join(CLAUDE_COMMANDS_DIR_REL, `${command.name}.md`);
+    const rendered = renderClaudeCommandAdapter(command);
+    const abs = path30.join(rootDir, relPath);
+    if (!await fileExists(abs)) {
+      await ensureDir(path30.dirname(abs));
+      await writeFile7(abs, rendered, "utf8");
+      ledger.hashes[relPath] = contentHash(rendered);
+      ledgerDirty = true;
+      results.push({ relativePath: relPath, status: "applied" });
+      continue;
+    }
+    const localContent = await readFile16(abs, "utf8");
+    if (localContent === rendered) {
+      if (ledger.hashes[relPath] !== contentHash(rendered)) {
+        ledger.hashes[relPath] = contentHash(rendered);
+        ledgerDirty = true;
+      }
+      results.push({ relativePath: relPath, status: "unchanged" });
+      continue;
+    }
+    if (shouldPreserveCustomizedOverlay(localContent, ledger.hashes[relPath])) {
+      results.push({ relativePath: relPath, status: "preserved-customized" });
+      continue;
+    }
+    await writeFile7(abs, rendered, "utf8");
+    ledger.hashes[relPath] = contentHash(rendered);
+    ledgerDirty = true;
+    results.push({ relativePath: relPath, status: "refreshed" });
+  }
+  if (ledgerDirty) await saveManagedHashLedger(rootDir, ledger);
+  return results;
+}
 
 // src/generator/claude-kit-load.ts
-import { writeFile as writeFile7 } from "fs/promises";
-import path29 from "path";
+import { writeFile as writeFile8 } from "fs/promises";
+import path31 from "path";
 var CLAUDE_MD_REL = "CLAUDE.md";
 var AGENT_KIT_COMMAND_REL = ".claude/commands/agent-kit.md";
 function renderClaudeMd() {
@@ -5669,7 +6116,7 @@ Cursor Ask questions is not available in this CLI. When a command requires a cho
 - Not Action A7 (Windsurf / VS Code generator parity)
 - Not Claude external plan-review audits (\`/plan-external-review\`)
 - Not \`--backend claude\` plan-loop ticks
-- Not a copy of Cursor \`sessionStart\` / other IDE hooks
+- Not a copy of Cursor hooks beyond the opt-in SessionStart context adapter (\`agent-kit hook session-start --format claude\`); no \`.claude/rules/\` mirrors, no \`.claude/agents/\` generated from the registry
 `;
 }
 function renderAgentKitCommand() {
@@ -5693,12 +6140,12 @@ Non-goals: not audits / \`/plan-external-review\`, not \`--backend claude\` tick
 `;
 }
 async function writeUnlessExists(rootDir, relativePath, content) {
-  const target = path29.join(rootDir, relativePath);
+  const target = path31.join(rootDir, relativePath);
   if (await fileExists(target)) {
     return { relativePath, status: "skipped-customized" };
   }
-  await ensureDir(path29.dirname(target));
-  await writeFile7(target, content, "utf8");
+  await ensureDir(path31.dirname(target));
+  await writeFile8(target, content, "utf8");
   return { relativePath, status: "applied" };
 }
 async function generateClaudeKitLoadArtifacts(rootDir) {
@@ -5708,9 +6155,109 @@ async function generateClaudeKitLoadArtifacts(rootDir) {
   ]);
 }
 
+// src/generator/claude-session-start-hook.ts
+import { readFile as readFile17, writeFile as writeFile9 } from "fs/promises";
+import path32 from "path";
+var CLAUDE_SETTINGS_REL = ".claude/settings.json";
+var RESOLVE_AGENT_KIT_REL = ".cursor/hooks/agent/resolve-agent-kit.sh";
+var SESSION_START_HOOK_MARKER = "hook session-start --format claude";
+var SESSION_START_DEGRADED_TEXT = "Agent Kit hooks are running in degraded fail-open mode: the agent-kit CLI could not be resolved (checked AGENT_KIT_HOOK_BIN, PATH, node_modules/.bin/agent-kit). Slash command adapters still work; session-context injection is inactive. Fix: install the CLI (npm i -D @dadado/agent-kit-cli) or set AGENT_KIT_HOOK_BIN.";
+function buildSessionStartHookCommand() {
+  return `. "\${CLAUDE_PROJECT_DIR}/${RESOLVE_AGENT_KIT_REL}" 2>/dev/null && resolve_agent_kit && exec $AGENT_KIT_RESOLVED hook session-start --format claude; printf '%s' ${shellSingleQuote(SESSION_START_DEGRADED_TEXT)}`;
+}
+function shellSingleQuote(text) {
+  return `'${text.replace(/'/g, "'\\''")}'`;
+}
+function buildSessionStartHookEntry() {
+  return {
+    type: "command",
+    command: buildSessionStartHookCommand(),
+    timeout: 15,
+    statusMessage: "Loading Agent Kit session context"
+  };
+}
+function isPlainObject2(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function groupHasMarker(group) {
+  if (!isPlainObject2(group) || !Array.isArray(group.hooks)) return false;
+  return group.hooks.some(
+    (h) => isPlainObject2(h) && typeof h.command === "string" && h.command.includes(SESSION_START_HOOK_MARKER)
+  );
+}
+function mergeSessionStartHookIntoSettings(existingRaw) {
+  const entry = buildSessionStartHookEntry();
+  const newGroup = { hooks: [entry] };
+  let root = {};
+  if (existingRaw !== null && existingRaw.trim() !== "") {
+    try {
+      const parsed = JSON.parse(existingRaw);
+      if (!isPlainObject2(parsed)) throw new Error("root is not an object");
+      root = parsed;
+    } catch {
+      return {
+        content: null,
+        status: "unavailable",
+        instructions: instructionsBlock(entry)
+      };
+    }
+  }
+  const hooks = isPlainObject2(root.hooks) ? { ...root.hooks } : {};
+  const sessionStart = Array.isArray(hooks.SessionStart) ? [...hooks.SessionStart] : [];
+  const existingIndex = sessionStart.findIndex((g) => groupHasMarker(g));
+  let status;
+  if (existingIndex === -1) {
+    sessionStart.push(newGroup);
+    status = "applied";
+  } else {
+    const current = sessionStart[existingIndex];
+    if (JSON.stringify(current) === JSON.stringify(newGroup)) {
+      status = "unchanged";
+    } else {
+      sessionStart[existingIndex] = newGroup;
+      status = "refreshed";
+    }
+  }
+  hooks.SessionStart = sessionStart;
+  root.hooks = hooks;
+  return { content: `${JSON.stringify(root, null, 2)}
+`, status };
+}
+function instructionsBlock(entry) {
+  return [
+    `Could not parse the existing ${CLAUDE_SETTINGS_REL} as JSON, so Agent Kit did not touch it.`,
+    "Add this hook by hand under hooks.SessionStart (create the arrays if they do not exist):",
+    "",
+    JSON.stringify(entry, null, 2)
+  ].join("\n");
+}
+async function writeClaudeSessionStartHook(rootDir) {
+  const abs = path32.join(rootDir, CLAUDE_SETTINGS_REL);
+  let existing = null;
+  try {
+    existing = await readFile17(abs, "utf8");
+  } catch {
+    existing = null;
+  }
+  const merged = mergeSessionStartHookIntoSettings(existing);
+  if (merged.status === "unavailable" || merged.content === null) {
+    return {
+      relativePath: CLAUDE_SETTINGS_REL,
+      status: "unavailable",
+      instructions: merged.instructions
+    };
+  }
+  if (merged.status === "unchanged") {
+    return { relativePath: CLAUDE_SETTINGS_REL, status: "unchanged" };
+  }
+  await ensureDir(path32.dirname(abs));
+  await writeFile9(abs, merged.content, "utf8");
+  return { relativePath: CLAUDE_SETTINGS_REL, status: merged.status };
+}
+
 // src/generator/vscode.ts
-import { writeFile as writeFile8 } from "fs/promises";
-import path30 from "path";
+import { writeFile as writeFile10 } from "fs/promises";
+import path33 from "path";
 
 // src/generator/platform.ts
 function gitProviderLabel(profile) {
@@ -5734,14 +6281,14 @@ function prTerminology(profile) {
 // src/generator/vscode.ts
 async function generateVSCodeArtifacts(profile) {
   const results = [];
-  const vscodeDir = path30.join(profile.rootDir, ".vscode");
-  const githubDir = path30.join(profile.rootDir, ".github");
+  const vscodeDir = path33.join(profile.rootDir, ".vscode");
+  const githubDir = path33.join(profile.rootDir, ".github");
   await Promise.all([ensureDir(vscodeDir), ensureDir(githubDir)]);
-  const settingsPath = path30.join(vscodeDir, "settings.json");
+  const settingsPath = path33.join(vscodeDir, "settings.json");
   if (await fileExists(settingsPath)) {
     results.push({ relativePath: ".vscode/settings.json", status: "skipped-customized" });
   } else {
-    await writeFile8(
+    await writeFile10(
       settingsPath,
       `${JSON.stringify(
         {
@@ -5761,11 +6308,11 @@ async function generateVSCodeArtifacts(profile) {
   }
   const provider = gitProviderLabel(profile);
   const prTerm = prTerminology(profile);
-  const copilotPath = path30.join(githubDir, "copilot-instructions.md");
+  const copilotPath = path33.join(githubDir, "copilot-instructions.md");
   if (await fileExists(copilotPath)) {
     results.push({ relativePath: ".github/copilot-instructions.md", status: "skipped-customized" });
   } else {
-    await writeFile8(
+    await writeFile10(
       copilotPath,
       `# Copilot Instructions
 
@@ -5779,14 +6326,14 @@ async function generateVSCodeArtifacts(profile) {
     results.push({ relativePath: ".github/copilot-instructions.md", status: "applied" });
   }
   if (profile.ide.plan === "vscode-pro") {
-    const securityPath = path30.join(vscodeDir, "security-review.agent.md");
+    const securityPath = path33.join(vscodeDir, "security-review.agent.md");
     if (await fileExists(securityPath)) {
       results.push({
         relativePath: ".vscode/security-review.agent.md",
         status: "skipped-customized"
       });
     } else {
-      await writeFile8(
+      await writeFile10(
         securityPath,
         "# Security Review Agent\n\nSpecialized mode for security review.\n",
         "utf8"
@@ -5991,7 +6538,7 @@ function renderProjectContext(profile, skillItems = []) {
 `;
 }
 async function createOwnedFile(rootDir, relativePath, content, evidence) {
-  const target = path31.join(rootDir, relativePath);
+  const target = path34.join(rootDir, relativePath);
   if (await fileExists(target)) {
     return {
       kind: "file",
@@ -6001,8 +6548,8 @@ async function createOwnedFile(rootDir, relativePath, content, evidence) {
       evidence
     };
   }
-  await ensureDir(path31.dirname(target));
-  await writeFile9(target, content, "utf8");
+  await ensureDir(path34.dirname(target));
+  await writeFile11(target, content, "utf8");
   return {
     kind: "file",
     id: relativePath,
@@ -6018,7 +6565,7 @@ async function packTargets(registryRoot, packId) {
 async function existingTargets(projectRoot, targets) {
   const checks = await Promise.all(
     targets.map(
-      async (target) => await fileExists(path31.join(projectRoot, target)) ? target : null
+      async (target) => await fileExists(path34.join(projectRoot, target)) ? target : null
     )
   );
   return checks.filter((target) => target !== null);
@@ -6040,14 +6587,14 @@ async function applyPersonalization(input) {
         componentResults.push({ ...item, status: "unavailable" });
         continue;
       }
-      const target = path31.posix.join(
+      const target = path34.posix.join(
         ".cursor",
         "skills",
         skill.path.includes("/core/") ? "core" : "community",
         skill.id,
         "SKILL.md"
       );
-      if (await fileExists(path31.join(input.rootDir, target))) {
+      if (await fileExists(path34.join(input.rootDir, target))) {
         componentResults.push({ ...item, status: "skipped-customized", path: target });
         protectedPaths.add(target);
         continue;
@@ -6106,6 +6653,41 @@ async function applyPersonalization(input) {
       evidence: profileEvidence
     };
   });
+  const claudeCommandItems = [];
+  let claudeSessionStartInstructions;
+  if (input.claudeAdapters) {
+    const adapterResults = await generateClaudeCommandAdapters(input.rootDir);
+    for (const artifact of adapterResults) {
+      protectedPaths.add(artifact.relativePath);
+      claudeCommandItems.push({
+        kind: "file",
+        id: artifact.relativePath,
+        path: artifact.relativePath,
+        // Overlay statuses (applied/unchanged/refreshed/preserved-customized)
+        // fold onto the shared PersonalizationStatus union: anything written
+        // or already current reads as "applied"; a hand-edited adapter left
+        // alone reads as "skipped-customized" (same meaning as elsewhere in
+        // this file — never silently clobbered).
+        status: artifact.status === "preserved-customized" ? "skipped-customized" : "applied",
+        evidence: profileEvidence
+      });
+    }
+    const hookResult = await writeClaudeSessionStartHook(input.rootDir);
+    protectedPaths.add(hookResult.relativePath);
+    claudeCommandItems.push({
+      kind: "file",
+      id: hookResult.relativePath,
+      path: hookResult.relativePath,
+      // "unavailable" (existing .claude/settings.json unparseable) is a real
+      // PersonalizationStatus value already; every other hook status folds
+      // onto "applied" the same way the command-adapter statuses do above.
+      status: hookResult.status === "unavailable" ? "unavailable" : "applied",
+      evidence: profileEvidence
+    });
+    if (hookResult.status === "unavailable" && hookResult.instructions) {
+      claudeSessionStartInstructions = hookResult.instructions;
+    }
+  }
   const ideDetection = await detectIde(input.rootDir);
   if (ideDetection.ide === "vscode" || ideDetection.ide === "other") {
     const git = {
@@ -6153,10 +6735,11 @@ async function applyPersonalization(input) {
     contractVersion: PERSONALIZATION_CONTRACT_VERSION,
     generatorVersion: input.generatorVersion,
     repositoryFingerprint: input.report.repositoryFingerprint,
-    items: [...fileResults, ...claudeItems, ...componentResults],
-    protectedPaths: [...protectedPaths].sort()
+    items: [...fileResults, ...claudeItems, ...claudeCommandItems, ...componentResults],
+    protectedPaths: [...protectedPaths].sort(),
+    ...claudeSessionStartInstructions ? { claudeSessionStartInstructions } : {}
   };
-  await writeJson(path31.join(input.rootDir, RESULT_PATH), result);
+  await writeJson(path34.join(input.rootDir, RESULT_PATH), result);
   return {
     result,
     manifest: {
@@ -6174,26 +6757,26 @@ async function applyPersonalization(input) {
   };
 }
 async function readRepositoryProfile(rootDir) {
-  const target = path31.join(rootDir, ".cursor/agent-kit.config.json");
+  const target = path34.join(rootDir, ".cursor/agent-kit.config.json");
   if (!await fileExists(target)) return null;
-  return JSON.parse(await readFile15(target, "utf8"));
+  return JSON.parse(await readFile18(target, "utf8"));
 }
 
 // src/lifecycle/onboard-migration.ts
 import { createHash as createHash4 } from "crypto";
-import { readFile as readFile16, unlink } from "fs/promises";
-import path32 from "path";
+import { readFile as readFile19, unlink } from "fs/promises";
+import path35 from "path";
 var LEGACY_ONBOARD_PATH = ".cursor/commands/onboard.md";
 var NAMESPACED_ONBOARD_PATH = ".cursor/commands/agent-kit-onboard.md";
 var MANAGED_LEGACY_HASHES = /* @__PURE__ */ new Set([
   "b274a68941813f19b185893cb7c5561dff027f53270890029992f208e24992fe"
 ]);
 async function migrateLegacyOnboardCommand(projectRoot, managedHashes = MANAGED_LEGACY_HASHES) {
-  const legacyPath = path32.join(projectRoot, LEGACY_ONBOARD_PATH);
+  const legacyPath = path35.join(projectRoot, LEGACY_ONBOARD_PATH);
   if (!await fileExists(legacyPath)) return "absent";
-  const namespacedPath = path32.join(projectRoot, NAMESPACED_ONBOARD_PATH);
+  const namespacedPath = path35.join(projectRoot, NAMESPACED_ONBOARD_PATH);
   if (!await fileExists(namespacedPath)) return "preserved-customized";
-  const content = await readFile16(legacyPath);
+  const content = await readFile19(legacyPath);
   const hash = createHash4("sha256").update(content).digest("hex");
   if (!managedHashes.has(hash)) return "preserved-customized";
   await unlink(legacyPath);
@@ -6252,6 +6835,9 @@ function parsePackList(raw) {
     )
   ];
 }
+function nextStepAfterInstall(pendingActions) {
+  return pendingActions > 0 ? "Next: run /agent-kit-onboard in Cursor to resolve the first pending action." : "Next: run /start-project in Cursor when you have a deliverable.";
+}
 function printReadinessNarrative(result) {
   const { summary, pendingActions } = result.readiness;
   const fixed = result.safeChanges.filter((change) => change.status === "applied").length;
@@ -6261,12 +6847,61 @@ function printReadinessNarrative(result) {
   );
   console.log(`  safe fixes applied: ${fixed}`);
   console.log(`  pending actions: ${pendingActions.length}`);
-  console.log(
-    pendingActions.length > 0 ? "Next: run /agent-kit-onboard in Cursor to resolve the first pending action" : "Next: run /start-project in Cursor when you have a deliverable"
-  );
+  console.log(nextStepAfterInstall(pendingActions.length));
+}
+function paint(fn, text) {
+  const prevEnabled = koloristOptions2.enabled;
+  const prevSupportLevel = koloristOptions2.supportLevel;
+  koloristOptions2.enabled = true;
+  koloristOptions2.supportLevel = 3;
+  try {
+    return fn(text);
+  } finally {
+    koloristOptions2.enabled = prevEnabled;
+    koloristOptions2.supportLevel = prevSupportLevel;
+  }
+}
+function printInstallEpilogue(env, options = {}) {
+  const print = options.print ?? ((line) => console.log(line));
+  const color = options.color ?? shouldUseWelcomeColor();
+  if (env.binOnPath) {
+    const line = "`agent-kit` is on PATH \u2014 run it directly, e.g. `agent-kit doctor`.";
+    print(color ? paint(green2, line) : line);
+    return;
+  }
+  const divider = "\u2500".repeat(60);
+  const body = [
+    "You ran this through npx, so a bare `agent-kit` isn't on PATH yet.",
+    'If you try `agent-kit <subcommand>` next, you will see "command not',
+    'found". Pick one:',
+    "",
+    "  1. Keep using npx \u2014 works right now, no action needed",
+    "     npx @dadado/agent-kit-cli <subcommand>",
+    "",
+    "  2. Put a bare `agent-kit` on PATH",
+    "     npx @dadado/agent-kit-cli setup-global",
+    "     (fixes a root-owned npm prefix if that's the blocker, or just installs)",
+    "",
+    "  3. Manual steps",
+    "     See docs/getting-started.md (Troubleshooting npm failures), or:",
+    "       mkdir -p ~/.npm-global",
+    '       npm config set prefix "~/.npm-global"',
+    '       export PATH="~/.npm-global/bin:$PATH"',
+    "       npm i -g @dadado/agent-kit-cli"
+  ];
+  print(color ? paint(cyan3, divider) : divider);
+  const heading = "Heads up: a bare `agent-kit` command won't work yet";
+  print(color ? paint(bold, paint(cyan3, heading)) : heading);
+  for (const line of body) print(line);
+  print(color ? paint(cyan3, divider) : divider);
+}
+async function printPostInstallSummary(result) {
+  printReadinessNarrative(result);
+  const env = await assessEnvironment();
+  printInstallEpilogue(env);
 }
 async function performInstall(options) {
-  const projectRoot = path33.resolve(options.cwd);
+  const projectRoot = path36.resolve(options.cwd);
   const packs = parsePackList(options.pack);
   const existing = await loadAgentKitManifest(projectRoot);
   const registry = await resolveRegistryFromCli({
@@ -6294,6 +6929,7 @@ async function performInstall(options) {
       generatorVersion: KIT_VERSION
     });
     let readiness = readinessExecution.after;
+    let claudeSessionStartInstructions;
     const profile = await readRepositoryProfile(projectRoot);
     if (profile) {
       const registryIndex = await loadRegistry(registry.root);
@@ -6304,9 +6940,11 @@ async function performInstall(options) {
         report: readinessExecution.after,
         registry: registryIndex,
         manifest: draft,
-        generatorVersion: KIT_VERSION
+        generatorVersion: KIT_VERSION,
+        claudeAdapters: options.claudeAdapters
       });
       await saveManifest(projectRoot, personalization.manifest);
+      claudeSessionStartInstructions = personalization.result.claudeSessionStartInstructions;
       readiness = createReadinessReport(await runScanner(projectRoot), {
         generatorVersion: KIT_VERSION
       });
@@ -6318,7 +6956,8 @@ async function performInstall(options) {
       manifestPath,
       stats,
       readiness,
-      safeChanges: readinessExecution.changes
+      safeChanges: readinessExecution.changes,
+      ...claudeSessionStartInstructions ? { claudeSessionStartInstructions } : {}
     };
   } finally {
     await registry.unlock?.();
@@ -6350,6 +6989,11 @@ var installCommand = defineCommand11({
       description: "Bypass the ambiguous-root guard (use with caution)",
       default: false
     },
+    claude: {
+      type: "boolean",
+      description: "Opt-in: generate .claude/commands/*.md thin pointer adapters for the installed .cursor/commands set, and merge a SessionStart context hook into .claude/settings.json (default install behavior is unchanged without this flag)",
+      default: false
+    },
     cwd: {
       type: "string",
       default: process.cwd()
@@ -6371,6 +7015,9 @@ var installCommand = defineCommand11({
     } catch (err) {
       if (err instanceof RootRefusedError) {
         logger.error(err.message);
+        if (err.recovery) console.error(`
+${err.recovery}
+`);
         process.exitCode = 1;
         return;
       }
@@ -6393,13 +7040,20 @@ var installCommand = defineCommand11({
           registry: args.registry,
           url: args.url,
           ref: args.ref,
-          refresh: args.refresh
+          refresh: args.refresh,
+          claudeAdapters: args.claude
         })
       );
       logApplyStats(result.stats);
       logger.success(`Manifest written: ${result.manifestPath}`);
       logger.success("Readiness snapshot written: .cursor/context/readiness.json");
-      printReadinessNarrative(result);
+      await printPostInstallSummary(result);
+      if (result.claudeSessionStartInstructions) {
+        logger.warn("Could not merge the Claude Code SessionStart hook automatically:");
+        console.log(`
+${result.claudeSessionStartInstructions}
+`);
+      }
     } catch (err) {
       const hint = classifyInstallError(err);
       logger.error(hint.message);
@@ -6426,25 +7080,57 @@ var initCommand = defineCommand12({
       type: "string",
       description: "Project root directory",
       default: process.cwd()
+    },
+    yes: {
+      type: "boolean",
+      alias: "y",
+      description: "Skip interactive prompts; use defaults (IDE-agnostic non-interactive mode)",
+      default: false
+    },
+    "force-root": {
+      type: "boolean",
+      description: "Bypass the ambiguous-root guard (use with caution)",
+      default: false
     }
   },
   async run({ args }) {
-    const nonInteractive = isNonInteractive();
+    const nonInteractive = args.yes || isNonInteractive();
     if (!nonInteractive) {
       intro(`agent-kit v${KIT_VERSION}`);
     } else {
       logger.info(`agent-kit v${KIT_VERSION} (non-interactive mode)`);
     }
     logger.info("init now uses the canonical install and readiness workflow.");
+    let projectRoot;
     try {
-      const result = await withCliProgress("init", () => runInitCompatibility(args.cwd));
+      projectRoot = await confirmProjectRoot(args.cwd, {
+        nonInteractive,
+        command: "install",
+        forceRoot: args["force-root"]
+      });
+    } catch (err) {
+      if (err instanceof RootRefusedError) {
+        logger.error(err.message);
+        if (err.recovery) console.error(`
+${err.recovery}
+`);
+        process.exitCode = 1;
+        return;
+      }
+      throw err;
+    }
+    try {
+      const result = await withCliProgress("init", () => runInitCompatibility(projectRoot));
       const pending = result.readiness.pendingActions.length;
       logger.success(`L0 and readiness prepared in ${result.projectRoot}`);
-      const nextStep = pending > 0 ? "Next: run /agent-kit-onboard in Cursor to resolve the first pending action." : "Next: run /start-project in Cursor when you have a deliverable.";
+      const nextStep = nextStepAfterInstall(pending);
+      const env = await assessEnvironment();
       if (!nonInteractive) {
+        printInstallEpilogue(env);
         outro(nextStep);
       } else {
         logger.info(nextStep);
+        printInstallEpilogue(env);
       }
     } catch (err) {
       const hint = classifyInstallError(err);
@@ -6458,13 +7144,13 @@ ${hint.recovery}
 });
 
 // src/commands/monitors.ts
-import path35 from "path";
+import path38 from "path";
 import { defineCommand as defineCommand13 } from "citty";
 
 // src/invariants/monitors-untriaged.ts
 import { execFile as execFile5 } from "child_process";
-import { readFile as readFile17, readdir as readdir6, stat as stat3 } from "fs/promises";
-import path34 from "path";
+import { readFile as readFile20, readdir as readdir8, stat as stat5 } from "fs/promises";
+import path37 from "path";
 import { promisify as promisify5 } from "util";
 
 // src/invariants/triage-heading.ts
@@ -6488,7 +7174,7 @@ function hasOpenGaps(content) {
 }
 async function listMonitorFiles(memoryDir) {
   try {
-    const names = await readdir6(memoryDir);
+    const names = await readdir8(memoryDir);
     return names.filter((n) => n.startsWith("plan-monitor-") && n.endsWith(".md")).sort();
   } catch {
     return [];
@@ -6505,7 +7191,7 @@ async function gitFreshMonitorNames(rootDir) {
     for (const line of stdout.split("\n")) {
       if (!line.trim()) continue;
       const file = line.slice(3).trim().replace(/^.* -> /, "");
-      const base = path34.basename(file);
+      const base = path37.basename(file);
       if (base.startsWith("plan-monitor-") && base.endsWith(".md")) {
         names.add(base);
       }
@@ -6528,15 +7214,15 @@ function monitorSlugFromName(fileName) {
   return fileName.replace(/^plan-monitor-/, "").replace(/\.md$/, "").toLowerCase();
 }
 async function selectUntriagedMonitors(rootDir) {
-  const root = path34.resolve(rootDir);
-  const memoryDir = path34.join(root, ".cursor", "memory");
+  const root = path37.resolve(rootDir);
+  const memoryDir = path37.join(root, ".cursor", "memory");
   const allNames = await listMonitorFiles(memoryDir);
   const selectionOrder = ["git-fresh", "handoff-aligned", "untriaged-scan"];
   const byName = /* @__PURE__ */ new Map();
   for (const name of allNames) {
-    const abs = path34.join(memoryDir, name);
+    const abs = path37.join(memoryDir, name);
     try {
-      const [content, st] = await Promise.all([readFile17(abs, "utf8"), stat3(abs)]);
+      const [content, st] = await Promise.all([readFile20(abs, "utf8"), stat5(abs)]);
       byName.set(name, { content, mtimeMs: st.mtimeMs });
     } catch {
     }
@@ -6549,7 +7235,7 @@ async function selectUntriagedMonitors(rootDir) {
   const gitFreshSet = [...gitFresh].filter(untriaged).sort();
   let handoff = "";
   try {
-    handoff = await readFile17(path34.join(root, ".cursor", "HANDOFF.md"), "utf8");
+    handoff = await readFile20(path37.join(root, ".cursor", "HANDOFF.md"), "utf8");
   } catch {
     handoff = "";
   }
@@ -6569,8 +7255,8 @@ async function selectUntriagedMonitors(rootDir) {
     const row = byName.get(name);
     if (!row) continue;
     entries.push({
-      path: path34.join(memoryDir, name),
-      relativePath: path34.relative(root, path34.join(memoryDir, name)).split(path34.sep).join("/"),
+      path: path37.join(memoryDir, name),
+      relativePath: path37.relative(root, path37.join(memoryDir, name)).split(path37.sep).join("/"),
       mtimeMs: row.mtimeMs,
       hasTriageHeading: false,
       hasOpenGaps: hasOpenGaps(row.content),
@@ -6616,7 +7302,7 @@ var monitorsCommand = defineCommand13({
       process.exitCode = 2;
       return;
     }
-    const result = await selectUntriagedMonitors(path35.resolve(args.cwd));
+    const result = await selectUntriagedMonitors(path38.resolve(args.cwd));
     if (args.json) {
       console.log(JSON.stringify(result, null, 2));
       return;
@@ -6632,7 +7318,7 @@ var monitorsCommand = defineCommand13({
 });
 
 // src/commands/run-plan.ts
-import path40 from "path";
+import path43 from "path";
 import { defineCommand as defineCommand14 } from "citty";
 
 // src/plan-loop/backends.ts
@@ -6717,14 +7403,14 @@ function listBackendIds() {
 }
 
 // src/plan-loop/run-loop.ts
-import { mkdir as mkdir6, readFile as readFile20, rm as rm2, unlink as unlink2 } from "fs/promises";
-import path39 from "path";
+import { mkdir as mkdir6, readFile as readFile23, rm as rm2, unlink as unlink2 } from "fs/promises";
+import path42 from "path";
 
 // src/plan-loop/external-review.ts
 import { spawn as spawn7 } from "child_process";
-import path36 from "path";
-var CANONICAL_REL = path36.join(".cursor", "scripts", "plan-external-review.sh");
-var FALLBACK_REL = path36.join("scripts", "plan-external-review.sh");
+import path39 from "path";
+var CANONICAL_REL = path39.join(".cursor", "scripts", "plan-external-review.sh");
+var FALLBACK_REL = path39.join("scripts", "plan-external-review.sh");
 function isPlanExhaustedReason(reason) {
   const r = reason.trim().toLowerCase();
   if (!r) return false;
@@ -6746,8 +7432,8 @@ async function armExternalPlanReview(root, options = {}) {
   const existsFn = options.existsFn ?? fileExists;
   const log = options.log ?? ((line) => console.log(line));
   const force = options.force === true;
-  const canonicalPath = path36.join(root, CANONICAL_REL);
-  const fallbackPath = path36.join(root, FALLBACK_REL);
+  const canonicalPath = path39.join(root, CANONICAL_REL);
+  const fallbackPath = path39.join(root, FALLBACK_REL);
   let scriptPath = null;
   let scriptRel = CANONICAL_REL;
   if (await existsFn(canonicalPath)) {
@@ -6800,12 +7486,12 @@ async function armExternalPlanReview(root, options = {}) {
 }
 
 // src/plan-loop/persona-banners.ts
-import path37 from "path";
+import path40 from "path";
 import {
   blue,
-  cyan as cyan3,
+  cyan as cyan4,
   gray as gray2,
-  green as green2,
+  green as green3,
   lightGray,
   lightGreen,
   magenta,
@@ -6818,8 +7504,8 @@ var DEFAULT_CLI_PERSONA_ID = "ghost-runner";
 var COLORS = {
   white,
   gray: gray2,
-  green: green2,
-  cyan: cyan3,
+  green: green3,
+  cyan: cyan4,
   magenta,
   yellow: yellow2,
   red: red2,
@@ -6836,7 +7522,7 @@ function resolveColor(name, fallback) {
 async function resolveCliPersonaId(root) {
   try {
     const cfg = await readJson(
-      path37.join(root, ".cursor", "context", "config.json")
+      path40.join(root, ".cursor", "context", "config.json")
     );
     const modes = cfg?.agentPersona?.modes ?? cfg?.workspaceSkin?.modes;
     const id = modes?.[CLI_RUN_PLAN_MODE];
@@ -6847,7 +7533,7 @@ async function resolveCliPersonaId(root) {
 }
 async function loadPersonaPack(root, personaId) {
   try {
-    const personaPath = path37.join(root, "registry", "personas", "core", personaId, "persona.json");
+    const personaPath = path40.join(root, "registry", "personas", "core", personaId, "persona.json");
     const pack = await readJson(personaPath);
     if (!pack || typeof pack.id !== "string") return null;
     return pack;
@@ -6865,7 +7551,7 @@ function createPersonaBannerPrinter(persona) {
   if (!banners.tickStart && !banners.tickEnd && !banners.phaseComplete) return null;
   const primary = resolveColor(persona.ansiPalette?.primary, white);
   const secondary = resolveColor(persona.ansiPalette?.secondary, gray2);
-  const accent = resolveColor(persona.ansiPalette?.accent, green2);
+  const accent = resolveColor(persona.ansiPalette?.accent, green3);
   return {
     tickStart(detail) {
       if (banners.tickStart) {
@@ -6896,8 +7582,8 @@ function createPersonaBannerPrinter(persona) {
 }
 
 // src/plan-loop/plan-state.ts
-import { readFile as readFile18, readdir as readdir7 } from "fs/promises";
-import path38 from "path";
+import { readFile as readFile21, readdir as readdir9 } from "fs/promises";
+import path41 from "path";
 function countPendingTodos(raw) {
   const lines = raw.split(/\r?\n/);
   let inFront = 0;
@@ -6924,15 +7610,15 @@ function countPendingTodos(raw) {
 }
 async function findActivePlanFile(plansDir) {
   if (!await fileExists(plansDir)) return null;
-  const files = (await readdir7(plansDir)).filter((f) => f.endsWith(".plan.md")).sort();
-  return files[0] ? path38.join(plansDir, files[0]) : null;
+  const files = (await readdir9(plansDir)).filter((f) => f.endsWith(".plan.md")).sort();
+  return files[0] ? path41.join(plansDir, files[0]) : null;
 }
 async function readPlan(planPath) {
-  return readFile18(planPath, "utf8");
+  return readFile21(planPath, "utf8");
 }
 
 // src/plan-loop/sentinel.ts
-import { readFile as readFile19 } from "fs/promises";
+import { readFile as readFile22 } from "fs/promises";
 var SENTINEL_RE = /LOOP_TICK_RESULT:\s*(continue|stop(?:\s*[—\-].*)?)/i;
 function takeFromText(text) {
   if (!text) return null;
@@ -6979,7 +7665,7 @@ function parseSentinelFromLog(content) {
 }
 async function parseSentinelFromLogFile(logPath) {
   try {
-    const content = await readFile19(logPath, "utf8");
+    const content = await readFile22(logPath, "utf8");
     return parseSentinelFromLog(content);
   } catch {
     return { kind: "missing" };
@@ -7002,9 +7688,9 @@ function sleep(ms) {
   return new Promise((r) => setTimeout(r, ms));
 }
 async function runPlanLoop(opts) {
-  const plansDir = path39.join(opts.root, ".cursor", "plans");
-  const stopFile = path39.join(opts.root, ".cursor", "loop.stop");
-  const logDir = path39.join(opts.root, ".cursor", "loop-logs");
+  const plansDir = path42.join(opts.root, ".cursor", "plans");
+  const stopFile = path42.join(opts.root, ".cursor", "loop.stop");
+  const logDir = path42.join(opts.root, ".cursor", "loop-logs");
   const planPath = await findActivePlanFile(plansDir);
   if (!planPath) {
     logger.error("No active plan in .cursor/plans/");
@@ -7025,7 +7711,7 @@ async function runPlanLoop(opts) {
   try {
     const persona = await loadCliRunPlanPersona(opts.root);
     const banners = createPersonaBannerPrinter(persona);
-    console.log(`Active plan: ${path39.basename(planPath)}`);
+    console.log(`Active plan: ${path42.basename(planPath)}`);
     console.log(`Pending to-dos: ${await pending()} | max ticks: ${opts.maxTicks}`);
     console.log(`Backend: ${opts.backend.id}`);
     if (persona) {
@@ -7068,8 +7754,8 @@ async function runPlanLoop(opts) {
         planExhausted = true;
         break;
       }
-      const logPath = path39.join(logDir, `tick-${stamp()}.log`);
-      const relLog = path39.relative(opts.root, logPath);
+      const logPath = path42.join(logDir, `tick-${stamp()}.log`);
+      const relLog = path42.relative(opts.root, logPath);
       console.log("");
       const tickLine = `=== tick ${tick}/${opts.maxTicks} - pending: ${before} - log: ${relLog} ===`;
       if (banners) banners.tickStart(tickLine);
@@ -7091,7 +7777,7 @@ async function runPlanLoop(opts) {
         return 1;
       }
       try {
-        const logText = await readFile20(logPath, "utf8");
+        const logText = await readFile23(logPath, "utf8");
         if (logText.includes("Too many MCP tools")) {
           const msg = "Too many MCP tools for the headless model - disable servers (cursor-agent mcp disable <id>) and run again.";
           if (banners) banners.stop(msg);
@@ -7148,7 +7834,7 @@ async function runPlanLoop(opts) {
     const finishDetail = `after ${tick} tick(s); pending: ${pendingNow}`;
     if (banners) banners.phaseComplete(finishDetail);
     console.log(
-      `Loop finished after ${tick} tick(s). Pending now: ${pendingNow}. Logs in ${path39.relative(opts.root, logDir)}/`
+      `Loop finished after ${tick} tick(s). Pending now: ${pendingNow}. Logs in ${path42.relative(opts.root, logDir)}/`
     );
     if (planExhausted || shouldArmExternalPlanReview({ pending: pendingNow, stopReason })) {
       await armExternalPlanReview(opts.root);
@@ -7219,7 +7905,7 @@ var runPlanCommand = defineCommand14({
       return;
     }
     const code = await runPlanLoop({
-      root: path40.resolve(args.cwd),
+      root: path43.resolve(args.cwd),
       maxTicks,
       sleepSeconds,
       model: args.model ? String(args.model) : void 0,
@@ -7252,9 +7938,286 @@ var scanCommand = defineCommand15({
   }
 });
 
-// src/commands/status.ts
-import path41 from "path";
+// src/commands/setup-global.ts
+import { spawn as spawn8 } from "child_process";
+import { appendFile, mkdir as mkdir7, readFile as readFile24, writeFile as writeFile12 } from "fs/promises";
+import { homedir as homedir4 } from "os";
+import path44 from "path";
+import { confirm as confirm2, isCancel as isCancel2 } from "@clack/prompts";
 import { defineCommand as defineCommand16 } from "citty";
+import { cyan as cyan5, green as green4, yellow as yellow3 } from "kolorist";
+var NPM_GLOBAL_DIR_NAME = ".npm-global";
+var SETUP_GLOBAL_MARKER = "# agent-kit setup-global";
+var DEFAULT_PACKAGE_SPEC = "@dadado/agent-kit-cli";
+function planSetupGlobalSteps(env, options = {}) {
+  const homeDir = options.homeDir ?? homedir4();
+  const packageSpec = options.packageSpec ?? DEFAULT_PACKAGE_SPEC;
+  const npmGlobalDir = path44.join(homeDir, NPM_GLOBAL_DIR_NAME);
+  const npmGlobalBin = path44.join(npmGlobalDir, "bin");
+  const npmrcPath = path44.join(homeDir, ".npmrc");
+  const npmrcPrefixValue = `~/${NPM_GLOBAL_DIR_NAME}`;
+  const pathExportLine = `export PATH="${npmGlobalBin}:$PATH"`;
+  const shellProfile = env.shellProfile;
+  const shellSupported = shellProfile != null;
+  const steps = [
+    {
+      id: "set-prefix",
+      title: "Set npm's global install prefix to a folder you own",
+      detail: [
+        `mkdir -p ${npmGlobalDir}`,
+        `npm config set prefix "${npmrcPrefixValue}"  (writes "prefix = ${npmrcPrefixValue}" to ${npmrcPath})`
+      ]
+    },
+    {
+      id: "append-path",
+      title: shellSupported ? `Put ${npmGlobalBin} on PATH via ${shellProfile}` : "Put npm's global bin on PATH (manual \u2014 shell not auto-detected)",
+      detail: shellSupported ? [`Append to ${shellProfile}:`, `  ${SETUP_GLOBAL_MARKER}`, `  ${pathExportLine}`] : [
+        `Shell could not be auto-detected as zsh or bash (detected: ${env.shell ?? "unknown"}).`,
+        "You'll need to add this line to your shell's startup file yourself:",
+        `  ${pathExportLine}`
+      ]
+    },
+    {
+      id: "npm-install",
+      title: `Reinstall ${packageSpec} globally, now into the new prefix`,
+      detail: [`npm i -g ${packageSpec}`]
+    },
+    {
+      id: "verify",
+      title: "Verify `agent-kit` resolves on PATH",
+      detail: [
+        "Re-check whether a bare `agent-kit` resolves on PATH.",
+        "Needs a new shell session (or `source` the profile) to take effect \u2014 this process's own PATH can't reflect it."
+      ]
+    }
+  ];
+  return {
+    packageSpec,
+    homeDir,
+    npmGlobalDir,
+    npmGlobalBin,
+    npmrcPath,
+    npmrcPrefixValue,
+    pathExportLine,
+    markerComment: SETUP_GLOBAL_MARKER,
+    shellProfile,
+    shellSupported,
+    alreadyWritable: env.npmPrefixWritable,
+    currentPrefix: env.npmPrefix.prefix,
+    steps
+  };
+}
+function upsertNpmrcPrefix(content, prefixValue) {
+  const line = `prefix = ${prefixValue}`;
+  const prefixLineRe = /^\s*prefix\s*=.*$/m;
+  if (prefixLineRe.test(content)) {
+    return content.replace(prefixLineRe, line);
+  }
+  const withTrailingNewline = content.length > 0 && !content.endsWith("\n") ? `${content}
+` : content;
+  return `${withTrailingNewline}${line}
+`;
+}
+var defaultFsImpl = {
+  mkdir: async (dir) => {
+    await mkdir7(dir, { recursive: true });
+  },
+  readFile: (filePath) => readFile24(filePath, "utf8"),
+  writeFile: (filePath, content) => writeFile12(filePath, content, "utf8"),
+  appendFile: (filePath, content) => appendFile(filePath, content, "utf8")
+};
+async function safeReadFile(fs, filePath) {
+  try {
+    return await fs.readFile(filePath);
+  } catch {
+    return "";
+  }
+}
+var defaultNpmInstallImpl = (packageSpec) => new Promise((resolve2) => {
+  const child = spawn8("npm", ["i", "-g", packageSpec], { stdio: "inherit" });
+  child.on("error", (error) => resolve2({ ok: false, error }));
+  child.on("close", (code) => {
+    if (code === 0) resolve2({ ok: true });
+    else resolve2({ ok: false, error: new Error(`npm exited with code ${code ?? "unknown"}`) });
+  });
+});
+var defaultConfirmImpl = async (message) => {
+  const answer = await confirm2({ message, initialValue: true });
+  if (isCancel2(answer)) return false;
+  return Boolean(answer);
+};
+function printHeader(env, print) {
+  print(cyan5("agent-kit setup-global"));
+  print(
+    `  npm prefix: ${env.npmPrefix.prefix ?? "unknown"} (${env.npmPrefixWritable ? "writable" : "NOT writable"})`
+  );
+  if (!env.npmPrefixWritable && env.npmPrefix.reason) {
+    print(`    ${env.npmPrefix.reason}`);
+  }
+  print(
+    `  shell: ${env.shell ?? "unknown"}${env.shellProfile ? ` (profile: ${env.shellProfile})` : " (profile not auto-detected: zsh/bash only)"}`
+  );
+}
+function printPlanSteps(plan, print) {
+  for (const [index, step] of plan.steps.entries()) {
+    print(`${index + 1}. ${step.title}`);
+    for (const line of step.detail) print(`   ${line}`);
+  }
+}
+function printManualInstructions(plan, print) {
+  print("No changes made. Same fix, as commands you can run yourself:");
+  print(`  mkdir -p ${plan.npmGlobalDir}`);
+  print(`  npm config set prefix "${plan.npmrcPrefixValue}"`);
+  if (plan.shellSupported) {
+    print(`  echo '${plan.markerComment}' >> ${plan.shellProfile}`);
+    print(`  echo '${plan.pathExportLine}' >> ${plan.shellProfile}`);
+    print(`  source ${plan.shellProfile}`);
+  } else {
+    print(`  # add this line to your shell's startup file:`);
+    print(`  ${plan.pathExportLine}`);
+  }
+  print(`  npm i -g ${plan.packageSpec}`);
+  print("  agent-kit --version   # verify, in a new shell session");
+}
+async function runSetupGlobal(options = {}) {
+  const print = options.print ?? ((line) => console.log(line));
+  const assessEnvironmentImpl = options.assessEnvironmentImpl ?? assessEnvironment;
+  const homeDir = options.homeDir ?? homedir4();
+  const env = await assessEnvironmentImpl(options);
+  const plan = planSetupGlobalSteps(env, { homeDir, packageSpec: options.packageSpec });
+  if (plan.alreadyWritable) {
+    printHeader(env, print);
+    print(green4("npm's global prefix is already writable \u2014 nothing to fix."));
+    return { exitCode: 0, mutated: false, outcome: "already-ok", env, plan };
+  }
+  if (options.dryRun) {
+    printHeader(env, print);
+    print("Dry run \u2014 no changes will be made. Steps that would run:");
+    printPlanSteps(plan, print);
+    return { exitCode: 0, mutated: false, outcome: "dry-run", env, plan };
+  }
+  const nonInteractive = options.nonInteractive ?? isNonInteractive();
+  if (nonInteractive) {
+    printHeader(env, print);
+    printManualInstructions(plan, print);
+    return { exitCode: 0, mutated: false, outcome: "manual-instructions", env, plan };
+  }
+  printHeader(env, print);
+  print("You just hit the classic 'command not found' / EACCES fresh-install blocker.");
+  print("The following steps need your confirmation, one at a time:");
+  printPlanSteps(plan, print);
+  const fs = options.fsImpl ?? defaultFsImpl;
+  const confirmStep = options.confirmImpl ?? defaultConfirmImpl;
+  const npmInstall = options.npmInstallImpl ?? defaultNpmInstallImpl;
+  let mutated = false;
+  const setPrefixStep = plan.steps[0];
+  print(`
+${setPrefixStep.title}`);
+  for (const line of setPrefixStep.detail) print(`   ${line}`);
+  const proceedPrefix = await confirmStep(`Set npm's global prefix to ${plan.npmGlobalDir}?`);
+  if (!proceedPrefix) {
+    print(yellow3("Cancelled \u2014 no changes made."));
+    return { exitCode: 1, mutated, outcome: "cancelled", env, plan };
+  }
+  await fs.mkdir(plan.npmGlobalDir);
+  const npmrcContent = await safeReadFile(fs, plan.npmrcPath);
+  await fs.writeFile(plan.npmrcPath, upsertNpmrcPrefix(npmrcContent, plan.npmrcPrefixValue));
+  mutated = true;
+  print(green4(`  done: prefix set (${plan.npmrcPath}).`));
+  const appendPathStep = plan.steps[1];
+  print(`
+${appendPathStep.title}`);
+  for (const line of appendPathStep.detail) print(`   ${line}`);
+  if (!plan.shellSupported) {
+    print(yellow3("  shell not auto-detected as zsh/bash \u2014 add the line above yourself."));
+  } else {
+    const profilePath = plan.shellProfile;
+    const profileContent = await safeReadFile(fs, profilePath);
+    if (profileContent.includes(plan.markerComment)) {
+      print(`  already present in ${profilePath} (marker found) \u2014 skipping.`);
+    } else {
+      const proceedPath = await confirmStep(`Append the PATH export to ${profilePath}?`);
+      if (!proceedPath) {
+        print(yellow3("Cancelled \u2014 prefix was set, PATH export was not appended."));
+        return { exitCode: 1, mutated, outcome: "cancelled", env, plan };
+      }
+      await fs.appendFile(profilePath, `
+${plan.markerComment}
+${plan.pathExportLine}
+`);
+      mutated = true;
+      print(green4(`  done: PATH export appended to ${profilePath}.`));
+    }
+  }
+  const installStep = plan.steps[2];
+  print(`
+${installStep.title}`);
+  for (const line of installStep.detail) print(`   ${line}`);
+  const proceedInstall = await confirmStep(`Run: npm i -g ${plan.packageSpec}?`);
+  if (!proceedInstall) {
+    print(yellow3("Cancelled \u2014 prefix/PATH changes above are still in place."));
+    return { exitCode: 1, mutated, outcome: "cancelled", env, plan };
+  }
+  const installResult = await npmInstall(plan.packageSpec);
+  if (!installResult.ok) {
+    const hint = classifyInstallError(installResult.error);
+    print(`  npm install failed: ${hint.message}`);
+    print(hint.recovery);
+    return { exitCode: 1, mutated, outcome: "error", env, plan };
+  }
+  mutated = true;
+  print(green4(`  done: ${plan.packageSpec} installed globally.`));
+  const verifyStep = plan.steps[3];
+  print(`
+${verifyStep.title}`);
+  for (const line of verifyStep.detail) print(`   ${line}`);
+  const proceedVerify = await confirmStep("Verify now (re-check PATH in this process)?");
+  if (proceedVerify) {
+    const verifyEnv = await assessEnvironmentImpl(options);
+    if (verifyEnv.binOnPath) {
+      print(green4("  verify: `agent-kit` resolves on PATH."));
+    } else {
+      print("  verify: `agent-kit` isn't resolvable in THIS process's PATH yet \u2014 that's expected.");
+      print(
+        `  Open a new terminal (or run: source ${plan.shellProfile ?? "<your shell profile>"}) and re-check with: agent-kit --version`
+      );
+    }
+  } else {
+    print("  skipped verification. Open a new terminal and run: agent-kit --version");
+  }
+  return { exitCode: 0, mutated, outcome: "completed", env, plan };
+}
+var setupGlobalCommand = defineCommand16({
+  meta: {
+    name: "setup-global",
+    description: "Self-heal a root-owned npm prefix: relocate to ~/.npm-global, fix PATH, reinstall globally."
+  },
+  args: {
+    "dry-run": {
+      type: "boolean",
+      description: "Print the resolved plan; mutate nothing.",
+      default: false
+    },
+    yes: {
+      type: "boolean",
+      alias: "y",
+      description: "Treat as non-interactive: print the manual steps instead of prompting (never mutates).",
+      default: false
+    }
+  },
+  async run({ args }) {
+    const nonInteractive = args.yes || isNonInteractive();
+    const result = await runSetupGlobal({
+      dryRun: Boolean(args["dry-run"]),
+      nonInteractive
+    });
+    process.exitCode = result.exitCode;
+  }
+});
+
+// src/commands/status.ts
+import path45 from "path";
+import { defineCommand as defineCommand17 } from "citty";
 function profileStatus(profile) {
   if (!profile) return { origin: "none", evidence: [], profile: null };
   if ("detection" in profile && profile.detection && typeof profile.detection === "object") {
@@ -7267,7 +8230,7 @@ function profileStatus(profile) {
   }
   return { origin: "legacy-wizard", evidence: [], profile };
 }
-var statusCommand = defineCommand16({
+var statusCommand = defineCommand17({
   meta: {
     name: "status",
     description: "Show installed kit version, manifest, and optional profile."
@@ -7284,11 +8247,11 @@ var statusCommand = defineCommand16({
     }
   },
   async run({ args }) {
-    const rootDir = path41.resolve(args.cwd);
+    const rootDir = path45.resolve(args.cwd);
     const [manifest, rawProfile, scan] = await Promise.all([
       loadAgentKitManifest(rootDir),
       readJson(
-        path41.join(rootDir, ".cursor", "agent-kit.config.json")
+        path45.join(rootDir, ".cursor", "agent-kit.config.json")
       ),
       runScanner(rootDir)
     ]);
@@ -7343,11 +8306,11 @@ var statusCommand = defineCommand16({
 });
 
 // src/commands/update.ts
-import { defineCommand as defineCommand17 } from "citty";
+import { defineCommand as defineCommand18 } from "citty";
 
 // src/lifecycle/check-updates.ts
 import { execFile as execFile6 } from "child_process";
-import path42 from "path";
+import path46 from "path";
 import { promisify as promisify6 } from "util";
 var execFileAsync5 = promisify6(execFile6);
 var SEMVER_CORE = /^v?(\d+)\.(\d+)\.(\d+)(?:[-+].*)?$/i;
@@ -7438,11 +8401,11 @@ function intervalElapsed2(lastCheckedAt, intervalDays) {
   return Date.now() - last >= ms;
 }
 async function loadContextConfig2(cwd) {
-  const configPath = path42.join(cwd, ".cursor", "context", "config.json");
+  const configPath = path46.join(cwd, ".cursor", "context", "config.json");
   return readJson(configPath);
 }
 async function stampLastCheckedAt(cwd) {
-  const configPath = path42.join(cwd, ".cursor", "context", "config.json");
+  const configPath = path46.join(cwd, ".cursor", "context", "config.json");
   const existing = await loadContextConfig2(cwd) ?? {};
   const prev = existing.updateCheck && typeof existing.updateCheck === "object" ? { ...existing.updateCheck } : {};
   existing.updateCheck = {
@@ -7454,7 +8417,7 @@ async function stampLastCheckedAt(cwd) {
 }
 async function readLocalKitVersion(registryRoot) {
   for (const rel of ["packages/cli/package.json", "package.json"]) {
-    const data = await readJson(path42.join(registryRoot, rel));
+    const data = await readJson(path46.join(registryRoot, rel));
     if (data && typeof data.version === "string" && data.version.length > 0) {
       return data.version;
     }
@@ -7475,7 +8438,7 @@ async function checkAgainstLocalRegistry(cwd, manifest, options) {
       status: "error",
       installedVersion: manifest.version,
       latestVersion: null,
-      registryUrl: path42.resolve(registryPath),
+      registryUrl: path46.resolve(registryPath),
       registryRef: "local",
       applyRecommended: false,
       message: `Failed to resolve --registry: ${msg}`
@@ -7697,7 +8660,7 @@ async function checkForUpdates(cwd, options = {}) {
 }
 
 // src/commands/update.ts
-var updateCommand = defineCommand17({
+var updateCommand = defineCommand18({
   meta: {
     name: "update",
     description: "Re-apply L0/packs/skills from the registry (never overwrites L3). --check = notify-only."
@@ -7776,6 +8739,9 @@ var updateCommand = defineCommand17({
     } catch (err) {
       if (err instanceof RootRefusedError) {
         logger.error(err.message);
+        if (err.recovery) console.error(`
+${err.recovery}
+`);
         process.exitCode = 1;
         return;
       }
@@ -7828,9 +8794,9 @@ var updateCommand = defineCommand17({
 });
 
 // src/commands/validate.ts
-import { readFile as readFile21 } from "fs/promises";
-import path43 from "path";
-import { defineCommand as defineCommand18 } from "citty";
+import { readFile as readFile25 } from "fs/promises";
+import path47 from "path";
+import { defineCommand as defineCommand19 } from "citty";
 
 // src/invariants/plan-schema.ts
 var CITE5 = "agent-kit validate plan (.cursor/context/templates/plan.md)";
@@ -7876,9 +8842,9 @@ function validatePlanFrontmatterText(text) {
 // src/commands/validate.ts
 async function resolveEditedPath(cwd, explicit) {
   if (explicit) {
-    const filePath2 = path43.resolve(cwd, explicit);
+    const filePath2 = path47.resolve(cwd, explicit);
     try {
-      return { filePath: filePath2, content: await readFile21(filePath2, "utf8") };
+      return { filePath: filePath2, content: await readFile25(filePath2, "utf8") };
     } catch {
       return null;
     }
@@ -7886,9 +8852,9 @@ async function resolveEditedPath(cwd, explicit) {
   const payload = await readStdinJson();
   const rel = typeof payload.file_path === "string" && payload.file_path || typeof payload.path === "string" && payload.path || typeof payload.file === "string" && payload.file || "";
   if (!rel) return null;
-  const filePath = path43.isAbsolute(rel) ? rel : path43.resolve(cwd, rel);
+  const filePath = path47.isAbsolute(rel) ? rel : path47.resolve(cwd, rel);
   try {
-    return { filePath, content: await readFile21(filePath, "utf8") };
+    return { filePath, content: await readFile25(filePath, "utf8") };
   } catch {
     return null;
   }
@@ -7900,13 +8866,13 @@ function isPlanPath(filePath) {
   const norm = filePath.replace(/\\/g, "/");
   return norm.includes("/.cursor/plans/") && norm.endsWith(".plan.md");
 }
-var validateCommand = defineCommand18({
+var validateCommand = defineCommand19({
   meta: {
     name: "validate",
     description: "Advisory validators for HANDOFF / plan frontmatter (hook adapter)."
   },
   subCommands: {
-    handoff: defineCommand18({
+    handoff: defineCommand19({
       meta: { name: "handoff", description: "Validate HANDOFF machine fields" },
       args: {
         cwd: { type: "string", default: process.cwd() },
@@ -7916,10 +8882,10 @@ var validateCommand = defineCommand18({
       async run({ args }) {
         const cwd = typeof args.cwd === "string" ? args.cwd : process.cwd();
         const fileArg = typeof args.file === "string" ? args.file : void 0;
-        const filePath = fileArg ? path43.resolve(cwd, fileArg) : path43.join(path43.resolve(cwd), ".cursor", "HANDOFF.md");
+        const filePath = fileArg ? path47.resolve(cwd, fileArg) : path47.join(path47.resolve(cwd), ".cursor", "HANDOFF.md");
         let content = "";
         try {
-          content = await readFile21(filePath, "utf8");
+          content = await readFile25(filePath, "utf8");
         } catch {
           console.log(JSON.stringify({ ok: true, warnings: [], note: "file missing" }));
           return;
@@ -7928,7 +8894,7 @@ var validateCommand = defineCommand18({
         console.log(JSON.stringify({ ok: warnings.length === 0, warnings }));
       }
     }),
-    plan: defineCommand18({
+    plan: defineCommand19({
       meta: { name: "plan", description: "Validate plan frontmatter" },
       args: {
         cwd: { type: "string", default: process.cwd() },
@@ -7943,10 +8909,10 @@ var validateCommand = defineCommand18({
           process.exitCode = 2;
           return;
         }
-        const filePath = path43.resolve(cwd, fileArg);
+        const filePath = path47.resolve(cwd, fileArg);
         let content = "";
         try {
-          content = await readFile21(filePath, "utf8");
+          content = await readFile25(filePath, "utf8");
         } catch {
           console.log(JSON.stringify({ ok: true, warnings: [], note: "file missing" }));
           return;
@@ -7955,7 +8921,7 @@ var validateCommand = defineCommand18({
         console.log(JSON.stringify({ ok: warnings.length === 0, warnings }));
       }
     }),
-    "after-edit": defineCommand18({
+    "after-edit": defineCommand19({
       meta: {
         name: "after-edit",
         description: "Advisory afterFileEdit: annotate HANDOFF/plan issues (never block)"
@@ -7965,7 +8931,7 @@ var validateCommand = defineCommand18({
       },
       async run({ args }) {
         const cwd = typeof args.cwd === "string" ? args.cwd : process.cwd();
-        const resolved = await resolveEditedPath(path43.resolve(cwd));
+        const resolved = await resolveEditedPath(path47.resolve(cwd));
         if (!resolved) {
           console.log(JSON.stringify({}));
           return;
@@ -8008,14 +8974,14 @@ var validateCommand = defineCommand18({
 });
 
 // src/welcome/help-groups.ts
-import { bold, gray as gray4, underline } from "kolorist";
+import { bold as bold2, gray as gray4, underline } from "kolorist";
 
 // src/welcome/screen.ts
 import {
   blue as blue2,
-  cyan as cyan4,
+  cyan as cyan6,
   gray as gray3,
-  options as koloristOptions2,
+  options as koloristOptions3,
   lightCyan,
   trueColor,
   white as white2
@@ -8044,15 +9010,15 @@ function outlineAnsi(line) {
   return trueColor(r, g, b)(line);
 }
 function withKoloristColor(fn) {
-  const prevEnabled = koloristOptions2.enabled;
-  const prevLevel = koloristOptions2.supportLevel;
-  koloristOptions2.enabled = true;
-  koloristOptions2.supportLevel = KOLORIST_TRUECOLOR;
+  const prevEnabled = koloristOptions3.enabled;
+  const prevLevel = koloristOptions3.supportLevel;
+  koloristOptions3.enabled = true;
+  koloristOptions3.supportLevel = KOLORIST_TRUECOLOR;
   try {
     return fn();
   } finally {
-    koloristOptions2.enabled = prevEnabled;
-    koloristOptions2.supportLevel = prevLevel;
+    koloristOptions3.enabled = prevEnabled;
+    koloristOptions3.supportLevel = prevLevel;
   }
 }
 function hasCliSubcommand(rawArgs) {
@@ -8079,7 +9045,7 @@ function renderWelcomeScreen(opts = {}) {
   const version = opts.version ?? KIT_VERSION;
   const color = shouldUseWelcomeColor(opts);
   const title = color ? white2("Mission Kit") : "Mission Kit";
-  const product = color ? cyan4("agent-kit") : "agent-kit";
+  const product = color ? cyan6("agent-kit") : "agent-kit";
   const muted = (s) => color ? gray3(s) : s;
   const lines = [
     renderHelmetAscii(color),
@@ -8092,7 +9058,7 @@ function renderWelcomeScreen(opts = {}) {
       const width = Math.max(...WELCOME_UTILITY_HINTS.map(({ cmd }) => cmd.length));
       return WELCOME_UTILITY_HINTS.map(({ cmd, hint }) => {
         const pad = " ".repeat(width - cmd.length + 2);
-        const left = color ? cyan4(`  ${cmd}`) : `  ${cmd}`;
+        const left = color ? cyan6(`  ${cmd}`) : `  ${cmd}`;
         return `${left}${pad}${muted(hint)}`;
       });
     })(),
@@ -8153,7 +9119,7 @@ async function resolveSubMeta(subCommands) {
 }
 async function renderGroupedRootHelp(cmd) {
   const color = shouldUseWelcomeColor();
-  const u = (s) => color ? underline(bold(s)) : s;
+  const u = (s) => color ? underline(bold2(s)) : s;
   const g = (s) => color ? gray4(s) : s;
   const meta = await resolveCommandMeta(cmd.meta);
   const name = meta?.name ?? "agent-kit";
@@ -8198,7 +9164,7 @@ async function renderGroupedRootHelp(cmd) {
 }
 
 // src/index.ts
-var main = defineCommand19({
+var main = defineCommand20({
   meta: {
     name: "agent-kit",
     description: "HITL framework for AI-assisted IDEs (Mission Kit family)",
@@ -8210,6 +9176,7 @@ var main = defineCommand19({
     scan: scanCommand,
     add: addCommand,
     doctor: doctorCommand,
+    "setup-global": setupGlobalCommand,
     status: statusCommand,
     update: updateCommand,
     "cursor-awareness": cursorAwarenessCommand,