codebase-snapshot 0.9.1 → 0.9.4

package/dist/mcp.d.ts

@@ -0,0 +1,399 @@
+import { Readable, Writable } from 'node:stream';
+
+/**
+ * JSON-RPC 2.0 envelopes and the Model Context Protocol revisions this server speaks.
+ *
+ * Two protocol eras coexist and this file is the only place that knows which revision belongs
+ * to which era. The legacy era (`2025-11-25` and earlier) opens every connection with an
+ * `initialize` handshake. The modern era (`2026-07-28`) removed the handshake: every request
+ * carries the protocol version and client capabilities in `_meta`, `server/discover` is
+ * mandatory, every result carries `resultType`, and `ping` no longer exists.
+ *
+ * The constants are read by the negotiation in `era.ts`, by the dispatch in `server.ts` and by
+ * the `describe` contract, so a revision cannot be added to one of them and forgotten in the
+ * others.
+ */
+/** A JSON object as it appears on the wire: the shape every `params`/`result` takes. */
+type JsonObject = Record<string, unknown>;
+type JsonRpcId = string | number;
+interface JsonRpcError {
+    code: number;
+    message: string;
+    data?: unknown;
+}
+interface JsonRpcSuccessResponse {
+    jsonrpc: "2.0";
+    id: JsonRpcId | null;
+    result: JsonObject;
+}
+interface JsonRpcErrorResponse {
+    jsonrpc: "2.0";
+    id: JsonRpcId | null;
+    error: JsonRpcError;
+}
+type JsonRpcResponse = JsonRpcSuccessResponse | JsonRpcErrorResponse;
+/**
+ * Revisions that open with the `initialize` handshake, newest first.
+ *
+ * The server echoes the requested revision when it is in this list and otherwise answers with
+ * the newest entry: the legacy lifecycle says a server that cannot speak the requested version
+ * responds with one it does speak, and the client decides whether to continue.
+ */
+declare const LEGACY_PROTOCOL_VERSIONS: readonly string[];
+/** Revisions that carry version and capabilities on every request, newest first. */
+declare const MODERN_PROTOCOL_VERSIONS: readonly string[];
+/** Everything advertised in `server/discover` and in an unsupported-version error. */
+declare const SUPPORTED_PROTOCOL_VERSIONS: readonly string[];
+/**
+ * JSON-RPC error codes, plus the one the modern era added.
+ *
+ * `-32022` is not a generic bad-params error: a client that receives it knows to read
+ * `data.supported` and retry with a mutually supported revision. Reporting it as `-32602`
+ * would leave a modern client with no way to recover.
+ */
+declare const ERROR_CODES: {
+    readonly parseError: -32700;
+    readonly invalidRequest: -32600;
+    readonly methodNotFound: -32601;
+    readonly invalidParams: -32602;
+    readonly internalError: -32603;
+    readonly unsupportedProtocolVersion: -32022;
+};
+/** Method names, kept as constants so a typo is a compile error rather than a `-32601`. */
+declare const METHOD: {
+    readonly initialize: "initialize";
+    readonly initialized: "notifications/initialized";
+    readonly discover: "server/discover";
+    readonly ping: "ping";
+    readonly toolsList: "tools/list";
+    readonly toolsCall: "tools/call";
+    readonly resourcesList: "resources/list";
+    readonly resourcesRead: "resources/read";
+    readonly resourceTemplatesList: "resources/templates/list";
+    readonly promptsList: "prompts/list";
+    readonly promptsGet: "prompts/get";
+    readonly cancelled: "notifications/cancelled";
+};
+/**
+ * A JSON Schema subset, as far as this server needs it.
+ *
+ * Deliberately not `unknown`: the tool table is authored by hand, and the compiler catching a
+ * misspelled keyword is worth more than accepting every dialect feature we never emit.
+ */
+interface JsonSchema {
+    type?: "object" | "string" | "number" | "integer" | "boolean" | "array";
+    description?: string;
+    properties?: Record<string, JsonSchema>;
+    required?: string[];
+    items?: JsonSchema;
+    enum?: readonly string[];
+    default?: string | number | boolean;
+    additionalProperties?: boolean;
+    minimum?: number;
+    maximum?: number;
+    minLength?: number;
+    maxLength?: number;
+}
+/** An `inputSchema` root: MCP requires a top-level object schema. */
+interface InputSchema extends JsonSchema {
+    type: "object";
+    properties: Record<string, JsonSchema>;
+}
+
+type ProtocolEra = "legacy" | "modern";
+/** Per-connection state. The modern era has no session, so this stays empty until legacy init. */
+interface SessionState {
+    /** Which era the connection committed to, or null before the first decisive request. */
+    era: ProtocolEra | null;
+    /** The revision in force. Null in legacy until `initialize` has been negotiated. */
+    protocolVersion: string | null;
+    /** True once `initialize` has been answered, which is the legacy lifecycle's gate. */
+    ready: boolean;
+}
+declare function createSession(): SessionState;
+/** The modern request metadata, when a request carries it at all. */
+interface ModernMeta {
+    version: string;
+    clientCapabilities: JsonObject;
+    clientInfo: JsonObject | null;
+}
+type MetaInspection = {
+    kind: "absent";
+} | {
+    kind: "incomplete";
+    missing: string;
+} | {
+    kind: "present";
+    meta: ModernMeta;
+};
+/**
+ * Reads `_meta` from a request.
+ *
+ * `absent` and `incomplete` are different answers: a request with no `_meta` at all is a legacy
+ * client, while a request with `_meta` that lacks a required key is a modern client making a
+ * mistake — and telling those two apart is what keeps the legacy era from being rejected for a
+ * field it never had.
+ */
+declare function inspectModernMeta(params: JsonObject | undefined): MetaInspection;
+type EraDecision = {
+    kind: "era";
+    era: ProtocolEra;
+    version: string | null;
+} | {
+    kind: "error";
+    code: number;
+    message: string;
+    data?: unknown;
+};
+/**
+ * Decides which era a request belongs to, and whether its version is acceptable.
+ *
+ * Once a connection commits to an era it stays committed. A legacy client that suddenly sends
+ * modern `_meta` is confused rather than clever, and silently switching would answer half a
+ * session in each shape.
+ */
+declare function classifyRequest(method: string, params: JsonObject | undefined, session: SessionState): EraDecision;
+interface LegacyNegotiation {
+    version: string;
+    /** False when the client asked for something we cannot speak and was negotiated down. */
+    matched: boolean;
+}
+/**
+ * Legacy version negotiation: echo a supported request, otherwise answer with our best.
+ *
+ * A client that asked for a modern revision here gets the newest *legacy* revision, not an error:
+ * under this lifecycle the server's answer is the offer, and the client decides.
+ */
+declare function negotiateLegacyVersion(requested: unknown): LegacyNegotiation;
+
+/**
+ * The capability records the MCP server serves.
+ *
+ * These are the shapes the protocol layer deals in, kept apart from the handlers that fill them so
+ * the server can be tested with a fixed set of stubs and the tool table can be built without a
+ * running transport.
+ */
+
+/** Everything a handler may touch. Deliberately small: no transport, no session, no protocol. */
+interface ToolContext {
+    /** Repository the server was launched for; every relative path resolves against it. */
+    cwd: string;
+    /** Absolute directories a `root` argument is allowed to resolve into. */
+    roots: string[];
+    /** Writes one line to stderr. Never stdout, which carries protocol messages only. */
+    log: (line: string) => void;
+}
+/**
+ * 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
+ * read-only and only `snapshot_generate` prompts.
+ */
+interface ToolAnnotations {
+    readOnlyHint: boolean;
+    destructiveHint: boolean;
+    idempotentHint: boolean;
+    openWorldHint: boolean;
+}
+/** What a handler returns. The protocol layer turns this into a `CallToolResult`. */
+interface ToolOutcome {
+    /** The text block a model reads. Keep it short: bulk content belongs in a windowed read. */
+    text: string;
+    /** Typed mirror of `text`, declared by the tool's `outputSchema`. */
+    structured?: JsonObject;
+    /** True for a tool-level failure. Reported inside the result, not as a JSON-RPC error. */
+    isError?: boolean;
+}
+interface McpTool {
+    name: string;
+    title: string;
+    description: string;
+    inputSchema: InputSchema;
+    outputSchema?: InputSchema;
+    annotations: ToolAnnotations;
+    handler(args: JsonObject, context: ToolContext): Promise<ToolOutcome>;
+}
+/** One addressable resource, as `resources/list` reports it. */
+interface McpResourceDescriptor {
+    uri: string;
+    name: string;
+    title?: string;
+    description: string;
+    mimeType: string;
+}
+interface McpResourceContents {
+    uri: string;
+    mimeType: string;
+    text: string;
+}
+/** A parameterised resource family, as `resources/templates/list` reports it. */
+interface McpResourceTemplate {
+    uriTemplate: string;
+    name: string;
+    title?: string;
+    description: string;
+    mimeType: string;
+}
+/**
+ * Resources are computed per call rather than declared once.
+ *
+ * The list depends on what is on disk — a snapshot that has not been generated has manifest
+ * resources that do not exist yet — so a static table would advertise resources whose read then
+ * fails, which is worse than an honest short list.
+ */
+interface ResourceProvider {
+    list(context: ToolContext): Promise<McpResourceDescriptor[]>;
+    templates(): McpResourceTemplate[];
+    /** Resolves one URI. Returns null when this server does not own it. */
+    read(uri: string, context: ToolContext): Promise<McpResourceContents | null>;
+}
+interface PromptArgument {
+    name: string;
+    description: string;
+    required: boolean;
+}
+interface PromptMessage {
+    role: "user" | "assistant";
+    content: {
+        type: "text";
+        text: string;
+    };
+}
+interface McpPrompt {
+    name: string;
+    title?: string;
+    description: string;
+    arguments: PromptArgument[];
+    build(args: JsonObject): {
+        description: string;
+        messages: PromptMessage[];
+    };
+}
+/** Identity reported at handshake and in every modern result's `_meta`. */
+interface McpServerInfo {
+    name: string;
+    title: string;
+    version: string;
+    websiteUrl: string;
+}
+
+interface McpServerOptions {
+    info: McpServerInfo;
+    instructions: string;
+    tools: McpTool[];
+    resources: ResourceProvider;
+    prompts: McpPrompt[];
+    context: ToolContext;
+}
+interface McpServer {
+    /** Handles one already-parsed message. Returns null when no response is due. */
+    handle(message: unknown): Promise<JsonRpcResponse | null>;
+    /** Exposed for tests and for `mcp --list`, which prints the negotiation table. */
+    readonly session: SessionState;
+}
+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[];
+
+declare function buildPrompts(): McpPrompt[];
+
+declare function buildResourceProvider(): ResourceProvider;
+
+interface ServerOptions {
+    /** Repository the tools operate on. Also the only directory they may read. */
+    cwd: string;
+    /** Additional directories callers may name as `root`. Defaults to `cwd` alone. */
+    roots?: string[];
+    /** Where operational notes go. Never stdout, which carries protocol messages only. */
+    log?: (line: string) => void;
+}
+/** Builds a server with every capability this package implements. */
+declare function createServer(options: ServerOptions): McpServer;
+/**
+ * Serves MCP over stdio until the client closes the stream.
+ *
+ * Writes are serialised through one promise chain: two tool calls finishing together must not
+ * interleave half-written lines, and a single response can be large. Reading is not serialised —
+ * a slow tool must not stop a cancellation notification from being read — and the process waits
+ * for every accepted request to answer before it resolves.
+ */
+declare function runStdioServer(options: ServerOptions): Promise<number>;
+
+/**
+ * The stdio transport: one JSON-RPC message per line, UTF-8, nothing else on the stream.
+ *
+ * MCP's stdio binding is newline-delimited JSON, not LSP's `Content-Length` framing, and the
+ * server MUST NOT write anything to stdout that is not a valid message. `JSON.stringify` escapes
+ * newlines inside strings, so serialising a message can never produce a second line — the writer
+ * deliberately does not pretty-print, because `JSON.stringify(value, null, 2)` would.
+ *
+ * Framing is separated from parsing on purpose: this module hands raw lines to its caller and the
+ * server decides what a bad line means (a `-32700` response), which keeps the line splitting
+ * testable without a running server.
+ */
+
+/**
+ * Largest single message this transport will buffer.
+ *
+ * A line with no newline grows the buffer until the process runs out of memory, so an oversized
+ * message is discarded rather than accepted: the snapshot itself is never this large, and a
+ * client that streams more than this is not sending a message.
+ */
+declare const MAX_LINE_BYTES: number;
+interface MessageWriter {
+    /** Serialises one message onto the stream. Rejects if the stream reports a write error. */
+    write(value: unknown): Promise<void>;
+}
+/**
+ * Creates a writer that emits exactly one line per message.
+ *
+ * Writes are awaited through the stream's callback rather than fire-and-forget: a tool result can
+ * be tens of kilobytes, and queueing several without backpressure interleaves them with the next
+ * response on a slow pipe.
+ */
+declare function createWriter(output: Writable): MessageWriter;
+interface LineReaderOptions {
+    /** Called for every complete, non-empty line, with the trailing CR already removed. */
+    onLine: (line: string) => void;
+    /** Called when one line exceeds {@link MAX_LINE_BYTES}; the line is discarded. */
+    onOverflow?: (bytes: number) => void;
+}
+/**
+ * Reads newline-delimited lines from `input` until it ends.
+ *
+ * Three details are what make this work against real clients rather than against our own tests:
+ * a chunk boundary can fall anywhere inside a line (including inside a multi-byte character,
+ * which `setEncoding` handles); a Windows client may terminate lines with CRLF; and the final
+ * line may arrive without a newline before the stream ends.
+ *
+ * Returns a function that removes the listeners, so a caller can shut a transport down without
+ * racing a late `end` event.
+ */
+declare function createLineReader(input: Readable, options: LineReaderOptions): () => void;
+
+/**
+ * The instructions an MCP client shows its model at handshake.
+ *
+ * This text is the cheapest documentation the project has: it arrives before the first tool call,
+ * in the model's own context, on every client that supports the field. It is therefore about
+ * *order* rather than features — an agent that reads a part end to end has already lost the
+ * budget this tool exists to protect.
+ */
+declare const SERVER_INSTRUCTIONS: string;
+
+/**
+ * A JSON Schema checker for tool arguments, sized to the schemas this server publishes.
+ *
+ * The alternative was Ajv, which is the right answer for arbitrary schemas and the wrong one for
+ * a package whose single dependency is a compiler. Every schema here is a flat object of scalar
+ * properties, so the checker is small, readable and — unlike a general-purpose validator — it can
+ * reject unknown properties by default, which is what turns an agent's typo (`maxPartByte`) into a
+ * named error instead of a silently ignored option.
+ */
+
+/** Human-readable problems, each prefixed with the argument path that caused it. */
+declare function validateArguments(schema: InputSchema, value: unknown): string[];
+
+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, createLineReader, createMcpServer, createServer, createSession, createWriter, inspectModernMeta, negotiateLegacyVersion, runStdioServer, validateArguments };

