@ankurhalder/codebase-snapshot 2.2.0 → 3.0.0

package/README.md

@@ -54,9 +54,9 @@ npx @ankurhalder/codebase-snapshot init --preset react-vite --max-part-bytes 120
 - **TypeScript AST extraction** — directives, imports, exports (including `export *` and anonymous
   defaults), functions, classes, interfaces, types, enums, components, hooks, and route handlers.
 - **Structured summaries** — JSON key shapes and Markdown headings, computed from redacted text.
-- **Built for AI agents** — `snap describe --format json` returns a machine-readable
+- **Built for AI agents** — `codebase-snapshot describe --format json` returns a machine-readable
   contract (workflow, every option and default, exit codes, presets, safety rules), and
-  `snap skill --install` writes the bundled agent skill into `AGENTS.md`,
+  `codebase-snapshot skill --install` writes the bundled agent skill into `AGENTS.md`,
   `.claude/skills/` and `.cursor/rules/` so a zero-context agent discovers the tool
   automatically. See [docs/agent.md](docs/agent.md).
 - **Zero-config presets** — auto-detects Next.js, Vite, Node/Express/Nest, and plain TypeScript.
@@ -122,8 +122,9 @@ npx @ankurhalder/codebase-snapshot@latest generate     # write ./snapshot/
 npx @ankurhalder/codebase-snapshot@latest validate     # exit 0 = matches disk
 ```
 
-Pin the tag (`@latest` or `@2`): a bare scoped spec can resolve to a placeholder manifest
-with no executable on some npm builds and exit 0 printing nothing.
+The bare form works too — `npx @ankurhalder/codebase-snapshot generate` — because the
+package ships exactly one executable, which is what lets npm resolve it. Pin `@latest`
+(or `@3`) when you need the same build on every machine.
 
 Details, including the contract schema and the skill's install targets, are in
 [docs/agent.md](docs/agent.md).
@@ -134,7 +135,7 @@ Details, including the contract schema and the skill's install targets, are in
 
 ```bash
 codebase-snapshot [command] [options]
-snap [command] [options]
+codebase-snapshot [command] [options]
 ```
 
 Every option accepts both `--opt value` and `--opt=value`. Human-readable progress goes to **stderr**;

package/dist/bin.js

@@ -4576,7 +4576,7 @@ function validateSnapshot(configInput) {
 
 // src/index.ts
 var GENERATOR_NAME = "@ankurhalder/codebase-snapshot";
-var GENERATOR_VERSION = "2.2.0";
+var GENERATOR_VERSION = "3.0.0";
 var SCHEMA_VERSION = "3.0.0";
 function sha256Hex2(input) {
   return crypto3.createHash("sha256").update(input).digest("hex");
@@ -5237,11 +5237,12 @@ function buildAgentContract() {
     requires: { node: ">=18.0.0", dependencies: ["typescript"] },
     invocation: {
       oneShot: `npx ${PACKAGE_NAME}@latest`,
-      installed: "npx snap",
-      bins: ["snap", "codebase-snapshot"],
+      installed: "npx codebase-snapshot",
+      bins: ["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.",
+        `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."
       ]
     },
