@ankurhalder/codebase-snapshot 2.1.1 → 3.0.0

package/dist/bin.js

@@ -1,8 +1,8 @@
 #!/usr/bin/env node
 
 // src/cli.ts
-import * as fs10 from "fs";
-import * as path11 from "path";
+import * as fs11 from "fs";
+import * as path12 from "path";
 import { parseArgs } from "util";
 
 // src/diff.ts
@@ -2107,11 +2107,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  // ")}
@@ -2180,7 +2181,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) {
@@ -2208,16 +2209,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")}
-});
+};
 `;
 }
 
@@ -2481,6 +2478,17 @@ var CONFIG_CANDIDATES = [
   ".snapshotrc.json",
   ".snapshotrc"
 ];
+function chooseConfigFileName(cwd) {
+  if (!supportsTypeScriptImports()) return "snapshot.config.mjs";
+  const pkgPath = path7.join(cwd, "package.json");
+  if (!fs6.existsSync(pkgPath)) return "snapshot.config.mjs";
+  try {
+    const parsed = JSON.parse(fs6.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" },
@@ -2686,7 +2694,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 = path7.join(options.cwd, configName);
   if (options.dryRun) {
     return {
@@ -2949,9 +2957,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) => {
@@ -3375,16 +3383,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]}
 `;
@@ -3393,7 +3401,7 @@ var sfcProfile = {
       script += `${match[1]}
 `;
     }