package/dist/mcp.js

@@ -0,0 +1,4 @@
+export { ERROR_CODES, LEGACY_PROTOCOL_VERSIONS, MAX_LINE_BYTES, METHOD, MODERN_PROTOCOL_VERSIONS, SERVER_INSTRUCTIONS, SUPPORTED_PROTOCOL_VERSIONS, buildPrompts, buildResourceProvider, buildTools, classifyRequest, createLineReader, createMcpServer, createServer, createSession, createWriter, inspectModernMeta, negotiateLegacyVersion, runStdioServer, validateArguments } from './chunk-EWZYK3VX.js';
+import './chunk-FCWD4LY7.js';
+//# sourceMappingURL=mcp.js.map
+//# sourceMappingURL=mcp.js.map

package/docs/agent.md

@@ -22,6 +22,26 @@ npx codebase-snapshot validate
 The bare package name works; pin an exact version (`npx codebase-snapshot --version` prints the current one) when the same version must run on every
 machine.
 
+### One command instead of three
+
+```bash
+npx codebase-snapshot --autopilot
+```
+
+Sets the project up — config, npm scripts, devDependency, `.gitignore`, install — and generates,
+with no prompts. It keeps an existing config, and `--no-install` avoids touching the lockfile.
+`setup` is the same operation as a command word.
+
+### Do not rely on the bare command
+
+```bash
+npx codebase-snapshot          # ❌ in an unconfigured project this exits 2
+```
+
+An agent has no terminal, so the guided first run cannot ask its question and refuses instead of
+generating with settings nobody chose. That exit `2` is the tool being honest, not broken: say
+which setup you want — `--autopilot`, `init --yes`, or `generate` on the documented defaults.
+
 ## The contract
 
 `describe --format json` returns the whole tool as data on stdout:
@@ -93,6 +113,22 @@ added.
 `codebase-snapshot init` does none of this: it writes the config, the npm scripts, the
 devDependency and the `.gitignore` entries for the snapshot directory, and nothing else.
 
+## When the client speaks MCP
+
+`codebase-snapshot mcp` serves the repository to a Model Context Protocol client over stdio: seven
+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:
+
+- **Reads come from the snapshot, not the working tree.** `snapshot_read` extracts a file's section
+  from the emitted part, so a file the snapshot excluded cannot be read back and a redacted value
+  stays redacted.
+- **Staleness is a first-class question.** `snapshot_validate` answers "has the code moved since
+  this was built", which an agent with only a filesystem tool has no way to ask.
+
+The tools are listed in [the MCP guide](mcp.md) and in the `mcp` block of
+`describe --format json`. A `root` argument may name a sub-directory of the directory the server was
+started for, and nothing outside it.
+
 ## Why both a contract and a skill
 
 The contract is for **doing** — the data an agent needs to pick correct commands and options.

package/docs/cli.md

@@ -4,12 +4,53 @@
 npx codebase-snapshot <command> [options]
 ```
 
-The package installs one executable, **`codebase-snapshot`**, with a short alias **`snap`**.
-Both are the same file. After `npx codebase-snapshot generate` the command
-becomes available as `npx codebase-snapshot` for the rest of that session; after
-`npm install -D` use `npx codebase-snapshot` or `npx snap` from the project.
+The package installs one executable under two names: **`codebase-snapshot`** (canonical, and the
+one to script against) and **`snapshot`** (the short command a global install puts on your
+`PATH`). Both are the same file. From a project dependency use `npx codebase-snapshot` or
+`npx snapshot` — both resolve the local copy first.
 
-Running with no command is the same as `generate`.
+Running with no command is the guided first run: in a project with no configuration it asks
+once, sets the project up and generates; in a configured project it is the same as `generate`.
+Naming the command (`codebase-snapshot generate`) always means "do exactly this", on the
+documented defaults. `--autopilot` sets the project up first without asking.
+
+```bash
+snapshot                     # global install: guided first run, then generate
+npx codebase-snapshot        # the same, from a project dependency
+npx codebase-snapshot --autopilot   # the same with no questions
+```
+
+## The first run
+
+```bash
+snapshot                # global install
+npx codebase-snapshot   # from a project dependency
+```
+
+In a project with no configuration the tool reports what it recognised **and what it keyed on**,
+then asks one question:
+
+```
+  codebase-snapshot
+
+  Detected   nextjs
+  Because    next.config.ts
+  Directory  /Users/you/app
+
+  ◆ How should I set this up?
+    ❯ Use the recommended setup      nextjs · config · npm scripts · install · generate
+      Go through each setting        every question starts on its default
+      Pick a different preset        everything else stays at the defaults
+```
+
+The first entry is the whole setup in one keystroke. The second walks through the settings, and
+every prompt starts on its answer, so pressing `enter` through the lot is the recommended setup
+spelled out. When nothing matched, the tool says so, names the manifests it looked for, and asks
+which preset is closest — the one case where it needs an answer it cannot find itself.
+
+A project that already has a config, or one this tool generated before, skips all of it and just
+generates. `--autopilot` does the same work with no questions at all, and reports each decision
+as it makes it.
 
 ## Contents
 
@@ -17,6 +58,7 @@ Running with no command is the same as `generate`.
   - [`generate`](#generate)
   - [`validate` / `check`](#validate--check)
   - [`report`](#report)
+  - [`setup`](#setup)
   - [`init`](#init)
   - [`explain <path>`](#explain-path)
   - [`diff <before> <after>`](#diff-before-after)
@@ -35,8 +77,15 @@ Running with no command is the same as `generate`.
 codebase-snapshot generate [options]
 ```
 