@@ -5251,7 +5252,7 @@ function buildAgentContract() {
         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`."
+        notes: "If it prints nothing, clear the npm cache and retry, or use `npx -p <pkg> codebase-snapshot`."
       },
       {
         step: 2,
@@ -5564,8 +5565,8 @@ function buildAgentContract() {
     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 ...`
+        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'",
@@ -5621,10 +5622,10 @@ another model, and reading files one by one would not fit in context.
 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.
+**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
 
@@ -5833,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
@@ -6020,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).`
       );
     }
   }

package/dist/{chunk-5I564BGX.js → chunk-5B4UVQLR.js}

@@ -4536,7 +4536,7 @@ async function runInit(options) {
 
 // src/index.ts
 var GENERATOR_NAME = "@ankurhalder/codebase-snapshot";
-var GENERATOR_VERSION = "2.2.0";
+var GENERATOR_VERSION = "3.0.0";
 var SCHEMA_VERSION = "3.0.0";
 function sha256Hex2(input) {
   return crypto.createHash("sha256").update(input).digest("hex");
@@ -5113,5 +5113,5 @@ async function generateSnapshotAsync(configInput, options) {
 }
 
 export { ARTIFACT_NAMES, DEFAULT_ANSWERS, DEFAULT_SECRET_PATTERNS, GENERATOR_NAME, GENERATOR_VERSION, LANGUAGE_PROFILES, MIN_MAX_PART_BYTES, PRESETS, PromptCancelled, SCHEMA_VERSION, anchorForPath, assertReplaceable, assertUsableConfigInput, collectFiles, compareManifests, countLines, defineConfig, detectLanguage, detectPreset, explainPath, fenceForContent, generateProjectTree, generateSnapshot, generateSnapshotAsync, getPreset, globToRegExp, isBinaryBuffer, isBinaryExtension, isBinaryFile, isInteractive, isResolvedConfig, isSensitivePath, listPresetNames, loadConfigFile, loadConfigFileDetailed, loadManifest, markResolvedConfig, matchRule, matchesExclude, normalizeResolvedConfig, parseByteSize, partitionFiles, profileForPath, renderConfig, renderDiffText, renderExplainText, renderMinimalConfig, renumberParts, resolveConfig, resolveSafeOutputDirs, runInit, scanAndRedactSecrets, stripJsonComments, summarizeJson, summarizeMarkdown, summarizeTypeScriptSource, summarizeWithProfile, supportsTypeScriptImports, truncatePreview, truncateToBytes, unknownPresetMessage, validateSnapshot };
-//# sourceMappingURL=chunk-5I564BGX.js.map
-//# sourceMappingURL=chunk-5I564BGX.js.map
+//# sourceMappingURL=chunk-5B4UVQLR.js.map
+//# sourceMappingURL=chunk-5B4UVQLR.js.map

package/dist/cli.cjs

@@ -4555,7 +4555,7 @@ function validateSnapshot(configInput) {
 
 // src/index.ts
 var GENERATOR_NAME = "@ankurhalder/codebase-snapshot";
-var GENERATOR_VERSION = "2.2.0";
+var GENERATOR_VERSION = "3.0.0";
 var SCHEMA_VERSION = "3.0.0";
 function sha256Hex2(input) {
   return crypto__namespace.createHash("sha256").update(input).digest("hex");
@@ -5216,11 +5216,12 @@ function buildAgentContract() {
     requires: { node: ">=18.0.0", dependencies: ["typescript"] },
     invocation: {
       oneShot: `npx ${PACKAGE_NAME}@latest`,
-      installed: "npx snap",
-      bins: ["snap", "codebase-snapshot"],
+      installed: "npx codebase-snapshot",
+      bins: ["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.",
+        `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."
       ]
     },
@@ -5230,7 +5231,7 @@ function buildAgentContract() {
         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`."
+        notes: "If it prints nothing, clear the npm cache and retry, or use `npx -p <pkg> codebase-snapshot`."
       },
       {
         step: 2,
@@ -5543,8 +5544,8 @@ function buildAgentContract() {
     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 ...`
+        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'",
@@ -5596,10 +5597,10 @@ another model, and reading files one by one would not fit in context.
 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.
+**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
 
@@ -5808,7 +5809,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
@@ -6007,7 +6007,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).`
       );
     }
   }

package/dist/cli.js

@@ -1,4 +1,4 @@
-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 { parseByteSize, GENERATOR_VERSION, ARTIFACT_NAMES, getPreset, unknownPresetMessage, MIN_MAX_PART_BYTES, loadConfigFileDetailed, resolveConfig, validateSnapshot, explainPath, compareManifests, loadManifest, renderDiffText, generateSnapshot, GENERATOR_NAME, runInit, PromptCancelled, SCHEMA_VERSION, PRESETS, renderExplainText } from './chunk-5B4UVQLR.js';
 import * as fs from 'fs';
 import * as path2 from 'path';
 import { parseArgs } from 'util';
@@ -91,11 +91,12 @@ function buildAgentContract() {
     requires: { node: ">=18.0.0", dependencies: ["typescript"] },
     invocation: {
       oneShot: `npx ${PACKAGE_NAME}@latest`,
-      installed: "npx snap",
-      bins: ["snap", "codebase-snapshot"],
+      installed: "npx codebase-snapshot",
+      bins: ["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.",
+        `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."
       ]
     },
