codebase-snapshot 0.9.0 → 0.9.4

package/docs/codebase-token-budget.md

@@ -0,0 +1,98 @@
+# How many tokens is a codebase?
+
+Before choosing a part budget, know the order of magnitude. A token is roughly 3.5–4 bytes of
+English prose; source code is denser, usually **3.3–3.7 bytes per token** because identifiers,
+punctuation and indentation tokenise less efficiently than words.
+
+The rule that survives contact with real repositories:
+
+```text
+tokens ≈ bytes / 3.5        ≈ lines × 11
+```
+
+## A measured example
+
+This repository, measured rather than estimated:
+
+| | |
+| :--- | ---: |
+| TypeScript files under `src/` | 57 |
+| Lines | 14,626 |
+| Bytes | 603,420 |
+| **Estimated tokens** | **≈ 165,000** |
+
+That single number decides the whole conversation. 165k tokens does not fit in an 8k window, it
+almost exactly fills a 200k window leaving nothing for the question or the answer, and it fits
+in a 1M window without effort.
+
+## What the default part budget means
+
+`maxPartBytes` defaults to **307,200 bytes (300 KB)** per part, which is roughly **84,000
+tokens**. If your model's window is 128k, one part plus a prompt and a reply fits, and the second
+part has to go in a separate conversation — which is exactly what the parts are for.
+
+| `maxPartBytes` | ≈ tokens per part | Fits comfortably in |
+| :--- | ---: | :--- |
+| `60k` | ≈ 16k | 32k windows, small chat prompts |
+| `120k` | ≈ 33k | 128k windows with room for a long answer |
+| `300k` (default) | ≈ 84k | 200k windows, one part per session |
+| `1mb` | ≈ 280k | 1M windows, or a summarising pass first |
+
+Set it from the destination, not from taste:
+
+```bash
+codebase-snapshot generate --max-part-bytes 120k
+```
+
+## Sizing the window, not just the code
+
+A window has to hold three things, and only the middle one is your snapshot:
+
+```text
+[ system prompt + instructions ] + [ snapshot parts ] + [ the answer ]
+```
+
+A rough allocation that works: **never spend more than 70% of the window on the snapshot**, and
+leave at least 8k tokens for the reply. On a 128k window that caps you at ~82k tokens of
+context — about one 300k-byte part.
+
+If you are re-reading several parts in one conversation, the sum is what matters, not the
+budget of any single part.
+
+## When the repository does not fit
+
+It usually does not. 165k tokens is a small library; a real application is five to twenty times
+that. In order of preference:
+
+1. **Scope the run, not the budget.** `include`/`exclude` patterns, or the wizard's "only
+   specific folders" option, cut more than any budget change. Packing the thing you are asking
+   about beats packing the repository.
+2. **Let the layers do the work.** The detected preset groups files into layers, and
+   `reports/navigation.md` maps every file to the part it landed in — read the index, open one
+   part, instead of feeding everything.
+3. **Raise the budget and lower the count.** One 300k part is easier to reason about than six
+   60k parts, and cheaper in prompt overhead.
+4. **Summarise once, in a separate session.** Ask the model for a map of the parts, then use that
+   map to choose which parts to read in detail.
+
+What not to do: silently truncate. A snapshot never exceeds its budget — a file too large for
+the remaining space is cut with an explicit omission marker that names the budget, and above
+`largeFileBytes` it becomes a head/tail excerpt rather than a full body.
+
+## Checking your own number
+
+The manifest records what was actually written, so you never have to guess:
+
+```bash
+codebase-snapshot report --format json \
+  | jq '{files: .manifest.counts.totalFiles, bytes: .manifest.counts.totalSizeBytes, parts: .manifest.counts.partsCount}'
+```
+
+`totalSizeBytes / 3.5` is your token estimate for the run. If it is far from the window you
+intended to fill, the budget was not the problem — the selection was.
+
+## Related
+
+- [Budgeting LLM context](how-to-context-budget.md) — choosing ceilings per layer
+- [Feeding a repo to an LLM](how-to-feed-a-repo-to-claude.md) — the end-to-end recipe
+- [Configuration](configuration.md) — `maxPartBytes`, `largeFileBytes`, `maxMonolithBytes`

