@ankurhalder/codebase-snapshot 4.0.6 → 4.1.0

package/dist/cli.js

@@ -1,4 +1,4 @@
-import { loadConfigFileDetailed, resolveConfig, validateSnapshot, explainPath, compareManifests, loadManifest, renderDiffText, generateSnapshot, GENERATOR_VERSION, ARTIFACT_NAMES, getPreset, unknownPresetMessage, GENERATOR_NAME, runInit, PromptCancelled, MIN_MAX_PART_BYTES, SCHEMA_VERSION, PRESETS, parseByteSize, renderExplainText } from './chunk-GAY7W5MK.js';
+import { GENERATOR_VERSION, loadConfigFileDetailed, resolveConfig, validateSnapshot, explainPath, compareManifests, loadManifest, renderDiffText, generateSnapshot, isDiscoveryMode, ARTIFACT_NAMES, getPreset, unknownPresetMessage, GENERATOR_NAME, runInit, PromptCancelled, MIN_MAX_PART_BYTES, SCHEMA_VERSION, PRESETS, parseByteSize, escapeControls, renderExplainText } from './chunk-6SMZR5EM.js';
 import * as fs from 'fs';
 import * as path2 from 'path';
 import { parseArgs } from 'util';
@@ -16,6 +16,7 @@ var COMMAND_OPTION_SCOPE = {
     "skip-artifacts",
     "only-artifacts",
     "no-config",
+    "discovery",
     "format",
     "mode",
     "dry-run",
@@ -34,6 +35,7 @@ var COMMAND_OPTION_SCOPE = {
     "skip-artifacts",
     "only-artifacts",
     "no-config",
+    "discovery",
     "format",
     "mode",
     "help",
@@ -66,12 +68,13 @@ var COMMAND_OPTION_SCOPE = {
     "skip-artifacts",
     "only-artifacts",
     "no-config",
+    "discovery",
     "format",
     "mode",
     "help",
     "version"
   ],
-  diff: ["format", "mode", "help", "version"],
+  diff: ["format", "mode", "no-config", "help", "version"],
   describe: ["format", "mode", "help", "version"],
   init: [
     "cwd",
@@ -116,6 +119,7 @@ function optionAppliesTo(option) {
 // src/agent/contract.ts
 var CONTRACT_VERSION = "1.0.0";
 var PACKAGE_NAME = "@ankurhalder/codebase-snapshot";
+var MAJOR_VERSION = GENERATOR_VERSION.split(".")[0];
 var ARTIFACT_SUMMARY = {
   readme: "README.md describing the snapshot at the output root.",
   manifest: "manifest.json: machine-readable index of every file, part, hash and config.",
@@ -215,8 +219,11 @@ function buildAgentContract() {
         step: 1,
         id: "verify",
         run: `npx ${PACKAGE_NAME}@latest --version`,
-        expect: `prints v${GENERATOR_VERSION} on stdout and exits 0`,
-        notes: "If it prints nothing, clear the npm cache and retry, or use `npx -p <pkg> codebase-snapshot`."
+        // The requirement is the major version; the exact build is context. A
+        // floating tag may print 4.0.7 today and 4.0.9 next week, and an agent
+        // must not conclude that a working tool is broken because of a patch.
+        expect: `prints v${MAJOR_VERSION} or newer on stdout and exits 0 (this build is v${GENERATOR_VERSION}: compare the major version, not the patch)`,
+        notes: `If it prints an older major than this contract's, the @latest tag is behind the release: pin the major with \`npx ${PACKAGE_NAME}@${MAJOR_VERSION} --version\` instead of retrying @latest. If it prints nothing, clear the npm cache and retry, or use \`npx -p <pkg> codebase-snapshot\`.`
       },
       {
         step: 2,
@@ -229,7 +236,7 @@ function buildAgentContract() {
         step: 3,
         id: "configure",
         run: `npx ${PACKAGE_NAME}@latest init --yes`,
-        expect: "writes snapshot.config.ts listing every setting at its current value",
+        expect: 'writes a commented config file listing every setting at its current value: snapshot.config.ts only when the running Node can strip types (>= 22.6) and the project is an ES module (`"type": "module"` in package.json); snapshot.config.mjs otherwise',
         notes: "Non-interactive. The detected preset is chosen automatically; override with --preset <name>. Skip this step to run on built-in defaults."
       },
       {
@@ -278,7 +285,7 @@ function buildAgentContract() {
       {
         name: "init",
         aliases: [],
-        summary: "Write a commented snapshot.config.ts (interactive, or --yes for CI).",
+        summary: "Write a commented config file (snapshot.config.ts only when Node can strip types and the project is an ES module; snapshot.config.mjs otherwise). Interactive, or --yes for CI.",
         positionals: [],
         exits: [0, 1, 2]
       },
@@ -359,6 +366,13 @@ function buildAgentContract() {
         appliesTo: optionAppliesTo("include-sensitive-files"),
         summary: "Also emit .env / *.pem / .npmrc style files. Off by default; they are recorded as skipped."
       },
+      {
+        flag: "--discovery",
+        type: "string",
+        default: "auto",
+        appliesTo: optionAppliesTo("discovery"),
+        summary: "How files are discovered: auto (git when usable), git (require git), walk (read the root .gitignore directly; the escape hatch for a .git that cannot be listed)."
+      },
       {
         flag: "--skip-artifacts",
         type: "string",
@@ -501,6 +515,7 @@ function buildAgentContract() {
         { key: "includeSensitiveFiles", type: "boolean", default: false, summary: "Emit .env / *.pem / credential files." },
         { key: "include", type: "string[]", default: "[]", summary: "Allow-list of globs; empty means everything." },
         { key: "excludePatterns", type: "string[]", default: "[]", summary: "Extra exclude globs." },
+        { key: "discovery", type: '"auto" | "git" | "walk"', default: "auto", summary: "How files are discovered; `walk` scans the tree and reads .gitignore directly when a .git directory cannot be listed." },
         { key: "artifacts", type: "object", default: "all on except monolith", summary: "Per-artifact opt-out." },
         { key: "budgets", type: "object", default: "{ default, byLayer }", summary: "Per-layer byte budgets." },
         { key: "layersMode", type: '"merge" | "replace"', default: "merge", summary: "Whether custom layers extend or replace the preset's." },
@@ -522,7 +537,7 @@ function buildAgentContract() {
       ],
       notes: [
         "Parts are ordered and budget-limited; a single file larger than the budget becomes a head/tail preview.",
-        "manifest.json.files[] carries relativePath, layer, kind, language, part, inclusionMode, hash and a structural summary.",
+        "manifest.json.files[] carries relativePath, layer, kind, language, part, inclusionMode and hash; `summary` is conditional \u2014 it is absent for languages with no structural summary, and `summaryOmitted: true` marks a summary dropped to fit the part budget; encoding appears when the file was not plain UTF-8.",
         "manifest.skipped[] carries the path and the exact reason it was excluded.",
         `The output directory is replaced atomically; ${MIN_MAX_PART_BYTES} bytes is the smallest legal budget.`
       ]
@@ -565,6 +580,7 @@ function buildAgentContract() {
 
 // src/agent/skill.ts
 var PACKAGE_NAME2 = "@ankurhalder/codebase-snapshot";
+var MAJOR_VERSION2 = GENERATOR_VERSION.split(".")[0];
 var SKILL_NAME = "codebase-snapshot";
 var AGENTS_MARKER_START = "<!-- codebase-snapshot:skill:start -->";
 var AGENTS_MARKER_END = "<!-- codebase-snapshot:skill:end -->";
@@ -589,15 +605,20 @@ another model, and reading files one by one would not fit in context.
 This tool is a Node CLI. It needs **Node.js 18 or newer**. You do not need to install it
 globally, and you do not need to clone anything.
 
-**Pin the tag** \u2014 \`npx ${PACKAGE_NAME2}@latest <command>\` \u2014 when you need the same version on
-every machine. The bare package name works too: this package ships exactly one executable,
-which is what lets npm pick it. If a command exits 0 printing nothing, the executable was
-not resolved \u2014 clear the npm cache and retry; do not assume the repository is broken.
+**Pin a version** \u2014 \`npx ${PACKAGE_NAME2}@${MAJOR_VERSION2} <command>\` (or an exact release) \u2014 when you
+need the same version on every machine. The bare package name works too: this package ships
+one executable file, published under two names (\`codebase-snapshot\` and \`snap\`), which is what
+lets npm pick it. If a command exits 0 printing nothing,
+the executable was not resolved \u2014 clear the npm cache and retry; do not assume the repository
+is broken.
 
 ## Step by step
 
-1. **Verify the tool.** Run \`npx ${PACKAGE_NAME2}@latest --version\`. Expect \`v${GENERATOR_VERSION}\` or
-   newer on stdout. Empty output means you hit the bare-spec problem above.
+1. **Verify the tool.** Run \`npx ${PACKAGE_NAME2}@latest --version\`. Expect \`v${MAJOR_VERSION2}\` or
+   newer on stdout \u2014 compare the major version, not the patch, because the
+   \`@latest\` tag can lag this release. If the printed major is older, pin the
+   major (\`@${MAJOR_VERSION2}\`) instead of retrying. Empty output means you hit the
+   bare-spec problem above.
 
 2. **Read the contract, not the prose.** Run
    \`npx ${PACKAGE_NAME2}@latest describe --format json\`. It returns the full machine
@@ -611,11 +632,12 @@ not resolved \u2014 clear the npm cache and retry; do not assume the repository
    \`--format json\` if you want to parse it.
 
 4. **Configure (recommended).** Run \`npx ${PACKAGE_NAME2}@latest init --yes\`. It detects
-   the project shape, then writes \`snapshot.config.ts\` (or \`.mjs\` when the project is
-   not an ES module) listing **every** setting at its
-   current value, commented. Pass \`--preset <name>\` only if detection is wrong; the
-   preset names are in the contract. This step is optional: without a config the tool
-   runs on the same defaults.
+   the project shape, then writes a commented config file listing **every** setting at its
+   current value. The filename depends on the project: \`snapshot.config.ts\` only when
+   the running Node can strip types (Node >= 22.6) **and** the project is an ES module
+   (\`"type": "module"\` in package.json); otherwise \`snapshot.config.mjs\`. Pass
+   \`--preset <name>\` only if detection is wrong; the preset names are in the contract.
+   This step is optional: without a config the tool runs on the same defaults.
 
 5. **Generate.** Run \`npx ${PACKAGE_NAME2}@latest generate\`. Expect exit 0 and a
    \`./snapshot/\` directory. If you need a different location use \`--out-dir <path>\`; if
@@ -626,9 +648,13 @@ not resolved \u2014 clear the npm cache and retry; do not assume the repository
 
 7. **Read the output in this order:**
    - \`snapshot/parts/part-*.md\` \u2014 the code itself, each file tagged with its layer, kind,
-     language and a structural summary (imports, exports, classes, functions).
+     language and, when it fits the budget, a structural summary (imports, exports,
+     classes, functions). A dropped summary appears as a \`Summary: (omitted \u2026)\` line.
    - \`snapshot/manifest.json\` \u2014 the index. \`files[]\` has \`relativePath\`, \`layer\`,
-     \`kind\`, \`language\`, \`part\`, \`inclusionMode\`, \`hashSha256\` and \`summary\`.
+     \`kind\`, \`language\`, \`part\`, \`inclusionMode\` and \`hashSha256\`, plus \`encoding\`
+     when the file was not plain UTF-8. \`summary\` is **optional**: it is absent for
+     languages with no structural summary, and \`summaryOmitted: true\` marks one dropped
+     to fit the part budget \u2014 never assume it exists.
      \`skipped[]\` records every excluded file **and why**. Prefer querying this over
      re-reading the parts.
    - \`snapshot/reports/audit.md\` \u2014 secrets found, large files, parse diagnostics, git
@@ -667,12 +693,16 @@ any of this to get a good first snapshot.
 Run \`npx ${PACKAGE_NAME2}@latest skill --install\`. It writes this skill into the
 repository in the places agents look for it by default: an \`AGENTS.md\` section,
 \`.claude/skills/${SKILL_NAME}/SKILL.md\`, and \`.cursor/rules/${SKILL_NAME}.mdc\`. The command
-is idempotent and only replaces its own marked section.
+is idempotent: it replaces its own marked section, and repairs a malformed one (missing,
+duplicated or nested markers) into a single block while leaving the rest of the file alone.
+It refuses a target that resolves outside the repository, so a linked \`.claude/\` cannot
+be used to write elsewhere.
 `;
 }
 
 // src/agent/install-skill.ts
 var SKILL_TARGETS = ["claude", "agents", "cursor", "all"];
+var REFUSED = "Refusing to install the agent skill";
 function targetPath(cwd, target) {
   switch (target) {
     case "claude":
@@ -683,6 +713,41 @@ function targetPath(cwd, target) {
       return path2.join(cwd, "AGENTS.md");
   }
 }
+function assertWritableInsideRepository(cwd, filePath) {
+  const root = fs.realpathSync(cwd);
+  const shown = path2.relative(root, filePath) || filePath;
+  let stat = null;
+  try {
+    stat = fs.lstatSync(filePath);
+  } catch {
+    stat = null;
+  }
+  if (stat !== null && stat.isSymbolicLink()) {
+    throw new Error(
+      `${REFUSED}: ${shown} is a symbolic link or junction. Remove the link, or write the skill into the directory it points at yourself, and run again.`
+    );
+  }
+  if (stat !== null && stat.isFile() && stat.nlink > 1) {
+    throw new Error(
+      `${REFUSED}: ${shown} has ${stat.nlink} hard links, so writing it would also rewrite a file outside the repository. Replace it with an ordinary file and run again.`
+    );
+  }
+  let existing = filePath;
+  const missing = [];
+  while (!fs.existsSync(existing)) {
+    missing.unshift(path2.basename(existing));
+    const parent = path2.dirname(existing);
+    if (parent === existing) break;
+    existing = parent;
+  }
+  const realAncestor = fs.realpathSync(existing);
+  const resolved = missing.length === 0 ? realAncestor : path2.join(realAncestor, ...missing);
+  if (resolved !== root && !resolved.startsWith(`${root}${path2.sep}`)) {
+    throw new Error(
+      `${REFUSED}: ${shown} resolves outside the repository (${resolved}). Move it back inside ${root}, or remove the link, and run again.`
+    );
+  }
+}
 function writeIfChanged(target, filePath, content) {
   const existing = fs.existsSync(filePath) ? fs.readFileSync(filePath, "utf8") : null;
   if (existing === content) return { target, path: filePath, action: "unchanged" };
@@ -704,34 +769,60 @@ function agentsBlock(skill) {
     ""
   ].join("\n");
 }
+function ownSpans(existing) {
+  const marks = [];
+  let cursor = 0;
+  while (cursor < existing.length) {
+    const start = existing.indexOf(AGENTS_MARKER_START, cursor);
+    const end = existing.indexOf(AGENTS_MARKER_END, cursor);
+    if (start === -1 && end === -1) break;
+    if (start !== -1 && (end === -1 || start < end)) {
+      marks.push({ kind: "start", start, end: start + AGENTS_MARKER_START.length });
+      cursor = start + AGENTS_MARKER_START.length;
+    } else {
+      marks.push({ kind: "end", start: end, end: end + AGENTS_MARKER_END.length });
+      cursor = end + AGENTS_MARKER_END.length;
+    }
+  }
+  const spans = [];
+  let open = -1;
+  for (const mark of marks) {
+    if (mark.kind === "start") {
+      if (open === -1) open = mark.start;
+    } else if (open !== -1) {
+      spans.push({ start: open, end: mark.end });
+      open = -1;
+    } else {
+      spans.push({ start: mark.start, end: mark.end });
+    }
+  }
+  if (open !== -1) spans.push({ start: open, end: open + AGENTS_MARKER_START.length });
+  return spans;
+}
+function mergeMarkedSection(existing, block) {
+  const spans = ownSpans(existing);
+  if (spans.length === 0) return `${existing.trimEnd()}
+
+${block}`;
+  let stripped = "";
+  let from = 0;
+  let insertAt = -1;
+  for (const span of spans) {
+    if (span.start < from) continue;
+    stripped += existing.slice(from, span.start);
+    if (insertAt === -1) insertAt = stripped.length;
+    from = span.end;
+  }
+  stripped += existing.slice(from);
+  return `${stripped.slice(0, insertAt)}${block.trimEnd()}${stripped.slice(insertAt)}`;
+}
 function mergeAgentsFile(cwd, skill) {
   const filePath = targetPath(cwd, "agents");
   const block = agentsBlock(skill);
   const existing = fs.existsSync(filePath) ? fs.readFileSync(filePath, "utf8") : null;
-  let next;
-  if (existing === null) {
-    next = `# AGENTS.md
-
-${block}`;
-  } else {
-    const starts = existing.split(AGENTS_MARKER_START).length - 1;
-    const ends = existing.split(AGENTS_MARKER_END).length - 1;
-    const start = existing.indexOf(AGENTS_MARKER_START);
-    const end = existing.indexOf(AGENTS_MARKER_END) + AGENTS_MARKER_END.length;
-    if (starts === 1 && ends === 1 && start < end) {
-      next = `${existing.slice(0, start)}${block.trimEnd()}${existing.slice(end)}`;
-    } else if (starts > 0 && ends === 0) {
-      next = `${existing.slice(0, start)}${block.trimEnd()}${existing.slice(
-        start + AGENTS_MARKER_START.length
-      )}`;
-    } else if (existing.includes(block.trimEnd())) {
-      next = existing;
-    } else {
-      next = `${existing.trimEnd()}
+  const next = existing === null ? `# AGENTS.md
 
-${block}`;
-    }
-  }
+${block}` : mergeMarkedSection(existing, block);
   const action = existing === null ? "created" : existing === next ? "unchanged" : "updated";
   if (action !== "unchanged") {
     fs.mkdirSync(path2.dirname(filePath), { recursive: true });
@@ -743,6 +834,7 @@ function installSkill(cwd, target = "all") {
   const skill = renderSkill();
   const written = [];
   const wanted = target === "all" ? ["agents", "claude", "cursor"] : [target];
+  for (const item of wanted) assertWritableInsideRepository(cwd, targetPath(cwd, item));
   for (const item of wanted) {
     if (item === "agents") {
       written.push(mergeAgentsFile(cwd, skill));
@@ -794,6 +886,7 @@ var CLI_OPTIONS = {
   "dry-run": { type: "boolean" },
   watch: { type: "boolean" },
   "no-config": { type: "boolean" },
+  discovery: { type: "string" },
   preset: { type: "string" },
   include: { type: "string" },
   exclude: { type: "string" },
@@ -841,6 +934,9 @@ Options:
   --dry-run                     Compute the snapshot without writing anything
   --watch                       Re-generate whenever the repository changes
   --no-config                   Ignore snapshot.config.* and use the built-in defaults
+  --discovery <mode>            auto | git | walk \u2014 how files are discovered.
+                                auto: git when usable. git: require git. walk: read
+                                .gitignore directly (escape hatch for a broken .git)
 
   init only:
   --preset <name>               Force a project preset instead of detecting one
@@ -970,6 +1066,19 @@ function parseCliArgs(argv) {
     }
     command = resolved;
   }
+  if (explicitMode !== void 0) {
+    const resolvedMode = COMMAND_ALIASES.get(explicitMode);
+    if (!resolvedMode) {
+      throw new UsageError(
+        `Unknown --mode "${explicitMode}". Expected one of: ${Array.from(COMMAND_ALIASES.keys()).join(", ")}.`
+      );
+    }
+    if (firstPositional !== void 0 && resolvedMode !== command) {
+      throw new UsageError(
+        `--mode ${explicitMode} contradicts the command "${firstPositional}". Pass one or the other.`
+      );
+    }
+  }
   const expectedArgs = COMMAND_ARITY[command];
   if (args.length !== expectedArgs) {
     if (command === "explain") {
@@ -988,6 +1097,13 @@ function parseCliArgs(argv) {
   if (rawFormat !== "text" && rawFormat !== "json") {
     throw new UsageError(`--format must be "text" or "json", received "${rawFormat}".`);
   }
+  const rawDiscovery = values.discovery === void 0 ? void 0 : String(values.discovery);
+  if (rawDiscovery !== void 0 && !isDiscoveryMode(rawDiscovery)) {
+    throw new UsageError(
+      `--discovery must be one of: auto, git, walk (received "${rawDiscovery}").`
+    );
+  }
+  let onlyNamesMonolith = false;
   const rawSkip = values["skip-artifacts"];
   const rawOnly = values["only-artifacts"];
   if (rawSkip !== void 0 && rawOnly !== void 0) {
@@ -996,6 +1112,7 @@ function parseCliArgs(argv) {
   let skipArtifacts;
   if (rawOnly !== void 0) {
     const keep = parseArtifactList(String(rawOnly), "--only-artifacts");
+    onlyNamesMonolith = keep.includes("monolith");
     skipArtifacts = ARTIFACT_NAMES.filter(
       (name) => !keep.includes(name)
     );
@@ -1050,7 +1167,7 @@ function parseCliArgs(argv) {
     target: values.target === void 0 ? void 0 : String(values.target),
     cwd: values.cwd === void 0 ? process.cwd() : path2.resolve(String(values.cwd)),
     outDir: values["out-dir"] === void 0 ? void 0 : String(values["out-dir"]),
-    includeMonolith: values["include-monolith"] === true ? true : void 0,
+    includeMonolith: values["include-monolith"] === true || onlyNamesMonolith === true ? true : void 0,
     includeSensitiveFiles: values["include-sensitive-files"] === true ? true : void 0,
     maxPartBytes: parseByteOption(
       values["max-part-bytes"],
@@ -1067,17 +1184,21 @@ function parseCliArgs(argv) {
       "max-monolith-bytes",
       1
     ),
-    skipArtifacts
+    skipArtifacts,
+    discovery: isDiscoveryMode(rawDiscovery) ? rawDiscovery : void 0
   };
 }
 var HelpRequested = class extends Error {
 };
+function escapeForTerminal(message) {
+  return message.split("\n").map((line) => escapeControls(line)).join("\n");
+}
 function info(message) {
-  process.stderr.write(`${message}
+  process.stderr.write(`${escapeForTerminal(message)}
 `);
 }
 function warn(message) {
-  process.stderr.write(`${message}
+  process.stderr.write(`${escapeForTerminal(message)}
 `);
 }
 function emit(format, payload, textRenderer) {
@@ -1094,8 +1215,8 @@ function splitList(value) {
 }
 function displayOutPath(cwd, outDir, ...segments) {
   const absolute = path2.resolve(cwd, outDir, ...segments);
-  const relative2 = path2.relative(cwd, absolute);
-  if (relative2 && !relative2.startsWith("..") && !path2.isAbsolute(relative2)) return relative2;
+  const relative3 = path2.relative(cwd, absolute);
+  if (relative3 && !relative3.startsWith("..") && !path2.isAbsolute(relative3)) return relative3;
   return absolute;
 }
 function describeManifestShapeProblem(manifest) {
@@ -1107,11 +1228,32 @@ function describeManifestShapeProblem(manifest) {
   if (!counts || typeof counts !== "object") return "missing `counts`";
   for (const key of ["totalFiles", "totalLines", "totalSizeBytes", "partsCount"]) {
     if (typeof counts[key] !== "number") return `missing numeric \`counts.${key}\``;
+    if (!Number.isSafeInteger(counts[key]) || counts[key] < 0) {
+      return `\`counts.${key}\` must be a non-negative integer`;
+    }
+  }
+  if (candidate.fingerprint !== void 0 && !/^[0-9a-f]{64}$/.test(String(candidate.fingerprint))) {
+    return "`fingerprint` must be a 64-character sha256 hex digest";
   }
   if (!candidate.layers || typeof candidate.layers !== "object") return "missing `layers`";
   if (!Array.isArray(candidate.files)) return "missing `files` array";
   return null;
 }
+function nextStepHint(cwd, scriptsAddedNow) {
+  let hasScript = scriptsAddedNow;
+  if (!hasScript) {
+    try {
+      const parsed = JSON.parse(fs.readFileSync(path2.join(cwd, "package.json"), "utf8"));
+      hasScript = typeof parsed.scripts?.snapshot === "string";
+    } catch {
+      hasScript = false;
+    }
+  }
+  if (!hasScript) return `npx ${GENERATOR_NAME} generate`;
+  const bin = path2.join(cwd, "node_modules", ".bin", "codebase-snapshot");
+  const installed = fs.existsSync(bin) || fs.existsSync(`${bin}.cmd`);
+  return installed ? "npm run snapshot" : "npm install && npm run snapshot";
+}
 async function runInitCommand(invocation) {
   try {
     const result = await runInit({
@@ -1144,11 +1286,7 @@ async function runInitCommand(invocation) {
     }
     for (const note of result.notes) info(`   \u26A0 ${note}`);
     info("");
-    if (result.scripts.length > 0) {
-      info("   Next:  npm run snapshot");
-    } else {
-      info(`   Next:  ${GENERATOR_NAME} generate`);
-    }
+    info(`   Next:  ${nextStepHint(invocation.cwd, result.scripts.length > 0)}`);
     info(
       `   Tip:   \`${GENERATOR_NAME} skill --install\` makes this repo discoverable by AI agents.`
     );
@@ -1200,6 +1338,9 @@ function renderValidateText(result) {
   } else {
     warn("\u274C Snapshot validation failed:");
     for (const error of result.errors) warn(`  - ${error}`);
+    for (const unreadable of result.drift.unreadable.slice(0, 20)) {
+      warn(`  - unreadable: ${unreadable}`);
+    }
     for (const drift of result.drift.hashMismatches.slice(0, 20)) {
       warn(`  - modified: ${drift.path}`);
     }
@@ -1247,7 +1388,8 @@ ${USAGE}
   if (invocation.command === "skill") {
     return runSkillCommand(invocation);
   }
-  const loaded = invocation.noConfig ? { config: null, warnings: [], errors: [], file: null } : await loadConfigFileDetailed(invocation.cwd);
+  const skipConfig = invocation.noConfig || invocation.command === "diff";
+  const loaded = skipConfig ? { config: null, warnings: [], errors: [], file: null } : await loadConfigFileDetailed(invocation.cwd);
   if (invocation.noConfig) info("\u2699  --no-config: using built-in defaults, config file ignored");
   for (const warning of loaded.warnings) warn(`\u26A0 Config: ${warning}`);
   if (loaded.errors.length > 0) {
@@ -1268,12 +1410,27 @@ ${USAGE}
       maxPartBytes: invocation.maxPartBytes,
       largeFileBytes: invocation.largeFileBytes,
       maxMonolithBytes: invocation.maxMonolithBytes,
-      skipArtifacts: invocation.skipArtifacts
+      skipArtifacts: invocation.skipArtifacts,
+      discovery: invocation.discovery
     },
     invocation.cwd
   );
   if (invocation.command === "validate") {
     const result = validateSnapshot(resolved);
+    if (result.valid) {
+      const manifestPath = path2.resolve(resolved.cwd, resolved.outDir, "manifest.json");
+      let manifest;
+      try {
+        manifest = JSON.parse(fs.readFileSync(manifestPath, "utf8"));
+      } catch {
+        manifest = void 0;
+      }
+      const shapeError = manifest === void 0 ? null : describeManifestShapeProblem(manifest);
+      if (shapeError) {
+        warn(`\u274C ${manifestPath} is not a snapshot manifest: ${shapeError}`);
+        return 1;
+      }
+    }
     emit(invocation.format, result, () => renderValidateText(result));
     return result.valid ? 0 : 1;
   }
@@ -1423,24 +1580,79 @@ ${USAGE}
     return 1;
   }
 }
+var WATCH_DEBOUNCE_MS = 250;
+var WATCH_SETTLE_MS = 1500;
+var VCS_SEGMENTS = /* @__PURE__ */ new Set([".git", ".hg", ".svn", ".bzr"]);
+function initialWatchState() {
+  return { running: false, pending: false, settleUntil: 0 };
+}
+function beginWatchRun(state) {
+  return { ...state, running: true, pending: false };
+}
+function finishWatchRun(state, now) {
+  return {
+    state: { running: false, pending: false, settleUntil: now + WATCH_SETTLE_MS },
+    schedule: state.pending
+  };
+}
+function comparablePath(value) {
+  const absolute = path2.resolve(value);
+  return process.platform === "win32" ? absolute.toLowerCase() : absolute;
+}
+function isSameOrInside(parent, candidate) {
+  const relative3 = path2.relative(parent, candidate);
+  return relative3 === "" || relative3 !== ".." && !relative3.startsWith(`..${path2.sep}`) && !path2.isAbsolute(relative3);
+}
+function isGeneratedWatchPath(candidate, paths) {
+  const absolute = comparablePath(path2.resolve(paths.cwd, candidate));
+  const outDir = comparablePath(path2.resolve(paths.cwd, paths.outDir));
+  const tmpDir = comparablePath(path2.resolve(paths.cwd, paths.tmpDir));
+  if (isSameOrInside(outDir, absolute) || isSameOrInside(tmpDir, absolute)) return true;
+  const parent = path2.dirname(absolute);
+  if (parent === path2.dirname(outDir) && path2.basename(absolute).startsWith(`${path2.basename(outDir)}.backup-`)) {
+    return true;
+  }
+  return absolute.split(/[\\/]+/).some((segment) => VCS_SEGMENTS.has(segment));
+}
+function decideWatchEvent(state, event, paths) {
+  if (event.path !== null) {
+    if (isGeneratedWatchPath(event.path, paths)) return { state, action: "ignore" };
+  } else if (state.running || event.now < state.settleUntil) {
+    return { state, action: "ignore" };
+  }
+  if (state.running) {
+    return { state: { ...state, pending: true }, action: "pending" };
+  }
+  return { state, action: "schedule" };
+}
 async function runWatchLoop(invocation, resolved) {
   const outDir = path2.resolve(resolved.cwd, resolved.outDir);
   const tmpDir = path2.resolve(resolved.cwd, resolved.tmpDir);
-  const VCS_SEGMENTS = /* @__PURE__ */ new Set([".git", ".hg", ".svn", ".bzr"]);
-  const outName = path2.basename(outDir).toLowerCase();
-  const tmpName = path2.basename(tmpDir).toLowerCase();
-  const isGenerated = (candidate) => candidate.toLowerCase().split(/[\\/]/).some(
-    (segment) => segment === outName || segment === tmpName || segment.startsWith(`${outName}.backup-`) || VCS_SEGMENTS.has(segment)
-  );
-  let running = false;
-  let quietUntil = 0;
-  const QUIET_MS = 1500;
+  const paths = { cwd: resolved.cwd, outDir, tmpDir };
+  let state = initialWatchState();
+  let timer = null;
+  let stopped = false;
+  const schedule = (delay = WATCH_DEBOUNCE_MS) => {
+    if (stopped) return;
+    if (timer) clearTimeout(timer);
+    timer = setTimeout(() => {
+      timer = null;
+      void regenerate();
+    }, delay);
+  };
   const regenerate = async () => {
-    if (running) return;
-    running = true;
+    if (state.running) {
+      state = { ...state, pending: true };
+      if (timer) {
+        clearTimeout(timer);
+        timer = null;
+      }
+      return;
+    }
+    state = beginWatchRun(state);
     const started = performance.now();
     try {
-      const loaded = await loadConfigFileDetailed(invocation.cwd);
+      const loaded = invocation.noConfig ? { config: null, warnings: [], errors: [], file: null } : await loadConfigFileDetailed(invocation.cwd);
       if (loaded.errors.length > 0) {
         for (const error of loaded.errors) warn(`\u26A0 Config: ${error}`);
         warn("\u274C The config file could not be read. Fix it, or delete it to use the defaults.");
@@ -1460,7 +1672,8 @@ async function runWatchLoop(invocation, resolved) {
           maxPartBytes: invocation.maxPartBytes,
           largeFileBytes: invocation.largeFileBytes,
           maxMonolithBytes: invocation.maxMonolithBytes,
-          skipArtifacts: invocation.skipArtifacts
+          skipArtifacts: invocation.skipArtifacts,
+          discovery: invocation.discovery
         },
         invocation.cwd
       );
@@ -1472,24 +1685,35 @@ async function runWatchLoop(invocation, resolved) {
     } catch (err) {
       warn(`\u274C ${err.message}`);
     } finally {
-      quietUntil = performance.now() + QUIET_MS;
-      running = false;
+      const finished = finishWatchRun(state, performance.now());
+      state = finished.state;
+      if (finished.schedule) schedule(0);
     }
   };
   info("\u{1F440} Watching for changes. Press Ctrl+C to stop.");
   void regenerate();
-  let timer = null;
   const watcher = fs.watch(resolved.cwd, { recursive: true }, (_event, filename) => {
-    if (performance.now() < quietUntil) return;
-    if (filename) {
-      const changed = path2.resolve(resolved.cwd, filename.toString());
-      if (isGenerated(changed)) return;
+    const decision = decideWatchEvent(
+      state,
+      {
+        path: filename ? path2.resolve(resolved.cwd, filename.toString()) : null,
+        now: performance.now()
+      },
+      paths
+    );
+    state = decision.state;
+    if (decision.action === "pending") {
+      if (timer) {
+        clearTimeout(timer);
+        timer = null;
+      }
+      return;
     }
-    if (timer) clearTimeout(timer);
-    timer = setTimeout(() => void regenerate(), 250);
+    if (decision.action === "schedule") schedule();
   });
   await new Promise((resolve2) => {
     const stop = () => {
+      stopped = true;
       if (timer) clearTimeout(timer);
       watcher.close();
       resolve2();
@@ -1515,6 +1739,6 @@ if (invokedDirectly) {
   );
 }
 
-export { UsageError, main, parseByteOption, parseCliArgs, parsePositiveInteger };
+export { UsageError, WATCH_DEBOUNCE_MS, WATCH_SETTLE_MS, beginWatchRun, decideWatchEvent, finishWatchRun, initialWatchState, isGeneratedWatchPath, main, parseByteOption, parseCliArgs, parsePositiveInteger };
 //# sourceMappingURL=cli.js.map
 //# sourceMappingURL=cli.js.map