@@ -105,7 +106,7 @@ function buildAgentContract() {
         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`."
+        notes: "If it prints nothing, clear the npm cache and retry, or use `npx -p <pkg> codebase-snapshot`."
       },
       {
         step: 2,
@@ -418,8 +419,8 @@ function buildAgentContract() {
     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 ...`
+        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'",
@@ -471,10 +472,10 @@ another model, and reading files one by one would not fit in context.
 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.
+**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
 
@@ -683,7 +684,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
@@ -882,7 +882,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).`
       );
     }
   }

package/dist/index.cjs

@@ -4565,7 +4565,7 @@ async function runInit(options) {
 
 // src/index.ts
 var GENERATOR_NAME = "@ankurhalder/codebase-snapshot";
-var GENERATOR_VERSION = "2.2.0";
+var GENERATOR_VERSION = "3.0.0";
 var SCHEMA_VERSION = "3.0.0";
 function sha256Hex2(input) {
   return crypto__namespace.createHash("sha256").update(input).digest("hex");

package/dist/index.d.cts

@@ -497,7 +497,7 @@ declare function matchesExclude(relativePath: string, pattern: string): boolean;
 declare function collectFiles(cwd: string, options?: CollectOptions): CollectResult;
 
 declare const GENERATOR_NAME = "@ankurhalder/codebase-snapshot";
-declare const GENERATOR_VERSION = "2.2.0";
+declare const GENERATOR_VERSION = "3.0.0";
 declare const SCHEMA_VERSION = "3.0.0";
 interface GenerateOptions {
     /** Compute the full manifest but write nothing to disk. */

package/dist/index.d.ts

@@ -497,7 +497,7 @@ declare function matchesExclude(relativePath: string, pattern: string): boolean;
 declare function collectFiles(cwd: string, options?: CollectOptions): CollectResult;
 
 declare const GENERATOR_NAME = "@ankurhalder/codebase-snapshot";
-declare const GENERATOR_VERSION = "2.2.0";
+declare const GENERATOR_VERSION = "3.0.0";
 declare const SCHEMA_VERSION = "3.0.0";
 interface GenerateOptions {
     /** Compute the full manifest but write nothing to disk. */

package/dist/index.js

@@ -1,3 +1,3 @@
-export { ARTIFACT_NAMES, DEFAULT_ANSWERS, DEFAULT_SECRET_PATTERNS, GENERATOR_NAME, GENERATOR_VERSION, LANGUAGE_PROFILES, MIN_MAX_PART_BYTES, PRESETS, PromptCancelled, SCHEMA_VERSION, anchorForPath, assertReplaceable, assertUsableConfigInput, collectFiles, compareManifests, countLines, defineConfig, detectLanguage, detectPreset, explainPath, fenceForContent, generateProjectTree, generateSnapshot, generateSnapshotAsync, getPreset, globToRegExp, isBinaryBuffer, isBinaryExtension, isBinaryFile, isInteractive, isResolvedConfig, isSensitivePath, listPresetNames, loadConfigFile, loadConfigFileDetailed, loadManifest, markResolvedConfig, matchRule, matchesExclude, normalizeResolvedConfig, parseByteSize, partitionFiles, profileForPath, renderConfig, renderDiffText, renderExplainText, renderMinimalConfig, renumberParts, resolveConfig, resolveSafeOutputDirs, runInit, scanAndRedactSecrets, stripJsonComments, summarizeJson, summarizeMarkdown, summarizeTypeScriptSource, summarizeWithProfile, supportsTypeScriptImports, truncatePreview, truncateToBytes, validateSnapshot } from './chunk-5I564BGX.js';
+export { ARTIFACT_NAMES, DEFAULT_ANSWERS, DEFAULT_SECRET_PATTERNS, GENERATOR_NAME, GENERATOR_VERSION, LANGUAGE_PROFILES, MIN_MAX_PART_BYTES, PRESETS, PromptCancelled, SCHEMA_VERSION, anchorForPath, assertReplaceable, assertUsableConfigInput, collectFiles, compareManifests, countLines, defineConfig, detectLanguage, detectPreset, explainPath, fenceForContent, generateProjectTree, generateSnapshot, generateSnapshotAsync, getPreset, globToRegExp, isBinaryBuffer, isBinaryExtension, isBinaryFile, isInteractive, isResolvedConfig, isSensitivePath, listPresetNames, loadConfigFile, loadConfigFileDetailed, loadManifest, markResolvedConfig, matchRule, matchesExclude, normalizeResolvedConfig, parseByteSize, partitionFiles, profileForPath, renderConfig, renderDiffText, renderExplainText, renderMinimalConfig, renumberParts, resolveConfig, resolveSafeOutputDirs, runInit, scanAndRedactSecrets, stripJsonComments, summarizeJson, summarizeMarkdown, summarizeTypeScriptSource, summarizeWithProfile, supportsTypeScriptImports, truncatePreview, truncateToBytes, validateSnapshot } from './chunk-5B4UVQLR.js';
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/docs/agent.md

@@ -60,7 +60,7 @@ between `<!-- codebase-snapshot:skill:start -->` and
 `<!-- codebase-snapshot:skill:end -->`, so an `AGENTS.md` that already documents your
 conventions keeps them. `--format json` reports what was created, updated or unchanged.
 
-`snap init` prints a reminder about this; it never installs the skill on its own.
+`codebase-snapshot init` prints a reminder about this; it never installs the skill on its own.
 
 ## Why both a contract and a skill
 

package/docs/configuration.md

@@ -256,7 +256,7 @@ marker written before any artifact, not by the set of filenames present, so
 custom artifacts never look like someone else's data.
 
 Note that a hook runs in the **process** working directory, so with
-`snap --cwd elsewhere` a relative path resolves against your shell's directory,
+`codebase-snapshot --cwd elsewhere` a relative path resolves against your shell's directory,
 not the target repo. Use the absolute paths on `manifest` (or resolve against
 `outDir` yourself) when passing `--cwd`.
 
@@ -276,7 +276,7 @@ not the target repo. Use the absolute paths on `manifest` (or resolve against
 ## `explain`
 
 ```
