codebase-snapshot 0.9.9 → 0.9.14

package/dist/{types-Ca4PmkiQ.d.cts → types-DIX6zWSt.d.cts}

@@ -21,7 +21,7 @@ type TextEncoding = "utf-8" | "utf-8-lossy" | "utf-16le" | "utf-16be";
  * `full`    – the complete file body was emitted.
  * `preview` – the body was truncated (by lines and/or bytes) before emission.
  */
-type InclusionMode = "full" | "preview";
+type InclusionMode = "full" | "preview" | "signatures";
 interface SourceSummary {
     directives: string[];
     imports: string[];
@@ -88,7 +88,15 @@ type SkipReason = "binary" | "read-error" | "not-file"
  * expected — which used to be recorded as the generic `not-file`, implying the path was a
  * socket or a FIFO rather than a repository whose contents are simply somebody else's.
  */
- | "nested-repository";
+ | "nested-repository"
+/**
+ * Not in the set that `--changed-since` or `--staged` asked for.
+ *
+ * Deliberately distinct from `excluded`, which means the user's own glob rejected the path.
+ * Here the file is perfectly includable and simply did not change; reporting it as
+ * `excluded` would send a reader looking for an exclude pattern they never wrote.
+ */
+ | "unchanged";
 interface SkipRecord {
     /** Path as it may be shown in an artifact: secret spans are masked. */
     path: string;
@@ -144,6 +152,23 @@ interface PartMetadata {
     filename: string;
     /** Exact UTF-8 byte length of the emitted part file. */
     byteSize: number;
+    /**
+     * Estimated tokens in this part.
+     *
+     * `byteSize` answers "will this fit the byte budget"; this answers the question a caller
+     * actually has, which is "will this fit my context window". An estimate, and labelled as
+     * one: `estimateTokens` documents exactly what it counts.
+     */
+    estimatedTokens: number;
+    /**
+     * The byte budget this part was partitioned against.
+     *
+     * With per-layer budgets a snapshot has several budgets at once, so "within budget"
+     * cannot be answered without knowing which one applied. Verification compared every
+     * part against the *largest* budget in the run, which passed a part that was over its
+     * own.
+     */
+    budgetBytes: number;
     sha256: string;
     lines: number;
     fileCount: number;
@@ -198,6 +223,14 @@ interface ManifestTotals {
     skippedFiles: number;
     totalSourceBytes: number;
     totalContentBytes: number;
+    /**
+     * Estimated tokens in the emitted parts.
+     *
+     * Optional because a manifest written before this was recorded has no such key. The number
+     * is an estimate — see `estimateTokens` for the method — and it exists because the snapshot
+     * is pasted into a context window, which is measured in tokens rather than bytes.
+     */
+    estimatedTokens?: number;
     partCount: number;
     warningCount: number;
     /**
@@ -256,13 +289,34 @@ interface ManifestConfigSnapshot {
     /** Digest of the effective settings; see `configDigest`. */
     digest?: string;
     maxPartBytes: number;
+    /**
+     * The token ceiling the run was given, or `undefined` when only bytes were named.
+     *
+     * Recorded so the manifest states the budget the user chose rather than only the byte
+     * value it was converted to.
+     */
+    maxPartTokens?: number;
     largeFileBytes: number;
     previewHeadLines: number;
     previewTailLines: number;
     includeMonolith: boolean;
+    /**
+     * The ceiling above which the monolith is not written; `null` for no ceiling.
+     *
+     * Optional because a manifest written before this was recorded has no such key.
+     */
+    maxMonolithBytes?: number | null;
     includeSensitiveFiles: boolean;
     /** How files were discovered; `undefined` on manifests written before this was recorded. */
     discovery?: DiscoveryMode;
+    /** The changed-files scope the snapshot was taken over, when one was used. */
+    changedSince?: string;
+    staged?: boolean;
+    withDependents?: boolean;
+    /** True when bodies were replaced by signatures. */
+    skeleton?: boolean;
+    /** True when `reports/audit.sarif` was written. */
+    sarif?: boolean;
     artifacts: ResolvedArtifacts;
     include: string[];
     preset: string;
@@ -315,6 +369,14 @@ interface Manifest {
     artifacts: {
         fullJson: ManifestArtifact | null;
         fullMarkdown: ManifestArtifact | null;
+        /**
+         * `reports/audit.sarif`, when `--sarif` asked for it.
+         *
+         * Optional because most runs do not write one, and a manifest written before this
+         * existed has no such key at all — the two are indistinguishable to a reader, which is
+         * why the presence of the file is also recorded in `config`.
+         */
+        sarif?: ManifestArtifact;
     };
     layers: Record<string, number>;
     kinds: Record<string, number>;
@@ -382,6 +444,15 @@ interface SnapshotConfig {
     tmpDir?: string;
     /** Raw bytes, or a human-readable size (`"120k"`, `"1.5mb"`). */
     maxPartBytes?: ByteSize;
+    /**
+     * A per-part ceiling in *tokens* rather than bytes.
+     *
+     * The snapshot is pasted into a context window, and a context window is measured in tokens;
+     * bytes are what the partitioner writes. Naming a token budget sets `maxPartBytes` to the
+     * byte count that corresponds to it, so the byte bound — the thing the partitioner actually
+     * enforces — never stops being true. The smaller of the two ceilings wins.
+     */
+    maxPartTokens?: ByteSize;
     largeFileBytes?: ByteSize;
     previewHeadLines?: number;
     previewTailLines?: number;
@@ -393,6 +464,31 @@ interface SnapshotConfig {
     include?: string[];
     /** Force a preset by name instead of auto-detecting one. */
     preset?: string;
+    /**
+     * Only include files changed since this git ref.
+     *
+     * The pull-request case: the diff is small and the repository is not. Unchanged files are
+     * recorded in `skipped[]` with reason `unchanged`, so the manifest accounts for them.
+     */
+    changedSince?: string;
+    /** Only include files staged for the next commit. */
+    staged?: boolean;
+    /**
+     * Emit signatures instead of bodies for TypeScript and TSX files.
+     *
+     * Matches `inclusionMode: "signatures"` on the entries it applies to, so a reader can tell a
+     * compressed file from a whole one without diffing it against the source.
+     */
+    skeleton?: boolean;
+    /** Also write `reports/audit.sarif` so a CI security gate can read the findings. */
+    sarif?: boolean;
+    /**
+     * With `changedSince` or `staged`, also include the files that import a changed one.
+     *
+     * A one-hop closure: the file you changed and the files that reference it are the context
+     * needed to change it safely.
+     */
+    withDependents?: boolean;
     /** Switch individual snapshot artifacts off. Everything is on by default. */
     artifacts?: ArtifactSelection;
     /**
@@ -418,6 +514,8 @@ interface ResolvedSnapshotConfig {
     outDir: string;
     tmpDir: string;
     maxPartBytes: number;
+    /** The token ceiling the user asked for, before it was turned into `maxPartBytes`. */
+    maxPartTokens?: number;
     largeFileBytes: number;
     previewHeadLines: number;
     previewTailLines: number;
@@ -430,6 +528,21 @@ interface ResolvedSnapshotConfig {
      * reader treats `undefined` as `auto`, so the effective mode is never guessed twice.
      */
     discovery?: DiscoveryMode;
+    /** Only files changed since this git ref; `undefined` scans everything. */
+    changedSince?: string;
+    /** Only files staged for the next commit. */
+    staged?: boolean;
+    /** Emit signatures instead of bodies for TypeScript and TSX files. */
+    skeleton?: boolean;
+    /**
+     * Also write `reports/audit.sarif`, the findings in SARIF 2.1.0.
+     *
+     * For a CI security gate: GitHub Code Scanning reads SARIF, and a markdown report it cannot
+     * ingest is a finding nobody's build can act on.
+     */
+    sarif?: boolean;
+    /** Also include the files that import a changed one. */
+    withDependents?: boolean;
     /** Empty means "no allow-list"; every discovered file is a candidate. */
     include: string[];
     /** The preset that was resolved (detected or forced). */
@@ -455,9 +568,24 @@ interface CliOptions {
     includeSensitiveFiles?: boolean;
     maxMonolithBytes?: number | null;
     maxPartBytes?: number;
+    maxPartTokens?: ByteSize | null;
     largeFileBytes?: number;
     /** Artifact names to suppress for this invocation (`--skip-artifacts`). */
     skipArtifacts?: string[];
+    /**
+     * Artifact names to keep, with everything else off (`--only-artifacts`).
+     *
+     * Separate from the derived `skipArtifacts` because the two are not interchangeable: "only
+     * these" is a statement about the whole selection, and the suppression list cannot express it
+     * when the configuration has already turned one of the named artifacts off.
+     */
+    onlyArtifacts?: string[];
+    discovery?: DiscoveryMode;
+    changedSince?: string;
+    staged?: boolean;
+    withDependents?: boolean;
+    skeleton?: boolean;
+    sarif?: boolean;
 }
 interface ValidationDrift {
     missingInSnapshot: string[];

package/dist/{types-Ca4PmkiQ.d.ts → types-DIX6zWSt.d.ts}

@@ -21,7 +21,7 @@ type TextEncoding = "utf-8" | "utf-8-lossy" | "utf-16le" | "utf-16be";
  * `full`    – the complete file body was emitted.
  * `preview` – the body was truncated (by lines and/or bytes) before emission.
  */
-type InclusionMode = "full" | "preview";
+type InclusionMode = "full" | "preview" | "signatures";
 interface SourceSummary {
     directives: string[];
     imports: string[];
@@ -88,7 +88,15 @@ type SkipReason = "binary" | "read-error" | "not-file"
  * expected — which used to be recorded as the generic `not-file`, implying the path was a
  * socket or a FIFO rather than a repository whose contents are simply somebody else's.
  */
- | "nested-repository";
+ | "nested-repository"
+/**
+ * Not in the set that `--changed-since` or `--staged` asked for.
+ *
+ * Deliberately distinct from `excluded`, which means the user's own glob rejected the path.
+ * Here the file is perfectly includable and simply did not change; reporting it as
+ * `excluded` would send a reader looking for an exclude pattern they never wrote.
+ */
+ | "unchanged";
 interface SkipRecord {
     /** Path as it may be shown in an artifact: secret spans are masked. */
     path: string;
@@ -144,6 +152,23 @@ interface PartMetadata {
     filename: string;
     /** Exact UTF-8 byte length of the emitted part file. */
     byteSize: number;
+    /**
+     * Estimated tokens in this part.
+     *
+     * `byteSize` answers "will this fit the byte budget"; this answers the question a caller
+     * actually has, which is "will this fit my context window". An estimate, and labelled as
+     * one: `estimateTokens` documents exactly what it counts.
+     */
+    estimatedTokens: number;
+    /**
+     * The byte budget this part was partitioned against.
+     *
+     * With per-layer budgets a snapshot has several budgets at once, so "within budget"
+     * cannot be answered without knowing which one applied. Verification compared every
+     * part against the *largest* budget in the run, which passed a part that was over its
+     * own.
+     */
+    budgetBytes: number;
     sha256: string;
     lines: number;
     fileCount: number;
@@ -198,6 +223,14 @@ interface ManifestTotals {
     skippedFiles: number;
     totalSourceBytes: number;
     totalContentBytes: number;
+    /**
+     * Estimated tokens in the emitted parts.
+     *
+     * Optional because a manifest written before this was recorded has no such key. The number
+     * is an estimate — see `estimateTokens` for the method — and it exists because the snapshot
+     * is pasted into a context window, which is measured in tokens rather than bytes.
+     */
+    estimatedTokens?: number;
     partCount: number;
     warningCount: number;
     /**
@@ -256,13 +289,34 @@ interface ManifestConfigSnapshot {
     /** Digest of the effective settings; see `configDigest`. */
     digest?: string;
     maxPartBytes: number;
+    /**
+     * The token ceiling the run was given, or `undefined` when only bytes were named.
+     *
+     * Recorded so the manifest states the budget the user chose rather than only the byte
+     * value it was converted to.
+     */
+    maxPartTokens?: number;
     largeFileBytes: number;
     previewHeadLines: number;
     previewTailLines: number;
     includeMonolith: boolean;
+    /**
+     * The ceiling above which the monolith is not written; `null` for no ceiling.
+     *
+     * Optional because a manifest written before this was recorded has no such key.
+     */
+    maxMonolithBytes?: number | null;
     includeSensitiveFiles: boolean;
     /** How files were discovered; `undefined` on manifests written before this was recorded. */
     discovery?: DiscoveryMode;
+    /** The changed-files scope the snapshot was taken over, when one was used. */
+    changedSince?: string;
+    staged?: boolean;
+    withDependents?: boolean;
+    /** True when bodies were replaced by signatures. */
+    skeleton?: boolean;
+    /** True when `reports/audit.sarif` was written. */
+    sarif?: boolean;
     artifacts: ResolvedArtifacts;
     include: string[];
     preset: string;
@@ -315,6 +369,14 @@ interface Manifest {
     artifacts: {
         fullJson: ManifestArtifact | null;
         fullMarkdown: ManifestArtifact | null;
+        /**
+         * `reports/audit.sarif`, when `--sarif` asked for it.
+         *
+         * Optional because most runs do not write one, and a manifest written before this
+         * existed has no such key at all — the two are indistinguishable to a reader, which is
+         * why the presence of the file is also recorded in `config`.
+         */
+        sarif?: ManifestArtifact;
     };
     layers: Record<string, number>;
     kinds: Record<string, number>;
@@ -382,6 +444,15 @@ interface SnapshotConfig {
     tmpDir?: string;
     /** Raw bytes, or a human-readable size (`"120k"`, `"1.5mb"`). */
     maxPartBytes?: ByteSize;
+    /**
+     * A per-part ceiling in *tokens* rather than bytes.
+     *
+     * The snapshot is pasted into a context window, and a context window is measured in tokens;
+     * bytes are what the partitioner writes. Naming a token budget sets `maxPartBytes` to the
+     * byte count that corresponds to it, so the byte bound — the thing the partitioner actually
+     * enforces — never stops being true. The smaller of the two ceilings wins.
+     */
+    maxPartTokens?: ByteSize;
     largeFileBytes?: ByteSize;
     previewHeadLines?: number;
     previewTailLines?: number;
@@ -393,6 +464,31 @@ interface SnapshotConfig {
     include?: string[];
     /** Force a preset by name instead of auto-detecting one. */
     preset?: string;
+    /**
+     * Only include files changed since this git ref.
+     *
+     * The pull-request case: the diff is small and the repository is not. Unchanged files are
+     * recorded in `skipped[]` with reason `unchanged`, so the manifest accounts for them.
+     */
+    changedSince?: string;
+    /** Only include files staged for the next commit. */
+    staged?: boolean;
+    /**
+     * Emit signatures instead of bodies for TypeScript and TSX files.
+     *
+     * Matches `inclusionMode: "signatures"` on the entries it applies to, so a reader can tell a
+     * compressed file from a whole one without diffing it against the source.
+     */
+    skeleton?: boolean;
+    /** Also write `reports/audit.sarif` so a CI security gate can read the findings. */
+    sarif?: boolean;
+    /**
+     * With `changedSince` or `staged`, also include the files that import a changed one.
+     *
+     * A one-hop closure: the file you changed and the files that reference it are the context
+     * needed to change it safely.
+     */
+    withDependents?: boolean;
     /** Switch individual snapshot artifacts off. Everything is on by default. */
     artifacts?: ArtifactSelection;
     /**
@@ -418,6 +514,8 @@ interface ResolvedSnapshotConfig {
     outDir: string;
     tmpDir: string;
     maxPartBytes: number;
+    /** The token ceiling the user asked for, before it was turned into `maxPartBytes`. */
+    maxPartTokens?: number;
     largeFileBytes: number;
     previewHeadLines: number;
     previewTailLines: number;
@@ -430,6 +528,21 @@ interface ResolvedSnapshotConfig {
      * reader treats `undefined` as `auto`, so the effective mode is never guessed twice.
      */
     discovery?: DiscoveryMode;
+    /** Only files changed since this git ref; `undefined` scans everything. */
+    changedSince?: string;
+    /** Only files staged for the next commit. */
+    staged?: boolean;
+    /** Emit signatures instead of bodies for TypeScript and TSX files. */
+    skeleton?: boolean;
+    /**
+     * Also write `reports/audit.sarif`, the findings in SARIF 2.1.0.
+     *
+     * For a CI security gate: GitHub Code Scanning reads SARIF, and a markdown report it cannot
+     * ingest is a finding nobody's build can act on.
+     */
+    sarif?: boolean;
+    /** Also include the files that import a changed one. */
+    withDependents?: boolean;
     /** Empty means "no allow-list"; every discovered file is a candidate. */
     include: string[];
     /** The preset that was resolved (detected or forced). */
@@ -455,9 +568,24 @@ interface CliOptions {
     includeSensitiveFiles?: boolean;
     maxMonolithBytes?: number | null;
     maxPartBytes?: number;
+    maxPartTokens?: ByteSize | null;
     largeFileBytes?: number;
     /** Artifact names to suppress for this invocation (`--skip-artifacts`). */
     skipArtifacts?: string[];
+    /**
+     * Artifact names to keep, with everything else off (`--only-artifacts`).
+     *
+     * Separate from the derived `skipArtifacts` because the two are not interchangeable: "only
+     * these" is a statement about the whole selection, and the suppression list cannot express it
+     * when the configuration has already turned one of the named artifacts off.
+     */
+    onlyArtifacts?: string[];
+    discovery?: DiscoveryMode;
+    changedSince?: string;
+    staged?: boolean;
+    withDependents?: boolean;
+    skeleton?: boolean;
+    sarif?: boolean;
 }
 interface ValidationDrift {
     missingInSnapshot: string[];

package/docs/agent.md

@@ -115,7 +115,7 @@ devDependency and the `.gitignore` entries for the snapshot directory, and nothi
 
 ## When the client speaks MCP
 
-`codebase-snapshot mcp` serves the repository to a Model Context Protocol client over stdio: seven
+`codebase-snapshot mcp` serves the repository to a Model Context Protocol client over stdio: eight
 tools, `snapshot://` resources and two prompts. Prefer it over shelling out when the agent already
 has an MCP connection, for two reasons that are properties of the design rather than of the wiring:
 

package/docs/cli.md

@@ -174,7 +174,7 @@ The whole first run in one command, with defaults and no prompts. This is the sa
 🚀 Setup for: /path/to/repo
 ✅ Created snapshot.config.ts (preset: nextjs)
    Added npm scripts: snapshot, snapshot:validate
-   Added devDependency: codebase-snapshot ^0.9.9
+   Added devDependency: codebase-snapshot ^0.9.14
    Added to .gitignore: snapshot/, snapshot.tmp/
 ⏳ Installing dependencies…
 ✅ Installed dependencies (npm install, 2.1s)
@@ -192,7 +192,9 @@ The whole first run in one command, with defaults and no prompts. This is the sa
   `generate` and `init`.
 - `--format json` emits **one** document:
   `{ "setup": { configPath, configReused, preset, scripts, dependency, gitignoreEntries, install, notes }, "manifest": { … } }`,
-  where `manifest` is the same object `generate --format json` writes.
+  where `manifest` is the same object `generate --format json` writes. If that generate fails, the
+  document is `{ "error": { … }, "setup": { … }, "manifest": null }` and the exit code is the
+  generate's: one document per invocation, a payload or an error, never a payload holding an error.
 - If `outDir` holds files this tool did not write, `setup` still refuses to replace it (exit 1,
   naming the entries) after writing the config — the guard is not weakened by the convenience.
 ### `init`
@@ -211,7 +213,7 @@ It also has three side effects on files you own, and it says so when it does the
 ```
 ✅ Created snapshot.config.ts (preset: node-lib)
    Added npm scripts: snapshot, snapshot:validate
-   Added devDependency: codebase-snapshot ^0.9.9
+   Added devDependency: codebase-snapshot ^0.9.14
    Added to .gitignore: snapshot/, snapshot.tmp/
 ```
 
@@ -378,7 +380,7 @@ codebase-snapshot mcp                 # serve the current directory over stdio
 codebase-snapshot mcp --cwd <path>    # serve another repository
 ```
 
-Serves the repository to a Model Context Protocol client over stdio: seven tools, `snapshot://`
+Serves the repository to a Model Context Protocol client over stdio: eight tools, `snapshot://`
 resources and two prompts. Stdout carries JSON-RPC messages and nothing else; every note goes to
 stderr. It speaks both protocol eras — the legacy `initialize` handshake and the stateless
 `2026-07-28` revision — and answers whichever the client starts with.
@@ -401,15 +403,22 @@ narrowest cases of the same rule.
 | `--cwd <path>` | path | current directory | generate, validate, report, explain, init, skill | Repository to operate on. Must exist and be a directory. `diff` and `describe` take no `--cwd`. |
 | `--out-dir <path>` | path | `snapshot` | generate, validate, report, explain, init | Where the snapshot is written or read. May be absolute. |
 | `--max-part-bytes <n>` | size | `307200` (300 KB) | generate, validate, report, explain, init | Hard ceiling per markdown part. Accepts `120k`, `1.5mb`. Minimum 4096. |
+| `--max-part-tokens <n>` | size | unset | generate, validate, setup | A per-part ceiling in **tokens**, for a context window rather than a disk. Narrows `--max-part-bytes` to the equivalent byte count (`tokens × 4`); the smaller of the two ceilings always wins, and both are recorded in the manifest. Accepts `32k`. Minimum 1024 — below that it is a usage error, not a value quietly raised to the floor. |
 | `--large-file-bytes <n>` | size | `204800` (200 KB) | generate, validate, report, explain | Above this, a file becomes a head/tail preview. |
 | `--max-monolith-bytes <n>` | size | unset | generate, validate, report, explain | Skip the single-file monolith when it would exceed this. |
 | `--include-monolith` | flag | off | generate, validate, report, explain | Also write `full-codebase.json` and `full-codebase.md`. |
 | `--include-sensitive-files` | flag | off | generate, validate, report, explain, init | Emit `.env`, `*.pem`, `.npmrc` and similar. Off by default; they are reported as skipped. |
 | `--skip-artifacts <names>` | list | unset | generate, validate, report, explain, init | Comma-separated artifacts to omit. |
-| `--only-artifacts <names>` | list | unset | generate, validate, report, explain, init | Write only these. Cannot be combined with `--skip-artifacts`. |
+| `--only-artifacts <names>` | list | unset | generate, validate, report, explain, init | Write *only* these, and **turn on** any this names: a config with `artifacts: { audit: false }` still gets `reports/audit.md` from `--only-artifacts audit`, because "only these" is a statement about the whole selection rather than a suppression list. Cannot be combined with `--skip-artifacts`. |
 | `--format <text\|json>` | enum | `text` | generate, validate, report, explain, init, setup, diff, describe, skill | `json` writes a pure JSON payload to stdout. Every command honours it, and `describe` reports the same nine-command list. |
+| `--sarif` | flag | off | generate, validate, setup | Also write `reports/audit.sarif`: the redaction findings as SARIF 2.1.0, for upload to GitHub Code Scanning. The artefact carries the path, the line and the rule — never the value. Works with `--skip-artifacts audit`, because a CI gate does not read markdown. Rule ids are fixed per rule name, so adding a custom rule never re-points an existing alert. |
+| `--skeleton` | flag | off | generate, validate, setup | Emit signatures instead of bodies: each function or method body becomes `{ /* ... */ }` in place, so formatting and comments around it are untouched. Covers `.ts`, `.tsx`, `.mts`, `.cts`, `.js`, `.jsx`, `.mjs` and `.cjs`; `.d.ts` files are left alone because they are already declarations. The summary still describes the whole file, and affected entries carry `inclusionMode: "signatures"`. `--include-monolith` still writes the whole body, so the monolith's `inclusionMode: "full"` stays true. |
+| `--changed-since <ref>` | git ref | unset | generate, validate, explain | Include only files changed since this ref, plus untracked ones. Every other file is recorded in `manifest.skipped[]` with reason `unchanged` and is never opened. `validate` re-resolves the scope: a skipped file that has changed since is reported as drift, and one that has not is left alone — and with `--with-dependents`, so is a file that now imports one that changed. `explain` answers with the same rule. A ref beginning with `-` is refused. |
+| `--staged` | flag | off | generate, validate, explain | Include only files staged for the next commit. |
+| `--with-dependents` | flag | off | generate, validate, explain | With either of the two above, also include the files that import a changed one — a one-hop closure, not a transitive walk. Needs a scope; alone it is a usage error. |
+| `--install-hook` | flag | off | init, setup | Write `.git/hooks/pre-commit` so a commit is refused while the snapshot is out of date. The hook checks the `outDir` the config names, so it works for a project that does not use `snapshot/`. An existing hook is never replaced; the note says what to add to it instead. |
 | `--dry-run` | flag | off | generate, init, setup | Compute everything, print it, write nothing. |
-| `--watch` | flag | off | generate | Regenerate on every change until interrupted. |
+| `--watch` | flag | off | generate | Regenerate on every change until interrupted. Redaction and parsing are cached per file across runs in the same process, keyed on the content hash, so a one-file edit regenerates from that one file instead of from the whole repository. The cache is memory only and is dropped when the process exits. |
 | `--autopilot` | flag | off | generate | Set the project up without asking — config, `.gitignore`, npm scripts, devDependency, install — then generate. Never overwrites an existing config; refuses an empty directory (exit `1`); contradicts `--no-config` (exit `2`). |
 | `--no-install` | flag | off | setup, generate `--autopilot` | Skip the dependency install. Anywhere else it is a usage error, because it would change nothing. |
 | `--no-config` | flag | off | generate, validate, report, explain, diff | Ignore every `snapshot.config.*` file and run on the built-in defaults. `diff` never loads a config anyway and accepts the flag for consistency. |
@@ -430,6 +439,17 @@ with and the comparison is like for like. `validate --skip-artifacts parts` on a
 built without parts therefore agrees, while the same flag on a full snapshot reports a
 config mismatch.
 
+The same rule applies to the compression and scope options. `--skeleton`, `--sarif` and
+`--max-part-tokens` are recorded in `manifest.config.digest`, so `validate` accepts them too —
+without that, a snapshot generated with `--skeleton` could not be validated at all, and passing
+the flag to `validate` was rejected as a flag that "does not apply to validate". `--changed-since`,
+`--staged` and `--with-dependents` are accepted by `validate` and `explain` because they decide
+which recorded `unchanged` skips are re-checked and what `explain` answers about one file.
+
+`report` does not take any of them: it reads the manifest and prints what is there, so a
+generation setting would change nothing. A flag that parses and does nothing is the silent
+fallback this table exists to prevent.
+
 Every option also accepts the `--option=value` form. That form is required for negative
 numbers, which otherwise look like flags.
 

package/docs/configuration.md

@@ -188,6 +188,11 @@ Classification drives per-layer budgets and the `Layers:` breakdown in `report`.
 ```js
 export default {
   maxPartBytes: "300k",        // hard ceiling per part; default 307200, minimum 4096
+  // maxPartTokens: 32000,     // a per-part ceiling in tokens; narrows maxPartBytes (tokens x 4)
+  // changedSince: "main",      // only files changed since this git ref
+  // staged: true,             // only files staged for the next commit
+  // withDependents: true,     // ...and the files that import them
+  // skeleton: true,           // signatures instead of bodies (--skeleton); TS, JS, TSX and JSX
   largeFileBytes: "200k",      // above this a file becomes a head/tail preview
   previewHeadLines: 80,
   previewTailLines: 40,
@@ -224,8 +229,9 @@ export default {
 ```
 
 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).
+artifacts off with the config or `--skip-artifacts a,b`. `--only-artifacts a,b` is different: it
+*writes only* those and turns each named artifact **on**, so `--only-artifacts audit` still produces
+`reports/audit.md` in a project whose config says `audit: false`. The two flags 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`
@@ -261,19 +267,52 @@ makes an audit entry mean something.
   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.
+  disable redaction itself, and it applies to **paths** as well as to content, so a
+  credential-shaped file name is no longer skipped by a rule you switched off.
 
 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
+masked too. 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`.
 
+The one shape that is *not* masked is a value that is a single `${…}` reference and nothing else —
+`password: "${DB_PASSWORD}"`, `` `${process.env.TOKEN}` `` — because that is an expression and
+masking it rewrites a program (or an assertion message) rather than hiding a credential. Anything
+inside the braces that is not a plain reference settles it the other way:
+`password: "${DB_PASSWORD:-hunter2}"` is masked, because the shell and Compose idiom for a default
+puts a **hardcoded credential** in the fallback position. So does a second interpolation, or any
+quote inside the braces.
+
+The same default is masked when it is not quoted, which is how it is usually written:
+
+```bash
+# .env, docker-compose.yml, a workflow, a shell script — all of these are masked
+POSTGRES_PASSWORD=${POSTGRES_PASSWORD:-MyProdPassword123!}
+POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:-MyProdPassword123!}
+```
+
+The fallback is what gets replaced; the variable name stays, exactly as `POSTGRES_PASSWORD:` does.
+`${PORT:-3000}` is untouched: the name is not a credential name, and a port number is not one
+either.
+
+A credential assigned to a name inside a string is also masked — a connection string is a string:
+
+```js
+const dsn = "password=MySuperSecret123;host=db.internal";
+```
+
+What is left alone is a credential *name* in a literal, with nothing assigned to it:
+`["awsSecret:", "apiKey:"]` is a list of keys, not two credentials, and a documentation line showing
+`password: "…"` inside a code span is showing an example. The difference is whether the literal
+closes between the name and the value.
+
+`readonly` and `declare` are shell assignments in a shell file and declarations in a source file, and
+the file decides: `readonly api_key=hunter2` in `.envrc`, `.sh`, `.zsh`, a YAML or an INI file is
+masked, while `private readonly apiKey = someValue` in TypeScript is left alone.
+
 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:`.