@dadado/agent-kit-cli 4.8.4 → 4.8.9

package/dist/index.js

@@ -1,14 +1,14 @@
 #!/usr/bin/env node
 
 // src/index.ts
-import { defineCommand as defineCommand18, runMain } from "citty";
+import { defineCommand as defineCommand19, runMain } from "citty";
 
 // src/commands/add.ts
 import { defineCommand } from "citty";
 
 // src/lifecycle/apply.ts
-import { copyFile, mkdir as mkdir2, readFile as readFile2 } from "fs/promises";
-import path3 from "path";
+import { copyFile, mkdir as mkdir3, readFile as readFile3 } from "fs/promises";
+import path4 from "path";
 
 // src/manifest/types.ts
 var MANIFEST_FILENAME = "agent-kit.json";
@@ -62,6 +62,62 @@ async function listDirectory(rootDir) {
   return readdir(rootDir);
 }
 
+// src/lifecycle/overlay.ts
+import { createHash } from "crypto";
+import { mkdir as mkdir2, readFile as readFile2, readdir as readdir2, writeFile as writeFile2 } from "fs/promises";
+import path3 from "path";
+
+// src/lifecycle/overlay-known-hashes.ts
+var KNOWN_SHIPPED_OVERLAY_HASHES = /* @__PURE__ */ new Set([
+  "082bdbc584be3f3d8aa6e9d7b9f4e076450f3ff48f9147a1deb557e31475036b",
+  "15566765ec95dad3bc3160f20ac910e01a13471df536e6d990f4b263700784a9",
+  "1681e6cf7b80a67cd999b94b8b6e16eb8caed0e11b32905848ba733da956e902",
+  "1974a5af0e4ba2bb0fc7e1872ef9ab70e323323ab216958c31731bcdd82c8241",
+  "1e58e0d4f2e8459b95a40d1b1e72c5c85a87230cbde945840a84073fe3a20422",
+  "285668d08f1b15d96286d27e29cc4a67e126e097fb8a940bdde33ccf25bd2bcd",
+  "3f3354825ff06ff9f9ae1e29b71784fef4250020c23c1b490940cf06b2be0f28",
+  "4bf23acbc9bd4e0f8468e61f4970e182600b72d9025d29e81ddbd83cb7b1710a",
+  "4c5167d0ebde685f266dce32c516a7c43876e0520647b93f07f2e2147e6a7b2f",
+  "4dc4efcd1b43c643d3889fb349df8d4964d0867c3a67eb67e2ec168fbb70fc75",
+  "4ff844cf789cef4b1e809a55ca006316cd964bcdb2557d91c916a08e30ad15f6",
+  "533b41599c25698e5746166096a68fd4080efb5e16287b2a1ed5f73295cda446",
+  "570c3f91fd31a4cc1e56e997c85feab5c6756f45fc73dc741afe573912111231",
+  "5d302d207521c53b9fa814ee0eba1376a5b2bfd2983c0373657c9fdf9884541b",
+  "621bc6cecf7c710a97e93463ca9b8872a1fcab1325c358cc8be65b418eebb339",
+  "69715048da3963947aa8a39e7ac30ec01632fec862bfcb9559c46764b4833be0",
+  "6a42e76fc038ca69ddad18541b8df161770c58980fefaf9e5e80d87407074bec",
+  "6a9af9e8a95dbb279347166c43dcee245ca673f9687841086b49911c54944c26",
+  "6b66ed7747ea2d19cb457f5af656e3c07f9f563f7f32b3951fa4ae5f27f0ac46",
+  "76ae85bbc336c6f435d9653e8f254ae49774b4ebaecf7335697115933eb8797c",
+  "8108b202c829627c3c2df33575016ebe942df42acf4f1cc393900be3b82b402c",
+  "8619500b0c7024390d43e3aaefa2a2d731728d7c664aaf90e0acdd067f3397ce",
+  "8a11c80b0fbf6c4aabf60eec05b8cca7dccf5bca472787a8afa3028fd8fbedfa",
+  "8b25659727063013e8bf6d7925f815b2630c2919b21e6fdac354362bf122bfab",
+  "8c7edbacc74b1431fbecb04c9857c0e7a9cb1578fc6ca6367be888dbcec3c98f",
+  "9439da963acbe5dd88a3aa4d6ba4fb297db666ce8f2c9d3917dbc6d6e517f9aa",
+  "98d96e25f67aa9c234cb0c422f0d701c22a04bfe184fb4eb68295003d429552b",
+  "99031145609af46e7e0f315006bf633f47002eccece8eb7af8b5efd762313ade",
+  "9a3cea681399b42ef930a0720802378fe1b06ee73370df9ede9d0309c3c60ab2",
+  "9d905aca0123f3018c81c579217104f1749d8da802f3837b2407fbad8f2d803f",
+  "a08d04f8efa121ad498f96873778c22630c9172c07c216839e348cd0bb7c2292",
+  "b5c7a10df90d209be07159b7ff9bfa24e869538a0b6026bb5ce79e1cdd5b2528",
+  "c96d522be440fbb638dbe953cebf1bb31185c431ac2e14446369cfb7d155a951",
+  "cf2bd11891b934484171fa705f470de284e3874402e1e487750735dbc7692857",
+  "d4659e4bb6fd6022559fc632b17db6a39007c04bc0ded59017a0dacc013632ed",
+  "d484243167e13c34f9df7ff378baf2967f7cbfcd88170d4d32e745efbcae7480",
+  "d96aa15dde45147aa40db64684688a4b5c9ad660dcd16c55156b31933a42c37e",
+  "d9ecd90f80ebc25db73ebed27c32596b9cfce518b3026a3a4d5787321ba6324a",
+  "dd01d051dbab257e16609b02c983bad6a576ed8473781b4f1df9ef2eb5f85795",
+  "de6efabde6a1d69357926b88b5a4ed3eec19e11b82597cb999f5365f952305b8",
+  "e03b5764b908f9ed5c592108fbc11d5962d9256fd129a63ab4a39c8efaa2ef3e",
+  "e102e77f9f520f938d26861978249e4d85a8c8755d48c8e79b21fef9423325ee",
+  "e511e04064ffb8c429b659d2ae2e0f223e8cc51039ae816753095a5f7a160595",
+  "ebd41f8df764a14b3460016fafcfdde98c4c3a59a3c17f773451ef061fc42f95",
+  "f061432a2606049717c0cbf098ef07b1da4df2b136c4cb9cdaa7ea44c876bcd6",
+  "f061d36a1180293519fbb560bbf659c621bd90885e995fca6eaf2eda9e418a50",
+  "f28731a82f4b394a5765fdefe2d1b667810831f6dcea400ca62bc66e1d65371c"
+]);
+
 // src/lifecycle/paths.ts
 import path2 from "path";
 function resolveContained(root, rel) {
@@ -77,6 +133,77 @@ function toPosixRel(root, absPath) {
   return path2.relative(root, absPath).split(path2.sep).join("/");
 }
 
+// src/lifecycle/overlay.ts
+var MANAGED_HASHES_REL = ".cursor/agent-kit.managed-hashes.json";
+var CONSUMER_OVERLAY_PREFIXES = [
+  ".cursor/agents/",
+  ".cursor/skills/",
+  ".cursor/commands/"
+];
+function isConsumerOverlayPath(relPath) {
+  const norm = relPath.split(path3.sep).join("/");
+  return CONSUMER_OVERLAY_PREFIXES.some((p) => norm.startsWith(p));
+}
+function contentHash(content) {
+  return createHash("sha256").update(content, "utf8").digest("hex");
+}
+async function loadManagedHashLedger(projectRoot) {
+  const abs = resolveContained(projectRoot, MANAGED_HASHES_REL);
+  try {
+    const raw = await readFile2(abs, "utf8");
+    const parsed = JSON.parse(raw);
+    if (parsed && typeof parsed === "object" && parsed.hashes && typeof parsed.hashes === "object") {
+      return { schemaVersion: 1, hashes: { ...parsed.hashes } };
+    }
+  } catch {
+  }
+  return { schemaVersion: 1, hashes: {} };
+}
+async function saveManagedHashLedger(projectRoot, ledger) {
+  const abs = resolveContained(projectRoot, MANAGED_HASHES_REL);
+  await mkdir2(path3.dirname(abs), { recursive: true });
+  const payload = {
+    schemaVersion: 1,
+    hashes: { ...ledger.hashes }
+  };
+  await writeFile2(abs, `${JSON.stringify(payload, null, 2)}
+`, "utf8");
+}
+function shouldPreserveCustomizedOverlay(localContent, recordedHash, knownShippedHashes = KNOWN_SHIPPED_OVERLAY_HASHES) {
+  const localHash = contentHash(localContent);
+  if (!recordedHash) {
+    return !knownShippedHashes.has(localHash);
+  }
+  return localHash !== recordedHash;
+}
+async function seedManagedHashLedger(projectRoot) {
+  const ledger = await loadManagedHashLedger(projectRoot);
+  for (const prefix of CONSUMER_OVERLAY_PREFIXES) {
+    const prefixPath = resolveContained(projectRoot, prefix);
+    let entries;
+    try {
+      entries = await readdir2(prefixPath, { withFileTypes: true, recursive: true });
+    } catch {
+      continue;
+    }
+    for (const entry of entries) {
+      if (!entry.isFile()) continue;
+      const parentPath = String(entry.parentPath);
+      const name = String(entry.name);
+      const rel = path3.relative(projectRoot, path3.join(parentPath, name));
+      const norm = rel.split(path3.sep).join("/");
+      if (ledger.hashes[norm]) continue;
+      try {
+        const content = await readFile2(path3.join(parentPath, name), "utf8");
+        ledger.hashes[norm] = contentHash(content);
+      } catch {
+      }
+    }
+  }
+  await saveManagedHashLedger(projectRoot, ledger);
+  return ledger;
+}
+
 // src/lifecycle/glob.ts
 function normalizeRelPath(input) {
   return input.replace(/\\/g, "/").replace(/^\.\//, "").replace(/\/+/g, "/");
@@ -158,7 +285,8 @@ function emptyStats() {
     collisions: [],
     skippedProtected: [],
     missing: [],
-    unchanged: []
+    unchanged: [],
+    preservedCustomized: []
   };
 }
 function mergeStats(into, from) {
@@ -168,34 +296,82 @@ function mergeStats(into, from) {
   into.skippedProtected.push(...from.skippedProtected);
   into.missing.push(...from.missing);
   into.unchanged.push(...from.unchanged);
+  into.preservedCustomized.push(...from.preservedCustomized);
   return into;
 }
-async function copyRegistryFile(registryRoot, projectRoot, sourceRel, targetRel, protectedGlobs) {
-  const targetNorm = targetRel.split(path3.sep).join("/");
+async function copyRegistryFile(registryRoot, projectRoot, sourceRel, targetRel, protectedGlobs, options = {}) {
+  const targetNorm = targetRel.split(path4.sep).join("/");
   if (isProtectedPath(targetNorm, protectedGlobs)) {
     return "skipped-protected";
   }
   const sourceAbs = resolveContained(registryRoot, sourceRel);
   const targetAbs = resolveContained(projectRoot, targetRel);
   try {
-    await readFile2(sourceAbs);
+    await readFile3(sourceAbs);
   } catch {
     return "missing-source";
   }
   let existing = null;
   try {
-    existing = await readFile2(targetAbs, "utf8");
+    existing = await readFile3(targetAbs, "utf8");
   } catch {
     existing = null;
   }
-  const next = await readFile2(sourceAbs, "utf8");
-  if (existing === next) return "unchanged";
-  await mkdir2(path3.dirname(targetAbs), { recursive: true });
+  const next = await readFile3(sourceAbs, "utf8");
+  if (existing === next) {
+    if (isConsumerOverlayPath(targetNorm)) {
+      await touchOverlayHash(projectRoot, targetNorm, next, options);
+    }
+    return "unchanged";
+  }
+  if (existing !== null && isConsumerOverlayPath(targetNorm)) {
+    const ledger = options.managedHashes ?? await loadManagedHashLedger(projectRoot);
+    const recorded = ledger.hashes[targetNorm];
+    if (shouldPreserveCustomizedOverlay(existing, recorded)) {
+      if (!recorded) {
+        const managedHash = contentHash(next);
+        ledger.hashes[targetNorm] = managedHash;
+        if (options.managedHashes) {
+          options.managedHashes.hashes[targetNorm] = managedHash;
+        }
+        if (options.persistManagedHashes !== false) {
+          await saveManagedHashLedger(projectRoot, ledger);
+        }
+      }
+      return "preserved-customized";
+    }
+    await mkdir3(path4.dirname(targetAbs), { recursive: true });
+    await copyFile(sourceAbs, targetAbs);
+    ledger.hashes[targetNorm] = contentHash(next);
+    if (options.managedHashes) {
+      options.managedHashes.hashes[targetNorm] = ledger.hashes[targetNorm];
+    }
+    if (options.persistManagedHashes !== false) {
+      await saveManagedHashLedger(projectRoot, ledger);
+    }
+    return "written";
+  }
+  await mkdir3(path4.dirname(targetAbs), { recursive: true });
   await copyFile(sourceAbs, targetAbs);
+  if (isConsumerOverlayPath(targetNorm)) {
+    await touchOverlayHash(projectRoot, targetNorm, next, options);
+  }
   return "written";
 }
+async function touchOverlayHash(projectRoot, targetNorm, content, options) {
+  const ledger = options.managedHashes ?? await loadManagedHashLedger(projectRoot);
+  const hash = contentHash(content);
+  if (ledger.hashes[targetNorm] === hash) return;
+  ledger.hashes[targetNorm] = hash;
+  if (options.managedHashes) {
+    options.managedHashes.hashes[targetNorm] = hash;
+  }
+  if (options.persistManagedHashes !== false) {
+    await saveManagedHashLedger(projectRoot, ledger);
+  }
+}
 function recordOutcome(stats, targetRel, outcome) {
-  const rel = targetRel.split(path3.sep).join("/");
+  const rel = targetRel.split(path4.sep).join("/");
   switch (outcome) {
     case "written":
       stats.written.push(rel);
@@ -209,14 +385,19 @@ function recordOutcome(stats, targetRel, outcome) {
     case "unchanged":
       stats.unchanged.push(rel);
       break;
+    case "preserved-customized":
+      stats.preservedCustomized.push(rel);
+      break;
   }
 }
 async function saveManifest(projectRoot, manifest) {
-  const target = path3.join(projectRoot, MANIFEST_RELATIVE_PATH);
+  const target = path4.join(projectRoot, MANIFEST_RELATIVE_PATH);
   const payload = {
     ...manifest,
     schemaVersion: MANIFEST_SCHEMA_VERSION,
-    installedAt: (/* @__PURE__ */ new Date()).toISOString()
+    // Preserve installedAt on no-op updates (ADR factory-pseudo-consumer
+    // decision 4); a version change earns a fresh install timestamp.
+    installedAt: manifest.installedAt ?? (/* @__PURE__ */ new Date()).toISOString()
   };
   await writeJson(target, payload);
   return toPosixRel(projectRoot, target);
@@ -276,6 +457,12 @@ function logApplyStats(stats) {
     logger.warn("Slash collision preserved because the legacy command is customized:");
     for (const p of stats.collisions) logger.info(`  ! ${p}`);
   }
+  if (stats.preservedCustomized.length > 0) {
+    logger.warn(
+      `Preserved customized overlay (agents/skills/commands); run diff / contribute to sync upstream: ${stats.preservedCustomized.length}`
+    );
+    for (const p of stats.preservedCustomized) logger.info(`  ! ${p}`);
+  }
   if (stats.skippedProtected.length > 0) {
     logger.warn(`Skipped protected (L3): ${stats.skippedProtected.length}`);
     for (const p of stats.skippedProtected) logger.info(`  ~ ${p}`);
@@ -288,9 +475,9 @@ function logApplyStats(stats) {
 
 // src/registry/resolve.ts
 import { execFile } from "child_process";
-import { createHash } from "crypto";
+import { createHash as createHash2 } from "crypto";
 import { homedir } from "os";
-import path4 from "path";
+import path5 from "path";
 import { promisify } from "util";
 var execFileAsync = promisify(execFile);
 var DEFAULT_REGISTRY_URL = "https://github.com/agent-kit-startup/agent-kit";
@@ -311,14 +498,14 @@ function gitEnv() {
   return { ...process.env, GIT_ALLOW_PROTOCOL: "https" };
 }
 function cacheKey(url, ref) {
-  return createHash("sha256").update(`${url}@${ref}`).digest("hex").slice(0, 16);
+  return createHash2("sha256").update(`${url}@${ref}`).digest("hex").slice(0, 16);
 }
 async function hasRegistryIndex(root) {
-  return fileExists(path4.join(root, "registry", "registry.json"));
+  return fileExists(path5.join(root, "registry", "registry.json"));
 }
 async function cloneRegistry(url, ref, dest) {
-  const { mkdir: mkdir5 } = await import("fs/promises");
-  await mkdir5(path4.dirname(dest), { recursive: true });
+  const { mkdir: mkdir6 } = await import("fs/promises");
+  await mkdir6(path5.dirname(dest), { recursive: true });
   try {
     await execFileAsync("git", ["clone", "--depth", "1", "--branch", ref, "--", url, dest], {
       env: gitEnv()
@@ -343,7 +530,7 @@ async function refreshCache(cacheDir) {
 }
 async function resolveRegistryRoot(options) {
   if (options.registryPath) {
-    const root = path4.resolve(options.registryPath);
+    const root = path5.resolve(options.registryPath);
     if (!await hasRegistryIndex(root)) {
       throw new Error(`No registry/registry.json under --registry ${root}`);
     }
@@ -351,7 +538,7 @@ async function resolveRegistryRoot(options) {
   }
   const envPath = process.env.AGENT_KIT_REGISTRY;
   if (envPath) {
-    const root = path4.resolve(envPath);
+    const root = path5.resolve(envPath);
     if (!await hasRegistryIndex(root)) {
       throw new Error(`No registry/registry.json under AGENT_KIT_REGISTRY=${root}`);
     }
@@ -359,7 +546,7 @@ async function resolveRegistryRoot(options) {
   }
   if (await hasRegistryIndex(options.cwd)) {
     return {
-      root: path4.resolve(options.cwd),
+      root: path5.resolve(options.cwd),
       source: "cwd",
       url: options.registryUrl,
       ref: options.registryRef
@@ -368,7 +555,7 @@ async function resolveRegistryRoot(options) {
   const url = options.registryUrl ?? DEFAULT_REGISTRY_URL;
   const ref = options.registryRef ?? DEFAULT_REGISTRY_REF;
   assertSafeRegistrySource(url, ref);
-  const dest = path4.join(homedir(), ".cache", "agent-kit", "registry", cacheKey(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 };
@@ -429,7 +616,7 @@ function loadPackageVersion() {
 var KIT_VERSION = loadPackageVersion();
 
 // src/manifest/index.ts
-import path5 from "path";
+import path6 from "path";
 
 // src/manifest/parse.ts
 var SEMVER = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/;
@@ -605,16 +792,16 @@ function parseAgentKitManifest(raw) {
 
 // src/manifest/index.ts
 async function loadAgentKitManifest(cwd) {
-  const target = path5.join(cwd, MANIFEST_RELATIVE_PATH);
+  const target = path6.join(cwd, MANIFEST_RELATIVE_PATH);
   const raw = await readJson(target);
   if (raw === null) return null;
   return parseAgentKitManifest(raw);
 }
 
 // src/registry/client.ts
-import path6 from "path";
+import path7 from "path";
 async function loadRegistry(rootDir) {
-  const indexPath = path6.join(rootDir, "registry", "registry.json");
+  const indexPath = path7.join(rootDir, "registry", "registry.json");
   const index = await readJson(indexPath);
   if (!index) throw new Error(`Registry not found at ${indexPath}`);
   return index;
@@ -639,47 +826,47 @@ async function findPack(rootDir, packId) {
 }
 
 // src/registry/install.ts
-import { readFile as readFile3 } from "fs/promises";
-import path7 from "path";
+import { readFile as readFile4 } from "fs/promises";
+import path8 from "path";
 function targetForMember(member) {
   switch (member.kind) {
     case "skill": {
       const category = member.source.includes("/core/") ? "core" : "community";
       return {
-        sourceRel: path7.posix.join(member.source, "SKILL.md"),
-        targetRel: path7.posix.join(".cursor", "skills", category, member.id, "SKILL.md")
+        sourceRel: path8.posix.join(member.source, "SKILL.md"),
+        targetRel: path8.posix.join(".cursor", "skills", category, member.id, "SKILL.md")
       };
     }
     case "rule":
       return {
         sourceRel: member.source,
-        targetRel: path7.posix.join(".cursor", "rules", path7.posix.basename(member.source))
+        targetRel: path8.posix.join(".cursor", "rules", path8.posix.basename(member.source))
       };
     case "agent":
       return {
         sourceRel: member.source,
-        targetRel: path7.posix.join(".cursor", "agents", path7.posix.basename(member.source))
+        targetRel: path8.posix.join(".cursor", "agents", path8.posix.basename(member.source))
       };
     case "command":
       return {
         sourceRel: member.source,
-        targetRel: path7.posix.join(".cursor", "commands", path7.posix.basename(member.source))
+        targetRel: path8.posix.join(".cursor", "commands", path8.posix.basename(member.source))
       };
     case "hook": {
-      const targetRel = member.source.startsWith(".cursor/") ? member.source : path7.posix.join(".cursor", "hooks", path7.posix.basename(member.source));
+      const targetRel = member.source.startsWith(".cursor/") ? member.source : path8.posix.join(".cursor", "hooks", path8.posix.basename(member.source));
       return { sourceRel: member.source, targetRel };
     }
     case "template": {
-      const base = path7.posix.basename(member.source);
+      const base = path8.posix.basename(member.source);
       if (member.source.includes("/context-management/") || member.source.includes("/engineering-architecture/")) {
         return {
           sourceRel: member.source,
-          targetRel: path7.posix.join(".cursor", "context", "templates", base)
+          targetRel: path8.posix.join(".cursor", "context", "templates", base)
         };
       }
       return {
         sourceRel: member.source,
-        targetRel: path7.posix.join("templates", base)
+        targetRel: path8.posix.join("templates", base)
       };
     }
     default: {
@@ -691,20 +878,23 @@ function targetForMember(member) {
 async function installSkill(registryRoot, projectRoot, skill, options = {}) {
   const stats = emptyStats();
   const category = skill.path.includes("/core/") ? "core" : "community";
-  const sourceRel = path7.posix.join(skill.path, "SKILL.md");
-  const targetRel = path7.posix.join(".cursor", "skills", category, skill.id, "SKILL.md");
+  const sourceRel = path8.posix.join(skill.path, "SKILL.md");
+  const targetRel = path8.posix.join(".cursor", "skills", category, skill.id, "SKILL.md");
+  const managedHashes = await loadManagedHashLedger(projectRoot);
   const outcome = await copyRegistryFile(
     registryRoot,
     projectRoot,
     sourceRel,
     targetRel,
-    options.protectedGlobs ?? []
+    options.protectedGlobs ?? [],
+    { managedHashes, persistManagedHashes: false }
   );
   recordOutcome(stats, targetRel, outcome);
+  await saveManagedHashLedger(projectRoot, managedHashes);
   return stats;
 }
 async function installSkillsByIds(registryRoot, projectRoot, skillIds, options = {}) {
-  const index = await readJson(path7.join(registryRoot, "registry", "registry.json"));
+  const index = await readJson(path8.join(registryRoot, "registry", "registry.json"));
   const stats = emptyStats();
   if (!index) return stats;
   const pool = allSkills(index);
@@ -720,7 +910,7 @@ async function installSkillsByIds(registryRoot, projectRoot, skillIds, options =
 }
 async function loadPackManifest(registryRoot, packId) {
   const summary = await findPack(registryRoot, packId);
-  const manifestPath = resolveContained(registryRoot, path7.join(summary.path, "pack.json"));
+  const manifestPath = resolveContained(registryRoot, path8.join(summary.path, "pack.json"));
   const manifest = await readJson(manifestPath);
   if (!manifest) throw new Error(`Pack manifest not found at ${manifestPath}`);
   return manifest;
@@ -730,6 +920,8 @@ async function installPack(registryRoot, projectRoot, packId, options = {}) {
   const packManifest = await loadPackManifest(registryRoot, packId);
   const stats = emptyStats();
   const protectedGlobs = options.protectedGlobs ?? [];
+  const managedHashes = await loadManagedHashLedger(projectRoot);
+  const copyOpts = { managedHashes, persistManagedHashes: false };
   for (const member of packManifest.members) {
     const { sourceRel, targetRel } = targetForMember(member);
     const outcome = await copyRegistryFile(
@@ -737,10 +929,12 @@ async function installPack(registryRoot, projectRoot, packId, options = {}) {
       projectRoot,
       sourceRel,
       targetRel,
-      protectedGlobs
+      protectedGlobs,
+      copyOpts
     );
     recordOutcome(stats, targetRel, outcome);
   }
+  await saveManagedHashLedger(projectRoot, managedHashes);
   return stats;
 }
 function packMemberTargets(member) {
@@ -853,8 +1047,8 @@ var addCommand = defineCommand({
 import { defineCommand as defineCommand2 } from "citty";
 
 // src/lifecycle/contribute.ts
-import { mkdir as mkdir3, readFile as readFile4, writeFile as writeFile2 } from "fs/promises";
-import path8 from "path";
+import { mkdir as mkdir4, readFile as readFile5, writeFile as writeFile3 } from "fs/promises";
+import path9 from "path";
 
 // src/lifecycle/contribute-gate.ts
 var SECRET_PATTERNS = [
@@ -1042,6 +1236,14 @@ var L0_ARTIFACTS = [
     source: ".cursor/commands/field-report-resolve.md",
     target: ".cursor/commands/field-report-resolve.md"
   },
+  {
+    source: ".cursor/commands/dogfood.md",
+    target: ".cursor/commands/dogfood.md"
+  },
+  {
+    source: ".cursor/commands/cursor-update-awareness.md",
+    target: ".cursor/commands/cursor-update-awareness.md"
+  },
   // Context (templates + example config; private config.json is not L0)
   {
     source: ".cursor/context/templates/plan-external-review-prompt.md",
@@ -1136,7 +1338,7 @@ var L0_ARTIFACTS = [
 // src/lifecycle/contribute.ts
 async function readLocal(projectRoot, rel) {
   try {
-    return await readFile4(resolveContained(projectRoot, rel), "utf8");
+    return await readFile5(resolveContained(projectRoot, rel), "utf8");
   } catch {
     return null;
   }
@@ -1144,13 +1346,13 @@ async function readLocal(projectRoot, rel) {
 async function buildRegistryPathMap(registryRoot, manifest) {
   const map = /* @__PURE__ */ new Map();
   for (const a of L0_ARTIFACTS) {
-    map.set(a.target.split(path8.sep).join("/"), a.source.split(path8.sep).join("/"));
+    map.set(a.target.split(path9.sep).join("/"), a.source.split(path9.sep).join("/"));
   }
   for (const packId of manifest.packs ?? []) {
     const pack = await loadPackManifest(registryRoot, packId);
     for (const member of pack.members) {
       const { sourceRel, targetRel } = packMemberTargets(member);
-      map.set(targetRel.split(path8.sep).join("/"), sourceRel.split(path8.sep).join("/"));
+      map.set(targetRel.split(path9.sep).join("/"), sourceRel.split(path9.sep).join("/"));
     }
   }
   if ((manifest.skills ?? []).length > 0) {
@@ -1160,24 +1362,24 @@ async function buildRegistryPathMap(registryRoot, manifest) {
       const skill = pool.find((s) => s.id === id);
       if (!skill) continue;
       const category = skill.path.includes("/core/") ? "core" : "community";
-      const sourceRel = path8.posix.join(skill.path, "SKILL.md");
-      const targetRel = path8.posix.join(".cursor", "skills", category, skill.id, "SKILL.md");
+      const sourceRel = path9.posix.join(skill.path, "SKILL.md");
+      const targetRel = path9.posix.join(".cursor", "skills", category, skill.id, "SKILL.md");
       map.set(targetRel, sourceRel);
     }
   }
   return map;
 }
 function guessRegistryPath(projectRel) {
-  const p = projectRel.split(path8.sep).join("/");
+  const p = projectRel.split(path9.sep).join("/");
   if (p.startsWith(".cursor/skills/") && p.endsWith("/SKILL.md")) {
     const rest = p.slice(".cursor/skills/".length);
     const parts = rest.split("/");
     if (parts.length === 3 && (parts[0] === "core" || parts[0] === "community")) {
-      return path8.posix.join("registry/skills", rest);
+      return path9.posix.join("registry/skills", rest);
     }
     const skillId = parts[0];
     if (parts.length === 2 && skillId) {
-      return path8.posix.join("registry/skills", "community", skillId, "SKILL.md");
+      return path9.posix.join("registry/skills", "community", skillId, "SKILL.md");
     }
   }
   if (p.startsWith(".cursor/rules/")) {
@@ -1203,7 +1405,7 @@ async function planContribute(options) {
   const candidates = [];
   const seen = /* @__PURE__ */ new Set();
   const push = async (kind, projectPath, registryPath) => {
-    const key = projectPath.split(path8.sep).join("/");
+    const key = projectPath.split(path9.sep).join("/");
     if (seen.has(key)) return;
     seen.add(key);
     const content = await readLocal(options.projectRoot, projectPath);
@@ -1212,7 +1414,7 @@ async function planContribute(options) {
     }
     if (kind === "drift") {
       try {
-        const upstream = await readFile4(
+        const upstream = await readFile5(
           resolveContained(options.registryRoot, registryPath),
           "utf8"
         );
@@ -1235,7 +1437,7 @@ async function planContribute(options) {
     }
   }
   for (const raw of options.extraPaths ?? []) {
-    const projectPath = raw.split(path8.sep).join("/");
+    const projectPath = raw.split(path9.sep).join("/");
     const blocked = gateContributePath(projectPath);
     if (blocked.length > 0) {
       if (!seen.has(projectPath)) {
@@ -1278,10 +1480,10 @@ async function writeContributeToRegistry(projectRoot, registryRoot, accepted) {
   const written = [];
   for (const c of accepted) {
     if (!c.registryPath) continue;
-    const content = await readFile4(resolveContained(projectRoot, c.projectPath), "utf8");
+    const content = await readFile5(resolveContained(projectRoot, c.projectPath), "utf8");
     const dest = resolveContained(registryRoot, c.registryPath);
-    await mkdir3(path8.dirname(dest), { recursive: true });
-    await writeFile2(dest, content, "utf8");
+    await mkdir4(path9.dirname(dest), { recursive: true });
+    await writeFile3(dest, content, "utf8");
     written.push(c.registryPath);
   }
   return written;
@@ -1406,66 +1608,466 @@ var contributeCommand = defineCommand2({
   }
 });
 
+// src/commands/cursor-awareness.ts
+import { defineCommand as defineCommand3 } from "citty";
+
+// src/lifecycle/cursor-update-awareness.ts
+import { readFile as readFile6 } 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");
+var DEFAULT_PREFS = {
+  enabled: false,
+  intervalDays: 7,
+  lastCheckedAt: null,
+  lastSeenCursorVersion: null,
+  changelogUrl: DEFAULT_CURSOR_CHANGELOG_URL
+};
+var CONVEYOR_HINT = "Confirmed gaps: Ask HITL then `/backlog-add` or `/dogfood` (lane-aware). Never auto Field Reports. Native-audit version prose owned by parked Marketplace plan.";
+function readCursorUpdateCheckPrefs(config) {
+  if (!config || typeof config !== "object" || Array.isArray(config)) {
+    return { ...DEFAULT_PREFS };
+  }
+  const raw = config.cursorUpdateCheck;
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+    return { ...DEFAULT_PREFS };
+  }
+  const uc = raw;
+  const intervalDays = typeof uc.intervalDays === "number" && Number.isInteger(uc.intervalDays) && uc.intervalDays >= 1 ? uc.intervalDays : DEFAULT_PREFS.intervalDays;
+  const changelogUrl = typeof uc.changelogUrl === "string" && uc.changelogUrl.startsWith("https://") ? uc.changelogUrl : DEFAULT_PREFS.changelogUrl;
+  return {
+    enabled: uc.enabled === true,
+    intervalDays,
+    lastCheckedAt: typeof uc.lastCheckedAt === "string" ? uc.lastCheckedAt : null,
+    lastSeenCursorVersion: typeof uc.lastSeenCursorVersion === "string" ? uc.lastSeenCursorVersion : null,
+    changelogUrl
+  };
+}
+function intervalElapsed(lastCheckedAt, intervalDays) {
+  if (!lastCheckedAt) return true;
+  const last = Date.parse(lastCheckedAt);
+  if (Number.isNaN(last)) return true;
+  return Date.now() - last >= intervalDays * 24 * 60 * 60 * 1e3;
+}
+async function loadContextConfig(cwd) {
+  const configPath = path10.join(cwd, ".cursor", "context", "config.json");
+  return readJson(configPath);
+}
+async function stampCursorUpdateCheck(cwd, patch) {
+  const configPath = path10.join(cwd, ".cursor", "context", "config.json");
+  const existing = await loadContextConfig(cwd) ?? {};
+  const prev = existing.cursorUpdateCheck && typeof existing.cursorUpdateCheck === "object" ? { ...existing.cursorUpdateCheck } : {};
+  const nextSeen = patch.lastSeenCursorVersion !== void 0 ? patch.lastSeenCursorVersion : void 0;
+  if (nextSeen !== void 0 && nextSeen !== null && !isPlausibleCursorVersion(nextSeen)) {
+    existing.cursorUpdateCheck = {
+      ...DEFAULT_PREFS,
+      ...prev,
+      lastCheckedAt: (/* @__PURE__ */ new Date()).toISOString()
+    };
+    await writeJson(configPath, existing);
+    return;
+  }
+  existing.cursorUpdateCheck = {
+    ...DEFAULT_PREFS,
+    ...prev,
+    lastCheckedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    ...nextSeen !== void 0 ? { lastSeenCursorVersion: nextSeen } : {}
+  };
+  await writeJson(configPath, existing);
+}
+function isPlausibleCursorVersion(version) {
+  const parts = String(version).split(".");
+  if (parts.length < 2 || parts.length > 3) return false;
+  const major = Number(parts[0]);
+  const minor = Number(parts[1]);
+  const patch = parts.length === 3 ? Number(parts[2]) : 0;
+  if ([major, minor, patch].some((n) => Number.isNaN(n) || n < 0)) return false;
+  if (major >= 2e3 || major > CURSOR_VERSION_MAJOR_MAX) return false;
+  if (minor > 999 || patch > 999) return false;
+  return true;
+}
+function extractLatestCursorVersion(changelogText) {
+  const text = String(changelogText ?? "");
+  const candidates = [];
+  const push = (major, minor, patch) => {
+    const version = patch !== void 0 ? `${major}.${minor}.${patch}` : `${major}.${minor}`;
+    if (isPlausibleCursorVersion(version)) candidates.push(version);
+  };
+  for (const m of text.matchAll(/<span class="label">(\d+)\.(\d+)(?:\.(\d+))?<\/span>/gi)) {
+    push(m[1] ?? "", m[2] ?? "", m[3]);
+  }
+  for (const m of text.matchAll(
+    /\b(\d+)\.(\d+)(?:\.(\d+))?\b(?=[^\n]{0,48}(?:Changelog|Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec))/gi
+  )) {
+    push(m[1] ?? "", m[2] ?? "", m[3]);
+  }
+  if (candidates.length === 0) {
+    for (const m of text.matchAll(/\b(\d+)\.(\d+)(?:\.(\d+))?\b/g)) {
+      push(m[1] ?? "", m[2] ?? "", m[3]);
+    }
+  }
+  let best = null;
+  let bestScore = -1;
+  for (const version of candidates) {
+    const parts = version.split(".").map(Number);
+    const score = (parts[0] ?? 0) * 1e6 + (parts[1] ?? 0) * 1e3 + (parts[2] ?? 0);
+    if (score > bestScore) {
+      bestScore = score;
+      best = version;
+    }
+  }
+  return best;
+}
+function compareCursorVersion(a, b) {
+  const pa = a.split(".").map((p) => Number(p));
+  const pb = b.split(".").map((p) => Number(p));
+  const len = Math.max(pa.length, pb.length);
+  for (let i = 0; i < len; i++) {
+    const da = pa[i] ?? 0;
+    const db = pb[i] ?? 0;
+    if (Number.isNaN(da) || Number.isNaN(db)) return 0;
+    if (da !== db) return da < db ? -1 : 1;
+  }
+  return 0;
+}
+function parseInventoryRefreshed(markdown) {
+  const m = markdown.match(/last refreshed\s+\*\*(\d{4}-\d{2}-\d{2})\*\*/i);
+  return m?.[1] ?? null;
+}
+function parseOpenActionIds(markdown) {
+  const ids = [];
+  for (const line of markdown.split("\n")) {
+    const m = line.match(/^\|\s*([A-Z]\d+)\s*\|\s*Open\s*\|/i);
+    if (m?.[1]) ids.push(m[1]);
+  }
+  return ids;
+}
+function parseFeatureMapNames(markdown) {
+  const names = [];
+  let inTable = false;
+  for (const line of markdown.split("\n")) {
+    if (line.startsWith("| Feature |")) {
+      inTable = true;
+      continue;
+    }
+    if (inTable) {
+      if (!line.startsWith("|")) break;
+      if (line.includes("---")) continue;
+      const cells = line.split("|").map((c) => c.trim());
+      const name = cells[1];
+      if (name && name.toLowerCase() !== "feature") names.push(name);
+    }
+  }
+  return names;
+}
+async function defaultFetchText(url) {
+  if (!url.startsWith("https://")) {
+    throw new Error(`Refusing non-HTTPS changelog URL: ${url}`);
+  }
+  const res = await fetch(url, {
+    headers: { Accept: "text/html,text/plain;q=0.9,*/*;q=0.8" },
+    redirect: "follow",
+    signal: AbortSignal.timeout(CHANGELOG_FETCH_TIMEOUT_MS)
+  });
+  if (!res.ok) {
+    throw new Error(`Changelog fetch failed: HTTP ${res.status}`);
+  }
+  return res.text();
+}
+function baseResult(partial) {
+  return {
+    ...partial,
+    applyRecommended: false,
+    fieldReportRecommended: false,
+    conveyorHint: CONVEYOR_HINT
+  };
+}
+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) {
+    if (!prefs.enabled) {
+      return baseResult({
+        status: "skipped-disabled",
+        inventoryPath: INVENTORY_REL,
+        featuresPath: FEATURES_REL,
+        changelogUrl,
+        latestCursorVersion: null,
+        lastSeenCursorVersion: prefs.lastSeenCursorVersion,
+        inventoryRefreshed: null,
+        openActionIds: [],
+        gaps: [],
+        message: "cursorUpdateCheck.enabled is false (opt-in). Set true in .cursor/context/config.json to nudge."
+      });
+    }
+    if (!intervalElapsed(prefs.lastCheckedAt, prefs.intervalDays)) {
+      return baseResult({
+        status: "skipped-interval",
+        inventoryPath: INVENTORY_REL,
+        featuresPath: FEATURES_REL,
+        changelogUrl,
+        latestCursorVersion: null,
+        lastSeenCursorVersion: prefs.lastSeenCursorVersion,
+        inventoryRefreshed: null,
+        openActionIds: [],
+        gaps: [],
+        message: `Within cursorUpdateCheck.intervalDays (${prefs.intervalDays}); last check ${prefs.lastCheckedAt}.`
+      });
+    }
+  }
+  let inventoryMd;
+  try {
+    inventoryMd = await readFile6(inventoryPath, "utf8");
+  } catch {
+    return baseResult({
+      status: "error",
+      inventoryPath: INVENTORY_REL,
+      featuresPath: FEATURES_REL,
+      changelogUrl,
+      latestCursorVersion: null,
+      lastSeenCursorVersion: prefs.lastSeenCursorVersion,
+      inventoryRefreshed: null,
+      openActionIds: [],
+      gaps: [],
+      message: `Missing inventory at ${INVENTORY_REL}.`
+    });
+  }
+  const inventoryRefreshed = parseInventoryRefreshed(inventoryMd);
+  const openActionIds = parseOpenActionIds(inventoryMd);
+  const gaps = [];
+  for (const id of openActionIds) {
+    gaps.push({
+      id: `open-action-${id}`,
+      severity: "advisory",
+      path: INVENTORY_REL,
+      evidence: `Action item ${id} is Open in the native-audit inventory`,
+      suggestedRoute: "backlog-add"
+    });
+  }
+  if (inventoryRefreshed) {
+    const refreshedMs = Date.parse(inventoryRefreshed);
+    if (!Number.isNaN(refreshedMs)) {
+      const ageDays = (Date.now() - refreshedMs) / (24 * 60 * 60 * 1e3);
+      if (ageDays > 45) {
+        gaps.push({
+          id: "inventory-stale",
+          severity: "stale",
+          path: INVENTORY_REL,
+          evidence: `Inventory last refreshed ${inventoryRefreshed} (>45 days). Version-prose refresh owned by parked Marketplace plan; awareness reports only.`,
+          suggestedRoute: "none"
+        });
+      }
+    }
+  }
+  try {
+    const featuresMd = await readFile6(featuresPath, "utf8");
+    if (parseFeatureMapNames(featuresMd).length === 0) {
+      gaps.push({
+        id: "features-map-empty",
+        severity: "info",
+        path: FEATURES_REL,
+        evidence: "Secondary feature map has no Feature table rows",
+        suggestedRoute: "none"
+      });
+    }
+  } catch {
+    gaps.push({
+      id: "features-map-missing",
+      severity: "info",
+      path: FEATURES_REL,
+      evidence: "Secondary feature map missing; changelog/inventory check continues",
+      suggestedRoute: "none"
+    });
+  }
+  let latestCursorVersion = null;
+  if (!options.offline) {
+    try {
+      const body = options.changelogBody ?? await (options.fetchText ?? defaultFetchText)(changelogUrl);
+      latestCursorVersion = extractLatestCursorVersion(body);
+      if (latestCursorVersion && prefs.lastSeenCursorVersion && compareCursorVersion(latestCursorVersion, prefs.lastSeenCursorVersion) > 0) {
+        gaps.push({
+          id: "changelog-ahead",
+          severity: "advisory",
+          path: changelogUrl,
+          evidence: `Changelog latest ${latestCursorVersion} is ahead of lastSeenCursorVersion ${prefs.lastSeenCursorVersion}`,
+          suggestedRoute: "backlog-add"
+        });
+      } else if (latestCursorVersion && !prefs.lastSeenCursorVersion) {
+        gaps.push({
+          id: "changelog-baseline",
+          severity: "info",
+          path: changelogUrl,
+          evidence: `Changelog latest ${latestCursorVersion}; no lastSeenCursorVersion baseline yet (stamp to baseline)`,
+          suggestedRoute: "none"
+        });
+      }
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      return baseResult({
+        status: "error",
+        inventoryPath: INVENTORY_REL,
+        featuresPath: FEATURES_REL,
+        changelogUrl,
+        latestCursorVersion: null,
+        lastSeenCursorVersion: prefs.lastSeenCursorVersion,
+        inventoryRefreshed,
+        openActionIds,
+        gaps,
+        message: `Changelog fetch error: ${msg}`
+      });
+    }
+  }
+  if (options.stamp) {
+    await stampCursorUpdateCheck(cwd, {
+      lastSeenCursorVersion: latestCursorVersion ?? prefs.lastSeenCursorVersion
+    });
+  }
+  const status = gaps.length > 0 ? "gaps-found" : "current";
+  const message = status === "current" ? "No advisory Cursor-update gaps vs inventory (check-only)." : `Found ${gaps.length} advisory gap(s). ${CONVEYOR_HINT}`;
+  return baseResult({
+    status,
+    inventoryPath: INVENTORY_REL,
+    featuresPath: FEATURES_REL,
+    changelogUrl: options.offline ? null : changelogUrl,
+    latestCursorVersion,
+    lastSeenCursorVersion: prefs.lastSeenCursorVersion,
+    inventoryRefreshed,
+    openActionIds,
+    gaps,
+    message
+  });
+}
+
+// src/commands/cursor-awareness.ts
+var cursorAwarenessCommand = defineCommand3({
+  meta: {
+    name: "cursor-awareness",
+    description: "Opt-in advisory: diff Cursor changelog / native-audit inventory for gaps (never apply, never Field Reports)"
+  },
+  args: {
+    cwd: {
+      type: "string",
+      default: process.cwd()
+    },
+    check: {
+      type: "boolean",
+      description: "Check-only (default true; apply is never supported)",
+      default: true
+    },
+    json: {
+      type: "boolean",
+      description: "Print machine-readable JSON",
+      default: false
+    },
+    "respect-prefs": {
+      type: "boolean",
+      description: "Honor cursorUpdateCheck.enabled and intervalDays from .cursor/context/config.json",
+      default: false
+    },
+    stamp: {
+      type: "boolean",
+      description: "Persist cursorUpdateCheck.lastCheckedAt / lastSeenCursorVersion",
+      default: false
+    },
+    offline: {
+      type: "boolean",
+      description: "Skip changelog network fetch; inventory-only advisory",
+      default: false
+    }
+  },
+  async run({ args }) {
+    void args.check;
+    const result = await checkCursorUpdateAwareness(args.cwd, {
+      respectPrefs: Boolean(args["respect-prefs"]),
+      stamp: Boolean(args.stamp),
+      offline: Boolean(args.offline)
+    });
+    if (args.json) {
+      console.log(JSON.stringify(result, null, 2));
+    } else {
+      const line = `[${result.status}] ${result.message}`;
+      if (result.status === "error") logger.error(line);
+      else if (result.status === "gaps-found") logger.warn(line);
+      else if (result.status.startsWith("skipped-")) logger.warn(line);
+      else logger.info(line);
+      if (result.gaps.length > 0 && !args.json) {
+        for (const gap of result.gaps.slice(0, 12)) {
+          logger.info(`- ${gap.id} (${gap.severity}): ${gap.evidence} \u2192 ${gap.suggestedRoute}`);
+        }
+        if (result.gaps.length > 12) {
+          logger.info(`\u2026 and ${result.gaps.length - 12} more (use --json)`);
+        }
+      }
+    }
+    if (result.status === "error") process.exitCode = 2;
+  }
+});
+
 // src/commands/dashboard-broadcast.ts
 import { spawn as spawn2 } from "child_process";
 import { access as access3 } from "fs/promises";
-import path10 from "path";
-import { defineCommand as defineCommand4 } from "citty";
+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 path9 from "path";
+import path11 from "path";
 import { fileURLToPath } from "url";
-import { defineCommand as defineCommand3 } from "citty";
+import { defineCommand as defineCommand4 } from "citty";
 function bundledDashboardCandidates(filename, moduleUrl = import.meta.url) {
-  const here = path9.dirname(fileURLToPath(moduleUrl));
+  const here = path11.dirname(fileURLToPath(moduleUrl));
   return [
     // Published / built: <pkg>/dist/index.js -> <pkg>/dashboard/
-    path9.join(here, "..", "dashboard", filename),
+    path11.join(here, "..", "dashboard", filename),
     // Dev source: packages/cli/src/commands/*.ts -> packages/cli/dashboard/ (sync copy)
-    path9.join(here, "..", "..", "dashboard", filename),
+    path11.join(here, "..", "..", "dashboard", filename),
     // From src/commands: packages/dashboard/ (unused layout); from dist: two levels above package
-    path9.join(here, "..", "..", "..", "dashboard", filename)
+    path11.join(here, "..", "..", "..", "dashboard", filename)
   ];
 }
 async function firstExisting(candidates) {
   for (const candidate2 of candidates) {
     try {
       await access2(candidate2);
-      return path9.resolve(candidate2);
+      return path11.resolve(candidate2);
     } catch {
     }
   }
   return null;
 }
 async function findDashboardStart(cwd, env = process.env, options = {}) {
-  let dir = path9.resolve(cwd);
+  let dir = path11.resolve(cwd);
   for (; ; ) {
-    const candidate2 = path9.join(dir, "dashboard", "start.mjs");
+    const candidate2 = path11.join(dir, "dashboard", "start.mjs");
     try {
       await access2(candidate2);
       return candidate2;
     } catch {
     }
-    const parent = path9.dirname(dir);
+    const parent = path11.dirname(dir);
     if (parent === dir) break;
     dir = parent;
   }
   for (const key of ["MISSION_CONTROL_KIT_ROOT", "AGENT_KIT_HOME"]) {
     const base = env[key];
     if (!base || typeof base !== "string" || !base.trim()) continue;
-    const candidate2 = path9.join(path9.resolve(base.trim()), "dashboard", "start.mjs");
+    const candidate2 = path11.join(path11.resolve(base.trim()), "dashboard", "start.mjs");
     try {
       await access2(candidate2);
       return candidate2;
     } catch {
     }
   }
-  const sibling = path9.join(path9.resolve(cwd), "..", "agent-kit", "dashboard", "start.mjs");
+  const sibling = path11.join(path11.resolve(cwd), "..", "agent-kit", "dashboard", "start.mjs");
   try {
     await access2(sibling);
-    return path9.resolve(sibling);
+    return path11.resolve(sibling);
   } catch {
   }
   return firstExisting(
@@ -1473,13 +2075,13 @@ async function findDashboardStart(cwd, env = process.env, options = {}) {
   );
 }
 function resolveDashboardSnapshotRoot(cwd) {
-  const abs = path9.resolve(cwd);
+  const abs = path11.resolve(cwd);
   try {
     const top = execFileSync("git", ["-C", abs, "rev-parse", "--show-toplevel"], {
       encoding: "utf8",
       timeout: 5e3
     }).trim();
-    if (top) return path9.resolve(top);
+    if (top) return path11.resolve(top);
   } catch {
   }
   return abs;
@@ -1487,7 +2089,7 @@ function resolveDashboardSnapshotRoot(cwd) {
 function runStartScript(startPath, env) {
   return new Promise((resolve, reject) => {
     const child = spawn(process.execPath, [startPath], {
-      cwd: path9.dirname(path9.dirname(startPath)),
+      cwd: path11.dirname(path11.dirname(startPath)),
       env,
       stdio: "inherit"
     });
@@ -1495,7 +2097,7 @@ function runStartScript(startPath, env) {
     child.on("close", (code) => resolve(code ?? 1));
   });
 }
-var dashboardCommand = defineCommand3({
+var dashboardCommand = defineCommand4({
   meta: {
     name: "dashboard",
     description: "Start Mission Control for this workspace (stable per-root port) and open the panel URL."
@@ -1532,30 +2134,30 @@ var dashboardCommand = defineCommand3({
 
 // src/commands/dashboard-broadcast.ts
 async function findDashboardBroadcastStart(cwd, env = process.env, options = {}) {
-  let dir = path10.resolve(cwd);
+  let dir = path12.resolve(cwd);
   for (; ; ) {
-    const candidate2 = path10.join(dir, "dashboard", "start-broadcast.mjs");
+    const candidate2 = path12.join(dir, "dashboard", "start-broadcast.mjs");
     try {
       await access3(candidate2);
       return candidate2;
     } catch {
     }
-    const parent = path10.dirname(dir);
+    const parent = path12.dirname(dir);
     if (parent === dir) break;
     dir = parent;
   }
   for (const key of ["MISSION_CONTROL_KIT_ROOT", "AGENT_KIT_HOME"]) {
     const base = env[key];
     if (!base || typeof base !== "string" || !base.trim()) continue;
-    const candidate2 = path10.join(path10.resolve(base.trim()), "dashboard", "start-broadcast.mjs");
+    const candidate2 = path12.join(path12.resolve(base.trim()), "dashboard", "start-broadcast.mjs");
     try {
       await access3(candidate2);
       return candidate2;
     } catch {
     }
   }
-  const sibling = path10.join(
-    path10.resolve(cwd),
+  const sibling = path12.join(
+    path12.resolve(cwd),
     "..",
     "agent-kit",
     "dashboard",
@@ -1563,7 +2165,7 @@ async function findDashboardBroadcastStart(cwd, env = process.env, options = {})
   );
   try {
     await access3(sibling);
-    return path10.resolve(sibling);
+    return path12.resolve(sibling);
   } catch {
   }
   for (const candidate2 of bundledDashboardCandidates(
@@ -1572,7 +2174,7 @@ async function findDashboardBroadcastStart(cwd, env = process.env, options = {})
   )) {
     try {
       await access3(candidate2);
-      return path10.resolve(candidate2);
+      return path12.resolve(candidate2);
     } catch {
     }
   }
@@ -1581,7 +2183,7 @@ async function findDashboardBroadcastStart(cwd, env = process.env, options = {})
 function runStartScript2(startPath, env) {
   return new Promise((resolve, reject) => {
     const child = spawn2(process.execPath, [startPath], {
-      cwd: path10.dirname(path10.dirname(startPath)),
+      cwd: path12.dirname(path12.dirname(startPath)),
       env,
       stdio: "inherit"
     });
@@ -1589,7 +2191,7 @@ function runStartScript2(startPath, env) {
     child.on("close", (code) => resolve(code ?? 1));
   });
 }
-var dashboardBroadcastCommand = defineCommand4({
+var dashboardBroadcastCommand = defineCommand5({
   meta: {
     name: "dashboard-broadcast",
     description: "Opt-in LAN Mission Control (token-gated). Terminal counterpart to /dashboard-broadcast. Does not change loopback /dashboard."
@@ -1624,20 +2226,20 @@ var dashboardBroadcastCommand = defineCommand4({
 });
 
 // src/commands/diff.ts
-import { defineCommand as defineCommand5 } from "citty";
+import { defineCommand as defineCommand6 } from "citty";
 
 // src/lifecycle/diff.ts
-import { readFile as readFile5 } from "fs/promises";
-import path11 from "path";
+import { readFile as readFile7 } from "fs/promises";
+import path13 from "path";
 async function readIfExists(abs) {
   try {
-    return await readFile5(abs, "utf8");
+    return await readFile7(abs, "utf8");
   } catch {
     return null;
   }
 }
 async function comparePair(registryRoot, projectRoot, sourceRel, targetRel, protectedGlobs) {
-  const posixTarget = targetRel.split(path11.sep).join("/");
+  const posixTarget = targetRel.split(path13.sep).join("/");
   if (isProtectedPath(posixTarget, protectedGlobs)) {
     return { path: posixTarget, status: "protected" };
   }
@@ -1667,7 +2269,7 @@ async function diffAgainstRegistry(registryRoot, projectRoot, manifest) {
   const entries = [];
   const seen = /* @__PURE__ */ new Set();
   const pushUnique = async (sourceRel, targetRel) => {
-    const key = targetRel.split(path11.sep).join("/");
+    const key = targetRel.split(path13.sep).join("/");
     if (seen.has(key)) return;
     seen.add(key);
     entries.push(
@@ -1694,8 +2296,8 @@ async function diffAgainstRegistry(registryRoot, projectRoot, manifest) {
         continue;
       }
       const category = skill.path.includes("/core/") ? "core" : "community";
-      const sourceRel = path11.posix.join(skill.path, "SKILL.md");
-      const targetRel = path11.posix.join(".cursor", "skills", category, skill.id, "SKILL.md");
+      const sourceRel = path13.posix.join(skill.path, "SKILL.md");
+      const targetRel = path13.posix.join(".cursor", "skills", category, skill.id, "SKILL.md");
       await pushUnique(sourceRel, targetRel);
     }
   }
@@ -1714,7 +2316,7 @@ function summarizeDiff(entries) {
 }
 
 // src/commands/diff.ts
-var diffCommand = defineCommand5({
+var diffCommand = defineCommand6({
   meta: {
     name: "diff",
     description: "Compare installed kit artifacts to the registry (respects L3 protected)."
@@ -1763,15 +2365,16 @@ var diffCommand = defineCommand5({
 });
 
 // src/commands/doctor.ts
-import path22 from "path";
-import { defineCommand as defineCommand6 } from "citty";
+import path24 from "path";
+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 readFile6, stat } from "fs/promises";
-import path12 from "path";
+import { constants as constants2, access as access4, readFile as readFile8, readdir as readdir3, stat } from "fs/promises";
+import path14 from "path";
 import { promisify as promisify2 } from "util";
 var execFileAsync2 = promisify2(execFile2);
+var GIT_HOOK_CANONICAL_NAMES = ["pre-commit", "pre-push", "prepare-commit-msg"];
 var EXPECTED_EVENTS = [
   "sessionStart",
   "preCompact",
@@ -1796,10 +2399,10 @@ async function isExecutable(p) {
   }
 }
 async function resolveAgentKitCli(rootDir) {
-  const root = path12.resolve(rootDir);
+  const root = path14.resolve(rootDir);
   const candidates = [
-    path12.join(root, "node_modules", ".bin", "agent-kit"),
-    path12.join(root, "packages", "cli", "dist", "index.js")
+    path14.join(root, "node_modules", ".bin", "agent-kit"),
+    path14.join(root, "packages", "cli", "dist", "index.js")
   ];
   for (const c of candidates) {
     if (await exists(c)) return c;
@@ -1818,16 +2421,83 @@ function commandLooksLikeAdapter(command) {
   const m = trimmed.match(/(\.cursor\/hooks\/agent\/[A-Za-z0-9._-]+\.sh)\b/);
   return m?.[1] ?? null;
 }
+async function assessGitHooksInstallDrift(rootDir) {
+  const root = path14.resolve(rootDir);
+  const canonicalDir = path14.join(root, "git-hooks");
+  if (!await exists(canonicalDir)) return [];
+  let hooksPathCfg = "";
+  try {
+    const { stdout } = await execFileAsync2(
+      "git",
+      ["-C", root, "config", "--get", "core.hooksPath"],
+      { encoding: "utf8" }
+    );
+    hooksPathCfg = stdout.trim();
+  } catch {
+  }
+  if (hooksPathCfg) {
+    const resolved = path14.isAbsolute(hooksPathCfg) ? path14.normalize(hooksPathCfg) : path14.normalize(path14.join(root, hooksPathCfg));
+    if (resolved === path14.normalize(canonicalDir)) {
+      return [];
+    }
+  }
+  const gitDir = path14.join(root, ".git");
+  if (!await exists(gitDir)) return [];
+  try {
+    const st = await stat(gitDir);
+    if (!st.isDirectory()) return [];
+  } catch {
+    return [];
+  }
+  const installedDir = path14.join(gitDir, "hooks");
+  const advisories = [];
+  const installHint = "Install or refresh with: `cp git-hooks/<name> .git/hooks/<name> && chmod +x .git/hooks/<name>` (see git-hooks/README.md)";
+  let names = [...GIT_HOOK_CANONICAL_NAMES];
+  try {
+    const listed = await readdir3(canonicalDir);
+    const fromDisk = listed.filter(
+      (n) => GIT_HOOK_CANONICAL_NAMES.includes(n)
+    );
+    if (fromDisk.length > 0) names = fromDisk;
+  } catch {
+  }
+  for (const name of names) {
+    const canonical = path14.join(canonicalDir, name);
+    const installed = path14.join(installedDir, name);
+    if (!await exists(canonical)) continue;
+    if (!await exists(installed)) {
+      advisories.push(
+        `git-hooks drift: \`.git/hooks/${name}\` missing (canonical \`git-hooks/${name}\` present). ${installHint}`
+      );
+      continue;
+    }
+    try {
+      const [a, b] = await Promise.all([readFile8(canonical, "utf8"), readFile8(installed, "utf8")]);
+      if (a !== b) {
+        advisories.push(
+          `git-hooks drift: \`.git/hooks/${name}\` differs from \`git-hooks/${name}\`. ${installHint}`
+        );
+      }
+    } catch {
+      advisories.push(
+        `git-hooks drift: could not compare \`git-hooks/${name}\` with \`.git/hooks/${name}\`. ${installHint}`
+      );
+    }
+  }
+  return advisories;
+}
 async function assessHooksHealth(rootDir) {
-  const root = path12.resolve(rootDir);
+  const root = path14.resolve(rootDir);
   const hooksJsonPath = ".cursor/hooks.json";
-  const hooksJsonAbs = path12.join(root, hooksJsonPath);
+  const hooksJsonAbs = path14.join(root, hooksJsonPath);
   const reasons = [];
   const wiredEvents = [];
+  const advisories = await assessGitHooksInstallDrift(root);
   if (!await exists(hooksJsonAbs)) {
     return {
       status: "missing",
       reasons: ["`.cursor/hooks.json` not found"],
+      advisories,
       hooksJsonPath,
       expectedEvents: [...EXPECTED_EVENTS],
       wiredEvents
@@ -1835,11 +2505,12 @@ async function assessHooksHealth(rootDir) {
   }
   let parsed;
   try {
-    parsed = JSON.parse(await readFile6(hooksJsonAbs, "utf8"));
+    parsed = JSON.parse(await readFile8(hooksJsonAbs, "utf8"));
   } catch {
     return {
       status: "degraded",
       reasons: ["`.cursor/hooks.json` is not valid JSON"],
+      advisories,
       hooksJsonPath,
       expectedEvents: [...EXPECTED_EVENTS],
       wiredEvents
@@ -1864,14 +2535,14 @@ async function assessHooksHealth(rootDir) {
       reasons.push(`missing hook event: ${event}`);
     }
   }
-  const resolveLib = path12.join(root, ".cursor", "hooks", "agent", "resolve-agent-kit.sh");
+  const resolveLib = path14.join(root, ".cursor", "hooks", "agent", "resolve-agent-kit.sh");
   if (!await exists(resolveLib)) {
     reasons.push("missing `.cursor/hooks/agent/resolve-agent-kit.sh` (thin adapter resolver)");
   } else if (!await isExecutable(resolveLib)) {
     reasons.push("`.cursor/hooks/agent/resolve-agent-kit.sh` is not executable (chmod +x)");
   }
   for (const rel of adapterRels) {
-    const abs = path12.join(root, rel);
+    const abs = path14.join(root, rel);
     if (!await exists(abs)) {
       reasons.push(`missing adapter script: \`${rel}\``);
       continue;
@@ -1903,6 +2574,7 @@ async function assessHooksHealth(rootDir) {
   return {
     status,
     reasons,
+    advisories,
     hooksJsonPath,
     expectedEvents: [...EXPECTED_EVENTS],
     wiredEvents
@@ -1910,7 +2582,7 @@ async function assessHooksHealth(rootDir) {
 }
 
 // src/scanner/readiness.ts
-import { createHash as createHash2 } from "crypto";
+import { createHash as createHash3 } from "crypto";
 function action(id, status, recommendation, owner) {
   return { id, status, recommendation, owner };
 }
@@ -1938,7 +2610,7 @@ function repositoryFingerprint(scan) {
     context: scan.context.sources,
     agentKitVersion: scan.agentKit.version
   };
-  return createHash2("sha256").update(JSON.stringify(fingerprintInput)).digest("hex");
+  return createHash3("sha256").update(JSON.stringify(fingerprintInput)).digest("hex");
 }
 function buildPillars(scan) {
   const agentKitStatus = scan.agentKit.installed ? "ready" : "auto_fix";
@@ -2156,12 +2828,12 @@ function createReadinessReport(scan, options) {
 }
 
 // src/scanner/safe-fixes.ts
-import { readFile as readFile9, writeFile as writeFile3 } from "fs/promises";
-import path20 from "path";
+import { readFile as readFile11, writeFile as writeFile4 } from "fs/promises";
+import path22 from "path";
 
 // src/scanner/detect-repository.ts
-import { readFile as readFile7 } from "fs/promises";
-import path13 from "path";
+import { readFile as readFile9 } from "fs/promises";
+import path15 from "path";
 var CONTEXT_PATHS = [
   ["README.md", "README"],
   ["README", "README"],
@@ -2180,7 +2852,7 @@ var CONTEXT_PATHS = [
 async function existingEvidence(rootDir, candidates) {
   const evidence = await Promise.all(
     candidates.map(
-      async ([relativePath, label]) => await fileExists(path13.join(rootDir, relativePath)) ? { source: "file", value: `${relativePath}:${label}` } : void 0
+      async ([relativePath, label]) => await fileExists(path15.join(rootDir, relativePath)) ? { source: "file", value: `${relativePath}:${label}` } : void 0
     )
   );
   return evidence.flatMap((item) => item ? [item] : []);
@@ -2201,7 +2873,7 @@ async function detectContext(rootDir) {
 async function detectPurpose(rootDir, stack) {
   const entries = await listDirectory(rootDir);
   const lowerEntries = entries.map((entry) => entry.toLowerCase());
-  const packageJson = await readJson(path13.join(rootDir, "package.json"));
+  const packageJson = await readJson(path15.join(rootDir, "package.json"));
   const categories = [];
   const evidence = [];
   const add = (category, value2) => {
@@ -2241,16 +2913,16 @@ async function detectPurpose(rootDir, stack) {
 }
 async function detectAgentKit(rootDir) {
   const manifestRelativePath = ".cursor/agent-kit.json";
-  const manifestPath = path13.join(rootDir, manifestRelativePath);
+  const manifestPath = path15.join(rootDir, manifestRelativePath);
   const installed = await fileExists(manifestPath);
   const manifest = installed ? await readJson(manifestPath) : null;
   return {
     installed,
     manifestPath: installed ? manifestRelativePath : void 0,
     version: manifest?.version,
-    hasPlans: await fileExists(path13.join(rootDir, ".cursor/plans")),
-    hasHandoff: await fileExists(path13.join(rootDir, ".cursor/HANDOFF.md")),
-    hasMemory: await fileExists(path13.join(rootDir, ".cursor/memory"))
+    hasPlans: await fileExists(path15.join(rootDir, ".cursor/plans")),
+    hasHandoff: await fileExists(path15.join(rootDir, ".cursor/HANDOFF.md")),
+    hasMemory: await fileExists(path15.join(rootDir, ".cursor/memory"))
   };
 }
 var REQUIRED_SECRET_PATTERNS = [
@@ -2264,9 +2936,9 @@ var REQUIRED_SECRET_PATTERNS = [
   "*service-account*.json"
 ];
 async function detectSafety(rootDir, trackedFiles) {
-  const gitignorePath = path13.join(rootDir, ".gitignore");
+  const gitignorePath = path15.join(rootDir, ".gitignore");
   const hasGitignore = await fileExists(gitignorePath);
-  const gitignore = hasGitignore ? await readFile7(gitignorePath, "utf8") : "";
+  const gitignore = hasGitignore ? await readFile9(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)
@@ -2275,7 +2947,7 @@ async function detectSafety(rootDir, trackedFiles) {
     (file) => /(^|\/)(\.env(\..+)?|.*\.(key|pem|p12|pfx)|.*credentials.*\.json)$/i.test(file)
   );
   const hookPaths = [".husky", ".git/hooks/pre-commit", "git-hooks/pre-commit"];
-  const hasHooks = (await Promise.all(hookPaths.map((item) => fileExists(path13.join(rootDir, item))))).some(Boolean);
+  const hasHooks = (await Promise.all(hookPaths.map((item) => fileExists(path15.join(rootDir, item))))).some(Boolean);
   const guardCandidates = [
     ".husky/pre-commit",
     ".husky/pre-push",
@@ -2284,7 +2956,7 @@ async function detectSafety(rootDir, trackedFiles) {
   ];
   const guardContents = await Promise.all(
     guardCandidates.map(
-      async (item) => await fileExists(path13.join(rootDir, item)) ? readFile7(path13.join(rootDir, item), "utf8") : ""
+      async (item) => await fileExists(path15.join(rootDir, item)) ? readFile9(path15.join(rootDir, item), "utf8") : ""
     )
   );
   return {
@@ -2302,11 +2974,11 @@ async function detectSafety(rootDir, trackedFiles) {
 }
 
 // src/scanner/scan.ts
-import path19 from "path";
+import path21 from "path";
 
 // src/scanner/detect-git.ts
 import { execFile as execFile3 } from "child_process";
-import path14 from "path";
+import path16 from "path";
 import { promisify as promisify3 } from "util";
 var exec = promisify3(execFile3);
 function remoteHostname(remoteUrl) {
@@ -2330,7 +3002,7 @@ function sanitizeRemoteUrl(remoteUrl) {
 }
 async function detectProvider(rootDir, remoteUrl) {
   const configuration = await readJson(
-    path14.join(rootDir, ".cursor", "agent-kit.config.json")
+    path16.join(rootDir, ".cursor", "agent-kit.config.json")
   );
   const configuredProvider = configuration?.git?.provider;
   if (configuredProvider) {
@@ -2387,7 +3059,7 @@ async function detectProvider(rootDir, remoteUrl) {
       evidence: remoteEvidence
     };
   }
-  if (await fileExists(path14.join(rootDir, ".gitlab-ci.yml"))) {
+  if (await fileExists(path16.join(rootDir, ".gitlab-ci.yml"))) {
     return {
       provider: "gitlab",
       providerKind: "gitlab-self-hosted",
@@ -2476,11 +3148,11 @@ async function detectGit(rootDir) {
 }
 
 // src/scanner/detect-ide.ts
-import path15 from "path";
+import path17 from "path";
 async function detectIde(rootDir) {
-  const hasCursor = await fileExists(path15.join(rootDir, ".cursor"));
-  const hasVSCode = await fileExists(path15.join(rootDir, ".vscode"));
-  const hasWindsurf = await fileExists(path15.join(rootDir, ".windsurfrules"));
+  const hasCursor = await fileExists(path17.join(rootDir, ".cursor"));
+  const hasVSCode = await fileExists(path17.join(rootDir, ".vscode"));
+  const hasWindsurf = await fileExists(path17.join(rootDir, ".windsurfrules"));
   if (hasCursor) return { ide: "cursor", plan: "cursor-pro" };
   if (hasVSCode) return { ide: "vscode", plan: "vscode-pro" };
   if (hasWindsurf) return { ide: "windsurf", plan: "windsurf" };
@@ -2488,7 +3160,7 @@ async function detectIde(rootDir) {
 }
 
 // src/scanner/detect-infra.ts
-import path16 from "path";
+import path18 from "path";
 
 // src/types.ts
 var CI_PLATFORM_FILES = {
@@ -2517,12 +3189,12 @@ var PM_TOOL_LABELS = {
 
 // src/scanner/detect-infra.ts
 async function detectInfra(rootDir) {
-  const docker = await fileExists(path16.join(rootDir, "Dockerfile")) || await fileExists(path16.join(rootDir, "docker-compose.yml")) || await fileExists(path16.join(rootDir, "docker-compose.yaml"));
-  const kubernetes = await fileExists(path16.join(rootDir, "k8s")) || await fileExists(path16.join(rootDir, "kubernetes"));
+  const docker = await fileExists(path18.join(rootDir, "Dockerfile")) || await fileExists(path18.join(rootDir, "docker-compose.yml")) || await fileExists(path18.join(rootDir, "docker-compose.yaml"));
+  const kubernetes = await fileExists(path18.join(rootDir, "k8s")) || await fileExists(path18.join(rootDir, "kubernetes"));
   let ci = "none";
   const ciFiles = [];
   for (const [platform, filePath] of Object.entries(CI_PLATFORM_FILES)) {
-    if (await fileExists(path16.join(rootDir, filePath))) {
+    if (await fileExists(path18.join(rootDir, filePath))) {
       if (ci === "none") ci = platform;
       ciFiles.push(filePath);
     }
@@ -2547,30 +3219,30 @@ async function detectInfra(rootDir) {
   ];
   const infrastructureFiles = (await Promise.all(
     infrastructureCandidates.map(
-      async (file) => await fileExists(path16.join(rootDir, file)) ? file : void 0
+      async (file) => await fileExists(path18.join(rootDir, file)) ? file : void 0
     )
   )).filter((file) => file !== void 0);
   const deploymentFiles = (await Promise.all(
     deploymentCandidates.map(
-      async (file) => await fileExists(path16.join(rootDir, file)) ? file : void 0
+      async (file) => await fileExists(path18.join(rootDir, file)) ? file : void 0
     )
   )).filter((file) => file !== void 0);
   return { docker, kubernetes, ci, ciFiles, infrastructureFiles, deploymentFiles };
 }
 
 // src/scanner/detect-services.ts
-import { readFile as readFile8 } from "fs/promises";
-import path17 from "path";
+import { readFile as readFile10 } from "fs/promises";
+import path19 from "path";
 async function detectProjectManagement(rootDir) {
   const tools = [];
   const mcpConfigPaths = [
-    path17.join(rootDir, ".cursor", "mcp.json"),
-    path17.join(rootDir, "mcp.json")
+    path19.join(rootDir, ".cursor", "mcp.json"),
+    path19.join(rootDir, "mcp.json")
   ];
   for (const configPath of mcpConfigPaths) {
     if (!await fileExists(configPath)) continue;
     try {
-      const raw = await readFile8(configPath, "utf8");
+      const raw = await readFile10(configPath, "utf8");
       const lower = raw.toLowerCase();
       if (lower.includes("clickup")) tools.push("clickup");
       if (lower.includes("jira") || lower.includes("atlassian")) tools.push("jira");
@@ -2581,20 +3253,20 @@ async function detectProjectManagement(rootDir) {
     } catch {
     }
   }
-  if (await fileExists(path17.join(rootDir, ".github", "ISSUE_TEMPLATE"))) {
+  if (await fileExists(path19.join(rootDir, ".github", "ISSUE_TEMPLATE"))) {
     tools.push("github-issues");
   }
-  if (await fileExists(path17.join(rootDir, ".github", "projects"))) {
+  if (await fileExists(path19.join(rootDir, ".github", "projects"))) {
     tools.push("github-projects");
   }
   return [...new Set(tools)];
 }
 async function detectServices(rootDir) {
-  const hasPrisma = await fileExists(path17.join(rootDir, "prisma/schema.prisma"));
-  const hasSequelize = await fileExists(path17.join(rootDir, "sequelize"));
-  const hasDrizzle = await fileExists(path17.join(rootDir, "drizzle.config.ts"));
-  const hasKnex = await fileExists(path17.join(rootDir, "knexfile.ts"));
-  const hasTypeorm = await fileExists(path17.join(rootDir, "ormconfig.json"));
+  const hasPrisma = await fileExists(path19.join(rootDir, "prisma/schema.prisma"));
+  const hasSequelize = await fileExists(path19.join(rootDir, "sequelize"));
+  const hasDrizzle = await fileExists(path19.join(rootDir, "drizzle.config.ts"));
+  const hasKnex = await fileExists(path19.join(rootDir, "knexfile.ts"));
+  const hasTypeorm = await fileExists(path19.join(rootDir, "ormconfig.json"));
   const database = hasPrisma || hasSequelize || hasDrizzle || hasKnex || hasTypeorm ? "postgresql" : void 0;
   const orm = hasPrisma ? "prisma" : hasDrizzle ? "drizzle" : hasSequelize ? "sequelize" : hasKnex ? "knex" : hasTypeorm ? "typeorm" : void 0;
   const projectManagement = await detectProjectManagement(rootDir);
@@ -2606,7 +3278,7 @@ async function detectServices(rootDir) {
 }
 
 // src/scanner/detect-stack.ts
-import path18 from "path";
+import path20 from "path";
 var PROJECT_MARKERS = [
   "package.json",
   "requirements.txt",
@@ -2635,7 +3307,7 @@ async function detectPackageManager(rootDir, packageJson) {
     };
   }
   for (const [lockfile, packageManager] of LOCKFILES) {
-    if (await fileExists(path18.join(rootDir, lockfile))) {
+    if (await fileExists(path20.join(rootDir, lockfile))) {
       return {
         packageManager,
         evidence: [{ source: "file", value: lockfile }]
@@ -2652,27 +3324,27 @@ function commandsForScripts(scripts, packageManager) {
   return { testCommands, validationCommands };
 }
 async function detectStack(rootDir) {
-  const hasAnyProjectMarker = (await Promise.all(PROJECT_MARKERS.map((item) => fileExists(path18.join(rootDir, item))))).some(Boolean);
-  const hasPackageJson = await fileExists(path18.join(rootDir, "package.json"));
+  const hasAnyProjectMarker = (await Promise.all(PROJECT_MARKERS.map((item) => fileExists(path20.join(rootDir, item))))).some(Boolean);
+  const hasPackageJson = await fileExists(path20.join(rootDir, "package.json"));
   if (hasPackageJson) {
-    const packageJson = await readJson(path18.join(rootDir, "package.json")) ?? {};
+    const packageJson = await readJson(path20.join(rootDir, "package.json")) ?? {};
     const scripts = packageJson.scripts ?? {};
     const packageManager = await detectPackageManager(rootDir, packageJson);
     const commands = commandsForScripts(scripts, packageManager.packageManager);
-    const hasNextConfig = await fileExists(path18.join(rootDir, "next.config.js")) || await fileExists(path18.join(rootDir, "next.config.mjs")) || await fileExists(path18.join(rootDir, "next.config.ts"));
-    const hasNestConfig = await fileExists(path18.join(rootDir, "nest-cli.json"));
+    const hasNextConfig = await fileExists(path20.join(rootDir, "next.config.js")) || await fileExists(path20.join(rootDir, "next.config.mjs")) || await fileExists(path20.join(rootDir, "next.config.ts"));
+    const hasNestConfig = await fileExists(path20.join(rootDir, "nest-cli.json"));
     return {
       language: "node",
       framework: hasNextConfig ? "nextjs" : hasNestConfig ? "nestjs" : "node",
       packageManager: packageManager.packageManager,
       packageManagerEvidence: packageManager.evidence,
       scripts,
-      workspaces: packageJson.workspaces !== void 0 || await fileExists(path18.join(rootDir, "pnpm-workspace.yaml")),
+      workspaces: packageJson.workspaces !== void 0 || await fileExists(path20.join(rootDir, "pnpm-workspace.yaml")),
       ...commands,
       hasProjectFiles: hasAnyProjectMarker
     };
   }
-  if (await fileExists(path18.join(rootDir, "pyproject.toml"))) {
+  if (await fileExists(path20.join(rootDir, "pyproject.toml"))) {
     return {
       language: "python",
       framework: "python",
@@ -2682,7 +3354,7 @@ async function detectStack(rootDir) {
       hasProjectFiles: hasAnyProjectMarker
     };
   }
-  if (await fileExists(path18.join(rootDir, "go.mod"))) {
+  if (await fileExists(path20.join(rootDir, "go.mod"))) {
     return {
       language: "go",
       framework: "go",
@@ -2692,7 +3364,7 @@ async function detectStack(rootDir) {
       hasProjectFiles: hasAnyProjectMarker
     };
   }
-  if (await fileExists(path18.join(rootDir, "Cargo.toml"))) {
+  if (await fileExists(path20.join(rootDir, "Cargo.toml"))) {
     return {
       language: "rust",
       framework: "rust",
@@ -2702,7 +3374,7 @@ async function detectStack(rootDir) {
       hasProjectFiles: hasAnyProjectMarker
     };
   }
-  if (await fileExists(path18.join(rootDir, "composer.json"))) {
+  if (await fileExists(path20.join(rootDir, "composer.json"))) {
     return {
       language: "php",
       framework: "php",
@@ -2735,7 +3407,7 @@ function isGreenfieldByEntries(entries) {
   return meaningful.length === 0;
 }
 async function runScanner(rootDir) {
-  const normalizedRoot = path19.resolve(rootDir);
+  const normalizedRoot = path21.resolve(rootDir);
   const entries = await listDirectory(normalizedRoot);
   const stack = await detectStack(normalizedRoot);
   const purpose = await detectPurpose(normalizedRoot, stack);
@@ -2939,7 +3611,7 @@ async function executeSafeReadinessFixes(rootDir, options) {
   });
   const changes = [];
   for (const relativePath of ESSENTIAL_DIRECTORIES) {
-    const absolutePath = path20.join(beforeScan.rootDir, relativePath);
+    const absolutePath = path22.join(beforeScan.rootDir, relativePath);
     const exists2 = await fileExists(absolutePath);
     if (!exists2 && !dryRun) await ensureDir(absolutePath);
     recordChange(
@@ -2952,11 +3624,11 @@ async function executeSafeReadinessFixes(rootDir, options) {
     );
   }
   const gitignoreRelativePath = ".gitignore";
-  const gitignorePath = path20.join(beforeScan.rootDir, gitignoreRelativePath);
-  const existingGitignore = await fileExists(gitignorePath) ? await readFile9(gitignorePath, "utf8") : "";
+  const gitignorePath = path22.join(beforeScan.rootDir, gitignoreRelativePath);
+  const existingGitignore = await fileExists(gitignorePath) ? await readFile11(gitignorePath, "utf8") : "";
   const mergedGitignore = mergeSecretIgnores(existingGitignore);
   const gitignoreChanged = mergedGitignore !== existingGitignore;
-  if (gitignoreChanged && !dryRun) await writeFile3(gitignorePath, mergedGitignore, "utf8");
+  if (gitignoreChanged && !dryRun) await writeFile4(gitignorePath, mergedGitignore, "utf8");
   recordChange(
     changes,
     "merge-secret-ignores",
@@ -2968,7 +3640,7 @@ async function executeSafeReadinessFixes(rootDir, options) {
       gitignoreChanged ? "required secret patterns are missing" : "required patterns are present"
     )
   );
-  const profilePath = path20.join(beforeScan.rootDir, PROFILE_RELATIVE_PATH);
+  const profilePath = path22.join(beforeScan.rootDir, PROFILE_RELATIVE_PATH);
   const existingProfile = await readJson(profilePath) ?? {};
   const desiredProfile = createProfile(beforeScan, before, generatedAt);
   const mergedProfile = mergeMissing(existingProfile, desiredProfile);
@@ -2990,7 +3662,7 @@ async function executeSafeReadinessFixes(rootDir, options) {
     generatorVersion: options.generatorVersion,
     generatedAt
   });
-  const contextConfigPath = path20.join(beforeScan.rootDir, CONTEXT_CONFIG_RELATIVE_PATH);
+  const contextConfigPath = path22.join(beforeScan.rootDir, CONTEXT_CONFIG_RELATIVE_PATH);
   const existingContextConfig = await readJson(contextConfigPath) ?? {};
   const onboarding = reconcileOnboardingState(evidenceReport, existingContextConfig, generatedAt);
   const defaults = preferenceDefaults(onboarding, existingContextConfig.onboarded);
@@ -3019,17 +3691,17 @@ async function executeSafeReadinessFixes(rootDir, options) {
 }
 
 // src/scanner/snapshot.ts
-import path21 from "path";
+import path23 from "path";
 var READINESS_SNAPSHOT_RELATIVE_PATH = ".cursor/context/readiness.json";
 async function writeReadinessSnapshot(rootDir, report) {
-  const snapshotPath = path21.join(rootDir, READINESS_SNAPSHOT_RELATIVE_PATH);
+  const snapshotPath = path23.join(rootDir, READINESS_SNAPSHOT_RELATIVE_PATH);
   await writeJson(snapshotPath, report);
   return snapshotPath;
 }
 
 // src/commands/doctor.ts
 async function runDoctor(cwd, options = {}) {
-  const rootDir = path22.resolve(cwd);
+  const rootDir = path24.resolve(cwd);
   const hooks = await assessHooksHealth(rootDir);
   if (options.fixSafe) {
     const execution = await executeSafeReadinessFixes(rootDir, {
@@ -3063,11 +3735,22 @@ function printDoctorSummary(result) {
       console.log(`  - ${reason}`);
     }
   }
+  if (result.hooks.advisories.length > 0) {
+    console.log("hooks advisories (soft; install via cp, see git-hooks/README.md):");
+    for (const tip of result.hooks.advisories.slice(0, 5)) {
+      console.log(`  - ${tip}`);
+    }
+  }
+  if (process.env.ALLOW_MAIN_PUSH === "1") {
+    console.log("\u26A0\uFE0F  WARNING: ALLOW_MAIN_PUSH=1 is set in environment");
+    console.log("   This disables main-push protection for agent Shell commands.");
+    console.log("   Consider unsetting it: unset ALLOW_MAIN_PUSH");
+  }
   console.log(
     nextAction ? `Next: ${nextAction.recommendation}` : "Next: repository readiness checks are complete"
   );
 }
-var doctorCommand = defineCommand6({
+var doctorCommand = defineCommand7({
   meta: {
     name: "doctor",
     description: "Diagnose repository readiness and optionally apply safe local fixes."
@@ -3101,7 +3784,7 @@ var doctorCommand = defineCommand6({
 // src/commands/guard.ts
 import { execFile as execFile4 } from "child_process";
 import { promisify as promisify4 } from "util";
-import { defineCommand as defineCommand7 } from "citty";
+import { defineCommand as defineCommand8 } from "citty";
 
 // src/hooks/read-stdin-json.ts
 async function readStdinJson() {
@@ -3187,10 +3870,53 @@ var PROTECTED_BRANCH_RE = /^(?:main|master|prod)$/;
 function normalizeShellCommand(command) {
   return command.replace(/\s+/g, " ").trim();
 }
-function shellInvocationHeads(command) {
+function shellSegments(command) {
   const normalized = normalizeShellCommand(command);
   if (!normalized) return [];
-  return normalized.split(/(?:&&|\|\||[;|])/).map((part) => part.trim().replace(/^(?:\w+=\S+\s+)*/, "")).filter(Boolean);
+  return normalized.split(/(?:&&|\|\||[;|])/).map((part) => part.trim()).filter(Boolean);
+}
+function stripLeadingEnvAssignments(segment) {
+  return segment.replace(/^(?:\w+=\S+\s+)*/, "");
+}
+function shellInvocationHeads(command) {
+  return shellSegments(command).map(stripLeadingEnvAssignments).filter(Boolean);
+}
+function segmentHasAllowMainPushEnv(segment) {
+  if (process.env.ALLOW_MAIN_PUSH === "1") return true;
+  const leading = segment.match(/^(?:\w+=\S+\s+)*/)?.[0] ?? "";
+  return /(?:^|\s)ALLOW_MAIN_PUSH=1(?:\s|$)/.test(leading);
+}
+function hasForbiddenMainPushFlags(head) {
+  for (const t of head.split(/\s+/).filter(Boolean)) {
+    if (t === "--force" || t === "-f" || t === "--force-with-lease" || t === "--no-verify" || t === "--all" || t === "--tags") {
+      return true;
+    }
+  }
+  return false;
+}
+function isAuthorizedProdMainPush(head) {
+  if (!/^(?:[\w./-]+\/)?git\s+push\b/.test(head)) return false;
+  if (hasForbiddenMainPushFlags(head)) return false;
+  const after = head.replace(/^(?:[\w./-]+\/)?git\s+push\b/, "").trim();
+  const positional = [];
+  for (const t of after.split(/\s+/).filter(Boolean)) {
+    if (t.startsWith("-")) continue;
+    positional.push(t);
+  }
+  const refspec = positional.length === 2 ? positional[1] : void 0;
+  if (!refspec) return false;
+  const unquoted = refspec.replace(/['"\\]/g, "");
+  if (unquoted.startsWith("+")) return false;
+  if (unquoted.includes(":")) {
+    const src = unquoted.slice(0, unquoted.lastIndexOf(":"));
+    if (src !== "HEAD") return false;
+  }
+  const dest = unquoted.includes(":") ? unquoted.slice(unquoted.lastIndexOf(":") + 1) : unquoted;
+  return normalizePushRefspecToken(dest) === "main";
+}
+function segmentAllowsMainPush(segment) {
+  if (!segmentHasAllowMainPushEnv(segment)) return false;
+  return isAuthorizedProdMainPush(stripLeadingEnvAssignments(segment));
 }
 function anyHeadMatches(command, re) {
   return shellInvocationHeads(command).some((head) => re.test(head));
@@ -3200,9 +3926,7 @@ function isProtectedBranch(name) {
 }
 function normalizePushRefspecToken(token) {
   let t = token.trim();
-  if (t.startsWith("'") && t.endsWith("'") && t.length >= 2 || t.startsWith('"') && t.endsWith('"') && t.length >= 2) {
-    t = t.slice(1, -1).trim();
-  }
+  t = t.replace(/['"\\]/g, "");
   if (t.startsWith("+")) t = t.slice(1);
   if (t.startsWith("refs/heads/")) t = t.slice("refs/heads/".length);
   if (t.startsWith("origin/")) t = t.slice("origin/".length);
@@ -3271,7 +3995,9 @@ var SHELL_DENY_RULES = [
   {
     id: "git-push-main",
     description: "direct push to main/master/prod bypasses staging",
-    test: (cmd, opts) => shellInvocationHeads(cmd).some((head) => {
+    test: (cmd, opts) => shellSegments(cmd).some((segment) => {
+      if (segmentAllowsMainPush(segment)) return false;
+      const head = stripLeadingEnvAssignments(segment);
       if (!/^(?:[\w./-]+\/)?git\s+push\b/.test(head)) return false;
       if (pushHeadHasProtectedDest(head)) {
         return true;
@@ -3315,13 +4041,13 @@ async function detectCurrentBranch() {
     return void 0;
   }
 }
-var guardCommand = defineCommand7({
+var guardCommand = defineCommand8({
   meta: {
     name: "guard",
     description: "Mechanizable deny/annotate guards (shell, prompt). Hooks are thin adapters."
   },
   subCommands: {
-    shell: defineCommand7({
+    shell: defineCommand8({
       meta: {
         name: "shell",
         description: "Evaluate a shell command against the destructive deny-list"
@@ -3348,7 +4074,7 @@ var guardCommand = defineCommand7({
         console.log(JSON.stringify(result));
       }
     }),
-    prompt: defineCommand7({
+    prompt: defineCommand8({
       meta: {
         name: "prompt",
         description: "Scan prompt text for secret patterns (advisory; fail-open at hook)"
@@ -3382,9 +4108,9 @@ var guardCommand = defineCommand7({
 
 // src/commands/handoff.ts
 import { spawn as spawn3 } from "child_process";
-import { readFile as readFile10, readdir as readdir2, writeFile as writeFile4 } from "fs/promises";
-import path23 from "path";
-import { defineCommand as defineCommand8 } from "citty";
+import { readFile as readFile12, readdir as readdir4, writeFile as writeFile5 } from "fs/promises";
+import path25 from "path";
+import { defineCommand as defineCommand9 } from "citty";
 function parsePlanFrontmatter(raw) {
   const match = raw.match(/^---\n([\s\S]*?)\n---/);
   if (!match?.[1]) return null;
@@ -3401,21 +4127,21 @@ function parsePlanFrontmatter(raw) {
 }
 async function findActivePlan(plansDir) {
   if (!await fileExists(plansDir)) return null;
-  const files = (await readdir2(plansDir)).filter((f) => f.endsWith(".plan.md")).sort().reverse();
+  const files = (await readdir4(plansDir)).filter((f) => f.endsWith(".plan.md")).sort().reverse();
   for (const file of files) {
-    const raw = await readFile10(path23.join(plansDir, file), "utf8");
+    const raw = await readFile12(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 readFile10(path23.join(plansDir, files[0]), "utf8") } : null;
+  return files[0] ? { file: files[0], raw: await readFile12(path25.join(plansDir, files[0]), "utf8") } : null;
 }
 function now() {
   return (/* @__PURE__ */ new Date()).toISOString().replace("T", " ").slice(0, 16);
 }
 async function loadProfile(rootDir) {
-  const configPath = path23.join(rootDir, ".cursor", "agent-kit.config.json");
+  const configPath = path25.join(rootDir, ".cursor", "agent-kit.config.json");
   try {
     return await readJson(configPath);
   } catch {
@@ -3501,7 +4227,7 @@ function runCursorHandoff(scriptPath, cwd) {
     child.on("close", (code) => resolve(code ?? 1));
   });
 }
-var handoffCommand = defineCommand8({
+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."
@@ -3515,15 +4241,15 @@ var handoffCommand = defineCommand8({
   },
   async run({ args }) {
     const profile = await loadProfile(args.cwd);
-    const plansDir = path23.join(args.cwd, ".cursor", "plans");
-    const handoffPath = path23.join(args.cwd, ".cursor", "HANDOFF.md");
+    const plansDir = path25.join(args.cwd, ".cursor", "plans");
+    const handoffPath = path25.join(args.cwd, ".cursor", "HANDOFF.md");
     const plan = await findActivePlan(plansDir);
     if (plan) {
       const fm = parsePlanFrontmatter(plan.raw);
       if (fm) {
-        await ensureDir(path23.join(args.cwd, ".cursor"));
+        await ensureDir(path25.join(args.cwd, ".cursor"));
         const content = buildHandoff(plan.file, fm, profile);
-        await writeFile4(handoffPath, content, "utf8");
+        await writeFile5(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)`
@@ -3541,7 +4267,7 @@ var handoffCommand = defineCommand8({
       }
       logger.warn(`Plan ${plan.file} without valid frontmatter; trying legacy flow.`);
     }
-    const scriptPath = path23.join(args.cwd, "cursor-handoff");
+    const scriptPath = path25.join(args.cwd, "cursor-handoff");
     if (!await fileExists(scriptPath)) {
       printV3Guidance();
       return;
@@ -3566,8 +4292,8 @@ var handoffCommand = defineCommand8({
 });
 
 // src/commands/hook.ts
-import path25 from "path";
-import { defineCommand as defineCommand9 } from "citty";
+import path27 from "path";
+import { defineCommand as defineCommand10 } from "citty";
 
 // src/hooks/pre-compact.ts
 function buildPreCompactUserMessage(payload = {}) {
@@ -3580,8 +4306,8 @@ function buildPreCompactUserMessage(payload = {}) {
 
 // src/hooks/session-start.ts
 import { spawn as spawn4 } from "child_process";
-import { access as access5, readFile as readFile11 } from "fs/promises";
-import path24 from "path";
+import { access as access5, readFile as readFile13 } from "fs/promises";
+import path26 from "path";
 
 // src/invariants/handoff-schema.ts
 var MACHINE_LIST_CHECKS = [
@@ -3638,18 +4364,24 @@ var HARD_RULES = `# Agent Kit session hard rules (manual mode default)
 11. **HANDOFF machine fields are bullet fields, not \`##\` headings.** Mission Control parses \`- **Plan:**\`, \`- **Backlog plans:**\`, \`- **Parked plans:**\`, \`- **Run queue:**\` (etc.). Canonical Plan: \`- **Plan:** \\\`name.plan.md\\\`\` or \`none\`. Nested backlog/parked rows: \`- \\\`other.plan.md\\\`\`. Never invent \`## Backlog plans\` / \`## Parked plans\` / \`## Run queue\` headings in place of those fields (Checklist / Current mission go empty or idle).`;
 var DOGFOOD_INBOX_HINT = `## Dogfood inbox
 
-Unprocessed files are listed under \`dogfood/README.md\` (### Unprocessed Files). Follow the ingest ritual there (detect \u2192 analyze \u2192 memory WRITE \u2192 triage). Do not auto-start analysis unless the user asks.`;
+Unprocessed files are listed under \`dogfood/README.md\` (factory) or \`.cursor/dogfood/README.md\` (consumer). To file a new note, use \`/dogfood <topic> [summary]\`. Follow the ingest ritual (detect \u2192 analyze \u2192 memory WRITE \u2192 triage). Do not auto-start analysis unless the user asks.`;
 var UPDATE_CHECK_NUDGE = `## Agent Kit update available
 
 Installed **v{installed}**; latest public **v{latest}**.
 
 This is an advisory only (no files were changed). To apply, run \`/update\` and confirm via Ask questions. Bare \`agent-kit update\` is an explicit operator invoke, not a background job.`;
+var CURSOR_AWARENESS_NUDGE = `## Cursor product-update awareness
+
+Advisory gaps vs \`docs/cursor-native-audit.md\` (check-only; no apply; no Field Reports).
+
+Run \`/cursor-update-awareness\` (or \`agent-kit cursor-awareness --check\`) and confirm routing via Ask \u2192 \`/backlog-add\` or \`/dogfood\`.`;
 
 // src/hooks/session-start.ts
 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 readFile11(filePath, "utf8")).split(/\r?\n/);
+    const lines = (await readFile13(filePath, "utf8")).split(/\r?\n/);
     return lines.slice(0, limit).join("\n").trim();
   } catch {
     return "";
@@ -3657,7 +4389,7 @@ async function readTextLimited(filePath, limit = 60) {
 }
 async function readFull(filePath) {
   try {
-    return await readFile11(filePath, "utf8");
+    return await readFile13(filePath, "utf8");
   } catch {
     return "";
   }
@@ -3690,8 +4422,8 @@ function parseUnprocessedDogfoodItems(readmeText) {
   return items;
 }
 async function l0Present(root) {
-  const cursor = path24.join(root, ".cursor");
-  return await fileExists2(path24.join(cursor, "agent-kit.json")) || await fileExists2(path24.join(cursor, "commands", "agent-kit-onboard.md")) || await fileExists2(path24.join(cursor, "commands", "start-project.md"));
+  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"));
 }
 function checkLabelAndRecommendation(check2) {
   const checkId = check2.id;
@@ -3730,10 +4462,10 @@ function unresolvedReadinessChecks(data) {
   return { essential, nonessential };
 }
 async function readinessSection(root) {
-  const snapshotPath = path24.join(root, ".cursor", "context", "readiness.json");
+  const snapshotPath = path26.join(root, ".cursor", "context", "readiness.json");
   let data;
   try {
-    data = JSON.parse(await readFile11(snapshotPath, "utf8"));
+    data = JSON.parse(await readFile13(snapshotPath, "utf8"));
   } catch {
     return null;
   }
@@ -3763,22 +4495,24 @@ Optional readiness item: \`${actionId}\`. ${recommendation} This does not block
 Optional readiness item: \`${first.id}\`. ${first.recommendation} This does not block \`/start-project\` or active plan work. Resume later with \`/agent-kit-onboard\` if useful.`;
 }
 async function dogfoodInboxSection(root) {
-  const dogfoodDir = path24.join(root, "dogfood");
-  if (!await fileExists2(dogfoodDir)) return null;
-  const readme = path24.join(dogfoodDir, "README.md");
-  if (!await fileExists2(readme)) return null;
-  try {
-    const text = await readFile11(readme, "utf8");
-    if (!parseUnprocessedDogfoodItems(text).length) return null;
-    return DOGFOOD_INBOX_HINT;
-  } catch {
-    return null;
+  const candidateReadmes = [
+    path26.join(root, "dogfood", "README.md"),
+    path26.join(root, ".cursor", "dogfood", "README.md")
+  ];
+  for (const readme of candidateReadmes) {
+    if (!await fileExists2(readme)) continue;
+    try {
+      const text = await readFile13(readme, "utf8");
+      if (parseUnprocessedDogfoodItems(text).length) return DOGFOOD_INBOX_HINT;
+    } catch {
+    }
   }
+  return null;
 }
 async function loadUpdateCheckPrefs(root) {
   try {
     const data = JSON.parse(
-      await readFile11(path24.join(root, ".cursor", "context", "config.json"), "utf8")
+      await readFile13(path26.join(root, ".cursor", "context", "config.json"), "utf8")
     );
     const uc = data.updateCheck;
     if (!uc || typeof uc !== "object" || uc.enabled !== true) {
@@ -3853,9 +4587,111 @@ async function updateCheckSection(root) {
   const latest = String(result.latestVersion ?? "?");
   return UPDATE_CHECK_NUDGE.replace("{installed}", installed).replace("{latest}", latest);
 }
+async function loadCursorUpdateCheckPrefs(root) {
+  try {
+    const data = JSON.parse(
+      await readFile13(path26.join(root, ".cursor", "context", "config.json"), "utf8")
+    );
+    const uc = data.cursorUpdateCheck;
+    if (!uc || typeof uc !== "object" || uc.enabled !== true) {
+      return null;
+    }
+    return uc;
+  } catch {
+    return null;
+  }
+}
+function runCursorAwarenessJson(root) {
+  return new Promise((resolve) => {
+    const child = spawn4(
+      process.execPath,
+      [
+        process.argv[1] ?? "",
+        "cursor-awareness",
+        "--check",
+        "--json",
+        "--respect-prefs",
+        "--stamp",
+        "--cwd",
+        root
+      ],
+      { stdio: ["ignore", "pipe", "ignore"], timeout: CURSOR_AWARENESS_SPAWN_TIMEOUT_MS }
+    );
+    let out = "";
+    child.stdout?.on("data", (chunk) => {
+      out += chunk.toString("utf8");
+    });
+    child.on("error", () => resolve(null));
+    child.on("close", () => {
+      try {
+        const parsed = JSON.parse(out.trim());
+        resolve(parsed && typeof parsed === "object" ? parsed : null);
+      } catch {
+        resolve(null);
+      }
+    });
+  });
+}
+function shouldEmitCursorAwarenessNudge(result) {
+  if (!result || result.status !== "gaps-found") return false;
+  if (result.applyRecommended === true || result.fieldReportRecommended === true) return false;
+  const gaps = Array.isArray(result.gaps) ? result.gaps : [];
+  return gaps.some(
+    (g) => g && typeof g === "object" && g.id === "changelog-ahead"
+  );
+}
+async function cursorAwarenessSection(root, deps = {}) {
+  if (await loadCursorUpdateCheckPrefs(root) === null) return null;
+  const spawnFn = deps.spawnFn ?? spawn4;
+  const runFallback = deps.runFallback ?? runCursorAwarenessJson;
+  const result = await new Promise((resolve) => {
+    let settled = false;
+    let fallbackStarted = false;
+    const finish = (value) => {
+      if (settled) return;
+      settled = true;
+      resolve(value);
+    };
+    const startFallback = () => {
+      if (settled || fallbackStarted) return;
+      fallbackStarted = true;
+      void runFallback(root).then(finish);
+    };
+    const child = spawnFn(
+      "agent-kit",
+      ["cursor-awareness", "--check", "--json", "--respect-prefs", "--stamp", "--cwd", root],
+      {
+        stdio: ["ignore", "pipe", "ignore"],
+        timeout: CURSOR_AWARENESS_SPAWN_TIMEOUT_MS,
+        shell: false
+      }
+    );
+    let out = "";
+    child.stdout?.on("data", (chunk) => {
+      out += chunk.toString("utf8");
+    });
+    child.on("error", () => {
+      startFallback();
+    });
+    child.on("close", (code) => {
+      if (settled || fallbackStarted) return;
+      if (code !== 0 && !out.trim()) {
+        startFallback();
+        return;
+      }
+      try {
+        finish(JSON.parse(out.trim()));
+      } catch {
+        startFallback();
+      }
+    });
+  });
+  if (!shouldEmitCursorAwarenessNudge(result)) return null;
+  return CURSOR_AWARENESS_NUDGE;
+}
 async function buildSessionStartAdditionalContext(rootDir, _payload = {}) {
-  const root = path24.resolve(rootDir);
-  const handoffPath = path24.join(root, ".cursor", "HANDOFF.md");
+  const root = path26.resolve(rootDir);
+  const handoffPath = path26.join(root, ".cursor", "HANDOFF.md");
   const handoffFull = await readFull(handoffPath);
   const handoff = await readTextLimited(handoffPath);
   const parts = [HARD_RULES];
@@ -3867,6 +4703,8 @@ async function buildSessionStartAdditionalContext(rootDir, _payload = {}) {
   if (dogfood) parts.push(dogfood);
   const updateNudge = await updateCheckSection(root);
   if (updateNudge) parts.push(updateNudge);
+  const cursorNudge = await cursorAwarenessSection(root);
+  if (cursorNudge) parts.push(cursorNudge);
   const formatWarnings = validateHandoffText(handoffFull);
   if (formatWarnings.length) {
     const bullet = formatWarnings.map((w) => `- ${w.message}`).join("\n");
@@ -3898,13 +4736,13 @@ function resolveSessionRoot(payload, cwd = process.cwd()) {
 }
 
 // src/commands/hook.ts
-var hookCommand = defineCommand9({
+var hookCommand = defineCommand10({
   meta: {
     name: "hook",
     description: "Cursor hook adapters (session-start, pre-compact). CLI is SoT; thin hooks shell out here."
   },
   subCommands: {
-    "session-start": defineCommand9({
+    "session-start": defineCommand10({
       meta: {
         name: "session-start",
         description: "Emit sessionStart additional_context JSON (stdin: Cursor payload)"
@@ -3918,12 +4756,12 @@ var hookCommand = defineCommand9({
       async run({ args }) {
         const payload = await readStdinJson();
         const cwd = typeof args.cwd === "string" ? args.cwd : process.cwd();
-        const root = resolveSessionRoot(payload, path25.resolve(cwd));
+        const root = resolveSessionRoot(payload, path27.resolve(cwd));
         const out = await buildSessionStartAdditionalContext(root, payload);
         console.log(JSON.stringify(out));
       }
     }),
-    "pre-compact": defineCommand9({
+    "pre-compact": defineCommand10({
       meta: {
         name: "pre-compact",
         description: "Emit preCompact user_message JSON (stdin: Cursor payload)"
@@ -3938,15 +4776,15 @@ var hookCommand = defineCommand9({
 
 // src/commands/init.ts
 import { intro, outro } from "@clack/prompts";
-import { defineCommand as defineCommand11 } from "citty";
+import { defineCommand as defineCommand12 } from "citty";
 
 // src/commands/install.ts
-import path28 from "path";
-import { defineCommand as defineCommand10 } from "citty";
+import path30 from "path";
+import { defineCommand as defineCommand11 } from "citty";
 
 // src/generator/personalization.ts
-import { readFile as readFile12, writeFile as writeFile5 } from "fs/promises";
-import path26 from "path";
+import { readFile as readFile14, writeFile as writeFile6 } from "fs/promises";
+import path28 from "path";
 var PERSONALIZATION_CONTRACT_VERSION = 1;
 var CONTEXT_PATH = ".cursor/project-context.md";
 var AGENTS_PATH = "AGENTS.md";
@@ -4097,7 +4935,7 @@ function renderProjectContext(profile) {
 `;
 }
 async function createOwnedFile(rootDir, relativePath, content, evidence) {
-  const target = path26.join(rootDir, relativePath);
+  const target = path28.join(rootDir, relativePath);
   if (await fileExists(target)) {
     return {
       kind: "file",
@@ -4107,8 +4945,8 @@ async function createOwnedFile(rootDir, relativePath, content, evidence) {
       evidence
     };
   }
-  await ensureDir(path26.dirname(target));
-  await writeFile5(target, content, "utf8");
+  await ensureDir(path28.dirname(target));
+  await writeFile6(target, content, "utf8");
   return {
     kind: "file",
     id: relativePath,
@@ -4124,7 +4962,7 @@ async function packTargets(registryRoot, packId) {
 async function existingTargets(projectRoot, targets) {
   const checks = await Promise.all(
     targets.map(
-      async (target) => await fileExists(path26.join(projectRoot, target)) ? target : null
+      async (target) => await fileExists(path28.join(projectRoot, target)) ? target : null
     )
   );
   return checks.filter((target) => target !== null);
@@ -4146,14 +4984,14 @@ async function applyPersonalization(input) {
         componentResults.push({ ...item, status: "unavailable" });
         continue;
       }
-      const target = path26.posix.join(
+      const target = path28.posix.join(
         ".cursor",
         "skills",
         skill.path.includes("/core/") ? "core" : "community",
         skill.id,
         "SKILL.md"
       );
-      if (await fileExists(path26.join(input.rootDir, target))) {
+      if (await fileExists(path28.join(input.rootDir, target))) {
         componentResults.push({ ...item, status: "skipped-customized", path: target });
         protectedPaths.add(target);
         continue;
@@ -4208,7 +5046,7 @@ async function applyPersonalization(input) {
     items: [...fileResults, ...componentResults],
     protectedPaths: [...protectedPaths].sort()
   };
-  await writeJson(path26.join(input.rootDir, RESULT_PATH), result);
+  await writeJson(path28.join(input.rootDir, RESULT_PATH), result);
   return {
     result,
     manifest: {
@@ -4226,27 +5064,27 @@ async function applyPersonalization(input) {
   };
 }
 async function readRepositoryProfile(rootDir) {
-  const target = path26.join(rootDir, ".cursor/agent-kit.config.json");
+  const target = path28.join(rootDir, ".cursor/agent-kit.config.json");
   if (!await fileExists(target)) return null;
-  return JSON.parse(await readFile12(target, "utf8"));
+  return JSON.parse(await readFile14(target, "utf8"));
 }
 
 // src/lifecycle/onboard-migration.ts
-import { createHash as createHash3 } from "crypto";
-import { readFile as readFile13, unlink } from "fs/promises";
-import path27 from "path";
+import { createHash as createHash4 } from "crypto";
+import { readFile as readFile15, unlink } from "fs/promises";
+import path29 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 = path27.join(projectRoot, LEGACY_ONBOARD_PATH);
+  const legacyPath = path29.join(projectRoot, LEGACY_ONBOARD_PATH);
   if (!await fileExists(legacyPath)) return "absent";
-  const namespacedPath = path27.join(projectRoot, NAMESPACED_ONBOARD_PATH);
+  const namespacedPath = path29.join(projectRoot, NAMESPACED_ONBOARD_PATH);
   if (!await fileExists(namespacedPath)) return "preserved-customized";
-  const content = await readFile13(legacyPath);
-  const hash = createHash3("sha256").update(content).digest("hex");
+  const content = await readFile15(legacyPath);
+  const hash = createHash4("sha256").update(content).digest("hex");
   if (!managedHashes.has(hash)) return "preserved-customized";
   await unlink(legacyPath);
   return "removed-managed";
@@ -4255,16 +5093,20 @@ async function migrateLegacyOnboardCommand(projectRoot, managedHashes = MANAGED_
 // src/lifecycle/sync.ts
 async function installL0(registryRoot, projectRoot, protectedGlobs) {
   const stats = emptyStats();
+  const managedHashes = await loadManagedHashLedger(projectRoot);
+  const copyOpts = { managedHashes, persistManagedHashes: false };
   for (const artifact of L0_ARTIFACTS) {
     const outcome = await copyRegistryFile(
       registryRoot,
       projectRoot,
       artifact.source,
       artifact.target,
-      protectedGlobs
+      protectedGlobs,
+      copyOpts
     );
     recordOutcome(stats, artifact.target, outcome);
   }
+  await saveManagedHashLedger(projectRoot, managedHashes);
   const migration = await migrateLegacyOnboardCommand(projectRoot);
   if (migration === "removed-managed") {
     stats.removed.push(".cursor/commands/onboard.md");
@@ -4314,7 +5156,7 @@ function printReadinessNarrative(result) {
   );
 }
 async function performInstall(options) {
-  const projectRoot = path28.resolve(options.cwd);
+  const projectRoot = path30.resolve(options.cwd);
   const packs = parsePackList(options.pack);
   const existing = await loadAgentKitManifest(projectRoot);
   const registry = await resolveRegistryFromCli({
@@ -4368,7 +5210,7 @@ async function performInstall(options) {
     safeChanges: readinessExecution.changes
   };
 }
-var installCommand = defineCommand10({
+var installCommand = defineCommand11({
   meta: {
     name: "install",
     description: "Bootstrap L0 (+ optional packs) from the registry and write agent-kit.json."
@@ -4390,7 +5232,7 @@ var installCommand = defineCommand10({
     ...REGISTRY_CLI_ARGS
   },
   async run({ args }) {
-    const projectRoot = path28.resolve(args.cwd);
+    const projectRoot = path30.resolve(args.cwd);
     logger.info(`Installing into: ${projectRoot}`);
     const packs = parsePackList(args.pack);
     for (const id of packs) {
@@ -4418,7 +5260,7 @@ var installCommand = defineCommand10({
 async function runInitCompatibility(cwd, installer = performInstall) {
   return installer({ cwd });
 }
-var initCommand = defineCommand11({
+var initCommand = defineCommand12({
   meta: {
     name: "init",
     description: "Guided compatibility entry point for install and repository readiness."
@@ -4443,13 +5285,13 @@ var initCommand = defineCommand11({
 });
 
 // src/commands/monitors.ts
-import path30 from "path";
-import { defineCommand as defineCommand12 } from "citty";
+import path32 from "path";
+import { defineCommand as defineCommand13 } from "citty";
 
 // src/invariants/monitors-untriaged.ts
 import { execFile as execFile5 } from "child_process";
-import { readFile as readFile14, readdir as readdir3, stat as stat2 } from "fs/promises";
-import path29 from "path";
+import { readFile as readFile16, readdir as readdir5, stat as stat2 } from "fs/promises";
+import path31 from "path";
 import { promisify as promisify5 } from "util";
 
 // src/invariants/triage-heading.ts
@@ -4473,7 +5315,7 @@ function hasOpenGaps(content) {
 }
 async function listMonitorFiles(memoryDir) {
   try {
-    const names = await readdir3(memoryDir);
+    const names = await readdir5(memoryDir);
     return names.filter((n) => n.startsWith("plan-monitor-") && n.endsWith(".md")).sort();
   } catch {
     return [];
@@ -4490,7 +5332,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 = path29.basename(file);
+      const base = path31.basename(file);
       if (base.startsWith("plan-monitor-") && base.endsWith(".md")) {
         names.add(base);
       }
@@ -4513,15 +5355,15 @@ function monitorSlugFromName(fileName) {
   return fileName.replace(/^plan-monitor-/, "").replace(/\.md$/, "").toLowerCase();
 }
 async function selectUntriagedMonitors(rootDir) {
-  const root = path29.resolve(rootDir);
-  const memoryDir = path29.join(root, ".cursor", "memory");
+  const root = path31.resolve(rootDir);
+  const memoryDir = path31.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 = path29.join(memoryDir, name);
+    const abs = path31.join(memoryDir, name);
     try {
-      const [content, st] = await Promise.all([readFile14(abs, "utf8"), stat2(abs)]);
+      const [content, st] = await Promise.all([readFile16(abs, "utf8"), stat2(abs)]);
       byName.set(name, { content, mtimeMs: st.mtimeMs });
     } catch {
     }
@@ -4534,7 +5376,7 @@ async function selectUntriagedMonitors(rootDir) {
   const gitFreshSet = [...gitFresh].filter(untriaged).sort();
   let handoff = "";
   try {
-    handoff = await readFile14(path29.join(root, ".cursor", "HANDOFF.md"), "utf8");
+    handoff = await readFile16(path31.join(root, ".cursor", "HANDOFF.md"), "utf8");
   } catch {
     handoff = "";
   }
@@ -4554,8 +5396,8 @@ async function selectUntriagedMonitors(rootDir) {
     const row = byName.get(name);
     if (!row) continue;
     entries.push({
-      path: path29.join(memoryDir, name),
-      relativePath: path29.relative(root, path29.join(memoryDir, name)).split(path29.sep).join("/"),
+      path: path31.join(memoryDir, name),
+      relativePath: path31.relative(root, path31.join(memoryDir, name)).split(path31.sep).join("/"),
       mtimeMs: row.mtimeMs,
       hasTriageHeading: false,
       hasOpenGaps: hasOpenGaps(row.content),
@@ -4574,7 +5416,7 @@ async function selectUntriagedMonitors(rootDir) {
 }
 
 // src/commands/monitors.ts
-var monitorsCommand = defineCommand12({
+var monitorsCommand = defineCommand13({
   meta: {
     name: "monitors",
     description: "Plan-monitor selection helpers (untriaged SoT for /plan-review-triage)"
@@ -4601,7 +5443,7 @@ var monitorsCommand = defineCommand12({
       process.exitCode = 2;
       return;
     }
-    const result = await selectUntriagedMonitors(path30.resolve(args.cwd));
+    const result = await selectUntriagedMonitors(path32.resolve(args.cwd));
     if (args.json) {
       console.log(JSON.stringify(result, null, 2));
       return;
@@ -4617,8 +5459,8 @@ var monitorsCommand = defineCommand12({
 });
 
 // src/commands/run-plan.ts
-import path35 from "path";
-import { defineCommand as defineCommand13 } from "citty";
+import path37 from "path";
+import { defineCommand as defineCommand14 } from "citty";
 
 // src/plan-loop/backends.ts
 import { execFileSync as execFileSync2, spawn as spawn5 } from "child_process";
@@ -4702,14 +5544,14 @@ function listBackendIds() {
 }
 
 // src/plan-loop/run-loop.ts
-import { mkdir as mkdir4, readFile as readFile17, rm, unlink as unlink2 } from "fs/promises";
-import path34 from "path";
+import { mkdir as mkdir5, readFile as readFile19, rm, unlink as unlink2 } from "fs/promises";
+import path36 from "path";
 
 // src/plan-loop/external-review.ts
 import { spawn as spawn6 } from "child_process";
-import path31 from "path";
-var CANONICAL_REL = path31.join(".cursor", "scripts", "plan-external-review.sh");
-var FALLBACK_REL = path31.join("scripts", "plan-external-review.sh");
+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");
 function isPlanExhaustedReason(reason) {
   const r = reason.trim().toLowerCase();
   if (!r) return false;
@@ -4731,8 +5573,8 @@ async function armExternalPlanReview(root, options = {}) {
   const existsFn = options.existsFn ?? fileExists;
   const log = options.log ?? ((line) => console.log(line));
   const force = options.force === true;
-  const canonicalPath = path31.join(root, CANONICAL_REL);
-  const fallbackPath = path31.join(root, FALLBACK_REL);
+  const canonicalPath = path33.join(root, CANONICAL_REL);
+  const fallbackPath = path33.join(root, FALLBACK_REL);
   let scriptPath = null;
   let scriptRel = CANONICAL_REL;
   if (await existsFn(canonicalPath)) {
@@ -4785,7 +5627,7 @@ async function armExternalPlanReview(root, options = {}) {
 }
 
 // src/plan-loop/persona-banners.ts
-import path32 from "path";
+import path34 from "path";
 import {
   blue,
   cyan as cyan2,
@@ -4821,7 +5663,7 @@ function resolveColor(name, fallback) {
 async function resolveCliPersonaId(root) {
   try {
     const cfg = await readJson(
-      path32.join(root, ".cursor", "context", "config.json")
+      path34.join(root, ".cursor", "context", "config.json")
     );
     const modes = cfg?.agentPersona?.modes ?? cfg?.workspaceSkin?.modes;
     const id = modes?.[CLI_RUN_PLAN_MODE];
@@ -4832,7 +5674,7 @@ async function resolveCliPersonaId(root) {
 }
 async function loadPersonaPack(root, personaId) {
   try {
-    const personaPath = path32.join(root, "registry", "personas", "core", personaId, "persona.json");
+    const personaPath = path34.join(root, "registry", "personas", "core", personaId, "persona.json");
     const pack = await readJson(personaPath);
     if (!pack || typeof pack.id !== "string") return null;
     return pack;
@@ -4881,8 +5723,8 @@ function createPersonaBannerPrinter(persona) {
 }
 
 // src/plan-loop/plan-state.ts
-import { readFile as readFile15, readdir as readdir4 } from "fs/promises";
-import path33 from "path";
+import { readFile as readFile17, readdir as readdir6 } from "fs/promises";
+import path35 from "path";
 function countPendingTodos(raw) {
   const lines = raw.split(/\r?\n/);
   let inFront = 0;
@@ -4909,15 +5751,15 @@ function countPendingTodos(raw) {
 }
 async function findActivePlanFile(plansDir) {
   if (!await fileExists(plansDir)) return null;
-  const files = (await readdir4(plansDir)).filter((f) => f.endsWith(".plan.md")).sort();
-  return files[0] ? path33.join(plansDir, files[0]) : null;
+  const files = (await readdir6(plansDir)).filter((f) => f.endsWith(".plan.md")).sort();
+  return files[0] ? path35.join(plansDir, files[0]) : null;
 }
 async function readPlan(planPath) {
-  return readFile15(planPath, "utf8");
+  return readFile17(planPath, "utf8");
 }
 
 // src/plan-loop/sentinel.ts
-import { readFile as readFile16 } from "fs/promises";
+import { readFile as readFile18 } from "fs/promises";
 var SENTINEL_RE = /LOOP_TICK_RESULT:\s*(continue|stop(?:\s*[—\-].*)?)/i;
 function takeFromText(text) {
   if (!text) return null;
@@ -4964,7 +5806,7 @@ function parseSentinelFromLog(content) {
 }
 async function parseSentinelFromLogFile(logPath) {
   try {
-    const content = await readFile16(logPath, "utf8");
+    const content = await readFile18(logPath, "utf8");
     return parseSentinelFromLog(content);
   } catch {
     return { kind: "missing" };
@@ -4987,16 +5829,16 @@ function sleep(ms) {
   return new Promise((r) => setTimeout(r, ms));
 }
 async function runPlanLoop(opts) {
-  const plansDir = path34.join(opts.root, ".cursor", "plans");
-  const stopFile = path34.join(opts.root, ".cursor", "loop.stop");
-  const logDir = path34.join(opts.root, ".cursor", "loop-logs");
+  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 planPath = await findActivePlanFile(plansDir);
   if (!planPath) {
     logger.error("No active plan in .cursor/plans/");
     return 1;
   }
   const pending = async () => countPendingTodos(await readPlan(planPath));
-  await mkdir4(logDir, { recursive: true });
+  await mkdir5(logDir, { recursive: true });
   try {
     await unlink2(stopFile);
   } catch {
@@ -5010,7 +5852,7 @@ async function runPlanLoop(opts) {
   try {
     const persona = await loadCliRunPlanPersona(opts.root);
     const banners = createPersonaBannerPrinter(persona);
-    console.log(`Active plan: ${path34.basename(planPath)}`);
+    console.log(`Active plan: ${path36.basename(planPath)}`);
     console.log(`Pending to-dos: ${await pending()} | max ticks: ${opts.maxTicks}`);
     console.log(`Backend: ${opts.backend.id}`);
     if (persona) {
@@ -5053,8 +5895,8 @@ async function runPlanLoop(opts) {
         planExhausted = true;
         break;
       }
-      const logPath = path34.join(logDir, `tick-${stamp()}.log`);
-      const relLog = path34.relative(opts.root, logPath);
+      const logPath = path36.join(logDir, `tick-${stamp()}.log`);
+      const relLog = path36.relative(opts.root, logPath);
       console.log("");
       const tickLine = `=== tick ${tick}/${opts.maxTicks} - pending: ${before} - log: ${relLog} ===`;
       if (banners) banners.tickStart(tickLine);
@@ -5073,7 +5915,7 @@ async function runPlanLoop(opts) {
         return 1;
       }
       try {
-        const logText = await readFile17(logPath, "utf8");
+        const logText = await readFile19(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);
@@ -5130,7 +5972,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 ${path34.relative(opts.root, logDir)}/`
+      `Loop finished after ${tick} tick(s). Pending now: ${pendingNow}. Logs in ${path36.relative(opts.root, logDir)}/`
     );
     if (planExhausted || shouldArmExternalPlanReview({ pending: pendingNow, stopReason })) {
       await armExternalPlanReview(opts.root);
@@ -5142,7 +5984,7 @@ async function runPlanLoop(opts) {
 }
 
 // src/commands/run-plan.ts
-var runPlanCommand = defineCommand13({
+var runPlanCommand = defineCommand14({
   meta: {
     name: "run-plan",
     description: "Headless continuous plan runner: one fresh agent per tick (LOOP_TICK_RESULT contract). Never git-prod."
@@ -5201,7 +6043,7 @@ var runPlanCommand = defineCommand13({
       return;
     }
     const code = await runPlanLoop({
-      root: path35.resolve(args.cwd),
+      root: path37.resolve(args.cwd),
       maxTicks,
       sleepSeconds,
       model: args.model ? String(args.model) : void 0,
@@ -5213,8 +6055,8 @@ var runPlanCommand = defineCommand13({
 });
 
 // src/commands/scan.ts
-import { defineCommand as defineCommand14 } from "citty";
-var scanCommand = defineCommand14({
+import { defineCommand as defineCommand15 } from "citty";
+var scanCommand = defineCommand15({
   meta: {
     name: "scan",
     description: "Scan the current repository and print detected profile."
@@ -5235,8 +6077,8 @@ var scanCommand = defineCommand14({
 });
 
 // src/commands/status.ts
-import path36 from "path";
-import { defineCommand as defineCommand15 } from "citty";
+import path38 from "path";
+import { defineCommand as defineCommand16 } from "citty";
 function profileStatus(profile) {
   if (!profile) return { origin: "none", evidence: [], profile: null };
   if ("detection" in profile && profile.detection && typeof profile.detection === "object") {
@@ -5249,7 +6091,7 @@ function profileStatus(profile) {
   }
   return { origin: "legacy-wizard", evidence: [], profile };
 }
-var statusCommand = defineCommand15({
+var statusCommand = defineCommand16({
   meta: {
     name: "status",
     description: "Show Agent Kit distribution status (manifest + optional wizard profile)."
@@ -5266,11 +6108,11 @@ var statusCommand = defineCommand15({
     }
   },
   async run({ args }) {
-    const rootDir = path36.resolve(args.cwd);
+    const rootDir = path38.resolve(args.cwd);
     const [manifest, rawProfile, scan] = await Promise.all([
       loadAgentKitManifest(rootDir),
       readJson(
-        path36.join(rootDir, ".cursor", "agent-kit.config.json")
+        path38.join(rootDir, ".cursor", "agent-kit.config.json")
       ),
       runScanner(rootDir)
     ]);
@@ -5325,11 +6167,11 @@ var statusCommand = defineCommand15({
 });
 
 // src/commands/update.ts
-import { defineCommand as defineCommand16 } from "citty";
+import { defineCommand as defineCommand17 } from "citty";
 
 // src/lifecycle/check-updates.ts
 import { execFile as execFile6 } from "child_process";
-import path37 from "path";
+import path39 from "path";
 import { promisify as promisify6 } from "util";
 var execFileAsync5 = promisify6(execFile6);
 var SEMVER_CORE = /^v?(\d+)\.(\d+)\.(\d+)(?:[-+].*)?$/i;
@@ -5412,20 +6254,20 @@ function readUpdateCheckPrefs(config) {
     lastCheckedAt: typeof uc.lastCheckedAt === "string" ? uc.lastCheckedAt : null
   };
 }
-function intervalElapsed(lastCheckedAt, intervalDays) {
+function intervalElapsed2(lastCheckedAt, intervalDays) {
   if (!lastCheckedAt) return true;
   const last = Date.parse(lastCheckedAt);
   if (Number.isNaN(last)) return true;
   const ms = intervalDays * 24 * 60 * 60 * 1e3;
   return Date.now() - last >= ms;
 }
-async function loadContextConfig(cwd) {
-  const configPath = path37.join(cwd, ".cursor", "context", "config.json");
+async function loadContextConfig2(cwd) {
+  const configPath = path39.join(cwd, ".cursor", "context", "config.json");
   return readJson(configPath);
 }
 async function stampLastCheckedAt(cwd) {
-  const configPath = path37.join(cwd, ".cursor", "context", "config.json");
-  const existing = await loadContextConfig(cwd) ?? {};
+  const configPath = path39.join(cwd, ".cursor", "context", "config.json");
+  const existing = await loadContextConfig2(cwd) ?? {};
   const prev = existing.updateCheck && typeof existing.updateCheck === "object" ? { ...existing.updateCheck } : {};
   existing.updateCheck = {
     ...DEFAULT_UPDATE_CHECK,
@@ -5461,7 +6303,7 @@ async function checkForUpdates(cwd, options = {}) {
     };
   }
   if (options.respectPrefs) {
-    const config = await loadContextConfig(cwd);
+    const config = await loadContextConfig2(cwd);
     const prefs = readUpdateCheckPrefs(config);
     if (!prefs.enabled) {
       return {
@@ -5474,7 +6316,7 @@ async function checkForUpdates(cwd, options = {}) {
         message: "updateCheck.enabled is false (opt-in). Set true in .cursor/context/config.json to nudge."
       };
     }
-    if (!intervalElapsed(prefs.lastCheckedAt, prefs.intervalDays)) {
+    if (!intervalElapsed2(prefs.lastCheckedAt, prefs.intervalDays)) {
       return {
         status: "skipped-interval",
         installedVersion: manifest.version,
@@ -5565,7 +6407,7 @@ async function checkForUpdates(cwd, options = {}) {
 }
 
 // src/commands/update.ts
-var updateCommand = defineCommand16({
+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."
@@ -5595,6 +6437,11 @@ var updateCommand = defineCommand16({
       description: "Persist updateCheck.lastCheckedAt after a network check",
       default: false
     },
+    "seed-overlay": {
+      type: "boolean",
+      description: "Seed the managed-hash ledger from current local overlay files before applying (factory/dogfood only; consumers should not use this)",
+      default: false
+    },
     ...REGISTRY_CLI_ARGS
   },
   async run({ args }) {
@@ -5636,10 +6483,18 @@ var updateCommand = defineCommand16({
       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.");
+    }
     const stats = await syncFromManifest(registry.root, args.cwd, next);
     await saveManifest(args.cwd, next);
     logApplyStats(stats);
@@ -5648,9 +6503,9 @@ var updateCommand = defineCommand16({
 });
 
 // src/commands/validate.ts
-import { readFile as readFile18 } from "fs/promises";
-import path38 from "path";
-import { defineCommand as defineCommand17 } from "citty";
+import { readFile as readFile20 } from "fs/promises";
+import path40 from "path";
+import { defineCommand as defineCommand18 } from "citty";
 
 // src/invariants/plan-schema.ts
 var CITE5 = "agent-kit validate plan (.cursor/context/templates/plan.md)";
@@ -5696,9 +6551,9 @@ function validatePlanFrontmatterText(text) {
 // src/commands/validate.ts
 async function resolveEditedPath(cwd, explicit) {
   if (explicit) {
-    const filePath2 = path38.resolve(cwd, explicit);
+    const filePath2 = path40.resolve(cwd, explicit);
     try {
-      return { filePath: filePath2, content: await readFile18(filePath2, "utf8") };
+      return { filePath: filePath2, content: await readFile20(filePath2, "utf8") };
     } catch {
       return null;
     }
@@ -5706,9 +6561,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 = path38.isAbsolute(rel) ? rel : path38.resolve(cwd, rel);
+  const filePath = path40.isAbsolute(rel) ? rel : path40.resolve(cwd, rel);
   try {
-    return { filePath, content: await readFile18(filePath, "utf8") };
+    return { filePath, content: await readFile20(filePath, "utf8") };
   } catch {
     return null;
   }
@@ -5720,13 +6575,13 @@ function isPlanPath(filePath) {
   const norm = filePath.replace(/\\/g, "/");
   return norm.includes("/.cursor/plans/") && norm.endsWith(".plan.md");
 }
-var validateCommand = defineCommand17({
+var validateCommand = defineCommand18({
   meta: {
     name: "validate",
     description: "Advisory validators for HANDOFF / plan frontmatter (afterFileEdit adapter)"
   },
   subCommands: {
-    handoff: defineCommand17({
+    handoff: defineCommand18({
       meta: { name: "handoff", description: "Validate HANDOFF machine fields" },
       args: {
         cwd: { type: "string", default: process.cwd() },
@@ -5736,10 +6591,10 @@ var validateCommand = defineCommand17({
       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 ? path38.resolve(cwd, fileArg) : path38.join(path38.resolve(cwd), ".cursor", "HANDOFF.md");
+        const filePath = fileArg ? path40.resolve(cwd, fileArg) : path40.join(path40.resolve(cwd), ".cursor", "HANDOFF.md");
         let content = "";
         try {
-          content = await readFile18(filePath, "utf8");
+          content = await readFile20(filePath, "utf8");
         } catch {
           console.log(JSON.stringify({ ok: true, warnings: [], note: "file missing" }));
           return;
@@ -5748,7 +6603,7 @@ var validateCommand = defineCommand17({
         console.log(JSON.stringify({ ok: warnings.length === 0, warnings }));
       }
     }),
-    plan: defineCommand17({
+    plan: defineCommand18({
       meta: { name: "plan", description: "Validate plan frontmatter" },
       args: {
         cwd: { type: "string", default: process.cwd() },
@@ -5763,10 +6618,10 @@ var validateCommand = defineCommand17({
           process.exitCode = 2;
           return;
         }
-        const filePath = path38.resolve(cwd, fileArg);
+        const filePath = path40.resolve(cwd, fileArg);
         let content = "";
         try {
-          content = await readFile18(filePath, "utf8");
+          content = await readFile20(filePath, "utf8");
         } catch {
           console.log(JSON.stringify({ ok: true, warnings: [], note: "file missing" }));
           return;
@@ -5775,7 +6630,7 @@ var validateCommand = defineCommand17({
         console.log(JSON.stringify({ ok: warnings.length === 0, warnings }));
       }
     }),
-    "after-edit": defineCommand17({
+    "after-edit": defineCommand18({
       meta: {
         name: "after-edit",
         description: "Advisory afterFileEdit: annotate HANDOFF/plan issues (never block)"
@@ -5785,7 +6640,7 @@ var validateCommand = defineCommand17({
       },
       async run({ args }) {
         const cwd = typeof args.cwd === "string" ? args.cwd : process.cwd();
-        const resolved = await resolveEditedPath(path38.resolve(cwd));
+        const resolved = await resolveEditedPath(path40.resolve(cwd));
         if (!resolved) {
           console.log(JSON.stringify({}));
           return;
@@ -5828,10 +6683,11 @@ var validateCommand = defineCommand17({
 });
 
 // src/index.ts
-var main = defineCommand18({
+var main = defineCommand19({
   meta: {
     name: "agent-kit",
-    description: "HITL framework for AI-assisted IDEs"
+    description: "HITL framework for AI-assisted IDEs",
+    version: KIT_VERSION
   },
   subCommands: {
     init: initCommand,
@@ -5841,6 +6697,7 @@ var main = defineCommand18({
     doctor: doctorCommand,
     status: statusCommand,
     update: updateCommand,
+    "cursor-awareness": cursorAwarenessCommand,
     diff: diffCommand,
     contribute: contributeCommand,
     handoff: handoffCommand,