-$ snap explain src/app/page.tsx
+$ codebase-snapshot explain src/app/page.tsx
 
 src/app/page.tsx
 
@@ -293,7 +293,7 @@ src/app/page.tsx
 Excluded paths say why:
 
 ```
-$ snap explain .env
+$ codebase-snapshot explain .env
 
 .env
 
@@ -308,7 +308,7 @@ same data as an object.
 ## `diff`
 
 ```
-$ snap diff old-snapshot new-snapshot
+$ codebase-snapshot diff old-snapshot new-snapshot
 
 before  2026-11-03T10:00:00.000Z  812 file(s), 4 part(s)
 after   2026-11-03T11:30:00.000Z  820 file(s), 4 part(s)

package/docs/install.md

@@ -12,24 +12,27 @@ Requires **Node.js 18 or newer**.
 npx @ankurhalder/codebase-snapshot generate
 ```
 
-If that exits with **no output and no error** instead of generating, your npm has
-resolved the bare spec to a placeholder manifest that carries no executable — npm creates
-a `0.0.0-stage` placeholder version during staged publishing, and some npm builds pick it
-when no version is given. Pin the version or the tag and it works:
+Pin the version when you need the same build on every machine:
 
 ```bash
 npx @ankurhalder/codebase-snapshot@latest generate
-npx @ankurhalder/codebase-snapshot@2 generate
+npx @ankurhalder/codebase-snapshot@3 generate
 ```
 
+The bare form works because this package ships **exactly one executable**
+(`codebase-snapshot`). That is deliberate: npm resolves which binary to run by matching the
+typed command against the package's `bin` keys, and no key can contain an `@scope/`, so a
+scoped package with several executables cannot be run by its bare name. If a command ever
+exits with no output, clear the npm cache and retry — see troubleshooting.
+
 `npx -p @ankurhalder/codebase-snapshot codebase-snapshot generate`, `pnpm dlx`,
-`yarn dlx` and `bunx` are unaffected. A normal `npm install -D` followed by `npx snap`
-is unaffected too, and is the more reproducible choice for a project.
+`yarn dlx` and `bunx` are equivalent. A normal `npm install -D` followed by
+`npx codebase-snapshot` is the more reproducible choice for a project.
 
 Equivalent one-liners for other clients:
 
 ```bash
-yarn dlx -p @ankurhalder/codebase-snapshot snap generate   # yarn Berry
+yarn dlx -p @ankurhalder/codebase-snapshot codebase-snapshot generate   # yarn Berry
 yarn global add @ankurhalder/codebase-snapshot             # yarn classic (installs globally)
 pnpm dlx @ankurhalder/codebase-snapshot generate
 bunx @ankurhalder/codebase-snapshot generate
@@ -47,13 +50,13 @@ bun add -d @ankurhalder/codebase-snapshot
 Then run it through your client so it resolves from the project's `node_modules`:
 
 ```bash
-npx snap generate
-yarn snap generate
-pnpm exec snap generate
-bun run snap generate
+npx codebase-snapshot generate
+yarn codebase-snapshot generate
+pnpm exec codebase-snapshot generate
+bun run codebase-snapshot generate
 ```
 
