@ankurhalder/codebase-snapshot 2.1.0 → 2.2.0

package/dist/cli.js

@@ -1,8 +1,633 @@
-import { parseByteSize, GENERATOR_VERSION, ARTIFACT_NAMES, getPreset, unknownPresetMessage, MIN_MAX_PART_BYTES, loadConfigFileDetailed, resolveConfig, validateSnapshot, explainPath, compareManifests, loadManifest, renderDiffText, generateSnapshot, GENERATOR_NAME, runInit, PromptCancelled, renderExplainText } from './chunk-QEIOXPMU.js';
+import { parseByteSize, GENERATOR_VERSION, ARTIFACT_NAMES, getPreset, unknownPresetMessage, MIN_MAX_PART_BYTES, loadConfigFileDetailed, resolveConfig, validateSnapshot, explainPath, compareManifests, loadManifest, renderDiffText, generateSnapshot, GENERATOR_NAME, runInit, PromptCancelled, SCHEMA_VERSION, PRESETS, renderExplainText } from './chunk-5I564BGX.js';
 import * as fs from 'fs';
-import * as path from 'path';
+import * as path2 from 'path';
 import { parseArgs } from 'util';
 
+// 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 path2.join(cwd, ".claude", "skills", SKILL_NAME, "SKILL.md");
+    case "cursor":
+      return path2.join(cwd, ".cursor", "rules", `${SKILL_NAME}.mdc`);
+    case "agents":
+      return path2.join(cwd, "AGENTS.md");
+  }
+}
+function writeIfChanged(target, filePath, content) {
+  const existing = fs.existsSync(filePath) ? fs.readFileSync(filePath, "utf8") : null;
+  if (existing === content) return { target, path: filePath, action: "unchanged" };
+  fs.mkdirSync(path2.dirname(filePath), { recursive: true });
+  fs.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 = fs.existsSync(filePath) ? fs.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") {
+    fs.mkdirSync(path2.dirname(filePath), { recursive: true });
+    fs.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([
   ["generate", "generate"],
@@ -11,7 +636,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,
@@ -19,7 +646,9 @@ var COMMAND_ARITY = {
   report: 0,
   init: 0,
   explain: 1,
-  diff: 2
+  diff: 2,
+  describe: 0,
+  skill: 0
 };
 var CLI_OPTIONS = {
   cwd: { type: "string" },
@@ -41,6 +670,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" }
 };
@@ -61,6 +692,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)
@@ -86,11 +719,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;
@@ -142,9 +781,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 (!fs.existsSync(target)) {
+      throw new UsageError(`--cwd directory does not exist: ${target}`);
+    }
+    if (!fs.statSync(target).isDirectory()) {
+      throw new UsageError(`--cwd is not a directory: ${target}`);
+    }
+  }
   if (values.help) {
     process.stdout.write(`${USAGE}
 `);
@@ -228,6 +890,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,
@@ -241,7 +911,9 @@ function parseCliArgs(argv) {
     yes: values.yes === true,
     minimal: values.minimal === true,
     force: values.force === true,
-    cwd: values.cwd === void 0 ? process.cwd() : path.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() : path2.resolve(String(values.cwd)),
     outDir: values["out-dir"] === void 0 ? void 0 : String(values["out-dir"]),
     includeMonolith: values["include-monolith"] === true ? true : void 0,
     includeSensitiveFiles: values["include-sensitive-files"] === true ? true : void 0,
@@ -323,7 +995,7 @@ async function runInitCommand(invocation) {
       info(result.configText);
       return 0;
     }
-    info(`\u2705 Created ${path.basename(result.configPath)} (preset: ${result.preset})`);
+    info(`\u2705 Created ${path2.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(", ")}`);
@@ -331,6 +1003,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) {
@@ -341,6 +1016,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 = path2.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.");
@@ -362,6 +1062,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}`);
 }
@@ -383,13 +1086,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 ${path.relative(process.cwd(), loaded.file) || loaded.file}`);
+  if (loaded.file) info(`\u2699  Using config ${path2.relative(process.cwd(), loaded.file) || loaded.file}`);
   const resolved = resolveConfig(
     loaded.config,
     {
@@ -413,7 +1124,7 @@ ${USAGE}
     return result.valid ? 0 : 1;
   }
   if (invocation.command === "report") {
-    const manifestPath = path.resolve(resolved.cwd, resolved.outDir, "manifest.json");
+    const manifestPath = path2.resolve(resolved.cwd, resolved.outDir, "manifest.json");
     if (!fs.existsSync(manifestPath)) {
       warn(`\u274C Manifest not found at ${manifestPath}. Run generate first.`);
       return 1;
@@ -492,9 +1203,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) {
@@ -511,15 +1236,23 @@ ${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;
   }
 }
 async function runWatchLoop(invocation, resolved) {
-  const outDir = path.resolve(resolved.cwd, resolved.outDir);
-  const tmpDir = path.resolve(resolved.cwd, resolved.tmpDir);
-  const outName = path.basename(outDir).toLowerCase();
-  const tmpName = path.basename(tmpDir).toLowerCase();
+  const outDir = path2.resolve(resolved.cwd, resolved.outDir);
+  const tmpDir = path2.resolve(resolved.cwd, resolved.tmpDir);
+  const outName = path2.basename(outDir).toLowerCase();
+  const tmpName = path2.basename(tmpDir).toLowerCase();
   const isGenerated = (candidate) => candidate.toLowerCase().split(/[\\/]/).some(
     (segment) => segment === outName || segment === tmpName || segment.startsWith(`${outName}.backup-`)
   );
@@ -545,7 +1278,7 @@ async function runWatchLoop(invocation, resolved) {
   let timer = null;
   const watcher = fs.watch(resolved.cwd, { recursive: true }, (_event, filename) => {
     if (filename) {
-      const changed = path.resolve(resolved.cwd, filename.toString());
+      const changed = path2.resolve(resolved.cwd, filename.toString());
       if (isGenerated(changed)) return;
     }
     if (timer) clearTimeout(timer);