-Scans the repository and writes the snapshot to `outDir` (default `./snapshot`). This is the
-default command, so `codebase-snapshot` alone does the same thing.
+Scans the repository and writes the snapshot to `outDir` (default `./snapshot`).
+
+Naming the command is the deterministic form: it runs on the documented defaults and writes nothing
+but the snapshot. Without a command word an unconfigured project gets the
+[guided first run](#the-first-run) first; `--autopilot` asks for that setup from an explicit
+`generate` too, and never prompts.
+
+A first run neither form can resolve — no config, no previous snapshot, no `--autopilot`, no
+terminal — exits `2` and names the alternatives. It does not quietly generate on defaults.
 
 Detection is automatic: a preset is chosen from the 25 in the
 [preset table](configuration.md#project-presets), which supplies layers, kinds and ecosystem
@@ -107,7 +156,8 @@ is `validate`, which re-reads the repository and exits `1` on drift.
 codebase-snapshot setup
 ```
 
-The whole first run in one command, with defaults and no prompts:
+The whole first run in one command, with defaults and no prompts. This is the same implementation
+`--autopilot` uses, spelled as a command word:
 
 1. Detects the project preset.
 2. Writes `snapshot.config.ts` (or `.mjs`) — **only when the repository has none**. An existing
@@ -124,7 +174,7 @@ The whole first run in one command, with defaults and no prompts:
 🚀 Setup for: /path/to/repo
 ✅ Created snapshot.config.ts (preset: nextjs)
    Added npm scripts: snapshot, snapshot:validate
-   Added devDependency: codebase-snapshot ^0.9.1
+   Added devDependency: codebase-snapshot ^0.9.4
    Added to .gitignore: snapshot/, snapshot.tmp/
 ⏳ Installing dependencies…
 ✅ Installed dependencies (npm install, 2.1s)
@@ -161,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.1
+   Added devDependency: codebase-snapshot ^0.9.4
    Added to .gitignore: snapshot/, snapshot.tmp/
 ```
 
@@ -311,6 +361,25 @@ unchanged, plus the ignore entries it added.
 
 Printing goes to **stdout** so it can be redirected: `codebase-snapshot skill > SKILL.md`.
 
+### `mcp`
+
+```bash
+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://`
+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.
+
+`--cwd` is the only directory it will read. A tool's `root` argument can name a sub-directory of it
+and nothing outside, symlinks included. It never installs packages and never writes a config file.
+
+There is no `--format` here, because stdout *is* the protocol stream. The full tool list, resource
+URIs and protocol versions appear in [the MCP server guide](mcp.md) and in
+`describe --format json` under `mcp`.
+
 ## Options
 
 An option a command does not accept is **rejected**, not ignored: exit `2` and a message
@@ -328,9 +397,11 @@ narrowest cases of the same rule.
 | `--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`. |
-| `--format <text\|json>` | enum | `text` | generate, validate, report, explain, init, diff, describe, skill | `json` writes a pure JSON payload to stdout. Every command honours it, and `describe` reports the same eight-command list. |
-| `--dry-run` | flag | off | generate, init | Compute everything, print it, write nothing. |
+| `--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. |
+| `--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`). |
+| `--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. |
 | `--discovery <mode>` | enum | `auto` | generate, validate, explain | How files are found: `auto` lists through git when git works and refuses when a `.git` directory cannot be listed; `git` requires git; `walk` scans the tree and reads `.gitignore` files directly. The escape hatch for a broken `.git`. |
 | `--preset <name>` | name | detected | *init only* | Force a preset instead of detecting one. |
@@ -341,7 +412,7 @@ narrowest cases of the same rule.
 | `--install` | flag | off | *skill only* | Write the skill into the repository instead of printing it. |
 | `--target <name>` | enum | `all` | *skill only* | `claude`, `cursor` or `all`. |
 | `-h`, `--help` | flag | — | every command | Print usage. |
-| `-v`, `--version` | flag | — | every command | Print the version on stdout: a bare `v`-prefixed semver such as `v4.0.0`, with no package name. |
+| `-v`, `--version` | flag | — | every command | Print the version on stdout: a bare `v`-prefixed semver (for example `v1.2.3`), with no package name. |
 
 The artifact and size options apply to `validate`, `report` and `explain` as well as
 `generate` because those commands re-read the snapshot: pass the selection you generated
@@ -373,7 +444,7 @@ reason to use it, and the positional form is the documented one.
 | :--- | :--- |
 | `0` | Success. For `validate`/`check`, no drift. |
 | `1` | Drift detected, generation refused or failed (nothing was written), or the state the command needed was not there. |
-| `2` | Usage error: unknown flag or command, an option the command does not accept, bad value, wrong argument count. |
+| `2` | Usage error: unknown flag or command, an option the command does not accept, bad value, wrong argument count. Also a first run that needs an answer and has no terminal — run `--autopilot`, `init --yes`, or name the command. |
 
 `1` covers the cases where the tool did the right thing but the state is not what you wanted
 — drift, a refused output directory, an unparseable config. `2` means the command itself was