package/docs/configuration.md

@@ -139,6 +139,12 @@ not mistaken for a Node library.
 | `docs` | 22 | ≥ 3 markdown files and no `package.json` | 100k | `.docusaurus`, `.vitepress/dist`, `site` |
 | `generic` | 0 | anything else | 120k | — |
 
+Each detector reports **the signal that fired**, not just a verdict: `next.config.ts`, `depends on
+express`, `django in pyproject.toml`. The first run prints it — `Detected nextjs` / `Because
+next.config.ts` — so a detection can be checked rather than taken on faith. `generic` is the
+fallback, reached only when no detector matched, and the first run says so instead of pretending it
+recognised the project.
+
 A preset contributes layers, kinds, ignores and a recommended budget — what `init` writes as
 `maxPartBytes`. Force one when detection is wrong:
 
@@ -403,8 +409,12 @@ preset's figure only takes effect once `init` has written it into a config.
 npx codebase-snapshot init
 ```
 
-Walks every tunable parameter, showing the detected value as the default. Every prompt has a
-flag, so the same setup works non-interactively:
+Walks every tunable parameter, showing the detected value as the default — press `enter` through
+the lot and you get the recommended configuration.
+
+The bare `snapshot` command starts the same wizard when the project has no config, but asks one
+question first: take the recommended setup in a single keystroke, walk through each setting, or pick
+a different preset. Every prompt has a flag, so the same setup works non-interactively:
 
 ```bash
 npx codebase-snapshot init --yes

package/docs/how-to-feed-a-repo-to-claude.md

@@ -27,12 +27,14 @@ Everything below runs locally.
 
 ```bash
 cd /path/to/your/project
-npx codebase-snapshot setup
+snapshot                 # installed globally: one word, and it asks once
+npx codebase-snapshot setup   # or from a checkout with no global install
 ```
 
 `setup` detects the project type from the repository, writes a commented `snapshot.config.mjs`, adds
 the npm scripts and the devDependency, installs it, and generates. It does not overwrite a config you
-already have. Use `--no-install` if you would rather not touch the lockfile.
+already have. Use `--no-install` if you would rather not touch the lockfile. `npx codebase-snapshot
+--autopilot` does the same thing with no questions at all, which is what you want in CI.
 
 If you prefer to see each stage:
 

package/docs/install.md

@@ -8,31 +8,55 @@ Requires **Node.js 18 or newer**.
 ## One command
 
 ```bash
-npx codebase-snapshot setup
+npx codebase-snapshot --autopilot
 ```
 
 Detects the project, writes the config (an existing one is kept), adds the npm scripts and the
 devDependency, installs them with the package manager your lockfile names, and generates the first