-Both `snap` and `codebase-snapshot` are exposed as binaries — pick whichever you prefer.
+Both `codebase-snapshot` and `codebase-snapshot` are exposed as binaries — pick whichever you prefer.
 
 Adding it to `package.json` scripts works the same everywhere:
 
@@ -82,23 +85,23 @@ if the generator version is reproducible.
 
 ```bash
 npx @ankurhalder/codebase-snapshot@2 generate
-pnpm dlx @ankurhalder/codebase-snapshot@2.2.0 generate
+pnpm dlx @ankurhalder/codebase-snapshot@3.0.0 generate
 ```
 
 ## Verified clients
 
 Every client below was used to install the published package and run
-`snap --version` successfully. This matrix is enforced in CI
+`codebase-snapshot --version` successfully. This matrix is enforced in CI
 (`.github/workflows/ci.yml` → `client-install`), so a change that breaks a client fails
 the build rather than a user's terminal.
 
 | Client | Version tested | Run installed binary with |
 | :--- | :--- | :--- |
-| npm | 10.x | `npx snap` |
-| yarn (classic) | 1.22.22 | `yarn snap` |
-| yarn (Berry, `nodeLinker: pnp`) | 4.6.0 | `yarn snap` |
-| pnpm | 10.28.0 | `pnpm exec snap` |
-| bun | 1.4.4 | `bun run snap` |
+| npm | 10.x | `npx codebase-snapshot` |
+| yarn (classic) | 1.22.22 | `yarn codebase-snapshot` |
+| yarn (Berry, `nodeLinker: pnp`) | 4.6.0 | `yarn codebase-snapshot` |
+| pnpm | 10.28.0 | `pnpm exec codebase-snapshot` |
+| bun | 1.4.4 | `bun run codebase-snapshot` |
 
 Yarn Berry's default **strict PnP** mode works: there is no `node_modules` directory, and
 the runtime `typescript` dependency still resolves through yarn's `.pnp.cjs` loader.
@@ -125,9 +128,9 @@ Snapshots already written to `snapshot/` are ordinary files and are left alone.
 
 ## Troubleshooting
 
-**`snap: command not found`** — when installed locally (not globally), the binary lives
+**`codebase-snapshot: command not found`** — when installed locally (not globally), the binary lives
 in `node_modules/.bin` and is only on your `PATH` inside a package script or a client
-runner. Use `npx snap`, `pnpm exec snap`, `yarn snap`, or `bun run snap`.
+runner. Use `npx codebase-snapshot`, `pnpm exec codebase-snapshot`, `yarn codebase-snapshot`, or `bun run codebase-snapshot`.
 
 **`Cannot find module 'typescript'`** — the package declares `typescript` as a runtime
 dependency for AST analysis. If your client prunes or externalizes it (some bundlers and
@@ -136,14 +139,14 @@ dependency for AST analysis. If your client prunes or externalizes it (some bund
 **CI has no Node** — that is not supported yet; this package is JavaScript and needs a
 Node runtime. See the future-work note above.
 
-**`yarn snap` prints extra lines, or breaks a script that parses output** — yarn classic
+**`yarn codebase-snapshot` prints extra lines, or breaks a script that parses output** — yarn classic
 wraps everything: it echoes `yarn run 1.22.22`, the resolved command, your tool's output,
 and a `Done in 0.37s.` trailer. For a human that is harmless; for anything that parses
-`snap`'s stdout it is not. In scripts and CI, call the binary directly:
+`codebase-snapshot`'s stdout it is not. In scripts and CI, call the binary directly:
 
 ```bash
-./node_modules/.bin/snap generate
-npx snap generate          # same, without the yarn wrapper
+./node_modules/.bin/codebase-snapshot generate
+npx codebase-snapshot generate          # same, without the yarn wrapper
 ```
 
 This is why the CI job in this repository reads the version from a line that *is* the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ankurhalder/codebase-snapshot",
-  "version": "2.2.0",
+  "version": "3.0.0",
   "description": "Production-grade LLM codebase snapshot generator, auditor, and AST partitioner",
   "keywords": [
     "codebase",
@@ -32,8 +32,7 @@
   "types": "./dist/index.d.ts",
   "sideEffects": false,
   "bin": {
-    "codebase-snapshot": "./dist/bin.js",
-    "snap": "./dist/bin.js"
+    "codebase-snapshot": "./dist/bin.js"
   },
   "exports": {
     ".": {