codebase-snapshot 0.9.9 → 0.9.12

package/dist/mcp.d.cts

@@ -1,3 +1,4 @@
+export { G as GenerateSummary, W as WorkerResults, g as generateInWorker } from './generate-worker-D5Xgh27c.cjs';
 import { Readable, Writable } from 'node:stream';
 
 /**
@@ -187,7 +188,7 @@ interface ToolContext {
  * Client-facing hints.
  *
  * `readOnlyHint` is the one that changes behaviour rather than appearance: clients use it to
- * auto-approve a call. Six of the seven tools never touch the filesystem, so they are marked
+ * auto-approve a call. Seven of the eight tools never touch the filesystem, so they are marked
  * read-only and only `snapshot_generate` prompts.
  */
 interface ToolAnnotations {
@@ -297,6 +298,73 @@ declare function createMcpServer(options: McpServerOptions): McpServer;
 /** Every tool this server exposes, in the order a first-time caller should read them. */
 declare function buildTools(): McpTool[];
 
+/**
+ * Reads one file's section back out of a rendered part.
+ *
+ * `snapshot_read` must not open the working tree. The snapshot is the contract: sensitive files
+ * are excluded from it, secret-shaped strings inside ordinary files are redacted on the way in,
+ * and a large file is emitted as a bounded preview. Reading the source directly would hand the
+ * model the `.env` the snapshot deliberately skipped and the credential it masked — so the read
+ * goes through the artifact instead.
+ *
+ * The format it parses is written by `renderFileSection`, and the parser is deliberately tied to
+ * that shape rather than to a regex over the whole document: a file's *content* may legitimately
+ * contain a line that looks like `### FILE: something`, and only fence tracking tells the two
+ * apart. Content fences are four or more backticks (`fenceForContent` never emits three), which
+ * is what makes "the next line equal to this exact fence" an unambiguous terminator.
+ */
+interface PartSection {
+    /** The path as rendered in the `### FILE:` heading. */
+    path: string;
+    /** The `<a id="…">` anchor from the line above the heading, when present. */
+    anchor: string | null;
+    /** The file body, without its fence. Redacted and possibly a bounded preview. */
+    body: string;
+    /** `full`, `preview` or `signatures`. */
+    inclusion: string | null;
+    includedLines: number | null;
+}
+/** Splits a part into one section per emitted file. */
+declare function parsePartSections(partText: string): PartSection[];
+/**
+ * Finds the section for one file.
+ *
+ * The **anchor** is the identifier, not the heading. `anchorForPath` hashes the real
+ * `relativePath`, so it is exact and injective; the heading is the display form, and for a path
+ * with a control character (escaped as `\uXXXX`) or one longer than 300 characters (capped from
+ * the middle) it is not the path at all. The old fallback for those cases was the content
+ * SHA-256, which the part no longer carries — and which could never disambiguate two files with
+ * the same content, the exact case that needs it.
+ *
+ * The heading comparison is kept as a second chance, for a snapshot written before the anchor
+ * was read, or a part whose anchor line was edited by hand.
+ */
+declare function findSection(sections: readonly PartSection[], relativePath: string): PartSection | null;
+interface Window {
+    text: string;
+    fromLine: number;
+    returnedLines: number;
+    totalLines: number;
+    truncated: boolean;
+    nextFromLine: number | null;
+    /**
+     * True when `fromLine` is beyond the last line of the body.
+     *
+     * The start used to be clamped to the last line, so asking for line 9,000 of a 40-line file
+     * returned line 40 with a header that read `Lines 40–40 of 40` — a wrong answer dressed as a
+     * right one. The caller is told the request was out of range instead.
+     */
+    pastEnd: boolean;
+}
+/**
+ * Cuts a line window out of a body.
+ *
+ * Windows are the whole point of this module: a part holds hundreds of kilobytes, and the only
+ * safe default for a tool that returns content is "as little as answers the question". `next` is
+ * an explicit pointer rather than an instruction to keep reading, so an agent decides.
+ */
+declare function windowText(body: string, fromLine: number, lineCount: number): Window;
+
 declare function buildPrompts(): McpPrompt[];
 
 declare function buildResourceProvider(): ResourceProvider;
@@ -409,4 +477,4 @@ declare function validateArguments(schema: InputSchema, value: unknown): string[
  */
 declare function coerceNumericStrings(schema: InputSchema, value: JsonObject): JsonObject;
 
-export { ERROR_CODES, type JsonRpcResponse, type JsonSchema, LEGACY_PROTOCOL_VERSIONS, type LineReaderOptions, MAX_LINE_BYTES, METHOD, MODERN_PROTOCOL_VERSIONS, type McpPrompt, type McpResourceContents, type McpResourceDescriptor, type McpResourceTemplate, type McpServer, type McpServerInfo, type McpServerOptions, type McpTool, type MessageWriter, type ProtocolEra, type ResourceProvider, SERVER_INSTRUCTIONS, SUPPORTED_PROTOCOL_VERSIONS, type ServerOptions, type SessionState, type ToolAnnotations, type ToolContext, type ToolOutcome, buildPrompts, buildResourceProvider, buildTools, classifyRequest, coerceNumericStrings, createLineReader, createMcpServer, createServer, createSession, createWriter, inspectModernMeta, negotiateLegacyVersion, runStdioServer, validateArguments };
+export { ERROR_CODES, type JsonRpcResponse, type JsonSchema, LEGACY_PROTOCOL_VERSIONS, type LineReaderOptions, MAX_LINE_BYTES, METHOD, MODERN_PROTOCOL_VERSIONS, type McpPrompt, type McpResourceContents, type McpResourceDescriptor, type McpResourceTemplate, type McpServer, type McpServerInfo, type McpServerOptions, type McpTool, type MessageWriter, type PartSection, type ProtocolEra, type ResourceProvider, SERVER_INSTRUCTIONS, SUPPORTED_PROTOCOL_VERSIONS, type ServerOptions, type SessionState, type ToolAnnotations, type ToolContext, type ToolOutcome, type Window, buildPrompts, buildResourceProvider, buildTools, classifyRequest, coerceNumericStrings, createLineReader, createMcpServer, createServer, createSession, createWriter, findSection, inspectModernMeta, negotiateLegacyVersion, parsePartSections, runStdioServer, validateArguments, windowText };

package/dist/mcp.d.ts

@@ -1,3 +1,4 @@
+export { G as GenerateSummary, W as WorkerResults, g as generateInWorker } from './generate-worker-D5Xgh27c.js';
 import { Readable, Writable } from 'node:stream';
 
 /**
@@ -187,7 +188,7 @@ interface ToolContext {
  * Client-facing hints.
  *
  * `readOnlyHint` is the one that changes behaviour rather than appearance: clients use it to
- * auto-approve a call. Six of the seven tools never touch the filesystem, so they are marked
+ * auto-approve a call. Seven of the eight tools never touch the filesystem, so they are marked
  * read-only and only `snapshot_generate` prompts.
  */
 interface ToolAnnotations {
@@ -297,6 +298,73 @@ declare function createMcpServer(options: McpServerOptions): McpServer;
 /** Every tool this server exposes, in the order a first-time caller should read them. */
 declare function buildTools(): McpTool[];
 
+/**
+ * Reads one file's section back out of a rendered part.
+ *
+ * `snapshot_read` must not open the working tree. The snapshot is the contract: sensitive files
+ * are excluded from it, secret-shaped strings inside ordinary files are redacted on the way in,
+ * and a large file is emitted as a bounded preview. Reading the source directly would hand the
+ * model the `.env` the snapshot deliberately skipped and the credential it masked — so the read
+ * goes through the artifact instead.
+ *
+ * The format it parses is written by `renderFileSection`, and the parser is deliberately tied to
+ * that shape rather than to a regex over the whole document: a file's *content* may legitimately
+ * contain a line that looks like `### FILE: something`, and only fence tracking tells the two
+ * apart. Content fences are four or more backticks (`fenceForContent` never emits three), which
+ * is what makes "the next line equal to this exact fence" an unambiguous terminator.
+ */
+interface PartSection {
+    /** The path as rendered in the `### FILE:` heading. */
+    path: string;
+    /** The `<a id="…">` anchor from the line above the heading, when present. */
+    anchor: string | null;
+    /** The file body, without its fence. Redacted and possibly a bounded preview. */
+    body: string;
+    /** `full`, `preview` or `signatures`. */
+    inclusion: string | null;
+    includedLines: number | null;
+}
+/** Splits a part into one section per emitted file. */
+declare function parsePartSections(partText: string): PartSection[];
+/**
+ * Finds the section for one file.
+ *
+ * The **anchor** is the identifier, not the heading. `anchorForPath` hashes the real
+ * `relativePath`, so it is exact and injective; the heading is the display form, and for a path
+ * with a control character (escaped as `\uXXXX`) or one longer than 300 characters (capped from
+ * the middle) it is not the path at all. The old fallback for those cases was the content
+ * SHA-256, which the part no longer carries — and which could never disambiguate two files with
+ * the same content, the exact case that needs it.
+ *
+ * The heading comparison is kept as a second chance, for a snapshot written before the anchor
+ * was read, or a part whose anchor line was edited by hand.
+ */
+declare function findSection(sections: readonly PartSection[], relativePath: string): PartSection | null;
+interface Window {
+    text: string;
+    fromLine: number;
+    returnedLines: number;
+    totalLines: number;
+    truncated: boolean;
+    nextFromLine: number | null;
+    /**
+     * True when `fromLine` is beyond the last line of the body.
+     *
+     * The start used to be clamped to the last line, so asking for line 9,000 of a 40-line file
+     * returned line 40 with a header that read `Lines 40–40 of 40` — a wrong answer dressed as a
+     * right one. The caller is told the request was out of range instead.
+     */
+    pastEnd: boolean;
+}
+/**
+ * Cuts a line window out of a body.
+ *
+ * Windows are the whole point of this module: a part holds hundreds of kilobytes, and the only
+ * safe default for a tool that returns content is "as little as answers the question". `next` is
+ * an explicit pointer rather than an instruction to keep reading, so an agent decides.
+ */
+declare function windowText(body: string, fromLine: number, lineCount: number): Window;
+
 declare function buildPrompts(): McpPrompt[];
 
 declare function buildResourceProvider(): ResourceProvider;
@@ -409,4 +477,4 @@ declare function validateArguments(schema: InputSchema, value: unknown): string[
  */
 declare function coerceNumericStrings(schema: InputSchema, value: JsonObject): JsonObject;
 
-export { ERROR_CODES, type JsonRpcResponse, type JsonSchema, LEGACY_PROTOCOL_VERSIONS, type LineReaderOptions, MAX_LINE_BYTES, METHOD, MODERN_PROTOCOL_VERSIONS, type McpPrompt, type McpResourceContents, type McpResourceDescriptor, type McpResourceTemplate, type McpServer, type McpServerInfo, type McpServerOptions, type McpTool, type MessageWriter, type ProtocolEra, type ResourceProvider, SERVER_INSTRUCTIONS, SUPPORTED_PROTOCOL_VERSIONS, type ServerOptions, type SessionState, type ToolAnnotations, type ToolContext, type ToolOutcome, buildPrompts, buildResourceProvider, buildTools, classifyRequest, coerceNumericStrings, createLineReader, createMcpServer, createServer, createSession, createWriter, inspectModernMeta, negotiateLegacyVersion, runStdioServer, validateArguments };
+export { ERROR_CODES, type JsonRpcResponse, type JsonSchema, LEGACY_PROTOCOL_VERSIONS, type LineReaderOptions, MAX_LINE_BYTES, METHOD, MODERN_PROTOCOL_VERSIONS, type McpPrompt, type McpResourceContents, type McpResourceDescriptor, type McpResourceTemplate, type McpServer, type McpServerInfo, type McpServerOptions, type McpTool, type MessageWriter, type PartSection, type ProtocolEra, type ResourceProvider, SERVER_INSTRUCTIONS, SUPPORTED_PROTOCOL_VERSIONS, type ServerOptions, type SessionState, type ToolAnnotations, type ToolContext, type ToolOutcome, type Window, buildPrompts, buildResourceProvider, buildTools, classifyRequest, coerceNumericStrings, createLineReader, createMcpServer, createServer, createSession, createWriter, findSection, inspectModernMeta, negotiateLegacyVersion, parsePartSections, runStdioServer, validateArguments, windowText };

package/dist/mcp.js

@@ -1,4 +1,2 @@
-export { ERROR_CODES, LEGACY_PROTOCOL_VERSIONS, MAX_LINE_BYTES, METHOD, MODERN_PROTOCOL_VERSIONS, SERVER_INSTRUCTIONS, SUPPORTED_PROTOCOL_VERSIONS, buildPrompts, buildResourceProvider, buildTools, classifyRequest, coerceNumericStrings, createLineReader, createMcpServer, createServer, createSession, createWriter, inspectModernMeta, negotiateLegacyVersion, runStdioServer, validateArguments } from './chunk-HQBEQ67K.js';
-import './chunk-KUVFTJHK.js';
-//# sourceMappingURL=mcp.js.map
-//# sourceMappingURL=mcp.js.map
+export { ERROR_CODES, LEGACY_PROTOCOL_VERSIONS, MAX_LINE_BYTES, METHOD, MODERN_PROTOCOL_VERSIONS, SERVER_INSTRUCTIONS, SUPPORTED_PROTOCOL_VERSIONS, buildPrompts, buildResourceProvider, buildTools, classifyRequest, coerceNumericStrings, createLineReader, createMcpServer, createServer, createSession, createWriter, findSection, inspectModernMeta, negotiateLegacyVersion, parsePartSections, runStdioServer, validateArguments, windowText } from './chunk-5OR3WVPW.js';
+export { generateInWorker } from './chunk-3H45YMBG.js';

package/dist/{types-Ca4PmkiQ.d.cts → types-CTewen3J.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). */

package/dist/{types-Ca4PmkiQ.d.ts → types-CTewen3J.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). */

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.12
    Added to .gitignore: snapshot/, snapshot.tmp/
 ⏳ Installing dependencies…
 ✅ Installed dependencies (npm install, 2.1s)
@@ -211,7 +211,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.12
    Added to .gitignore: snapshot/, snapshot.tmp/
 ```
 
@@ -378,7 +378,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,6 +401,7 @@ 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`. |
@@ -408,6 +409,12 @@ narrowest cases of the same rule.
 | `--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`. |
 | `--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 TypeScript and TSX signatures instead of bodies: each function or method body becomes `{ /* ... */ }` in place, so formatting and comments around it are untouched. 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. |
 | `--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`). |
@@ -430,6 +437,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.