codebase-snapshot 0.9.0 → 0.9.4

package/CHANGELOG.md

@@ -4,6 +4,234 @@ All notable changes to `codebase-snapshot`.
 
 ---
 
+## A note on version numbers
+
+This package started its public life as `@ankurhalder/codebase-snapshot`, which reached 4.4.1. It
+moved to the unscoped name and **restarted at 0.9.0**, so the numbers below are not a continuation of
+the old line — `0.9.0` is newer than `4.4.1`, not older. 1.0.0 is reserved for when the CLI surface
+is settled.
+
+Two versions exist on the registry that are not releases, and both are deprecated:
+
+| Version | What it is |
+| :-- | :-- |
+| `codebase-snapshot@4.5.0` | Published for about an hour under the new name before the scheme was reset to 0.9.0. Withdrawn, never the supported version. |
+| `codebase-snapshot@0.0.0-stage` | npm's own staging placeholder, created automatically during the first publish of the name. Not a release. |
+
+Deleting them requires account-level rights that the release pipeline does not have, so they are
+deprecated with an explanatory message instead. `latest` has pointed at 0.9.0 since it existed.
+
+## 0.9.4
+
+### The snapshot is now something an agent can ask for
+
+`codebase-snapshot mcp` serves the repository over the Model Context Protocol on stdio. Seven
+tools, each answering one question an agent actually asks, and nothing that only looks useful:
+
+| Tool | Question |
+| :-- | :-- |
+| `snapshot_status` | Is there a snapshot here, and what does it cover? |
+| `snapshot_plan` | What *would* a generate at this budget include, and what would it drop? |
+| `snapshot_generate` | Build it. The only tool that writes. |
+| `snapshot_validate` | Is the context I was given still current? |
+| `snapshot_locate` | Which part holds this symbol, route or file? |
+| `snapshot_read` | Give me this window of this file. |
+| `snapshot_explain` | Why is this path missing? |
+
+Six are marked `readOnlyHint`, so clients can run them without a prompt; `snapshot_generate` is the
+only one that asks.
+
+### Both protocol eras, because they are not the same protocol
+
+Revision `2026-07-28` removed the `initialize` handshake: requests carry their protocol version and
+client capabilities in `_meta`, `server/discover` is mandatory, every result carries `resultType`,
+and `ping` no longer exists. Every client shipping today speaks the older handshake. The server
+answers whichever arrives first and never mixes them.
+
+The eras also disagree about an unsupported version, and getting it backwards breaks one while
+looking correct in the other: **legacy negotiates down** (the server answers with a revision it does
+speak), **modern rejects with `-32022`** and lists what it supports so the client can retry. Both
+paths have their own tests.
+
+### Zero dependencies, including the protocol
+
+`@modelcontextprotocol/sdk` is 4.5 MB unpacked with Express, Hono, Ajv, JOSE and Zod behind it. The
+transport here is newline-delimited JSON-RPC in about 400 readable lines, which keeps the package's
+single-dependency property intact and means the whole server can be audited in one sitting.
+
+### Reads come from the snapshot, never from the working tree
+
+`snapshot_read` extracts a file's section from the emitted part. That is why an excluded `.env`
+cannot be read back, a redacted credential stays redacted, and a large file returns the bounded
+preview the snapshot actually contains. The test asserts the strongest available property: the
+secret value appears in no artifact the server serves.
+
+### The contract does not lie about the server either
+
+`describe --format json` gained an `mcp` block — tools, arguments, prompts, resources, protocol
+versions — generated from the same objects the server serves. A test opens a live session, calls
+`tools/list`, and compares it against the CLI's output, so a tool that exists on one side and not the
+other fails the build.
+
+### Known limitation, measured rather than assumed
+
+Generation is synchronous. On this repository a `generate` takes **1.1 s**; on a synthetic
+3,000-file tree it takes **7.5 s**, during which the server answers nothing else. That is under every
+client's request timeout and well under a real monorepo's worth of files, so 0.9.4 runs it inline.
+The number is in the docs, and a worker thread is the next change if reports come back that clients
+time out.
+
+### Ships alongside
+
+- The README was cut from 2,311 to 1,814 tokens (measured by `readme-lint`, which counts URLs and
+  code blocks too). The narrative lost about a third of its length; the command table, the preset
+  names and the links stayed, because they are what a reader scans for.
+- A `codebase-snapshot/mcp` subpath so another tool can mount the server in-process.
+- `snapshot://` resources: the manifest, each part, the three reports, the contract and the skill,
+  plus `snapshot://parts/{index}` as a template.
+- Two prompts, `orient` and `keep-current`, both about order of operations rather than features.
+- `--cwd` is the only directory the server may read; a `root` argument can name a sub-directory of
+  it and nothing outside. `includeSensitiveFiles` is deliberately not a tool argument.
+
+It does not install packages, write a config file, speak HTTP, or fetch a remote repository.
+
+## 0.9.3
+
+### The project now says what it is
+
+Everything here already worked; none of it was visible. The pitch was "turn a repository into
+an LLM-ready snapshot", which is the pitch every packer uses, so the one thing that is actually
+ours — you can check the result — was buried in the fourth bullet of the second section.
+
+The line is now **a snapshot you can prove is current**, and the mark is a frame closing on a
+fingerprint. Both are consequences of the same idea rather than decoration: the artefact is
+bounded, it is identifiable, and it can be compared later.
+
+- **README**: a centred hero with the mark and the line, five badges, one command, and a
+  diagram that draws the argument — a dump that was silently truncated beside a snapshot with a
+  manifest and a validator. Nav links under the fold; the CLI reference moved to the site.
+- **Brand assets** in `docs/assets/`: mark in light and dark ink, a favicon that carries its own
+  plate so it survives both colour schemes, an iOS touch icon, and a 1200×630 social card. The
+  design tokens and the reason each variant exists are written down beside them.
+- **Two new pages**, both about problems we can name precisely: [stale LLM context is a
+  bug](docs/stale-context-is-your-bug.md) and [how many tokens a codebase
+  is](docs/codebase-token-budget.md).
+
+### The site stopped being invisible when shared
+
+Measured before the fix: twelve pages, every one declaring `twitter:card=summary_large_image`
+with **no `og:image` at all** — so every share on X, LinkedIn, Reddit, Slack or Discord rendered
+as a blank card — and no favicon anywhere.
+
+- `og:image`, `og:image:alt`, dimensions, `og:site_name`, `twitter:image`, an author, a theme
+  colour and a favicon set on every page.
+- Titles rewritten query-first instead of `<heading> — codebase-snapshot`, which spent the part
+  of a result a reader actually scans on a brand nobody is searching for yet.
+- Descriptions written by hand at 90–165 characters; they used to be the page's first sentence
+  cut mid-word at 158.
+- JSON-LD gains `BreadcrumbList` everywhere, `author` on every node, `sameAs` to npm and the
+  author's site, and an `image`.
+- `llms-full.txt`: every page in one file, one fetch for a crawler that wants the corpus.
+- The author's own site is now linked from every page (`rel="author"`), so the project hangs off
+  a person rather than a repository.
+
+### Two gates, because these defects survive builds
+
+`npm run verify` now fails if either is violated:
+
+- **`scripts/audit-site.mjs`** — title and description lengths, canonical identity, `og:image`
+  present *and* the file it names exists at 1200×630, twitter card, exactly one `<h1>`, alt text
+  on every image, parseable JSON-LD with a breadcrumb, favicon, sitemap coverage, and no page
+  that renders `undefined`.
+- **`scripts/readme-lint.mjs`** — a hero in the first lines, at least five badges, in-page
+  navigation, alt text, and every relative link resolving to a real file.
+
+### `snapshot` is the command now, and a first run sets the project up
+
+*(Prepared as 0.9.2, which was never published — everything in it ships here.)*
+
+Installing globally used to give `codebase-snapshot` plus a `snap` alias — a word that
+collides with Ubuntu's snapd and with an npm package of the same name. `snap` is gone and
+**`snapshot`** replaces it, pointing at the same file. The long name stays the canonical one, and
+the bare word is what a global install puts on `PATH`.
+
+The bare command is no longer a synonym for `generate`. In a project with no configuration it now
+recognises the project, says **what it keyed on** — `Detected nextjs` / `Because next.config.ts` —
+and offers the recommended setup in one keystroke: config, `.gitignore`, npm scripts,
+devDependency, install, generate. Or it walks through every setting, with each question starting
+on its answer, so pressing enter through the lot is the recommended setup spelled out. When
+nothing matches, it lists the manifests it looked for and asks which preset is closest.
+
+A project that already has a config, or that this tool generated before, skips all of it and just
+generates — nobody is walked through setup twice.
+
+**A first run never guesses.** With no terminal and no `--autopilot`, it exits `2` and names the
+three ways forward instead of generating with defaults nobody chose.
+
+```bash
+snapshot                    # guided first run, then generate
+snapshot --autopilot        # same, no questions
+npx codebase-snapshot       # same, from a project dependency
+```
+
+### New: `--autopilot`
+
+The whole setup with no prompts, from the default command: detect the preset, write the config and
+`.gitignore`, add the npm scripts and devDependency, install with the project's own package
+manager, then generate. It keeps an existing config, `--no-install` skips the install, and it
+refuses an empty directory (there is nothing to snapshot and nothing to install into).
+
+`--autopilot` and `setup` are one implementation with two entry points, so they cannot drift.
+`--autopilot --no-config` is a usage error: one writes a config, the other promises to ignore one.
+
+### Detection reports its evidence
+
+`detect()` returns the signal that fired instead of a boolean, so every preset can say why it
+matched — a filename, a dependency, a manifest line — and the setup prints it. A detection you
+cannot check is a detection you have to take on faith. The fallback preset is now explicit
+(`fallback: true`) rather than a detector that always returns true, which is what makes "I could
+not tell what this is" a state the tool can be in and report.
+
+### Other
+
+- `naming the command still means exactly that`: `snapshot generate` runs on the documented
+  defaults and writes nothing but the snapshot, as it always has.
+- The wizard's part-size question now starts on the preset's recommended budget instead of a fixed
+  120 KB, so a Next.js project no longer silently gets a third of the budget it was detected for.
+- `describe` and the bundled skill state the non-interactive rule, the two bin names, and that
+  `--autopilot` is the unattended path.
+
+---
+## 0.9.1
+
+### The documentation now derives its version from `package.json`
+
+A documented version is a promise about the release, and every one of them was hand-written — so they
+rotted silently at each bump. The README still described a `0.x` line whose numbers appeared nowhere
+in it, `SECURITY.md` advertised **"4.x supported"** on a project whose latest release was 0.9.0, and
+both `setup` examples printed `4.4.0` and `4.1.1` as the dependency the command adds.
+
+Versions now live in exactly one place, and `scripts/sync-docs.mjs` writes them into the documentation:
+
+- Prose carries marked spans — `<!--@majorMinor-->0.9<!--/@majorMinor-->` — which GitHub renders as
+  the value and hides as a comment.
+- Code-block examples are matched by shape instead, because inside a fence an HTML comment is literal
+  text and the marker syntax would leak into the page.
+- `npm run verify` fails when anything is out of step, and `npm run site` and `prepack` both sync
+  first, so the docs site and the published README cannot contradict the package they describe.
+
+Changelog history is deliberately excluded. It records what happened at each version, and rewriting a
+past entry would falsify that record rather than maintain it.
+
+### Other corrections in this pass
+
+- `SECURITY.md` supported versions: 0.9.x, with a sentence explaining why 0.9.0 is newer than 4.4.1.
+- The README states the pre-1.0 contract once, in wording that does not go stale.
+- The changelog opens with a note on the version numbering, so the registry's three versions are not
+  a mystery to anyone reading them.
+- The `v4.5.0` release and git tag were deleted; that version no longer exists on npm.
+
+---
 ## 0.9.0
 
 ### The package is now `codebase-snapshot`, unscoped
