@ankurhalder/codebase-snapshot 3.0.0 → 4.0.0

package/dist/cli.d.cts

@@ -1,4 +1,4 @@
-import { O as OutputFormat } from './types-CJqkePM4.cjs';
+import { O as OutputFormat } from './types-BdpT_4b8.cjs';
 
 type Command = "generate" | "validate" | "report" | "init" | "explain" | "diff" | "describe" | "skill";
 /** A user-input problem: printed without a stack trace, exits 2. */
@@ -11,6 +11,8 @@ interface ParsedInvocation {
     format: OutputFormat;
     dryRun: boolean;
     watch: boolean;
+    /** Ignore any config file and run on the built-in defaults. */
+    noConfig: boolean;
     preset?: string;
     /** The size exactly as typed, so the generated config can keep `120k`. */
     maxPartBytesRaw?: string;

package/dist/cli.d.ts

@@ -1,4 +1,4 @@
-import { O as OutputFormat } from './types-CJqkePM4.js';
+import { O as OutputFormat } from './types-BdpT_4b8.js';
 
 type Command = "generate" | "validate" | "report" | "init" | "explain" | "diff" | "describe" | "skill";
 /** A user-input problem: printed without a stack trace, exits 2. */
@@ -11,6 +11,8 @@ interface ParsedInvocation {
     format: OutputFormat;
     dryRun: boolean;
     watch: boolean;
+    /** Ignore any config file and run on the built-in defaults. */
+    noConfig: boolean;
     preset?: string;
     /** The size exactly as typed, so the generated config can keep `120k`. */
     maxPartBytesRaw?: string;

package/dist/cli.js

@@ -1,8 +1,118 @@
-import { parseByteSize, GENERATOR_VERSION, ARTIFACT_NAMES, getPreset, unknownPresetMessage, MIN_MAX_PART_BYTES, loadConfigFileDetailed, resolveConfig, validateSnapshot, explainPath, compareManifests, loadManifest, renderDiffText, generateSnapshot, GENERATOR_NAME, runInit, PromptCancelled, SCHEMA_VERSION, PRESETS, renderExplainText } from './chunk-5B4UVQLR.js';
+import { parseByteSize, GENERATOR_VERSION, ARTIFACT_NAMES, getPreset, unknownPresetMessage, MIN_MAX_PART_BYTES, loadConfigFileDetailed, resolveConfig, validateSnapshot, explainPath, compareManifests, loadManifest, renderDiffText, generateSnapshot, GENERATOR_NAME, runInit, PromptCancelled, SCHEMA_VERSION, PRESETS, renderExplainText } from './chunk-FM4OOQPF.js';
 import * as fs from 'fs';
 import * as path2 from 'path';
 import { parseArgs } from 'util';
 
+// src/agent/option-scope.ts
+var COMMAND_OPTION_SCOPE = {
+  generate: [
+    "cwd",
+    "out-dir",
+    "max-part-bytes",
+    "large-file-bytes",
+    "max-monolith-bytes",
+    "include-monolith",
+    "include-sensitive-files",
+    "skip-artifacts",
+    "only-artifacts",
+    "no-config",
+    "format",
+    "mode",
+    "dry-run",
+    "watch",
+    "help",
+    "version"
+  ],
+  validate: [
+    "cwd",
+    "out-dir",
+    "max-part-bytes",
+    "large-file-bytes",
+    "max-monolith-bytes",
+    "include-monolith",
+    "include-sensitive-files",
+    "skip-artifacts",
+    "only-artifacts",
+    "no-config",
+    "format",
+    "mode",
+    "help",
+    "version"
+  ],
+  report: [
+    "cwd",
+    "out-dir",
+    "max-part-bytes",
+    "large-file-bytes",
+    "max-monolith-bytes",
+    "include-monolith",
+    "include-sensitive-files",
+    "skip-artifacts",
+    "only-artifacts",
+    "no-config",
+    "format",
+    "mode",
+    "help",
+    "version"
+  ],
+  explain: [
+    "cwd",
+    "out-dir",
+    "max-part-bytes",
+    "large-file-bytes",
+    "max-monolith-bytes",
+    "include-monolith",
+    "include-sensitive-files",
+    "skip-artifacts",
+    "only-artifacts",
+    "no-config",
+    "format",
+    "mode",
+    "help",
+    "version"
+  ],
+  diff: ["format", "mode", "help", "version"],
+  describe: ["format", "mode", "help", "version"],
+  init: [
+    "cwd",
+    "out-dir",
+    "max-part-bytes",
+    "include-sensitive-files",
+    "skip-artifacts",
+    "only-artifacts",
+    "preset",
+    "include",
+    "exclude",
+    "yes",
+    "minimal",
+    "force",
+    "dry-run",
+    "format",
+    "mode",
+    "help",
+    "version"
+  ],
+  skill: ["cwd", "format", "mode", "install", "target", "help", "version"]
+};
+var COMMAND_ORDER = [
+  "generate",
+  "validate",
+  "report",
+  "explain",
+  "init",
+  "diff",
+  "describe",
+  "skill"
+];
+function commandsForOption(option) {
+  return COMMAND_ORDER.filter((command) => COMMAND_OPTION_SCOPE[command].includes(option));
+}
+function optionAppliesTo(option) {
+  const commands = commandsForOption(option);
+  if (commands.length === COMMAND_ORDER.length) return "all commands";
+  return commands.join("/");
+}
+
 // src/agent/contract.ts
 var CONTRACT_VERSION = "1.0.0";
 var PACKAGE_NAME = "@ankurhalder/codebase-snapshot";
@@ -92,11 +202,11 @@ function buildAgentContract() {
     invocation: {
       oneShot: `npx ${PACKAGE_NAME}@latest`,
       installed: "npx codebase-snapshot",
-      bins: ["codebase-snapshot"],
+      bins: ["codebase-snapshot", "snap"],
       notes: [
         `The bare package name also works: npx ${PACKAGE_NAME} <command>.`,
-        "Pin @latest (or @2) when you need the exact same version on every machine.",
-        "This package exposes exactly one executable on purpose: npm cannot infer which one to run for a scoped package that ships several.",
+        "Pin @latest (or @4) when you need the exact same version on every machine.",
+        "Both bin names point at the same file. npm resolves a package by its bin entries, so they must stay aliases of one executable.",
         "Human progress goes to stderr. With --format json the payload on stdout is pure JSON."
       ]
     },
@@ -105,7 +215,7 @@ function buildAgentContract() {
         step: 1,
         id: "verify",
         run: `npx ${PACKAGE_NAME}@latest --version`,
-        expect: "prints v2.x.x on stdout and exits 0",
+        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`."
       },
       {
@@ -175,9 +285,9 @@ function buildAgentContract() {
       {
         name: "explain",
         aliases: [],
-        summary: "Explain how one path would be treated: layer, kind, part, skip reason.",
+        summary: "Explain how one path would be treated: layer, kind, part, skip reason. Always exits 0 when it can report; read `included` and `reason` instead of the exit code.",
         positionals: ["<path>"],
-        exits: [0, 1]
+        exits: [0]
       },
       {
         name: "diff",
@@ -211,140 +321,147 @@ function buildAgentContract() {
         flag: "--out-dir",
         type: "string",
         default: "snapshot",
-        appliesTo: "generate/validate/report/explain",
+        appliesTo: optionAppliesTo("out-dir"),
         summary: "Where the snapshot is written. Must not be the repo root or a directory the tool did not create."
       },
       {
         flag: "--max-part-bytes",
         type: "string",
         default: 307200,
-        appliesTo: "generate/validate/report",
+        appliesTo: optionAppliesTo("max-part-bytes"),
         summary: 'Byte budget per markdown part. Accepts "120k" / "1.5mb". Minimum 4096.'
       },
       {
         flag: "--large-file-bytes",
         type: "string",
         default: 204800,
-        appliesTo: "generate/validate/report",
+        appliesTo: optionAppliesTo("large-file-bytes"),
         summary: "Above this size a file gets a head/tail preview instead of the full body."
       },
       {
         flag: "--max-monolith-bytes",
         type: "string",
         default: "unset",
-        appliesTo: "generate",
+        appliesTo: optionAppliesTo("max-monolith-bytes"),
         summary: "Skip the monolith artifacts when they would exceed this size."
       },
       {
         flag: "--include-monolith",
         type: "boolean",
         default: false,
-        appliesTo: "generate",
+        appliesTo: optionAppliesTo("include-monolith"),
         summary: "Also write full-codebase.json and full-codebase.md."
       },
       {
         flag: "--include-sensitive-files",
         type: "boolean",
         default: false,
-        appliesTo: "generate/validate/report",
+        appliesTo: optionAppliesTo("include-sensitive-files"),
         summary: "Also emit .env / *.pem / .npmrc style files. Off by default; they are recorded as skipped."
       },
       {
         flag: "--skip-artifacts",
         type: "string",
         default: "unset",
-        appliesTo: "generate",
+        appliesTo: optionAppliesTo("skip-artifacts"),
         summary: "Comma-separated artifacts to omit (readme, manifest, parts, navigation, projectTree, audit, monolith)."
       },
       {
         flag: "--only-artifacts",
         type: "string",
         default: "unset",
-        appliesTo: "generate",
+        appliesTo: optionAppliesTo("only-artifacts"),
         summary: "Write only these artifacts. Cannot be combined with --skip-artifacts."
       },
       {
         flag: "--format",
         type: "string",
         default: "text",
-        appliesTo: "all commands",
+        appliesTo: optionAppliesTo("format"),
         summary: 'Output format: "text" or "json". JSON goes to stdout, progress to stderr.'
       },
       {
         flag: "--cwd",
         type: "string",
         default: "process.cwd()",
-        appliesTo: "all commands",
+        appliesTo: optionAppliesTo("cwd"),
         summary: "Repository to operate on. Must be an existing directory."
       },
       {
         flag: "--dry-run",
         type: "boolean",
         default: false,
-        appliesTo: "generate",
+        appliesTo: optionAppliesTo("dry-run"),
         summary: "Compute everything and print the result without writing."
       },
       {
         flag: "--watch",
         type: "boolean",
         default: false,
-        appliesTo: "generate",
+        appliesTo: optionAppliesTo("watch"),
         summary: "Regenerate on every change until interrupted."
       },
+      {
+        flag: "--no-config",
+        type: "boolean",
+        default: false,
+        appliesTo: optionAppliesTo("no-config"),
+        summary: "Ignore the config file and run on the built-in defaults."
+      },
       {
         flag: "--preset",
         type: "string",
         default: "detected",
-        appliesTo: "init",
+        appliesTo: optionAppliesTo("preset"),
         summary: "Force a project preset instead of detecting one. Unknown names are a usage error."
       },
       {
         flag: "--include",
         type: "string",
         default: "unset",
-        appliesTo: "init",
+        appliesTo: optionAppliesTo("include"),
         summary: "Comma-separated allow-list of globs to record in the generated config."
       },
       {
         flag: "--exclude",
         type: "string",
         default: "unset",
-        appliesTo: "init",
+        appliesTo: optionAppliesTo("exclude"),
         summary: "Comma-separated globs to record in the generated config."
       },
       {
         flag: "--yes",
         type: "boolean",
         default: false,
-        appliesTo: "init",
+        appliesTo: optionAppliesTo("yes"),
         summary: "Accept every default without prompting. Required in a non-TTY."
       },
       {
         flag: "--minimal",
         type: "boolean",
         default: false,
-        appliesTo: "init",
+        appliesTo: optionAppliesTo("minimal"),
         summary: "Write only the settings that differ from the defaults."
       },
       {
         flag: "--force",
         type: "boolean",
         default: false,
-        appliesTo: "init",
+        appliesTo: optionAppliesTo("force"),
         summary: "Overwrite an existing config file."
       },
       {
         flag: "--install",
         type: "boolean",
         default: false,
-        appliesTo: "skill",
+        appliesTo: optionAppliesTo("install"),
         summary: "Write the skill into the repository instead of printing it."
       },
       {
         flag: "--target",
         type: "string",
         default: "all",
-        appliesTo: "skill",
+        appliesTo: optionAppliesTo("target"),
         summary: 'Where to install: "claude", "agents", "cursor" or "all".'
       }
     ],
@@ -419,8 +536,8 @@ function buildAgentContract() {
     troubleshooting: [
       {
         symptom: "Command prints nothing and exits 0",
-        cause: "The executable was not found: an offline or partially populated npm cache, or an npm proxy serving an incomplete manifest.",
-        fix: `Clear the npx cache (npm cache clean --force), then run npx ${PACKAGE_NAME}@latest <command>.`
+        cause: "A stale global install of this package (often a leftover `npm link`) is shadowing npx: npm runs the global binary instead of installing the published one.",
+        fix: "Check `npm ls -g --depth=0` for @ankurhalder/codebase-snapshot and remove it with `npm rm -g @ankurhalder/codebase-snapshot`. If it is not installed globally, clear the npx cache with `npm cache clean --force` and retry."
       },
       {
         symptom: "Exit 1 with 'Refusing to replace outDir'",
@@ -494,7 +611,8 @@ 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\` listing **every** setting at its
+   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.
@@ -595,14 +713,24 @@ function mergeAgentsFile(cwd, skill) {
     next = `# AGENTS.md
 
 ${block}`;
-  } else if (existing.includes(AGENTS_MARKER_START) && existing.includes(AGENTS_MARKER_END)) {
+  } 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;
-    next = `${existing.slice(0, start)}${block.trimEnd()}${existing.slice(end)}`;
-  } else {
-    next = `${existing.trimEnd()}
+    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()}
 
 ${block}`;
+    }
   }
   const action = existing === null ? "created" : existing === next ? "unchanged" : "updated";
   if (action !== "unchanged") {
@@ -665,6 +793,7 @@ var CLI_OPTIONS = {
   mode: { type: "string" },
   "dry-run": { type: "boolean" },
   watch: { type: "boolean" },
+  "no-config": { type: "boolean" },
   preset: { type: "string" },
   include: { type: "string" },
   exclude: { type: "string" },
@@ -711,6 +840,7 @@ Options:
   --format <text|json>          CLI output format (default: text)
   --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
 
   init only:
   --preset <name>               Force a project preset instead of detecting one
@@ -872,28 +1002,32 @@ function parseCliArgs(argv) {
   } else if (rawSkip !== void 0) {
     skipArtifacts = parseArtifactList(String(rawSkip), "--skip-artifacts");
   }
-  if (command !== "init") {
-    const initOnly = [];
-    if (values.preset !== void 0) initOnly.push("--preset");
-    if (values.include !== void 0) initOnly.push("--include");
-    if (values.exclude !== void 0) initOnly.push("--exclude");
-    if (values.yes === true) initOnly.push("--yes");
-    if (values.minimal === true) initOnly.push("--minimal");
-    if (values.force === true) initOnly.push("--force");
-    if (initOnly.length > 0) {
-      throw new UsageError(
-        `${initOnly.join(", ")} ${initOnly.length === 1 ? "is" : "are"} only valid with \`init\`. To scope \`${command}\`, set include/excludePatterns/preset in snapshot.config.ts (or run \`codebase-snapshot init\` to generate one).`
-      );
-    }
+  const scope = COMMAND_OPTION_SCOPE[command];
+  const ignored = [];
+  for (const name of Object.keys(CLI_OPTIONS)) {
+    if (scope.includes(name)) continue;
+    const value = values[name];
+    if (value === void 0 || value === false) continue;
+    ignored.push(`--${name}`);
+  }
+  if (ignored.length > 0) {
+    const owners = Array.from(
+      new Set(
+        ignored.flatMap(
+          (flag) => commandsForOption(flag.replace(/^--/, "")).map((owner) => `\`${owner}\``)
+        )
+      )
+    );
+    const hint = ignored.some((flag) => ["--preset", "--include", "--exclude"].includes(flag)) ? " To scope a run, set include/excludePatterns/preset in snapshot.config.ts (or run `codebase-snapshot init` to generate one)." : "";
+    throw new UsageError(
+      `${ignored.join(", ")} ${ignored.length === 1 ? "does" : "do"} not apply to \`${command}\` and ${ignored.length === 1 ? "was" : "were"} not applied. ${ignored.length === 1 ? "It is" : "They are"} accepted by: ${owners.join(", ")}.${hint}`
+    );
   }
   if (command === "init" && values.preset !== void 0) {
     const requested = String(values.preset);
     if (!getPreset(requested)) throw new UsageError(unknownPresetMessage(requested));
   }
-  if (command !== "skill" && (values.install !== void 0 || values.target !== void 0)) {
-    throw new UsageError("--install and --target are only valid with `skill`.");
-  }
-  if (values.target !== void 0 && !isSkillTarget(String(values.target))) {
+  if (command === "skill" && values.target !== void 0 && !isSkillTarget(String(values.target))) {
     throw new UsageError(
       `--target must be one of: ${SKILL_TARGETS.join(", ")} (received "${String(values.target)}").`
     );
@@ -904,6 +1038,7 @@ function parseCliArgs(argv) {
     format: rawFormat,
     dryRun: values["dry-run"] === true,
     watch: values.watch === true,
+    noConfig: values["no-config"] === true,
     preset: values.preset === void 0 ? void 0 : String(values.preset),
     maxPartBytesRaw: values["max-part-bytes"] === void 0 ? void 0 : String(values["max-part-bytes"]),
     include: values.include === void 0 ? void 0 : String(values.include),
@@ -957,6 +1092,12 @@ function splitList(value) {
   if (value === void 0) return void 0;
   return value.split(",").map((entry) => entry.trim()).filter(Boolean);
 }
+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;
+  return absolute;
+}
 function describeManifestShapeProblem(manifest) {
   if (!manifest || typeof manifest !== "object" || Array.isArray(manifest)) {
     return "not a JSON object";
@@ -976,6 +1117,7 @@ async function runInitCommand(invocation) {
     const result = await runInit({
       cwd: invocation.cwd,
       preset: invocation.preset,
+      outDir: invocation.outDir,
       maxPartBytes: invocation.maxPartBytesRaw ?? invocation.maxPartBytes,
       include: splitList(invocation.include),
       exclude: splitList(invocation.exclude),
@@ -1002,7 +1144,11 @@ async function runInitCommand(invocation) {
     }
     for (const note of result.notes) info(`   \u26A0 ${note}`);
     info("");
-    info("   Next:  npm run snapshot");
+    if (result.scripts.length > 0) {
+      info("   Next:  npm run snapshot");
+    } else {
+      info(`   Next:  ${GENERATOR_NAME} generate`);
+    }
     info(
       `   Tip:   \`${GENERATOR_NAME} skill --install\` makes this repo discoverable by AI agents.`
     );
@@ -1018,6 +1164,13 @@ async function runInitCommand(invocation) {
 }
 function runSkillCommand(invocation) {
   if (!invocation.install) {
+    if (invocation.format === "json") {
+      process.stdout.write(
+        `${JSON.stringify({ name: SKILL_NAME, version: GENERATOR_VERSION, skill: renderSkill() }, null, 2)}
+`
+      );
+      return 0;
+    }
     process.stdout.write(renderSkill());
     return 0;
   }
@@ -1094,7 +1247,8 @@ ${USAGE}
   if (invocation.command === "skill") {
     return runSkillCommand(invocation);
   }
-  const loaded = await loadConfigFileDetailed(invocation.cwd);
+  const loaded = invocation.noConfig ? { 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) {
     warn("\u274C The config file could not be read. Fix it, or delete it to use the defaults.");
@@ -1166,7 +1320,7 @@ ${USAGE}
   if (invocation.command === "explain") {
     const result = explainPath(resolved, invocation.args[0]);
     emit(invocation.format, result, () => info(renderExplainText(result)));
-    return result.included ? 0 : 1;
+    return 0;
   }
   if (invocation.command === "diff") {
     try {
@@ -1190,7 +1344,9 @@ ${USAGE}
     if (invocation.dryRun) {
       info("\n\u{1F9EA} Dry run \u2014 nothing was written:");
       info(`   - Would track:  ${manifest.counts.totalFiles} files`);
-      info(`   - Would write:  ${manifest.counts.partsCount} part(s) under ${resolved.outDir}/parts/`);
+      info(
+        `   - Would write:  ${manifest.counts.partsCount} part(s) under ${displayOutPath(resolved.cwd, resolved.outDir, "parts")}`
+      );
       info(`   - Skipped:      ${manifest.counts.skippedCount} file(s)`);
       info(`   - Warnings:     ${manifest.warnings.length}`);
       info(`   - Integrity:    ${manifest.validation.status}`);
@@ -1205,7 +1361,9 @@ ${USAGE}
       );
       const { artifacts } = resolved;
       if (artifacts.parts) {
-        info(`   - Parts written: ${manifest.counts.partsCount} under ${resolved.outDir}/parts/`);
+        info(
+          `   - Parts written: ${manifest.counts.partsCount} under ${displayOutPath(resolved.cwd, resolved.outDir, "parts")}/`
+        );
       }
       const reports = [
         artifacts.projectTree && "project-tree",
@@ -1213,10 +1371,28 @@ ${USAGE}
         artifacts.audit && "audit"
       ].filter(Boolean);
       if (reports.length > 0) {
-        info(`   - Reports:       ${resolved.outDir}/reports/ (${reports.join(", ")})`);
+        info(
+          `   - Reports:       ${displayOutPath(resolved.cwd, resolved.outDir, "reports")}/ (${reports.join(", ")})`
+        );
+      }
+      if (artifacts.manifest) {
+        info(`   - Manifest:      ${displayOutPath(resolved.cwd, resolved.outDir, "manifest.json")}`);
+      }
+      if (artifacts.monolith) {
+        const monolithFiles = [
+          manifest.artifacts?.fullJson ? "full-codebase.json" : null,
+          manifest.artifacts?.fullMarkdown ? "full-codebase.md" : null
+        ].filter((name) => name !== null);
+        if (monolithFiles.length === 2) {
+          info(
+            `   - Monolith:      ${displayOutPath(resolved.cwd, resolved.outDir, "full-codebase.{json,md}")}`
+          );
+        } else if (monolithFiles.length === 1) {
+          info(
+            `   - Monolith:      ${displayOutPath(resolved.cwd, resolved.outDir, monolithFiles[0])} (the other was skipped by --max-monolith-bytes)`
+          );
+        }
       }
-      if (artifacts.manifest) info(`   - Manifest:      ${resolved.outDir}/manifest.json`);
-      if (artifacts.monolith) info(`   - Monolith:      ${resolved.outDir}/full-codebase.{json,md}`);
       if (reports.length === 0 && !artifacts.parts && !artifacts.manifest && !artifacts.monolith) {
         info(`   - Artifacts:     all disabled (only the ownership marker was written)`);
       }
@@ -1251,18 +1427,43 @@ ${USAGE}
 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-`)
+    (segment) => segment === outName || segment === tmpName || segment.startsWith(`${outName}.backup-`) || VCS_SEGMENTS.has(segment)
   );
   let running = false;
-  const regenerate = () => {
+  const regenerate = async () => {
     if (running) return;
     running = true;
     const started = performance.now();
     try {
-      const manifest = generateSnapshot(resolved, { dryRun: invocation.dryRun });
+      const loaded = 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.");
+        return;
+      }
+      for (const warning of loaded.warnings) warn(`\u26A0 Config: ${warning}`);
+      const next = resolveConfig(
+        loaded.config,
+        {
+          mode: invocation.command,
+          format: invocation.format,
+          dryRun: invocation.dryRun,
+          cwd: invocation.cwd,
+          outDir: invocation.outDir,
+          includeMonolith: invocation.includeMonolith,
+          includeSensitiveFiles: invocation.includeSensitiveFiles,
+          maxPartBytes: invocation.maxPartBytes,
+          largeFileBytes: invocation.largeFileBytes,
+          maxMonolithBytes: invocation.maxMonolithBytes,
+          skipArtifacts: invocation.skipArtifacts
+        },
+        invocation.cwd
+      );
+      const manifest = generateSnapshot(next, { dryRun: invocation.dryRun });
       const elapsed = ((performance.now() - started) / 1e3).toFixed(2);
       info(
         `\u267B\uFE0F  ${(/* @__PURE__ */ new Date()).toISOString()}  ${manifest.counts.totalFiles} file(s), ${manifest.counts.partsCount} part(s), ${manifest.validation.status} (${elapsed}s)`
@@ -1274,7 +1475,7 @@ async function runWatchLoop(invocation, resolved) {
     }
   };
   info("\u{1F440} Watching for changes. Press Ctrl+C to stop.");
-  regenerate();
+  void regenerate();
   let timer = null;
   const watcher = fs.watch(resolved.cwd, { recursive: true }, (_event, filename) => {
     if (filename) {
@@ -1282,7 +1483,7 @@ async function runWatchLoop(invocation, resolved) {
       if (isGenerated(changed)) return;
     }
     if (timer) clearTimeout(timer);
-    timer = setTimeout(regenerate, 250);
+    timer = setTimeout(() => void regenerate(), 250);
   });
   await new Promise((resolve2) => {
     const stop = () => {