-    const name = componentName(path12);
+    const name = componentName(path13);
     if (!script.trim()) {
       const summary2 = emptySummary();
       if (name) {
@@ -3427,15 +3435,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
@@ -4568,7 +4576,7 @@ function validateSnapshot(configInput) {
 
 // src/index.ts
 var GENERATOR_NAME = "@ankurhalder/codebase-snapshot";
-var GENERATOR_VERSION = "2.1.1";
+var GENERATOR_VERSION = "3.0.0";
 var SCHEMA_VERSION = "3.0.0";
 function sha256Hex2(input) {
   return crypto3.createHash("sha256").update(input).digest("hex");
@@ -5141,6 +5149,635 @@ 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 codebase-snapshot",
+      bins: ["codebase-snapshot"],
+      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.",
+        "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, clear the npm cache and retry, or use `npx -p <pkg> codebase-snapshot`."
+      },
+      {
+        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: "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>.`
+      },
+      {
+        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/install-skill.ts
+import * as fs10 from "fs";
+import * as path11 from "path";
+
+// 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.
+
+**Pin the tag** \u2014 \`npx ${PACKAGE_NAME2}@latest <command>\` \u2014 when you need the same version on
+every machine. The bare package name works too: this package ships exactly one executable,
+which is what lets npm pick it. If a command exits 0 printing nothing, the executable was
+not resolved \u2014 clear the npm cache and retry; do not assume the repository is broken.
+
+## 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 path11.join(cwd, ".claude", "skills", SKILL_NAME, "SKILL.md");
+    case "cursor":
+      return path11.join(cwd, ".cursor", "rules", `${SKILL_NAME}.mdc`);
+    case "agents":
+      return path11.join(cwd, "AGENTS.md");
+  }
+}
+function writeIfChanged(target, filePath, content) {
+  const existing = fs10.existsSync(filePath) ? fs10.readFileSync(filePath, "utf8") : null;
+  if (existing === content) return { target, path: filePath, action: "unchanged" };
+  fs10.mkdirSync(path11.dirname(filePath), { recursive: true });
+  fs10.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 = fs10.existsSync(filePath) ? fs10.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") {
+    fs10.mkdirSync(path11.dirname(filePath), { recursive: true });
+    fs10.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([
@@ -5150,7 +5787,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,
@@ -5158,7 +5797,9 @@ var COMMAND_ARITY = {
   report: 0,
   init: 0,
   explain: 1,
-  diff: 2
+  diff: 2,
+  describe: 0,
+  skill: 0
 };
 var CLI_OPTIONS = {
   cwd: { type: "string" },
@@ -5180,6 +5821,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" }
 };
@@ -5191,7 +5834,6 @@ Production-grade LLM codebase snapshot generator, auditor, and AST partitioner
 
 Usage:
   codebase-snapshot [command] [options]
-  snap [command] [options]
 
 Commands:
   generate (default)   Generate a complete partitioned codebase snapshot
@@ -5200,6 +5842,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)
@@ -5225,11 +5869,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 parseByteOption(raw, optionName, minimum) {
   if (raw === void 0) return void 0;
@@ -5288,10 +5938,10 @@ function parseCliArgs(argv) {
   }
   if (values.cwd !== void 0) {
     const target = String(values.cwd);
-    if (!fs10.existsSync(target)) {
+    if (!fs11.existsSync(target)) {
       throw new UsageError(`--cwd directory does not exist: ${target}`);
     }
-    if (!fs10.statSync(target).isDirectory()) {
+    if (!fs11.statSync(target).isDirectory()) {
       throw new UsageError(`--cwd is not a directory: ${target}`);
     }
   }
@@ -5370,7 +6020,7 @@ function parseCliArgs(argv) {
     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 \`snap init\` to generate one).`
+        `${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).`
       );
     }
   }
@@ -5378,6 +6028,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,
@@ -5391,7 +6049,9 @@ function parseCliArgs(argv) {
     yes: values.yes === true,
     minimal: values.minimal === true,
     force: values.force === true,
-    cwd: values.cwd === void 0 ? process.cwd() : path11.resolve(String(values.cwd)),
+    install: values.install === true,
+    target: values.target === void 0 ? void 0 : String(values.target),
+    cwd: values.cwd === void 0 ? process.cwd() : path12.resolve(String(values.cwd)),
     outDir: values["out-dir"] === void 0 ? void 0 : String(values["out-dir"]),
     includeMonolith: values["include-monolith"] === true ? true : void 0,
     includeSensitiveFiles: values["include-sensitive-files"] === true ? true : void 0,
@@ -5473,7 +6133,7 @@ async function runInitCommand(invocation) {
       info(result.configText);
       return 0;
     }
-    info(`\u2705 Created ${path11.basename(result.configPath)} (preset: ${result.preset})`);
+    info(`\u2705 Created ${path12.basename(result.configPath)} (preset: ${result.preset})`);
     if (result.scripts.length > 0) info(`   Added npm scripts: ${result.scripts.join(", ")}`);
     if (result.gitignoreEntries.length > 0) {
       info(`   Added to .gitignore: ${result.gitignoreEntries.join(", ")}`);
@@ -5481,6 +6141,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) {
@@ -5491,6 +6154,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 = path12.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.");
@@ -5536,13 +6224,21 @@ ${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) {
     warn("\u274C The config file could not be read. Fix it, or delete it to use the defaults.");
     return 1;
   }
-  if (loaded.file) info(`\u2699  Using config ${path11.relative(process.cwd(), loaded.file) || loaded.file}`);
+  if (loaded.file) info(`\u2699  Using config ${path12.relative(process.cwd(), loaded.file) || loaded.file}`);
   const resolved = resolveConfig(
     loaded.config,
     {
@@ -5566,14 +6262,14 @@ ${USAGE}
     return result.valid ? 0 : 1;
   }
   if (invocation.command === "report") {
-    const manifestPath = path11.resolve(resolved.cwd, resolved.outDir, "manifest.json");
-    if (!fs10.existsSync(manifestPath)) {
+    const manifestPath = path12.resolve(resolved.cwd, resolved.outDir, "manifest.json");
+    if (!fs11.existsSync(manifestPath)) {
       warn(`\u274C Manifest not found at ${manifestPath}. Run generate first.`);
       return 1;
     }
     let manifest;
     try {
-      manifest = JSON.parse(fs10.readFileSync(manifestPath, "utf8"));
+      manifest = JSON.parse(fs11.readFileSync(manifestPath, "utf8"));
     } catch (err) {
       warn(`\u274C Could not read ${manifestPath}: ${err.message}`);
       return 1;
@@ -5691,10 +6387,10 @@ ${USAGE}
   }
 }
 async function runWatchLoop(invocation, resolved) {
-  const outDir = path11.resolve(resolved.cwd, resolved.outDir);
-  const tmpDir = path11.resolve(resolved.cwd, resolved.tmpDir);
-  const outName = path11.basename(outDir).toLowerCase();
-  const tmpName = path11.basename(tmpDir).toLowerCase();
+  const outDir = path12.resolve(resolved.cwd, resolved.outDir);
+  const tmpDir = path12.resolve(resolved.cwd, resolved.tmpDir);
+  const outName = path12.basename(outDir).toLowerCase();
+  const tmpName = path12.basename(tmpDir).toLowerCase();
   const isGenerated = (candidate) => candidate.toLowerCase().split(/[\\/]/).some(
     (segment) => segment === outName || segment === tmpName || segment.startsWith(`${outName}.backup-`)
   );
@@ -5718,9 +6414,9 @@ async function runWatchLoop(invocation, resolved) {
   info("\u{1F440} Watching for changes. Press Ctrl+C to stop.");
   regenerate();
   let timer = null;
-  const watcher = fs10.watch(resolved.cwd, { recursive: true }, (_event, filename) => {
+  const watcher = fs11.watch(resolved.cwd, { recursive: true }, (_event, filename) => {
     if (filename) {
-      const changed = path11.resolve(resolved.cwd, filename.toString());
+      const changed = path12.resolve(resolved.cwd, filename.toString());
       if (isGenerated(changed)) return;
     }
     if (timer) clearTimeout(timer);