@ankurhalder/codebase-snapshot 3.0.0 → 4.0.0

package/dist/cli.cjs

@@ -7,6 +7,7 @@ var url = require('url');
 var childProcess = require('child_process');
 var readline = require('readline');
 var crypto = require('crypto');
+var os = require('os');
 var ts = require('typescript');
 
 function _interopDefault (e) { return e && e.__esModule ? e : { default: e }; }
@@ -34,6 +35,7 @@ var path10__namespace = /*#__PURE__*/_interopNamespace(path10);
 var childProcess__namespace = /*#__PURE__*/_interopNamespace(childProcess);
 var readline__namespace = /*#__PURE__*/_interopNamespace(readline);
 var crypto__namespace = /*#__PURE__*/_interopNamespace(crypto);
+var os__namespace = /*#__PURE__*/_interopNamespace(os);
 var ts__default = /*#__PURE__*/_interopDefault(ts);
 
 // src/cli.ts
@@ -54,7 +56,40 @@ function hashMap(manifest) {
   }
   return map;
 }
+function manifestProblem(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return "not a JSON object";
+  const candidate = value;
+  if (!Array.isArray(candidate.files)) return 'no "files" array';
+  for (const entry of candidate.files) {
+    if (!entry || typeof entry !== "object" || Array.isArray(entry)) {
+      return 'a "files" entry is not an object';
+    }
+    if (typeof entry.relativePath !== "string") {
+      return 'a "files" entry has no "relativePath"';
+    }
+  }
+  const counts = candidate.counts;
+  if (!counts || typeof counts !== "object" || Array.isArray(counts)) {
+    return 'no "counts" object';
+  }
+  for (const key of ["totalFiles", "totalLines", "totalSizeBytes", "partsCount"]) {
+    if (typeof counts[key] !== "number") {
+      return `no numeric "counts.${key}"`;
+    }
+  }
+  if (typeof candidate.generatedAt !== "string") return 'no "generatedAt"';
+  if (typeof candidate.fingerprint !== "string") return 'no "fingerprint"';
+  return null;
+}
+function assertUsableManifest(value, label) {
+  const problem = manifestProblem(value);
+  if (problem) {
+    throw new Error(`The ${label} manifest is not a snapshot manifest this tool wrote: ${problem}.`);
+  }
+}
 function compareManifests(before, after) {
+  assertUsableManifest(before, "before");
+  assertUsableManifest(after, "after");
   const left = hashMap(before);
   const right = hashMap(after);
   const added = [];
@@ -100,11 +135,11 @@ function loadManifest(target) {
   } catch (err) {
     throw new Error(`Could not parse ${manifestPath}: ${err.message}`);
   }
-  if (!parsed || !Array.isArray(parsed.files)) {
-    throw new Error(`${manifestPath} is not a snapshot manifest (no "files" array).`);
-  }
-  if (!parsed.counts || typeof parsed.counts !== "object") {
-    throw new Error(`${manifestPath} is not a snapshot manifest (no "counts" object).`);
+  const problem = manifestProblem(parsed);
+  if (problem) {
+    throw new Error(
+      `${manifestPath} is not a usable snapshot manifest: ${problem}. Point diff at a manifest.json written by \`generate\` (or at the directory that holds it).`
+    );
   }
   return parsed;
 }
@@ -966,6 +1001,416 @@ function toDetected(preset) {
 function detectPreset(cwd, forced) {
   return detectPresetFromContext(buildPresetContext(cwd), forced);
 }
+
+// src/security/patterns.ts
+var STRONG_CREDENTIAL_NAME = "(?:password|passwd|passphrase|pwd|api[_-]?key|api[_-]?secret|secret[_-]?access[_-]?key|secret[_-]?key|client[_-]?secret[_-]?key|client[_-]?secret|private[_-]?key|aws[_-]?secret[_-]?access[_-]?key|access[_-]?token|refresh[_-]?token|auth[_-]?token|session[_-]?token|secret|token)";
+var WEAK_CREDENTIAL_NAME = "(?:pass|id[_-]?token|credentials?)";
+var NOT_A_LITERAL_VALUE = "(?!(?:string|number|boolean|bigint|symbol|unknown|any|never|void|null|undefined|true|false|process\\.env|Buffer|Record|object)\\b)";
+var UNQUOTED_LITERAL = "(?![0-9]+(?![A-Za-z0-9_+=/.-]))([A-Za-z0-9_+=/-]{1,512})(?![A-Za-z0-9_+=/.-]|\\()";
+var UNQUOTED_AMBIGUOUS_LITERAL = "(?![0-9]+(?![A-Za-z0-9_+=/.-]))([A-Za-z0-9_+=/-]{8,512})(?![A-Za-z0-9_+=/.-]|\\()";
+var UNQUOTED_STRONG_NAME = `(?<!id[-_])${STRONG_CREDENTIAL_NAME}`;
+var DEFAULT_SECRET_PATTERNS = [
+  {
+    rule: "private-key-header",
+    pattern: /-----BEGIN (?:[A-Z0-9]+ )*PRIVATE KEY(?: BLOCK)?-----|-----BEGIN (?:RSA |OPENSSH |EC |PGP |DSA |ENCRYPTED )?PRIVATE KEY-----/
+  },
+  {
+    rule: "jwt-token",
+    pattern: /eyJ[A-Za-z0-9_-]{10,1024}\.eyJ[A-Za-z0-9_-]{10,1024}\.[A-Za-z0-9_-]{10,1024}/
+  },
+  {
+    rule: "aws-access-key-id",
+    pattern: /(?:AKIA|ASIA|AGPA|AIDA|AROA|AIPA|ANPA|ANVA|ASCA)[0-9A-Z]{16}/
+  },
+  {
+    // The name is no longer limited to the three snake_case spellings: an
+    // `awsSecret` / `secretAccessKey` property leaked verbatim because only the
+    // literal words matched. The value is masked alone, so the key survives.
+    rule: "aws-secret-access-key",
+    pattern: new RegExp(
+      `${STRONG_CREDENTIAL_NAME}["']?\\s{0,8}[:=]\\s{0,8}["']?([A-Za-z0-9/+=]{40})["']?`,
+      "i"
+    ),
+    valueGroup: 1
+  },
+  {
+    // A 40-character base64 value with no key name in sight. A key-independent
+    // rule is the only thing that catches `new AWS.SecretKey(…)` arguments and
+    // pasted `~/.aws/credentials` fragments, but a bare length test also matches
+    // every 40-char git SHA-1, so the value must mix case and digits and must
+    // not be pure hex.
+    rule: "aws-secret-access-key-value",
+    pattern: /(?<![A-Za-z0-9/+=])(?![0-9a-fA-F]{40}(?![A-Za-z0-9/+=]))(?=[A-Za-z0-9/+=]{40}(?![A-Za-z0-9/+=]))(?=[A-Za-z0-9/+=]{0,39}[A-Z])(?=[A-Za-z0-9/+=]{0,39}[a-z])(?=[A-Za-z0-9/+=]{0,39}[0-9])[A-Za-z0-9/+=]{40}/
+  },
+  {
+    rule: "github-token",
+    pattern: /gh[pousr]_[A-Za-z0-9]{36,251}|github_pat_[A-Za-z0-9_]{22,251}|ghs_[A-Za-z0-9]{36,251}/
+  },
+  {
+    // `xoxc-`/`xoxd-` are the user and refresh tokens, `xoxb`/`xoxp` the bot and
+    // user tokens; the whole Slack family shares one prefix shape.
+    rule: "slack-token",
+    pattern: /xox[baprsdc]-[0-9A-Za-z-]{10,250}/
+  },
+  {
+    // Prefix-only vendors. Each prefix below is documented, globally unique and
+    // cannot collide with an ordinary identifier, which is what makes a bare
+    // prefix rule cheap and safe: `glpat-` (GitLab), `hvs.`/`s.` (Vault service
+    // and batch tokens), `whsec_` (Stripe webhook secret), `dckr_pat_` (Docker
+    // Hub), `hf_` (HuggingFace), `ya29.` (Google OAuth access token).
+    rule: "known-vendor-token-prefix",
+    pattern: /\b(?:glpat-[A-Za-z0-9_-]{20,64}|hvs\.[A-Za-z0-9_-]{20,128}|s\.[A-Za-z0-9]{20,64}|whsec_[A-Za-z0-9]{20,64}|dckr_pat_[A-Za-z0-9_-]{20,64}|hf_[A-Za-z0-9]{30,64}|ya29\.[A-Za-z0-9_-]{20,128})/
+  },
+  {
+    rule: "slack-webhook-url",
+    pattern: /hooks\.slack\.com\/services\/T[A-Z0-9]{6,12}\/B[A-Z0-9]{6,12}\/[A-Za-z0-9]{20,32}/
+  },
+  {
+    rule: "stripe-secret-key",
+    pattern: /[sr]k_live_[0-9a-zA-Z]{20,247}/
+  },
+  {
+    rule: "google-api-key",
+    pattern: /AIza[0-9A-Za-z_-]{35}/
+  },
+  {
+    rule: "google-oauth-client-secret",
+    pattern: /GOCSPX-[A-Za-z0-9_-]{20,64}/
+  },
+  {
+    rule: "openai-anthropic-key",
+    pattern: /\bsk-(?:ant-[a-z0-9]+-|proj-|svcacct-|admin-)?[A-Za-z0-9_-]{20,}_?[A-Za-z0-9_-]{0,20}\b/
+  },
+  {
+    rule: "npm-token",
+    pattern: /npm_[A-Za-z0-9]{36}/
+  },
+  {
+    rule: "pypi-token",
+    pattern: /pypi-[A-Za-z0-9_-]{50,180}/
+  },
+  {
+    rule: "sendgrid-key",
+    pattern: /SG\.[A-Za-z0-9_-]{22}\.[A-Za-z0-9_-]{43}/
+  },
+  {
+    rule: "twilio-api-key",
+    pattern: /SK[0-9a-fA-F]{32}/
+  },
+  {
+    rule: "digitalocean-token",
+    pattern: /dop_v1_[0-9a-f]{64}/
+  },
+  {
+    rule: "azure-storage-account-key",
+    pattern: /AccountKey=[A-Za-z0-9+/=]{80,100}/
+  },
+  {
+    // Scheme-less userinfo: `//user:password@host`.
+    //
+    // Enumerating schemes is a losing game — `mysqlx`, `svn`, `telnet`, `imap`,
+    // `pop3`, `nntp`, `kafka`, `elasticsearch` each leaked a password while the
+    // list grew by hand. This rule matches the shape instead, so any scheme
+    // (including one invented tomorrow) is covered, provided the `//` is followed
+    // immediately by the userinfo: `// see the docs` and a bare reminder comment
+    // never match, because a space or the comment wording breaks the shape.
+    rule: "uri-credentials",
+    pattern: /\/\/[^\s:/@"'`;()<>,]{1,128}:[^\s:/@"'`;()<>,]{1,256}@[^\s/"'`;()<>,]{1,256}/
+  },
+  {
+    // The host tail stops at quotes, `;`, `)`, `<`, `>` and `,`: an unbounded
+    // `[^\s/]` used to swallow the closing quote and the statement separator of
+    // the string the URL was written in.
+    rule: "database-uri-credentials",
+    pattern: /(?:mongodb(?:\+srv)?|postgres(?:ql)?|mysql|maria(?:db)?|redis(?:s)?|amqp(?:s)?|clickhouse|mssql|sqlserver|oracle):\/\/[^\s:@/"'`;()<>,]{1,128}:[^\s@/"'`;()<>,]{1,256}@[^\s/"'`;()<>,]{1,256}/
+  },
+  {
+    rule: "basic-auth-url",
+    pattern: /(?:https?|ftp|sftp|ssh|git|smtp|smtps|ldap|ldaps):\/\/[^\s:@/"'`;()<>,]{1,128}:[^\s@/"'`;()<>,]{1,256}@[^\s/"'`;()<>,]{1,256}/i
+  },
+  {
+    // Quoted credentials in any common key spelling. The value may be as short
+    // as one character: `password: "hunter2"` is a credential whatever its
+    // entropy, and a length floor was exactly how it survived into `parts`.
+    //
+    // The key is either bare (`dbPassword:`) or wholly quoted (`"dbPassword":`).
+    // There is deliberately no optional quote *before* the separator: that let a
+    // previous string's closing quote stand in for the key's, so
+    // ``${pass ? "  PASS" : "  FAIL"}`` had `"  FAIL"` masked as if `PASS` were
+    // the key name.
+    rule: "credential-assignment",
+    pattern: new RegExp(
+      `(?:["']${STRONG_CREDENTIAL_NAME}["']|${STRONG_CREDENTIAL_NAME})\\s{0,8}[:=]\\s{0,8}(["'\`])([^"'\`\\n]{1,512})\\1`,
+      "i"
+    ),
+    valueGroup: 2
+  },
+  {
+    // `pass`, `id-token` and `credentials` are ambiguous on their own, so they
+    // are accepted only against a quoted value long enough to be a credential.
+    rule: "credential-assignment-weak",
+    pattern: new RegExp(
+      `(?:["']${WEAK_CREDENTIAL_NAME}["']|${WEAK_CREDENTIAL_NAME})\\s{0,8}[:=]\\s{0,8}(["'\`])([^"'\`\\n]{8,512})\\1`,
+      "i"
+    ),
+    valueGroup: 2
+  },
+  {
+    // The unquoted twin for YAML, docker-compose and `.env`: those formats never
+    // quote their values, so the rules above cannot see them. `valueGroup` keeps
+    // `POSTGRES_PASSWORD:` in the output.
+    rule: "credential-assignment-unquoted",
+    pattern: new RegExp(
+      `${UNQUOTED_STRONG_NAME}\\s{0,8}[:=]\\s{0,8}${NOT_A_LITERAL_VALUE}${UNQUOTED_LITERAL}`,
+      "i"
+    ),
+    valueGroup: 1
+  },
+  {
+    // `pass: hunter2hunter2` and `credentials: hunter2hunter2`: the ambiguous
+    // names, unquoted, with the length and non-digit floor that keeps
+    // `pass: 3` / `credentials: none` readable.
+    rule: "credential-assignment-unquoted-weak",
+    pattern: new RegExp(
+      `${WEAK_CREDENTIAL_NAME}\\s{0,8}[:=]\\s{0,8}${NOT_A_LITERAL_VALUE}${UNQUOTED_AMBIGUOUS_LITERAL}`,
+      "i"
+    ),
+    valueGroup: 1
+  },
+  {
+    // `Authorization: Bearer <token>` and `Authorization: Basic <base64>`.
+    //
+    // The scheme is consumed by a lookbehind so the match is the token alone and
+    // needs no `valueGroup`. A lone `Bearer`/`Basic`, and a word after it that
+    // cannot be a credential (`Bearer authentication`), stay readable: the value
+    // must contain a digit, be at least 32 chars, or carry base64 `=` padding.
+    rule: "authorization-header",
+    pattern: /(?<=(?:Bearer|Basic)\s{1,8})(?:[A-Za-z0-9_.+/-]{0,31}[0-9][A-Za-z0-9_.+/-]{0,1024}|[A-Za-z0-9_.+/-]{32,1024}|[A-Za-z0-9_.+/-]{8,1024}={1,2})(?![A-Za-z0-9_.+/=-])/
+  },
+  {
+    // Broader names than before (`apiKey`, `clientSecret`, `privateKey` were
+    // invisible to it) and value-only masking. Kept alongside the two rules
+    // above because it also matches a *quoted key* followed by an unquoted
+    // value, e.g. `"client_secret": abc123`.
+    rule: "generic-secret-assignment",
+    pattern: /(?:api[_-]?key|secret[_-]?key|auth[_-]?token|client[_-]?secret|access[_-]?token|refresh[_-]?token|private[_-]?key|password|passwd|pwd)["']?\s*[:=]\s*["']([^"'\s]{8,256})["']/i,
+    valueGroup: 1
+  },
+  {
+    // Covers `.env` / shell assignment syntax, which never quotes its values and
+    // was therefore invisible to the rule above. Anchored to the line start and
+    // limited to secret-looking names to stay at zero false positives.
+    //
+    // The name is matched with BOUNDED quantifiers on purpose: an unbounded
+    // `[A-Za-z0-9_]*` on both sides of the keyword alternation backtracks at
+    // every offset of a long identifier, which made this rule quadratic
+    // (measured 5.6 s for a single 240 KB line before bounding).
+    // The value is matched on its own — `=\s*(value)` — and masked alone.
+    // Anchoring the value to end-of-line (`[^\s#]{6,512}$`) meant ANY trailing
+    // comment or space disabled the rule, so `TOKEN=secret # rotate` and
+    // `TOKEN=secret   ` were emitted in clear; a CRLF file disabled it wholesale.
+    rule: "env-secret-assignment",
+    pattern: /^\s{0,64}(?:export\s{1,8})?[A-Za-z0-9_]{0,96}(?:KEY|TOKEN|SECRET|PASSWORD|PASSWD|PASS|PWD|CREDENTIAL)[A-Za-z0-9_]{0,96}\s{0,8}=\s{0,8}(?!["'`$<{[\]\s])([^\s#;"'`)]{1,512})/i,
+    valueGroup: 1
+  }
+];
+var PEM_BLOCK_PATTERN = /-----BEGIN (?:[A-Z0-9]+ )*PRIVATE KEY(?: BLOCK)?-----[\s\S]*?-----END (?:[A-Z0-9]+ )*PRIVATE KEY(?: BLOCK)?-----/g;
+var PEM_UNTERMINATED_PATTERN = /-----BEGIN (?:[A-Z0-9]+ )*PRIVATE KEY(?: BLOCK)?-----(?:\r?\n[A-Za-z0-9+/=]{4,}[ A-Za-z0-9+/=]*)+/g;
+
+// src/security/redact.ts
+var REDACTION_MARKER = "[REDACTED: potential secret-like value omitted from snapshot]";
+var PEM_REDACTION_MARKER = "[REDACTED: private key block omitted from snapshot]";
+function describeValue(value) {
+  if (value === null) return "null";
+  if (Array.isArray(value)) return "an array";
+  if (value instanceof RegExp) return value.toString();
+  if (typeof value === "string") return `the string ${JSON.stringify(value)}`;
+  return `a ${typeof value}`;
+}
+function compilePattern(rule, pattern, valueGroup) {
+  if (pattern instanceof RegExp) {
+    const flags = new Set(pattern.flags.replace(/[gy]/g, "").split(""));
+    if (valueGroup !== void 0) flags.add("d");
+    return {
+      rule,
+      pattern: new RegExp(pattern.source, [...flags].join("")),
+      ...valueGroup === void 0 ? {} : { valueGroup }
+    };
+  }
+  if (typeof pattern === "string") {
+    try {
+      return {
+        rule,
+        pattern: new RegExp(pattern, valueGroup === void 0 ? "i" : "id"),
+        ...valueGroup === void 0 ? {} : { valueGroup }
+      };
+    } catch (err) {
+      throw new Error(
+        `Invalid regular expression for secret rule "${rule}": ${err.message}`
+      );
+    }
+  }
+  throw new Error(
+    `Secret rule "${rule}" has a pattern that is neither a RegExp nor a string (received ${describeValue(pattern)}).`
+  );
+}
+function compileSecretRules(rules) {
+  if (!Array.isArray(rules)) {
+    throw new Error(
+      `secrets.customPatterns must be an array of secret rules (received ${describeValue(rules)}).`
+    );
+  }
+  let generated = 0;
+  return rules.map((entry, index) => {
+    const where = `secrets.customPatterns[${index}]`;
+    if (entry instanceof RegExp) {
+      generated += 1;
+      return compilePattern(`custom-${generated}`, entry, void 0);
+    }
+    if (typeof entry === "string") {
+      generated += 1;
+      return compilePattern(`custom-${generated}`, entry, void 0);
+    }
+    if (typeof entry === "object" && entry !== null) {
+      const candidate = entry;
+      if (typeof candidate.rule !== "string" || candidate.rule.trim() === "") {
+        throw new Error(
+          `${where} is missing \`rule\` (received keys: ${Object.keys(candidate).join(", ") || "none"}). A named rule is { rule: "corp-token", pattern: /CORP-[A-Z0-9]{8}/ }, or pass the RegExp itself.`
+        );
+      }
+      const valueGroup = candidate.valueGroup;
+      if (valueGroup !== void 0) {
+        if (typeof valueGroup !== "number" || !Number.isInteger(valueGroup) || valueGroup < 0) {
+          throw new Error(
+            `${where}.valueGroup must be a non-negative integer capture-group index (received ${describeValue(valueGroup)}).`
+          );
+        }
+      }
+      if (candidate.pattern === void 0) {
+        throw new Error(
+          `${where} (rule "${candidate.rule}") is missing \`pattern\`. Expected { rule, pattern: RegExp | string }.`
+        );
+      }
+      return compilePattern(
+        candidate.rule,
+        candidate.pattern,
+        valueGroup
+      );
+    }
+    throw new Error(
+      `${where} must be a RegExp, a string, or { rule, pattern } (received ${describeValue(entry)}).`
+    );
+  });
+}
+function toGlobal(rule) {
+  const flags = new Set(rule.pattern.flags.replace(/[gy]/g, "").split(""));
+  flags.add("g");
+  if (rule.valueGroup !== void 0) flags.add("d");
+  return new RegExp(rule.pattern.source, [...flags].join(""));
+}
+var LINE_BREAK = /(\r\n|\n|\r)/;
+function scanAndRedactSecrets(content, rules, filePath) {
+  const findings = [];
+  let redacted = content;
+  for (const blockPattern of [PEM_BLOCK_PATTERN, PEM_UNTERMINATED_PATTERN]) {
+    blockPattern.lastIndex = 0;
+    let match;
+    while ((match = blockPattern.exec(redacted)) !== null) {
+      if (match[0].length === 0) {
+        blockPattern.lastIndex += 1;
+        continue;
+      }
+      const line = redacted.slice(0, match.index).split("\n").length;
+      const newlines = (match[0].match(/\n/g) ?? []).length;
+      findings.push({ rule: "private-key-block", line, path: filePath });
+      redacted = redacted.slice(0, match.index) + PEM_REDACTION_MARKER + "\n".repeat(newlines) + redacted.slice(match.index + match[0].length);
+      blockPattern.lastIndex = match.index + PEM_REDACTION_MARKER.length + newlines;
+    }
+  }
+  const compiled = rules.map((rule) => ({
+    rule: rule.rule,
+    pattern: toGlobal(rule),
+    ...rule.valueGroup === void 0 ? {} : { valueGroup: rule.valueGroup }
+  }));
+  const segments = redacted.split(LINE_BREAK);
+  let lineNumber = 1;
+  for (let index = 0; index < segments.length; index += 2) {
+    const line = segments[index];
+    if (line.length > 0) {
+      const spans = [];
+      const matchedRules = /* @__PURE__ */ new Set();
+      for (const { rule, pattern, valueGroup } of compiled) {
+        pattern.lastIndex = 0;
+        let match;
+        while ((match = pattern.exec(line)) !== null) {
+          if (match[0].length === 0) {
+            pattern.lastIndex += 1;
+            continue;
+          }
+          const group = valueGroup === void 0 ? void 0 : match.indices?.[valueGroup];
+          spans.push(
+            group ? { start: group[0], end: group[1], rule } : { start: match.index, end: match.index + match[0].length, rule }
+          );
+          matchedRules.add(rule);
+        }
+      }
+      if (spans.length > 0) {
+        for (const rule of matchedRules) {
+          findings.push({ rule, line: lineNumber, path: filePath });
+        }
+        segments[index] = applySpans(line, spans);
+      }
+    }
+    if (index + 1 < segments.length) lineNumber += 1;
+  }
+  return { redacted: segments.join(""), findings };
+}
+var TOKEN_CHARS_LEFT = /[A-Za-z0-9_+/-]/;
+var TOKEN_CHARS_RIGHT = /[A-Za-z0-9_+/=-]/;
+function expandOverToken(line, start, end) {
+  let left = start;
+  let right = end;
+  while (left > 0 && TOKEN_CHARS_LEFT.test(line[left - 1])) left -= 1;
+  while (right < line.length && TOKEN_CHARS_RIGHT.test(line[right])) right += 1;
+  return { start: left, end: right };
+}
+function applySpans(line, spans) {
+  const ordered = [...spans].sort((a, b) => a.start - b.start || a.end - b.end);
+  const merged = [];
+  for (const span of ordered) {
+    const clampedStart = Math.max(0, Math.min(span.start, line.length));
+    const clampedEnd = Math.max(clampedStart, Math.min(span.end, line.length));
+    const { start, end } = expandOverToken(line, clampedStart, clampedEnd);
+    const last = merged[merged.length - 1];
+    if (last && start <= last.end) last.end = Math.max(last.end, end);
+    else merged.push({ start, end });
+  }
+  let out = "";
+  let cursor = 0;
+  for (const span of merged) {
+    out += line.slice(cursor, span.start);
+    out += REDACTION_MARKER;
+    cursor = span.end;
+  }
+  out += line.slice(cursor);
+  return out;
+}
+
+// src/scanner/files.ts
+var PRESET_IGNORES = new Set(
+  PRESETS.flatMap((preset) => preset.exclude ?? [])
+);
+function readLinkTarget(linkPath, fallback) {
+  try {
+    return fs9__namespace.readlinkSync(linkPath);
+  } catch {
+    return fallback;
+  }
+}
+function isInside(root, candidate) {
+  const relative5 = path10__namespace.relative(root, candidate);
+  return relative5 === "" || !relative5.startsWith(`..${path10__namespace.sep}`) && relative5 !== ".." && !path10__namespace.isAbsolute(relative5);
+}
 function getGitInfo(cwd, fallbackBranch = "main") {
   try {
     const reported = childProcess__namespace.execSync("git rev-parse --abbrev-ref HEAD", {
@@ -1010,20 +1455,61 @@ var DEFAULT_IGNORED_FILES = [
   "bun.lockb",
   "composer.lock"
 ];
-var SENSITIVE_BASENAME = /^(?:\.env(?:[._-][A-Za-z0-9_-]*)*|\.env(?:backup|bak|old|orig|copy|save)|\.envrc|\.npmrc(?:\.[A-Za-z0-9_-]+)?|\.yarnrc(?:\.yml)?|\.netrc(?:\.[A-Za-z0-9_-]+)?|\.git-credentials|\.htpasswd|\.pgpass|id_[a-z0-9_]+(?:\.[A-Za-z0-9_-]+)?|credentials(?:\.json)?|service[-_]?account(?:\.[a-z0-9_-]+)*\.json|secrets?\.(?:json|ya?ml))$/i;
+var SENSITIVE_BASENAME = /^(?:\.env(?:[._-][A-Za-z0-9_-]*)*|\.env(?:backup|bak|old|orig|copy|save)|\.envrc|\.npmrc(?:\.[A-Za-z0-9_-]+)?|\.yarnrc(?:\.yml)?|\.netrc(?:\.[A-Za-z0-9_-]+)?|\.git-credentials|\.htpasswd|\.pgpass|\.vault-token|vault[-_]agent[-_]token|id_[a-z0-9_]+(?:\.[A-Za-z0-9_-]+)?|credentials(?:\.(?:json|ya?ml|toml))?|service[-_]?account(?:\.[a-z0-9_-]+)*\.json|secrets?\.(?:json|ya?ml|toml)|env|[A-Za-z0-9_-]{1,64}\.env)$/i;
 var SENSITIVE_PATH = /(?:^|\/)\.(?:aws|ssh|gnupg)\/|(?:^|\/)\.docker\/config\.json$|(?:^|\/)\.kube\/config$/i;
 var SENSITIVE_EXT = /\.(?:pem|key|p12|pfx|jks|keystore|ppk|asc|kdbx|tfstate|tfvars)$/i;
 var TEMPLATE_SUFFIX = /\.(?:example|sample|template|dist)(?=$|[.])/i;
+var BACKUP_SUFFIX = /(?:~|\.(?:bak|backup|old|orig|save|copy|swp|swo|tmp|part))$/i;
+function normaliseName(name) {
+  let normalised = name.trim().replace(/[. ]+$/, "");
+  let previous = "";
+  while (previous !== normalised) {
+    previous = normalised;
+    normalised = normalised.replace(BACKUP_SUFFIX, "");
+  }
+  return normalised;
+}
 var matchesSensitiveList = (posixPath, base) => SENSITIVE_BASENAME.test(base) || SENSITIVE_PATH.test(posixPath) || SENSITIVE_EXT.test(base);
 function isSensitivePath(relativePath) {
   const posixPath = relativePath.replace(/\\/g, "/");
-  const base = posixPath.split("/").pop() ?? posixPath;
+  const raw = posixPath.split("/").pop() ?? posixPath;
+  const base = normaliseName(raw);
   if (TEMPLATE_SUFFIX.test(base)) {
     const stripped = base.replace(new RegExp(TEMPLATE_SUFFIX.source, "gi"), "");
     if (matchesSensitiveList(posixPath, stripped)) return false;
   }
   return matchesSensitiveList(posixPath, base);
 }
+function findSecretInPath(relativePath) {
+  const posixPath = relativePath.replace(/\\/g, "/");
+  const spans = [];
+  const rules = [];
+  for (const { rule, pattern } of DEFAULT_SECRET_PATTERNS) {
+    const scan = new RegExp(pattern.source, `${pattern.flags.replace(/[gy]/g, "")}g`);
+    let match;
+    while ((match = scan.exec(posixPath)) !== null) {
+      if (match[0].length === 0) {
+        scan.lastIndex += 1;
+        continue;
+      }
+      spans.push({ start: match.index, end: match.index + match[0].length, rule });
+      if (!rules.includes(rule)) rules.push(rule);
+    }
+  }
+  if (spans.length === 0) return null;
+  spans.sort((a, b) => a.start - b.start || a.end - b.end);
+  let out = "";
+  let cursor = 0;
+  for (const span of spans) {
+    if (span.end <= cursor) continue;
+    const start = Math.max(span.start, cursor);
+    out += posixPath.slice(cursor, start);
+    out += REDACTION_MARKER;
+    cursor = Math.min(span.end, posixPath.length);
+  }
+  out += posixPath.slice(cursor);
+  return { rules, masked: out };
+}
 function globToRegExp(glob) {
   const normalized = glob.replace(/\\/g, "/").replace(/^\.\//, "").replace(/\/+$/, "");
   const anchored = normalized.startsWith("/");
@@ -1144,36 +1630,163 @@ function defaultIgnoreReason(relativePath) {
   }
   return null;
 }
-function collectFiles(cwd, options = {}) {
-  const includePatterns = options.includePatterns ?? [];
-  const excludePatterns = options.excludePatterns ?? [];
-  const includeSensitiveFiles = options.includeSensitiveFiles ?? false;
-  let candidates;
-  let walkSkips = [];
+function listIgnoredPaths(cwd) {
   try {
     const stdout = childProcess__namespace.execSync(
-      "git ls-files -z --cached --others --exclude-standard",
+      "git ls-files -z --others --ignored --exclude-standard --directory",
       {
         cwd,
         stdio: ["ignore", "pipe", "ignore"],
         encoding: "utf8",
-        maxBuffer: 50 * 1024 * 1024
+        maxBuffer: 32 * 1024 * 1024
       }
     );
-    candidates = stdout.split("\0").filter((entry) => entry.length > 0).map((entry) => entry.replace(/\\/g, "/"));
+    return stdout.split("\0").filter((entry) => entry.length > 0).map((entry) => entry.replace(/\\/g, "/"));
   } catch {
-    const walked = walkDirectory(cwd, cwd, /* @__PURE__ */ new Set());
-    candidates = walked.files;
-    walkSkips = walked.skipped;
+    return [];
   }
-  const skipped = [...walkSkips];
-  const files = candidates.filter((file) => {
-    const ignored = defaultIgnoreReason(file);
-    if (ignored) {
-      skipped.push({ path: file, reason: "default-ignore", detail: ignored });
-      return false;
-    }
-    if (includePatterns.length > 0 && !includePatterns.some((pattern) => matchesExclude(file, pattern))) {
+}
+var TOOL_OWNED_DIR_NAMES = /* @__PURE__ */ new Set(["snapshot", "snapshot.tmp"]);
+function isToolOwnedDirName(name) {
+  return TOOL_OWNED_DIR_NAMES.has(name) || name.startsWith("snapshot.backup-");
+}
+function hasSnapshotMarker(target) {
+  try {
+    return fs9__namespace.statSync(target).isDirectory() && fs9__namespace.existsSync(path10__namespace.join(target, ".codebase-snapshot"));
+  } catch {
+    return false;
+  }
+}
+function makeToolOwnedDecider(cwd) {
+  const markers = /* @__PURE__ */ new Map();
+  return (relativePath) => {
+    const parts = relativePath.replace(/\\/g, "/").split("/");
+    for (let depth = 1; depth < parts.length; depth += 1) {
+      const prefix = parts.slice(0, depth).join("/");
+      if (depth === 1 && isToolOwnedDirName(prefix)) return true;
+      let hasMarker = markers.get(prefix);
+      if (hasMarker === void 0) {
+        hasMarker = fs9__namespace.existsSync(path10__namespace.join(cwd, prefix, ".codebase-snapshot"));
+        markers.set(prefix, hasMarker);
+      }
+      if (hasMarker) return true;
+    }
+    return false;
+  };
+}
+function makeLinkProbe() {
+  const cache = /* @__PURE__ */ new Map();
+  return (absolutePath) => {
+    let known = cache.get(absolutePath);
+    if (known === void 0) {
+      try {
+        known = fs9__namespace.lstatSync(absolutePath).isSymbolicLink();
+      } catch {
+        known = false;
+      }
+      cache.set(absolutePath, known);
+    }
+    return known;
+  };
+}
+function dropLinkedDirectories(cwd, candidates, skipped) {
+  const isLink = makeLinkProbe();
+  let rootReal = cwd;
+  try {
+    rootReal = fs9__namespace.realpathSync(cwd);
+  } catch {
+  }
+  const reported = /* @__PURE__ */ new Set();
+  const kept = [];
+  for (const candidate of candidates) {
+    const parts = candidate.split("/");
+    let linkedDir = null;
+    for (let depth = 1; depth <= parts.length; depth += 1) {
+      const prefix = parts.slice(0, depth).join("/");
+      if (isLink(path10__namespace.join(cwd, prefix))) {
+        linkedDir = prefix;
+        break;
+      }
+    }
+    if (linkedDir === null) {
+      kept.push(candidate);
+      continue;
+    }
+    if (reported.has(linkedDir)) continue;
+    reported.add(linkedDir);
+    const absolute = path10__namespace.join(cwd, linkedDir);
+    let targetReal = absolute;
+    try {
+      targetReal = fs9__namespace.realpathSync(absolute);
+    } catch {
+    }
+    const target = readLinkTarget(absolute, targetReal);
+    const what = linkedDir === candidate ? "symbolic link" : "directory link";
+    skipped.push(
+      isInside(rootReal, targetReal) ? {
+        path: linkedDir,
+        reason: "symlink",
+        detail: `${what} not followed (target: ${target})`
+      } : {
+        path: linkedDir,
+        reason: "outside-root",
+        detail: `link target resolves outside the scanned root (target: ${target}); not followed`
+      }
+    );
+  }
+  return kept;
+}
+function collectFiles(cwd, options = {}) {
+  const includePatterns = options.includePatterns ?? [];
+  const excludePatterns = options.excludePatterns ?? [];
+  const includeSensitiveFiles = options.includeSensitiveFiles ?? false;
+  const isToolOwned = makeToolOwnedDecider(cwd);
+  let candidates;
+  const skipped = [];
+  try {
+    const stdout = childProcess__namespace.execSync(
+      "git ls-files -z --cached --others --exclude-standard",
+      {
+        cwd,
+        stdio: ["ignore", "pipe", "ignore"],
+        encoding: "utf8",
+        maxBuffer: 50 * 1024 * 1024
+      }
+    );
+    candidates = stdout.split("\0").filter((entry) => entry.length > 0).map((entry) => entry.replace(/\\/g, "/"));
+    candidates = dropLinkedDirectories(cwd, candidates, skipped);
+    const known = new Set(candidates);
+    for (const ignoredPath of listIgnoredPaths(cwd)) {
+      const trimmed = ignoredPath.replace(/\/+$/, "");
+      if (known.has(trimmed) || known.has(ignoredPath)) continue;
+      if (isToolOwned(trimmed)) continue;
+      if (isSensitivePath(trimmed)) {
+        skipped.push({
+          path: trimmed,
+          reason: "sensitive-file",
+          detail: "credential-bearing file, ignored by .gitignore; enable includeSensitiveFiles to emit it"
+        });
+      } else {
+        skipped.push({
+          path: trimmed,
+          reason: "gitignore",
+          detail: ignoredPath.endsWith("/") ? "ignored by .gitignore (directory, not descended)" : "ignored by .gitignore"
+        });
+      }
+    }
+  } catch {
+    const walked = walkDirectory(cwd, cwd, /* @__PURE__ */ new Set(), true);
+    candidates = walked.files;
+    skipped.push(...walked.skipped);
+  }
+  const files = candidates.filter((file) => {
+    if (isToolOwned(file)) return false;
+    const ignored = defaultIgnoreReason(file);
+    if (ignored) {
+      skipped.push({ path: file, reason: "default-ignore", detail: ignored });
+      return false;
+    }
+    if (includePatterns.length > 0 && !includePatterns.some((pattern) => matchesExclude(file, pattern))) {
       skipped.push({
         path: file,
         reason: "excluded",
@@ -1183,10 +1796,11 @@ function collectFiles(cwd, options = {}) {
     }
     for (const pattern of excludePatterns) {
       if (matchesExclude(file, pattern)) {
+        const fromPreset = PRESET_IGNORES.has(pattern);
         skipped.push({
           path: file,
-          reason: "excluded",
-          detail: `matches exclude pattern "${pattern}"`
+          reason: fromPreset ? "default-ignore" : "excluded",
+          detail: fromPreset ? `preset ignore: "${pattern}"` : `matches exclude pattern "${pattern}"`
         });
         return false;
       }
@@ -1199,11 +1813,20 @@ function collectFiles(cwd, options = {}) {
       });
       return false;
     }
+    const secret = findSecretInPath(file);
+    if (secret) {
+      skipped.push({
+        path: secret.masked,
+        reason: "sensitive-path",
+        detail: `path matches secret rule "${secret.rules.join('", "')}"; the file was skipped and its path is masked here because paths are emitted into every artifact`
+      });
+      return false;
+    }
     return true;
   }).sort();
   return { files, skipped };
 }
-function walkDirectory(dir, baseDir, visited) {
+function walkDirectory(dir, baseDir, visited, isRoot = false) {
   const results = { files: [], skipped: [] };
   let realDir;
   try {
@@ -1213,7 +1836,13 @@ function walkDirectory(dir, baseDir, visited) {
   }
   if (visited.has(realDir)) return results;
   visited.add(realDir);
-  const ignoredByGitignore = dir === baseDir ? readGitignoreMatcher(baseDir) : () => false;
+  let rootReal;
+  try {
+    rootReal = fs9__namespace.realpathSync(baseDir);
+  } catch {
+    rootReal = baseDir;
+  }
+  const ignoredByGitignore = isRoot ? readGitignoreMatcher(baseDir) : () => false;
   let entries;
   try {
     entries = fs9__namespace.readdirSync(dir, { withFileTypes: true });
@@ -1222,30 +1851,79 @@ function walkDirectory(dir, baseDir, visited) {
     return results;
   }
   for (const entry of entries) {
-    if (DEFAULT_IGNORED_DIRS.includes(entry.name)) continue;
     const fullPath = path10__namespace.join(dir, entry.name);
     const relPath = path10__namespace.relative(baseDir, fullPath).replace(/\\/g, "/");
-    if (ignoredByGitignore(relPath)) continue;
+    if (isToolOwnedDirName(entry.name)) continue;
+    if (DEFAULT_IGNORED_DIRS.includes(entry.name)) {
+      results.skipped.push({
+        path: relPath,
+        reason: "default-ignore",
+        detail: `built-in ignore: directory "${entry.name}" (not descended)`
+      });
+      continue;
+    }
+    if (DEFAULT_IGNORED_FILES.includes(entry.name) || entry.name.startsWith("snapshot.backup-")) {
+      results.skipped.push({
+        path: relPath,
+        reason: "default-ignore",
+        detail: "built-in ignore: filename"
+      });
+      continue;
+    }
+    if (ignoredByGitignore(relPath)) {
+      if (!hasSnapshotMarker(fullPath)) {
+        results.skipped.push({
+          path: relPath,
+          reason: isSensitivePath(relPath) ? "sensitive-file" : "gitignore",
+          detail: "ignored by .gitignore"
+        });
+      }
+      continue;
+    }
     let isDirectory = entry.isDirectory();
     let isFile = entry.isFile();
     if (entry.isSymbolicLink()) {
+      let targetReal;
       try {
-        const stats = fs9__namespace.statSync(fullPath);
-        isDirectory = stats.isDirectory();
-        isFile = stats.isFile();
-        if (!isDirectory && !isFile) {
-          results.skipped.push({ path: relPath, reason: "symlink", detail: "not a file or directory" });
-          continue;
-        }
+        targetReal = fs9__namespace.realpathSync(fullPath);
+      } catch {
+        results.skipped.push({ path: relPath, reason: "read-error", detail: "broken symlink" });
+        continue;
+      }
+      let stats;
+      try {
+        stats = fs9__namespace.statSync(fullPath);
+      } catch {
+        results.skipped.push({ path: relPath, reason: "read-error", detail: "unreadable symlink" });
+        continue;
+      }
+      const linkTarget = readLinkTarget(fullPath, targetReal);
+      if (!isInside(rootReal, targetReal)) {
+        results.skipped.push({
+          path: relPath,
+          reason: "outside-root",
+          detail: `link target resolves outside the scanned root (target: ${linkTarget}); not followed`
+        });
+        continue;
+      }
+      if (stats.isDirectory()) {
         results.skipped.push({
           path: relPath,
           reason: "symlink",
-          detail: isDirectory ? "followed directory symlink" : "followed file symlink"
+          detail: `directory link not followed (target: ${linkTarget})`
+        });
+        continue;
+      }
+      if (!stats.isFile()) {
+        results.skipped.push({
+          path: relPath,
+          reason: "symlink",
+          detail: `link to neither a file nor a directory (target: ${linkTarget})`
         });
-      } catch {
-        results.skipped.push({ path: relPath, reason: "read-error", detail: "broken symlink" });
         continue;
       }
+      isDirectory = false;
+      isFile = true;
     }
     if (isDirectory) {
       const nested = walkDirectory(fullPath, baseDir, visited);
@@ -1258,195 +1936,6 @@ function walkDirectory(dir, baseDir, visited) {
   return results;
 }
 
-// src/security/patterns.ts
-var DEFAULT_SECRET_PATTERNS = [
-  {
-    rule: "private-key-header",
-    pattern: /-----BEGIN (?:[A-Z0-9]+ )*PRIVATE KEY(?: BLOCK)?-----|-----BEGIN (?:RSA |OPENSSH |EC |PGP |DSA |ENCRYPTED )?PRIVATE KEY-----/
-  },
-  {
-    rule: "jwt-token",
-    pattern: /eyJ[A-Za-z0-9_-]{10,1024}\.eyJ[A-Za-z0-9_-]{10,1024}\.[A-Za-z0-9_-]{10,1024}/
-  },
-  {
-    rule: "aws-access-key-id",
-    pattern: /(?:AKIA|ASIA|AGPA|AIDA|AROA|AIPA|ANPA|ANVA|ASCA)[0-9A-Z]{16}/
-  },
-  {
-    rule: "aws-secret-access-key",
-    pattern: /(?:aws_secret_access_key|aws_secret_key|secret_access_key)["']?\s*[:=]\s*["']?[A-Za-z0-9/+=]{40}["']?/i
-  },
-  {
-    rule: "github-token",
-    pattern: /gh[pousr]_[A-Za-z0-9]{36,251}|github_pat_[A-Za-z0-9_]{22,251}|ghs_[A-Za-z0-9]{36,251}/
-  },
-  {
-    rule: "slack-token",
-    pattern: /xox[baprs]-[0-9A-Za-z-]{10,250}/
-  },
-  {
-    rule: "slack-webhook-url",
-    pattern: /hooks\.slack\.com\/services\/T[A-Z0-9]{6,12}\/B[A-Z0-9]{6,12}\/[A-Za-z0-9]{20,32}/
-  },
-  {
-    rule: "stripe-secret-key",
-    pattern: /[sr]k_live_[0-9a-zA-Z]{20,247}/
-  },
-  {
-    rule: "google-api-key",
-    pattern: /AIza[0-9A-Za-z_-]{35}/
-  },
-  {
-    rule: "google-oauth-client-secret",
-    pattern: /GOCSPX-[A-Za-z0-9_-]{20,64}/
-  },
-  {
-    rule: "openai-anthropic-key",
-    pattern: /\bsk-(?:ant-[a-z0-9]+-|proj-|svcacct-|admin-)?[A-Za-z0-9_-]{20,}_?[A-Za-z0-9_-]{0,20}\b/
-  },
-  {
-    rule: "npm-token",
-    pattern: /npm_[A-Za-z0-9]{36}/
-  },
-  {
-    rule: "pypi-token",
-    pattern: /pypi-[A-Za-z0-9_-]{50,180}/
-  },
-  {
-    rule: "sendgrid-key",
-    pattern: /SG\.[A-Za-z0-9_-]{22}\.[A-Za-z0-9_-]{43}/
-  },
-  {
-    rule: "twilio-api-key",
-    pattern: /SK[0-9a-fA-F]{32}/
-  },
-  {
-    rule: "digitalocean-token",
-    pattern: /dop_v1_[0-9a-f]{64}/
-  },
-  {
-    rule: "azure-storage-account-key",
-    pattern: /AccountKey=[A-Za-z0-9+/=]{80,100}/
-  },
-  {
-    rule: "database-uri-credentials",
-    pattern: /(?:mongodb(?:\+srv)?|postgres(?:ql)?|mysql|maria(?:db)?|redis(?:s)?|amqp(?:s)?|clickhouse):\/\/[^\s:@/]{1,128}:[^\s@/]{1,256}@[^\s/]{1,256}/
-  },
-  {
-    rule: "basic-auth-url",
-    pattern: /(?:https?|ftp|sftp|ssh|git):\/\/[^\s:@/]{1,128}:[^\s@/]{1,256}@[^\s/]{1,256}/i
-  },
-  {
-    rule: "generic-secret-assignment",
-    pattern: /(?:api[_-]?key|secret[_-]?key|auth[_-]?token|client[_-]?secret|access[_-]?token|refresh[_-]?token|private[_-]?key|password|passwd|pwd)["']?\s*[:=]\s*["'][^"'\s]{8,256}["']/i
-  },
-  {
-    // Covers `.env` / shell assignment syntax, which never quotes its values and
-    // was therefore invisible to the rule above. Anchored to the line start and
-    // limited to secret-looking names to stay at zero false positives.
-    //
-    // The name is matched with BOUNDED quantifiers on purpose: an unbounded
-    // `[A-Za-z0-9_]*` on both sides of the keyword alternation backtracks at
-    // every offset of a long identifier, which made this rule quadratic
-    // (measured 5.6 s for a single 240 KB line before bounding).
-    rule: "env-secret-assignment",
-    pattern: /^\s{0,64}(?:export\s{1,8})?[A-Za-z0-9_]{0,96}(?:KEY|TOKEN|SECRET|PASSWORD|PASSWD|PWD|CREDENTIAL)[A-Za-z0-9_]{0,96}\s{0,8}=\s{0,8}(?![\s$<{[])[^\s#]{6,512}$/i
-  }
-];
-var PEM_BLOCK_PATTERN = /-----BEGIN (?:[A-Z0-9]+ )*PRIVATE KEY(?: BLOCK)?-----[\s\S]*?-----END (?:[A-Z0-9]+ )*PRIVATE KEY(?: BLOCK)?-----/g;
-var PEM_UNTERMINATED_PATTERN = /-----BEGIN (?:[A-Z0-9]+ )*PRIVATE KEY(?: BLOCK)?-----(?:\r?\n[A-Za-z0-9+/=]{4,}[ A-Za-z0-9+/=]*)+/g;
-
-// src/security/redact.ts
-var REDACTION_MARKER = "[REDACTED: potential secret-like value omitted from snapshot]";
-var PEM_REDACTION_MARKER = "[REDACTED: private key block omitted from snapshot]";
-function compileSecretRules(rules) {
-  return rules.map((rule) => {
-    if (rule.pattern instanceof RegExp) {
-      return {
-        rule: rule.rule,
-        pattern: new RegExp(rule.pattern.source, rule.pattern.flags.replace(/[gy]/g, ""))
-      };
-    }
-    if (typeof rule.pattern === "string") {
-      try {
-        return { rule: rule.rule, pattern: new RegExp(rule.pattern, "i") };
-      } catch (err) {
-        throw new Error(
-          `Invalid regular expression for secret rule "${rule.rule}": ${err.message}`
-        );
-      }
-    }
-    throw new Error(
-      `Secret rule "${String(rule.rule)}" has a pattern that is neither a RegExp nor a string.`
-    );
-  });
-}
-function toGlobal(pattern) {
-  const flags = pattern.flags.replace(/[gy]/g, "");
-  return new RegExp(pattern.source, `${flags}g`);
-}
-function scanAndRedactSecrets(content, rules, filePath) {
-  const findings = [];
-  let redacted = content;
-  for (const blockPattern of [PEM_BLOCK_PATTERN, PEM_UNTERMINATED_PATTERN]) {
-    blockPattern.lastIndex = 0;
-    let match;
-    while ((match = blockPattern.exec(redacted)) !== null) {
-      if (match[0].length === 0) {
-        blockPattern.lastIndex += 1;
-        continue;
-      }
-      const line = redacted.slice(0, match.index).split("\n").length;
-      const newlines = (match[0].match(/\n/g) ?? []).length;
-      findings.push({ rule: "private-key-block", line, path: filePath });
-      redacted = redacted.slice(0, match.index) + PEM_REDACTION_MARKER + "\n".repeat(newlines) + redacted.slice(match.index + match[0].length);
-      blockPattern.lastIndex = match.index + PEM_REDACTION_MARKER.length + newlines;
-    }
-  }
-  const compiled = rules.map((rule) => ({
-    rule: rule.rule,
-    pattern: toGlobal(rule.pattern)
-  }));
-  const lines = redacted.split("\n");
-  const redactedLines = lines.map((line, index) => {
-    if (line.length === 0) return line;
-    const spans = [];
-    const matchedRules = /* @__PURE__ */ new Set();
-    for (const { rule, pattern } of compiled) {
-      pattern.lastIndex = 0;
-      let match;
-      while ((match = pattern.exec(line)) !== null) {
-        if (match[0].length === 0) {
-          pattern.lastIndex += 1;
-          continue;
-        }
-        spans.push({ start: match.index, end: match.index + match[0].length, rule });
-        matchedRules.add(rule);
-      }
-    }
-    if (spans.length === 0) return line;
-    for (const rule of matchedRules) {
-      findings.push({ rule, line: index + 1, path: filePath });
-    }
-    return applySpans(line, spans);
-  });
-  return { redacted: redactedLines.join("\n"), findings };
-}
-function applySpans(line, spans) {
-  const ordered = [...spans].sort((a, b) => a.start - b.start || a.end - b.end);
-  let out = "";
-  let cursor = 0;
-  for (const span of ordered) {
-    if (span.end <= cursor) continue;
-    const start = Math.max(span.start, cursor);
-    out += line.slice(cursor, start);
-    out += REDACTION_MARKER;
-    cursor = Math.min(span.end, line.length);
-  }
-  out += line.slice(cursor);
-  return out;
-}
-
 // src/config.ts
 var CONFIG_FILENAMES = [
   "snapshot.config.ts",
@@ -1496,7 +1985,12 @@ function normalizeResolvedConfig(config) {
     ),
     include: resolveInclude(config.include),
     preset: typeof config.preset === "string" ? config.preset : "generic",
-    presetExclude: Array.isArray(config.presetExclude) ? config.presetExclude : [],
+    presetExclude: [
+      .../* @__PURE__ */ new Set([
+        ...Array.isArray(config.presetExclude) ? config.presetExclude : [],
+        ...outputExcludePatterns(config.cwd, config.outDir, config.tmpDir)
+      ])
+    ],
     layersMode: config.layersMode === "replace" ? "replace" : "merge",
     budgets: config.budgets && typeof config.budgets === "object" ? config.budgets : { default: config.maxPartBytes, byLayer: {} },
     hooks: resolveHooks(config.hooks),
@@ -1533,7 +2027,68 @@ function supportsTypeScriptImports() {
   return major > 22 || major === 22 && minor >= 6;
 }
 function stripJsonComments(raw) {
-  return raw.replace(/^\uFEFF/, "").replace(/\/\*[\s\S]*?\*\//g, "").replace(/(^|[^:"'\\])\/\/.*$/gm, "$1");
+  const text2 = raw.replace(/^\uFEFF/, "");
+  let out = "";
+  let inString = false;
+  let escaped = false;
+  for (let index = 0; index < text2.length; index += 1) {
+    const char = text2[index];
+    if (inString) {
+      out += char;
+      if (escaped) escaped = false;
+      else if (char === "\\") escaped = true;
+      else if (char === '"') inString = false;
+      continue;
+    }
+    if (char === '"') {
+      inString = true;
+      out += char;
+      continue;
+    }
+    if (char === "/" && text2[index + 1] === "/") {
+      while (index < text2.length && text2[index] !== "\n" && text2[index] !== "\r") index += 1;
+      index -= 1;
+      continue;
+    }
+    if (char === "/" && text2[index + 1] === "*") {
+      index += 2;
+      while (index < text2.length && !(text2[index] === "*" && text2[index + 1] === "/")) {
+        if (text2[index] === "\n" || text2[index] === "\r") out += text2[index];
+        index += 1;
+      }
+      index += 1;
+      continue;
+    }
+    out += char;
+  }
+  return stripTrailingCommas(out);
+}
+function stripTrailingCommas(text2) {
+  let out = "";
+  let inString = false;
+  let escaped = false;
+  for (let index = 0; index < text2.length; index += 1) {
+    const char = text2[index];
+    if (inString) {
+      out += char;
+      if (escaped) escaped = false;
+      else if (char === "\\") escaped = true;
+      else if (char === '"') inString = false;
+      continue;
+    }
+    if (char === '"') {
+      inString = true;
+      out += char;
+      continue;
+    }
+    if (char === ",") {
+      let next = index + 1;
+      while (next < text2.length && /\s/.test(text2[next])) next += 1;
+      if (text2[next] === "}" || text2[next] === "]") continue;
+    }
+    out += char;
+  }
+  return out;
 }
 function parseJsonish(raw, file) {
   try {
@@ -1542,6 +2097,47 @@ function parseJsonish(raw, file) {
     throw new Error(`Could not parse ${file}: ${err.message}`);
   }
 }
+function describeValue2(value) {
+  if (value === null) return "null";
+  if (Array.isArray(value)) return "an array";
+  if (value instanceof RegExp) return value.toString();
+  if (typeof value === "function") return "a function";
+  if (typeof value === "string") return JSON.stringify(value);
+  if (typeof value === "object") {
+    const keys = Object.keys(value);
+    return keys.length > 0 ? `an object with keys ${keys.join(", ")}` : "an empty object";
+  }
+  return `${typeof value} (${String(value)})`;
+}
+var isThenable = (value) => typeof value.then === "function";
+function readConfigExport(exported, file) {
+  if (exported === void 0 || exported === null) {
+    throw new Error(
+      `${file} does not export a configuration object (received ${describeValue2(exported)}).`
+    );
+  }
+  if (Array.isArray(exported)) {
+    throw new Error(
+      `${file} exports an array; expected a single configuration object such as \`export default { outDir: "snapshot" }\`.`
+    );
+  }
+  if (typeof exported === "function") {
+    throw new Error(
+      `${file} exports a function; expected a configuration object. Call the function yourself and export its result.`
+    );
+  }
+  if (typeof exported !== "object") {
+    throw new Error(
+      `${file} does not export a configuration object (received ${describeValue2(exported)}).`
+    );
+  }
+  if (isThenable(exported)) {
+    throw new Error(
+      `${file} exports a Promise/thenable, not a configuration object. An async config is read synchronously, so its settings would be ignored: export a plain object (\`const config = {\u2026}; export default config;\`).`
+    );
+  }
+  return exported;
+}
 async function loadConfigFileDetailed(cwd) {
   const warnings = [];
   const errors = [];
@@ -1571,13 +2167,7 @@ async function loadConfigFileDetailed(cwd) {
     }
     try {
       const imported = await import(url.pathToFileURL(fullPath).href);
-      const config = imported.default ?? imported;
-      if (!config || typeof config !== "object") {
-        const message = `${fullPath} does not export a configuration object.`;
-        warnings.push(message);
-        errors.push(message);
-        continue;
-      }
+      const config = readConfigExport(imported.default ?? imported, fullPath);
       return { config, file: fullPath, warnings, errors };
     } catch (err) {
       const message = `Could not load ${fullPath}: ${err.message}`;
@@ -1627,7 +2217,7 @@ var DEFAULT_ARTIFACTS = {
 function isArtifactName(value) {
   return ARTIFACT_NAMES.includes(value);
 }
-function resolveArtifacts(requested, skipped, includeMonolith) {
+function resolveArtifacts(requested, skipped, includeMonolith, monolithOverride) {
   const artifacts = {
     ...DEFAULT_ARTIFACTS,
     // `includeMonolith` predates this selection and stays the switch for it.
@@ -1649,6 +2239,9 @@ function resolveArtifacts(requested, skipped, includeMonolith) {
       artifacts[name] = value;
     }
   }
+  if (monolithOverride !== void 0) {
+    artifacts.monolith = monolithOverride;
+  }
   for (const name of skipped ?? []) {
     if (!isArtifactName(name)) {
       throw new Error(
@@ -1659,9 +2252,106 @@ function resolveArtifacts(requested, skipped, includeMonolith) {
   }
   return artifacts;
 }
-function positiveInteger(value, fallback) {
-  if (!Number.isFinite(value) || value <= 0) return fallback;
-  return Math.floor(value);
+function strictPositiveInteger(value, fallback, label) {
+  if (value === void 0) return fallback;
+  if (typeof value !== "number" || !Number.isInteger(value) || value <= 0) {
+    throw new Error(`${label} must be a positive integer (received ${describeValue2(value)}).`);
+  }
+  return value;
+}
+function strictBoolean(value, fallback, label) {
+  if (value === void 0) return fallback;
+  if (typeof value !== "boolean") {
+    throw new Error(`${label} must be true or false (received ${describeValue2(value)}).`);
+  }
+  return value;
+}
+function strictString(value, fallback, label) {
+  if (value === void 0) return fallback;
+  if (typeof value !== "string" || value.trim() === "") {
+    throw new Error(`${label} must be a non-empty string (received ${describeValue2(value)}).`);
+  }
+  return value;
+}
+function resolveExcludePatterns(value) {
+  if (value === void 0) return [];
+  if (!Array.isArray(value) || value.some((pattern) => typeof pattern !== "string")) {
+    throw new Error(
+      `\`excludePatterns\` must be an array of glob strings such as ["**/*.test.ts"] (received ${describeValue2(value)}).`
+    );
+  }
+  return value.map((pattern) => pattern.trim()).filter(Boolean);
+}
+var AUTO_PRESET_ALIASES = /* @__PURE__ */ new Set(["auto", "detected"]);
+function resolvePresetName(value) {
+  if (value === void 0) return void 0;
+  if (typeof value !== "string" || value.trim() === "") {
+    throw new Error(
+      `\`preset\` must be a preset name (received ${describeValue2(value)}). Use "detected" (or "auto") to detect one, or one of: ${listPresetNames().join(", ")}.`
+    );
+  }
+  const name = value.trim();
+  return AUTO_PRESET_ALIASES.has(name.toLowerCase()) ? void 0 : name;
+}
+function resolveRuleList(value, kind) {
+  const collection = kind === "layer" ? "layers" : "kinds";
+  const example = kind === "layer" ? `{ name: "api", match: "src/api/**" }` : `{ kind: "route", match: "src/routes/**" }`;
+  if (value === void 0) return [];
+  if (!Array.isArray(value)) {
+    throw new Error(
+      `\`${collection}\` must be an array of ${kind} rules (received ${describeValue2(value)}). A ${kind} rule is ${example}.`
+    );
+  }
+  return value.map((entry, index) => {
+    const where = `${collection}[${index}]`;
+    if (typeof entry !== "object" || entry === null || Array.isArray(entry)) {
+      throw new Error(`${where} must be an object (received ${describeValue2(entry)}). A ${kind} rule is ${example}.`);
+    }
+    const record = entry;
+    const keys = Object.keys(record);
+    const canonical = kind === "layer" ? "name" : "kind";
+    const alias = kind === "layer" ? "layer" : "name";
+    const rawName = typeof record[canonical] === "string" ? record[canonical] : typeof record[alias] === "string" ? record[alias] : void 0;
+    if (rawName === void 0 || rawName.trim() === "") {
+      throw new Error(
+        `${where} is missing \`${canonical}\` (received keys: ${keys.join(", ") || "none"}). A ${kind} rule is ${example}; \`${alias}\` is accepted as an alias of \`${canonical}\`.`
+      );
+    }
+    const match = record.match;
+    if (match === void 0) {
+      throw new Error(
+        `${where}.match is required (received keys: ${keys.join(", ") || "none"}). Use a glob string ("src/api/**"), a RegExp (/\\\\.tsx$/) or a function.`
+      );
+    }
+    if (!(typeof match === "string" || match instanceof RegExp || typeof match === "function")) {
+      throw new Error(`${where}.match must be a string, a RegExp or a function (received ${describeValue2(match)}).`);
+    }
+    if (typeof match === "string" && match.trim() === "") {
+      throw new Error(`${where}.match must not be an empty string.`);
+    }
+    return {
+      name: rawName.trim(),
+      match
+    };
+  });
+}
+function resolveLayerRules(value) {
+  return resolveRuleList(value, "layer").map((rule) => ({ name: rule.name, match: rule.match }));
+}
+function resolveKindRules(value) {
+  return resolveRuleList(value, "kind").map((rule) => ({ kind: rule.name, match: rule.match }));
+}
+function outputExcludePatterns(cwd, outDir, tmpDir) {
+  const patterns = [];
+  for (const dir of [outDir, tmpDir]) {
+    const absolute = path10__namespace.resolve(cwd, dir);
+    const relative5 = path10__namespace.relative(cwd, absolute);
+    if (!relative5 || relative5 === ".." || relative5.startsWith(`..${path10__namespace.sep}`) || path10__namespace.isAbsolute(relative5)) {
+      continue;
+    }
+    patterns.push(`${relative5.replace(/\\/g, "/")}/**`);
+  }
+  return patterns;
 }
 var BYTE_UNITS = {
   b: 1,
@@ -1730,11 +2420,13 @@ function resolveLayersMode(mode) {
   }
   return mode;
 }
-function resolveBudgets(budgets, fallback) {
+function resolveBudgets(budgets, fallback, overrideDefault) {
   const byLayer = {};
   if (budgets === void 0) return { default: fallback, byLayer };
   if (typeof budgets !== "object" || budgets === null || Array.isArray(budgets)) {
-    throw new Error("`budgets` must be an object.");
+    throw new Error(
+      `\`budgets\` must be an object such as { default: "120k", byLayer: { api: "60k" } } (received ${describeValue2(budgets)}).`
+    );
   }
   if (budgets.byLayer !== void 0) {
     if (typeof budgets.byLayer !== "object" || budgets.byLayer === null) {
@@ -1749,10 +2441,12 @@ function resolveBudgets(budgets, fallback) {
       );
     }
   }
-  return {
-    default: boundedBytes(budgets.default, fallback, MIN_MAX_PART_BYTES, "budgets.default"),
-    byLayer
-  };
+  const resolvedDefault = boundedBytes(budgets.default, fallback, MIN_MAX_PART_BYTES, "budgets.default");
+  if (!overrideDefault) return { default: resolvedDefault, byLayer };
+  for (const [layer2, value] of Object.entries(byLayer)) {
+    byLayer[layer2] = Math.min(value, fallback);
+  }
+  return { default: fallback, byLayer };
 }
 function resolveHooks(hooks) {
   if (hooks === void 0) return {};
@@ -1765,6 +2459,11 @@ function resolveHooks(hooks) {
   return { ...hooks };
 }
 function resolveCandidateCwd(userConfig, cliOptions, baseDir) {
+  if (userConfig?.cwd !== void 0 && (typeof userConfig.cwd !== "string" || userConfig.cwd.trim() === "")) {
+    throw new Error(
+      `\`cwd\` must be a non-empty path string (received ${describeValue2(userConfig.cwd)}).`
+    );
+  }
   const candidate = cliOptions?.cwd || userConfig?.cwd || baseDir || process.cwd();
   const resolved = path10__namespace.resolve(candidate);
   if (!fs9__namespace.existsSync(resolved)) {
@@ -1777,55 +2476,106 @@ function resolveCandidateCwd(userConfig, cliOptions, baseDir) {
 }
 function resolveConfig(userConfig, cliOptions, baseDir) {
   const cwd = resolveCandidateCwd(userConfig ?? null, cliOptions, baseDir);
-  const forcedPreset = userConfig?.preset;
+  const forcedPreset = resolvePresetName(userConfig?.preset);
   if (forcedPreset !== void 0 && !getPreset(forcedPreset)) {
     throw new Error(unknownPresetMessage(forcedPreset));
   }
   const preset = detectPreset(cwd, forcedPreset);
   const layersMode = resolveLayersMode(userConfig?.layersMode);
-  const layers = userConfig?.layers && userConfig.layers.length > 0 ? layersMode === "replace" ? userConfig.layers : [...userConfig.layers, ...preset.layers] : preset.layers;
-  const kinds = userConfig?.kinds && userConfig.kinds.length > 0 ? layersMode === "replace" ? userConfig.kinds : [...userConfig.kinds, ...preset.kinds] : preset.kinds;
-  const customRules = userConfig?.secrets?.customPatterns ?? [];
-  const rawRules = userConfig?.secrets?.disableDefaultPatterns ? customRules : [...DEFAULT_SECRET_PATTERNS, ...customRules];
-  const secretRules = compileSecretRules(rawRules);
-  const includeMonolith = cliOptions?.includeMonolith ?? userConfig?.includeMonolith ?? false;
+  const userLayers = resolveLayerRules(userConfig?.layers);
+  const userKinds = resolveKindRules(userConfig?.kinds);
+  const layers = userLayers.length > 0 ? layersMode === "replace" ? userLayers : [...userLayers, ...preset.layers] : preset.layers;
+  const kinds = userKinds.length > 0 ? layersMode === "replace" ? userKinds : [...userKinds, ...preset.kinds] : preset.kinds;
+  const secrets = userConfig?.secrets;
+  if (secrets !== void 0 && (typeof secrets !== "object" || Array.isArray(secrets))) {
+    throw new Error(
+      `\`secrets\` must be an object of { customPatterns, disableDefaultPatterns } (received ${describeValue2(secrets)}).`
+    );
+  }
+  const customRules = secrets?.customPatterns ?? [];
+  if (!Array.isArray(customRules)) {
+    throw new Error(
+      `\`secrets.customPatterns\` must be an array of secret rules (received ${describeValue2(customRules)}). Each entry is a RegExp, a string, or { rule, pattern }.`
+    );
+  }
+  const disableDefaultPatterns = strictBoolean(
+    secrets?.disableDefaultPatterns,
+    false,
+    "`secrets.disableDefaultPatterns`"
+  );
+  const aliasedRules = userConfig?.secretRules;
+  if (aliasedRules !== void 0 && !Array.isArray(aliasedRules)) {
+    throw new Error(
+      `\`secretRules\` must be an array of { rule, pattern } entries (received ${describeValue2(aliasedRules)}).`
+    );
+  }
+  const compiledCustomRules = compileSecretRules([
+    ...customRules,
+    ...aliasedRules ?? []
+  ]);
+  const secretRules = disableDefaultPatterns ? compiledCustomRules : [...compileSecretRules(DEFAULT_SECRET_PATTERNS), ...compiledCustomRules];
+  const cliMonolith = cliOptions?.includeMonolith;
+  const includeMonolith = cliMonolith ?? strictBoolean(userConfig?.includeMonolith, false, "`includeMonolith`");
   const artifacts = resolveArtifacts(
     userConfig?.artifacts,
     cliOptions?.skipArtifacts,
-    includeMonolith
+    includeMonolith,
+    cliMonolith
   );
+  const explicitMaxPartBytes = cliOptions?.maxPartBytes ?? userConfig?.maxPartBytes;
   const maxPartBytes = boundedBytes(
-    cliOptions?.maxPartBytes ?? userConfig?.maxPartBytes,
+    explicitMaxPartBytes,
     300 * 1024,
     MIN_MAX_PART_BYTES,
     "maxPartBytes"
   );
-  const budgets = resolveBudgets(userConfig?.budgets, maxPartBytes);
+  const budgets = resolveBudgets(
+    userConfig?.budgets,
+    maxPartBytes,
+    explicitMaxPartBytes !== void 0
+  );
+  const configuredOutDir = strictString(userConfig?.outDir, "snapshot", "`outDir`");
+  const outDir = cliOptions?.outDir || configuredOutDir;
+  const tmpDir = strictString(userConfig?.tmpDir, "snapshot.tmp", "`tmpDir`");
+  const branch = strictString(userConfig?.branch, "main", "`branch`");
+  const configuredSensitiveFiles = strictBoolean(
+    userConfig?.includeSensitiveFiles,
+    false,
+    "`includeSensitiveFiles`"
+  );
+  const includeSensitiveFiles = strictBoolean(
+    cliOptions?.includeSensitiveFiles,
+    configuredSensitiveFiles,
+    "`includeSensitiveFiles`"
+  );
+  const presetExclude = [
+    .../* @__PURE__ */ new Set([...preset.exclude, ...outputExcludePatterns(cwd, outDir, tmpDir)])
+  ];
   return markResolvedConfig({
     cwd,
-    branch: userConfig?.branch || "main",
-    outDir: cliOptions?.outDir || userConfig?.outDir || "snapshot",
-    tmpDir: userConfig?.tmpDir || "snapshot.tmp",
+    branch,
+    outDir,
+    tmpDir,
     maxPartBytes,
     largeFileBytes: boundedBytes(cliOptions?.largeFileBytes ?? userConfig?.largeFileBytes, 200 * 1024, 1, "largeFileBytes"),
-    previewHeadLines: positiveInteger(userConfig?.previewHeadLines ?? 80, 80),
-    previewTailLines: positiveInteger(userConfig?.previewTailLines ?? 40, 40),
+    previewHeadLines: strictPositiveInteger(userConfig?.previewHeadLines, 80, "`previewHeadLines`"),
+    previewTailLines: strictPositiveInteger(userConfig?.previewTailLines, 40, "`previewTailLines`"),
     includeMonolith: artifacts.monolith,
     maxMonolithBytes: optionalBytes(
       cliOptions?.maxMonolithBytes !== void 0 ? cliOptions.maxMonolithBytes : userConfig?.maxMonolithBytes,
       "maxMonolithBytes"
     ),
-    includeSensitiveFiles: cliOptions?.includeSensitiveFiles ?? userConfig?.includeSensitiveFiles ?? false,
+    includeSensitiveFiles,
     include: resolveInclude(userConfig?.include),
     preset: preset.presetName,
-    presetExclude: [...preset.exclude],
+    presetExclude,
     artifacts,
     layersMode,
     budgets,
     hooks: resolveHooks(userConfig?.hooks),
     layers,
     kinds,
-    excludePatterns: userConfig?.excludePatterns ?? [],
+    excludePatterns: resolveExcludePatterns(userConfig?.excludePatterns),
     secretRules
   });
 }
@@ -1904,6 +2654,75 @@ function truncatePreview(content, headLines, tailLines) {
     includedLines: headLines + tailLines + 1
   };
 }
+var BINARY_EXTENSIONS = /* @__PURE__ */ new Set([
+  ".png",
+  ".jpg",
+  ".jpeg",
+  ".gif",
+  ".webp",
+  ".avif",
+  ".ico",
+  ".bmp",
+  ".tiff",
+  ".pdf",
+  ".zip",
+  ".tar",
+  ".gz",
+  ".tgz",
+  ".bz2",
+  ".xz",
+  ".7z",
+  ".rar",
+  ".mp3",
+  ".mp4",
+  ".wav",
+  ".ogg",
+  ".webm",
+  ".mov",
+  ".avi",
+  ".woff",
+  ".woff2",
+  ".ttf",
+  ".otf",
+  ".eot",
+  ".wasm",
+  ".node",
+  ".exe",
+  ".dll",
+  ".dylib",
+  ".so"
+]);
+function isBinaryExtension(filePath) {
+  const ext = path10__namespace.extname(filePath).toLowerCase();
+  return BINARY_EXTENSIONS.has(ext);
+}
+function isBinaryBuffer(buffer) {
+  const checkLength = Math.min(buffer.length, 8192);
+  for (let index = 0; index < checkLength; index++) {
+    if (buffer[index] === 0) return true;
+  }
+  return false;
+}
+function isBinaryFile(absolutePath) {
+  if (isBinaryExtension(absolutePath)) return true;
+  let fd;
+  try {
+    fd = fs9__namespace.openSync(absolutePath, "r");
+    const buffer = Buffer.alloc(8192);
+    const bytesRead = fs9__namespace.readSync(fd, buffer, 0, 8192, 0);
+    if (bytesRead === 0) return false;
+    return isBinaryBuffer(buffer.subarray(0, bytesRead));
+  } catch {
+    return false;
+  } finally {
+    if (fd !== void 0) {
+      try {
+        fs9__namespace.closeSync(fd);
+      } catch {
+      }
+    }
+  }
+}
 var LANGUAGE_BY_EXTENSION = {
   ".ts": "typescript",
   ".mts": "typescript",
@@ -1970,16 +2789,15 @@ function describeMatcher(matcher) {
   if (typeof matcher === "string") return matcher;
   if (matcher instanceof RegExp) return String(matcher);
   if (typeof matcher === "function") {
-    const source = String(matcher).replace(/\s+/g, " ").trim();
-    return source.length > 70 ? `${source.slice(0, 67)}...` : source;
+    return "function (custom predicate)";
   }
   return String(matcher);
 }
 function normalizeTarget(cwd, target) {
   const absolute = path10__namespace.resolve(cwd, target);
-  const relative4 = path10__namespace.relative(cwd, absolute);
-  if (relative4.startsWith("..") || path10__namespace.isAbsolute(relative4)) return target;
-  return relative4.split(path10__namespace.sep).join("/");
+  const relative5 = path10__namespace.relative(cwd, absolute);
+  if (relative5.startsWith("..") || path10__namespace.isAbsolute(relative5)) return target;
+  return relative5.split(path10__namespace.sep).join("/");
 }
 function findRuleMatch(rules, relativePath) {
   return rules.find(
@@ -1995,10 +2813,10 @@ function readManifest2(config) {
   }
 }
 function explainPath(config, target) {
-  const relative4 = normalizeTarget(config.cwd, target);
-  const absolute = path10__namespace.join(config.cwd, relative4);
+  const relative5 = normalizeTarget(config.cwd, target);
+  const absolute = path10__namespace.join(config.cwd, relative5);
   const result = {
-    path: relative4,
+    path: relative5,
     exists: fs9__namespace.existsSync(absolute),
     included: false
   };
@@ -2007,8 +2825,8 @@ function explainPath(config, target) {
     excludePatterns: [...config.excludePatterns, ...config.presetExclude],
     includeSensitiveFiles: config.includeSensitiveFiles
   });
-  if (!collection.files.includes(relative4)) {
-    const record = collection.skipped.find((entry2) => entry2.path === relative4);
+  if (!collection.files.includes(relative5)) {
+    const record = collection.skipped.find((entry2) => entry2.path === relative5);
     if (record) {
       result.reason = record.reason;
       result.detail = record.detail;
@@ -2022,24 +2840,30 @@ function explainPath(config, target) {
     return result;
   }
   result.included = true;
-  result.layer = classifyLayer(relative4, config.layers);
-  result.kind = classifyKind(relative4, config.kinds);
-  result.language = detectLanguage(relative4);
-  const layerRule = findRuleMatch(config.layers, relative4);
+  if (isBinaryFile(absolute)) {
+    result.included = false;
+    result.reason = "binary";
+    result.detail = "binary content; generate skips it and records `binary` in manifest.skipped[]";
+    return result;
+  }
+  result.layer = classifyLayer(relative5, config.layers);
+  result.kind = classifyKind(relative5, config.kinds);
+  result.language = detectLanguage(relative5);
+  const layerRule = findRuleMatch(config.layers, relative5);
   if (layerRule) result.layerMatch = describeMatcher(layerRule.match);
-  const kindRule = findRuleMatch(config.kinds, relative4);
+  const kindRule = findRuleMatch(config.kinds, relative5);
   if (kindRule) result.kindMatch = describeMatcher(kindRule.match);
   if (fs9__namespace.existsSync(absolute) && fs9__namespace.statSync(absolute).isFile()) {
     const buffer = fs9__namespace.readFileSync(absolute);
     const text2 = buffer.toString("utf8");
     result.bytes = buffer.length;
     result.lines = countLines(text2);
-    const { findings } = scanAndRedactSecrets(text2, config.secretRules, relative4);
+    const { findings } = scanAndRedactSecrets(text2, config.secretRules, relative5);
     result.secretCount = findings.length;
     result.secrets = findings.slice(0, 20).map((finding) => ({ rule: finding.rule, line: finding.line }));
   }
   const manifest = readManifest2(config);
-  const entry = manifest?.files.find((file) => file.relativePath === relative4);
+  const entry = manifest?.files.find((file) => file.relativePath === relative5);
   result.part = entry?.part ?? null;
   result.inclusionMode = entry?.inclusionMode;
   return result;
@@ -2163,7 +2987,7 @@ function renderConfig(answers) {
   secrets: {
     // [{ rule: "internal-token", pattern: /CORP-[A-Z0-9]{32}/ }]
     customPatterns: [],
-    // Set true to drop the 21 built-in rules.
+    // Set true to drop the built-in rules above and keep only customPatterns.
     disableDefaultPatterns: false,
   },
 
@@ -2179,6 +3003,10 @@ function renderConfig(answers) {
   },
   // Skip the monolith above this size. null = no limit.
   maxMonolithBytes: null,
+  // Top-level switch for the monolith, equivalent to artifacts.monolith.
+  // When both are present the artifact entry wins; this one exists so the
+  // generated file lists every setting the tool accepts.
+  includeMonolith: ${artifacts.monolith},
 
   // \u2500\u2500 Advanced \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
   // afterGenerate: (manifest) => { /* write your own artifact */ }
@@ -2500,6 +3328,14 @@ function existingConfig(cwd) {
   }
   return null;
 }
+function packageJsonHasConfig(cwd) {
+  try {
+    const parsed = JSON.parse(fs9__namespace.readFileSync(path10__namespace.join(cwd, "package.json"), "utf8"));
+    return typeof parsed.snapshot === "object" && parsed.snapshot !== null;
+  } catch {
+    return false;
+  }
+}
 function artifactAnswers(options) {
   const artifacts = { ...DEFAULT_ANSWERS.artifacts };
   for (const name of options.skipArtifacts ?? []) {
@@ -2712,6 +3548,11 @@ async function runInit(options) {
       `A configuration already exists (${present}). Re-run with --force to replace it.`
     );
   }
+  if (packageJsonHasConfig(options.cwd) && !options.force) {
+    throw new Error(
+      'package.json already defines a "snapshot" config. Remove that key, or re-run with --force to write a config file that takes precedence over it.'
+    );
+  }
   if (fs9__namespace.existsSync(configPath) && !options.force) {
     throw new Error(`${configName} already exists. Re-run with --force to replace it.`);
   }
@@ -3268,14 +4109,42 @@ function summarizeTypeScriptSource(relativePath, content) {
     const modifiers = ts__default.default.canHaveModifiers(node) ? ts__default.default.getModifiers(node) : void 0;
     return Boolean(modifiers?.some((m) => m.kind === ts__default.default.SyntaxKind.DefaultKeyword));
   };
-  const recordFunctionLike = (name, exported) => {
+  const rendersJsx = (node) => {
+    const pending = [node];
+    while (pending.length > 0) {
+      const current = pending.pop();
+      if (ts__default.default.isJsxElement(current) || ts__default.default.isJsxSelfClosingElement(current) || ts__default.default.isJsxFragment(current)) {
+        return true;
+      }
+      if (ts__default.default.isCallExpression(current)) {
+        const callee = current.expression;
+        const calleeName = ts__default.default.isIdentifier(callee) ? callee.text : ts__default.default.isPropertyAccessExpression(callee) ? callee.name.text : "";
+        if (calleeName === "createElement") return true;
+      }
+      ts__default.default.forEachChild(current, (child) => {
+        pending.push(child);
+      });
+    }
+    return false;
+  };
+  const REACT_BASE_CLASS = /(?:^|\.)(?:PureComponent|Component)$/;
+  const extendsReactBase = (node) => {
+    const heritage = (node.heritageClauses ?? []).find(
+      (clause) => clause.token === ts__default.default.SyntaxKind.ExtendsKeyword
+    );
+    const expression = heritage?.types[0]?.expression;
+    if (!expression) return false;
+    const text2 = ts__default.default.isIdentifier(expression) ? expression.text : expression.getText(sourceFile);
+    return REACT_BASE_CLASS.test(text2);
+  };
+  const recordFunctionLike = (name, exported, node) => {
     summary.functions.push(name);
     if (exported) {
       summary.exports.push(name);
       if (ROUTE_HANDLER_NAMES.has(name)) summary.routeHandlers.push(name);
     }
     if (/^use[A-Z0-9]/.test(name)) summary.hooks.push(name);
-    if (/^[A-Z]/.test(name)) summary.reactComponents.push(name);
+    if (/^[A-Z]/.test(name) && rendersJsx(node)) summary.reactComponents.push(name);
   };
   const stack = [sourceFile];
   while (stack.length > 0) {
@@ -3304,7 +4173,7 @@ function summarizeTypeScriptSource(relativePath, content) {
     if (ts__default.default.isFunctionDeclaration(node)) {
       const exported = isExported(node);
       if (node.name) {
-        recordFunctionLike(node.name.text, exported);
+        recordFunctionLike(node.name.text, exported, node);
         if (isDefault(node)) summary.exports.push("default");
       } else if (isDefault(node)) {
         summary.exports.push("default");
@@ -3315,7 +4184,9 @@ function summarizeTypeScriptSource(relativePath, content) {
         summary.classes.push(node.name.text);
         if (isExported(node)) summary.exports.push(node.name.text);
         if (isDefault(node)) summary.exports.push("default");
-        if (/^[A-Z]/.test(node.name.text)) summary.reactComponents.push(node.name.text);
+        if (/^[A-Z]/.test(node.name.text) && (extendsReactBase(node) || rendersJsx(node))) {
+          summary.reactComponents.push(node.name.text);
+        }
       } else if (isDefault(node)) {
         summary.exports.push("default");
       }
@@ -3343,7 +4214,9 @@ function summarizeTypeScriptSource(relativePath, content) {
           if (ROUTE_HANDLER_NAMES.has(name)) summary.routeHandlers.push(name);
         }
         if (/^use[A-Z0-9]/.test(name)) summary.hooks.push(name);
-        if (/^[A-Z]/.test(name)) summary.reactComponents.push(name);
+        if (/^[A-Z]/.test(name) && declaration.initializer !== void 0 && rendersJsx(declaration.initializer)) {
+          summary.reactComponents.push(name);
+        }
       }
     }
     const children = [];
@@ -3570,7 +4443,11 @@ function generateAuditReport(manifest, secretFindings) {
     `**Total Files:** ${manifest.counts.totalFiles}  `,
     `**Total Lines:** ${manifest.counts.totalLines.toLocaleString()}  `,
     `**Total Size:** ${(manifest.counts.totalSizeBytes / (1024 * 1024)).toFixed(2)} MB  `,
-    `**Redacted Content Bytes:** ${manifest.totals.totalContentBytes.toLocaleString()}  `,
+    // This counts the bytes that were *emitted* after redaction, not the bytes
+    // that were masked: calling it "redacted bytes" made a repository with zero
+    // secrets report a non-zero redacted-byte figure directly above "no secrets
+    // detected". The number of masked spans is reported in section 1 instead.
+    `**Emitted Content Bytes:** ${manifest.totals.totalContentBytes.toLocaleString()}  `,
     "",
     "## 1. Security Scan & Redaction",
     "",
@@ -3731,6 +4608,8 @@ function renumberParts(parts, contentFingerprint) {
       layerCounts[file.layer] = (layerCounts[file.layer] || 0) + 1;
       kindCounts[file.kind] = (kindCounts[file.kind] || 0) + 1;
     }
+    const pathLines = included.map((file) => displayPath(file.relativePath));
+    const listFence = fenceForText(pathLines.join("\n"), 3);
     const header = [
       `# Codebase Snapshot Part ${zeroPad(index + 1)} of ${zeroPad(total)}`,
       "",
@@ -3743,9 +4622,9 @@ function renumberParts(parts, contentFingerprint) {
       "",
       "## Files",
       "",
-      "```text",
-      ...included.map((file) => displayPath(file.relativePath)),
-      "```",
+      `${listFence}text`,
+      ...pathLines,
+      listFence,
       "",
       "## Contents",
       ""
@@ -3773,7 +4652,8 @@ function capValue(value, max) {
   return `${value.slice(0, half)}\u2026${value.slice(value.length - half)}`;
 }
 var capMetadata = (value) => capValue(value, METADATA_VALUE_MAX);
-var displayPath = (value) => capValue(value, DISPLAY_PATH_MAX);
+var CONTROL_CHARS = /[\u0000-\u001f\u007f]/g;
+var displayPath = (value) => capValue(value.replace(CONTROL_CHARS, " "), DISPLAY_PATH_MAX);
 function topEntries(counts, limit) {
   return Object.entries(counts).sort((a, b) => b[1] - a[1] || (a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0)).slice(0, limit).map(([key, value]) => `${capMetadata(key)} (${value})`).join(", ");
 }
@@ -3869,6 +4749,8 @@ function renderGroups(groups, contentFingerprint) {
       layerCounts[section.file.layer] = (layerCounts[section.file.layer] || 0) + 1;
       kindCounts[section.file.kind] = (kindCounts[section.file.kind] || 0) + 1;
     }
+    const pathLines = group.map((s) => displayPath(s.file.relativePath));
+    const listFence = fenceForText(pathLines.join("\n"), 3);
     const header = [
       `# Codebase Snapshot Part ${zeroPad(index + 1)} of ${zeroPad(total)}`,
       "",
@@ -3881,9 +4763,9 @@ function renderGroups(groups, contentFingerprint) {
       "",
       "## Files",
       "",
-      "```text",
-      ...group.map((s) => displayPath(s.file.relativePath)),
-      "```",
+      `${listFence}text`,
+      ...pathLines,
+      listFence,
       "",
       "## Contents",
       ""
@@ -3942,9 +4824,12 @@ function renderFileSection(file) {
   ].join("\n");
 }
 function fenceForContent(content) {
+  return fenceForText(content, 4);
+}
+function fenceForText(content, minimum) {
   const matches = content.match(/`+/g);
   const maxRun = matches?.reduce((max, run) => Math.max(max, run.length), 0) ?? 0;
-  return "`".repeat(Math.max(4, maxRun + 1));
+  return "`".repeat(Math.max(minimum, maxRun + 1));
 }
 function renderSummary(summary) {
   if (!summary) return [];
@@ -4093,118 +4978,51 @@ function generateReadme(manifest) {
 
 // src/generator/tree.ts
 var MAX_TREE_LINES = 2e4;
+var CONTROL_CHARS2 = /[\u0000-\u001f\u007f]/g;
 function generateProjectTree(filePaths) {
   const root = { children: /* @__PURE__ */ new Map() };
   for (const filePath of filePaths) {
     const parts = filePath.split("/").filter((part) => part.length > 0);
     let current = root;
     for (const part of parts) {
-      let child = current.children.get(part);
-      if (!child) {
-        child = { children: /* @__PURE__ */ new Map() };
-        current.children.set(part, child);
-      }
-      current = child;
-    }
-  }
-  const lines = ["# Project Tree", "", "```text", "."];
-  let truncatedAt = -1;
-  function walk(node, prefix) {
-    if (truncatedAt !== -1) return;
-    const keys = Array.from(node.children.keys()).sort((a, b) => {
-      const aIsDir = node.children.get(a).children.size > 0;
-      const bIsDir = node.children.get(b).children.size > 0;
-      if (aIsDir !== bIsDir) return aIsDir ? -1 : 1;
-      return a < b ? -1 : a > b ? 1 : 0;
-    });
-    keys.forEach((key, index) => {
-      if (truncatedAt !== -1) return;
-      const isLast = index === keys.length - 1;
-      const child = node.children.get(key);
-      const isDirectory = child.children.size > 0;
-      lines.push(`${prefix}${isLast ? "\u2514\u2500\u2500 " : "\u251C\u2500\u2500 "}${key}${isDirectory ? "/" : ""}`);
-      if (lines.length >= MAX_TREE_LINES) {
-        truncatedAt = lines.length;
-        return;
-      }
-      walk(child, prefix + (isLast ? "    " : "\u2502   "));
-    });
-  }
-  walk(root, "");
-  if (truncatedAt !== -1) {
-    lines.push(`... [tree truncated at ${MAX_TREE_LINES} lines] ...`);
-  }
-  lines.push("```", "");
-  return lines.join("\n");
-}
-var BINARY_EXTENSIONS = /* @__PURE__ */ new Set([
-  ".png",
-  ".jpg",
-  ".jpeg",
-  ".gif",
-  ".webp",
-  ".avif",
-  ".ico",
-  ".bmp",
-  ".tiff",
-  ".pdf",
-  ".zip",
-  ".tar",
-  ".gz",
-  ".tgz",
-  ".bz2",
-  ".xz",
-  ".7z",
-  ".rar",
-  ".mp3",
-  ".mp4",
-  ".wav",
-  ".ogg",
-  ".webm",
-  ".mov",
-  ".avi",
-  ".woff",
-  ".woff2",
-  ".ttf",
-  ".otf",
-  ".eot",
-  ".wasm",
-  ".node",
-  ".exe",
-  ".dll",
-  ".dylib",
-  ".so"
-]);
-function isBinaryExtension(filePath) {
-  const ext = path10__namespace.extname(filePath).toLowerCase();
-  return BINARY_EXTENSIONS.has(ext);
-}
-function isBinaryBuffer(buffer) {
-  const checkLength = Math.min(buffer.length, 8192);
-  for (let index = 0; index < checkLength; index++) {
-    if (buffer[index] === 0) return true;
-  }
-  return false;
-}
-function isBinaryFile(absolutePath) {
-  if (isBinaryExtension(absolutePath)) return true;
-  let fd;
-  try {
-    fd = fs9__namespace.openSync(absolutePath, "r");
-    const buffer = Buffer.alloc(8192);
-    const bytesRead = fs9__namespace.readSync(fd, buffer, 0, 8192, 0);
-    if (bytesRead === 0) return false;
-    return isBinaryBuffer(buffer.subarray(0, bytesRead));
-  } catch {
-    return false;
-  } finally {
-    if (fd !== void 0) {
-      try {
-        fs9__namespace.closeSync(fd);
-      } catch {
+      let child = current.children.get(part);
+      if (!child) {
+        child = { children: /* @__PURE__ */ new Map() };
+        current.children.set(part, child);
       }
+      current = child;
     }
   }
+  const lines = ["."];
+  let truncatedAt = -1;
+  function walk(node, prefix) {
+    if (truncatedAt !== -1) return;
+    const keys = Array.from(node.children.keys()).sort((a, b) => {
+      const aIsDir = node.children.get(a).children.size > 0;
+      const bIsDir = node.children.get(b).children.size > 0;
+      if (aIsDir !== bIsDir) return aIsDir ? -1 : 1;
+      return a < b ? -1 : a > b ? 1 : 0;
+    });
+    keys.forEach((key, index) => {
+      if (truncatedAt !== -1) return;
+      const isLast = index === keys.length - 1;
+      const child = node.children.get(key);
+      const isDirectory = child.children.size > 0;
+      const label = key.replace(CONTROL_CHARS2, " ");
+      lines.push(`${prefix}${isLast ? "\u2514\u2500\u2500 " : "\u251C\u2500\u2500 "}${label}${isDirectory ? "/" : ""}`);
+      if (lines.length >= MAX_TREE_LINES) {
+        truncatedAt = lines.length;
+        return;
+      }
+      walk(child, prefix + (isLast ? "    " : "\u2502   "));
+    });
+  }
+  walk(root, "");
+  if (truncatedAt !== -1) {
+    lines.push(`... [tree truncated at ${MAX_TREE_LINES} lines] ...`);
+  }
+  const fence = fenceForText(lines.join("\n"), 3);
+  return ["# Project Tree", "", `${fence}text`, ...lines, fence, ""].join("\n");
 }
 function emptyDrift() {
   return {
@@ -4219,6 +5037,15 @@ function emptyDrift() {
 function sha256Hex(buffer) {
   return crypto__namespace.createHash("sha256").update(buffer).digest("hex");
 }
+function wouldNowBeIncluded(cwd, relativePath) {
+  const absolutePath = path10__namespace.join(cwd, relativePath);
+  try {
+    if (!fs9__namespace.statSync(absolutePath).isFile()) return false;
+    return !isBinaryFile(absolutePath);
+  } catch {
+    return false;
+  }
+}
 function validateSnapshot(configInput) {
   assertUsableConfigInput(configInput);
   const config = isResolvedConfig(configInput) ? normalizeResolvedConfig(configInput) : resolveConfig(configInput);
@@ -4273,9 +5100,9 @@ function validateSnapshot(configInput) {
     includeSensitiveFiles: config.includeSensitiveFiles
   });
   for (const diskFile of collection.files) {
-    if (skippedSet.has(diskFile)) continue;
     const snapshotHash = manifestFileMap.get(diskFile);
     if (!snapshotHash) {
+      if (skippedSet.has(diskFile) && !wouldNowBeIncluded(config.cwd, diskFile)) continue;
       drift.missingInSnapshot.push(diskFile);
       continue;
     }
@@ -4555,7 +5382,7 @@ function validateSnapshot(configInput) {
 
 // src/index.ts
 var GENERATOR_NAME = "@ankurhalder/codebase-snapshot";
-var GENERATOR_VERSION = "3.0.0";
+var GENERATOR_VERSION = "4.0.0";
 var SCHEMA_VERSION = "3.0.0";
 function sha256Hex2(input) {
   return crypto__namespace.createHash("sha256").update(input).digest("hex");
@@ -4725,27 +5552,213 @@ function resolveSafeOutputDirs(config) {
   return { outDir, tmpDir };
 }
 var PLACEHOLDER_ENTRIES = /* @__PURE__ */ new Set([".gitkeep", ".gitignore", ".DS_Store"]);
+var STAGING_ENTRIES = /* @__PURE__ */ new Set([
+  ".codebase-snapshot",
+  "manifest.json",
+  "README.md",
+  "parts",
+  "reports",
+  "full-codebase.json",
+  "full-codebase.md"
+]);
 var OWNERSHIP_MARKER = ".codebase-snapshot";
-function writeOwnershipMarker(dir) {
+var SUPPORTED_MARKER_SCHEMAS = /* @__PURE__ */ new Set([SCHEMA_VERSION]);
+var SNAPSHOT_ID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+function listEntries(dir) {
+  const entries = [];
+  const walk = (absolute, prefix) => {
+    let children;
+    try {
+      children = fs9__namespace.readdirSync(absolute, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const child of children) {
+      const relative5 = prefix === "" ? child.name : `${prefix}/${child.name}`;
+      entries.push(relative5);
+      if (child.isDirectory()) walk(path10__namespace.join(absolute, child.name), relative5);
+    }
+  };
+  walk(dir, "");
+  return entries.sort();
+}
+function markerPayload(dir, state, id, createdAt) {
   const marker2 = {
     generator: GENERATOR_NAME,
     version: GENERATOR_VERSION,
-    schemaVersion: SCHEMA_VERSION
+    schemaVersion: SCHEMA_VERSION,
+    createdAt,
+    state,
+    id,
+    entries: listEntries(dir)
   };
-  fs9__namespace.writeFileSync(path10__namespace.join(dir, OWNERSHIP_MARKER), `${JSON.stringify(marker2, null, 2)}
-`, "utf8");
-}
-function isOwnOutput(dir) {
-  if (fs9__namespace.existsSync(path10__namespace.join(dir, OWNERSHIP_MARKER))) return true;
   const manifestPath = path10__namespace.join(dir, "manifest.json");
-  if (!fs9__namespace.existsSync(manifestPath)) return false;
+  if (fs9__namespace.existsSync(manifestPath)) {
+    marker2.manifestSha256 = sha256Hex2(fs9__namespace.readFileSync(manifestPath));
+  }
+  return marker2;
+}
+function writeOwnershipMarker(dir, marker2) {
+  fs9__namespace.writeFileSync(
+    path10__namespace.join(dir, OWNERSHIP_MARKER),
+    `${JSON.stringify(marker2, null, 2)}
+`,
+    "utf8"
+  );
+}
+function readOwnershipMarker(dir) {
+  const markerPath = path10__namespace.join(dir, OWNERSHIP_MARKER);
+  if (!fs9__namespace.existsSync(markerPath)) {
+    return { marker: null, problem: "it holds no .codebase-snapshot marker" };
+  }
+  let raw;
   try {
-    const parsed = JSON.parse(fs9__namespace.readFileSync(manifestPath, "utf8"));
-    const generator = parsed.generator;
-    return typeof parsed.schemaVersion === "string" && Array.isArray(parsed.files) && typeof generator === "object" && generator !== null && generator.name === GENERATOR_NAME;
+    raw = fs9__namespace.readFileSync(markerPath, "utf8");
   } catch {
-    return false;
+    return { marker: null, problem: "its .codebase-snapshot marker could not be read" };
+  }
+  if (raw.trim().length === 0) {
+    return { marker: null, problem: "its .codebase-snapshot marker is empty" };
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return { marker: null, problem: "its .codebase-snapshot marker is not valid JSON" };
+  }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    return { marker: null, problem: "its .codebase-snapshot marker is not a JSON object" };
+  }
+  const candidate = parsed;
+  if (candidate.generator !== GENERATOR_NAME) {
+    return { marker: null, problem: "its .codebase-snapshot marker names a different generator" };
+  }
+  if (typeof candidate.schemaVersion !== "string" || !SUPPORTED_MARKER_SCHEMAS.has(candidate.schemaVersion)) {
+    return {
+      marker: null,
+      problem: `its .codebase-snapshot marker has a schema version this build does not understand (${String(candidate.schemaVersion)})`
+    };
+  }
+  if (typeof candidate.id !== "string" || !SNAPSHOT_ID_PATTERN.test(candidate.id)) {
+    return { marker: null, problem: "its .codebase-snapshot marker carries no snapshot id" };
+  }
+  if (candidate.state !== "staging" && candidate.state !== "complete") {
+    return { marker: null, problem: "its .codebase-snapshot marker records no run state" };
+  }
+  return {
+    marker: {
+      generator: GENERATOR_NAME,
+      version: typeof candidate.version === "string" ? candidate.version : "unknown",
+      schemaVersion: candidate.schemaVersion,
+      createdAt: typeof candidate.createdAt === "string" ? candidate.createdAt : "unknown",
+      state: candidate.state,
+      id: candidate.id,
+      manifestSha256: typeof candidate.manifestSha256 === "string" ? candidate.manifestSha256 : void 0,
+      entries: Array.isArray(candidate.entries) && candidate.entries.every((entry) => typeof entry === "string") ? candidate.entries : void 0
+    },
+    problem: null
+  };
+}
+function describeManifestProblem(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return "is not a JSON object";
+  const candidate = value;
+  const generator = candidate.generator;
+  if (typeof generator !== "object" || generator === null || generator.name !== GENERATOR_NAME) {
+    return "was not written by this generator";
+  }
+  if (!Array.isArray(candidate.files)) return "has no files array";
+  return null;
+}
+function assessSnapshotDirectory(dir) {
+  const { marker: marker2, problem } = readOwnershipMarker(dir);
+  if (!marker2) return { owned: false, problem, foreignEntries: [], marker: null };
+  if (marker2.state !== "complete") {
+    return {
+      owned: false,
+      problem: "its .codebase-snapshot marker records a run that never finished writing it",
+      foreignEntries: [],
+      marker: marker2
+    };
+  }
+  const manifestPath = path10__namespace.join(dir, "manifest.json");
+  if (fs9__namespace.existsSync(manifestPath)) {
+    let raw;
+    try {
+      raw = fs9__namespace.readFileSync(manifestPath, "utf8");
+    } catch {
+      return {
+        owned: false,
+        problem: "its manifest.json could not be read",
+        foreignEntries: [],
+        marker: marker2
+      };
+    }
+    let parsed;
+    try {
+      parsed = JSON.parse(raw);
+    } catch {
+      return {
+        owned: false,
+        problem: "its manifest.json is not valid JSON",
+        foreignEntries: [],
+        marker: marker2
+      };
+    }
+    const manifestProblem2 = describeManifestProblem(parsed);
+    if (manifestProblem2) {
+      return {
+        owned: false,
+        problem: `its manifest.json ${manifestProblem2}`,
+        foreignEntries: [],
+        marker: marker2
+      };
+    }
+    if (!marker2.manifestSha256) {
+      return {
+        owned: false,
+        problem: "its .codebase-snapshot marker records no manifest digest",
+        foreignEntries: [],
+        marker: marker2
+      };
+    }
+    if (sha256Hex2(raw) !== marker2.manifestSha256) {
+      return {
+        owned: false,
+        problem: "its manifest.json does not match the digest recorded in its .codebase-snapshot marker",
+        foreignEntries: [],
+        marker: marker2
+      };
+    }
+  } else if (marker2.manifestSha256) {
+    return {
+      owned: false,
+      problem: "its manifest.json is missing although its marker records one",
+      foreignEntries: [],
+      marker: marker2
+    };
+  }
+  const recorded = new Set(marker2.entries ?? []);
+  if (recorded.size === 0) {
+    return {
+      owned: false,
+      problem: "its .codebase-snapshot marker records no contents",
+      foreignEntries: [],
+      marker: marker2
+    };
   }
+  const foreignEntries = listEntries(dir).filter(
+    (entry) => !recorded.has(entry) && !PLACEHOLDER_ENTRIES.has(entry)
+  );
+  return {
+    owned: foreignEntries.length === 0,
+    problem: null,
+    foreignEntries,
+    marker: marker2
+  };
+}
+function describeEntries(entries, limit = 5) {
+  const shown = entries.slice(0, limit).join(", ");
+  return entries.length > limit ? `${shown}, and ${entries.length - limit} more` : shown;
 }
 function assertReplaceable(target, label) {
   if (!fs9__namespace.existsSync(target)) return;
@@ -4755,16 +5768,124 @@ function assertReplaceable(target, label) {
     );
   }
   const entries = fs9__namespace.readdirSync(target);
-  const meaningful = entries.filter((name) => !PLACEHOLDER_ENTRIES.has(name));
-  if (meaningful.length === 0) return;
-  if (isOwnOutput(target)) return;
-  const preview = meaningful.slice(0, 5).join(", ");
-  const more = meaningful.length > 5 ? `, and ${meaningful.length - 5} more` : "";
+  if (entries.length === 0) return;
+  if (label === "outDir" && entries.every((name) => PLACEHOLDER_ENTRIES.has(name))) return;
+  const { marker: marker2, problem } = readOwnershipMarker(target);
+  if (label === "tmpDir") {
+    if (!marker2) {
+      throw new Error(
+        `Refusing to replace tmpDir ${target}: ${problem ?? "it does not carry this generator's marker"}. This generator only clears a staging directory it wrote. Point tmpDir at a new or empty directory, or remove ${target} yourself.`
+      );
+    }
+    const unexpected = entries.filter((name) => !STAGING_ENTRIES.has(name));
+    if (unexpected.length > 0) {
+      throw new Error(
+        `Refusing to replace tmpDir ${target}: it holds ${describeEntries(unexpected)}, which this generator did not write. Point tmpDir at a new or empty directory, or remove those files yourself.`
+      );
+    }
+    return;
+  }
+  const verdict = assessSnapshotDirectory(target);
+  if (verdict.owned) return;
+  if (verdict.foreignEntries.length > 0) {
+    throw new Error(
+      `Refusing to replace ${label} ${target}: it carries this generator's ownership marker, but these entries are not part of the snapshot it recorded: ${describeEntries(verdict.foreignEntries)}. Remove them yourself, or point ${label} at a new or empty directory.`
+    );
+  }
+  const reason = verdict.problem ?? problem ?? "it does not look like a snapshot this generator wrote";
   throw new Error(
-    `Refusing to replace ${label} ${target}: it exists, is not empty, and does not look like a snapshot this generator wrote (found ${preview}${more}). Point ${label} at a new or empty directory, or delete it yourself first.`
+    `Refusing to replace ${label} ${target}: ${reason} (found ${describeEntries(entries)}). Remove the directory yourself, or point ${label} at a new or empty directory.`
+  );
+}
+function ensureParentDirectory(target, label) {
+  const parent = path10__namespace.dirname(target);
+  if (fs9__namespace.existsSync(parent) && !fs9__namespace.statSync(parent).isDirectory()) {
+    throw new Error(
+      `Refusing to create ${label} ${target}: ${parent} exists but is not a directory.`
+    );
+  }
+  try {
+    fs9__namespace.mkdirSync(parent, { recursive: true });
+  } catch (err) {
+    throw new Error(
+      `Refusing to create ${label} ${target}: its parent ${parent} could not be created (${err.message}).`
+    );
+  }
+}
+function acquireRunLock(outDir) {
+  const lockPath = path10__namespace.join(
+    os__namespace.tmpdir(),
+    `codebase-snapshot-${sha256Hex2(outDir).slice(0, 16)}.lock`
   );
+  const payload = `${JSON.stringify({
+    pid: process.pid,
+    outDir,
+    startedAt: (/* @__PURE__ */ new Date()).toISOString()
+  })}
+`;
+  for (let attempt = 0; attempt < 2; attempt += 1) {
+    try {
+      const handle = fs9__namespace.openSync(lockPath, "wx");
+      try {
+        fs9__namespace.writeSync(handle, payload);
+      } finally {
+        fs9__namespace.closeSync(handle);
+      }
+      return () => {
+        try {
+          fs9__namespace.rmSync(lockPath, { force: true });
+        } catch {
+        }
+      };
+    } catch (err) {
+      if (err.code !== "EEXIST") throw err;
+      if (attempt === 0 && lockOwnerIsGone(lockPath)) {
+        fs9__namespace.rmSync(lockPath, { force: true });
+        continue;
+      }
+      throw new Error(
+        `Another generate run is already writing ${outDir}. Wait for it to finish, or delete ${lockPath} if no other run is active.`
+      );
+    }
+  }
+  throw new Error(`Could not acquire the generate lock for ${outDir}.`);
+}
+function lockOwnerIsGone(lockPath) {
+  let raw;
+  try {
+    raw = fs9__namespace.readFileSync(lockPath, "utf8");
+  } catch {
+    return false;
+  }
+  let pid;
+  try {
+    pid = JSON.parse(raw).pid;
+  } catch {
+    return false;
+  }
+  if (typeof pid !== "number" || !Number.isInteger(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return false;
+  } catch (err) {
+    return err.code === "ESRCH";
+  }
+}
+function writeManifestAtomically(manifestPath, manifest) {
+  const tempPath = `${manifestPath}.${process.pid}.tmp`;
+  fs9__namespace.writeFileSync(tempPath, JSON.stringify(manifest, null, 2), "utf8");
+  try {
+    fs9__namespace.renameSync(tempPath, manifestPath);
+  } catch (err) {
+    try {
+      fs9__namespace.rmSync(tempPath, { force: true });
+    } catch {
+    }
+    throw err;
+  }
 }
 function swapIntoPlace(tmpDir, outDir) {
+  ensureParentDirectory(outDir, "outDir");
   const backupDir = `${outDir}.backup-${process.pid}-${Date.now()}`;
   const hadPrevious = fs9__namespace.existsSync(outDir);
   if (hadPrevious) fs9__namespace.renameSync(outDir, backupDir);
@@ -4853,6 +5974,7 @@ function generateSnapshot(configInput, options) {
     includeSensitiveFiles: config.includeSensitiveFiles
   });
   const files = [];
+  const monolithBodies = /* @__PURE__ */ new Map();
   const skipped = [...collection.skipped];
   const secretFindings = [];
   const warnings = [];
@@ -4916,6 +6038,9 @@ function generateSnapshot(configInput, options) {
       isPreviewTruncated = preview.isTruncated;
       includedLines = preview.includedLines;
     }
+    if (config.includeMonolith && isPreviewTruncated) {
+      monolithBodies.set(relativePath, redacted);
+    }
     let summary;
     let summaryQuality;
     try {
@@ -4958,7 +6083,12 @@ function generateSnapshot(configInput, options) {
     ).join("\n")
   );
   const fullContents = /* @__PURE__ */ new Map();
-  for (const file of files) fullContents.set(file.relativePath, file.content ?? "");
+  for (const file of files) {
+    fullContents.set(
+      file.relativePath,
+      monolithBodies.get(file.relativePath) ?? file.content ?? ""
+    );
+  }
   const parts = partitionByBudget(files, config, fingerprint);
   const maxEffectiveBudget = Math.max(
     config.maxPartBytes,
@@ -5044,10 +6174,17 @@ function generateSnapshot(configInput, options) {
   let monolithJson = null;
   let monolithMarkdown = null;
   if (config.includeMonolith) {
-    const fullFiles = files.map((file) => ({
-      ...file,
-      content: fullContents.get(file.relativePath) ?? ""
-    }));
+    const fullFiles = files.map((file) => {
+      const content = fullContents.get(file.relativePath) ?? "";
+      return {
+        ...file,
+        content,
+        inclusionMode: "full",
+        isPreviewTruncated: false,
+        includedBytes: Buffer.byteLength(content, "utf8"),
+        includedLines: countLines(content)
+      };
+    });
     const json = generateMonolithJson(manifest, fullFiles);
     const markdown = generateMonolithMarkdown(manifest, fullFiles);
     const jsonBytes = Buffer.byteLength(json, "utf8");
@@ -5075,57 +6212,199 @@ function generateSnapshot(configInput, options) {
   }
   for (const message of artifactWarnings(config.artifacts)) manifest.warnings.push(message);
   manifest.totals.warningCount = manifest.warnings.length;
+  const { outDir, tmpDir } = resolveSafeOutputDirs(config);
+  const { artifacts } = config;
+  assertReplaceable(tmpDir, "tmpDir");
+  assertReplaceable(outDir, "outDir");
   if (dryRun) {
     runAfterGenerate(config, manifest);
     return manifest;
   }
-  const { outDir, tmpDir } = resolveSafeOutputDirs(config);
-  assertReplaceable(tmpDir, "tmpDir");
-  assertReplaceable(outDir, "outDir");
-  const { artifacts } = config;
-  fs9__namespace.rmSync(tmpDir, { recursive: true, force: true });
-  fs9__namespace.mkdirSync(tmpDir, { recursive: true });
-  writeOwnershipMarker(tmpDir);
-  const partsDir = path10__namespace.join(tmpDir, "parts");
-  const reportsDir = path10__namespace.join(tmpDir, "reports");
-  if (artifacts.parts) fs9__namespace.mkdirSync(partsDir, { recursive: true });
-  if (artifacts.navigation || artifacts.projectTree || artifacts.audit) {
-    fs9__namespace.mkdirSync(reportsDir, { recursive: true });
-  }
-  if (artifacts.parts) {
-    for (const part of parts) {
-      fs9__namespace.writeFileSync(path10__namespace.join(partsDir, part.filename), part.markdown, "utf8");
+  const releaseLock = acquireRunLock(outDir);
+  let stagingStarted = false;
+  try {
+    ensureParentDirectory(outDir, "outDir");
+    fs9__namespace.rmSync(tmpDir, { recursive: true, force: true });
+    fs9__namespace.mkdirSync(tmpDir, { recursive: true });
+    stagingStarted = true;
+    const snapshotId = crypto__namespace.randomUUID();
+    const createdAt = (/* @__PURE__ */ new Date()).toISOString();
+    writeOwnershipMarker(tmpDir, {
+      generator: GENERATOR_NAME,
+      version: GENERATOR_VERSION,
+      schemaVersion: SCHEMA_VERSION,
+      createdAt,
+      state: "staging",
+      id: snapshotId
+    });
+    const partsDir = path10__namespace.join(tmpDir, "parts");
+    const reportsDir = path10__namespace.join(tmpDir, "reports");
+    if (artifacts.parts) fs9__namespace.mkdirSync(partsDir, { recursive: true });
+    if (artifacts.navigation || artifacts.projectTree || artifacts.audit) {
+      fs9__namespace.mkdirSync(reportsDir, { recursive: true });
+    }
+    if (artifacts.parts) {
+      for (const part of parts) {
+        fs9__namespace.writeFileSync(path10__namespace.join(partsDir, part.filename), part.markdown, "utf8");
+      }
     }
+    if (artifacts.projectTree) {
+      const projectTree = generateProjectTree(files.map((file) => file.relativePath));
+      fs9__namespace.writeFileSync(path10__namespace.join(reportsDir, "project-tree.md"), projectTree, "utf8");
+    }
+    if (artifacts.navigation) {
+      fs9__namespace.writeFileSync(path10__namespace.join(reportsDir, "navigation.md"), generateNavigation(manifest), "utf8");
+    }
+    if (artifacts.audit) {
+      fs9__namespace.writeFileSync(
+        path10__namespace.join(reportsDir, "audit.md"),
+        generateAuditReport(manifest, secretFindings),
+        "utf8"
+      );
+    }
+    if (artifacts.readme) {
+      fs9__namespace.writeFileSync(path10__namespace.join(tmpDir, "README.md"), generateReadme(manifest), "utf8");
+    }
+    if (artifacts.manifest) {
+      fs9__namespace.writeFileSync(path10__namespace.join(tmpDir, "manifest.json"), JSON.stringify(manifest, null, 2), "utf8");
+    }
+    if (monolithJson !== null) {
+      fs9__namespace.writeFileSync(path10__namespace.join(tmpDir, "full-codebase.json"), monolithJson, "utf8");
+    }
+    if (monolithMarkdown !== null) {
+      fs9__namespace.writeFileSync(path10__namespace.join(tmpDir, "full-codebase.md"), monolithMarkdown, "utf8");
+    }
+    writeOwnershipMarker(tmpDir, markerPayload(tmpDir, "complete", snapshotId, createdAt));
+    swapIntoPlace(tmpDir, outDir);
+    stagingStarted = false;
+    const warningsBeforeHook = manifest.warnings.length;
+    runAfterGenerate(config, manifest);
+    if (artifacts.manifest && manifest.warnings.length !== warningsBeforeHook) {
+      writeManifestAtomically(path10__namespace.join(outDir, "manifest.json"), manifest);
+    }
+    writeOwnershipMarker(outDir, markerPayload(outDir, "complete", snapshotId, createdAt));
+    return manifest;
+  } catch (err) {
+    if (stagingStarted) {
+      try {
+        fs9__namespace.rmSync(tmpDir, { recursive: true, force: true });
+      } catch {
+      }
+    }
+    throw err;
+  } finally {
+    releaseLock();
   }
-  if (artifacts.projectTree) {
-    const projectTree = generateProjectTree(files.map((file) => file.relativePath));
-    fs9__namespace.writeFileSync(path10__namespace.join(reportsDir, "project-tree.md"), projectTree, "utf8");
-  }
-  if (artifacts.navigation) {
-    fs9__namespace.writeFileSync(path10__namespace.join(reportsDir, "navigation.md"), generateNavigation(manifest), "utf8");
-  }
-  if (artifacts.audit) {
-    fs9__namespace.writeFileSync(
-      path10__namespace.join(reportsDir, "audit.md"),
-      generateAuditReport(manifest, secretFindings),
-      "utf8"
-    );
-  }
-  if (artifacts.readme) {
-    fs9__namespace.writeFileSync(path10__namespace.join(tmpDir, "README.md"), generateReadme(manifest), "utf8");
-  }
-  if (artifacts.manifest) {
-    fs9__namespace.writeFileSync(path10__namespace.join(tmpDir, "manifest.json"), JSON.stringify(manifest, null, 2), "utf8");
-  }
-  if (monolithJson !== null) {
-    fs9__namespace.writeFileSync(path10__namespace.join(tmpDir, "full-codebase.json"), monolithJson, "utf8");
-  }
-  if (monolithMarkdown !== null) {
-    fs9__namespace.writeFileSync(path10__namespace.join(tmpDir, "full-codebase.md"), monolithMarkdown, "utf8");
-  }
-  swapIntoPlace(tmpDir, outDir);
-  runAfterGenerate(config, manifest);
-  return manifest;
+}
+
+// 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
@@ -5217,11 +6496,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."
       ]
     },
@@ -5230,7 +6509,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`."
       },
       {
@@ -5300,9 +6579,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",
@@ -5336,140 +6615,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".'
       }
     ],
@@ -5544,8 +6830,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'",
@@ -5619,7 +6905,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.
@@ -5720,14 +7007,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") {
@@ -5790,6 +7087,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" },
@@ -5836,6 +7134,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
@@ -5997,28 +7296,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)}").`
     );
@@ -6029,6 +7332,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),
@@ -6082,6 +7386,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 = path10__namespace.resolve(cwd, outDir, ...segments);
+  const relative5 = path10__namespace.relative(cwd, absolute);
+  if (relative5 && !relative5.startsWith("..") && !path10__namespace.isAbsolute(relative5)) return relative5;
+  return absolute;
+}
 function describeManifestShapeProblem(manifest) {
   if (!manifest || typeof manifest !== "object" || Array.isArray(manifest)) {
     return "not a JSON object";
@@ -6101,6 +7411,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),
@@ -6127,7 +7438,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.`
     );
@@ -6143,6 +7458,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;
   }
@@ -6219,7 +7541,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.");
@@ -6291,7 +7614,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 {
@@ -6315,7 +7638,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}`);
@@ -6330,7 +7655,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",
@@ -6338,10 +7665,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)`);
       }
@@ -6376,18 +7721,43 @@ ${USAGE}
 async function runWatchLoop(invocation, resolved) {
   const outDir = path10__namespace.resolve(resolved.cwd, resolved.outDir);
   const tmpDir = path10__namespace.resolve(resolved.cwd, resolved.tmpDir);
+  const VCS_SEGMENTS = /* @__PURE__ */ new Set([".git", ".hg", ".svn", ".bzr"]);
   const outName = path10__namespace.basename(outDir).toLowerCase();
   const tmpName = path10__namespace.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)`
@@ -6399,7 +7769,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 = fs9__namespace.watch(resolved.cwd, { recursive: true }, (_event, filename) => {
     if (filename) {
@@ -6407,7 +7777,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((resolve6) => {
     const stop = () => {