codebase-snapshot 0.0.0-stage → 0.9.0

package/docs/configuration.md

@@ -0,0 +1,424 @@
+# Configuration reference
+
+Every setting, every default, and what each one changes. For commands and options see the
+[CLI reference](cli.md).
+
+Nothing here is required: with no config at all the tool runs on the defaults below.
+
+## Contents
+
+- [Config files](#config-files)
+- [Scoping: which files get in](#scoping-which-files-get-in)
+- [Project presets](#project-presets)
+- [Classification: layers and kinds](#classification-layers-and-kinds)
+- [Sizing: byte budgets](#sizing-byte-budgets)
+- [Artifacts: what gets written](#artifacts-what-gets-written)
+- [Secrets: redaction](#secrets-redaction)
+- [Output directories](#output-directories)
+- [Hooks](#hooks)
+- [Complete example](#complete-example)
+- [Interactive setup](#interactive-setup)
+
+## Config files
+
+The first match wins:
+
+```
+snapshot.config.ts
+snapshot.config.js
+snapshot.config.mjs
+snapshot.config.cjs
+snapshot.config.json
+.snapshotrc / .snapshotrc.json
+package.json → "snapshot"
+```
+
+`snapshot.config.json` accepts comments. `package.json`'s `"snapshot"` key is read only when
+no dedicated config file exists, and it must be an object (a wrong type is a warning, since
+other tools use that key too).
+
+The extension decides how the file is loaded. `.cjs` is always CommonJS and must use
+`module.exports`; `.mjs` and `.ts` are always ESM and must use `export default`. `.js` follows
+the package's `type` field — `module` means ESM, `commonjs` means CommonJS; with no `type`
+Node decides by detecting the syntax, so `export default` works on current Node but is not
+portable to versions without detection. Getting it wrong is the `Could not load …` error
+above, not a silent fallback.
+
+A config file that exists but cannot be parsed is a **hard error** (exit `1`, nothing
+written). Silently ignoring it would produce a snapshot with none of your settings.
+
+A `.ts` config needs Node ≥ 22.6 **and** an ES-module project, because Node applies the
+package's `type` field to a `.ts` file. `codebase-snapshot init` picks the right filename for
+the project — `.ts` when both conditions hold, `.mjs` otherwise — and writes a plain object
+with no imports so it loads even when the package is only used through `npx`.
+
+The snippets below show an `export default { … }` object for brevity. `init` writes it as
+`const config = { … }; export default config;` because the anonymous form is reported by
+`import/no-anonymous-default-export`, which `eslint-config-next` enables by default — both load
+identically, so use whichever keeps your linter quiet.
+
+CLI flags override the config for a single run (`--max-part-bytes`, `--out-dir`, …).
+`--no-config` goes further and ignores every config file, so the run uses the built-in
+defaults and the project's detected preset. A code config is executed when it is loaded, so
+`--no-config` is also the way to snapshot a repository whose config you do not want to run —
+see [the trust boundary](../SECURITY.md#trust-boundary).
+
+## Scoping: which files get in
+
+```js
+export default {
+  include: [],                    // allow-list; empty means "everything"
+  excludePatterns: [],            // extra excludes, applied on top of the preset's
+  discovery: "auto",              // "auto" | "git" | "walk" — how files are found
+};
+```
+
+- `include` is an allow-list of globs. When non-empty, only matching files are considered.
+- `exclude` is accepted as an alias of `excludePatterns` and means the same thing; the resolved
+  config always records it under `excludePatterns`.
+- `excludePatterns` removes files everywhere. Presets contribute their own ecosystem ignores
+  on top; those are not removable, only addable to.
+- `discovery` chooses how the file list is produced, and is recorded in `manifest.config`, so
+  changing it shows up as config drift:
+  - `"auto"` (default) — list through `git ls-files` when git can do it; if a `.git` directory
+    exists but git cannot list the files, refuse rather than silently switch methods.
+  - `"git"` — require git; a directory without a usable repository is an error.
+  - `"walk"` — scan the tree and read `.gitignore` files directly (nested ones included), still
+    skipping credential files. Use it when a `.git` directory cannot be listed. It cannot
+    reproduce git's own ignore sources (`.git/info/exclude`, your global `core.excludesFile`),
+    git's inclusion of files that are tracked although a `.gitignore` now matches them, or its
+    treatment of a submodule as a single entry. The same setting is available per run as
+    [`--discovery`](cli.md#options).
+
+Built-in ignores always apply: `.git`, `node_modules`, `.next`, `dist`, `build`, lockfiles,
+minified assets and binaries. Sensitive files are handled separately (see
+[Secrets](#secrets-redaction)).
+
+Every path the scanner discovers is recorded in `manifest.skipped[]` with the reason and the
+rule that matched — nothing it sees is dropped silently, including a `.gitignore`d path in a
+repository where git does the filtering. See the [`skipped[]`
+reasons](output.md#skipped). To debug one path:
+
+```bash
+npx codebase-snapshot explain src/some/file.ts
+```
+
+## Project presets
+
+Detection reads the repository **once** and picks the highest-priority match, so a Next.js
+app inside a pnpm workspace is still `nextjs`, not `monorepo`. `peerDependencies` and
+`optionalDependencies` count as dependencies. A bare `package.json` ranks below any
+definitive language manifest, so a Go or Rust repository with a `package.json` for tooling is
+not mistaken for a Node library.
+
+| Preset | Priority | Detected from | Budget | Ecosystem ignores |
+| :--- | ---: | :--- | :--- | :--- |
+| `nextjs` | 100 | `next.config.*`, or `next` | 300k | `.svelte-kit`, `.astro`, `.vite`, `.output` |
+| `nuxt` | 98 | `nuxt.config.*`, or `nuxt` | 200k | `.nuxt`, `.output` |
+| `sveltekit` | 96 | `svelte.config.*`, `@sveltejs/kit` | 200k | `.svelte-kit`, `.vercel` |
+| `remix` | 94 | `@remix-run/*` | 200k | `.cache`, `public/build` |
+| `astro` | 92 | `astro.config.*`, `astro` | 150k | `.astro`, `dist` |
+| `angular` | 90 | `angular.json`, `@angular/core` | 200k | `.angular`, `dist` |
+| `solid` | 88 | `solid-js`, `solid-start` | 120k | `.solid`, `dist` |
+| `vue-vite` | 86 | `vue` + `vite`/`vite.config.*` | 120k | `.vite`, `dist` |
+| `react-vite` | 84 | `react` + `vite`/`vite.config.*` | 120k | `.vite`, `dist` |
+| `nest` | 80 | `@nestjs/core` | 200k | `dist`, `node_modules` |
+| `node-express` | 78 | `express`, `fastify`, `koa`, `@hapi/hapi` | 200k | `dist` |
+| `monorepo` | 70 | `pnpm-workspace.yaml`, `nx.json`, `turbo.json`, `lerna.json`, `"workspaces"` | 200k | `.turbo`, `.nx` |
+| `python-django` | 56 | `manage.py`, django in `pyproject.toml`/`requirements.txt` | 150k | `__pycache__`, `.venv`, `venv`, `.mypy_cache`, `.pytest_cache`, `.tox`, `.eggs`, `staticfiles`, `media` |
+| `python-fastapi` | 54 | fastapi or flask in `pyproject.toml`/`requirements.txt` | 150k | `__pycache__`, `.venv`, `venv`, `.mypy_cache`, `.pytest_cache`, `.tox`, `.eggs` |
+| `go` | 50 | `go.mod` | 200k | `vendor`, `testdata` |
+| `rust` | 48 | `Cargo.toml` | 200k | `target` |
+| `java-spring` | 46 | `pom.xml`, `build.gradle`, `build.gradle.kts` | 200k | `.gradle`, `out`, `target` |
+| `node-lib` | 45 | any `package.json` | 120k | `dist` |
+| `dotnet` | 44 | `*.csproj`, `*.sln`, `global.json` | 200k | `bin`, `obj`, `.vs` |
+| `php-laravel` | 42 | `artisan`, laravel in `composer.json`, `composer.json` | 150k | `vendor`, `storage`, `bootstrap/cache`, `public/build` |
+| `ruby-rails` | 40 | `Gemfile`, `config.ru`, `Rakefile` | 150k | `.bundle`, `log`, `tmp`, `vendor/bundle`, `public/assets` |
+| `python-lib` | 30 | `pyproject.toml`, `setup.py`, `requirements.txt`, `.py` files | 120k | `__pycache__`, `.venv`, `venv`, `.mypy_cache`, `.pytest_cache`, `.tox`, `.eggs` |
+| `infra` | 24 | `*.tf`, `Chart.yaml`, `kustomization.yaml`, `docker-compose.yml` | 100k | `.terraform`, `.terragrunt-cache` |
+| `docs` | 22 | ≥ 3 markdown files and no `package.json` | 100k | `.docusaurus`, `.vitepress/dist`, `site` |
+| `generic` | 0 | anything else | 120k | — |
+
+A preset contributes layers, kinds, ignores and a recommended budget — what `init` writes as
+`maxPartBytes`. Force one when detection is wrong:
+
+```js
+export default { preset: "react-vite" };
+```
+
+An unknown name is an error listing every valid preset, never a silent fallback. The resolved
+preset is recorded in `manifest.config.preset`, so changing it shows up as config drift.
+
+## Classification: layers and kinds
+
+Layers group files (roughly directories), kinds label their role. Both are first-match-wins
+with `other` as the fallback, and both accept a glob string, a `RegExp`, or a function.
+
+```js
+export default {
+  layersMode: "merge",         // "merge" (default) or "replace"
+  layers: [
+    { name: "api", match: "src/api/**" },
+    { name: "ui", match: /\.(tsx|vue|svelte)$/ },
+  ],
+  kinds: [
+    { kind: "route", match: /(^|\/)route\.tsx?$/ },
+    { kind: "hook", match: "src/hooks/**" },
+  ],
+};
+```
+
+A layer rule is `{ name, match }` and a kind rule is `{ kind, match }`. The label key is
+different in each, and a row that gets it wrong is rejected rather than silently ignored, so
+copy the shapes above.
+
+- `layersMode: "merge"` keeps the preset's rules and lets yours win by being evaluated first.
+- `layersMode: "replace"` discards the preset's rules entirely.
+
+Classification drives per-layer budgets and the `Layers:` breakdown in `report`.
+
+## Sizing: byte budgets
+
+```js
+export default {
+  maxPartBytes: "300k",        // hard ceiling per part; default 307200, minimum 4096
+  largeFileBytes: "200k",      // above this a file becomes a head/tail preview
+  previewHeadLines: 80,
+  previewTailLines: 40,
+  budgets: {                   // optional per-layer overrides
+    default: "120k",
+    byLayer: { docs: 40_000, core: 300_000 },
+  },
+};
+```
+
+Sizes accept bytes (`307200`), `"120k"`, `"1.5mb"`, and spaces (`"120 k"`). Zero and negative
+values are errors; so is anything below 4096 — a part budget that small cannot hold a header,
+let alone code.
+
+The budget is a hard ceiling: a part never exceeds it. A single file larger than the budget is
+not split mid-file — it becomes a head/tail preview, marked `isPreviewTruncated`.
+
+`budgets.byLayer` lets expensive layers get more room than generated docs, for example.
+
+## Artifacts: what gets written
+
+```js
+export default {
+  artifacts: {
+    readme: true,          // snapshot/README.md
+    manifest: true,        // snapshot/manifest.json
+    parts: true,           // snapshot/parts/*.md
+    navigation: true,      // snapshot/reports/navigation.md
+    projectTree: true,     // snapshot/reports/project-tree.md
+    audit: true,           // snapshot/reports/audit.md
+    monolith: false,       // full-codebase.json + full-codebase.md
+  },
+};
+```
+
+Everything except `monolith` is on by default; `monolith` follows `includeMonolith`. Turn
+artifacts off with the config, `--skip-artifacts a,b`, or `--only-artifacts a,b` (the two
+cannot be combined).
+
+Two combinations warn because they produce a snapshot that contradicts itself: `manifest` off
+means `validate` and `report` cannot inspect the snapshot, and `parts` off with `navigation`
+on leaves links pointing at files that were never written. Both are allowed.
+
+The `.codebase-snapshot` ownership marker is always written, whatever the selection.
+
+See [Snapshot output](output.md) for the layout and the manifest schema.
+
+## Secrets: redaction
+
+```js
+export default {
+  secrets: {
+    customPatterns: [
+      { rule: "github-pat", pattern: /ghp_[A-Za-z0-9]{36}/ },
+      { rule: "internal-token", pattern: /CORP-[A-Z0-9]{32}/ },
+    ],
+    disableDefaultPatterns: false,
+  },
+  includeSensitiveFiles: false,   // .env, *.pem, .npmrc, .ssh/, .tfstate …
+};
+```
+
+Each entry is `{ rule, pattern }`, where `rule` is the name that appears in the audit and
+`pattern` is a `RegExp`, or a string in a `.json` config. A bare `RegExp` in the array works
+too — it comes out as `custom-1`, `custom-2`, … in the findings — but naming the rule is what
+makes an audit entry mean something.
+
+- Credential-bearing **files** are skipped by default and listed in `skipped[]` with reason
+  `sensitive-file`. `includeSensitiveFiles: true` emits them.
+- Secret-shaped **strings** inside ordinary files are redacted in the emitted parts. Only the
+  matched span is masked, never the whole line, and no excerpt of a matched line reaches any
+  artifact. Multi-line PEM keys are masked as a block.
+- `customPatterns` add rules; `disableDefaultPatterns` removes the built-in set — it does not
+  disable redaction itself.
+
+Redaction is **fail-closed**, so a placeholder is indistinguishable from a secret: a
+`.env.example` whose line reads `JWT_SECRET=replace-with-base64url-48-bytes` is masked like a
+live key would be, and a test fixture literal such as `process.env.X_SECRET = "test-value"` is
+masked too. The same holds for an environment reference written as a quoted value —
+`password: "${DB_PASSWORD}"` is masked exactly like a literal password, because the rule sees a
+credential-shaped key followed by a string and a `${…}` reference cannot be told apart from a
+secret by shape alone. That is the intended trade-off — the alternative is guessing which values
+are throwaway — and it is worth knowing before you hand the snapshot to a model and find the
+template less readable than the original. To narrow it, remove a rule by name with
+`disableDefaultPatterns: true` plus your own `customPatterns`.
+
+Findings are summarised in `reports/audit.md` (one row per line, naming every rule that matched
+it), counted in `manifest.totals.redactedLines`, and shown in the `generate` summary as a
+`Redacted:` line separate from `Warnings:`.
+
+## Output directories
+
+```js
+export default {
+  outDir: "snapshot",
+  tmpDir: "snapshot.tmp",
+};
+```
+
+`outDir` may not be the working directory, an ancestor, or the filesystem root, and
+`outDir`/`tmpDir` may not contain one another — the message prints the resolved paths. Writes
+are atomic: the previous snapshot survives until the new one is complete.
+
+Both directories are also **refused if they already exist and this generator did not write
+them**, so `outDir: "src"` cannot replace your source tree. Ownership is proved by the
+`.codebase-snapshot` marker and nothing else: a JSON object naming this generator, with a
+schema version this build understands, a per-snapshot `id`, and the list of entries it wrote.
+A file with that name but no valid marker, or a directory holding a manifest from another
+tool, is refused. The proof is never a filename, so an existing `docs/README.md` is safe.
+
+Files your hook writes into the output directory are recorded in the marker's entry list, so
+they do not block later runs; a file you add by hand afterwards does, because it is not in the
+snapshot the marker describes.
+
+## Hooks
+
+```js
+export default {
+  hooks: {
+    afterGenerate: (manifest) => {
+      // runs after a real generate; a dry run does not call it
+    },
+  },
+};
+```
+
+A throwing hook is downgraded to a warning on the manifest — it never loses a snapshot that
+was already written. A hook may return a promise: it is not awaited (this API is synchronous),
+and a rejection is recorded as a warning on the re-shipped manifest and marker. Anything the
+hook writes to stdout is redirected to stderr for the duration of the call, so `--format json`
+stays parseable.
+
+"Not awaited" does not mean "free": Node keeps the process alive while the hook's own timers,
+sockets or pending I/O are outstanding, so a hook that schedules a long job delays the command by
+that long even though the snapshot is already written. Keep `afterGenerate` short — hand long work
+to a background process — or use the programmatic `generateSnapshot`, whose promise you can `await`
+alongside your own work.
+
+A hook may write its own files into the output directory; that is safe across reruns because
+ownership is established by the marker rather than by the filenames present.
+
+A hook runs in the **process** working directory, so with `--cwd elsewhere` a relative path
+resolves against your shell, not the target repository. Use the absolute paths on `manifest`
+(or resolve against `outDir` yourself) when passing `--cwd`.
+
+## Complete example
+
+Every setting at its built-in default. Nothing here has to be written — the tool runs on these
+values with no config at all.
+
+```js
+const config = {
+  // ── Project ──────────────────────────────────────────────
+  preset: "detected",            // "detected" auto-detects; or name one of the 25
+  branch: "main",                // recorded when git cannot report one
+
+  // ── Output ───────────────────────────────────────────────
+  outDir: "snapshot",
+  tmpDir: "snapshot.tmp",
+
+  // ── Size ─────────────────────────────────────────────────
+  maxPartBytes: "300k",
+  largeFileBytes: "200k",
+  previewHeadLines: 80,
+  previewTailLines: 40,
+  budgets: { default: "300k", byLayer: {} },
+
+  // ── Scope ────────────────────────────────────────────────
+  include: [],
+  excludePatterns: [],
+  discovery: "auto",                 // "auto" | "git" | "walk"
+
+  // ── Artifacts ────────────────────────────────────────────
+  artifacts: {
+    readme: true,
+    manifest: true,
+    parts: true,
+    navigation: true,
+    projectTree: true,
+    audit: true,
+    monolith: false,
+  },
+
+  // ── Safety ───────────────────────────────────────────────
+  includeSensitiveFiles: false,
+  secrets: { customPatterns: [], disableDefaultPatterns: false },
+
+  // ── Classification ───────────────────────────────────────
+  layersMode: "merge",
+  layers: [],
+  kinds: [],
+
+  // ── Advanced ─────────────────────────────────────────────
+  includeMonolith: false,
+  maxMonolithBytes: null,
+  hooks: {},
+};
+
+export default config;
+```
+
+Deleting any line is safe — the defaults are real, and each one is what the comment says.
+
+The object is exported through a name because `export default { … }` is reported by
+`import/no-anonymous-default-export`, which `eslint-config-next` enables by default: the inline
+form made the generated file a lint error on first save in a Next.js project. A named export is
+also what lets you reference the object (from a test, or from `--dry-run`) without a wrapper.
+
+This is **not** byte-identical to a generated file. `codebase-snapshot init` starts from these
+values and substitutes two things: `preset` becomes the detected name (`node-lib` for a plain
+npm package), and `maxPartBytes` with `budgets.default` become that preset's
+`recommendedBudget` (`"120k"` in the same project). `generate` on its own applies no
+recommended budget — without a config it uses `--max-part-bytes`, default 307200 — so the
+preset's figure only takes effect once `init` has written it into a config.
+
+## Interactive setup
+
+```bash
+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:
+
+```bash
+npx codebase-snapshot init --yes
+npx codebase-snapshot init --preset go --max-part-bytes 200k \
+    --include "cmd/**,internal/**" --exclude "**/*_test.go" --yes
+```
+
+`--dry-run` prints the config and writes nothing. `--force` replaces an existing ES-module
+config (`.ts`, `.js`, `.mjs`) in place; without it, an existing config is left alone and the
+command exits `1`.
+
+It will not replace a JSON-family config — `snapshot.config.json`, `.snapshotrc`,
+`.snapshotrc.json`, or the `"snapshot"` key in `package.json` — because this wizard writes an
+ES-module file and a new file beside the old one would silently shadow it. Those cases exit `1`
+with a message naming the file to delete or rename. Note that this means `--force` writing
+`snapshot.config.ts` does shadow a `"snapshot"` key in `package.json`, since a dedicated config
+file always wins.

package/docs/how-to-context-budget.md

@@ -0,0 +1,90 @@
+# How to budget LLM context files for a codebase
+
+Context is a budget, not a bin. Every token spent on a lockfile is a token not spent on the function
+being asked about, and the failure is silent — the model simply gets vaguer. This page is about
+choosing the numbers and knowing what they cost.
+
+## Start from the destination, not the repository
+
+Work backwards. The constraint is whatever consumes the output:
+
+| Consumer | What actually limits you |
+| :--- | :--- |
+| A chat window | The window, minus room for the conversation and the answer |
+| A RAG pipeline | Embedding chunk size, and how many chunks get retrieved per query |
+| An agent loop | The window, minus tool schemas and minus the reasoning it has left to do |
+| A review artifact | Human attention — usually far smaller than any window |
+
+An agent needs room to *think*, so it wants the smallest context that answers the question. A chat
+window can take the largest.
+
+## The numbers that matter
+
+- **`maxPartBytes`** — the hard ceiling for one part. This is a promise, not an average: no part
+  exceeds it. Set it to the destination's limit and stop worrying about the largest file.
+- **`largeFileBytes`** — above this, a file becomes a head/tail excerpt rather than its full body.
+  This is what stops one generated 40 MB file from consuming an entire snapshot.
+- **`budgets.byLayer`** — different ceilings per layer. Documentation is usually worth less per byte
+  than source; `{ docs: 40_000 }` is a common shape.
+- **`maxMonolithBytes`** — the single-file artifact roughly doubles output, so it is off by default
+  and capped when on.
+
+```js
+const config = {
+  maxPartBytes: "120k",
+  largeFileBytes: "200k",
+  budgets: { default: "120k", byLayer: { docs: 40_000, config: 20_000 } },
+  artifacts: { monolith: false },
+};
+export default config;
+```
+
+## What each byte buys
+
+Measured on this repository's own snapshot, as a rough guide:
+
+| Layer | Share of bytes | Worth it? |
+| :--- | :--- | :--- |
+| Source | largest | yes — this is the question |
+| Docs and comments | large | partly; often the best value per byte, but not when duplicated |
+| Config | small | yes — it explains how the source runs |
+| Tests | often 30–40% | rarely, for a code question |
+| Generated and vendored | varies | almost never |
+
+The cheapest large win in most repositories is excluding tests and build output. The second cheapest
+is excluding duplicated documentation (the same content in a wiki, a `docs/` tree and a README).
+
+## Do not trust a size estimate you have not measured
+
+A snapshot is auditable: `manifest.json` records `includedBytes` and `includedLines` **measured from
+the block actually emitted**, not from the file on disk. That distinction matters — a truncated file
+does not report its on-disk size.
+
+```bash
+npx codebase-snapshot report
+```
+
+`report` prints totals, per-layer metrics and the secret audit, so you can see where the budget went
+before you spend it on a model call.
+
+## Tuning loop
+
+1. Generate with a ceiling that matches the destination.
+2. Run `report`; look at the per-layer breakdown.
+3. Cut the largest layer that does not answer your question.
+4. Re-generate and compare `manifest.totals.events` and the part count.
+5. Keep the settings that produced a snapshot you actually used — the config is the durable artifact,
+   not the output.
+
+## The failure this prevents
+
+Without a ceiling, the boundary is wherever the tool stopped. Two runs can cut differently, so a
+worse answer is indistinguishable from a different cut. With `maxPartBytes` fixed and output
+deterministic, a changed answer means changed code — which is the only interpretation that lets you
+debug it.
+
+## Next
+
+- [Configuration](configuration.md) — every setting, all 25 presets
+- [Snapshot output](output.md) — the full `manifest.json` schema
+- [How to feed a codebase to an LLM](how-to-feed-a-repo-to-claude.md)

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

@@ -0,0 +1,122 @@
+# How to feed a whole codebase to ChatGPT, Claude or Cursor
+
+A model cannot clone your repository. Everything it knows about your code has to arrive as text, and
+the text has to fit. This is the practical, repeated recipe — including the parts most guides skip,
+which are the ones that decide whether the answer is any good.
+
+## The problem, stated properly
+
+There are three separate failures, and they need different fixes:
+
+1. **It does not fit.** A real repository is far larger than any context window once you include
+   node_modules, lockfiles and build output. Naively concatenating files produces something that is
+   rejected, truncated by an unknown amount, or billed at a size you did not expect.
+2. **It does not fit *predictably*.** If the boundary moves between runs, you cannot tell whether a
+   changed answer came from changed code or a different cut of the same code.
+3. **It is not current.** The document you pasted was generated yesterday. Nobody notices until the
+   model confidently describes a function you deleted.
+
+Most "paste your repo into an LLM" tooling solves only the first.
+
+## The recipe
+
+### 1. Generate from the checkout, not from a website
+
+If the code is private, it should not be uploaded to a third-party service to be turned into text.
+Everything below runs locally.
+
+```bash
+cd /path/to/your/project
+npx codebase-snapshot setup
+```
+
+`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.
+
+If you prefer to see each stage:
+
+```bash
+npx codebase-snapshot init --yes    # config + scripts + dependency + .gitignore
+npm install
+npm run snapshot                    # generate
+npm run snapshot:validate           # exit 0 = still matches the disk
+```
+
+### 2. Choose the budget, not the file list
+
+The setting that matters is `maxPartBytes` — the hard ceiling for one part. Pick it from the
+destination, not from taste:
+
+| Destination | Practical budget |
+| :--- | :--- |
+| A chat window | 40–120 KB per part; paste one or two |
+| A RAG index | 120–300 KB per part, chunked by heading |
+| An agent's context | 60–150 KB; smaller parts leave room to reason |
+
+```js
+// snapshot.config.mjs
+const config = {
+  maxPartBytes: "120k",
+  // Per-layer ceilings, when docs and code deserve different treatment.
+  budgets: { default: "120k", byLayer: { docs: 40_000 } },
+};
+export default config;
+```
+
+A file larger than the budget is not silently dropped: it is truncated with an explicit marker
+naming the budget, and files above `largeFileBytes` become a head/tail excerpt instead of a body.
+
+### 3. Tell the model what it is looking at
+
+The snapshot is self-describing, and saying so up front measurably improves answers:
+
+> The context below is a generated snapshot of a repository. `manifest.json` lists every included
+> file with its language, part and hash, and every excluded file with the reason. Reads start with
+> `parts/part-001.md`. If something you need is missing, ask me to check `explain <path>` rather than
+> assuming it does not exist.
+
+That last sentence matters more than it looks: models fill gaps by invention, and telling them the
+gap is documented turns a hallucination into a question.
+
+### 4. Include the index, always
+
+Paste `manifest.json` alongside the parts, or at least `reports/navigation.md`. Without the index the
+model sees text with no map and guesses at structure. With it, it can say "this file is in part 3,
+which I have not been given" instead of inventing the file.
+
+### 5. Re-validate before every session that matters
+
+```bash
+npm run snapshot:validate || npm run snapshot
+```
+
+`validate` compares each file's hash *and* a digest of the settings used to generate the snapshot. A
+changed budget, layer rule or secret pattern is drift, not silence — so the check catches both code
+changes and configuration changes.
+
+## What to exclude
+
+The defaults already skip binaries, credential files (`.env`, `*.pem`, `.ssh/`, `.npmrc`) and
+anything gitignored. Beyond that, the highest-value exclusions are usually:
+
+```js
+excludePatterns: ["**/*.test.ts", "**/__snapshots__/**", "public/**", "*.min.js", "vendor/**"],
+```
+
+Tests and fixtures are often 40% of a repository and rarely part of the question. Removing them buys
+context for the code that is being asked about.
+
+## What this does not solve
+
+- **The model still has a fixed window.** If the code genuinely exceeds it, you are choosing what to
+  omit — this tool makes that choice explicit and recorded rather than accidental.
+- **Understanding beats volume.** A smaller snapshot with the right 20 files outperforms a large one
+  containing everything. Use `include` when you know the area.
+- **Drift is only detected when you run the check.** It is not a watcher, unless you use `--watch`.
+
+## Next
+
+- [Configuration](configuration.md) — every setting and its default
+- [Snapshot output](output.md) — what each artifact contains
+- [Comparing with other tools](vs-repomix.md)