-snapshot. `--no-install` skips the install; `--dry-run` writes nothing. The sections below are the
-same steps taken one at a time.
+snapshot. `--no-install` skips the install; `--dry-run` writes nothing. `setup` does the same as a
+command word, and the bare `snapshot` (or `npx codebase-snapshot` with no arguments) does the
+same after one question — see [the first run](#the-first-run). The sections below are the same
+steps taken one at a time.
+
+## The first run
+
+With the package installed globally, the whole thing is one word:
+
+```bash
+snapshot
+```
+
+In a project with no configuration it names what it recognised and what it keyed on
+(`Detected nextjs` / `Because next.config.ts`), then offers the recommended setup in one
+keystroke or a walk through each setting with the defaults pre-filled. It writes the config,
+adds the npm scripts and devDependency, installs, and generates.
+
+In a project that already has a config — or one it has generated before — the same command just
+generates, so nobody is walked through setup twice.
+
+**It never guesses.** With no terminal (CI, a container, an agent) a first run exits `2` and
+names the three ways forward instead of generating with settings nobody chose. `--autopilot` is
+the answer for unattended use; naming the command (`npx codebase-snapshot generate`) is the
+other, and it runs on the documented defaults exactly as before.
+
 ## One-off use
 
 ```bash
 npx codebase-snapshot generate
 ```
 
-This is the shortest path and needs no install. The command is also available as
-`codebase-snapshot` and, once installed, as the short alias `snap`.
+This is the shortest path and needs no install.
 
-Pin the version when you need the same build on every machine:
+Pin the version when you need the same build on every machine. `--version` prints the exact
+string to pin:
 
 ```bash
 npx codebase-snapshot@latest generate
-npx codebase-snapshot@0.9.0 generate
+npx codebase-snapshot --version
 ```
 
 **Why the bare name works.** npm resolves which binary to run from the package's `bin`
-entries. This package declares `codebase-snapshot` and `snap` pointing at the *same file*, so
+entries. This package declares `codebase-snapshot` and `snapshot` pointing at the *same file*, so
 npm treats them as aliases and can always resolve one. Keep them aliases: two *different*
 executables under a scoped package name would make the bare form unresolvable.
 
@@ -57,8 +81,9 @@ Then run it through your client so the binary resolves from the project:
 | pnpm | `pnpm exec codebase-snapshot generate` |
 | bun | `bun run codebase-snapshot generate` |
 
-`snap` works everywhere `codebase-snapshot` does. Adding it to `package.json` scripts is the
-most reproducible option:
+`snapshot` works everywhere `codebase-snapshot` does — `npx snapshot` from a project dependency,
+`pnpm exec snapshot`, `yarn snapshot`, and the bare word after a global install. Adding the script
+to `package.json` is the most reproducible option:
 
 ```json
 {
@@ -129,6 +154,8 @@ preset, and JSON configs are parsed rather than executed. See
 npm install -g codebase-snapshot
 ```
 
+This is what puts the short `snapshot` command on your `PATH`.
+
 Convenient, but prefer pinning per project: snapshots are only reproducible if the generator
 version is. A global install also shadows `npx` for this package — npm will run your global
 copy instead of the published one, which is confusing when the two differ. That is exactly
@@ -156,7 +183,8 @@ A snapshot written by **3.0.0 or earlier** is refused rather than replaced: its
 the directory. Delete the old snapshot directory and generate again.
 
 See [CHANGELOG](../CHANGELOG.md) for breaking changes — 3.0.0 removed nothing, but it briefly
-did in error; 4.0.0 restored the `snap` alias.
+did in error; 4.0.0 restored the `snap` alias, and 0.9.2 replaced that alias with `snapshot`
+when the version line was restarted.
 
 ## Uninstalling
 

package/docs/mcp.md

@@ -0,0 +1,149 @@
+# Run codebase-snapshot as an MCP server
+
+`codebase-snapshot mcp` serves a repository to any [Model Context Protocol](https://modelcontextprotocol.io)
+client over stdio. It is one command, no configuration, and it is the snapshot — not a directory
+walk — that the client sees.
+
+> Available from **0.9.4**. Run `npx codebase-snapshot --version` before wiring a client; anything
+> older does not have the `mcp` command.
+
+## Start it
+
+```bash
+npx -y codebase-snapshot@0.9.4 mcp
+```
+
+The server serves the directory it was started in. `--cwd <path>` points it elsewhere, and that
+directory is the only one it will read.
+
+A client needs two things: the command `npx` and the arguments above. The surrounding
+configuration shape belongs to the client — the example below is the `mcpServers` form used by
+Claude Desktop and Cursor:
+
+```json
+{
+  "mcpServers": {
+    "codebase-snapshot": {
+      "command": "npx",
+      "args": ["-y", "codebase-snapshot@0.9.4", "mcp", "--cwd", "/absolute/path/to/repo"]
+    }
+  }
+}
+```
+
+Claude Code registers the same thing from a shell:
+
+```bash
+claude mcp add codebase-snapshot -- npx -y codebase-snapshot@0.9.4 mcp --cwd /absolute/path/to/repo
+```
+
+On Windows, wrap the command as `cmd /c npx` with the same arguments — `npx` is a `.cmd` shim
+there, and clients that spawn without a shell cannot execute it directly.
+
+## The seven tools
+
+| Tool | Answers | Writes |
+| :-- | :-- | :-- |
+| `snapshot_status` | Is there a snapshot, when was it built, what does it cover? | no |
+| `snapshot_plan` | What would a generate at this budget include, and what would it leave out? | no |
+| `snapshot_generate` | Build it. | yes |
+| `snapshot_validate` | Is the context the agent was given still current? | no |
+| `snapshot_locate` | Which part holds this symbol, route or file? | no |
+| `snapshot_read` | A window of one file, as the snapshot contains it. | no |
+| `snapshot_explain` | Why is this path not in the snapshot? | no |
+
+Six are declared `readOnlyHint`, which most clients use to run them without asking. Only
+`snapshot_generate` prompts.
+
+`snapshot_locate` is the one that makes the others usable: a twelve-part snapshot is hundreds of
+kilobytes, and asking "which part holds authentication?" is cheaper than reading all twelve. It
+searches the manifest's index — file paths, exported symbols, component names, routes, layers and
+kinds — and returns the part each match lives in.
+
+`snapshot_read` is windowed on purpose. It defaults to 200 lines and reports `nextFromLine` when
+more remains, so an agent continues deliberately instead of pulling a whole part into a context
+window it has not budgeted.
+
+## Resources
+
+Resources are the browse surface; tools are the act surface.
+
+| URI | Contents |
+| :-- | :-- |
+| `snapshot://manifest` | Every included file with layer, kind, part and hash, plus every skip reason |
+| `snapshot://parts/{index}` | One budgeted part, by 1-based index |
+| `snapshot://reports/audit` | Secret findings, large files, parse diagnostics |
+| `snapshot://reports/tree` | The directory tree of included files |
+| `snapshot://reports/navigation` | File-to-part lookup |
+| `snapshot://contract` | The machine-readable CLI contract |
+| `snapshot://skill` | The agent skill, as one read |
+
+Part resources carry their size in the description, so a client choosing between them can see that
+one is 300 kB before attaching it.
+
+## Prompts
+
+Two, both about order of operations rather than features: `orient` maps the repository before
+anything is read, and `keep-current` validates before trusting earlier context and again after
+making changes.
+
+## What it will not do
+
+- **Read outside its root.** `--cwd` is the only directory that is readable. A `root` argument can
+  name a sub-directory of it and nothing else; symlinks are resolved before the check.
+- **Emit a sensitive file.** `.env`, `*.pem` and the rest stay out, and `includeSensitiveFiles` is
+  not a tool argument — a prompt cannot ask for it. Reads come from the emitted snapshot, so
+  redaction applies to everything the client sees.
+- **Install or configure.** `snapshot_generate` writes the snapshot directory and nothing else. It
+  never runs a package manager and never writes a config file.
+- **Touch the network.** The server makes no outbound connections, and there is no HTTP transport.
+
+## Both protocol eras
+
+Revision `2026-07-28` removed the handshake that every client in use today still performs. The
+server speaks both and answers whichever arrives first.
+
+| Era | Revisions | Opening move |
+| :-- | :-- | :-- |
+| Legacy | `2025-11-25`, `2025-06-18` | `initialize`, then `notifications/initialized` |
+| Modern | `2026-07-28` | `server/discover`, or `_meta` on every request |
+
+The two disagree about an unsupported version, and the difference is observable: a legacy client is
+negotiated *down* to a revision the server speaks, while a modern client receives `-32022` with the
+list of supported revisions so it can retry.
+
+## Why there is no SDK
+
+`@modelcontextprotocol/sdk` is 4.5 MB unpacked and brings Express, Hono, Ajv, JOSE and Zod with it.
+The transport here is newline-delimited JSON-RPC, which is roughly 400 lines of readable code, and
+the package's only runtime dependency remains `typescript`. The parity test — a live `tools/list`
+compared against `describe --format json` — is what keeps the protocol implementation honest, not
+the presence of a library.
+
+## Performance
+
+Generation is synchronous, so a tool call blocks the server for its duration. Both numbers are
+measured, not estimated:
+
+| Repository | Files | `snapshot_generate` |
+| :-- | --: | --: |
+| This project | 127 | 1.1 s |
+| A synthetic tree | 3,000 | 7.5 s |
+
+Both are under any client's request timeout. If a repository large enough to exceed yours shows up,
+`snapshot_plan` gives the same numbers without writing, and the fix — moving generation to a worker
+thread — is tracked rather than assumed.
+
+## Troubleshooting
+
+**The client lists no tools.** The server writes JSON-RPC to stdout and nothing else; every note goes
+to stderr. Check the client's server log — the first line says which directory is being served.
+
+**`Unknown tool` or a missing command.** The published version is older than 0.9.4. Pin the exact
+version in the client arguments.
+
+**`Unknown resource` for a part.** Resources are computed from the manifest, so nothing but the
+static set exists before the first generate. Call `snapshot_status`, then `snapshot_generate`.
+
+**A file is missing from `snapshot_locate`.** It is excluded, and `snapshot_explain` will name the
+reason — an ignore rule, the preset, a sensitive-file pattern, or your own config.

package/docs/stale-context-is-your-bug.md

@@ -0,0 +1,118 @@
+# Stale LLM context is a bug
+
+A snapshot is a copy. The code keeps moving. Nothing in the copy says so, and nothing in the
+model can notice.
+
+That is the whole failure mode: you hand a model a faithful description of your repository on
+Monday, change four files on Wednesday, and on Thursday ask about a function you have already
+deleted. The answer is confident, plausible and about a repository that no longer exists.
+
+```text
+you ──▶ snapshot (Monday) ──▶ model ──▶ answer about Monday's code
+             code moves (Wednesday) ────┘
+```
+
+There is no error message, because nothing failed. The model did exactly what it was given.
+
+## Why "just regenerate it" is not a control
+
+Regenerating is cheap — it takes a second. The problem is that you have to *know* to do it, and
+nobody notices a stale snapshot until an answer is wrong. A habit is not a guard, and a README
+line that says "re-run this before asking" is a habit.
+
+What you need is not more discipline. It is a comparison that can fail.
+
+## Three things that make drift visible
+
+### 1. An identity for the copy
+
+Every run writes `manifest.fingerprint`, a hash of what was included, derived from the content
+of every file. Two repositories that differ by one byte have different fingerprints; two runs
+over the same tree on different machines have the same one.
+
+```bash
+codebase-snapshot report --format json | jq -r .manifest.fingerprint
+```
+
+Quote that value wherever the snapshot is used — in the prompt, in the PR description, in the
+ticket. It turns "the snapshot we sent" into a value that can be compared later.
+
+### 2. A comparison you can run
+
+`validate` re-scans the repository, re-hashes each file the snapshot claims to contain, and
+compares. It exits `1` when the code has moved, and `0` when the snapshot still describes what
+is on disk.
+
+```bash
+codebase-snapshot validate
+```
+
+```text
+✖ Snapshot does not match the repository:
+   - modified: src/parser/partition.ts
+   - added:    src/presets/evidence.ts
+   - removed:  src/legacy/old-partitioner.ts
+```
+
+That is the difference between a copy and an artefact. A copy is trusted; an artefact is
+checked.
+
+### 3. A record of what was left out
+
+`manifest.skipped[]` names every path the snapshot did not include, with a reason for each:
+
+| Reason | Meaning |
+| :--- | :--- |
+| `gitignore` | the repository's own rules excluded it |
+| `default-ignore` | `node_modules`, build output, VCS metadata |
+| `sensitive-file` | `.env`, `*.pem`, `.npmrc` — excluded unless explicitly requested |
+| `binary` | not text, so not useful as context |
+| `outside-root` | a symlink pointing out of the repository |
+| `nested-repository` | a submodule or nested checkout |
+| `read-error` | it could not be read, and the run says so instead of dropping it quietly |
+
+When an answer is wrong because the model never saw a file, this is the list that tells you
+whether the file was excluded on purpose or by accident.
+
+## Gate it
+
+The comparison is only a guard if something runs it. In CI, after whatever changes the tree:
+
+```yaml
+- name: Snapshot is still current
+  run: npx codebase-snapshot validate
+```
+
+A failure means the context you are about to rely on describes a different repository. Whether
+that blocks the pipeline or just warns is a policy question; having it at all is not.
+
+The same gate works for a long-running agent: run `validate` before a session that will read
+the snapshot, and regenerate when it fails.
+
+## What this does not tell you
+
+Worth being precise about the limits, because "validate" sounds like more than it is:
+
+- **It compares files, not meaning.** A refactor that preserves every byte proves nothing is
+  wrong — correctly, because nothing is.
+- **It cannot see what the model did with the text.** A current snapshot can still be
+  misunderstood, summarised badly, or ignored.
+- **It says nothing about whether the snapshot was a good selection.** Use `explain <path>` to
+  see why one path was included or skipped, and `report` for the shape of the whole run.
+- **It does not follow history.** If you keep three snapshots from three branches, each one
+  validates against the branch it was generated from.
+
+## When this is overkill
+
+If you generate a snapshot, paste it into a chat, and throw it away in the same hour, you do not
+need any of this — `snapshot` alone is the right amount of ceremony.
+
+The controls start to pay for themselves the moment a snapshot outlives the session that made
+it: a checked-in context directory, a scheduled job, a review bot, an agent that runs for days,
+or a team where the person who generated the snapshot is not the person who reads it.
+
+## Related
+
+- [Budgeting LLM context](how-to-context-budget.md) — choosing a part size that fits the window
+- [Snapshot output](output.md) — the manifest fields this page refers to
+- [CLI reference](cli.md#validate--check) — `validate` in full

package/docs/troubleshooting.md

@@ -49,6 +49,9 @@ column is in the [CLI reference](cli.md#options).
 | Message | Fix |
 | :--- | :--- |
 | `Unknown command "frobnicate". Expected one of: …` | Use one of the commands in the [CLI reference](cli.md). |
+| `No configuration found in … and this session is not interactive, so nothing was generated.` | A first run and no terminal to ask its question. Nothing is wrong with the repository: say which setup you want — `--autopilot` for the full setup, `init --yes` then `generate` for the steps, or `generate` for the documented defaults. See [the first run](cli.md#the-first-run). |
+| `--autopilot sets a project up and writes a config; --no-config ignores config files. Pass one or the other.` | The two flags contradict each other. Drop one. |
+| `--no-install only applies to \`setup\`, or to \`generate --autopilot\`.` | The install only happens during a setup. Drop the flag, or add `--autopilot`. |
 | `--preset does not apply to \`generate\` and was not applied. It is accepted by: \`init\`. To scope a run, set include/excludePatterns/preset in snapshot.config.ts (or run \`codebase-snapshot init\` to generate one).` | `--preset`, `--include`, `--exclude`, `--yes` and `--force` configure `init`, which writes them into the config. Set them at generation time in `snapshot.config.ts` instead. |
 | `--install does not apply to \`generate\` and was not applied. It is accepted by: \`skill\`.` | `--install` and `--target` configure `skill` only. |
 | `--cwd directory does not exist: …` / `--cwd is not a directory: …` | Point `--cwd` at an existing repository directory. |
@@ -171,6 +174,16 @@ The output paths are unsafe: `outDir` or `tmpDir` is the working directory, an a
 filesystem root, or they contain one another. The message prints the resolved paths so you
 can see why. Use a subdirectory.
 
+### `Nothing to snapshot: … has no files.`
+
+```
+❌ Nothing to snapshot: this directory has no files. Run this inside the repository you want to snapshot, or pass --cwd.
+```
+
+The directory is empty apart from `.git` (or `.hg`, `.svn`, `.DS_Store`, `Thumbs.db`). Setting the
+project up would install a devDependency and add scripts for a repository with nothing in it, so
+`--autopilot` refuses too. Run the command from the repository, or point `--cwd` at it.
+
 ### Budget errors
 
 A budget set in a **config file** exits `1`, and names the setting as you wrote it:

package/docs/vs-repomix.md

@@ -29,7 +29,7 @@ If you want the most popular, most integrated tool: **use repomix.**
 | Reproducible output | Parts are byte-identical across runs; a fingerprint covers them | Content is stable; no published determinism guarantee |
 | Staleness check | `validate` re-hashes the repository and exits non-zero on drift | Not a feature |
 | Remote repositories | No — operates on a local checkout | **Yes** — packs a GitHub URL directly |
-| MCP server | No (planned) | **Yes** |
+| MCP server | **Yes** — seven tools over stdio, and it serves the validated snapshot rather than the working tree | **Yes** — packs a repository, including by URL |
 | Secret handling | 30 default rules, value-span masking, per-line audit table | Secretlint integration |
 | Language awareness | 25 presets, AST or structural summaries labelled by confidence | Tree-sitter parsing with a compression mode |
 | Adoption | New | **Mature** — large user base, many integrations |
@@ -41,7 +41,9 @@ If you want the most popular, most integrated tool: **use repomix.**
   repomix is built around that workflow.
 - **You need a remote URL.** `repomix --remote https://github.com/owner/repo` works without a clone.
   This project has no equivalent.
-- **You want MCP.** repomix ships an MCP server today; this project does not, yet.
+- **You want MCP against a remote URL.** repomix's server can pack a repository by URL. This one
+  serves a local checkout, and refuses to read outside it. Both ship a server; ours is narrower on
+  purpose, and it can tell the agent whether the snapshot it is reading is still current.
 - **You want the ecosystem.** More stars, more tutorials, more people who have already hit your
   problem.
 - **You are packing something enormous and prefer compression to budgets.** repomix's tree-sitter

package/package.json

@@ -1,28 +1,31 @@
 {
   "name": "codebase-snapshot",
-  "version": "0.9.0",
-  "description": "Turn a codebase into token-efficient, size-budgeted Markdown parts for an LLM: an AST partitioner, snapshot generator, secret auditor and drift validator for ChatGPT, Claude and Cursor.",
+  "version": "0.9.4",
+  "description": "Pack a codebase for an LLM into budgeted Markdown parts, with a manifest of every file and skip, and validate to prove the snapshot is current.",
   "keywords": [
     "codebase",
     "snapshot",
     "llm",
-    "ai",
-    "context",
+    "claude",
+    "chatgpt",
+    "cursor",
     "context-window",
-    "context-engineering",
-    "codebase-snapshot",
-    "codebase-to-prompt",
     "repo-to-llm",
+    "codebase-to-prompt",
     "markdown",
-    "prompt-engineering",
+    "token-efficiency",
+    "context-engineering",
     "ai-agents",
-    "claude",
-    "cursor",
+    "mcp",
+    "model-context-protocol",
+    "mcp-server",
+    "prompt-engineering",
     "partitioner",
     "ast",
+    "codebase-packer",
     "code-analysis",
-    "token-efficiency",
-    "codebase-packer"
+    "ai",
+    "codebase-snapshot"
   ],
   "author": "Ankur Halder <ankur.halder12345@gmail.com>",
   "license": "MIT",
@@ -44,7 +47,7 @@
   "sideEffects": false,
   "bin": {
     "codebase-snapshot": "./dist/bin.js",
-    "snap": "./dist/bin.js"
+    "snapshot": "./dist/bin.js"
   },
   "exports": {
     ".": {
@@ -67,6 +70,16 @@
         "default": "./dist/cli.cjs"
       }
     },
+    "./mcp": {
+      "import": {
+        "types": "./dist/mcp.d.ts",
+        "default": "./dist/mcp.js"
+      },
+      "require": {
+        "types": "./dist/mcp.d.cts",
+        "default": "./dist/mcp.cjs"
+      }
+    },
     "./package.json": "./package.json"
   },
   "files": [
@@ -91,11 +104,14 @@
     "test:coverage": "node --test --experimental-test-coverage tests/*.test.js",
     "prepublishOnly": "npm run build",
     "publish:create": "npm publish packages/create --access public",
-    "prepack": "npm run build",
+    "prepack": "npm run sync-docs && npm run build",
     "pack-check": "node scripts/pack-check.mjs",
-    "site": "node scripts/build-site.mjs",
+    "sync-docs": "node scripts/sync-docs.mjs",
+    "site": "npm run sync-docs && node scripts/build-site.mjs",
+    "audit-site": "node scripts/audit-site.mjs",
+    "readme-lint": "node scripts/readme-lint.mjs",
     "seo-rank": "node scripts/seo-rank.mjs",
-    "verify": "npm run check && npm run pack-check"
+    "verify": "npm run check && npm run sync-docs -- --check && npm run site && npm run audit-site && npm run readme-lint && npm run pack-check"
   },
   "dependencies": {
     "typescript": "^5.0.0"