@dadado/agent-kit-cli 4.8.9 → 5.0.0

package/dist/index.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 // src/index.ts
-import { defineCommand as defineCommand19, runMain } from "citty";
+import { defineCommand as defineCommand19, runMain, showUsage } from "citty";
 
 // src/commands/add.ts
 import { defineCommand } from "citty";
@@ -69,53 +69,116 @@ import path3 from "path";
 
 // src/lifecycle/overlay-known-hashes.ts
 var KNOWN_SHIPPED_OVERLAY_HASHES = /* @__PURE__ */ new Set([
+  "004d98f557942677264d053dcd8335f2bbcf19c5591123ec16a7a2697cb88932",
+  "05ee6ecde4215e33ace0ee152ffbf2cd885d2bd4b032900f0f0bb001d350ef0f",
   "082bdbc584be3f3d8aa6e9d7b9f4e076450f3ff48f9147a1deb557e31475036b",
+  "0b5fe4729c3c68654434837630d775b847c082418f25b0b2c581700fe84b797a",
+  "1106b279558b6a20f87951102f172a680976f3e6530855d5dad083e1f89b9ba3",
   "15566765ec95dad3bc3160f20ac910e01a13471df536e6d990f4b263700784a9",
   "1681e6cf7b80a67cd999b94b8b6e16eb8caed0e11b32905848ba733da956e902",
+  "17818e47e06349ee35c1d8e1cc16e8bcbbbcc89c664014e9096e1f08c8567807",
   "1974a5af0e4ba2bb0fc7e1872ef9ab70e323323ab216958c31731bcdd82c8241",
+  "1b384771cc6228215e31e6a9ab0943b13a5cdc463354a2641f1c0d85b4357e84",
+  "1b5f8c4197393dc9110d020f3b619b8502862adeb6522a6b9be4b49dd8794612",
+  "1c5c1af87951367ad04bb6fa5b1d6ebaaefbc0ee95989b624cabf406a1869907",
+  "1ded5c7b7eefc355fc1d17feb65ec472e35ed96076e47ce95f7bff5c1b84746c",
   "1e58e0d4f2e8459b95a40d1b1e72c5c85a87230cbde945840a84073fe3a20422",
   "285668d08f1b15d96286d27e29cc4a67e126e097fb8a940bdde33ccf25bd2bcd",
+  "2acdb148b07f3a4872b896da419af796fd3fefaace7ac79cdee0aab447004a83",
+  "2cd7fc018a384b0188737259ecf593ce25b4b75cc38b3e410063ac91745894b9",
+  "2f6cedfa61cb62126efd6b845bbf4d8d7913e39223d5f799ac09ef64c0489824",
+  "3204a7449f3031916a8d57b37144e5d8ded6c94aa5659493fa5cc2c7321f4eab",
+  "33982aea21a074d21a638850475ce1fefa7d043ec035de3855889cc68d60cf35",
+  "38675aec695e9d4e7f16e8fbe3facc3280f47fb875bf9ac50bd6837b92b7a7fa",
+  "3ee94e2441218025c085856679d17b4a4fe7a6e3d0274423abe20a422a5ab05d",
   "3f3354825ff06ff9f9ae1e29b71784fef4250020c23c1b490940cf06b2be0f28",
+  "46a1dd4a07a2190ab9fb09abc05a3962277209f8e0c28033bb41450301474c86",
+  "48a0d55e21132a305946b195db7f6b75da78d44a1d32166fb0c69bef4a5ffbe2",
+  "4b62a46c74e5fa6a80283f21e8e6711958fbcd577051dc73ff4050643a031475",
   "4bf23acbc9bd4e0f8468e61f4970e182600b72d9025d29e81ddbd83cb7b1710a",
   "4c5167d0ebde685f266dce32c516a7c43876e0520647b93f07f2e2147e6a7b2f",
   "4dc4efcd1b43c643d3889fb349df8d4964d0867c3a67eb67e2ec168fbb70fc75",
+  "4f133554d01cedc62280006f4cf6453e25a5cb41ef6dde4a43f9508cb36ef75d",
+  "4fe1e2bce8bd55a6decdd62c887a423cf85148b692f313aad4c777d0e50596b3",
   "4ff844cf789cef4b1e809a55ca006316cd964bcdb2557d91c916a08e30ad15f6",
   "533b41599c25698e5746166096a68fd4080efb5e16287b2a1ed5f73295cda446",
+  "54dda8addb74bc187ee23c31f8b7d17ad19e745a45169d29ffea094860eb18f2",
   "570c3f91fd31a4cc1e56e997c85feab5c6756f45fc73dc741afe573912111231",
+  "5cb36f5dab846b2551afd05eab92c14122853c147d7f02136d1c04e01e3c9def",
   "5d302d207521c53b9fa814ee0eba1376a5b2bfd2983c0373657c9fdf9884541b",
+  "5f5c125f7edf280029f214589ce3e088fc74bad717e30178405a3b537673c42f",
   "621bc6cecf7c710a97e93463ca9b8872a1fcab1325c358cc8be65b418eebb339",
+  "693c732658e31d6403cf59e85985518f24ab92bf7fcdc3c225e9a79e54597a43",
   "69715048da3963947aa8a39e7ac30ec01632fec862bfcb9559c46764b4833be0",
+  "6994595e3a62edb6c518006a6bece6848c7077977c041439cf7c822b89304a14",
   "6a42e76fc038ca69ddad18541b8df161770c58980fefaf9e5e80d87407074bec",
   "6a9af9e8a95dbb279347166c43dcee245ca673f9687841086b49911c54944c26",
   "6b66ed7747ea2d19cb457f5af656e3c07f9f563f7f32b3951fa4ae5f27f0ac46",
+  "6dede0588274f5b44d833bcc696ec4776eb978ed24a20efdcc9c38caf3df1576",
+  "71991a10972b8b956cae93c88517e31741c95e351814082df65e44f813590210",
+  "75e591bfde61ca1ca3ca1303cc9bc487197af2f713c68f346a46e94ca9432fd5",
   "76ae85bbc336c6f435d9653e8f254ae49774b4ebaecf7335697115933eb8797c",
+  "79878f0f6f59d1a0b65d94011c0cafe7b6f8e03e89f568aa638b8ba7a2c34076",
   "8108b202c829627c3c2df33575016ebe942df42acf4f1cc393900be3b82b402c",
+  "819b7bd3ba9e8bf12dcd4f81a76c98e48261b34c397f339b36d36eb364d9c3f4",
   "8619500b0c7024390d43e3aaefa2a2d731728d7c664aaf90e0acdd067f3397ce",
+  "875b0a8805280b2a2df43f2c42f9063fe0623a34fa19c3aa5d2ec48211f3ebae",
   "8a11c80b0fbf6c4aabf60eec05b8cca7dccf5bca472787a8afa3028fd8fbedfa",
   "8b25659727063013e8bf6d7925f815b2630c2919b21e6fdac354362bf122bfab",
   "8c7edbacc74b1431fbecb04c9857c0e7a9cb1578fc6ca6367be888dbcec3c98f",
+  "8ffc181bb152c68a3353309bfdc87c42bdb925b98675cdba959c0cdb90b2adea",
+  "91ce0c933e3c8ee81927b8224f944ec5ce5445098a2ad154773092e3541dbf69",
+  "9309af07a0a99a56143386b3ddd2a35fae29378fba3f6b4c9297a5d1c02a9724",
   "9439da963acbe5dd88a3aa4d6ba4fb297db666ce8f2c9d3917dbc6d6e517f9aa",
+  "989e7e1bdfb29dedf850405f28648810d008885196efe7ae38c6e7554c7ce45d",
   "98d96e25f67aa9c234cb0c422f0d701c22a04bfe184fb4eb68295003d429552b",
   "99031145609af46e7e0f315006bf633f47002eccece8eb7af8b5efd762313ade",
   "9a3cea681399b42ef930a0720802378fe1b06ee73370df9ede9d0309c3c60ab2",
+  "9ccf52fe53c6fa4d731650ab4928ce50e201fa34f3e174fee70e3d29867fef2a",
   "9d905aca0123f3018c81c579217104f1749d8da802f3837b2407fbad8f2d803f",
+  "9e324c52c1a9d1ceee738bccf47da92910aca9f7a5a21cc41738d9573c414830",
+  "a013a6a476160183d6457ff6c1c51ec228bdca359b11eb15cd9b7fc177a705db",
   "a08d04f8efa121ad498f96873778c22630c9172c07c216839e348cd0bb7c2292",
+  "a7cd7058bcb6fbd962c37317fa16893bc86a270d0164af5a0e6f3f026aa408ad",
+  "a833a7131cdfc003b45a48cb26c6ce33dc218c1814156047db5211a79192e0a0",
+  "ac2f1f7d9e68f9c98fc4fe5ca348b1a90cf484141bbd116db871d63bdcc3c7c3",
   "b5c7a10df90d209be07159b7ff9bfa24e869538a0b6026bb5ce79e1cdd5b2528",
+  "bd9fd1efacbd132c5dafc12cd0cf2b651a2b1fab7b2d7a9ba4a3e44128097f48",
+  "be964ff33a40280e13ce6071fb3e30ce87c374527efbb74c25c9d4534084a634",
   "c96d522be440fbb638dbe953cebf1bb31185c431ac2e14446369cfb7d155a951",
   "cf2bd11891b934484171fa705f470de284e3874402e1e487750735dbc7692857",
+  "d0e3bf82efbe32c09761689802ffea7838046dbdd4803b88ead5ec3dfc7efb7e",
   "d4659e4bb6fd6022559fc632b17db6a39007c04bc0ded59017a0dacc013632ed",
   "d484243167e13c34f9df7ff378baf2967f7cbfcd88170d4d32e745efbcae7480",
+  "d67ac8fa1edec6e50c82aeca064335e799e408d0e4bbc95e1407cf7463a61de3",
+  "d7ad53f06a41bcb2f2b998fd4a4c99209a0cf287cf0d0d4acbcc36c73dd46e4a",
   "d96aa15dde45147aa40db64684688a4b5c9ad660dcd16c55156b31933a42c37e",
   "d9ecd90f80ebc25db73ebed27c32596b9cfce518b3026a3a4d5787321ba6324a",
   "dd01d051dbab257e16609b02c983bad6a576ed8473781b4f1df9ef2eb5f85795",
+  "dd9ff2ff8aa7bcb2cdfc59092ad73227631c1c3619b495131f7faee65224cb17",
   "de6efabde6a1d69357926b88b5a4ed3eec19e11b82597cb999f5365f952305b8",
+  "debc0758b3e39294df85ccb7eab3455e93a2b8c608602d309a7b0ebdb6618805",
   "e03b5764b908f9ed5c592108fbc11d5962d9256fd129a63ab4a39c8efaa2ef3e",
   "e102e77f9f520f938d26861978249e4d85a8c8755d48c8e79b21fef9423325ee",
+  "e2d89f780c6ae5393dc05818f9e3e9a8bf6629eac05702eea8f9a25b578e3ff1",
+  "e2f1e9108fd450817ab42570db656b1e43b20b5ba703b14027ce540e1b8fe502",
+  "e37c62695b5c70451ef1a0c90b31b73a9c442ebc55fb3fc3f79c294b993b99ea",
+  "e3c32aec17e8f728cbd13162a123a9debffb8bbcec527a00b1c2df30a1a20080",
   "e511e04064ffb8c429b659d2ae2e0f223e8cc51039ae816753095a5f7a160595",
+  "e5682d4696e874d09f12a1d65891fee5971201a29c654c08f5d3b90fb9a6a0b7",
+  "e57437bf790fda1d43b895e2b5b0a7d2d57635c319ac0e2439ba2222a825bcde",
+  "e8bb214c3e551c44f379db13c5962ef20698b505b0227d283d3ae632e1bc3626",
+  "ea36e74c9d592980cba5c08d04ee70fc59a6cd01e87a50bbfae4f668557df4b4",
   "ebd41f8df764a14b3460016fafcfdde98c4c3a59a3c17f773451ef061fc42f95",
+  "ef181a4e2bd9f82f45628637b8d66925ffa20801558808f1b03ea72b7cb82a72",
   "f061432a2606049717c0cbf098ef07b1da4df2b136c4cb9cdaa7ea44c876bcd6",
   "f061d36a1180293519fbb560bbf659c621bd90885e995fca6eaf2eda9e418a50",
-  "f28731a82f4b394a5765fdefe2d1b667810831f6dcea400ca62bc66e1d65371c"
+  "f28731a82f4b394a5765fdefe2d1b667810831f6dcea400ca62bc66e1d65371c",
+  "f46c108457e4fe12953dca75b409e06fca9cb264baffabe0c0d04c89af471e56",
+  "f6bc17efa746680a44bbc49be67ac3f924d9c306c6d937f9959c57a1d3c5b9af",
+  "f981764422d468567b5aff31148dc659aeee22cb13dc0ecd873d737deaf07372",
+  "fa306a0cdb0f40c817e32164cd03b946564a02b4b7f7c3f4f0b9513096584d28",
+  "fa5cf460eb314437081f7cea30dc8041c0bd6fc3f560a74bc2d7be1bf07384b0"
 ]);
 
 // src/lifecycle/paths.ts
