@ankurhalder/codebase-snapshot 2.1.0 → 2.2.0

package/dist/cli.cjs

@@ -81,7 +81,13 @@ function compareManifests(before, after) {
   };
 }
 function loadManifest(target) {
-  const manifestPath = fs9__namespace.statSync(target).isDirectory() ? path10__namespace.join(target, "manifest.json") : target;
+  let isDirectory;
+  try {
+    isDirectory = fs9__namespace.statSync(target).isDirectory();
+  } catch {
+    throw new Error(`No snapshot found at ${target}: the path does not exist.`);
+  }
+  const manifestPath = isDirectory ? path10__namespace.join(target, "manifest.json") : target;
   let raw;
   try {
     raw = fs9__namespace.readFileSync(manifestPath, "utf8");
@@ -97,6 +103,9 @@ function loadManifest(target) {
   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).`);
+  }
   return parsed;
 }
 function renderDiffText(diff) {
@@ -959,11 +968,12 @@ function detectPreset(cwd, forced) {
 }
 function getGitInfo(cwd, fallbackBranch = "main") {
   try {
-    const branch = childProcess__namespace.execSync("git rev-parse --abbrev-ref HEAD", {
+    const reported = childProcess__namespace.execSync("git rev-parse --abbrev-ref HEAD", {
       cwd,
       stdio: ["ignore", "pipe", "ignore"],
       encoding: "utf8"
-    }).trim() || fallbackBranch;
+    }).trim();
+    const branch = !reported || reported === "HEAD" ? fallbackBranch : reported;
     const commit = childProcess__namespace.execSync("git rev-parse HEAD", {
       cwd,
       stdio: ["ignore", "pipe", "ignore"],
@@ -1584,6 +1594,9 @@ async function loadConfigFileDetailed(cwd) {
       if (snapshotKey && typeof snapshotKey === "object") {
         return { config: snapshotKey, file: pkgJsonPath, warnings, errors };
       }
+      if (snapshotKey !== void 0) {
+        warnings.push(`${pkgJsonPath}: the "snapshot" key must be an object; it was ignored.`);
+      }
     } catch (err) {
       const message = err.message;
       warnings.push(message);
@@ -2096,11 +2109,12 @@ var PRESET_NAMES = [
   "java-spring \xB7 dotnet \xB7 php-laravel \xB7 ruby-rails",
   "monorepo \xB7 docs \xB7 infra \xB7 generic"
 ];
+var CONFIG_HEADER = `// Generated by codebase-snapshot. A plain object on purpose: this file must load
+// even when the package itself is only run through npx.
+`;
 function renderConfig(answers) {
   const { artifacts } = answers;
-  return `import { defineConfig } from "@ankurhalder/codebase-snapshot";
-
-export default defineConfig({
+  return `${CONFIG_HEADER}export default {
   // \u2500\u2500 Project \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\u2500
   // Which project shape to use. Detected from the repo when omitted.
   // ${PRESET_NAMES.join("\n  // ")}
@@ -2169,7 +2183,7 @@ export default defineConfig({
   // \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 */ }
   hooks: {},
-});
+};
 `;
 }
 function renderMinimalConfig(answers) {
@@ -2197,16 +2211,12 @@ ${entries},
   },`);
   }
   if (lines.length === 0) {
-    return `import { defineConfig } from "@ankurhalder/codebase-snapshot";
-
-export default defineConfig({});
+    return `${CONFIG_HEADER}export default {};
 `;
   }
-  return `import { defineConfig } from "@ankurhalder/codebase-snapshot";
-
-export default defineConfig({
+  return `${CONFIG_HEADER}export default {
 ${lines.join("\n")}
-});
+};
 `;
 }
 var PromptCancelled = class extends Error {
@@ -2467,6 +2477,17 @@ var CONFIG_CANDIDATES = [
   ".snapshotrc.json",
   ".snapshotrc"
 ];
+function chooseConfigFileName(cwd) {
+  if (!supportsTypeScriptImports()) return "snapshot.config.mjs";
+  const pkgPath = path10__namespace.join(cwd, "package.json");
+  if (!fs9__namespace.existsSync(pkgPath)) return "snapshot.config.mjs";
+  try {
+    const parsed = JSON.parse(fs9__namespace.readFileSync(pkgPath, "utf8"));
+    return parsed.type === "module" ? "snapshot.config.ts" : "snapshot.config.mjs";
+  } catch {
+    return "snapshot.config.mjs";
+  }
+}
 var SIZE_CHOICES = [
   { value: "60k", label: "Small", hint: "60 KB \xB7 ~15k tokens \xB7 tight context windows" },
   { value: "120k", label: "Medium", hint: "120 KB \xB7 ~30k tokens \xB7 recommended" },
@@ -2672,7 +2693,7 @@ async function runInit(options) {
     if (!proceed) throw new PromptCancelled();
   }
   const configText = options.minimal ? renderMinimalConfig(answers) : renderConfig(answers);
-  const configName = supportsTypeScriptImports() ? "snapshot.config.ts" : "snapshot.config.mjs";
+  const configName = chooseConfigFileName(options.cwd);
   const configPath = path10__namespace.join(options.cwd, configName);
   if (options.dryRun) {
     return {
@@ -2930,9 +2951,9 @@ var JAVA_METHOD = /^\s+(?:public|private|protected)\s+(?:static\s+)?(?:final\s+)
 var jvmProfile = {
   id: "jvm",
   extensions: [".java", ".kt", ".kts", ".scala"],
-  summarize(path12, content) {
+  summarize(path13, content) {
     const summary = emptySummary();
-    const lower = path12.toLowerCase();
+    const lower = path13.toLowerCase();
     const isJava = lower.endsWith(".java");
     const isKotlin = lower.endsWith(".kt") || lower.endsWith(".kts");
     eachLine(content, (line) => {
@@ -3353,16 +3374,16 @@ function summarizeTypeScriptSource(relativePath, content) {
 // src/ast/profiles/sfc.ts
 var SCRIPT_BLOCK = /<script[^>]*>([\s\S]*?)<\/script>/gi;
 var ASTRO_FRONTMATTER = /^\uFEFF?---[ \t]*\r?\n([\s\S]*?)\r?\n---[ \t]*(?=\r?\n|$)/;
-function componentName(path12) {
-  const base = path12.split("/").pop() ?? path12;
+function componentName(path13) {
+  const base = path13.split("/").pop() ?? path13;
   return base.replace(/\.[^.]+$/, "");
 }
 var sfcProfile = {
   id: "sfc",
   extensions: [".vue", ".svelte", ".astro"],
-  summarize(path12, content) {
+  summarize(path13, content) {
     let script = "";
-    if (path12.toLowerCase().endsWith(".astro")) {
+    if (path13.toLowerCase().endsWith(".astro")) {
       const frontmatter = ASTRO_FRONTMATTER.exec(content);
       if (frontmatter) script += `${frontmatter[1]}
 `;
@@ -3371,7 +3392,7 @@ var sfcProfile = {
       script += `${match[1]}
 `;
     }
-    const name = componentName(path12);
+    const name = componentName(path13);
     if (!script.trim()) {
       const summary2 = emptySummary();
       if (name) {
@@ -3405,15 +3426,15 @@ for (const profile of LANGUAGE_PROFILES) {
     BY_EXTENSION.set(extension.toLowerCase(), profile);
   }
 }
-function profileForPath(path12) {
-  const lower = path12.toLowerCase();
+function profileForPath(path13) {
+  const lower = path13.toLowerCase();
   const dot = lower.lastIndexOf(".");
   if (dot === -1) return null;
   return BY_EXTENSION.get(lower.slice(dot)) ?? null;
 }
-function summarizeWithProfile(path12, content) {
-  const profile = profileForPath(path12);
-  return profile ? profile.summarize(path12, content) : null;
+function summarizeWithProfile(path13, content) {
+  const profile = profileForPath(path13);
+  return profile ? profile.summarize(path13, content) : null;
 }
 
 // src/ast/structured.ts
@@ -4274,6 +4295,7 @@ function validateSnapshot(configInput) {
       drift.missingOnDisk.push(snapshotFile);
     }
   }
+  drift.missingOnDisk = [...new Set(drift.missingOnDisk)];
   const maxEffectiveBudget = Math.max(
     config.maxPartBytes,
     config.budgets.default,
@@ -4533,7 +4555,7 @@ function validateSnapshot(configInput) {
 
 // src/index.ts
 var GENERATOR_NAME = "@ankurhalder/codebase-snapshot";
-var GENERATOR_VERSION = "2.1.0";
+var GENERATOR_VERSION = "2.2.0";
 var SCHEMA_VERSION = "3.0.0";
 function sha256Hex2(input) {
   return crypto__namespace.createHash("sha256").update(input).digest("hex");
@@ -4777,7 +4799,9 @@ function artifactWarnings(artifacts) {
     );
   }
   if (ARTIFACT_NAMES.every((name) => artifacts[name] === false)) {
-    messages.push("every artifact is disabled: the snapshot directory will be empty.");
+    messages.push(
+      "every artifact is disabled: only the .codebase-snapshot ownership marker will be written."
+    );
   }
   return messages;
 }
@@ -5104,6 +5128,630 @@ function generateSnapshot(configInput, options) {
   return manifest;
 }
 
+// src/agent/contract.ts
+var CONTRACT_VERSION = "1.0.0";
+var PACKAGE_NAME = "@ankurhalder/codebase-snapshot";
+var ARTIFACT_SUMMARY = {
+  readme: "README.md describing the snapshot at the output root.",
+  manifest: "manifest.json: machine-readable index of every file, part, hash and config.",
+  parts: "parts/*.md: the packed, budget-limited markdown parts that carry the code.",
+  navigation: "reports/navigation.md: links between parts and layers.",
+  projectTree: "reports/project-tree.md: the directory tree of included files.",
+  audit: "reports/audit.md: secret findings, large files, parse diagnostics, git state.",
+  monolith: "full-codebase.json and full-codebase.md: the whole repository in one file (off by default)."
+};
+var ARTIFACT_DEFAULTS = {
+  readme: true,
+  manifest: true,
+  parts: true,
+  navigation: true,
+  projectTree: true,
+  audit: true,
+  monolith: false
+};
+function renderContractText(contract) {
+  const lines = [];
+  lines.push(`${contract.package} v${contract.version}`);
+  lines.push(contract.summary);
+  lines.push("");
+  lines.push(`Node        : ${contract.requires.node}`);
+  lines.push(`Schema      : ${contract.schemaVersion} (contract ${contract.contractVersion})`);
+  lines.push(`One-shot    : ${contract.invocation.oneShot} <command>`);
+  lines.push(`Installed   : ${contract.invocation.installed} <command>`);
+  lines.push("");
+  lines.push("Workflow:");
+  for (const step of contract.workflow) {
+    lines.push(`  ${step.step}. ${step.id}`);
+    lines.push(`     run    : ${step.run}`);
+    lines.push(`     expect : ${step.expect}`);
+    if (step.notes) lines.push(`     note   : ${step.notes}`);
+  }
+  lines.push("");
+  lines.push("Commands:");
+  for (const command of contract.commands) {
+    const args = command.positionals.length > 0 ? ` ${command.positionals.join(" ")}` : "";
+    lines.push(`  ${(command.name + args).padEnd(26)} ${command.summary}`);
+  }
+  lines.push("");
+  lines.push("Exit codes:");
+  for (const [code, meaning] of Object.entries(contract.exitCodes)) {
+    lines.push(`  ${code}  ${meaning}`);
+  }
+  lines.push("");
+  lines.push(`Presets (${contract.presets.length}): ${contract.presets.map((p) => p.name).join(", ")}`);
+  lines.push("");
+  lines.push("Artifacts:");
+  for (const artifact of contract.artifacts) {
+    lines.push(`  ${artifact.name.padEnd(12)} ${artifact.default ? "on " : "off"}  ${artifact.summary}`);
+  }
+  lines.push("");
+  lines.push("Options:");
+  for (const option of contract.options) {
+    const fallback = option.default === void 0 ? "" : ` [${JSON.stringify(option.default)}]`;
+    lines.push(`  ${option.flag.padEnd(24)} ${option.appliesTo.padEnd(32)}${fallback}`);
+    lines.push(`  ${"".padEnd(24)} ${option.summary}`);
+  }
+  lines.push("");
+  lines.push("Safety:");
+  for (const note of contract.safety) lines.push(`  - ${note}`);
+  lines.push("");
+  lines.push("Troubleshooting:");
+  for (const item of contract.troubleshooting) {
+    lines.push(`  ${item.symptom}`);
+    lines.push(`     cause: ${item.cause}`);
+    lines.push(`     fix  : ${item.fix}`);
+  }
+  lines.push("");
+  lines.push("This is the human rendering. Agents should use: describe --format json");
+  return lines.join("\n");
+}
+function buildAgentContract() {
+  return {
+    generator: GENERATOR_NAME,
+    package: PACKAGE_NAME,
+    version: GENERATOR_VERSION,
+    schemaVersion: SCHEMA_VERSION,
+    contractVersion: CONTRACT_VERSION,
+    summary: "Turns a repository into an LLM-ready snapshot: code packed into size-budgeted markdown parts, plus a manifest, a project tree, navigation and a secret audit. Auto-detects the project shape (framework, language, monorepo, docs, infra).",
+    requires: { node: ">=18.0.0", dependencies: ["typescript"] },
+    invocation: {
+      oneShot: `npx ${PACKAGE_NAME}@latest`,
+      installed: "npx snap",
+      bins: ["snap", "codebase-snapshot"],
+      notes: [
+        `Pin the tag (${PACKAGE_NAME}@latest or @2) instead of the bare package name.`,
+        "A bare scoped spec can resolve to a bin-less placeholder on some npm builds and exit 0 with no output; a pinned spec cannot.",
+        "Human progress goes to stderr. With --format json the payload on stdout is pure JSON."
+      ]
+    },
+    workflow: [
+      {
+        step: 1,
+        id: "verify",
+        run: `npx ${PACKAGE_NAME}@latest --version`,
+        expect: "prints v2.x.x on stdout and exits 0",
+        notes: "If it prints nothing, re-run with @latest explicitly, or use `npx -p <pkg> snap`."
+      },
+      {
+        step: 2,
+        id: "understand",
+        run: `npx ${PACKAGE_NAME}@latest describe --format json`,
+        expect: "the full contract as JSON: commands, options, presets, exit codes",
+        notes: "Read this before acting if you have no prior knowledge of the tool."
+      },
+      {
+        step: 3,
+        id: "configure",
+        run: `npx ${PACKAGE_NAME}@latest init --yes`,
+        expect: "writes snapshot.config.ts listing every setting at its current value",
+        notes: "Non-interactive. The detected preset is chosen automatically; override with --preset <name>. Skip this step to run on built-in defaults."
+      },
+      {
+        step: 4,
+        id: "generate",
+        run: `npx ${PACKAGE_NAME}@latest generate`,
+        expect: "exit 0, and ./snapshot/ written with parts, reports and manifest.json"
+      },
+      {
+        step: 5,
+        id: "verify-output",
+        run: `npx ${PACKAGE_NAME}@latest validate`,
+        expect: "exit 0 means the snapshot matches the files on disk",
+        notes: "Exit 1 means drift or a damaged snapshot; re-run generate."
+      },
+      {
+        step: 6,
+        id: "consume",
+        run: "read ./snapshot/parts/*.md, then ./snapshot/manifest.json, then ./snapshot/reports/audit.md",
+        expect: "the code, the index of what was included, and the risk findings",
+        notes: "manifest.json.files[] lists every included file with layer, kind, language, part and summary. manifest.skipped[] explains every file that was left out and why."
+      }
+    ],
+    commands: [
+      {
+        name: "generate",
+        aliases: ["default"],
+        summary: "Write the snapshot. This is the command you normally want.",
+        positionals: [],
+        exits: [0, 1]
+      },
+      {
+        name: "validate",
+        aliases: ["check"],
+        summary: "Compare the snapshot on disk with the repository; exit 1 on drift.",
+        positionals: [],
+        exits: [0, 1]
+      },
+      {
+        name: "report",
+        aliases: [],
+        summary: "Print snapshot health, layer metrics and the secret audit.",
+        positionals: [],
+        exits: [0, 1]
+      },
+      {
+        name: "init",
+        aliases: [],
+        summary: "Write a commented snapshot.config.ts (interactive, or --yes for CI).",
+        positionals: [],
+        exits: [0, 1, 2]
+      },
+      {
+        name: "explain",
+        aliases: [],
+        summary: "Explain how one path would be treated: layer, kind, part, skip reason.",
+        positionals: ["<path>"],
+        exits: [0, 1]
+      },
+      {
+        name: "diff",
+        aliases: [],
+        summary: "Compare two snapshots (directories or manifest.json files).",
+        positionals: ["<before>", "<after>"],
+        exits: [0, 1]
+      },
+      {
+        name: "describe",
+        aliases: [],
+        summary: "Print this contract. --format json for machines, text for humans.",
+        positionals: [],
+        exits: [0]
+      },
+      {
+        name: "skill",
+        aliases: [],
+        summary: "Print the agent skill, or --install it into the repository (AGENTS.md, .claude/skills, .cursor/rules).",
+        positionals: [],
+        exits: [0, 1, 2]
+      }
+    ],
+    exitCodes: {
+      "0": "success (and validate: no drift)",
+      "1": "drift detected, or generation refused/failed (nothing was written)",
+      "2": "usage error: unknown flag/command, bad value, wrong argument count"
+    },
+    options: [
+      {
+        flag: "--out-dir",
+        type: "string",
+        default: "snapshot",
+        appliesTo: "generate/validate/report/explain",
+        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",
+        summary: 'Byte budget per markdown part. Accepts "120k" / "1.5mb". Minimum 4096.'
+      },
+      {
+        flag: "--large-file-bytes",
+        type: "string",
+        default: 204800,
+        appliesTo: "generate/validate/report",
+        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",
+        summary: "Skip the monolith artifacts when they would exceed this size."
+      },
+      {
+        flag: "--include-monolith",
+        type: "boolean",
+        default: false,
+        appliesTo: "generate",
+        summary: "Also write full-codebase.json and full-codebase.md."
+      },
+      {
+        flag: "--include-sensitive-files",
+        type: "boolean",
+        default: false,
+        appliesTo: "generate/validate/report",
+        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",
+        summary: "Comma-separated artifacts to omit (readme, manifest, parts, navigation, projectTree, audit, monolith)."
+      },
+      {
+        flag: "--only-artifacts",
+        type: "string",
+        default: "unset",
+        appliesTo: "generate",
+        summary: "Write only these artifacts. Cannot be combined with --skip-artifacts."
+      },
+      {
+        flag: "--format",
+        type: "string",
+        default: "text",
+        appliesTo: "all commands",
+        summary: 'Output format: "text" or "json". JSON goes to stdout, progress to stderr.'
+      },
+      {
+        flag: "--cwd",
+        type: "string",
+        default: "process.cwd()",
+        appliesTo: "all commands",
+        summary: "Repository to operate on. Must be an existing directory."
+      },
+      {
+        flag: "--dry-run",
+        type: "boolean",
+        default: false,
+        appliesTo: "generate",
+        summary: "Compute everything and print the result without writing."
+      },
+      {
+        flag: "--watch",
+        type: "boolean",
+        default: false,
+        appliesTo: "generate",
+        summary: "Regenerate on every change until interrupted."
+      },
+      {
+        flag: "--preset",
+        type: "string",
+        default: "detected",
+        appliesTo: "init",
+        summary: "Force a project preset instead of detecting one. Unknown names are a usage error."
+      },
+      {
+        flag: "--include",
+        type: "string",
+        default: "unset",
+        appliesTo: "init",
+        summary: "Comma-separated allow-list of globs to record in the generated config."
+      },
+      {
+        flag: "--exclude",
+        type: "string",
+        default: "unset",
+        appliesTo: "init",
+        summary: "Comma-separated globs to record in the generated config."
+      },
+      {
+        flag: "--yes",
+        type: "boolean",
+        default: false,
+        appliesTo: "init",
+        summary: "Accept every default without prompting. Required in a non-TTY."
+      },
+      {
+        flag: "--minimal",
+        type: "boolean",
+        default: false,
+        appliesTo: "init",
+        summary: "Write only the settings that differ from the defaults."
+      },
+      {
+        flag: "--force",
+        type: "boolean",
+        default: false,
+        appliesTo: "init",
+        summary: "Overwrite an existing config file."
+      },
+      {
+        flag: "--install",
+        type: "boolean",
+        default: false,
+        appliesTo: "skill",
+        summary: "Write the skill into the repository instead of printing it."
+      },
+      {
+        flag: "--target",
+        type: "string",
+        default: "all",
+        appliesTo: "skill",
+        summary: 'Where to install: "claude", "agents", "cursor" or "all".'
+      }
+    ],
+    presets: PRESETS.map((preset) => ({
+      name: preset.name,
+      priority: preset.priority,
+      recommendedBudget: preset.recommendedBudget ?? "300k",
+      excludes: preset.exclude ? [...preset.exclude] : []
+    })),
+    artifacts: ARTIFACT_NAMES.map((name) => ({
+      name,
+      default: ARTIFACT_DEFAULTS[name] ?? true,
+      summary: ARTIFACT_SUMMARY[name] ?? name
+    })),
+    config: {
+      fileNames: [
+        "snapshot.config.ts",
+        "snapshot.config.js",
+        "snapshot.config.mjs",
+        "snapshot.config.cjs",
+        "snapshot.config.json",
+        ".snapshotrc",
+        ".snapshotrc.json",
+        'package.json \u2192 "snapshot" key'
+      ],
+      settings: [
+        { key: "outDir", type: "string", default: "snapshot", summary: "Snapshot output directory." },
+        { key: "tmpDir", type: "string", default: "snapshot.tmp", summary: "Scratch directory used for the atomic swap." },
+        { key: "branch", type: "string", default: "main", summary: "Branch recorded when git cannot report one." },
+        { key: "preset", type: "string", default: "detected", summary: "Force a preset. Unknown names are an error." },
+        { key: "maxPartBytes", type: "number | string", default: 307200, summary: "Per-part byte budget." },
+        { key: "largeFileBytes", type: "number | string", default: 204800, summary: "Preview threshold for large files." },
+        { key: "previewHeadLines", type: "number", default: 80, summary: "Lines kept from the head of a large file." },
+        { key: "previewTailLines", type: "number", default: 40, summary: "Lines kept from the tail of a large file." },
+        { key: "includeMonolith", type: "boolean", default: false, summary: "Also write the single-file monolith." },
+        { key: "maxMonolithBytes", type: "number | string | null", default: null, summary: "Skip the monolith above this size." },
+        { key: "includeSensitiveFiles", type: "boolean", default: false, summary: "Emit .env / *.pem / credential files." },
+        { key: "include", type: "string[]", default: "[]", summary: "Allow-list of globs; empty means everything." },
+        { key: "excludePatterns", type: "string[]", default: "[]", summary: "Extra exclude globs." },
+        { key: "artifacts", type: "object", default: "all on except monolith", summary: "Per-artifact opt-out." },
+        { key: "budgets", type: "object", default: "{ default, byLayer }", summary: "Per-layer byte budgets." },
+        { key: "layersMode", type: '"merge" | "replace"', default: "merge", summary: "Whether custom layers extend or replace the preset's." },
+        { key: "layers", type: "array", default: "preset layers", summary: "Custom layer rules (glob or RegExp)." },
+        { key: "kinds", type: "array", default: "preset kinds", summary: "Custom kind rules." },
+        { key: "secrets", type: "object", default: "{}", summary: "Custom secret patterns, or disable the defaults." },
+        { key: "hooks", type: "object", default: "{}", summary: "afterGenerate(manifest) runs after a successful generate." }
+      ]
+    },
+    output: {
+      layout: [
+        "<outDir>/README.md",
+        "<outDir>/manifest.json",
+        "<outDir>/parts/part-NNN.md",
+        "<outDir>/reports/project-tree.md",
+        "<outDir>/reports/navigation.md",
+        "<outDir>/reports/audit.md",
+        "<outDir>/.codebase-snapshot  (ownership marker, always written)"
+      ],
+      notes: [
+        "Parts are ordered and budget-limited; a single file larger than the budget becomes a head/tail preview.",
+        "manifest.json.files[] carries relativePath, layer, kind, language, part, inclusionMode, hash and a structural summary.",
+        "manifest.skipped[] carries the path and the exact reason it was excluded.",
+        `The output directory is replaced atomically; ${MIN_MAX_PART_BYTES} bytes is the smallest legal budget.`
+      ]
+    },
+    safety: [
+      "Sensitive files (.env, *.pem, .npmrc, .ssh/, .tfstate) are excluded by default and listed in manifest.skipped[].",
+      "Secret-shaped strings in ordinary source files are redacted in the emitted parts.",
+      "The tool refuses to replace an outDir that it did not create, so a mistyped outDir cannot delete source code.",
+      "Nothing is ever written above the repository root; --out-dir may not be the root or an ancestor."
+    ],
+    troubleshooting: [
+      {
+        symptom: "Command prints nothing and exits 0",
+        cause: "A bare scoped spec resolved to a bin-less placeholder manifest on this npm build.",
+        fix: `Use the pinned form: npx ${PACKAGE_NAME}@latest ...`
+      },
+      {
+        symptom: "Exit 1 with 'Refusing to replace outDir'",
+        cause: "The outDir exists and contains files this tool did not write.",
+        fix: "Choose a new/empty --out-dir, or delete the existing directory yourself."
+      },
+      {
+        symptom: "Exit 1 with 'The config file could not be read'",
+        cause: "snapshot.config.* exists but does not parse.",
+        fix: "Fix the syntax, or delete the config to use the defaults."
+      },
+      {
+        symptom: "Exit 1 from validate",
+        cause: "The snapshot no longer matches the files on disk.",
+        fix: "Re-run generate."
+      },
+      {
+        symptom: "A directory you expected is missing from the snapshot",
+        cause: "It is excluded by the preset, by default ignores, or by your own globs.",
+        fix: "Run `explain <path>`; manifest.skipped[] also records the reason for every file."
+      }
+    ]
+  };
+}
+
+// src/agent/skill.ts
+var PACKAGE_NAME2 = "@ankurhalder/codebase-snapshot";
+var SKILL_NAME = "codebase-snapshot";
+var AGENTS_MARKER_START = "<!-- codebase-snapshot:skill:start -->";
+var AGENTS_MARKER_END = "<!-- codebase-snapshot:skill:end -->";
+function renderSkill() {
+  return `---
+name: ${SKILL_NAME}
+description: Create an LLM-ready snapshot of a repository (size-budgeted markdown parts, a JSON manifest, project tree, navigation and a secret audit) when a whole codebase has to be read, summarized or handed to a model that cannot clone it. Use when asked to snapshot a codebase, prepare repository context, or analyze a project's structure.
+version: ${GENERATOR_VERSION}
+---
+
+# codebase-snapshot
+
+Turns a repository into an LLM-ready snapshot under \`./snapshot/\`: code packed into
+size-budgeted markdown parts, plus a manifest that indexes every file, a project tree, a
+navigation index and a secret audit.
+
+Use it when you need to understand a whole repository, or produce repository context for
+another model, and reading files one by one would not fit in context.
+
+## Before you start
+
+This tool is a Node CLI. It needs **Node.js 18 or newer**. You do not need to install it
+globally, and you do not need to clone anything.
+
+**Always pin the tag** \u2014 \`npx ${PACKAGE_NAME2}@latest <command>\`. A bare scoped spec can
+resolve to a placeholder manifest with no executable on some npm builds and exit 0
+printing nothing; the pinned form cannot. If a command exits 0 with no output, that is
+the cause, not a broken repository.
+
+## Step by step
+
+1. **Verify the tool.** Run \`npx ${PACKAGE_NAME2}@latest --version\`. Expect \`v${GENERATOR_VERSION}\` or
+   newer on stdout. Empty output means you hit the bare-spec problem above.
+
+2. **Read the contract, not the prose.** Run
+   \`npx ${PACKAGE_NAME2}@latest describe --format json\`. It returns the full machine
+   contract: every command, every option with its default, the exit-code meanings, the
+   25 project presets, the artifact list, the config settings and a troubleshooting
+   table. Read it before you make decisions; do not guess option names.
+
+3. **Look before you leap (optional but cheap).** To see how a specific file or directory
+   would be treated, run \`npx ${PACKAGE_NAME2}@latest explain <path>\`. It reports the
+   layer, kind, language, target part, and the exact reason a path would be skipped.
+   \`--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
+   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.
+
+5. **Generate.** Run \`npx ${PACKAGE_NAME2}@latest generate\`. Expect exit 0 and a
+   \`./snapshot/\` directory. If you need a different location use \`--out-dir <path>\`; if
+   you need smaller or larger parts use \`--max-part-bytes 120k\`.
+
+6. **Verify.** Run \`npx ${PACKAGE_NAME2}@latest validate\`. Exit 0 means the snapshot
+   matches the files on disk. Exit 1 means drift \u2014 re-run step 5.
+
+7. **Read the output in this order:**
+   - \`snapshot/parts/part-*.md\` \u2014 the code itself, each file tagged with its layer, kind,
+     language and a structural summary (imports, exports, classes, functions).
+   - \`snapshot/manifest.json\` \u2014 the index. \`files[]\` has \`relativePath\`, \`layer\`,
+     \`kind\`, \`language\`, \`part\`, \`inclusionMode\`, \`hashSha256\` and \`summary\`.
+     \`skipped[]\` records every excluded file **and why**. Prefer querying this over
+     re-reading the parts.
+   - \`snapshot/reports/audit.md\` \u2014 secrets found, large files, parse diagnostics, git
+     state. Read this before you quote code back to a user.
+   - \`snapshot/reports/project-tree.md\` and \`navigation.md\` \u2014 structure and cross-links.
+
+## Project types
+
+Detection is automatic and covers Next.js, Nuxt, SvelteKit, Remix, Astro, Angular, Solid,
+Vue+React with Vite, Nest, Express/Fastify/Koa, any Node library, monorepos, Django,
+FastAPI/Flask, plain Python, Go, Rust, Java/Spring, .NET, PHP/Laravel, Ruby/Rails,
+Terraform/Docker infra, docs-only repositories, and a generic fallback. It sets sensible
+layers, kinds, ecosystem ignore patterns and a recommended part budget. For non-TypeScript
+languages it extracts imports, exports, classes and functions structurally; Vue, Svelte and
+Astro script blocks go through the real TypeScript compiler. You do not need to configure
+any of this to get a good first snapshot.
+
+## Things that will surprise you
+
+- **Sensitive files are excluded by default** (\`.env\`, \`*.pem\`, \`.npmrc\`, \`.ssh/\`,
+  \`.tfstate\`) and are listed in \`manifest.skipped[]\`. Add \`--include-sensitive-files\` only
+  if the user asks for them explicitly.
+- **Secret-shaped strings inside normal source files are redacted** in the emitted parts.
+  If the user needs the raw value, say so rather than working around it.
+- **The output directory is owned by the tool.** It is replaced atomically, and the tool
+  refuses to replace a directory it did not create. Never point \`--out-dir\` at source
+  code; if you see \`Refusing to replace outDir\`, choose a new directory rather than
+  deleting anything.
+- **Exit 2 is a usage error**, not a failure of the repository. Re-read the contract
+  before retrying.
+- **\`--format json\` keeps stdout pure.** Progress goes to stderr, so \`stdout\` is safe to
+  pipe into a JSON parser.
+
+## Making this available to other agents
+
+Run \`npx ${PACKAGE_NAME2}@latest skill --install\`. It writes this skill into the
+repository in the places agents look for it by default: an \`AGENTS.md\` section,
+\`.claude/skills/${SKILL_NAME}/SKILL.md\`, and \`.cursor/rules/${SKILL_NAME}.mdc\`. The command
+is idempotent and only replaces its own marked section.
+`;
+}
+
+// src/agent/install-skill.ts
+var SKILL_TARGETS = ["claude", "agents", "cursor", "all"];
+function targetPath(cwd, target) {
+  switch (target) {
+    case "claude":
+      return path10__namespace.join(cwd, ".claude", "skills", SKILL_NAME, "SKILL.md");
+    case "cursor":
+      return path10__namespace.join(cwd, ".cursor", "rules", `${SKILL_NAME}.mdc`);
+    case "agents":
+      return path10__namespace.join(cwd, "AGENTS.md");
+  }
+}
+function writeIfChanged(target, filePath, content) {
+  const existing = fs9__namespace.existsSync(filePath) ? fs9__namespace.readFileSync(filePath, "utf8") : null;
+  if (existing === content) return { target, path: filePath, action: "unchanged" };
+  fs9__namespace.mkdirSync(path10__namespace.dirname(filePath), { recursive: true });
+  fs9__namespace.writeFileSync(filePath, content, "utf8");
+  return { target, path: filePath, action: existing === null ? "created" : "updated" };
+}
+function agentsBlock(skill) {
+  return [
+    AGENTS_MARKER_START,
+    "",
+    `## ${SKILL_NAME} (${"@ankurhalder/codebase-snapshot"})`,
+    "",
+    // Drop the YAML frontmatter: inside AGENTS.md it is noise, and the heading
+    // above already names the skill.
+    skill.replace(/^---[\s\S]*?---\r?\n/, "").trim(),
+    "",
+    AGENTS_MARKER_END,
+    ""
+  ].join("\n");
+}
+function mergeAgentsFile(cwd, skill) {
+  const filePath = targetPath(cwd, "agents");
+  const block = agentsBlock(skill);
+  const existing = fs9__namespace.existsSync(filePath) ? fs9__namespace.readFileSync(filePath, "utf8") : null;
+  let next;
+  if (existing === null) {
+    next = `# AGENTS.md
+
+${block}`;
+  } else if (existing.includes(AGENTS_MARKER_START) && existing.includes(AGENTS_MARKER_END)) {
+    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()}
+
+${block}`;
+  }
+  const action = existing === null ? "created" : existing === next ? "unchanged" : "updated";
+  if (action !== "unchanged") {
+    fs9__namespace.mkdirSync(path10__namespace.dirname(filePath), { recursive: true });
+    fs9__namespace.writeFileSync(filePath, next, "utf8");
+  }
+  return { target: "agents", path: filePath, action };
+}
+function installSkill(cwd, target = "all") {
+  const skill = renderSkill();
+  const written = [];
+  const wanted = target === "all" ? ["agents", "claude", "cursor"] : [target];
+  for (const item of wanted) {
+    if (item === "agents") {
+      written.push(mergeAgentsFile(cwd, skill));
+      continue;
+    }
+    written.push(writeIfChanged(item, targetPath(cwd, item), skill));
+  }
+  return { cwd, written };
+}
+function isSkillTarget(value) {
+  return SKILL_TARGETS.includes(value);
+}
+
 // src/cli.ts
 var VERSION = GENERATOR_VERSION;
 var COMMAND_ALIASES = /* @__PURE__ */ new Map([
@@ -5113,7 +5761,9 @@ var COMMAND_ALIASES = /* @__PURE__ */ new Map([
   ["report", "report"],
   ["init", "init"],
   ["explain", "explain"],
-  ["diff", "diff"]
+  ["diff", "diff"],
+  ["describe", "describe"],
+  ["skill", "skill"]
 ]);
 var COMMAND_ARITY = {
   generate: 0,
@@ -5121,7 +5771,9 @@ var COMMAND_ARITY = {
   report: 0,
   init: 0,
   explain: 1,
-  diff: 2
+  diff: 2,
+  describe: 0,
+  skill: 0
 };
 var CLI_OPTIONS = {
   cwd: { type: "string" },
@@ -5143,6 +5795,8 @@ var CLI_OPTIONS = {
   yes: { type: "boolean" },
   minimal: { type: "boolean" },
   force: { type: "boolean" },
+  install: { type: "boolean" },
+  target: { type: "string" },
   help: { type: "boolean", short: "h" },
   version: { type: "boolean", short: "v" }
 };
@@ -5163,6 +5817,8 @@ Commands:
   report               Print codebase health, layer metrics, and secret audit
   explain <path>       Show how one path would be treated: layer, kind, part, skips
   diff <a> <b>         Compare two snapshots (directories or manifest.json files)
+  describe             Print the machine-readable contract (--format json for agents)
+  skill                Print the bundled agent skill; --install writes it into the repo
 
 Options:
   --cwd <path>                  Target repository directory (default: current directory)
@@ -5188,11 +5844,17 @@ Options:
   --minimal                     Write only the settings that differ from defaults
   --yes                         Accept every default without prompting
   --force                       Overwrite an existing config
+
+  skill only:
+  --install                     Write the skill into the repository instead of printing
+  --target <name>               claude | agents | cursor | all (default: all)
+
   -h, --help                    Display this help message
   -v, --version                 Display version
 
 All options also accept the --option=value form.
 Human-readable progress is written to stderr; payloads (--format json) go to stdout.
+Agents with no prior knowledge of this tool should start with: describe --format json
 `.trim();
 function parsePositiveInteger(raw, optionName, minimum) {
   if (raw === void 0) return void 0;
@@ -5244,9 +5906,32 @@ function parseCliArgs(argv) {
       strict: true
     });
   } catch (err) {
-    throw new UsageError(err.message);
+    const message = err.message;
+    const ambiguous = /^Option '(--[^']+)' argument is ambiguous/i.exec(message);
+    if (ambiguous) {
+      throw new UsageError(
+        `${ambiguous[1]} received a value that looks like another flag (for example a negative number). Use the "--option=value" form, and note that sizes must be positive.`
+      );
+    }
+    throw new UsageError(message);
   }
   const values = parsed.values;