@@ -41,7 +269,7 @@ name on the next run, so an existing snapshot keeps working and is upgraded in p
 
 ### Documentation site
 
-The docs now have a crawlable home at <https://codebase-snapshot.ankurhalder.com>, generated from
+The docs now have a crawlable home at <https://ankurhalder.github.io/codebase-snapshot/>, generated from
 `README.md` and `docs/` in this repository, with a sitemap, its own `robots.txt`, an `llms.txt` at
 the site root and a Markdown twin per page. GitHub's `robots.txt` blocks directory-tree and raw-file
 paths and publishes no repository sitemap, so `docs/` had no crawlable entry point before this.

package/README.md

@@ -1,99 +1,114 @@
-# codebase-snapshot
+<div align="center">
+  <img src="https://raw.githubusercontent.com/ankurhalder/codebase-snapshot/main/docs/assets/favicon.svg" width="64" height="64" alt="codebase-snapshot">
 
-**Turn any repository into an LLM-ready snapshot: code packed into size-budgeted markdown
-parts, indexed by a JSON manifest, with a secret audit — in one command.**
+  <h1>codebase-snapshot</h1>
 
-[![npm version](https://img.shields.io/npm/v/codebase-snapshot.svg)](https://www.npmjs.com/package/codebase-snapshot)
-[![npm downloads](https://img.shields.io/npm/dw/codebase-snapshot.svg)](https://www.npmjs.com/package/codebase-snapshot)
-[![license](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/ankurhalder/codebase-snapshot/blob/main/LICENSE)
-[![node](https://img.shields.io/badge/node-%3E%3D18-brightgreen.svg)](https://nodejs.org)
+  <p><b>A snapshot you can prove is current.</b><br>
+  Plain-text parts under a hard byte budget, an index of every file and every skipped<br>
+  file with the reason, and a <code>validate</code> command that fails when the code moves.</p>
+
+  <p>
+    <a href="https://www.npmjs.com/package/codebase-snapshot"><img alt="npm version" src="https://img.shields.io/npm/v/codebase-snapshot.svg"></a>
+    <a href="https://www.npmjs.com/package/codebase-snapshot"><img alt="weekly downloads" src="https://img.shields.io/npm/dw/codebase-snapshot.svg"></a>
+    <a href="#license"><img alt="license: MIT" src="https://img.shields.io/badge/license-MIT-blue.svg"></a>
+    <a href="https://nodejs.org"><img alt="node: 18 or newer" src="https://img.shields.io/badge/node-%3E%3D18-brightgreen.svg"></a>
+    <a href="https://ankurhalder.github.io/codebase-snapshot/"><img alt="documentation" src="https://img.shields.io/badge/docs-read-1a7f37"></a>
+  </p>
+</div>
 
 ```bash
-npx codebase-snapshot generate
+snapshot                        # detects the project, sets it up, generates
+npx codebase-snapshot generate  # or no install at all, straight to the snapshot
 ```
 
-That writes `./snapshot/` — a directory you can drop into a chat, a prompt, a RAG pipeline or
-a repository review. It works on TypeScript and JavaScript projects, and on Python, Go, Rust,
-Java/Kotlin, C#/.NET, PHP, Ruby, C/C++, Vue, Svelte and Astro, without configuration.
+That writes `./snapshot/` — a directory you can drop into a chat, a prompt, a RAG pipeline or a
+repository review. TypeScript and JavaScript first, but also Python, Go, Rust, Java/Kotlin,
+C#/.NET, PHP, Ruby, C/C++, Vue, Svelte and Astro, without configuration.
+
+![Two ways to give a repository to a model: a dump that was silently truncated, and a snapshot
+with a manifest and a validator](https://raw.githubusercontent.com/ankurhalder/codebase-snapshot/main/docs/assets/how-it-works.svg)
 
-![How it works](https://raw.githubusercontent.com/ankurhalder/codebase-snapshot/main/docs/how-it-works.svg)
+<p align="center">
+  <a href="#install">Install</a> ·
+  <a href="#quick-start">Quick start</a> ·
+  <a href="#built-to-be-trusted">Trust</a> ·
+  <a href="#for-ai-agents">AI agents</a> ·
+  <a href="#documentation">Docs</a> ·
+  <a href="https://ankurhalder.github.io/codebase-snapshot/">Site</a>
+</p>
 
 ---
 
 ## Why
 
-Feeding a real repository to a model is awkward: files are too big, context windows are too
-small, and picking what matters by hand does not scale or repeat. `codebase-snapshot` does it
-deterministically:
+Feeding a real repository to a model is awkward: files are too big, context windows are too small,
+and choosing what matters by hand neither scales nor repeats. This does it deterministically.
 
-- **One file per part, never over budget.** `maxPartBytes` is a hard ceiling. A file bigger
-  than the budget is truncated with an explicit omission marker naming the budget rather than
-  blowing the limit — and above `largeFileBytes` it becomes a head/tail excerpt instead.
+- **A hard ceiling, not a target.** `maxPartBytes` is a limit. A file bigger than the budget is cut
+  with an explicit omission marker naming the budget, and above `largeFileBytes` it becomes a
+  head/tail excerpt instead — nothing silently overflows the window you sized.
 - **An index, not just text.** `manifest.json` lists every included file with its layer, kind,
-  language, part, hash and a structural summary — and every *excluded* file with the reason.
-- **Provably current.** `validate` re-hashes the repository against the snapshot and exits
-  non-zero on any drift, so a pipeline can gate on context being fresh.
-- **Deterministic where it matters.** Two runs over unchanged input give byte-identical
-  `parts/`, `reports/navigation.md` and `reports/project-tree.md`, and the same
-  `manifest.fingerprint`. Only `manifest.json`, the snapshot's `README.md`,
-  `reports/audit.md` and `.codebase-snapshot` change between runs, because they carry
-  timestamps, a run id and a pid.
-- **Safe by default.** Credential files are skipped unless asked for, secret-shaped strings are
-  redacted, and a mistyped output directory cannot delete source code.
-- **Usable by agents, not just humans.** A machine-readable contract and an installable skill
-  let an agent with no prior knowledge drive the whole thing.
+  language, part, hash and a structural summary, and every *excluded* file with the reason.
+- **Provably current.** `validate` re-hashes the repository against the snapshot and exits non-zero
+  on any drift, so a pipeline can gate on the context being fresh.
+- **Repeatable.** Two runs over unchanged input give byte-identical parts and the same
+  `manifest.fingerprint`; only the artifacts that carry a timestamp, run id or pid differ.
 
 ## Install
 
 ```bash
-npx codebase-snapshot generate      # no install, one-off
-npm install -D codebase-snapshot    # or add it to a project
+npm install -g codebase-snapshot      # puts `snapshot` on your PATH
+npx codebase-snapshot generate        # or no install at all, one-off
+npm install -D codebase-snapshot      # or add it to a project
 ```
 
-This is a **0.x** release. Version numbers follow semver's 0.x conventions, so the CLI surface may change in a minor release until 1.0.0 — pin an exact version if you need a fixed surface today.`n`nAny npm-compatible client works — npm, yarn (classic and Berry with strict PnP), pnpm and bun —
-each verified against the packed tarball before release. Requires **Node.js 18+**.
+`codebase-snapshot` is the canonical name to script against; `snapshot` is the short command a
+global install provides, and from a project dependency the same binary is `npx snapshot` or the
+`npm run snapshot` script `init` writes.
 
-Published from GitHub Actions with [build provenance](https://docs.npmjs.com/generating-provenance-statements): npm shows the tarball was built from this repository at a tagged commit, and `npm audit signatures` verifies it.
+Requires **Node.js 18+**. Any npm client works — npm, yarn (classic and Berry with strict PnP), pnpm
+and bun. Published from GitHub Actions with [build
+provenance](https://docs.npmjs.com/generating-provenance-statements), so `npm audit signatures`
+verifies the tarball came from this repository at a tagged commit.
+
+This is a **<!--@major-->0<!--/@major-->.x** release: the CLI surface may still change in a minor
+release until 1.0.0, so pin an exact version if you need a fixed surface today.
 
 → [Installation guide](https://github.com/ankurhalder/codebase-snapshot/blob/main/docs/install.md)
 
 ## Quick start
 
-One command does the whole first run — detects the project, writes a commented config, adds the
-npm scripts and the devDependency, installs it, and generates the snapshot:
+Type it. That is the whole first run.
 
 ```bash
-npx codebase-snapshot setup
+snapshot
 ```
 
+It recognises the project and says what it keyed on — `Detected nextjs` / `Because next.config.ts`
+— then offers the recommended setup in one keystroke, or a walk through every setting with each
+question starting on its default. Either way it writes the config, adds the npm scripts and the
+devDependency, installs with your package manager, and generates. A project that already has a
+config just generates.
+
+Nothing to press — CI, a container, an agent:
+
 ```bash
-# Or step by step, if you want to see each stage:
-npx codebase-snapshot init --yes   # config + scripts + devDependency + .gitignore
-npm install                                     # the package, into node_modules
-npm run snapshot                                # generate
-npm run snapshot:validate                       # exit 0 = current with disk
+npx codebase-snapshot --autopilot
 ```
 
-`setup` keeps a config the repository already has, and `setup --no-install` skips the install
-(CI, offline, or a lockfile you would rather not touch).
+**A first run never guesses.** With no terminal and no `--autopilot` it exits `2` and names the
+three ways forward, because a snapshot built from settings nobody chose is a snapshot nobody can
+check.
 
-```
-📸 Generating snapshot for: /Users/you/project
-   Branch: main | Part budget: 300 KB
-
-✅ Snapshot generated in 0.14s:
-   - Tracked files: 128
-   - Total lines:   9,431
-   - Total size:    0.41 MB
-   - Parts written: 3 under snapshot/parts/
-   - Reports:       snapshot/reports/ (project-tree, navigation, audit)
-   - Manifest:      snapshot/manifest.json
-   - Fingerprint:   e4607b570268c8def0911babbace97e4a0196d9eaf2cac22c8847500883d70aa
-   - Integrity:     passed
+```bash
+npx codebase-snapshot init --yes   # config + scripts + devDependency + .gitignore
+npm install                        # the package, into node_modules
+npm run snapshot                   # generate
+npm run snapshot:validate          # exit 0 = current with disk
 ```
 
-The fingerprint is printed in full — all 64 hex characters, never elided — and it is the same
-value as `manifest.fingerprint`.
+The fingerprint is printed in full — all 64 hex characters, never elided — and it is the same value
+as `manifest.fingerprint`.
 
 ## What you get
 
@@ -114,34 +129,29 @@ Every artifact can be turned off (`--skip-artifacts`, `--only-artifacts`, or the
 
 ## Built to be trusted with a whole repository
 
-A snapshot is only useful if you can believe it, so the tool is explicit about everything it does
-*not* contain:
+A snapshot is only useful if you can believe it, so the tool is explicit about what it does *not*
+contain.
 
 - **Nothing is dropped silently.** Every excluded path is recorded in `manifest.skipped[]` with a
-  reason — `binary`, `gitignore`, `default-ignore`, `sensitive-file`, `sensitive-path`, `symlink`,
-  `outside-root`, `read-error`, `not-file`, `nested-repository`, `excluded` — and `explain <path>`
-  answers the same question for any single path.
-- **Encoding is stated, not guessed.** UTF-16 files are transcoded instead of vanishing as
-  "binary"; a file that is not valid UTF-8 is kept but labelled `utf-8-lossy` with the count of
-  undecodable bytes, so you never mistake mojibake for source.
+  reason — `binary`, `gitignore`, `sensitive-file`, `symlink`, `read-error`, `excluded` and the
+  rest — and `explain <path>` answers the same question for any single file.
 - **Counts describe what was emitted.** `includedBytes` and `includedLines` are measured from the
-  block in the part, not from the file on disk.
+  block in the part, not from the file on disk. A file that is not valid UTF-8 is kept and labelled
+  `utf-8-lossy` rather than vanishing as "binary".
 - **Drift is checked, not assumed.** `validate` compares every file's hash *and* a digest of the
-  settings the snapshot was generated with, so a changed budget, layer rule or secret pattern is
-  drift rather than silence.
-- **Memory is bounded.** Files above 2 MB are not parsed for a structural summary (that is where a 50 MB file
-  used to reach 3 GB of resident memory), and 130 000 files in one directory or a 3 000-level path
-  scan without crashing.
-- **`diff` compares payloads, not just paths.** Two snapshots of identical sources with different
-  settings say so instead of reporting "0 changed".
-- **When git cannot list files** — an interrupted clone, a dehydrated `.git`, `safe.directory` —
-  the run refuses rather than quietly scanning something different, and `--discovery walk` is the
-  documented escape hatch.
+  settings the snapshot was generated with, so a changed budget or secret pattern is drift rather
+  than silence.
+- **The output directory is the tool's.** Each run is written to a scratch directory and swapped in
+  atomically, and it refuses to replace a directory it did not create — `--out-dir src` cannot
+  destroy source code.
+- **Credential files are excluded by default** — `.env`, `*.pem`, `.npmrc`, `id_rsa`, `*.tfstate`
+  and more — and secret-shaped strings inside ordinary files are redacted by masking only the
+  matched span, never the whole line.
 
 ## Supported projects
 
-25 presets, detected automatically from the repository — each contributing layers, kinds,
-ecosystem ignore patterns and a recommended part budget.
+25 presets, detected from the repository — each contributing layers, kinds, ecosystem ignore
+patterns and a recommended part budget.
 
 | | | | |
 | :--- | :--- | :--- | :--- |
@@ -153,11 +163,9 @@ ecosystem ignore patterns and a recommended part budget.
 | Laravel (PHP) | Rails (Ruby) | Terraform / Docker infra | Docs-only |
 | generic fallback | | | |
 
-Non-TypeScript languages get import/export/class/function summaries rather than being treated
-as opaque text. Vue, Svelte and Astro script blocks go through the real TypeScript compiler.
-Every summary is labelled `ast`, `structural` or `heuristic` so you know how much to trust it —
-Python, for example, is a line-scan `heuristic`, while JSON and Markdown get `structural`
-shapes.
+Non-TypeScript languages get import/export/class/function summaries rather than being treated as
+opaque text, and every summary is labelled `ast`, `structural` or `heuristic` so you know how much
+to trust it.
 
 → [Preset table and detection rules](https://github.com/ankurhalder/codebase-snapshot/blob/main/docs/configuration.md#project-presets)
 
@@ -165,7 +173,9 @@ shapes.
 
 | Command | Does |
 | :--- | :--- |
-| `generate` *(default)* | Write the snapshot. |
+| *(none)* | The guided first run. Asks once when the project has no config; generates otherwise. |
+| `generate` *(default)* | Write the snapshot. `--autopilot` sets the project up first, unasked. |
+| `setup` | Config, npm scripts, devDependency, install and generate, in one command. |
 | `validate` / `check` | Compare the snapshot with the repository; exit `1` on drift. |
 | `report` | Snapshot health, layer metrics, secret audit. |
 | `init` | Interactive (or `--yes`) setup that writes a self-documenting config. |
@@ -173,35 +183,39 @@ shapes.
 | `diff <a> <b>` | Compare two snapshots. |
 | `describe` | The machine-readable contract (`--format json`). |
 | `skill` | Print or install the agent skill. |
+| `mcp` | Serve the repository to an MCP client over stdio. |
 
-Exit codes: `0` success · `1` drift or refused generation · `2` usage error.
+Exit codes: `0` success · `1` drift, refused generation, or nothing to snapshot · `2` usage error,
+or a first run with no terminal and no `--autopilot`.
 
 → [Full CLI reference](https://github.com/ankurhalder/codebase-snapshot/blob/main/docs/cli.md)
 
 ## For AI agents
 
-Everything an agent needs is available as data, and the tool can install its own skill:
+Everything an agent needs is available as data, and the tool can install its own skill.
 
 ```bash
-# The contract: workflow, every option and default, exit codes, presets, safety rules
-npx codebase-snapshot describe --format json
-
-# Install the skill into the registries agent tools read: .claude/skills/, .cursor/rules/
-# (it adds those files to .gitignore, and never touches your own AGENTS.md)
-npx codebase-snapshot skill --install
+npx codebase-snapshot describe --format json   # contract: workflow, options, exit codes
+npx codebase-snapshot skill --install          # into .claude/skills + .cursor/rules
+npx -y codebase-snapshot@0.9.4 mcp             # or serve it over MCP
 ```
 
-An agent told only "use `npx codebase-snapshot`" can read the contract, follow its
-ordered workflow, and produce a validated snapshot unaided — that path is covered by a test.
+An agent told only "use `npx codebase-snapshot`" can read the contract, follow its ordered
+workflow, and produce a validated snapshot unaided — that path is covered by a test.
 
-→ [Using this with an AI agent](https://github.com/ankurhalder/codebase-snapshot/blob/main/docs/agent.md) · [AGENTS.md](https://github.com/ankurhalder/codebase-snapshot/blob/main/AGENTS.md) · [llms.txt](https://github.com/ankurhalder/codebase-snapshot/blob/main/llms.txt)
+The MCP server exposes seven tools — status, plan, generate, validate, locate, read, explain — plus
+`snapshot://` resources and two prompts. Its reads come from the snapshot rather than the working
+tree, so an excluded file stays excluded and a redacted value stays redacted, and
+`snapshot_validate` answers the question an agent otherwise cannot ask: is the context I was given
+still true?
+
+→ [Using this with an AI agent](https://github.com/ankurhalder/codebase-snapshot/blob/main/docs/agent.md) · [MCP server](https://github.com/ankurhalder/codebase-snapshot/blob/main/docs/mcp.md) · [AGENTS.md](https://github.com/ankurhalder/codebase-snapshot/blob/main/AGENTS.md) · [llms.txt](https://github.com/ankurhalder/codebase-snapshot/blob/main/llms.txt)
 
 ## Configuration
 
-`snapshot.config.ts` (or `.mjs`) is written by `init` with **every** setting at its current
-value, commented and grouped, so it doubles as the reference. Deleting any line is safe: the
-defaults are real. The object is exported through a name — `export default { … }` is
-`import/no-anonymous-default-export`, on by default in `eslint-config-next`.
+`snapshot.config.ts` (or `.mjs`) is written by `init` with **every** setting at its current value,
+commented and grouped, so it doubles as the reference. Deleting any line is safe: the defaults are
+real.
 
 ```js
 const config = {
@@ -230,8 +244,9 @@ const manifest = generateSnapshot(config);
 const validation = validateSnapshot(config);
 ```
 
-CommonJS works too (`require("codebase-snapshot")`), with type definitions for
-both. The CLI and the API share one implementation, so anything the CLI does is available here.
+CommonJS works too (`require("codebase-snapshot")`), with type definitions for both. The CLI, the
+API and the MCP server share one implementation, so anything one of them does is available in the
+others.
 
 ## Documentation
 
@@ -242,36 +257,35 @@ both. The CLI and the API share one implementation, so anything the CLI does is
 | [Configuration](https://github.com/ankurhalder/codebase-snapshot/blob/main/docs/configuration.md) | Every setting, all 25 presets, budgets, hooks, secrets |
 | [Snapshot output](https://github.com/ankurhalder/codebase-snapshot/blob/main/docs/output.md) | Directory layout and the full manifest schema |
 | [AI agents](https://github.com/ankurhalder/codebase-snapshot/blob/main/docs/agent.md) | The contract, the skill, what an agent should avoid |
+| [MCP server](https://github.com/ankurhalder/codebase-snapshot/blob/main/docs/mcp.md) | Seven tools, resources, both protocol eras |
 | [Troubleshooting](https://github.com/ankurhalder/codebase-snapshot/blob/main/docs/troubleshooting.md) | Every message and what to do about it |
 | [Changelog](https://github.com/ankurhalder/codebase-snapshot/blob/main/CHANGELOG.md) | Release history and breaking changes |
 
-## Guides
-
-| | |
-| :--- | :--- |
-| [Feeding a codebase to ChatGPT, Claude or Cursor](https://github.com/ankurhalder/codebase-snapshot/blob/main/docs/how-to-feed-a-repo-to-claude.md) | The full recipe, including the parts most guides skip |
-| [Budgeting LLM context](https://github.com/ankurhalder/codebase-snapshot/blob/main/docs/how-to-context-budget.md) | Choosing the numbers from the destination, not from taste |
-| [vs repomix](https://github.com/ankurhalder/codebase-snapshot/blob/main/docs/vs-repomix.md) | Including where repomix is the better choice |
-| [vs gitingest](https://github.com/ankurhalder/codebase-snapshot/blob/main/docs/vs-gitingest.md) | Including where gitingest is the better choice |
-| [vs code2prompt](https://github.com/ankurhalder/codebase-snapshot/blob/main/docs/vs-code2prompt.md) | Including where code2prompt is the better choice |
-
-## Safety
-
-- **Credential files are excluded by default** — `.env`, `*.pem`, `*.key`, `.npmrc`, `.netrc`,
-  `.git-credentials`, `id_rsa`, `.kube/config`, `*.tfstate` — and listed in
-  `manifest.skipped[]` with the reason.
-- **Secrets are redacted** inside ordinary files: only the matched span is masked, never the
-  whole line, and no excerpt reaches any artifact.
-- **The output directory is owned by the tool.** Each run is written to a scratch directory and
-  swapped in atomically; the previous snapshot survives a failure.
-- **It refuses to replace a directory it did not create**, so `--out-dir src` cannot destroy
-  source code.
+Guides: [feeding a codebase to ChatGPT, Claude or
+Cursor](https://github.com/ankurhalder/codebase-snapshot/blob/main/docs/how-to-feed-a-repo-to-claude.md)
+· [stale LLM context is a
+bug](https://github.com/ankurhalder/codebase-snapshot/blob/main/docs/stale-context-is-your-bug.md) ·
+[how many tokens a codebase
+is](https://github.com/ankurhalder/codebase-snapshot/blob/main/docs/codebase-token-budget.md) ·
+[budgeting a context
+window](https://github.com/ankurhalder/codebase-snapshot/blob/main/docs/how-to-context-budget.md) ·
+[vs repomix](https://github.com/ankurhalder/codebase-snapshot/blob/main/docs/vs-repomix.md) · [vs
+gitingest](https://github.com/ankurhalder/codebase-snapshot/blob/main/docs/vs-gitingest.md) · [vs
+code2prompt](https://github.com/ankurhalder/codebase-snapshot/blob/main/docs/vs-code2prompt.md)
 
 ## Contributing
 
-Issues and pull requests are welcome — see [CONTRIBUTING.md](https://github.com/ankurhalder/codebase-snapshot/blob/main/CONTRIBUTING.md) and the
-[code of conduct](https://github.com/ankurhalder/codebase-snapshot/blob/main/CODE_OF_CONDUCT.md). Security reports: [SECURITY.md](https://github.com/ankurhalder/codebase-snapshot/blob/main/SECURITY.md).
+Issues and pull requests are welcome — see
+[CONTRIBUTING.md](https://github.com/ankurhalder/codebase-snapshot/blob/main/CONTRIBUTING.md) and the
+[code of conduct](https://github.com/ankurhalder/codebase-snapshot/blob/main/CODE_OF_CONDUCT.md).
+Security reports: [SECURITY.md](https://github.com/ankurhalder/codebase-snapshot/blob/main/SECURITY.md).
 
 ## License
 
 [MIT](https://github.com/ankurhalder/codebase-snapshot/blob/main/LICENSE) © Ankur Halder
+
+<p align="center">
+  <sub>Built by <a href="https://ankurhalder.com" rel="author">Ankur Halder</a> ·
+  <a href="https://ankurhalder.github.io/codebase-snapshot/">documentation</a> ·
+  <a href="https://www.npmjs.com/package/codebase-snapshot">npm</a></sub>
+</p>

package/SECURITY.md

@@ -6,8 +6,12 @@ Only the latest published release receives security fixes.
 
 | Version | Supported |
 | :--- | :--- |
-| 4.x | ✅ |
-| 3.x and older | ❌ |
+| <!--@majorMinor-->0.9<!--/@majorMinor-->.x | ✅ |
+| anything older | ❌ |
+
+The number line restarted at 0.9.0 when the package moved to the unscoped `codebase-snapshot` name,
+so <!--@majorMinor-->0.9<!--/@majorMinor-->.x is newer than 4.4.1, not older. That is explained in full in the
+[changelog](CHANGELOG.md#a-note-on-version-numbers).
 
 ## Reporting a vulnerability