@@ -475,11 +538,119 @@ function logApplyStats(stats) {
 
 // src/registry/resolve.ts
 import { execFile } from "child_process";
-import { createHash as createHash2 } from "crypto";
+import { createHash as createHash2, randomUUID } from "crypto";
+import { mkdir as mkdir4, readFile as readFile4, rename, rm, stat, writeFile as writeFile3 } from "fs/promises";
 import { homedir } from "os";
 import path5 from "path";
 import { promisify } from "util";
 var execFileAsync = promisify(execFile);
+var LOCK_TIMEOUT_MS = 6e4;
+var LOCK_RETRY_MS = 200;
+var LOCK_STALE_MS = 5 * 6e4;
+var LOCK_REFRESH_MS = 1e4;
+function lockOwnerPath(lockDir) {
+  return path5.join(lockDir, "owner.json");
+}
+function isProcessAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function readLockOwner(lockDir) {
+  try {
+    const raw = await readFile4(lockOwnerPath(lockDir), "utf8");
+    const parsed = JSON.parse(raw);
+    if (typeof parsed.pid === "number" && typeof parsed.uuid === "string") {
+      return parsed;
+    }
+  } catch {
+  }
+  return null;
+}
+async function writeLockOwner(lockDir, owner) {
+  const finalPath = lockOwnerPath(lockDir);
+  const tmpPath = path5.join(lockDir, `owner.${owner.uuid}.tmp`);
+  await writeFile3(tmpPath, JSON.stringify(owner), "utf8");
+  await rename(tmpPath, finalPath);
+}
+async function refreshLockOwner(lockDir, uuid) {
+  const owner = await readLockOwner(lockDir);
+  if (!owner || owner.uuid !== uuid) return;
+  await writeLockOwner(lockDir, { ...owner, updatedAt: Date.now() });
+}
+async function releaseCacheLock(lockDir, uuid) {
+  const owner = await readLockOwner(lockDir);
+  if (!owner || owner.uuid !== uuid) {
+    return;
+  }
+  try {
+    await rm(lockDir, { recursive: true, force: true });
+  } catch {
+  }
+}
+async function tryReclaimStaleLock(lockDir) {
+  let owner;
+  let lockStat;
+  try {
+    lockStat = await stat(lockDir);
+    owner = await readLockOwner(lockDir);
+  } catch {
+    return false;
+  }
+  const now2 = Date.now();
+  if (owner) {
+    const ownerFresh = now2 - owner.updatedAt < LOCK_STALE_MS;
+    if (isProcessAlive(owner.pid) && ownerFresh) {
+      return false;
+    }
+  }
+  if (now2 - lockStat.mtimeMs > LOCK_STALE_MS) {
+    try {
+      await rm(lockDir, { recursive: true, force: true });
+      return true;
+    } catch {
+    }
+  }
+  return false;
+}
+async function acquireCacheLock(cacheDir) {
+  const lockDir = `${cacheDir}.lock`;
+  const deadline = Date.now() + LOCK_TIMEOUT_MS;
+  const uuid = randomUUID();
+  const owner = { pid: process.pid, uuid, updatedAt: Date.now() };
+  await mkdir4(path5.dirname(lockDir), { recursive: true });
+  while (Date.now() < deadline) {
+    try {
+      await mkdir4(lockDir, { recursive: false });
+      await writeLockOwner(lockDir, owner);
+      const refreshInterval = setInterval(() => {
+        refreshLockOwner(lockDir, uuid).catch(() => {
+        });
+      }, LOCK_REFRESH_MS);
+      return async () => {
+        clearInterval(refreshInterval);
+        await releaseCacheLock(lockDir, uuid);
+      };
+    } catch (err) {
+      const code = err.code;
+      if (code === "EEXIST") {
+        if (await tryReclaimStaleLock(lockDir)) {
+          continue;
+        }
+        await new Promise((r) => setTimeout(r, LOCK_RETRY_MS + Math.random() * 100));
+        continue;
+      }
+      if (code === "ENOENT") {
+        continue;
+      }
+      throw err;
+    }
+  }
+  throw new Error(`Timed out waiting for cache lock on ${cacheDir}. Another install may be stuck.`);
+}
 var DEFAULT_REGISTRY_URL = "https://github.com/agent-kit-startup/agent-kit";
 var DEFAULT_REGISTRY_REF = "main";
 var SAFE_URL = /^https:\/\/[^\s]+$/;
@@ -504,15 +675,32 @@ async function hasRegistryIndex(root) {
   return fileExists(path5.join(root, "registry", "registry.json"));
 }
 async function cloneRegistry(url, ref, dest) {
-  const { mkdir: mkdir6 } = await import("fs/promises");
-  await mkdir6(path5.dirname(dest), { recursive: true });
+  const { mkdir: mkdir7 } = await import("fs/promises");
+  await mkdir7(path5.dirname(dest), { recursive: true });
   try {
     await execFileAsync("git", ["clone", "--depth", "1", "--branch", ref, "--", url, dest], {
       env: gitEnv()
     });
-  } catch {
-    await execFileAsync("git", ["clone", "--depth", "1", "--", url, dest], { env: gitEnv() });
-    await execFileAsync("git", ["checkout", ref, "--"], { cwd: dest, env: gitEnv() });
+  } catch (firstErr) {
+    try {
+      await execFileAsync("git", ["clone", "--depth", "1", "--", url, dest], { env: gitEnv() });
+      await execFileAsync("git", ["checkout", ref, "--"], { cwd: dest, env: gitEnv() });
+    } catch (secondErr) {
+      const msg = secondErr instanceof Error ? secondErr.message : String(secondErr);
+      if (/403|Authentication|could not read Username/i.test(msg)) {
+        throw new Error(
+          `Registry clone failed (auth/access): ${url}@${ref}. Check git credentials or use --registry <local-path> for a local checkout.`
+        );
+      }
+      if (/Could not resolve host|Network is unreachable|Connection refused/i.test(msg)) {
+        throw new Error(
+          `Registry clone failed (network): ${url}@${ref}. Check network/proxy settings or use --registry <local-path>.`
+        );
+      }
+      throw new Error(
+        `Registry clone failed: ${url}@${ref}. ${msg}. Use --registry <local-path> if you have a local checkout.`
+      );
+    }
   }
 }
 async function refreshCache(cacheDir) {
@@ -556,15 +744,24 @@ async function resolveRegistryRoot(options) {
   const ref = options.registryRef ?? DEFAULT_REGISTRY_REF;
   assertSafeRegistrySource(url, ref);
   const dest = path5.join(homedir(), ".cache", "agent-kit", "registry", cacheKey(url, ref));
-  if (await hasRegistryIndex(dest)) {
-    await refreshCache(dest);
-    return { root: dest, source: "remote-cache", url, ref };
-  }
-  await cloneRegistry(url, ref, dest);
-  if (!await hasRegistryIndex(dest)) {
-    throw new Error(`Cloned ${url}@${ref} but registry/registry.json is missing`);
+  const unlock = await acquireCacheLock(dest);
+  let ownershipTransferred = false;
+  try {
+    if (await hasRegistryIndex(dest)) {
+      await refreshCache(dest);
+    } else {
+      await cloneRegistry(url, ref, dest);
+      if (!await hasRegistryIndex(dest)) {
+        throw new Error(`Cloned ${url}@${ref} but registry/registry.json is missing`);
+      }
+    }
+    ownershipTransferred = true;
+    return { root: dest, source: "remote-cache", url, ref, unlock };
+  } finally {
+    if (!ownershipTransferred) {
+      await unlock();
+    }
   }
-  return { root: dest, source: "remote-cache", url, ref };
 }
 
 // src/lifecycle/resolve-cli.ts
@@ -826,7 +1023,7 @@ async function findPack(rootDir, packId) {
 }
 
 // src/registry/install.ts
-import { readFile as readFile4 } from "fs/promises";
+import { readFile as readFile5 } from "fs/promises";
 import path8 from "path";
 function targetForMember(member) {
   switch (member.kind) {
@@ -945,7 +1142,7 @@ function packMemberTargets(member) {
 var addCommand = defineCommand({
   meta: {
     name: "add",
-    description: "Install a skill or L1 pack from the registry into the project."
+    description: "Install a skill or L1 pack from the registry."
   },
   args: {
     id: {
@@ -982,64 +1179,68 @@ var addCommand = defineCommand({
       refresh: args.refresh,
       manifest: existing
     });
-    const protectedGlobs = resolveProtectedGlobs(existing);
-    const index = await loadRegistry(registry.root);
-    const asSkill = allSkills(index).find((s) => s.id === args.id);
-    const asPack = allPacks(index).find((p) => p.id === args.id);
-    const base = existing ? { ...existing } : buildManifest({
-      version: KIT_VERSION,
-      profile: "default",
-      registryUrl: registry.url,
-      registryRef: registry.ref
-    });
-    const finish = async (kind, id) => {
-      if (kind === "skill") base.skills = upsertIdList(base.skills, id);
-      else base.packs = upsertIdList(base.packs, id);
-      if (registry.url || registry.ref) {
-        base.registry = {
-          url: registry.url ?? base.registry?.url,
-          ref: registry.ref ?? base.registry?.ref
-        };
+    try {
+      const protectedGlobs = resolveProtectedGlobs(existing);
+      const index = await loadRegistry(registry.root);
+      const asSkill = allSkills(index).find((s) => s.id === args.id);
+      const asPack = allPacks(index).find((p) => p.id === args.id);
+      const base = existing ? { ...existing } : buildManifest({
+        version: KIT_VERSION,
+        profile: "default",
+        registryUrl: registry.url,
+        registryRef: registry.ref
+      });
+      const finish = async (kind, id) => {
+        if (kind === "skill") base.skills = upsertIdList(base.skills, id);
+        else base.packs = upsertIdList(base.packs, id);
+        if (registry.url || registry.ref) {
+          base.registry = {
+            url: registry.url ?? base.registry?.url,
+            ref: registry.ref ?? base.registry?.ref
+          };
+        }
+        base.version = KIT_VERSION;
+        await saveManifest(args.cwd, base);
+      };
+      if (args.skill) {
+        const skill = await findSkill(registry.root, args.id);
+        const stats = await installSkill(registry.root, args.cwd, skill, { protectedGlobs });
+        logApplyStats(stats);
+        await finish("skill", skill.id);
+        logger.success(`Skill '${skill.id}' added.`);
+        return;
       }
-      base.version = KIT_VERSION;
-      await saveManifest(args.cwd, base);
-    };
-    if (args.skill) {
-      const skill = await findSkill(registry.root, args.id);
-      const stats = await installSkill(registry.root, args.cwd, skill, { protectedGlobs });
-      logApplyStats(stats);
-      await finish("skill", skill.id);
-      logger.success(`Skill '${skill.id}' added.`);
-      return;
-    }
-    if (args.pack) {
-      const pack = await findPack(registry.root, args.id);
-      const stats = await installPack(registry.root, args.cwd, pack.id, { protectedGlobs });
-      logApplyStats(stats);
-      await finish("pack", pack.id);
-      logger.success(`Pack '${pack.id}' added.`);
-      return;
-    }
-    if (asSkill && asPack) {
-      throw new Error(
-        `'${args.id}' is both a skill and a pack. Disambiguate: agent-kit add --skill ${args.id} | agent-kit add --pack ${args.id}`
-      );
-    }
-    if (asSkill) {
-      const stats = await installSkill(registry.root, args.cwd, asSkill, { protectedGlobs });
-      logApplyStats(stats);
-      await finish("skill", asSkill.id);
-      logger.success(`Skill '${asSkill.id}' added.`);
-      return;
-    }
-    if (asPack) {
-      const stats = await installPack(registry.root, args.cwd, asPack.id, { protectedGlobs });
-      logApplyStats(stats);
-      await finish("pack", asPack.id);
-      logger.success(`Pack '${asPack.id}' added.`);
-      return;
+      if (args.pack) {
+        const pack = await findPack(registry.root, args.id);
+        const stats = await installPack(registry.root, args.cwd, pack.id, { protectedGlobs });
+        logApplyStats(stats);
+        await finish("pack", pack.id);
+        logger.success(`Pack '${pack.id}' added.`);
+        return;
+      }
+      if (asSkill && asPack) {
+        throw new Error(
+          `'${args.id}' is both a skill and a pack. Disambiguate: agent-kit add --skill ${args.id} | agent-kit add --pack ${args.id}`
+        );
+      }
+      if (asSkill) {
+        const stats = await installSkill(registry.root, args.cwd, asSkill, { protectedGlobs });
+        logApplyStats(stats);
+        await finish("skill", asSkill.id);
+        logger.success(`Skill '${asSkill.id}' added.`);
+        return;
+      }
+      if (asPack) {
+        const stats = await installPack(registry.root, args.cwd, asPack.id, { protectedGlobs });
+        logApplyStats(stats);
+        await finish("pack", asPack.id);
+        logger.success(`Pack '${asPack.id}' added.`);
+        return;
+      }
+      throw new Error(`'${args.id}' not found as skill or pack in registry.`);
+    } finally {
+      await registry.unlock?.();
     }
-    throw new Error(`'${args.id}' not found as skill or pack in registry.`);
   }
 });
 
@@ -1047,7 +1248,7 @@ var addCommand = defineCommand({
 import { defineCommand as defineCommand2 } from "citty";
 
 // src/lifecycle/contribute.ts
-import { mkdir as mkdir4, readFile as readFile5, writeFile as writeFile3 } from "fs/promises";
+import { mkdir as mkdir5, readFile as readFile6, writeFile as writeFile4 } from "fs/promises";
 import path9 from "path";
 
 // src/lifecycle/contribute-gate.ts
@@ -1240,6 +1441,9 @@ var L0_ARTIFACTS = [
     source: ".cursor/commands/dogfood.md",
     target: ".cursor/commands/dogfood.md"
   },
+  // Factory-only: `.cursor/commands/public-issue-triage.md` is intentionally
+  // omitted from L0 (and excluded from public-sync). See ADR
+  // 2026-08-05_factory-only-public-issue-triage-command.md.
   {
     source: ".cursor/commands/cursor-update-awareness.md",
     target: ".cursor/commands/cursor-update-awareness.md"
@@ -1338,7 +1542,7 @@ var L0_ARTIFACTS = [
 // src/lifecycle/contribute.ts
 async function readLocal(projectRoot, rel) {
   try {
-    return await readFile5(resolveContained(projectRoot, rel), "utf8");
+    return await readFile6(resolveContained(projectRoot, rel), "utf8");
   } catch {
     return null;
   }
@@ -1414,7 +1618,7 @@ async function planContribute(options) {
     }
     if (kind === "drift") {
       try {
-        const upstream = await readFile5(
+        const upstream = await readFile6(
           resolveContained(options.registryRoot, registryPath),
           "utf8"
         );
@@ -1480,10 +1684,10 @@ async function writeContributeToRegistry(projectRoot, registryRoot, accepted) {
   const written = [];
   for (const c of accepted) {
     if (!c.registryPath) continue;
-    const content = await readFile5(resolveContained(projectRoot, c.projectPath), "utf8");
+    const content = await readFile6(resolveContained(projectRoot, c.projectPath), "utf8");
     const dest = resolveContained(registryRoot, c.registryPath);
-    await mkdir4(path9.dirname(dest), { recursive: true });
-    await writeFile3(dest, content, "utf8");
+    await mkdir5(path9.dirname(dest), { recursive: true });
+    await writeFile4(dest, content, "utf8");
     written.push(c.registryPath);
   }
   return written;
@@ -1554,57 +1758,61 @@ var contributeCommand = defineCommand2({
       refresh: args.refresh,
       manifest
     });
-    if (registry.source !== "flag" && args.write) {
-      logger.warn(
-        "contribute --write needs a local kit checkout. Pass --registry /path/to/agent-kit."
-      );
-      return;
-    }
-    logger.info(`Registry: ${registry.root} (${registry.source})`);
-    const plan = await planContribute({
-      registryRoot: registry.root,
-      projectRoot: args.cwd,
-      manifest,
-      extraPaths: parsePaths(args.path),
-      includeDrift: args.drift
-    });
-    console.log(
-      `Contribute plan: accepted=${plan.accepted.length} rejected=${plan.rejected.length} (drift scan=${args.drift})`
-    );
-    if (plan.candidates.length === 0) {
-      logger.success("Nothing to contribute (no drift / no --path).");
-      return;
-    }
-    for (const c of plan.candidates) {
-      const mark = c.gateOk ? "ok" : "FAIL";
+    try {
+      if (registry.source !== "flag" && args.write) {
+        logger.warn(
+          "contribute --write needs a local kit checkout. Pass --registry /path/to/agent-kit."
+        );
+        return;
+      }
+      logger.info(`Registry: ${registry.root} (${registry.source})`);
+      const plan = await planContribute({
+        registryRoot: registry.root,
+        projectRoot: args.cwd,
+        manifest,
+        extraPaths: parsePaths(args.path),
+        includeDrift: args.drift
+      });
       console.log(
-        `${mark.padEnd(4)} ${c.kind.padEnd(5)} ${c.projectPath} \u2192 ${c.registryPath || "(unmapped)"}`
+        `Contribute plan: accepted=${plan.accepted.length} rejected=${plan.rejected.length} (drift scan=${args.drift})`
       );
-      for (const issue of c.issues) {
-        console.log(`       [${issue.code}] ${issue.message}`);
+      if (plan.candidates.length === 0) {
+        logger.success("Nothing to contribute (no drift / no --path).");
+        return;
       }
+      for (const c of plan.candidates) {
+        const mark = c.gateOk ? "ok" : "FAIL";
+        console.log(
+          `${mark.padEnd(4)} ${c.kind.padEnd(5)} ${c.projectPath} \u2192 ${c.registryPath || "(unmapped)"}`
+        );
+        for (const issue of c.issues) {
+          console.log(`       [${issue.code}] ${issue.message}`);
+        }
+      }
+      if (plan.accepted.length === 0) {
+        logger.warn("No files passed the contribute gate.");
+        return;
+      }
+      console.log("\n--- Suggested PR body ---\n");
+      console.log(formatPrBody(plan.accepted));
+      if (!args.write) {
+        logger.info(
+          "Dry run. Re-run with --write --registry /path/to/agent-kit to copy accepted files into the kit checkout, then open a PR (gh pr create --base main)."
+        );
+        return;
+      }
+      const written = await writeContributeToRegistry(args.cwd, registry.root, plan.accepted);
+      logger.success(`Wrote ${written.length} file(s) into ${registry.root}`);
+      for (const p of written) console.log(`  + ${p}`);
+      console.log("\nNext (HITL \u2014 review before push):");
+      console.log(`  cd ${registry.root}`);
+      console.log("  git checkout -b contribute/<short-topic>");
+      console.log('  git add <files> && git commit -m "feat: contribute <topic> from consumer"');
+      console.log("  git push -u origin HEAD");
+      console.log('  gh pr create --base main --title "feat: contribute <topic>" --body-file -');
+    } finally {
+      await registry.unlock?.();
     }
-    if (plan.accepted.length === 0) {
-      logger.warn("No files passed the contribute gate.");
-      return;
-    }
-    console.log("\n--- Suggested PR body ---\n");
-    console.log(formatPrBody(plan.accepted));
-    if (!args.write) {
-      logger.info(
-        "Dry run. Re-run with --write --registry /path/to/agent-kit to copy accepted files into the kit checkout, then open a PR (gh pr create --base main)."
-      );
-      return;
-    }
-    const written = await writeContributeToRegistry(args.cwd, registry.root, plan.accepted);
-    logger.success(`Wrote ${written.length} file(s) into ${registry.root}`);
-    for (const p of written) console.log(`  + ${p}`);
-    console.log("\nNext (HITL \u2014 review before push):");
-    console.log(`  cd ${registry.root}`);
-    console.log("  git checkout -b contribute/<short-topic>");
-    console.log('  git add <files> && git commit -m "feat: contribute <topic> from consumer"');
-    console.log("  git push -u origin HEAD");
-    console.log('  gh pr create --base main --title "feat: contribute <topic>" --body-file -');
   }
 });
 
@@ -1612,13 +1820,30 @@ var contributeCommand = defineCommand2({
 import { defineCommand as defineCommand3 } from "citty";
 
 // src/lifecycle/cursor-update-awareness.ts
-import { readFile as readFile6 } from "fs/promises";
+import { access as access2, readFile as readFile7 } from "fs/promises";
 import path10 from "path";
 var DEFAULT_CURSOR_CHANGELOG_URL = "https://cursor.com/changelog";
 var CHANGELOG_FETCH_TIMEOUT_MS = 15e3;
 var CURSOR_VERSION_MAJOR_MAX = 20;
 var INVENTORY_REL = path10.join("docs", "cursor-native-audit.md");
 var FEATURES_REL = path10.join("docs", "cursor-3-features.md");
+async function resolveInventoryRoot(cwd) {
+  let dir = path10.resolve(cwd);
+  for (; ; ) {
+    try {
+      await access2(path10.join(dir, INVENTORY_REL));
+      return dir;
+    } catch {
+    }
+    const parent = path10.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return null;
+}
+function missingInventoryMessage() {
+  return `Missing inventory at ${INVENTORY_REL}. Run from the kit/repo root that contains that file, or pass --cwd <path>.`;
+}
 var DEFAULT_PREFS = {
   enabled: false,
   intervalDays: 7,
@@ -1786,8 +2011,6 @@ function baseResult(partial) {
   };
 }
 async function checkCursorUpdateAwareness(cwd, options = {}) {
-  const inventoryPath = path10.join(cwd, INVENTORY_REL);
-  const featuresPath = path10.join(cwd, FEATURES_REL);
   const prefs = readCursorUpdateCheckPrefs(await loadContextConfig(cwd));
   const changelogUrl = options.changelogUrl ?? prefs.changelogUrl;
   if (options.respectPrefs) {
@@ -1820,9 +2043,26 @@ async function checkCursorUpdateAwareness(cwd, options = {}) {
       });
     }
   }
+  const inventoryRoot = await resolveInventoryRoot(cwd);
+  if (!inventoryRoot) {
+    return baseResult({
+      status: "error",
+      inventoryPath: INVENTORY_REL,
+      featuresPath: FEATURES_REL,
+      changelogUrl,
+      latestCursorVersion: null,
+      lastSeenCursorVersion: prefs.lastSeenCursorVersion,
+      inventoryRefreshed: null,
+      openActionIds: [],
+      gaps: [],
+      message: missingInventoryMessage()
+    });
+  }
+  const inventoryPath = path10.join(inventoryRoot, INVENTORY_REL);
+  const featuresPath = path10.join(inventoryRoot, FEATURES_REL);
   let inventoryMd;
   try {
-    inventoryMd = await readFile6(inventoryPath, "utf8");
+    inventoryMd = await readFile7(inventoryPath, "utf8");
   } catch {
     return baseResult({
       status: "error",
@@ -1834,7 +2074,7 @@ async function checkCursorUpdateAwareness(cwd, options = {}) {
       inventoryRefreshed: null,
       openActionIds: [],
       gaps: [],
-      message: `Missing inventory at ${INVENTORY_REL}.`
+      message: missingInventoryMessage()
     });
   }
   const inventoryRefreshed = parseInventoryRefreshed(inventoryMd);
@@ -1865,7 +2105,7 @@ async function checkCursorUpdateAwareness(cwd, options = {}) {
     }
   }
   try {
-    const featuresMd = await readFile6(featuresPath, "utf8");
+    const featuresMd = await readFile7(featuresPath, "utf8");
     if (parseFeatureMapNames(featuresMd).length === 0) {
       gaps.push({
         id: "features-map-empty",
@@ -1947,7 +2187,7 @@ async function checkCursorUpdateAwareness(cwd, options = {}) {
 var cursorAwarenessCommand = defineCommand3({
   meta: {
     name: "cursor-awareness",
-    description: "Opt-in advisory: diff Cursor changelog / native-audit inventory for gaps (never apply, never Field Reports)"
+    description: "Opt-in advisory: Cursor changelog vs native-audit gaps (never apply)."
   },
   args: {
     cwd: {
@@ -2009,17 +2249,124 @@ var cursorAwarenessCommand = defineCommand3({
 });
 
 // src/commands/dashboard-broadcast.ts
-import { spawn as spawn2 } from "child_process";
-import { access as access3 } from "fs/promises";
+import { spawn as spawn3 } from "child_process";
+import { access as access4 } from "fs/promises";
 import path12 from "path";
 import { defineCommand as defineCommand5 } from "citty";
 
 // src/commands/dashboard.ts
-import { execFileSync, spawn } from "child_process";
-import { access as access2 } from "fs/promises";
+import { execFileSync, spawn as spawn2 } from "child_process";
+import { existsSync, readFileSync as readFileSync2, realpathSync } from "fs";
+import { access as access3 } from "fs/promises";
 import path11 from "path";
 import { fileURLToPath } from "url";
 import { defineCommand as defineCommand4 } from "citty";
+
+// ../../dashboard/lib/guards.mjs
+import { randomBytes, timingSafeEqual } from "crypto";
+import { networkInterfaces } from "os";
+import { resolve } from "path";
+var KIT_ROOT_ENV_KEYS = Object.freeze(["MISSION_CONTROL_KIT_ROOT", "AGENT_KIT_HOME"]);
+var CONTEXT_CONFIG_REL = ".cursor/context/config.json";
+var CONFIG_PERSONA_IDS = Object.freeze(["autopilot", "night-shift", "ghost-runner"]);
+var CONFIG_PERSONA_MODES = Object.freeze(["continue-plan", "run-plan", "cli-run-plan"]);
+var CONFIG_REVIEW_BACKENDS = Object.freeze(["claude"]);
+var CONFIG_REVIEW_MODES = Object.freeze(["paste", "autonomous"]);
+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;
+  if (typeof repoRoot !== "string" || !repoRoot) {
+    return { ok: false, error: "invalid repo root" };
+  }
+  const abs = resolve(repoRoot, CONTEXT_CONFIG_REL);
+  const contextDir = resolve(repoRoot, ".cursor", "context");
+  const absNorm = abs.replace(/\\/g, "/");
+  if (!absNorm.endsWith("/.cursor/context/config.json")) {
+    return { ok: false, error: "path escape" };
+  }
+  try {
+    if (typeof mkdir7 === "function" && typeof exists2 === "function" && !exists2(contextDir)) {
+      mkdir7(contextDir, { recursive: true });
+    }
+    if (typeof realpath === "function" && typeof exists2 === "function" && exists2(abs)) {
+      const fileReal = String(realpath(abs)).replace(/\\/g, "/");
+      const rootReal = String(realpath(repoRoot)).replace(/\\/g, "/");
+      if (!fileReal.startsWith(`${rootReal}/`)) {
+        return { ok: false, error: "path escape" };
+      }
+      if (!fileReal.endsWith("/.cursor/context/config.json")) {
+        return { ok: false, error: "path escape" };
+      }
+      return { ok: true, path: realpath(abs) };
+    }
+  } catch {
+    return { ok: false, error: "path escape" };
+  }
+  return { ok: true, path: abs };
+}
+
+// ../../dashboard/lib/open-browser.mjs
+import { spawn, spawnSync } from "child_process";
+import { readFileSync } from "fs";
+import { platform as osPlatform } from "os";
+var OS_DEFAULT_TOKENS = /* @__PURE__ */ new Set(["", "default", "os", "ask"]);
+function isSafePreferredBrowser(value) {
+  if (typeof value !== "string") return false;
+  const s = value.trim();
+  if (!s) return false;
+  if (/[/\\]/.test(s)) return false;
+  if (/[\0-\x1f\x7f]/.test(s)) return false;
+  if (/[$`;&|<>(){}[\]!*?#~"'%^=,+]/.test(s)) return false;
+  if (s.includes(":")) return false;
+  if (/^-/.test(s)) return false;
+  return true;
+}
+function normalizePreferredBrowser(value) {
+  if (value == null) return null;
+  const s = String(value).trim();
+  if (!s || OS_DEFAULT_TOKENS.has(s.toLowerCase())) return null;
+  if (!isSafePreferredBrowser(s)) return null;
+  return s;
+}
+function readPreferredBrowserFromConfig(configPath, fsHooks = {}) {
+  const read = fsHooks.readFileSync ?? readFileSync;
+  try {
+    const raw = read(configPath, "utf8");
+    const data = JSON.parse(raw);
+    if (!data || typeof data !== "object" || Array.isArray(data)) return null;
+    const mc = data.missionControl;
+    if (!mc || typeof mc !== "object" || Array.isArray(mc)) return null;
+    return mc.preferredBrowser ?? null;
+  } catch {
+    return null;
+  }
+}
+
+// src/commands/dashboard.ts
+function readPreferredBrowserFromWorkspace(cwd, readFile22 = readFileSync2) {
+  const resolved = resolveContextConfigPath(path11.resolve(cwd), {
+    existsSync,
+    realpathSync
+  });
+  if (!resolved.ok) return null;
+  const value = readPreferredBrowserFromConfig(resolved.path, { readFileSync: readFile22 });
+  return normalizePreferredBrowser(value);
+}
+function applyDashboardOpenEnv(env, opts) {
+  const next = { ...env };
+  if (opts.noOpen) next.MISSION_CONTROL_NO_OPEN = "1";
+  const flag = opts.browser?.trim();
+  if (flag) {
+    const safe = normalizePreferredBrowser(flag);
+    if (safe) next.MISSION_CONTROL_PREFERRED_BROWSER = safe;
+  } else if (!next.MISSION_CONTROL_PREFERRED_BROWSER && opts.cwd) {
+    const fromConfig = readPreferredBrowserFromWorkspace(opts.cwd);
+    if (fromConfig) next.MISSION_CONTROL_PREFERRED_BROWSER = fromConfig;
+  }
+  return next;
+}
 function bundledDashboardCandidates(filename, moduleUrl = import.meta.url) {
   const here = path11.dirname(fileURLToPath(moduleUrl));
   return [
@@ -2034,7 +2381,7 @@ function bundledDashboardCandidates(filename, moduleUrl = import.meta.url) {
 async function firstExisting(candidates) {
   for (const candidate2 of candidates) {
     try {
-      await access2(candidate2);
+      await access3(candidate2);
       return path11.resolve(candidate2);
     } catch {
     }
@@ -2046,7 +2393,7 @@ async function findDashboardStart(cwd, env = process.env, options = {}) {
   for (; ; ) {
     const candidate2 = path11.join(dir, "dashboard", "start.mjs");
     try {
-      await access2(candidate2);
+      await access3(candidate2);
       return candidate2;
     } catch {
     }
@@ -2059,14 +2406,14 @@ async function findDashboardStart(cwd, env = process.env, options = {}) {
     if (!base || typeof base !== "string" || !base.trim()) continue;
     const candidate2 = path11.join(path11.resolve(base.trim()), "dashboard", "start.mjs");
     try {
-      await access2(candidate2);
+      await access3(candidate2);
       return candidate2;
     } catch {
     }
   }
   const sibling = path11.join(path11.resolve(cwd), "..", "agent-kit", "dashboard", "start.mjs");
   try {
-    await access2(sibling);
+    await access3(sibling);
     return path11.resolve(sibling);
   } catch {
   }
@@ -2076,6 +2423,15 @@ async function findDashboardStart(cwd, env = process.env, options = {}) {
 }
 function resolveDashboardSnapshotRoot(cwd) {
   const abs = path11.resolve(cwd);
+  let dir = abs;
+  for (; ; ) {
+    if (existsSync(path11.join(dir, ".cursor", "agent-kit.json"))) {
+      return dir;
+    }
+    const parent = path11.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
   try {
     const top = execFileSync("git", ["-C", abs, "rev-parse", "--show-toplevel"], {
       encoding: "utf8",
@@ -2087,46 +2443,68 @@ function resolveDashboardSnapshotRoot(cwd) {
   return abs;
 }
 function runStartScript(startPath, env) {
-  return new Promise((resolve, reject) => {
-    const child = spawn(process.execPath, [startPath], {
+  return new Promise((resolve2, reject) => {
+    const child = spawn2(process.execPath, [startPath], {
       cwd: path11.dirname(path11.dirname(startPath)),
       env,
       stdio: "inherit"
     });
     child.on("error", reject);
-    child.on("close", (code) => resolve(code ?? 1));
+    child.on("close", (code) => resolve2(code ?? 1));
   });
 }
 var dashboardCommand = defineCommand4({
   meta: {
     name: "dashboard",
-    description: "Start Mission Control for this workspace (stable per-root port) and open the panel URL."
+    description: "Start Mission Control for this workspace (loopback; opens panel URL)."
   },
   args: {
     cwd: {
       type: "string",
       default: process.cwd(),
-      description: "Workspace to snapshot (git root preferred); also searched upward for dashboard/start.mjs"
+      description: "Workspace to snapshot (nearest .cursor/agent-kit.json, else git root); also searched upward for dashboard/start.mjs"
     },
     "no-open": {
       type: "boolean",
       default: false,
       description: "Do not open a browser; only ensure the server is up and print the URL"
+    },
+    browser: {
+      type: "string",
+      description: "Preferred browser app/binary for this launch (overrides config missionControl.preferredBrowser)"
     }
   },
   async run({ args }) {
     const snapshotRoot = resolveDashboardSnapshotRoot(args.cwd);
     const startPath = await findDashboardStart(args.cwd);
     if (!startPath) {
-      logger.error(
-        "No dashboard/start.mjs found. After a CLI publish that ships dashboard/ (Path C), reinstall @dadado/agent-kit-cli. Or set MISSION_CONTROL_KIT_ROOT / AGENT_KIT_HOME to an agent-kit checkout, place a sibling ../agent-kit tree, or run from that kit tree."
+      logger.error("No dashboard/start.mjs found.");
+      console.error(
+        [
+          "",
+          "The dashboard runtime is not available in this workspace.",
+          "L0 install provides the /dashboard command text but not the panel itself.",
+          "",
+          "Recovery (pick one):",
+          "  1. Upgrade the CLI: npx @dadado/agent-kit-cli@latest dashboard",
+          "     (Path C ships dashboard/ from 4.8.2 onward)",
+          "  2. Set an env var pointing to an agent-kit checkout:",
+          "     export MISSION_CONTROL_KIT_ROOT=/path/to/agent-kit",
+          "     agent-kit dashboard",
+          "  3. Place an agent-kit sibling: ../agent-kit/dashboard/start.mjs",
+          "  4. Run directly from a kit tree: node dashboard/start.mjs",
+          "",
+          "Works in Cursor, VS Code, and any Node.js terminal.",
+          ""
+        ].join("\n")
       );
       process.exitCode = 1;
       return;
     }
-    const env = { ...process.env };
-    env.MISSION_CONTROL_REPO_ROOT = snapshotRoot;
-    if (args["no-open"]) env.MISSION_CONTROL_NO_OPEN = "1";
+    const env = applyDashboardOpenEnv(
+      { ...process.env, MISSION_CONTROL_REPO_ROOT: snapshotRoot },
+      { noOpen: Boolean(args["no-open"]), browser: args.browser, cwd: snapshotRoot }
+    );
     const code = await runStartScript(startPath, env);
     if (code !== 0) process.exitCode = code;
   }
@@ -2138,7 +2516,7 @@ async function findDashboardBroadcastStart(cwd, env = process.env, options = {})
   for (; ; ) {
     const candidate2 = path12.join(dir, "dashboard", "start-broadcast.mjs");
     try {
-      await access3(candidate2);
+      await access4(candidate2);
       return candidate2;
     } catch {
     }
@@ -2151,7 +2529,7 @@ async function findDashboardBroadcastStart(cwd, env = process.env, options = {})
     if (!base || typeof base !== "string" || !base.trim()) continue;
     const candidate2 = path12.join(path12.resolve(base.trim()), "dashboard", "start-broadcast.mjs");
     try {
-      await access3(candidate2);
+      await access4(candidate2);
       return candidate2;
     } catch {
     }
@@ -2164,7 +2542,7 @@ async function findDashboardBroadcastStart(cwd, env = process.env, options = {})
     "start-broadcast.mjs"
   );
   try {
-    await access3(sibling);
+    await access4(sibling);
     return path12.resolve(sibling);
   } catch {
   }
@@ -2173,7 +2551,7 @@ async function findDashboardBroadcastStart(cwd, env = process.env, options = {})
     options.moduleUrl ?? import.meta.url
   )) {
     try {
-      await access3(candidate2);
+      await access4(candidate2);
       return path12.resolve(candidate2);
     } catch {
     }
@@ -2181,14 +2559,14 @@ async function findDashboardBroadcastStart(cwd, env = process.env, options = {})
   return null;
 }
 function runStartScript2(startPath, env) {
-  return new Promise((resolve, reject) => {
-    const child = spawn2(process.execPath, [startPath], {
+  return new Promise((resolve2, reject) => {
+    const child = spawn3(process.execPath, [startPath], {
       cwd: path12.dirname(path12.dirname(startPath)),
       env,
       stdio: "inherit"
     });
     child.on("error", reject);
-    child.on("close", (code) => resolve(code ?? 1));
+    child.on("close", (code) => resolve2(code ?? 1));
   });
 }
 var dashboardBroadcastCommand = defineCommand5({
@@ -2205,7 +2583,11 @@ var dashboardBroadcastCommand = defineCommand5({
     "no-open": {
       type: "boolean",
       default: false,
-      description: "Do not open a browser; only ensure the server is up and print LAN URL + token"
+      description: "Do not open a browser; only ensure the server is up and print Share URL (when masking is on) plus token / LAN lines"
+    },
+    browser: {
+      type: "string",
+      description: "Preferred browser app/binary for this launch (overrides config missionControl.preferredBrowser)"
     }
   },
   async run({ args }) {
@@ -2218,8 +2600,11 @@ var dashboardBroadcastCommand = defineCommand5({
       process.exitCode = 1;
       return;
     }
-    const env = { ...process.env };
-    if (args["no-open"]) env.MISSION_CONTROL_NO_OPEN = "1";
+    const snapshotRoot = resolveDashboardSnapshotRoot(args.cwd);
+    const env = applyDashboardOpenEnv(
+      { ...process.env },
+      { noOpen: Boolean(args["no-open"]), browser: args.browser, cwd: snapshotRoot }
+    );
     const code = await runStartScript2(startPath, env);
     if (code !== 0) process.exitCode = code;
   }
@@ -2229,11 +2614,11 @@ var dashboardBroadcastCommand = defineCommand5({
 import { defineCommand as defineCommand6 } from "citty";
 
 // src/lifecycle/diff.ts
-import { readFile as readFile7 } from "fs/promises";
+import { readFile as readFile8 } from "fs/promises";
 import path13 from "path";
 async function readIfExists(abs) {
   try {
-    return await readFile7(abs, "utf8");
+    return await readFile8(abs, "utf8");
   } catch {
     return null;
   }
@@ -2347,19 +2732,23 @@ var diffCommand = defineCommand6({
       refresh: args.refresh,
       manifest
     });
-    logger.info(`Registry: ${registry.root} (${registry.source})`);
-    const entries = await diffAgainstRegistry(registry.root, args.cwd, manifest);
-    const summary = summarizeDiff(entries);
-    console.log(
-      `Summary: match=${summary.match} drift=${summary.drift} missing-local=${summary["missing-local"]} missing-registry=${summary["missing-registry"]} protected=${summary.protected}`
-    );
-    const rows = args.all ? entries : entries.filter((e) => e.status !== "match");
-    if (rows.length === 0) {
-      logger.success("No drift (matches only).");
-      return;
-    }
-    for (const e of rows) {
-      console.log(`${e.status.padEnd(18)} ${e.path}`);
+    try {
+      logger.info(`Registry: ${registry.root} (${registry.source})`);
+      const entries = await diffAgainstRegistry(registry.root, args.cwd, manifest);
+      const summary = summarizeDiff(entries);
+      console.log(
+        `Summary: match=${summary.match} drift=${summary.drift} missing-local=${summary["missing-local"]} missing-registry=${summary["missing-registry"]} protected=${summary.protected}`
+      );
+      const rows = args.all ? entries : entries.filter((e) => e.status !== "match");
+      if (rows.length === 0) {
+        logger.success("No drift (matches only).");
+        return;
+      }
+      for (const e of rows) {
+        console.log(`${e.status.padEnd(18)} ${e.path}`);
+      }
+    } finally {
+      await registry.unlock?.();
     }
   }
 });
@@ -2370,7 +2759,7 @@ import { defineCommand as defineCommand7 } from "citty";
 
 // src/invariants/hooks-health.ts
 import { execFile as execFile2 } from "child_process";
-import { constants as constants2, access as access4, readFile as readFile8, readdir as readdir3, stat } from "fs/promises";
+import { constants as constants2, access as access5, readFile as readFile9, readdir as readdir3, stat as stat2 } from "fs/promises";
 import path14 from "path";
 import { promisify as promisify2 } from "util";
 var execFileAsync2 = promisify2(execFile2);
@@ -2384,7 +2773,7 @@ var EXPECTED_EVENTS = [
 ];
 async function exists(p) {
   try {
-    await access4(p);
+    await access5(p);
     return true;
   } catch {
     return false;
@@ -2392,7 +2781,7 @@ async function exists(p) {
 }
 async function isExecutable(p) {
   try {
-    await access4(p, constants2.X_OK);
+    await access5(p, constants2.X_OK);
     return true;
   } catch {
     return false;
@@ -2444,7 +2833,7 @@ async function assessGitHooksInstallDrift(rootDir) {
   const gitDir = path14.join(root, ".git");
   if (!await exists(gitDir)) return [];
   try {
-    const st = await stat(gitDir);
+    const st = await stat2(gitDir);
     if (!st.isDirectory()) return [];
   } catch {
     return [];
@@ -2472,7 +2861,7 @@ async function assessGitHooksInstallDrift(rootDir) {
       continue;
     }
     try {
-      const [a, b] = await Promise.all([readFile8(canonical, "utf8"), readFile8(installed, "utf8")]);
+      const [a, b] = await Promise.all([readFile9(canonical, "utf8"), readFile9(installed, "utf8")]);
       if (a !== b) {
         advisories.push(
           `git-hooks drift: \`.git/hooks/${name}\` differs from \`git-hooks/${name}\`. ${installHint}`
@@ -2505,7 +2894,7 @@ async function assessHooksHealth(rootDir) {
   }
   let parsed;
   try {
-    parsed = JSON.parse(await readFile8(hooksJsonAbs, "utf8"));
+    parsed = JSON.parse(await readFile9(hooksJsonAbs, "utf8"));
   } catch {
     return {
       status: "degraded",
@@ -2548,7 +2937,7 @@ async function assessHooksHealth(rootDir) {
       continue;
     }
     try {
-      const st = await stat(abs);
+      const st = await stat2(abs);
       if (!st.isFile()) {
         reasons.push(`adapter path is not a file: \`${rel}\``);
         continue;
@@ -2828,11 +3217,11 @@ function createReadinessReport(scan, options) {
 }
 
 // src/scanner/safe-fixes.ts
-import { readFile as readFile11, writeFile as writeFile4 } from "fs/promises";
+import { readFile as readFile12, writeFile as writeFile5 } from "fs/promises";
 import path22 from "path";
 
 // src/scanner/detect-repository.ts
-import { readFile as readFile9 } from "fs/promises";
+import { readFile as readFile10 } from "fs/promises";
 import path15 from "path";
 var CONTEXT_PATHS = [
   ["README.md", "README"],
@@ -2938,7 +3327,7 @@ var REQUIRED_SECRET_PATTERNS = [
 async function detectSafety(rootDir, trackedFiles) {
   const gitignorePath = path15.join(rootDir, ".gitignore");
   const hasGitignore = await fileExists(gitignorePath);
-  const gitignore = hasGitignore ? await readFile9(gitignorePath, "utf8") : "";
+  const gitignore = hasGitignore ? await readFile10(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)
@@ -2956,7 +3345,7 @@ async function detectSafety(rootDir, trackedFiles) {
   ];
   const guardContents = await Promise.all(
     guardCandidates.map(
-      async (item) => await fileExists(path15.join(rootDir, item)) ? readFile9(path15.join(rootDir, item), "utf8") : ""
+      async (item) => await fileExists(path15.join(rootDir, item)) ? readFile10(path15.join(rootDir, item), "utf8") : ""
     )
   );
   return {
@@ -3163,6 +3552,33 @@ async function detectIde(rootDir) {
 import path18 from "path";
 
 // src/types.ts
+var GIT_PLATFORM_META = {
+  github: {
+    cli: "gh",
+    prTerm: "Pull Request",
+    prCommand: "gh pr create",
+    ciDefault: "github-actions"
+  },
+  gitlab: {
+    cli: "glab",
+    prTerm: "Merge Request",
+    prCommand: "glab mr create",
+    ciDefault: "gitlab-ci"
+  },
+  bitbucket: {
+    cli: "bb",
+    prTerm: "Pull Request",
+    prCommand: "bb pr create",
+    ciDefault: "bitbucket-pipelines"
+  },
+  "azure-devops": {
+    cli: "az repos",
+    prTerm: "Pull Request",
+    prCommand: "az repos pr create",
+    ciDefault: "azure-pipelines"
+  },
+  gitea: { cli: "tea", prTerm: "Pull Request", prCommand: "tea pr create", ciDefault: "none" }
+};
 var CI_PLATFORM_FILES = {
   "github-actions": ".github/workflows",
   "gitlab-ci": ".gitlab-ci.yml",
@@ -3231,7 +3647,7 @@ async function detectInfra(rootDir) {
 }
 
 // src/scanner/detect-services.ts
-import { readFile as readFile10 } from "fs/promises";
+import { readFile as readFile11 } from "fs/promises";
 import path19 from "path";
 async function detectProjectManagement(rootDir) {
   const tools = [];
@@ -3242,7 +3658,7 @@ async function detectProjectManagement(rootDir) {
   for (const configPath of mcpConfigPaths) {
     if (!await fileExists(configPath)) continue;
     try {
-      const raw = await readFile10(configPath, "utf8");
+      const raw = await readFile11(configPath, "utf8");
       const lower = raw.toLowerCase();
       if (lower.includes("clickup")) tools.push("clickup");
       if (lower.includes("jira") || lower.includes("atlassian")) tools.push("jira");
@@ -3625,10 +4041,10 @@ async function executeSafeReadinessFixes(rootDir, options) {
   }
   const gitignoreRelativePath = ".gitignore";
   const gitignorePath = path22.join(beforeScan.rootDir, gitignoreRelativePath);
-  const existingGitignore = await fileExists(gitignorePath) ? await readFile11(gitignorePath, "utf8") : "";
+  const existingGitignore = await fileExists(gitignorePath) ? await readFile12(gitignorePath, "utf8") : "";
   const mergedGitignore = mergeSecretIgnores(existingGitignore);
   const gitignoreChanged = mergedGitignore !== existingGitignore;
-  if (gitignoreChanged && !dryRun) await writeFile4(gitignorePath, mergedGitignore, "utf8");
+  if (gitignoreChanged && !dryRun) await writeFile5(gitignorePath, mergedGitignore, "utf8");
   recordChange(
     changes,
     "merge-secret-ignores",
@@ -3753,7 +4169,7 @@ function printDoctorSummary(result) {
 var doctorCommand = defineCommand7({
   meta: {
     name: "doctor",
-    description: "Diagnose repository readiness and optionally apply safe local fixes."
+    description: "Diagnose repository readiness; optional --fix-safe local repairs."
   },
   args: {
     cwd: {
@@ -4044,7 +4460,7 @@ async function detectCurrentBranch() {
 var guardCommand = defineCommand8({
   meta: {
     name: "guard",
-    description: "Mechanizable deny/annotate guards (shell, prompt). Hooks are thin adapters."
+    description: "Deny/annotate guards (shell, prompt). Hooks are thin adapters."
   },
   subCommands: {
     shell: defineCommand8({
@@ -4107,8 +4523,8 @@ var guardCommand = defineCommand8({
 });
 
 // src/commands/handoff.ts
-import { spawn as spawn3 } from "child_process";
-import { readFile as readFile12, readdir as readdir4, writeFile as writeFile5 } from "fs/promises";
+import { spawn as spawn4 } from "child_process";
+import { readFile as readFile13, readdir as readdir4, writeFile as writeFile6 } from "fs/promises";
 import path25 from "path";
 import { defineCommand as defineCommand9 } from "citty";
 function parsePlanFrontmatter(raw) {
@@ -4129,13 +4545,13 @@ async function findActivePlan(plansDir) {
   if (!await fileExists(plansDir)) return null;
   const files = (await readdir4(plansDir)).filter((f) => f.endsWith(".plan.md")).sort().reverse();
   for (const file of files) {
-    const raw = await readFile12(path25.join(plansDir, file), "utf8");
+    const raw = await readFile13(path25.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 readFile12(path25.join(plansDir, files[0]), "utf8") } : null;
+  return files[0] ? { file: files[0], raw: await readFile13(path25.join(plansDir, files[0]), "utf8") } : null;
 }
 function now() {
   return (/* @__PURE__ */ new Date()).toISOString().replace("T", " ").slice(0, 16);
@@ -4218,19 +4634,19 @@ function printV3Guidance() {
   logger.info("Resume in IDE: /resume, summaries and transcripts.");
 }
 function runCursorHandoff(scriptPath, cwd) {
-  return new Promise((resolve, reject) => {
-    const child = spawn3("sh", [scriptPath, "handoff"], {
+  return new Promise((resolve2, reject) => {
+    const child = spawn4("sh", [scriptPath, "handoff"], {
       cwd,
       stdio: "inherit"
     });
     child.on("error", (err) => reject(err));
-    child.on("close", (code) => resolve(code ?? 1));
+    child.on("close", (code) => resolve2(code ?? 1));
   });
 }
 var handoffCommand = defineCommand9({
   meta: {
     name: "handoff",
-    description: "Write .cursor/HANDOFF.md from the active Cursor plan, or run ./cursor-handoff handoff when no plan exists."
+    description: "Write .cursor/HANDOFF.md from the active plan (or cursor-handoff fallback)."
   },
   args: {
     cwd: {
@@ -4249,7 +4665,7 @@ var handoffCommand = defineCommand9({
       if (fm) {
         await ensureDir(path25.join(args.cwd, ".cursor"));
         const content = buildHandoff(plan.file, fm, profile);
-        await writeFile5(handoffPath, content, "utf8");
+        await writeFile6(handoffPath, content, "utf8");
         logger.success("HANDOFF.md updated: .cursor/HANDOFF.md");
         logger.info(
           `Plan: ${plan.file} (${fm.todos?.filter((t) => t.status === "completed").length}/${fm.todos?.length} completed)`
@@ -4305,8 +4721,8 @@ function buildPreCompactUserMessage(payload = {}) {
 }
 
 // src/hooks/session-start.ts
-import { spawn as spawn4 } from "child_process";
-import { access as access5, readFile as readFile13 } from "fs/promises";
+import { spawn as spawn5 } from "child_process";
+import { access as access6, readFile as readFile14 } from "fs/promises";
 import path26 from "path";
 
 // src/invariants/handoff-schema.ts
@@ -4381,7 +4797,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 readFile13(filePath, "utf8")).split(/\r?\n/);
+    const lines = (await readFile14(filePath, "utf8")).split(/\r?\n/);
     return lines.slice(0, limit).join("\n").trim();
   } catch {
     return "";
@@ -4389,14 +4805,14 @@ async function readTextLimited(filePath, limit = 60) {
 }
 async function readFull(filePath) {
   try {
-    return await readFile13(filePath, "utf8");
+    return await readFile14(filePath, "utf8");
   } catch {
     return "";
   }
 }
 async function fileExists2(p) {
   try {
-    await access5(p);
+    await access6(p);
     return true;
   } catch {
     return false;
@@ -4405,22 +4821,55 @@ async function fileExists2(p) {
 function parseUnprocessedDogfoodItems(readmeText) {
   const items = [];
   let inSection = false;
+  let sectionLevel = 0;
   for (const line of readmeText.split(/\r?\n/)) {
-    if (line.startsWith("### Unprocessed Files")) {
+    const unprocessedMatch = /^(#{2,3})\s+Unprocessed Files\b/.exec(line);
+    if (unprocessedMatch) {
+      const hashes = unprocessedMatch[1];
+      if (!hashes) continue;
       inSection = true;
+      sectionLevel = hashes.length;
       continue;
     }
     if (!inSection) continue;
-    if (line.startsWith("### ")) break;
-    const stripped = line.trim();
-    if (!stripped.startsWith("- ")) continue;
-    const body = stripped.slice(2).trim();
-    const normalized = body.toLowerCase().replace(/[*_]/g, "").trim();
-    if (!normalized || NONE_PLACEHOLDERS.has(normalized)) continue;
+    const headingMatch = /^(#{1,6})\s+/.exec(line);
+    if (headingMatch) {
+      if (/\bProcessed Files\b/.test(line)) break;
+      const hashes = headingMatch[1];
+      if (hashes && hashes.length <= sectionLevel) break;
+      continue;
+    }
+    const body = extractUnprocessedDogfoodLine(line);
+    if (!body) continue;
     items.push(body);
   }
   return items;
 }
+function extractUnprocessedDogfoodLine(line) {
+  const stripped = line.trim();
+  if (!stripped) return null;
+  let raw = null;
+  if (stripped.startsWith("- ")) {
+    raw = stripped.slice(2).trim();
+  } else {
+    const numbered = /^(\d+)[.)]\s+(.+)$/.exec(stripped);
+    if (numbered?.[2]) {
+      raw = numbered[2].trim();
+    } else if (stripped.startsWith("|")) {
+      const parts = stripped.replace(/^\|/, "").replace(/\|$/, "").split("|").map((cell) => cell.trim());
+      if (parts.length === 0) return null;
+      if (parts.every((cell) => /^:?-+:?$/.test(cell))) return null;
+      const first = parts[0] ?? "";
+      const headerish = first.toLowerCase().replace(/[*_`]/g, "").trim();
+      if (/^(note|file|entrada|title|name|item|path)$/.test(headerish)) return null;
+      raw = first.trim();
+    }
+  }
+  if (!raw) return null;
+  const normalized = raw.toLowerCase().replace(/[*_]/g, "").trim();
+  if (!normalized || NONE_PLACEHOLDERS.has(normalized)) return null;
+  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"));
@@ -4465,7 +4914,7 @@ async function readinessSection(root) {
   const snapshotPath = path26.join(root, ".cursor", "context", "readiness.json");
   let data;
   try {
-    data = JSON.parse(await readFile13(snapshotPath, "utf8"));
+    data = JSON.parse(await readFile14(snapshotPath, "utf8"));
   } catch {
     return null;
   }
@@ -4502,7 +4951,7 @@ async function dogfoodInboxSection(root) {
   for (const readme of candidateReadmes) {
     if (!await fileExists2(readme)) continue;
     try {
-      const text = await readFile13(readme, "utf8");
+      const text = await readFile14(readme, "utf8");
       if (parseUnprocessedDogfoodItems(text).length) return DOGFOOD_INBOX_HINT;
     } catch {
     }
@@ -4512,7 +4961,7 @@ async function dogfoodInboxSection(root) {
 async function loadUpdateCheckPrefs(root) {
   try {
     const data = JSON.parse(
-      await readFile13(path26.join(root, ".cursor", "context", "config.json"), "utf8")
+      await readFile14(path26.join(root, ".cursor", "context", "config.json"), "utf8")
     );
     const uc = data.updateCheck;
     if (!uc || typeof uc !== "object" || uc.enabled !== true) {
@@ -4524,8 +4973,8 @@ async function loadUpdateCheckPrefs(root) {
   }
 }
 function runUpdateCheckJson(root) {
-  return new Promise((resolve) => {
-    const child = spawn4(
+  return new Promise((resolve2) => {
+    const child = spawn5(
       process.execPath,
       [
         process.argv[1] ?? "",
@@ -4543,21 +4992,21 @@ function runUpdateCheckJson(root) {
     child.stdout?.on("data", (chunk) => {
       out += chunk.toString("utf8");
     });
-    child.on("error", () => resolve(null));
+    child.on("error", () => resolve2(null));
     child.on("close", () => {
       try {
         const parsed = JSON.parse(out.trim());
-        resolve(parsed && typeof parsed === "object" ? parsed : null);
+        resolve2(parsed && typeof parsed === "object" ? parsed : null);
       } catch {
-        resolve(null);
+        resolve2(null);
       }
     });
   });
 }
 async function updateCheckSection(root) {
   if (await loadUpdateCheckPrefs(root) === null) return null;
-  const result = await new Promise((resolve) => {
-    const child = spawn4(
+  const result = await new Promise((resolve2) => {
+    const child = spawn5(
       "agent-kit",
       ["update", "--check", "--json", "--respect-prefs", "--stamp", "--cwd", root],
       { stdio: ["ignore", "pipe", "ignore"], timeout: 12e3, shell: false }
@@ -4567,17 +5016,17 @@ async function updateCheckSection(root) {
       out += chunk.toString("utf8");
     });
     child.on("error", () => {
-      void runUpdateCheckJson(root).then(resolve);
+      void runUpdateCheckJson(root).then(resolve2);
     });
     child.on("close", (code) => {
       if (code !== 0 && !out.trim()) {
-        void runUpdateCheckJson(root).then(resolve);
+        void runUpdateCheckJson(root).then(resolve2);
         return;
       }
       try {
-        resolve(JSON.parse(out.trim()));
+        resolve2(JSON.parse(out.trim()));
       } catch {
-        void runUpdateCheckJson(root).then(resolve);
+        void runUpdateCheckJson(root).then(resolve2);
       }
     });
   });
@@ -4590,7 +5039,7 @@ async function updateCheckSection(root) {
 async function loadCursorUpdateCheckPrefs(root) {
   try {
     const data = JSON.parse(
-      await readFile13(path26.join(root, ".cursor", "context", "config.json"), "utf8")
+      await readFile14(path26.join(root, ".cursor", "context", "config.json"), "utf8")
     );
     const uc = data.cursorUpdateCheck;
     if (!uc || typeof uc !== "object" || uc.enabled !== true) {
@@ -4602,8 +5051,8 @@ async function loadCursorUpdateCheckPrefs(root) {
   }
 }
 function runCursorAwarenessJson(root) {
-  return new Promise((resolve) => {
-    const child = spawn4(
+  return new Promise((resolve2) => {
+    const child = spawn5(
       process.execPath,
       [
         process.argv[1] ?? "",
@@ -4621,13 +5070,13 @@ function runCursorAwarenessJson(root) {
     child.stdout?.on("data", (chunk) => {
       out += chunk.toString("utf8");
     });
-    child.on("error", () => resolve(null));
+    child.on("error", () => resolve2(null));
     child.on("close", () => {
       try {
         const parsed = JSON.parse(out.trim());
-        resolve(parsed && typeof parsed === "object" ? parsed : null);
+        resolve2(parsed && typeof parsed === "object" ? parsed : null);
       } catch {
-        resolve(null);
+        resolve2(null);
       }
     });
   });
@@ -4642,15 +5091,15 @@ function shouldEmitCursorAwarenessNudge(result) {
 }
 async function cursorAwarenessSection(root, deps = {}) {
   if (await loadCursorUpdateCheckPrefs(root) === null) return null;
-  const spawnFn = deps.spawnFn ?? spawn4;
+  const spawnFn = deps.spawnFn ?? spawn5;
   const runFallback = deps.runFallback ?? runCursorAwarenessJson;
-  const result = await new Promise((resolve) => {
+  const result = await new Promise((resolve2) => {
     let settled = false;
     let fallbackStarted = false;
     const finish = (value) => {
       if (settled) return;
       settled = true;
-      resolve(value);
+      resolve2(value);
     };
     const startFallback = () => {
       if (settled || fallbackStarted) return;
@@ -4739,7 +5188,7 @@ function resolveSessionRoot(payload, cwd = process.cwd()) {
 var hookCommand = defineCommand10({
   meta: {
     name: "hook",
-    description: "Cursor hook adapters (session-start, pre-compact). CLI is SoT; thin hooks shell out here."
+    description: "Cursor hook adapters (session-start, pre-compact). CLI is SoT."
   },
   subCommands: {
     "session-start": defineCommand10({
@@ -4778,13 +5227,216 @@ var hookCommand = defineCommand10({
 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 { 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;
+}
+async function validateProjectRoot(resolved) {
+  const home = path28.resolve(homedir2());
+  if (resolved === "/" || resolved === home) {
+    return { ok: false, reason: `Refused to use ${resolved} as a project root.` };
+  }
+  const hasGit = await fileExists(path28.join(resolved, ".git"));
+  const hasManifest = await fileExists(path28.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.`
+    };
+  }
+  return { ok: true };
+}
+async function confirmProjectRoot(cwd, opts) {
+  const resolved = path28.resolve(cwd);
+  if (opts.forceRoot) {
+    return resolved;
+  }
+  const validation = await validateProjectRoot(resolved);
+  if (!validation.ok) {
+    if (opts.nonInteractive) {
+      throw new RootRefusedError(resolved, validation.reason);
+    }
+    const ok2 = await confirm({
+      message: `${validation.reason} Proceed anyway?`,
+      initialValue: false
+    });
+    if (isCancel(ok2) || !ok2) {
+      throw new RootRefusedError(resolved, validation.reason);
+    }
+    return resolved;
+  }
+  if (opts.nonInteractive) {
+    return resolved;
+  }
+  const ok = await confirm({
+    message: `${opts.command === "install" ? "Install" : "Update"} Agent Kit in: ${resolved}`,
+    initialValue: true
+  });
+  if (isCancel(ok) || !ok) {
+    throw new RootRefusedError(resolved);
+  }
+  return resolved;
+}
+var RootRefusedError = class extends Error {
+  constructor(root, reason) {
+    super(reason ?? `Refused to write into ${root}. Re-run from the correct project directory.`);
+    this.root = root;
+    this.name = "RootRefusedError";
+  }
+  root;
+};
+function classifyInstallError(err) {
+  const msg = err instanceof Error ? err.message : String(err);
+  const code = err?.code;
+  if (code === "EPERM" || code === "EACCES" || /EPERM|EACCES/.test(msg)) {
+    return {
+      kind: "eperm",
+      message: `Permission error: ${msg}`,
+      recovery: [
+        "The npm cache may have ownership drift (root-written files in a user dir).",
+        "Recovery options:",
+        "  1. npx --cache .npm-cache @dadado/agent-kit-cli install",
+        "  2. npm cache clean --force && npx @dadado/agent-kit-cli install",
+        "  3. Use Port B fallback: drag install.md into the Cursor chat"
+      ].join("\n")
+    };
+  }
+  if (/403|Forbidden|unauthorized|E401|ENEEDAUTH/.test(msg)) {
+    return {
+      kind: "registry-auth",
+      message: `Registry access denied: ${msg}`,
+      recovery: [
+        "The npm registry returned 403/401 for the scoped package.",
+        "Recovery options:",
+        "  1. Check npm auth: npm whoami (login if needed: npm login)",
+        "  2. If using a private registry, verify .npmrc scope config",
+        "  3. Use Port B fallback: drag install.md into the Cursor chat"
+      ].join("\n")
+    };
+  }
+  if (/ENOTFOUND|ETIMEDOUT|ECONNREFUSED|ECONNRESET|EAI_AGAIN|fetch failed/.test(msg) || code === "ENOTFOUND" || code === "ETIMEDOUT") {
+    return {
+      kind: "network",
+      message: `Network error: ${msg}`,
+      recovery: [
+        "Could not reach the registry or git remote.",
+        "Recovery options:",
+        "  1. Check network/proxy/VPN settings",
+        "  2. Retry: npx @dadado/agent-kit-cli install",
+        "  3. Use --registry <local-path> if you have a local checkout"
+      ].join("\n")
+    };
+  }
+  return {
+    kind: "unknown",
+    message: msg,
+    recovery: "Unexpected error. Check the message above and retry, or use Port B fallback."
+  };
+}
+
 // src/commands/install.ts
-import path30 from "path";
+import path32 from "path";
 import { defineCommand as defineCommand11 } from "citty";
 
 // src/generator/personalization.ts
-import { readFile as readFile14, writeFile as writeFile6 } from "fs/promises";
-import path28 from "path";
+import { readFile as readFile15, writeFile as writeFile8 } from "fs/promises";
+import path30 from "path";
+
+// src/generator/vscode.ts
+import { writeFile as writeFile7 } from "fs/promises";
+import path29 from "path";
+
+// src/generator/platform.ts
+function gitProviderLabel(profile) {
+  const p = profile.git.provider;
+  if (!p || p === "other") return "Git";
+  const labels = {
+    github: "GitHub",
+    gitlab: "GitLab",
+    bitbucket: "Bitbucket",
+    "azure-devops": "Azure DevOps",
+    gitea: "Gitea"
+  };
+  return labels[p] ?? "Git";
+}
+function prTerminology(profile) {
+  const p = profile.git.provider;
+  if (!p || p === "other") return "PR/MR";
+  return GIT_PLATFORM_META[p]?.prTerm ?? "PR/MR";
+}
+
+// src/generator/vscode.ts
+async function generateVSCodeArtifacts(profile) {
+  const results = [];
+  const vscodeDir = path29.join(profile.rootDir, ".vscode");
+  const githubDir = path29.join(profile.rootDir, ".github");
+  await Promise.all([ensureDir(vscodeDir), ensureDir(githubDir)]);
+  const settingsPath = path29.join(vscodeDir, "settings.json");
+  if (await fileExists(settingsPath)) {
+    results.push({ relativePath: ".vscode/settings.json", status: "skipped-customized" });
+  } else {
+    await writeFile7(
+      settingsPath,
+      `${JSON.stringify(
+        {
+          "editor.formatOnSave": true,
+          "editor.codeActionsOnSave": {
+            "source.fixAll": "explicit"
+          },
+          "files.autoSave": "afterDelay"
+        },
+        null,
+        2
+      )}
+`,
+      "utf8"
+    );
+    results.push({ relativePath: ".vscode/settings.json", status: "applied" });
+  }
+  const provider = gitProviderLabel(profile);
+  const prTerm = prTerminology(profile);
+  const copilotPath = path29.join(githubDir, "copilot-instructions.md");
+  if (await fileExists(copilotPath)) {
+    results.push({ relativePath: ".github/copilot-instructions.md", status: "skipped-customized" });
+  } else {
+    await writeFile7(
+      copilotPath,
+      `# Copilot Instructions
+
+- Keep code changes small and testable.
+- Use Conventional Commits (feat:, fix:, docs:, etc.).
+- Prefer security-safe defaults.
+- Git platform: ${provider}. Always create a ${prTerm} for review.
+`,
+      "utf8"
+    );
+    results.push({ relativePath: ".github/copilot-instructions.md", status: "applied" });
+  }
+  if (profile.ide.plan === "vscode-pro") {
+    const securityPath = path29.join(vscodeDir, "security-review.agent.md");
+    if (await fileExists(securityPath)) {
+      results.push({
+        relativePath: ".vscode/security-review.agent.md",
+        status: "skipped-customized"
+      });
+    } else {
+      await writeFile7(
+        securityPath,
+        "# Security Review Agent\n\nSpecialized mode for security review.\n",
+        "utf8"
+      );
+      results.push({ relativePath: ".vscode/security-review.agent.md", status: "applied" });
+    }
+  }
+  return results;
+}
+
+// src/generator/personalization.ts
 var PERSONALIZATION_CONTRACT_VERSION = 1;
 var CONTEXT_PATH = ".cursor/project-context.md";
 var AGENTS_PATH = "AGENTS.md";
@@ -4928,6 +5580,16 @@ function renderProjectContext(profile) {
   if (profile.infra.ci !== "none" && profile.infra.ciFiles.length > 0) {
     sections.push(`- CI: ${profile.infra.ci}.`);
   }
+  sections.push(
+    "",
+    "## Relevant skills",
+    "",
+    "Installed and project-owned skills for this repository. Prefer `.cursor/agent-kit.json` `skills[]` as the install index; project-only domain skills may live under `.cursor/skills/domain/`.",
+    "",
+    "| Skill / path | Role | Evidence |",
+    "|--------------|------|----------|",
+    "| (none yet) | Add rows when `/agent-kit-onboard` scaffolds domain skills or personalization installs packs | \u2014 |"
+  );
   if (profile.context.sources.length > 0) {
     sections.push("", "## Sources", ...profile.context.sources.map((item) => `- ${item.value}`));
   }
@@ -4935,7 +5597,7 @@ function renderProjectContext(profile) {
 `;
 }
 async function createOwnedFile(rootDir, relativePath, content, evidence) {
-  const target = path28.join(rootDir, relativePath);
+  const target = path30.join(rootDir, relativePath);
   if (await fileExists(target)) {
     return {
       kind: "file",
@@ -4945,8 +5607,8 @@ async function createOwnedFile(rootDir, relativePath, content, evidence) {
       evidence
     };
   }
-  await ensureDir(path28.dirname(target));
-  await writeFile6(target, content, "utf8");
+  await ensureDir(path30.dirname(target));
+  await writeFile8(target, content, "utf8");
   return {
     kind: "file",
     id: relativePath,
@@ -4962,7 +5624,7 @@ async function packTargets(registryRoot, packId) {
 async function existingTargets(projectRoot, targets) {
   const checks = await Promise.all(
     targets.map(
-      async (target) => await fileExists(path28.join(projectRoot, target)) ? target : null
+      async (target) => await fileExists(path30.join(projectRoot, target)) ? target : null
     )
   );
   return checks.filter((target) => target !== null);
@@ -4984,14 +5646,14 @@ async function applyPersonalization(input) {
         componentResults.push({ ...item, status: "unavailable" });
         continue;
       }
-      const target = path28.posix.join(
+      const target = path30.posix.join(
         ".cursor",
         "skills",
         skill.path.includes("/core/") ? "core" : "community",
         skill.id,
         "SKILL.md"
       );
-      if (await fileExists(path28.join(input.rootDir, target))) {
+      if (await fileExists(path30.join(input.rootDir, target))) {
         componentResults.push({ ...item, status: "skipped-customized", path: target });
         protectedPaths.add(target);
         continue;
@@ -5039,6 +5701,49 @@ async function applyPersonalization(input) {
   ]);
   protectedPaths.add(CONTEXT_PATH);
   protectedPaths.add(AGENTS_PATH);
+  const ideDetection = await detectIde(input.rootDir);
+  if (ideDetection.ide === "vscode" || ideDetection.ide === "other") {
+    const git = {
+      providerKind: input.profile.git.providerKind ?? "unknown",
+      providerConfidence: input.profile.git.providerConfidence ?? "low",
+      providerEvidence: input.profile.git.providerEvidence ?? [],
+      remotes: input.profile.git.remotes ?? [],
+      mode: input.profile.git.mode ?? "none",
+      workflow: input.profile.git.workflow ?? "unknown",
+      isDirty: input.profile.git.isDirty ?? false,
+      hasLocalStaging: input.profile.git.hasLocalStaging ?? false,
+      hasRemoteStaging: input.profile.git.hasRemoteStaging ?? false,
+      provider: input.profile.git.provider,
+      remoteUrl: input.profile.git.remoteUrl,
+      remoteName: input.profile.git.remoteName,
+      currentBranch: input.profile.git.currentBranch,
+      defaultBranch: input.profile.git.defaultBranch
+    };
+    const projectProfile = {
+      rootDir: input.rootDir,
+      stack: input.profile.stack,
+      git,
+      ide: ideDetection,
+      infra: input.profile.infra,
+      services: input.profile.services,
+      installHooks: false,
+      selectedCoreComponents: []
+    };
+    const vscodeResults = await generateVSCodeArtifacts(projectProfile);
+    const ideEvidence = [
+      { source: "derived", value: `ide:${ideDetection.ide}` }
+    ];
+    for (const artifact of vscodeResults) {
+      protectedPaths.add(artifact.relativePath);
+      componentResults.push({
+        kind: "file",
+        id: artifact.relativePath,
+        path: artifact.relativePath,
+        status: artifact.status,
+        evidence: ideEvidence
+      });
+    }
+  }
   const result = {
     contractVersion: PERSONALIZATION_CONTRACT_VERSION,
     generatorVersion: input.generatorVersion,
@@ -5046,7 +5751,7 @@ async function applyPersonalization(input) {
     items: [...fileResults, ...componentResults],
     protectedPaths: [...protectedPaths].sort()
   };
-  await writeJson(path28.join(input.rootDir, RESULT_PATH), result);
+  await writeJson(path30.join(input.rootDir, RESULT_PATH), result);
   return {
     result,
     manifest: {
@@ -5064,26 +5769,26 @@ async function applyPersonalization(input) {
   };
 }
 async function readRepositoryProfile(rootDir) {
-  const target = path28.join(rootDir, ".cursor/agent-kit.config.json");
+  const target = path30.join(rootDir, ".cursor/agent-kit.config.json");
   if (!await fileExists(target)) return null;
-  return JSON.parse(await readFile14(target, "utf8"));
+  return JSON.parse(await readFile15(target, "utf8"));
 }
 
 // src/lifecycle/onboard-migration.ts
 import { createHash as createHash4 } from "crypto";
-import { readFile as readFile15, unlink } from "fs/promises";
-import path29 from "path";
+import { readFile as readFile16, unlink } from "fs/promises";
+import path31 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 = path29.join(projectRoot, LEGACY_ONBOARD_PATH);
+  const legacyPath = path31.join(projectRoot, LEGACY_ONBOARD_PATH);
   if (!await fileExists(legacyPath)) return "absent";
-  const namespacedPath = path29.join(projectRoot, NAMESPACED_ONBOARD_PATH);
+  const namespacedPath = path31.join(projectRoot, NAMESPACED_ONBOARD_PATH);
   if (!await fileExists(namespacedPath)) return "preserved-customized";
-  const content = await readFile15(legacyPath);
+  const content = await readFile16(legacyPath);
   const hash = createHash4("sha256").update(content).digest("hex");
   if (!managedHashes.has(hash)) return "preserved-customized";
   await unlink(legacyPath);
@@ -5156,7 +5861,7 @@ function printReadinessNarrative(result) {
   );
 }
 async function performInstall(options) {
-  const projectRoot = path30.resolve(options.cwd);
+  const projectRoot = path32.resolve(options.cwd);
   const packs = parsePackList(options.pack);
   const existing = await loadAgentKitManifest(projectRoot);
   const registry = await resolveRegistryFromCli({
@@ -5167,53 +5872,57 @@ async function performInstall(options) {
     refresh: options.refresh,
     manifest: existing
   });
-  const draft = buildManifest({
-    version: KIT_VERSION,
-    profile: options.profile ?? existing?.profile ?? "default",
-    packs: packs.length > 0 ? packs : existing?.packs,
-    skills: existing?.skills,
-    protected: existing?.protected,
-    personalization: existing?.personalization,
-    registryUrl: registry.url ?? existing?.registry?.url,
-    registryRef: registry.ref ?? existing?.registry?.ref
-  });
-  const stats = (draft.packs?.length ?? 0) > 0 || (draft.skills?.length ?? 0) > 0 ? await syncFromManifest(registry.root, projectRoot, draft) : await installL0(registry.root, projectRoot, resolveProtectedGlobs(draft));
-  const manifestPath = await saveManifest(projectRoot, draft);
-  const readinessExecution = await executeSafeReadinessFixes(projectRoot, {
-    generatorVersion: KIT_VERSION
-  });
-  let readiness = readinessExecution.after;
-  const profile = await readRepositoryProfile(projectRoot);
-  if (profile) {
-    const registryIndex = await loadRegistry(registry.root);
-    const personalization = await applyPersonalization({
-      rootDir: projectRoot,
-      registryRoot: registry.root,
-      profile,
-      report: readinessExecution.after,
-      registry: registryIndex,
-      manifest: draft,
-      generatorVersion: KIT_VERSION
+  try {
+    const draft = buildManifest({
+      version: KIT_VERSION,
+      profile: options.profile ?? existing?.profile ?? "default",
+      packs: packs.length > 0 ? packs : existing?.packs,
+      skills: existing?.skills,
+      protected: existing?.protected,
+      personalization: existing?.personalization,
+      registryUrl: registry.url ?? existing?.registry?.url,
+      registryRef: registry.ref ?? existing?.registry?.ref
     });
-    await saveManifest(projectRoot, personalization.manifest);
-    readiness = createReadinessReport(await runScanner(projectRoot), {
+    const stats = (draft.packs?.length ?? 0) > 0 || (draft.skills?.length ?? 0) > 0 ? await syncFromManifest(registry.root, projectRoot, draft) : await installL0(registry.root, projectRoot, resolveProtectedGlobs(draft));
+    const manifestPath = await saveManifest(projectRoot, draft);
+    const readinessExecution = await executeSafeReadinessFixes(projectRoot, {
       generatorVersion: KIT_VERSION
     });
-    readiness.appliedSafeFixes = readinessExecution.after.appliedSafeFixes;
+    let readiness = readinessExecution.after;
+    const profile = await readRepositoryProfile(projectRoot);
+    if (profile) {
+      const registryIndex = await loadRegistry(registry.root);
+      const personalization = await applyPersonalization({
+        rootDir: projectRoot,
+        registryRoot: registry.root,
+        profile,
+        report: readinessExecution.after,
+        registry: registryIndex,
+        manifest: draft,
+        generatorVersion: KIT_VERSION
+      });
+      await saveManifest(projectRoot, personalization.manifest);
+      readiness = createReadinessReport(await runScanner(projectRoot), {
+        generatorVersion: KIT_VERSION
+      });
+      readiness.appliedSafeFixes = readinessExecution.after.appliedSafeFixes;
+    }
+    await writeReadinessSnapshot(projectRoot, readiness);
+    return {
+      projectRoot,
+      manifestPath,
+      stats,
+      readiness,
+      safeChanges: readinessExecution.changes
+    };
+  } finally {
+    await registry.unlock?.();
   }
-  await writeReadinessSnapshot(projectRoot, readiness);
-  return {
-    projectRoot,
-    manifestPath,
-    stats,
-    readiness,
-    safeChanges: readinessExecution.changes
-  };
 }
 var installCommand = defineCommand11({
   meta: {
     name: "install",
-    description: "Bootstrap L0 (+ optional packs) from the registry and write agent-kit.json."
+    description: "Bootstrap L0 (+ optional packs) and write .cursor/agent-kit.json."
   },
   args: {
     profile: {
@@ -5225,6 +5934,17 @@ var installCommand = defineCommand11({
       type: "string",
       description: `Comma-separated L1 pack ids (e.g. cybersec,devops). Known: ${DOMAIN_PACK_IDS.join(", ")}`
     },
+    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
+    },
     cwd: {
       type: "string",
       default: process.cwd()
@@ -5232,7 +5952,25 @@ var installCommand = defineCommand11({
     ...REGISTRY_CLI_ARGS
   },
   async run({ args }) {
-    const projectRoot = path30.resolve(args.cwd);
+    const nonInteractive = args.yes || isNonInteractive();
+    if (nonInteractive) {
+      logger.info("Non-interactive mode: skipping prompts, using defaults.");
+    }
+    let projectRoot;
+    try {
+      projectRoot = await confirmProjectRoot(args.cwd, {
+        nonInteractive,
+        command: "install",
+        forceRoot: args["force-root"]
+      });
+    } catch (err) {
+      if (err instanceof RootRefusedError) {
+        logger.error(err.message);
+        process.exitCode = 1;
+        return;
+      }
+      throw err;
+    }
     logger.info(`Installing into: ${projectRoot}`);
     const packs = parsePackList(args.pack);
     for (const id of packs) {
@@ -5240,19 +5978,28 @@ var installCommand = defineCommand11({
         logger.warn(`Pack '${id}' is not in the known L1 list; will still try registry.`);
       }
     }
-    const result = await performInstall({
-      cwd: projectRoot,
-      profile: args.profile,
-      pack: args.pack,
-      registry: args.registry,
-      url: args.url,
-      ref: args.ref,
-      refresh: args.refresh
-    });
-    logApplyStats(result.stats);
-    logger.success(`Manifest written: ${result.manifestPath}`);
-    logger.success("Readiness snapshot written: .cursor/context/readiness.json");
-    printReadinessNarrative(result);
+    try {
+      const result = await performInstall({
+        cwd: projectRoot,
+        profile: args.profile,
+        pack: args.pack,
+        registry: args.registry,
+        url: args.url,
+        ref: args.ref,
+        refresh: args.refresh
+      });
+      logApplyStats(result.stats);
+      logger.success(`Manifest written: ${result.manifestPath}`);
+      logger.success("Readiness snapshot written: .cursor/context/readiness.json");
+      printReadinessNarrative(result);
+    } catch (err) {
+      const hint = classifyInstallError(err);
+      logger.error(hint.message);
+      console.error(`
+${hint.recovery}
+`);
+      process.exit(1);
+    }
   }
 });
 
@@ -5263,7 +6010,7 @@ async function runInitCompatibility(cwd, installer = performInstall) {
 var initCommand = defineCommand12({
   meta: {
     name: "init",
-    description: "Guided compatibility entry point for install and repository readiness."
+    description: "Guided setup entry (compat path to install + readiness)."
   },
   args: {
     cwd: {
@@ -5273,25 +6020,42 @@ var initCommand = defineCommand12({
     }
   },
   async run({ args }) {
-    intro(`agent-kit v${KIT_VERSION}`);
+    const nonInteractive = 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.");
-    const result = await runInitCompatibility(args.cwd);
-    const pending = result.readiness.pendingActions.length;
-    logger.success(`L0 and readiness prepared in ${result.projectRoot}`);
-    outro(
-      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."
-    );
+    try {
+      const result = await runInitCompatibility(args.cwd);
+      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.";
+      if (!nonInteractive) {
+        outro(nextStep);
+      } else {
+        logger.info(nextStep);
+      }
+    } catch (err) {
+      const hint = classifyInstallError(err);
+      logger.error(hint.message);
+      console.error(`
+${hint.recovery}
+`);
+      process.exit(1);
+    }
   }
 });
 
 // src/commands/monitors.ts
-import path32 from "path";
+import path34 from "path";
 import { defineCommand as defineCommand13 } from "citty";
 
 // src/invariants/monitors-untriaged.ts
 import { execFile as execFile5 } from "child_process";
-import { readFile as readFile16, readdir as readdir5, stat as stat2 } from "fs/promises";
-import path31 from "path";
+import { readFile as readFile17, readdir as readdir5, stat as stat3 } from "fs/promises";
+import path33 from "path";
 import { promisify as promisify5 } from "util";
 
 // src/invariants/triage-heading.ts
@@ -5332,7 +6096,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 = path31.basename(file);
+      const base = path33.basename(file);
       if (base.startsWith("plan-monitor-") && base.endsWith(".md")) {
         names.add(base);
       }
@@ -5355,15 +6119,15 @@ function monitorSlugFromName(fileName) {
   return fileName.replace(/^plan-monitor-/, "").replace(/\.md$/, "").toLowerCase();
 }
 async function selectUntriagedMonitors(rootDir) {
-  const root = path31.resolve(rootDir);
-  const memoryDir = path31.join(root, ".cursor", "memory");
+  const root = path33.resolve(rootDir);
+  const memoryDir = path33.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 = path31.join(memoryDir, name);
+    const abs = path33.join(memoryDir, name);
     try {
-      const [content, st] = await Promise.all([readFile16(abs, "utf8"), stat2(abs)]);
+      const [content, st] = await Promise.all([readFile17(abs, "utf8"), stat3(abs)]);
       byName.set(name, { content, mtimeMs: st.mtimeMs });
     } catch {
     }
@@ -5376,7 +6140,7 @@ async function selectUntriagedMonitors(rootDir) {
   const gitFreshSet = [...gitFresh].filter(untriaged).sort();
   let handoff = "";
   try {
-    handoff = await readFile16(path31.join(root, ".cursor", "HANDOFF.md"), "utf8");
+    handoff = await readFile17(path33.join(root, ".cursor", "HANDOFF.md"), "utf8");
   } catch {
     handoff = "";
   }
@@ -5396,8 +6160,8 @@ async function selectUntriagedMonitors(rootDir) {
     const row = byName.get(name);
     if (!row) continue;
     entries.push({
-      path: path31.join(memoryDir, name),
-      relativePath: path31.relative(root, path31.join(memoryDir, name)).split(path31.sep).join("/"),
+      path: path33.join(memoryDir, name),
+      relativePath: path33.relative(root, path33.join(memoryDir, name)).split(path33.sep).join("/"),
       mtimeMs: row.mtimeMs,
       hasTriageHeading: false,
       hasOpenGaps: hasOpenGaps(row.content),
@@ -5419,7 +6183,7 @@ async function selectUntriagedMonitors(rootDir) {
 var monitorsCommand = defineCommand13({
   meta: {
     name: "monitors",
-    description: "Plan-monitor selection helpers (untriaged SoT for /plan-review-triage)"
+    description: "Select untriaged plan monitors (--untriaged; SoT for chat triage)."
   },
   args: {
     cwd: {
@@ -5443,7 +6207,7 @@ var monitorsCommand = defineCommand13({
       process.exitCode = 2;
       return;
     }
-    const result = await selectUntriagedMonitors(path32.resolve(args.cwd));
+    const result = await selectUntriagedMonitors(path34.resolve(args.cwd));
     if (args.json) {
       console.log(JSON.stringify(result, null, 2));
       return;
@@ -5459,11 +6223,11 @@ var monitorsCommand = defineCommand13({
 });
 
 // src/commands/run-plan.ts
-import path37 from "path";
+import path39 from "path";
 import { defineCommand as defineCommand14 } from "citty";
 
 // src/plan-loop/backends.ts
-import { execFileSync as execFileSync2, spawn as spawn5 } from "child_process";
+import { execFileSync as execFileSync2, spawn as spawn6 } from "child_process";
 import { createWriteStream } from "fs";
 async function which(bin) {
   try {
@@ -5474,9 +6238,9 @@ async function which(bin) {
   }
 }
 function spawnLogged(command, args, logPath) {
-  return new Promise((resolve, reject) => {
+  return new Promise((resolve2, reject) => {
     const out = createWriteStream(logPath, { flags: "w" });
-    const child = spawn5(command, args, {
+    const child = spawn6(command, args, {
       stdio: ["ignore", "pipe", "pipe"]
     });
     const onData = (chunk) => {
@@ -5490,7 +6254,7 @@ function spawnLogged(command, args, logPath) {
       reject(err);
     });
     child.on("close", (code) => {
-      out.end(() => resolve({ exitCode: code ?? 1 }));
+      out.end(() => resolve2({ exitCode: code ?? 1 }));
     });
   });
 }
@@ -5544,14 +6308,14 @@ function listBackendIds() {
 }
 
 // src/plan-loop/run-loop.ts
-import { mkdir as mkdir5, readFile as readFile19, rm, unlink as unlink2 } from "fs/promises";
-import path36 from "path";
+import { mkdir as mkdir6, readFile as readFile20, rm as rm2, unlink as unlink2 } from "fs/promises";
+import path38 from "path";
 
 // src/plan-loop/external-review.ts
-import { spawn as spawn6 } from "child_process";
-import path33 from "path";
-var CANONICAL_REL = path33.join(".cursor", "scripts", "plan-external-review.sh");
-var FALLBACK_REL = path33.join("scripts", "plan-external-review.sh");
+import { spawn as spawn7 } from "child_process";
+import path35 from "path";
+var CANONICAL_REL = path35.join(".cursor", "scripts", "plan-external-review.sh");
+var FALLBACK_REL = path35.join("scripts", "plan-external-review.sh");
 function isPlanExhaustedReason(reason) {
   const r = reason.trim().toLowerCase();
   if (!r) return false;
@@ -5569,12 +6333,12 @@ function shouldArmExternalPlanReview(input) {
   return false;
 }
 async function armExternalPlanReview(root, options = {}) {
-  const spawnFn = options.spawnFn ?? spawn6;
+  const spawnFn = options.spawnFn ?? spawn7;
   const existsFn = options.existsFn ?? fileExists;
   const log = options.log ?? ((line) => console.log(line));
   const force = options.force === true;
-  const canonicalPath = path33.join(root, CANONICAL_REL);
-  const fallbackPath = path33.join(root, FALLBACK_REL);
+  const canonicalPath = path35.join(root, CANONICAL_REL);
+  const fallbackPath = path35.join(root, FALLBACK_REL);
   let scriptPath = null;
   let scriptRel = CANONICAL_REL;
   if (await existsFn(canonicalPath)) {
@@ -5592,7 +6356,7 @@ async function armExternalPlanReview(root, options = {}) {
   }
   log("Plan exhausted: arming optional external plan review (opt-in handled by script)...");
   const args = force ? [scriptPath, "--force", "--print"] : [scriptPath, "--print"];
-  return new Promise((resolve) => {
+  return new Promise((resolve2) => {
     const child = spawnFn("bash", args, {
       cwd: root,
       env: { ...process.env, AGENT_KIT_HEADLESS: "1" }
@@ -5613,7 +6377,7 @@ async function armExternalPlanReview(root, options = {}) {
       log(
         `tip: external plan review launcher failed (${err.message}). Manual: ${scriptRel} or /plan-external-review`
       );
-      resolve({ invoked: true, exitCode: null, output });
+      resolve2({ invoked: true, exitCode: null, output });
     });
     child.on("close", (code) => {
       if (code !== 0 && code !== null) {
@@ -5621,13 +6385,13 @@ async function armExternalPlanReview(root, options = {}) {
           `tip: external plan review exited ${code} (ignored; does not fail the loop). Manual: ${scriptRel} or /plan-external-review`
         );
       }
-      resolve({ invoked: true, exitCode: code, output });
+      resolve2({ invoked: true, exitCode: code, output });
     });
   });
 }
 
 // src/plan-loop/persona-banners.ts
-import path34 from "path";
+import path36 from "path";
 import {
   blue,
   cyan as cyan2,
@@ -5663,7 +6427,7 @@ function resolveColor(name, fallback) {
 async function resolveCliPersonaId(root) {
   try {
     const cfg = await readJson(
-      path34.join(root, ".cursor", "context", "config.json")
+      path36.join(root, ".cursor", "context", "config.json")
     );
     const modes = cfg?.agentPersona?.modes ?? cfg?.workspaceSkin?.modes;
     const id = modes?.[CLI_RUN_PLAN_MODE];
@@ -5674,7 +6438,7 @@ async function resolveCliPersonaId(root) {
 }
 async function loadPersonaPack(root, personaId) {
   try {
-    const personaPath = path34.join(root, "registry", "personas", "core", personaId, "persona.json");
+    const personaPath = path36.join(root, "registry", "personas", "core", personaId, "persona.json");
     const pack = await readJson(personaPath);
     if (!pack || typeof pack.id !== "string") return null;
     return pack;
@@ -5723,8 +6487,8 @@ function createPersonaBannerPrinter(persona) {
 }
 
 // src/plan-loop/plan-state.ts
-import { readFile as readFile17, readdir as readdir6 } from "fs/promises";
-import path35 from "path";
+import { readFile as readFile18, readdir as readdir6 } from "fs/promises";
+import path37 from "path";
 function countPendingTodos(raw) {
   const lines = raw.split(/\r?\n/);
   let inFront = 0;
@@ -5752,14 +6516,14 @@ function countPendingTodos(raw) {
 async function findActivePlanFile(plansDir) {
   if (!await fileExists(plansDir)) return null;
   const files = (await readdir6(plansDir)).filter((f) => f.endsWith(".plan.md")).sort();
-  return files[0] ? path35.join(plansDir, files[0]) : null;
+  return files[0] ? path37.join(plansDir, files[0]) : null;
 }
 async function readPlan(planPath) {
-  return readFile17(planPath, "utf8");
+  return readFile18(planPath, "utf8");
 }
 
 // src/plan-loop/sentinel.ts
-import { readFile as readFile18 } from "fs/promises";
+import { readFile as readFile19 } from "fs/promises";
 var SENTINEL_RE = /LOOP_TICK_RESULT:\s*(continue|stop(?:\s*[—\-].*)?)/i;
 function takeFromText(text) {
   if (!text) return null;
@@ -5806,7 +6570,7 @@ function parseSentinelFromLog(content) {
 }
 async function parseSentinelFromLogFile(logPath) {
   try {
-    const content = await readFile18(logPath, "utf8");
+    const content = await readFile19(logPath, "utf8");
     return parseSentinelFromLog(content);
   } catch {
     return { kind: "missing" };
@@ -5829,16 +6593,16 @@ function sleep(ms) {
   return new Promise((r) => setTimeout(r, ms));
 }
 async function runPlanLoop(opts) {
-  const plansDir = path36.join(opts.root, ".cursor", "plans");
-  const stopFile = path36.join(opts.root, ".cursor", "loop.stop");
-  const logDir = path36.join(opts.root, ".cursor", "loop-logs");
+  const plansDir = path38.join(opts.root, ".cursor", "plans");
+  const stopFile = path38.join(opts.root, ".cursor", "loop.stop");
+  const logDir = path38.join(opts.root, ".cursor", "loop-logs");
   const planPath = await findActivePlanFile(plansDir);
   if (!planPath) {
     logger.error("No active plan in .cursor/plans/");
     return 1;
   }
   const pending = async () => countPendingTodos(await readPlan(planPath));
-  await mkdir5(logDir, { recursive: true });
+  await mkdir6(logDir, { recursive: true });
   try {
     await unlink2(stopFile);
   } catch {
@@ -5852,7 +6616,7 @@ async function runPlanLoop(opts) {
   try {
     const persona = await loadCliRunPlanPersona(opts.root);
     const banners = createPersonaBannerPrinter(persona);
-    console.log(`Active plan: ${path36.basename(planPath)}`);
+    console.log(`Active plan: ${path38.basename(planPath)}`);
     console.log(`Pending to-dos: ${await pending()} | max ticks: ${opts.maxTicks}`);
     console.log(`Backend: ${opts.backend.id}`);
     if (persona) {
@@ -5884,7 +6648,7 @@ async function runPlanLoop(opts) {
         if (banners) banners.stop(msg);
         else console.log(msg);
         try {
-          await rm(stopFile, { force: true });
+          await rm2(stopFile, { force: true });
         } catch {
         }
         break;
@@ -5895,8 +6659,8 @@ async function runPlanLoop(opts) {
         planExhausted = true;
         break;
       }
-      const logPath = path36.join(logDir, `tick-${stamp()}.log`);
-      const relLog = path36.relative(opts.root, logPath);
+      const logPath = path38.join(logDir, `tick-${stamp()}.log`);
+      const relLog = path38.relative(opts.root, logPath);
       console.log("");
       const tickLine = `=== tick ${tick}/${opts.maxTicks} - pending: ${before} - log: ${relLog} ===`;
       if (banners) banners.tickStart(tickLine);
@@ -5915,7 +6679,7 @@ async function runPlanLoop(opts) {
         return 1;
       }
       try {
-        const logText = await readFile19(logPath, "utf8");
+        const logText = await readFile20(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);
@@ -5972,7 +6736,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 ${path36.relative(opts.root, logDir)}/`
+      `Loop finished after ${tick} tick(s). Pending now: ${pendingNow}. Logs in ${path38.relative(opts.root, logDir)}/`
     );
     if (planExhausted || shouldArmExternalPlanReview({ pending: pendingNow, stopReason })) {
       await armExternalPlanReview(opts.root);
@@ -5987,7 +6751,7 @@ async function runPlanLoop(opts) {
 var runPlanCommand = defineCommand14({
   meta: {
     name: "run-plan",
-    description: "Headless continuous plan runner: one fresh agent per tick (LOOP_TICK_RESULT contract). Never git-prod."
+    description: "Headless continuous plan runner (one fresh agent per tick). Never git-prod."
   },
   args: {
     cwd: {
@@ -6043,7 +6807,7 @@ var runPlanCommand = defineCommand14({
       return;
     }
     const code = await runPlanLoop({
-      root: path37.resolve(args.cwd),
+      root: path39.resolve(args.cwd),
       maxTicks,
       sleepSeconds,
       model: args.model ? String(args.model) : void 0,
@@ -6059,7 +6823,7 @@ import { defineCommand as defineCommand15 } from "citty";
 var scanCommand = defineCommand15({
   meta: {
     name: "scan",
-    description: "Scan the current repository and print detected profile."
+    description: "Scan the repository and print the detected profile."
   },
   args: {
     cwd: {
@@ -6077,7 +6841,7 @@ var scanCommand = defineCommand15({
 });
 
 // src/commands/status.ts
-import path38 from "path";
+import path40 from "path";
 import { defineCommand as defineCommand16 } from "citty";
 function profileStatus(profile) {
   if (!profile) return { origin: "none", evidence: [], profile: null };
@@ -6094,7 +6858,7 @@ function profileStatus(profile) {
 var statusCommand = defineCommand16({
   meta: {
     name: "status",
-    description: "Show Agent Kit distribution status (manifest + optional wizard profile)."
+    description: "Show installed kit version, manifest, and optional profile."
   },
   args: {
     cwd: {
@@ -6108,11 +6872,11 @@ var statusCommand = defineCommand16({
     }
   },
   async run({ args }) {
-    const rootDir = path38.resolve(args.cwd);
+    const rootDir = path40.resolve(args.cwd);
     const [manifest, rawProfile, scan] = await Promise.all([
       loadAgentKitManifest(rootDir),
       readJson(
-        path38.join(rootDir, ".cursor", "agent-kit.config.json")
+        path40.join(rootDir, ".cursor", "agent-kit.config.json")
       ),
       runScanner(rootDir)
     ]);
@@ -6171,7 +6935,7 @@ import { defineCommand as defineCommand17 } from "citty";
 
 // src/lifecycle/check-updates.ts
 import { execFile as execFile6 } from "child_process";
-import path39 from "path";
+import path41 from "path";
 import { promisify as promisify6 } from "util";
 var execFileAsync5 = promisify6(execFile6);
 var SEMVER_CORE = /^v?(\d+)\.(\d+)\.(\d+)(?:[-+].*)?$/i;
@@ -6262,11 +7026,11 @@ function intervalElapsed2(lastCheckedAt, intervalDays) {
   return Date.now() - last >= ms;
 }
 async function loadContextConfig2(cwd) {
-  const configPath = path39.join(cwd, ".cursor", "context", "config.json");
+  const configPath = path41.join(cwd, ".cursor", "context", "config.json");
   return readJson(configPath);
 }
 async function stampLastCheckedAt(cwd) {
-  const configPath = path39.join(cwd, ".cursor", "context", "config.json");
+  const configPath = path41.join(cwd, ".cursor", "context", "config.json");
   const existing = await loadContextConfig2(cwd) ?? {};
   const prev = existing.updateCheck && typeof existing.updateCheck === "object" ? { ...existing.updateCheck } : {};
   existing.updateCheck = {
@@ -6410,7 +7174,7 @@ async function checkForUpdates(cwd, options = {}) {
 var updateCommand = defineCommand17({
   meta: {
     name: "update",
-    description: "Re-apply L0/packs/skills from the registry; never overwrites L3 protected paths. Use --check for notify-only."
+    description: "Re-apply L0/packs/skills from the registry (never overwrites L3). --check = notify-only."
   },
   args: {
     cwd: {
@@ -6442,6 +7206,17 @@ var updateCommand = defineCommand17({
       description: "Seed the managed-hash ledger from current local overlay files before applying (factory/dogfood only; consumers should not use this)",
       default: false
     },
+    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
+    },
     ...REGISTRY_CLI_ARGS
   },
   async run({ args }) {
@@ -6463,48 +7238,68 @@ var updateCommand = defineCommand17({
       if (result.status === "error") process.exitCode = 2;
       return;
     }
-    const existing = await loadAgentKitManifest(args.cwd);
+    const nonInteractive = args.yes || isNonInteractive();
+    let projectRoot;
+    try {
+      projectRoot = await confirmProjectRoot(args.cwd, {
+        nonInteractive,
+        command: "update",
+        forceRoot: args["force-root"]
+      });
+    } catch (err) {
+      if (err instanceof RootRefusedError) {
+        logger.error(err.message);
+        process.exitCode = 1;
+        return;
+      }
+      throw err;
+    }
+    const existing = await loadAgentKitManifest(projectRoot);
     if (!existing) {
       logger.warn("No .cursor/agent-kit.json \u2014 run agent-kit install first.");
       return;
     }
     const registry = await resolveRegistryFromCli({
-      cwd: args.cwd,
+      cwd: projectRoot,
       registry: args.registry,
       url: args.url,
       ref: args.ref,
       refresh: args.refresh,
       manifest: existing
     });
-    logger.info(`Registry: ${registry.root} (${registry.source})`);
-    const next = buildManifest({
-      version: KIT_VERSION,
-      profile: existing.profile,
-      packs: existing.packs,
-      skills: existing.skills,
-      protected: existing.protected,
-      personalization: existing.personalization,
-      registryUrl: registry.url ?? existing.registry?.url,
-      registryRef: registry.ref ?? existing.registry?.ref
-    });
-    if (existing.overrides?.length) next.overrides = existing.overrides;
-    if (next.version === existing.version && existing.installedAt) {
-      next.installedAt = existing.installedAt;
-    }
-    if (args["seed-overlay"]) {
-      await seedManagedHashLedger(args.cwd);
-      logger.info("Seeded managed-hash ledger from current local overlay files.");
+    try {
+      logger.info(`Registry: ${registry.root} (${registry.source})`);
+      const next = buildManifest({
+        version: KIT_VERSION,
+        profile: existing.profile,
+        packs: existing.packs,
+        skills: existing.skills,
+        protected: existing.protected,
+        personalization: existing.personalization,
+        registryUrl: registry.url ?? existing.registry?.url,
+        registryRef: registry.ref ?? existing.registry?.ref
+      });
+      if (existing.overrides?.length) next.overrides = existing.overrides;
+      if (next.version === existing.version && existing.installedAt) {
+        next.installedAt = existing.installedAt;
+      }
+      if (args["seed-overlay"]) {
+        await seedManagedHashLedger(projectRoot);
+        logger.info("Seeded managed-hash ledger from current local overlay files.");
+      }
+      const stats = await syncFromManifest(registry.root, projectRoot, next);
+      await saveManifest(projectRoot, next);
+      logApplyStats(stats);
+      logger.success("Update complete (L3 protected paths left untouched).");
+    } finally {
+      await registry.unlock?.();
     }
-    const stats = await syncFromManifest(registry.root, args.cwd, next);
-    await saveManifest(args.cwd, next);
-    logApplyStats(stats);
-    logger.success("Update complete (L3 protected paths left untouched).");
   }
 });
 
 // src/commands/validate.ts
-import { readFile as readFile20 } from "fs/promises";
-import path40 from "path";
+import { readFile as readFile21 } from "fs/promises";
+import path42 from "path";
 import { defineCommand as defineCommand18 } from "citty";
 
 // src/invariants/plan-schema.ts
@@ -6551,9 +7346,9 @@ function validatePlanFrontmatterText(text) {
 // src/commands/validate.ts
 async function resolveEditedPath(cwd, explicit) {
   if (explicit) {
-    const filePath2 = path40.resolve(cwd, explicit);
+    const filePath2 = path42.resolve(cwd, explicit);
     try {
-      return { filePath: filePath2, content: await readFile20(filePath2, "utf8") };
+      return { filePath: filePath2, content: await readFile21(filePath2, "utf8") };
     } catch {
       return null;
     }
@@ -6561,9 +7356,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 = path40.isAbsolute(rel) ? rel : path40.resolve(cwd, rel);
+  const filePath = path42.isAbsolute(rel) ? rel : path42.resolve(cwd, rel);
   try {
-    return { filePath, content: await readFile20(filePath, "utf8") };
+    return { filePath, content: await readFile21(filePath, "utf8") };
   } catch {
     return null;
   }
@@ -6578,7 +7373,7 @@ function isPlanPath(filePath) {
 var validateCommand = defineCommand18({
   meta: {
     name: "validate",
-    description: "Advisory validators for HANDOFF / plan frontmatter (afterFileEdit adapter)"
+    description: "Advisory validators for HANDOFF / plan frontmatter (hook adapter)."
   },
   subCommands: {
     handoff: defineCommand18({
@@ -6591,10 +7386,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 ? path40.resolve(cwd, fileArg) : path40.join(path40.resolve(cwd), ".cursor", "HANDOFF.md");
+        const filePath = fileArg ? path42.resolve(cwd, fileArg) : path42.join(path42.resolve(cwd), ".cursor", "HANDOFF.md");
         let content = "";
         try {
-          content = await readFile20(filePath, "utf8");
+          content = await readFile21(filePath, "utf8");
         } catch {
           console.log(JSON.stringify({ ok: true, warnings: [], note: "file missing" }));
           return;
@@ -6618,10 +7413,10 @@ var validateCommand = defineCommand18({
           process.exitCode = 2;
           return;
         }
-        const filePath = path40.resolve(cwd, fileArg);
+        const filePath = path42.resolve(cwd, fileArg);
         let content = "";
         try {
-          content = await readFile20(filePath, "utf8");
+          content = await readFile21(filePath, "utf8");
         } catch {
           console.log(JSON.stringify({ ok: true, warnings: [], note: "file missing" }));
           return;
@@ -6640,7 +7435,7 @@ var validateCommand = defineCommand18({
       },
       async run({ args }) {
         const cwd = typeof args.cwd === "string" ? args.cwd : process.cwd();
-        const resolved = await resolveEditedPath(path40.resolve(cwd));
+        const resolved = await resolveEditedPath(path42.resolve(cwd));
         if (!resolved) {
           console.log(JSON.stringify({}));
           return;
@@ -6682,11 +7477,204 @@ var validateCommand = defineCommand18({
   }
 });
 
+// src/welcome/help-groups.ts
+import { bold, gray as gray3, underline } from "kolorist";
+
+// src/welcome/screen.ts
+import {
+  blue as blue2,
+  cyan as cyan3,
+  gray as gray2,
+  options as koloristOptions,
+  lightCyan,
+  trueColor,
+  white as white2
+} from "kolorist";
+var HELMET_OUTLINE = "#e2e8f0";
+var KOLORIST_TRUECOLOR = 3;
+var HELMET_ASCII = [
+  "       ____",
+  "    .-'    '-.",
+  "   /  .--.    \\",
+  "  |  /    \\    |",
+  "  | |  ()  |   |",
+  "  |  \\    /    |",
+  "   \\  '--'    /",
+  "    '-.____.-'",
+  "   /_/      \\_\\"
+];
+function hexToRgb(hex) {
+  const m = /^#([0-9a-fA-F]{6})$/.exec(hex.trim());
+  const hexBody = m?.[1];
+  if (!hexBody) throw new Error(`invalid hex color: ${hex}`);
+  const n = Number.parseInt(hexBody, 16);
+  return [n >> 16 & 255, n >> 8 & 255, n & 255];
+}
+function outlineAnsi(line) {
+  const [r, g, b] = hexToRgb(HELMET_OUTLINE);
+  return trueColor(r, g, b)(line);
+}
+function withKoloristColor(fn) {
+  const prevEnabled = koloristOptions.enabled;
+  const prevLevel = koloristOptions.supportLevel;
+  koloristOptions.enabled = true;
+  koloristOptions.supportLevel = KOLORIST_TRUECOLOR;
+  try {
+    return fn();
+  } finally {
+    koloristOptions.enabled = prevEnabled;
+    koloristOptions.supportLevel = prevLevel;
+  }
+}
+function hasCliSubcommand(rawArgs) {
+  return Boolean(rawArgs?.some((arg) => !arg.startsWith("-")));
+}
+function shouldUseWelcomeColor(opts = {}) {
+  if (opts.color === false) return false;
+  if (process.env.NO_COLOR) return false;
+  if (process.env.NODE_DISABLE_COLORS) return false;
+  if (process.env.FORCE_COLOR === "0") return false;
+  if (process.env.CI != null && process.env.CI !== "") return false;
+  if (opts.color === true) return true;
+  const tty = opts.stdoutIsTTY ?? Boolean(process.stdout.isTTY);
+  return tty;
+}
+function renderHelmetAscii(color) {
+  if (!color) return HELMET_ASCII.join("\n");
+  return withKoloristColor(
+    () => HELMET_ASCII.map((line, i) => {
+      if (i <= 1 || i >= HELMET_ASCII.length - 1) return outlineAnsi(line);
+      if (i === 4) return lightCyan(line);
+      return blue2(line);
+    }).join("\n")
+  );
+}
+var WELCOME_UTILITY_HINTS = [
+  { cmd: "agent-kit --help", hint: "grouped commands" },
+  { cmd: "agent-kit doctor", hint: "repository readiness" },
+  { cmd: "agent-kit status", hint: "installed kit version" },
+  { cmd: "agent-kit dashboard", hint: "Mission Control panel" },
+  { cmd: "agent-kit init", hint: "guided install entry" }
+];
+function renderWelcomeScreen(opts = {}) {
+  const version = opts.version ?? KIT_VERSION;
+  const color = shouldUseWelcomeColor(opts);
+  const title = color ? white2("Mission Kit") : "Mission Kit";
+  const product = color ? cyan3("agent-kit") : "agent-kit";
+  const muted = (s) => color ? gray2(s) : s;
+  const lines = [
+    renderHelmetAscii(color),
+    "",
+    `${title}  \xB7  ${product} v${version}`,
+    muted("HITL framework for AI-assisted IDEs  \xB7  @dadado/agent-kit-cli"),
+    "",
+    muted("Try:"),
+    ...(() => {
+      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 ? cyan3(`  ${cmd}`) : `  ${cmd}`;
+        return `${left}${pad}${muted(hint)}`;
+      });
+    })(),
+    "",
+    muted(
+      "Chat HITL (start-project, git-staging/prod, run-plan-all) stays in Cursor slash commands."
+    )
+  ];
+  return `${lines.join("\n")}
+`;
+}
+function printWelcomeScreen(opts = {}) {
+  process.stdout.write(renderWelcomeScreen(opts));
+}
+
+// src/welcome/help-groups.ts
+var CLI_HELP_GROUPS = [
+  {
+    id: "setup",
+    title: "SETUP",
+    commands: ["init", "install", "doctor", "status", "update", "add", "scan"]
+  },
+  {
+    id: "mission",
+    title: "MISSION",
+    commands: ["handoff", "run-plan"]
+  },
+  {
+    id: "dashboard",
+    title: "DASHBOARD",
+    commands: ["dashboard", "dashboard-broadcast", "monitors"]
+  },
+  {
+    id: "integrity",
+    title: "INTEGRITY",
+    commands: ["validate", "guard", "hook", "cursor-awareness", "diff", "contribute"]
+  }
+];
+async function resolveCommandMeta(meta) {
+  if (meta == null) return void 0;
+  const value = typeof meta === "function" ? await meta() : meta;
+  return await Promise.resolve(value);
+}
+async function resolveSubMeta(subCommands) {
+  const out = /* @__PURE__ */ new Map();
+  for (const [name, raw] of Object.entries(subCommands)) {
+    const resolved = typeof raw === "function" ? await raw() : raw;
+    const def = resolved;
+    const meta = await resolveCommandMeta(def?.meta);
+    out.set(name, meta?.description ?? "");
+  }
+  return out;
+}
+async function renderGroupedRootHelp(cmd) {
+  const color = shouldUseWelcomeColor();
+  const u = (s) => color ? underline(bold(s)) : s;
+  const g = (s) => color ? gray3(s) : s;
+  const meta = await resolveCommandMeta(cmd.meta);
+  const name = meta?.name ?? "agent-kit";
+  const version = meta?.version ?? KIT_VERSION;
+  const description = meta?.description ?? "HITL framework for AI-assisted IDEs (Mission Kit family)";
+  const subCommands = await (typeof cmd.subCommands === "function" ? cmd.subCommands() : cmd.subCommands);
+  const descriptions = subCommands ? await resolveSubMeta(subCommands) : /* @__PURE__ */ new Map();
+  const placed = new Set(CLI_HELP_GROUPS.flatMap((grp) => grp.commands));
+  const leftover = [...descriptions.keys()].filter((c) => !placed.has(c)).sort();
+  const groups = [...CLI_HELP_GROUPS];
+  if (leftover.length > 0) {
+    groups.push({ id: "other", title: "OTHER", commands: leftover });
+  }
+  const lines = [
+    g(`${description} (${name} v${version})`),
+    "",
+    `${u("USAGE")} \`${name} <command> [OPTIONS]\``,
+    ""
+  ];
+  for (const group of groups) {
+    const rows = group.commands.filter((c) => descriptions.has(c));
+    if (rows.length === 0) continue;
+    lines.push(u(group.title), "");
+    const width = Math.max(...rows.map((c) => c.length));
+    for (const c of rows) {
+      const pad = " ".repeat(width - c.length + 2);
+      lines.push(`  ${c}${pad}${descriptions.get(c) ?? ""}`);
+    }
+    lines.push("");
+  }
+  lines.push(
+    g(`Use \`${name} <command> --help\` for more information about a command.`),
+    g(
+      "Chat-only HITL (start-project, backlog, git-staging/prod, run-plan-all) is not a CLI surface."
+    ),
+    ""
+  );
+  return lines.join("\n");
+}
+
 // src/index.ts
 var main = defineCommand19({
   meta: {
     name: "agent-kit",
-    description: "HITL framework for AI-assisted IDEs",
+    description: "HITL framework for AI-assisted IDEs (Mission Kit family)",
     version: KIT_VERSION
   },
   subCommands: {
@@ -6708,6 +7696,19 @@ var main = defineCommand19({
     guard: guardCommand,
     monitors: monitorsCommand,
     validate: validateCommand
+  },
+  async run({ rawArgs }) {
+    if (hasCliSubcommand(rawArgs)) return;
+    printWelcomeScreen();
+  }
+});
+runMain(main, {
+  showUsage: async (cmd, parent) => {
+    if (!parent) {
+      process.stdout.write(`${await renderGroupedRootHelp(cmd)}
+`);
+      return;
+    }
+    await showUsage(cmd, parent);
   }
 });
-runMain(main);