+  for (const [name, spec] of Object.entries(CLI_OPTIONS)) {
+    if (spec.type !== "string") continue;
+    const raw = values[name];
+    if (raw !== void 0 && String(raw).trim() === "") {
+      throw new UsageError(`--${name} requires a value (received an empty string).`);
+    }
+  }
+  if (values.cwd !== void 0) {
+    const target = String(values.cwd);
+    if (!fs9__namespace.existsSync(target)) {
+      throw new UsageError(`--cwd directory does not exist: ${target}`);
+    }
+    if (!fs9__namespace.statSync(target).isDirectory()) {
+      throw new UsageError(`--cwd is not a directory: ${target}`);
+    }
+  }
   if (values.help) {
     process.stdout.write(`${USAGE}
 `);
@@ -5330,6 +6015,14 @@ function parseCliArgs(argv) {
     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))) {
+    throw new UsageError(
+      `--target must be one of: ${SKILL_TARGETS.join(", ")} (received "${String(values.target)}").`
+    );
+  }
   return {
     command,
     args,
@@ -5343,6 +6036,8 @@ function parseCliArgs(argv) {
     yes: values.yes === true,
     minimal: values.minimal === true,
     force: values.force === true,
+    install: values.install === true,
+    target: values.target === void 0 ? void 0 : String(values.target),
     cwd: values.cwd === void 0 ? process.cwd() : path10__namespace.resolve(String(values.cwd)),
     outDir: values["out-dir"] === void 0 ? void 0 : String(values["out-dir"]),
     includeMonolith: values["include-monolith"] === true ? true : void 0,
@@ -5433,6 +6128,9 @@ async function runInitCommand(invocation) {
     for (const note of result.notes) info(`   \u26A0 ${note}`);
     info("");
     info("   Next:  npm run snapshot");
+    info(
+      `   Tip:   \`${GENERATOR_NAME} skill --install\` makes this repo discoverable by AI agents.`
+    );
     return 0;
   } catch (err) {
     if (err instanceof PromptCancelled) {
@@ -5443,6 +6141,31 @@ async function runInitCommand(invocation) {
     return 1;
   }
 }
+function runSkillCommand(invocation) {
+  if (!invocation.install) {
+    process.stdout.write(renderSkill());
+    return 0;
+  }
+  try {
+    const result = installSkill(invocation.cwd, invocation.target);
+    if (invocation.format === "json") {
+      process.stdout.write(`${JSON.stringify(result, null, 2)}
+`);
+      return 0;
+    }
+    info(`\u2705 Agent skill installed (${SKILL_NAME}):`);
+    for (const item of result.written) {
+      const shown = path10__namespace.relative(invocation.cwd, item.path) || item.path;
+      info(`   - ${item.action.padEnd(9)} ${shown}`);
+    }
+    info("");
+    info("   Agents that read AGENTS.md, .claude/skills or .cursor/rules will pick this up automatically.");
+    return 0;
+  } catch (err) {
+    warn(`\u274C Could not install the skill: ${err.message}`);
+    return 1;
+  }
+}
 function renderValidateText(result) {
   if (result.valid) {
     info("\u2705 Snapshot is valid and up to date with disk.");
@@ -5464,6 +6187,9 @@ function renderValidateText(result) {
     for (const missing of result.drift.missingOnDisk.slice(0, 20)) {
       warn(`  - deleted: ${missing}`);
     }
+    for (const mismatch of result.drift.totalsMismatches.slice(0, 20)) {
+      warn(`  - counts: ${mismatch}`);
+    }
   }
   for (const warning of result.warnings) warn(`  \u26A0 ${warning}`);
 }
@@ -5485,6 +6211,14 @@ ${USAGE}
   if (invocation.command === "init") {
     return await runInitCommand(invocation);
   }
+  if (invocation.command === "describe") {
+    const contract = buildAgentContract();
+    emit(invocation.format, contract, () => info(renderContractText(contract)));
+    return 0;
+  }
+  if (invocation.command === "skill") {
+    return runSkillCommand(invocation);
+  }
   const loaded = await loadConfigFileDetailed(invocation.cwd);
   for (const warning of loaded.warnings) warn(`\u26A0 Config: ${warning}`);
   if (loaded.errors.length > 0) {
@@ -5594,9 +6328,23 @@ ${USAGE}
       info(
         `   - Total size:    ${(manifest.counts.totalSizeBytes / (1024 * 1024)).toFixed(2)} MB`
       );
-      info(`   - Parts written: ${manifest.counts.partsCount} under ${resolved.outDir}/parts/`);
-      info(`   - Reports:       ${resolved.outDir}/reports/ (project-tree, navigation, audit)`);
-      info(`   - Manifest:      ${resolved.outDir}/manifest.json`);
+      const { artifacts } = resolved;
+      if (artifacts.parts) {
+        info(`   - Parts written: ${manifest.counts.partsCount} under ${resolved.outDir}/parts/`);
+      }
+      const reports = [
+        artifacts.projectTree && "project-tree",
+        artifacts.navigation && "navigation",
+        artifacts.audit && "audit"
+      ].filter(Boolean);
+      if (reports.length > 0) {
+        info(`   - Reports:       ${resolved.outDir}/reports/ (${reports.join(", ")})`);
+      }
+      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)`);
+      }
       info(`   - Fingerprint:   ${manifest.fingerprint}`);
       info(`   - Integrity:     ${manifest.validation.status}`);
       if (manifest.warnings.length > 0) {
@@ -5613,6 +6361,14 @@ ${USAGE}
     }
     return manifest.validation.status === "passed" ? 0 : 1;
   } catch (err) {
+    const code = err.code;
+    if (code === "EPERM" || code === "EACCES") {
+      warn(
+        `\u274C Cannot write the snapshot: permission denied under ${resolved.outDir}. Check the directory's permissions or choose another --out-dir.`
+      );
+      warn(`   (${err.message})`);
+      return 1;
+    }
     warn(`\u274C Failed to generate snapshot: ${err.message}`);
     return 1;
   }