codebase-snapshot 0.9.1 → 0.9.5

package/dist/bin.js

@@ -2,8 +2,8 @@
 
 // src/cli.ts
 import { spawnSync } from "child_process";
-import * as fs12 from "fs";
-import * as path13 from "path";
+import * as fs16 from "fs";
+import * as path17 from "path";
 import { parseArgs } from "util";
 
 // src/diff.ts
@@ -167,8 +167,8 @@ function workspacePackageDirs(cwd, patterns) {
 function scanWorkspacePackages(cwd, patterns) {
   const files = /* @__PURE__ */ new Set();
   const dependencies = /* @__PURE__ */ new Set();
-  for (const relative8 of workspacePackageDirs(cwd, patterns)) {
-    const full = path.join(cwd, relative8);
+  for (const relative11 of workspacePackageDirs(cwd, patterns)) {
+    const full = path.join(cwd, relative11);
     try {
       for (const entry of fs.readdirSync(full, { withFileTypes: true })) files.add(entry.name);
     } catch {
@@ -245,25 +245,41 @@ function buildPresetContext(cwd) {
     markdownCount: files.has("package.json") ? 0 : countMarkdownFiles(cwd)
   };
 }
-function hasFile(context, name) {
-  return context.files.has(name);
+
+// src/presets/evidence.ts
+function fileEvidence(context, name) {
+  return context.files.has(name) ? name : null;
 }
-function hasFileStartingWith(context, prefix) {
+function fileStartingWithEvidence(context, prefix) {
   for (const file of context.files) {
-    if (file.startsWith(prefix)) return true;
+    if (file.startsWith(prefix)) return file;
   }
   for (const file of context.workspaceFiles) {
-    if (file.startsWith(prefix)) return true;
+    if (file.startsWith(prefix)) return file;
   }
-  return false;
+  return null;
+}
+function dependencyEvidence(context, ...names) {
+  for (const name of names) {
+    if (context.dependencies.has(name)) return `depends on ${name}`;
+  }
+  return null;
 }
-function manifestContains(context, manifest, needle) {
+function manifestEvidence(context, manifest, needle) {
   const content = context.manifests[manifest];
-  if (!content) return false;
-  return content.toLowerCase().includes(needle.toLowerCase());
+  if (!content) return null;
+  if (!content.toLowerCase().includes(needle.toLowerCase())) return null;
+  return `${needle} in ${manifest}`;
+}
+function suffixEvidence(context, suffix) {
+  for (const file of context.files) {
+    if (file.endsWith(suffix)) return file;
+  }
+  return null;
 }
-function hasDependency(context, ...names) {
-  return names.some((name) => context.dependencies.has(name));
+function markdownEvidence(context) {
+  if (context.markdownCount < 3 || context.files.has("package.json")) return null;
+  return `${context.markdownCount} markdown files, no package.json`;
 }
 
 // src/presets/helpers.ts
@@ -471,7 +487,7 @@ var JS_PRESETS = [
   {
     name: "nextjs",
     priority: 100,
-    detect: (context) => hasFileStartingWith(context, "next.config") || hasDependency(context, "next"),
+    detect: (context) => fileStartingWithEvidence(context, "next.config") ?? dependencyEvidence(context, "next"),
     layers: NEXTJS_LAYERS,
     kinds: NEXTJS_KINDS,
     exclude: NEXT_LIKE_EXCLUDES,
@@ -480,7 +496,7 @@ var JS_PRESETS = [
   {
     name: "nuxt",
     priority: 98,
-    detect: (context) => hasFileStartingWith(context, "nuxt.config") || hasDependency(context, "nuxt", "nuxt3"),
+    detect: (context) => fileStartingWithEvidence(context, "nuxt.config") ?? dependencyEvidence(context, "nuxt", "nuxt3"),
     layers: [
       layer("pages", "pages/", "src/pages/"),
       layer("components", "components/", "src/components/"),
@@ -504,7 +520,7 @@ var JS_PRESETS = [
   {
     name: "sveltekit",
     priority: 96,
-    detect: (context) => hasFileStartingWith(context, "svelte.config") || hasDependency(context, "@sveltejs/kit", "svelte"),
+    detect: (context) => fileStartingWithEvidence(context, "svelte.config") ?? dependencyEvidence(context, "@sveltejs/kit", "svelte"),
     layers: [
       layer("routes", "src/routes/", "routes/"),
       layer("lib", "src/lib/", "lib/"),
@@ -525,7 +541,7 @@ var JS_PRESETS = [
   {
     name: "remix",
     priority: 94,
-    detect: (context) => hasDependency(context, "@remix-run/react", "@remix-run/node", "@remix-run/dev"),
+    detect: (context) => dependencyEvidence(context, "@remix-run/react", "@remix-run/node", "@remix-run/dev"),
     layers: [
       layer("routes", "app/routes/", "routes/"),
       layer("components", "app/components/"),
@@ -539,7 +555,7 @@ var JS_PRESETS = [
   {
     name: "astro",
     priority: 92,
-    detect: (context) => hasFileStartingWith(context, "astro.config") || hasDependency(context, "astro"),
+    detect: (context) => fileStartingWithEvidence(context, "astro.config") ?? dependencyEvidence(context, "astro"),
     layers: [
       layer("pages", "src/pages/"),
       layer("layouts", "src/layouts/"),
@@ -554,7 +570,7 @@ var JS_PRESETS = [
   {
     name: "angular",
     priority: 90,
-    detect: (context) => hasFile(context, "angular.json") || hasDependency(context, "@angular/core"),
+    detect: (context) => fileEvidence(context, "angular.json") ?? dependencyEvidence(context, "@angular/core"),
     layers: [
       layer("app", "src/app/"),
       layer("features", "src/app/features/"),
@@ -578,7 +594,7 @@ var JS_PRESETS = [
   {
     name: "solid",
     priority: 88,
-    detect: (context) => hasDependency(context, "solid-js", "solid-start"),
+    detect: (context) => dependencyEvidence(context, "solid-js", "solid-start"),
     layers: [
       layer("pages", "src/routes/", "src/pages/"),
       layer("components", "src/components/"),
@@ -591,7 +607,15 @@ var JS_PRESETS = [
   {
     name: "vue-vite",
     priority: 86,
-    detect: (context) => hasDependency(context, "vue") && (hasDependency(context, "vite") || hasFileStartingWith(context, "vite.config")),
+    // `vue` is the decisive signal; `vite` (or its config file) only says the app is
+    // built with Vite rather than shipped pre-compiled, so it is required but not what
+    // gets reported.
+    detect: (context) => {
+      const framework = dependencyEvidence(context, "vue");
+      if (framework === null) return null;
+      const build = dependencyEvidence(context, "vite") ?? fileStartingWithEvidence(context, "vite.config");
+      return build === null ? null : framework;
+    },
     layers: [
       layer("pages", "src/pages/", "src/views/"),
       layer("components", "src/components/"),
@@ -616,7 +640,12 @@ var JS_PRESETS = [
   {
     name: "react-vite",
     priority: 84,
-    detect: (context) => hasDependency(context, "react") && (hasDependency(context, "vite") || hasFileStartingWith(context, "vite.config")),
+    detect: (context) => {
+      const framework = dependencyEvidence(context, "react");
+      if (framework === null) return null;
+      const build = dependencyEvidence(context, "vite") ?? fileStartingWithEvidence(context, "vite.config");
+      return build === null ? null : framework;
+    },
     layers: VITE_LAYERS,
     kinds: VITE_KINDS,
     exclude: [".vite", "dist"],
@@ -625,7 +654,7 @@ var JS_PRESETS = [
   {
     name: "nest",
     priority: 80,
-    detect: (context) => hasDependency(context, "@nestjs/core"),
+    detect: (context) => dependencyEvidence(context, "@nestjs/core"),
     layers: [
       layer("modules", "src/modules/", "modules/"),
       layer("controllers", "src/controllers/", "controllers/"),
@@ -651,7 +680,7 @@ var JS_PRESETS = [
   {
     name: "node-express",
     priority: 78,
-    detect: (context) => hasDependency(context, "express", "fastify", "koa", "@hapi/hapi"),
+    detect: (context) => dependencyEvidence(context, "express", "fastify", "koa", "@hapi/hapi"),
     layers: NODE_LAYERS,
     kinds: NODE_KINDS,
     exclude: ["dist"],
@@ -662,7 +691,7 @@ var JS_PRESETS = [
     // A bare package.json is often just tooling around a non-JS project, so it
     // ranks below every definitive language manifest.
     priority: 45,
-    detect: (context) => hasFile(context, "package.json"),
+    detect: (context) => fileEvidence(context, "package.json"),
     layers: [
       layer("src", "src/"),
       layer("lib", "lib/"),
@@ -676,13 +705,12 @@ var JS_PRESETS = [
 ];
 
 // src/presets/lang-presets.ts
-var anyFileEndingWith = (context, suffix) => Array.from(context.files).some((file) => file.endsWith(suffix));
 var DIR = (name) => `${name}/`;
 var LANGUAGE_PRESETS = [
   {
     name: "python-django",
     priority: 56,
-    detect: (context) => hasFile(context, "manage.py") || manifestContains(context, "pyproject.toml", "django") || manifestContains(context, "requirements.txt", "django"),
+    detect: (context) => fileEvidence(context, "manage.py") ?? manifestEvidence(context, "pyproject.toml", "django") ?? manifestEvidence(context, "requirements.txt", "django"),
     layers: [
       layer("views", DIR("views"), DIR("app/views"), DIR("apps/views")),
       layer("models", DIR("models"), DIR("app/models"), DIR("apps/models")),
@@ -708,7 +736,7 @@ var LANGUAGE_PRESETS = [
   {
     name: "python-fastapi",
     priority: 54,
-    detect: (context) => manifestContains(context, "requirements.txt", "fastapi") || manifestContains(context, "requirements.txt", "flask") || manifestContains(context, "pyproject.toml", "fastapi") || manifestContains(context, "pyproject.toml", "flask"),
+    detect: (context) => manifestEvidence(context, "requirements.txt", "fastapi") ?? manifestEvidence(context, "requirements.txt", "flask") ?? manifestEvidence(context, "pyproject.toml", "fastapi") ?? manifestEvidence(context, "pyproject.toml", "flask"),
     layers: [
       layer("routers", DIR("routers"), DIR("routes"), DIR("api")),
       layer("models", DIR("models"), DIR("db")),
@@ -732,7 +760,7 @@ var LANGUAGE_PRESETS = [
     name: "python-lib",
     // Below node-lib: a Node repo with a stray .py file is still a Node repo.
     priority: 30,
-    detect: (context) => hasFile(context, "pyproject.toml") || hasFile(context, "setup.py") || hasFile(context, "requirements.txt") || anyFileEndingWith(context, ".py"),
+    detect: (context) => fileEvidence(context, "pyproject.toml") ?? fileEvidence(context, "setup.py") ?? fileEvidence(context, "requirements.txt") ?? suffixEvidence(context, ".py"),
     layers: [
       layer("package", DIR("src"), DIR("lib")),
       layer("tests", DIR("tests"), DIR("test")),
@@ -745,7 +773,7 @@ var LANGUAGE_PRESETS = [
   {
     name: "go",
     priority: 50,
-    detect: (context) => hasFile(context, "go.mod"),
+    detect: (context) => fileEvidence(context, "go.mod"),
     layers: [
       layer("cmd", "cmd/"),
       layer("internal", "internal/"),
@@ -769,7 +797,7 @@ var LANGUAGE_PRESETS = [
   {
     name: "rust",
     priority: 48,
-    detect: (context) => hasFile(context, "Cargo.toml"),
+    detect: (context) => fileEvidence(context, "Cargo.toml"),
     layers: [
       layer("src", "src/"),
       layer("crates", "crates/"),
@@ -785,7 +813,7 @@ var LANGUAGE_PRESETS = [
   {
     name: "java-spring",
     priority: 46,
-    detect: (context) => hasFile(context, "pom.xml") || hasFile(context, "build.gradle") || hasFile(context, "build.gradle.kts"),
+    detect: (context) => fileEvidence(context, "pom.xml") ?? fileEvidence(context, "build.gradle") ?? fileEvidence(context, "build.gradle.kts"),
     layers: [
       layer("api", "src/main/java/"),
       layer("test", "src/test/java/"),
@@ -808,7 +836,7 @@ var LANGUAGE_PRESETS = [
   {
     name: "dotnet",
     priority: 44,
-    detect: (context) => anyFileEndingWith(context, ".csproj") || anyFileEndingWith(context, ".sln") || hasFile(context, "global.json"),
+    detect: (context) => suffixEvidence(context, ".csproj") ?? suffixEvidence(context, ".sln") ?? fileEvidence(context, "global.json"),
     layers: [
       layer("web", "src/", "Web/"),
       layer("domain", "Domain/", "Core/"),
@@ -831,7 +859,7 @@ var LANGUAGE_PRESETS = [
   {
     name: "php-laravel",
     priority: 42,
-    detect: (context) => hasFile(context, "artisan") || manifestContains(context, "composer.json", "laravel") || hasFile(context, "composer.json"),
+    detect: (context) => fileEvidence(context, "artisan") ?? manifestEvidence(context, "composer.json", "laravel") ?? fileEvidence(context, "composer.json"),
     layers: [
       layer("app", "app/"),
       layer("routes", "routes/"),
@@ -857,7 +885,7 @@ var LANGUAGE_PRESETS = [
   {
     name: "ruby-rails",
     priority: 40,
-    detect: (context) => hasFile(context, "Gemfile") || hasFile(context, "config.ru") || hasFile(context, "Rakefile"),
+    detect: (context) => fileEvidence(context, "Gemfile") ?? fileEvidence(context, "config.ru") ?? fileEvidence(context, "Rakefile"),
     layers: [
       layer("app", "app/"),
       layer("controllers", "app/controllers/"),
@@ -930,7 +958,7 @@ var SHAPE_PRESETS = [
   {
     name: "monorepo",
     priority: 70,
-    detect: (context) => hasFile(context, "pnpm-workspace.yaml") || hasFile(context, "nx.json") || hasFile(context, "turbo.json") || hasFile(context, "lerna.json") || manifestContains(context, "package.json", '"workspaces"'),
+    detect: (context) => fileEvidence(context, "pnpm-workspace.yaml") ?? fileEvidence(context, "nx.json") ?? fileEvidence(context, "turbo.json") ?? fileEvidence(context, "lerna.json") ?? manifestEvidence(context, "package.json", '"workspaces"'),
     layers: [
       layer("apps", "apps/"),
       layer("packages", "packages/"),
@@ -944,7 +972,7 @@ var SHAPE_PRESETS = [
   {
     name: "infra",
     priority: 24,
-    detect: (context) => Array.from(context.files).some((file) => file.endsWith(".tf")) || hasFile(context, "Chart.yaml") || hasFile(context, "kustomization.yaml") || hasFile(context, "docker-compose.yml") || hasFile(context, "docker-compose.yaml"),
+    detect: (context) => suffixEvidence(context, ".tf") ?? fileEvidence(context, "Chart.yaml") ?? fileEvidence(context, "kustomization.yaml") ?? fileEvidence(context, "docker-compose.yml") ?? fileEvidence(context, "docker-compose.yaml"),
     layers: [
       layer("modules", "modules/"),
       layer("environments", "env/", "environments/"),
@@ -966,7 +994,7 @@ var SHAPE_PRESETS = [
     // up to two directories down (bounded in the context builder). Counting
     // only the root turned every real documentation repository — README.md plus
     // the pages under `docs/` — into `generic`.
-    detect: (context) => context.markdownCount >= 3 && !hasFile(context, "package.json"),
+    detect: (context) => markdownEvidence(context),
     layers: [
       layer("content", "content/", "docs/"),
       layer("assets", "assets/", "static/", "public/"),
@@ -979,7 +1007,10 @@ var SHAPE_PRESETS = [
   {
     name: "generic",
     priority: 0,
-    detect: () => true,
+    // No detector: this is the fallback, and `detectPresetFromContext` reaches it only
+    // when every other preset reported no evidence. `fallback: true` is what lets the
+    // wizard tell "I recognised this" apart from "I gave up".
+    fallback: true,
     layers: DEFAULT_LAYERS,
     kinds: DEFAULT_KINDS,
     exclude: [],
@@ -1011,20 +1042,27 @@ function detectPresetFromContext(context, forced) {
   if (forced !== void 0) {
     const preset = BY_NAME.get(forced);
     if (!preset) throw new Error(unknownPresetMessage(forced));
-    return toDetected(preset);
+    return toDetected(preset, null);
   }
   for (const preset of PRESETS) {
-    if (preset.detect(context)) return toDetected(preset);
+    const reason = preset.detect?.(context) ?? null;
+    if (reason !== null) return toDetected(preset, reason);
+  }
+  const fallback = PRESETS.find((preset) => preset.fallback === true);
+  if (fallback === void 0) {
+    throw new Error("No fallback preset is defined. Exactly one preset must set `fallback: true`.");
   }
-  return toDetected(PRESETS[PRESETS.length - 1]);
+  return toDetected(fallback, null, true);
 }
-function toDetected(preset) {
+function toDetected(preset, reason, fallback = false) {
   return {
     presetName: preset.name,
     layers: preset.layers,
     kinds: preset.kinds,
     exclude: preset.exclude ? [...preset.exclude] : [],
-    recommendedBudget: preset.recommendedBudget ?? null
+    recommendedBudget: preset.recommendedBudget ?? null,
+    reason,
+    fallback
   };
 }
 function detectPreset(cwd, forced) {
@@ -1470,8 +1508,8 @@ function readLinkTarget(linkPath, fallback) {
   }
 }
 function isInside(root, candidate) {
-  const relative8 = path2.relative(root, candidate);
-  return relative8 === "" || !relative8.startsWith(`..${path2.sep}`) && relative8 !== ".." && !path2.isAbsolute(relative8);
+  const relative11 = path2.relative(root, candidate);
+  return relative11 === "" || !relative11.startsWith(`..${path2.sep}`) && relative11 !== ".." && !path2.isAbsolute(relative11);
 }
 function getGitInfo(cwd, fallbackBranch = "main") {
   try {
@@ -2153,6 +2191,20 @@ var CONFIG_FILENAMES = [
   ".snapshotrc.json",
   ".snapshotrc"
 ];
+function findConfigFile(cwd) {
+  for (const filename of CONFIG_FILENAMES) {
+    const fullPath = path3.join(cwd, filename);
+    if (fs3.existsSync(fullPath)) return fullPath;
+  }
+  const pkgJsonPath = path3.join(cwd, "package.json");
+  if (!fs3.existsSync(pkgJsonPath)) return null;
+  try {
+    const parsed = JSON.parse(fs3.readFileSync(pkgJsonPath, "utf8"));
+    return parsed.snapshot === void 0 ? null : pkgJsonPath;
+  } catch {
+    return null;
+  }
+}
 var RESOLVED_CONFIG_BRAND = /* @__PURE__ */ Symbol.for(
   "codebase-snapshot/resolved-config"
 );
@@ -2608,11 +2660,11 @@ function outputExcludePatterns(cwd, outDir, tmpDir) {
   const patterns = [];
   for (const dir of [outDir, tmpDir]) {
     const absolute = path3.resolve(cwd, dir);
-    const relative8 = path3.relative(cwd, absolute);
-    if (!relative8 || relative8 === ".." || relative8.startsWith(`..${path3.sep}`) || path3.isAbsolute(relative8)) {
+    const relative11 = path3.relative(cwd, absolute);
+    if (!relative11 || relative11 === ".." || relative11.startsWith(`..${path3.sep}`) || path3.isAbsolute(relative11)) {
       continue;
     }
-    patterns.push(`${relative8.replace(/\\/g, "/")}/**`);
+    patterns.push(`${relative11.replace(/\\/g, "/")}/**`);
   }
   return patterns;
 }
@@ -4108,21 +4160,21 @@ function describeMatcher(matcher) {
 }
 function normalizeTarget(cwd, target) {
   const absolute = path8.resolve(cwd, target);
-  const relative8 = path8.relative(cwd, absolute);
-  if (relative8.startsWith("..") || path8.isAbsolute(relative8)) return target;
-  return relative8.split(path8.sep).join("/");
+  const relative11 = path8.relative(cwd, absolute);
+  if (relative11.startsWith("..") || path8.isAbsolute(relative11)) return target;
+  return relative11.split(path8.sep).join("/");
 }
 function findRuleMatch(rules, relativePath) {
   return rules.find(
     (rule) => matchRule(relativePath, rule.match)
   );
 }
-function findRecordedAncestor(skipped, relative8, maskedPath2) {
+function findRecordedAncestor(skipped, relative11, maskedPath2) {
   let nearest;
   for (const record of skipped) {
     const ancestorPath = record.path;
     if (ancestorPath.length === 0) continue;
-    const isAncestor = relative8.startsWith(`${ancestorPath}/`) || maskedPath2.startsWith(`${ancestorPath}/`);
+    const isAncestor = relative11.startsWith(`${ancestorPath}/`) || maskedPath2.startsWith(`${ancestorPath}/`);
     if (!isAncestor) continue;
     if (!nearest || ancestorPath.length > nearest.path.length) nearest = record;
   }
@@ -4137,9 +4189,9 @@ function readManifest2(config) {
   }
 }
 function explainPath(config, target) {
-  const relative8 = normalizeTarget(config.cwd, target);
-  const absolute = path8.join(config.cwd, relative8);
-  const maskedPath2 = findSecretInPath(relative8, config.secretRules)?.masked ?? relative8;
+  const relative11 = normalizeTarget(config.cwd, target);
+  const absolute = path8.join(config.cwd, relative11);
+  const maskedPath2 = findSecretInPath(relative11, config.secretRules)?.masked ?? relative11;
   const result = {
     path: maskedPath2,
     exists: fs7.existsSync(absolute),
@@ -4154,11 +4206,11 @@ function explainPath(config, target) {
     // that is only missing because the walker dropped the tool's own output directory.
     toolOwnedPaths: [config.outDir, config.tmpDir].map(
       (directory) => path8.relative(config.cwd, path8.resolve(config.cwd, directory)).replace(/\\/g, "/")
-    ).filter((relative9) => relative9.length > 0 && !relative9.startsWith(".."))
+    ).filter((relative12) => relative12.length > 0 && !relative12.startsWith(".."))
   });
-  if (!collection.files.includes(relative8)) {
+  if (!collection.files.includes(relative11)) {
     const record = collection.skipped.find(
-      (entry2) => entry2.path === relative8 || entry2.path === maskedPath2
+      (entry2) => entry2.path === relative11 || entry2.path === maskedPath2
     );
     if (record) {
       result.reason = record.reason;
@@ -4167,7 +4219,7 @@ function explainPath(config, target) {
       result.reason = "missing";
       result.detail = "no such file or directory, relative to the configured cwd";
     } else {
-      const ancestor = findRecordedAncestor(collection.skipped, relative8, maskedPath2);
+      const ancestor = findRecordedAncestor(collection.skipped, relative11, maskedPath2);
       if (ancestor) {
         result.reason = ancestor.reason;
         result.detail = ancestor.detail ? `${ancestor.detail} \u2014 inherited from the skipped directory \`${ancestor.path}\`` : `inside the skipped directory \`${ancestor.path}\``;
@@ -4185,12 +4237,12 @@ function explainPath(config, target) {
     result.detail = "binary content; generate skips it and records `binary` in manifest.skipped[]";
     return result;
   }
-  result.layer = classifyLayer(relative8, config.layers);
-  result.kind = classifyKind(relative8, config.kinds);
-  result.language = detectLanguage(relative8);
-  const layerRule = findRuleMatch(config.layers, relative8);
+  result.layer = classifyLayer(relative11, config.layers);
+  result.kind = classifyKind(relative11, config.kinds);
+  result.language = detectLanguage(relative11);
+  const layerRule = findRuleMatch(config.layers, relative11);
   if (layerRule) result.layerMatch = describeMatcher(layerRule.match);
-  const kindRule = findRuleMatch(config.kinds, relative8);
+  const kindRule = findRuleMatch(config.kinds, relative11);
   if (kindRule) result.kindMatch = describeMatcher(kindRule.match);
   if (fs7.existsSync(absolute) && fs7.statSync(absolute).isFile()) {
     const buffer = fs7.readFileSync(absolute);
@@ -4205,12 +4257,12 @@ function explainPath(config, target) {
     result.bytes = buffer.length;
     result.lines = countLines(text2);
     if (decoded.encoding !== "utf-8") result.encoding = decoded.encoding;
-    const { findings } = scanAndRedactSecrets(text2, config.secretRules, relative8);
+    const { findings } = scanAndRedactSecrets(text2, config.secretRules, relative11);
     result.secretCount = findings.length;
     result.secrets = findings.slice(0, 20).map((finding) => ({ rules: finding.rules, line: finding.line }));
   }
   const manifest = readManifest2(config);
-  const entry = Array.isArray(manifest?.files) ? manifest.files.find((file) => file.relativePath === relative8) : void 0;
+  const entry = Array.isArray(manifest?.files) ? manifest.files.find((file) => file.relativePath === relative11) : void 0;
   result.part = entry?.part ?? null;
   result.inclusionMode = entry?.inclusionMode;
   return result;
@@ -4294,7 +4346,7 @@ function gitignorePath(cwd, filePath) {
 
 // src/version.ts
 var GENERATOR_NAME = "codebase-snapshot";
-var GENERATOR_VERSION = "0.9.1";
+var GENERATOR_VERSION = "0.9.5";
 var LEGACY_GENERATOR_NAMES = ["@ankurhalder/codebase-snapshot"];
 function isOurGeneratorName(name) {
   if (typeof name !== "string") return false;
@@ -4435,6 +4487,12 @@ var PromptCancelled = class extends Error {
     this.name = "PromptCancelled";
   }
 };
+var PromptBack = class extends Error {
+  constructor() {
+    super("Prompt back");
+    this.name = "PromptBack";
+  }
+};
 function defaultIO() {
   return { input: process.stdin, output: process.stdout };
 }
@@ -4458,35 +4516,40 @@ function choiceLine(choice, active) {
   const hint = choice.hint ? `  ${choice.hint}` : "";
   return `  ${marker(active)} ${choice.label}${hint}`;
 }
-function renderSelect(message, choices, index) {
+function listFooter(base, allowBack) {
+  return allowBack ? `${base} \xB7 \u2190 back` : base;
+}
+function renderSelect(message, choices, index, allowBack = false) {
   const lines = [`\u25C6 ${message}`, ""];
   choices.forEach((choice, position) => lines.push(choiceLine(choice, position === index)));
-  lines.push("", "  \u2191\u2193 move \xB7 enter select");
+  lines.push("", `  ${listFooter("\u2191\u2193 move \xB7 enter select", allowBack)}`);
   return lines.join("\n");
 }
-function renderMultiSelect(message, choices, index, selected) {
+function renderMultiSelect(message, choices, index, selected, allowBack = false) {
   const lines = [`\u25C6 ${message}`, ""];
   choices.forEach((choice, position) => {
     const box = selected.has(position) ? "\u25FC" : "\u25FB";
     const hint = choice.hint ? `  ${choice.hint}` : "";
     lines.push(`  ${marker(position === index)} ${box} ${choice.label}${hint}`);
   });
-  lines.push("", "  \u2191\u2193 move \xB7 space toggle \xB7 enter confirm");
+  lines.push("", `  ${listFooter("\u2191\u2193 move \xB7 space toggle \xB7 enter confirm", allowBack)}`);
   return lines.join("\n");
 }
-function renderConfirm(message, value) {
+function renderConfirm(message, value, allowBack = false) {
+  const footer = allowBack ? "\u2190\u2192 or y/n \xB7 enter confirm \xB7 b back" : "\u2190\u2192 or y/n \xB7 enter confirm";
   return [
     `\u25C6 ${message}`,
     "",
     `  ${marker(value)} Yes`,
     `  ${marker(!value)} No`,
     "",
-    "  \u2190\u2192 or y/n \xB7 enter confirm"
+    `  ${footer}`
   ].join("\n");
 }
-function renderText(message, value, error) {
+function renderText(message, value, error, allowBack = false) {
   const lines = [`\u25C6 ${message}`, "", `  ${value || "\u258F"}`];
   if (error) lines.push("", `  \u2716 ${error}`);
+  if (allowBack) lines.push("", "  enter confirm \xB7 \u2190 back");
   return lines.join("\n");
 }
 function keyReader(input) {
@@ -4506,7 +4569,7 @@ function keyReader(input) {
     next() {
       const queued = queue.shift();
       if (queued) return Promise.resolve(queued);
-      return new Promise((resolve6) => waiters.push(resolve6));
+      return new Promise((resolve9) => waiters.push(resolve9));
     },
     close() {
       input.off("keypress", onKey);
@@ -4535,14 +4598,18 @@ var Frame = class {
 function isCancel(key) {
   return key.ctrl === true && key.name === "c" || key.ctrl === true && key.name === "d";
 }
+function isListBack(key, allowBack) {
+  return allowBack && (key.name === "left" || key.name === "b");
+}
 async function select(io, message, choices, options = {}) {
   if (choices.length === 0) throw new Error("select() requires at least one choice.");
+  const allowBack = options.allowBack === true;
   const fallbackIndex = Math.max(
     0,
     choices.findIndex((choice) => choice.value === options.defaultValue)
   );
   if (!isInteractive(io)) {
-    io.output.write(`${renderSelect(message, choices, fallbackIndex)}
+    io.output.write(`${renderSelect(message, choices, fallbackIndex, allowBack)}
 `);
     return choices[fallbackIndex].value;
   }
@@ -4551,9 +4618,10 @@ async function select(io, message, choices, options = {}) {
   let index = fallbackIndex;
   try {
     for (; ; ) {
-      frame.draw(renderSelect(message, choices, index));
+      frame.draw(renderSelect(message, choices, index, allowBack));
       const key = await reader.next();
       if (isCancel(key)) throw new PromptCancelled();
+      if (isListBack(key, allowBack)) throw new PromptBack();
       if (key.name === "up") index = moveSelection(index, -1, choices.length);
       else if (key.name === "down") index = moveSelection(index, 1, choices.length);
       else if (key.name === "return" || key.name === "enter") {
@@ -4562,18 +4630,22 @@ async function select(io, message, choices, options = {}) {
       } else if (key.name === "j") index = moveSelection(index, 1, choices.length);
       else if (key.name === "k") index = moveSelection(index, -1, choices.length);
     }
+  } catch (error) {
+    frame.erase();
+    throw error;
   } finally {
     reader.close();
   }
 }
 async function multiSelect(io, message, choices, options = {}) {
+  const allowBack = options.allowBack === true;
   const selected = /* @__PURE__ */ new Set();
   choices.forEach((choice, position) => {
     if (options.defaults?.includes(choice.value)) selected.add(position);
   });
   const result = () => choices.filter((_, position) => selected.has(position)).map((choice) => choice.value);
   if (!isInteractive(io)) {
-    io.output.write(`${renderMultiSelect(message, choices, 0, selected)}
+    io.output.write(`${renderMultiSelect(message, choices, 0, selected, allowBack)}
 `);
     return result();
   }
@@ -4582,9 +4654,10 @@ async function multiSelect(io, message, choices, options = {}) {
   let index = 0;
   try {
     for (; ; ) {
-      frame.draw(renderMultiSelect(message, choices, index, selected));
+      frame.draw(renderMultiSelect(message, choices, index, selected, allowBack));
       const key = await reader.next();
       if (isCancel(key)) throw new PromptCancelled();
+      if (isListBack(key, allowBack)) throw new PromptBack();
       if (key.name === "up") index = moveSelection(index, -1, choices.length);
       else if (key.name === "down") index = moveSelection(index, 1, choices.length);
       else if (key.name === "space") {
@@ -4599,14 +4672,18 @@ async function multiSelect(io, message, choices, options = {}) {
         return result();
       }
     }
+  } catch (error) {
+    frame.erase();
+    throw error;
   } finally {
     reader.close();
   }
 }
 async function confirm(io, message, options = {}) {
+  const allowBack = options.allowBack === true;
   let value = options.defaultValue ?? true;
   if (!isInteractive(io)) {
-    io.output.write(`${renderConfirm(message, value)}
+    io.output.write(`${renderConfirm(message, value, allowBack)}
 `);
     return value;
   }
@@ -4614,9 +4691,10 @@ async function confirm(io, message, options = {}) {
   const reader = keyReader(io.input);
   try {
     for (; ; ) {
-      frame.draw(renderConfirm(message, value));
+      frame.draw(renderConfirm(message, value, allowBack));
       const key = await reader.next();
       if (isCancel(key)) throw new PromptCancelled();
+      if (allowBack && key.name === "b") throw new PromptBack();
       if (key.name === "up" || key.name === "left") value = true;
       else if (key.name === "down" || key.name === "right") value = false;
       else if (key.name === "y") value = true;
@@ -4626,14 +4704,18 @@ async function confirm(io, message, options = {}) {
         return value;
       }
     }
+  } catch (error) {
+    frame.erase();
+    throw error;
   } finally {
     reader.close();
   }
 }
 async function text(io, message, options = {}) {
+  const allowBack = options.allowBack === true;
   const fallback = options.defaultValue ?? "";
   if (!isInteractive(io)) {
-    io.output.write(`${renderText(message, fallback)}
+    io.output.write(`${renderText(message, fallback, void 0, allowBack)}
 `);
     return fallback;
   }
@@ -4643,9 +4725,10 @@ async function text(io, message, options = {}) {
   let error;
   try {
     for (; ; ) {
-      frame.draw(renderText(message, value, error));
+      frame.draw(renderText(message, value, error, allowBack));
       const key = await reader.next();
       if (isCancel(key)) throw new PromptCancelled();
+      if (allowBack && key.name === "left") throw new PromptBack();
       error = void 0;
       if (key.name === "return" || key.name === "enter") {
         const problem = options.validate ? options.validate(value) : null;
@@ -4666,6 +4749,9 @@ async function text(io, message, options = {}) {
       }
       if (_isPrintable(key)) value += _keyText(key);
     }
+  } catch (error_) {
+    frame.erase();
+    throw error_;
   } finally {
     reader.close();
   }
@@ -4861,16 +4947,18 @@ function updatePackageJson(cwd, notes) {
   return { scripts: added, dependency };
 }
 var GITIGNORE_ENTRIES = ["snapshot/", "snapshot.tmp/"];
-function resolvePresetChoice(answers, presetName) {
+function resolvePresetChoice(detectedName, presetName) {
   return {
     value: presetName,
     label: presetName,
-    hint: presetName === answers.preset ? "detected" : void 0
+    hint: presetName === detectedName ? "detected" : void 0
   };
 }
 async function runInit(options) {
   const io = options.io ?? defaultIO();
   const detected = detectPreset(options.cwd, options.preset);
+  let reason = detected.reason;
+  let fallback = detected.fallback;
   const notes = [];
   const answers = {
     preset: detected.presetName,
@@ -4892,73 +4980,37 @@ async function runInit(options) {
   if (interactive) {
     io.output.write("\n  codebase-snapshot\n");
     io.output.write("  Turn this repository into an LLM-ready, redacted, byte-bounded snapshot.\n\n");
-    io.output.write(`  Detected   ${detected.presetName}
+    if (fallback) {
+      io.output.write("  \u26A0 Could not tell what kind of project this is.\n");
+      io.output.write("    No package.json, go.mod, Cargo.toml, pyproject.toml, Gemfile,\n");
+      io.output.write("    composer.json, pom.xml, *.csproj, next.config.*, vite.config.*, *.tf\n");
+      io.output.write("    or workspace marker was found here.\n\n");
+    } else {
+      io.output.write(`  Detected   ${detected.presetName}
 `);
-    io.output.write(`  Directory  ${options.cwd}
+      io.output.write(`  Because    ${reason}
 
 `);
-    const useDetected = await confirm(io, `Set up for ${detected.presetName}?`, {
-      defaultValue: true
-    });
-    if (!useDetected) {
-      answers.preset = await select(
-        io,
-        "What kind of project is this?",
-        listPresetNames().map((name) => resolvePresetChoice(answers, name))
-      );
-      const chosen = detectPreset(options.cwd, answers.preset);
-      answers.preset = chosen.presetName;
-    }
-    const scope = await select(
-      io,
-      "What should go into the snapshot?",
-      [
-        { value: "all", label: "Everything the scanner finds", hint: "recommended \xB7 respects .gitignore" },
-        { value: "folders", label: "Only specific folders\u2026" },
-        { value: "no-tests", label: "Everything, but skip tests" },
-        { value: "custom", label: "Let me write glob patterns" }
-      ],
-      { defaultValue: "all" }
-    );
-    if (scope === "folders") {
-      const dirs = topLevelDirs(options.cwd).slice(0, 40);
-      if (dirs.length === 0) {
-        notes.push("No top-level directories found; the snapshot will include everything.");
-      } else {
-        const chosen = await multiSelect(
-          io,
-          "Select folders",
-          dirs.map((name) => ({ value: name, label: `${name}/` })),
-          { defaults: dirs }
-        );
-        answers.include = chosen.map((name) => `${name}/**`);
-      }
-    } else if (scope === "no-tests") {
-      answers.excludePatterns = [
-        ...answers.excludePatterns,
-        "**/*.test.*",
-        "**/*.spec.*",
-        "tests",
-        "test"
-      ];
-    } else if (scope === "custom") {
-      const raw = await text(io, "Glob patterns to include (comma separated)", {
-        defaultValue: ""
-      });
-      answers.include = raw.split(",").map((value) => value.trim()).filter(Boolean);
-    }
-    const sizeChoice = await select(io, "How large should each part be?", SIZE_CHOICES, {
-      defaultValue: "120k"
-    });
-    if (sizeChoice === "custom") {
-      const raw = await text(io, "Part size (e.g. 150k, 1.5mb, 900000)", {
-        defaultValue: String(answers.maxPartBytes),
-        validate: (value) => parseByteSize(value) === void 0 ? "Not a valid size." : null
-      });
-      answers.maxPartBytes = parseByteSize(raw) ?? answers.maxPartBytes;
-    } else {
-      answers.maxPartBytes = sizeChoice;
     }
+    io.output.write(`  Directory  ${options.cwd}
+
+`);
+    const paceChoices = fallback ? [
+      { value: "choose", label: "Pick the closest preset", hint: "then generate with the defaults" },
+      { value: "recommended", label: "Use the defaults", hint: "generic \xB7 everything the scanner finds" },
+      { value: "walk", label: "Go through each setting", hint: "every question starts on its default" }
+    ] : [
+      {
+        value: "recommended",
+        label: "Use the recommended setup",
+        hint: `${detected.presetName} \xB7 config \xB7 npm scripts \xB7 install \xB7 generate`
+      },
+      { value: "walk", label: "Go through each setting", hint: "every question starts on its default" },
+      { value: "choose", label: "Pick a different preset", hint: "everything else stays at the defaults" }
+    ];
+    const baseInclude = [...answers.include];
+    const baseExclude = [...answers.excludePatterns];
+    let lastScope = "all";
     const artifactChoices = [
       { value: "readme", label: "README.md", hint: "orientation page" },
       { value: "manifest", label: "manifest.json", hint: "required by validate and report" },
@@ -4968,36 +5020,158 @@ async function runInit(options) {
       { value: "audit", label: "reports/audit.md", hint: "security and health findings" },
       { value: "monolith", label: "full-codebase.json + .md", hint: "roughly doubles output" }
     ];
-    const presetEnabled = ARTIFACT_NAMES.filter((name) => answers.artifacts[name]);
-    const selectedArtifacts = await multiSelect(
-      io,
-      "Which artifacts should be generated?",
-      artifactChoices,
-      { defaults: presetEnabled }
-    );
-    for (const name of ARTIFACT_NAMES) answers.artifacts[name] = selectedArtifacts.includes(name);
-    const enabledCount = ARTIFACT_NAMES.filter((name) => answers.artifacts[name]).length;
-    answers.includeSensitiveFiles = await confirm(
-      io,
-      "Include credential files (.env, *.pem, .npmrc, .ssh/)?",
-      { defaultValue: false }
-    );
-    io.output.write("\n  Review\n\n");
-    io.output.write(`  project          ${answers.preset}
+    const scopeStep = async () => {
+      for (; ; ) {
+        const scope = await select(
+          io,
+          "What should go into the snapshot?",
+          [
+            { value: "all", label: "Everything the scanner finds", hint: "recommended \xB7 respects .gitignore" },
+            { value: "folders", label: "Only specific folders\u2026" },
+            { value: "no-tests", label: "Everything, but skip tests" },
+            { value: "custom", label: "Let me write glob patterns" }
+          ],
+          { defaultValue: lastScope, allowBack: true }
+        );
+        lastScope = scope;
+        answers.include = [...baseInclude];
+        answers.excludePatterns = [...baseExclude];
+        try {
+          if (scope === "folders") {
+            const dirs = topLevelDirs(options.cwd).slice(0, 40);
+            if (dirs.length === 0) {
+              notes.push("No top-level directories found; the snapshot will include everything.");
+            } else {
+              const chosen = await multiSelect(
+                io,
+                "Select folders",
+                dirs.map((name) => ({ value: name, label: `${name}/` })),
+                { defaults: dirs, allowBack: true }
+              );
+              answers.include = chosen.map((name) => `${name}/**`);
+            }
+          } else if (scope === "no-tests") {
+            answers.excludePatterns = [...baseExclude, "**/*.test.*", "**/*.spec.*", "tests", "test"];
+          } else if (scope === "custom") {
+            const raw = await text(io, "Glob patterns to include (comma separated)", {
+              defaultValue: baseInclude.join(", "),
+              allowBack: true
+            });
+            answers.include = raw.split(",").map((value) => value.trim()).filter(Boolean);
+          }
+          return;
+        } catch (error) {
+          if (error instanceof PromptBack) continue;
+          throw error;
+        }
+      }
+    };
+    const sizeStep = async () => {
+      for (; ; ) {
+        const currentBudget = String(answers.maxPartBytes);
+        const sizeChoice = await select(io, "How large should each part be?", SIZE_CHOICES, {
+          defaultValue: SIZE_CHOICES.some((choice) => choice.value === currentBudget) ? currentBudget : "custom",
+          allowBack: true
+        });
+        if (sizeChoice !== "custom") {
+          answers.maxPartBytes = sizeChoice;
+          return;
+        }
+        try {
+          const raw = await text(io, "Part size (e.g. 150k, 1.5mb, 900000)", {
+            defaultValue: currentBudget,
+            validate: (value) => parseByteSize(value) === void 0 ? "Not a valid size." : null,
+            allowBack: true
+          });
+          answers.maxPartBytes = parseByteSize(raw) ?? answers.maxPartBytes;
+          return;
+        } catch (error) {
+          if (error instanceof PromptBack) continue;
+          throw error;
+        }
+      }
+    };
+    const artifactsStep = async () => {
+      const enabled = ARTIFACT_NAMES.filter((name) => answers.artifacts[name]);
+      const selectedArtifacts = await multiSelect(
+        io,
+        "Which artifacts should be generated?",
+        artifactChoices,
+        { defaults: enabled, allowBack: true }
+      );
+      for (const name of ARTIFACT_NAMES) answers.artifacts[name] = selectedArtifacts.includes(name);
+    };
+    const credentialsStep = async () => {
+      answers.includeSensitiveFiles = await confirm(
+        io,
+        "Include credential files (.env, *.pem, *.npmrc, *.ssh/)?",
+        { defaultValue: answers.includeSensitiveFiles, allowBack: true }
+      );
+    };
+    const reviewStep = async () => {
+      const enabledCount = ARTIFACT_NAMES.filter((name) => answers.artifacts[name]).length;
+      io.output.write("\n  Review\n\n");
+      io.output.write(`  project          ${answers.preset}
 `);
-    io.output.write(`  include          ${answers.include.length ? answers.include.join(", ") : "everything"}
+      io.output.write(`  include          ${answers.include.length ? answers.include.join(", ") : "everything"}
 `);
-    io.output.write(`  part size        ${String(answers.maxPartBytes)}
+      io.output.write(`  part size        ${String(answers.maxPartBytes)}
 `);
-    io.output.write(`  artifacts        ${enabledCount} of ${ARTIFACT_NAMES.length}
+      io.output.write(`  artifacts        ${enabledCount} of ${ARTIFACT_NAMES.length}
 `);
-    io.output.write(`  credentials      ${answers.includeSensitiveFiles ? "included" : "skipped"}
+      io.output.write(`  credentials      ${answers.includeSensitiveFiles ? "included" : "skipped"}
 
 `);
-    io.output.write("  Will write snapshot.config with your answers, plus every other setting\n");
-    io.output.write("  at its default \u2014 so nothing is hidden behind the docs.\n\n");
-    const proceed = await confirm(io, "Write this and continue?", { defaultValue: true });
-    if (!proceed) throw new PromptCancelled();
+      io.output.write("  Will write snapshot.config with your answers, plus every other setting\n");
+      io.output.write("  at its default \u2014 so nothing is hidden behind the docs.\n\n");
+      const proceed = await confirm(io, "Write this and continue?", {
+        defaultValue: true,
+        allowBack: true
+      });
+      if (!proceed) throw new PromptBack();
+    };
+    const walk = async () => {
+      const steps = [scopeStep, sizeStep, artifactsStep, credentialsStep, reviewStep];
+      let index = 0;
+      while (index < steps.length) {
+        try {
+          await steps[index]();
+          index += 1;
+        } catch (error) {
+          if (!(error instanceof PromptBack)) throw error;
+          if (index === 0) return false;
+          index -= 1;
+          io.output.write("\n");
+        }
+      }
+      return true;
+    };
+    for (; ; ) {
+      const pace = await select(io, "How should I set this up?", paceChoices, {
+        defaultValue: fallback ? "choose" : "recommended"
+      });
+      if (pace === "choose") {
+        try {
+          answers.preset = await select(
+            io,
+            "What kind of project is this?",
+            listPresetNames().map(
+              (name) => resolvePresetChoice(fallback ? null : detected.presetName, name)
+            ),
+            { defaultValue: answers.preset, allowBack: true }
+          );
+        } catch (error) {
+          if (error instanceof PromptBack) continue;
+          throw error;
+        }
+        const chosen = detectPreset(options.cwd, answers.preset);
+        answers.preset = chosen.presetName;
+        reason = null;
+        fallback = false;
+      }
+      if (pace === "walk" && !await walk()) continue;
+      break;
+    }
   }
   const configText = renderConfig(answers);
   const preferredName = chooseConfigFileName(options.cwd);
@@ -5021,6 +5195,8 @@ async function runInit(options) {
       written: false,
       reused,
       preset: answers.preset,
+      reason,
+      fallback,
       scripts: [],
       gitignoreEntries: [],
       dependency: { name: GENERATOR_NAME, range: `^${GENERATOR_VERSION}`, added: false },
@@ -5055,6 +5231,8 @@ async function runInit(options) {
     written: true,
     reused,
     preset: answers.preset,
+    reason,
+    fallback,
     scripts,
     gitignoreEntries: ignore.added,
     dependency,
@@ -5062,12 +5240,58 @@ async function runInit(options) {
   };
 }
 
+// src/wizard/autopilot.ts
+import * as fs10 from "fs";
+import * as path11 from "path";
+function describeTarget(cwd) {
+  const relative11 = path11.relative(process.cwd(), cwd);
+  if (relative11 === "") return "this directory";
+  if (relative11.startsWith("..") || path11.isAbsolute(relative11)) return cwd;
+  return relative11;
+}
+function firstRunMessage(reason, cwd) {
+  const where = describeTarget(cwd);
+  if (reason === "empty") {
+    return `Nothing to snapshot: ${where} has no files. Run this inside the repository you want to snapshot, or pass --cwd.`;
+  }
+  return `No configuration found in ${where} and this session is not interactive, so nothing was generated.
+Choose one:
+  ${GENERATOR_NAME} --autopilot     detect the project, set it up and generate, no questions
+  ${GENERATOR_NAME} init --yes      write a config from the detected defaults, then generate
+  ${GENERATOR_NAME} init            write a config interactively`;
+}
+function planFirstRun(facts) {
+  if (facts.emptyTarget) return { action: "refuse", exitCode: 1, reason: "empty" };
+  if (facts.autopilot) return { action: "setup", interactive: false };
+  if (facts.hasConfig || facts.hasPriorSnapshot) return { action: "generate" };
+  if (facts.interactive) return { action: "setup", interactive: true };
+  return { action: "refuse", exitCode: 2, reason: "undecided" };
+}
+var NOT_CONTENT = /* @__PURE__ */ new Set([".git", ".hg", ".svn", ".bzr", ".DS_Store", "Thumbs.db"]);
+function isEffectivelyEmpty(cwd) {
+  try {
+    return fs10.readdirSync(cwd).every((entry) => NOT_CONTENT.has(entry));
+  } catch {
+    return false;
+  }
+}
+function hasPriorSnapshot(cwd, outDir) {
+  let parsed;
+  try {
+    parsed = JSON.parse(fs10.readFileSync(path11.join(cwd, outDir, ".codebase-snapshot"), "utf8"));
+  } catch {
+    return false;
+  }
+  if (parsed === null || typeof parsed !== "object") return false;
+  return isOurGeneratorName(parsed.generator);
+}
+
 // src/index.ts
 import * as crypto3 from "crypto";
 import { AsyncLocalStorage } from "async_hooks";
-import * as fs10 from "fs";
+import * as fs11 from "fs";
 import * as os from "os";
-import * as path11 from "path";
+import * as path12 from "path";
 
 // src/ast/profiles/shared.ts
 var MAX_SUMMARY_CHARS = 1e6;
@@ -5291,9 +5515,9 @@ var JAVA_METHOD = /^\s+(?:public|private|protected)\s+(?:static\s+)?(?:final\s+)
 var jvmProfile = {
   id: "jvm",
   extensions: [".java", ".kt", ".kts", ".scala"],
-  summarize(path14, content) {
+  summarize(path18, content) {
     const summary = emptySummary();
-    const lower = path14.toLowerCase();
+    const lower = path18.toLowerCase();
     const isJava = lower.endsWith(".java");
     const isKotlin = lower.endsWith(".kt") || lower.endsWith(".kts");
     eachLine(content, (line) => {
@@ -5749,16 +5973,16 @@ function summarizeTypeScriptSource(relativePath, content) {
 // src/ast/profiles/sfc.ts
 var SCRIPT_BLOCK = /<script[^>]*>([\s\S]*?)<\/script>/gi;
 var ASTRO_FRONTMATTER = /^\uFEFF?---[ \t]*\r?\n([\s\S]*?)\r?\n---[ \t]*(?=\r?\n|$)/;
-function componentName(path14) {
-  const base = path14.split("/").pop() ?? path14;
+function componentName(path18) {
+  const base = path18.split("/").pop() ?? path18;
   return base.replace(/\.[^.]+$/, "");
 }
 var sfcProfile = {
   id: "sfc",
   extensions: [".vue", ".svelte", ".astro"],
-  summarize(path14, content) {
+  summarize(path18, content) {
     let script = "";
-    if (path14.toLowerCase().endsWith(".astro")) {
+    if (path18.toLowerCase().endsWith(".astro")) {
       const frontmatter = ASTRO_FRONTMATTER.exec(content);
       if (frontmatter) script += `${frontmatter[1]}
 `;
@@ -5767,7 +5991,7 @@ var sfcProfile = {
       script += `${match[1]}
 `;
     }
-    const name = componentName(path14);
+    const name = componentName(path18);
     if (!script.trim()) {
       const summary2 = emptySummary();
       if (name) {
@@ -5801,15 +6025,15 @@ for (const profile of LANGUAGE_PROFILES) {
     BY_EXTENSION.set(extension.toLowerCase(), profile);
   }
 }
-function profileForPath(path14) {
-  const lower = path14.toLowerCase();
+function profileForPath(path18) {
+  const lower = path18.toLowerCase();
   const dot = lower.lastIndexOf(".");
   if (dot === -1) return null;
   return BY_EXTENSION.get(lower.slice(dot)) ?? null;
 }
-function summarizeWithProfile(path14, content) {
-  const profile = profileForPath(path14);
-  return profile ? profile.summarize(path14, content) : null;
+function summarizeWithProfile(path18, content) {
+  const profile = profileForPath(path18);
+  return profile ? profile.summarize(path18, content) : null;
 }
 
 // src/ast/structured.ts
@@ -6739,13 +6963,13 @@ function buildImportResolver(files) {
     const relativePath = file.relativePath;
     remember(byPath, relativePath, relativePath);
     remember(byPathFolded, relativePath.toLowerCase(), relativePath);
-    const extension = path11.posix.extname(relativePath);
+    const extension = path12.posix.extname(relativePath);
     if (!SOURCE_EXTENSIONS.has(extension)) continue;
     const stem = relativePath.slice(0, -extension.length);
     remember(byStem, stem, relativePath);
     remember(byStemFolded, stem.toLowerCase(), relativePath);
-    if (path11.posix.basename(stem) === "index") {
-      const directory = path11.posix.dirname(stem);
+    if (path12.posix.basename(stem) === "index") {
+      const directory = path12.posix.dirname(stem);
       remember(byStem, directory, relativePath);
       remember(byStemFolded, directory.toLowerCase(), relativePath);
     }
@@ -6754,8 +6978,8 @@ function buildImportResolver(files) {
 }
 function resolveSpecifier(fromFile, specifier, resolver) {
   if (!RELATIVE_SPECIFIER.test(specifier)) return null;
-  const joined = path11.posix.normalize(
-    path11.posix.join(path11.posix.dirname(fromFile), specifier)
+  const joined = path12.posix.normalize(
+    path12.posix.join(path12.posix.dirname(fromFile), specifier)
   );
   const exact = (key) => resolver.byPath.get(key) ?? resolver.byPathFolded.get(key.toLowerCase()) ?? null;
   const direct = exact(joined);
@@ -6848,11 +7072,11 @@ function verifyInMemory(files, parts, maxPartBytes) {
   return errors;
 }
 function resolveSafeOutputDirs(config) {
-  const cwd = path11.resolve(config.cwd);
-  const outDir = path11.resolve(cwd, config.outDir);
-  const tmpDir = path11.resolve(cwd, config.tmpDir);
-  const root = path11.parse(cwd).root;
-  const contains = (parent, child) => child === parent || child.startsWith(`${parent}${path11.sep}`);
+  const cwd = path12.resolve(config.cwd);
+  const outDir = path12.resolve(cwd, config.outDir);
+  const tmpDir = path12.resolve(cwd, config.tmpDir);
+  const root = path12.parse(cwd).root;
+  const contains = (parent, child) => child === parent || child.startsWith(`${parent}${path12.sep}`);
   const reject = (reason) => {
     throw new Error(
       `Refusing to generate: ${reason}. outDir=${outDir} tmpDir=${tmpDir} cwd=${cwd}`
@@ -6908,14 +7132,14 @@ function listEntries(dir) {
   const walk = (absolute, prefix) => {
     let children;
     try {
-      children = fs10.readdirSync(absolute, { withFileTypes: true });
+      children = fs11.readdirSync(absolute, { withFileTypes: true });
     } catch {
       return;
     }
     for (const child of children) {
-      const relative8 = prefix === "" ? child.name : `${prefix}/${child.name}`;
-      entries.push(relative8);
-      if (child.isDirectory()) walk(path11.join(absolute, child.name), relative8);
+      const relative11 = prefix === "" ? child.name : `${prefix}/${child.name}`;
+      entries.push(relative11);
+      if (child.isDirectory()) walk(path12.join(absolute, child.name), relative11);
     }
   };
   walk(dir, "");
@@ -6932,28 +7156,28 @@ function markerPayload(dir, state, id, createdAt) {
     pid: process.pid,
     entries: listEntries(dir)
   };
-  const manifestPath = path11.join(dir, "manifest.json");
-  if (fs10.existsSync(manifestPath)) {
-    marker2.manifestSha256 = sha256Hex2(fs10.readFileSync(manifestPath));
+  const manifestPath = path12.join(dir, "manifest.json");
+  if (fs11.existsSync(manifestPath)) {
+    marker2.manifestSha256 = sha256Hex2(fs11.readFileSync(manifestPath));
   }
   return marker2;
 }
 function writeOwnershipMarker(dir, marker2) {
-  fs10.writeFileSync(
-    path11.join(dir, OWNERSHIP_MARKER),
+  fs11.writeFileSync(
+    path12.join(dir, OWNERSHIP_MARKER),
     `${JSON.stringify(marker2, null, 2)}
 `,
     "utf8"
   );
 }
 function readOwnershipMarker(dir) {
-  const markerPath = path11.join(dir, OWNERSHIP_MARKER);
-  if (!fs10.existsSync(markerPath)) {
+  const markerPath = path12.join(dir, OWNERSHIP_MARKER);
+  if (!fs11.existsSync(markerPath)) {
     return { marker: null, problem: "it holds no .codebase-snapshot marker" };
   }
   let raw;
   try {
-    raw = fs10.readFileSync(markerPath, "utf8");
+    raw = fs11.readFileSync(markerPath, "utf8");
   } catch {
     return { marker: null, problem: "its .codebase-snapshot marker could not be read" };
   }
@@ -7021,11 +7245,11 @@ function assessSnapshotDirectory(dir) {
       marker: marker2
     };
   }
-  const manifestPath = path11.join(dir, "manifest.json");
-  if (fs10.existsSync(manifestPath)) {
+  const manifestPath = path12.join(dir, "manifest.json");
+  if (fs11.existsSync(manifestPath)) {
     let raw;
     try {
-      raw = fs10.readFileSync(manifestPath, "utf8");
+      raw = fs11.readFileSync(manifestPath, "utf8");
     } catch {
       return {
         owned: false,
@@ -7107,13 +7331,13 @@ function containsNoFiles(dir) {
     const current = pending.pop();
     let entries;
     try {
-      entries = fs10.readdirSync(current, { withFileTypes: true });
+      entries = fs11.readdirSync(current, { withFileTypes: true });
     } catch {
       return false;
     }
     for (const entry of entries) {
       if (entry.isDirectory()) {
-        pending.push(path11.join(current, entry.name));
+        pending.push(path12.join(current, entry.name));
       } else if (!IGNORABLE_ENTRIES.has(entry.name)) {
         return false;
       }
@@ -7122,13 +7346,13 @@ function containsNoFiles(dir) {
   return true;
 }
 function assertReplaceable(target, label, secretRules) {
-  if (!fs10.existsSync(target)) return;
-  if (!fs10.statSync(target).isDirectory()) {
+  if (!fs11.existsSync(target)) return;
+  if (!fs11.statSync(target).isDirectory()) {
     throw new Error(
       `Refusing to write into ${label} ${target}: it exists but is not a directory.`
     );
   }
-  const entries = fs10.readdirSync(target);
+  const entries = fs11.readdirSync(target);
   if (entries.length === 0) return;
   if (entries.every((name) => IGNORABLE_ENTRIES.has(name))) return;
   if (containsNoFiles(target)) return;
@@ -7148,18 +7372,18 @@ function assertReplaceable(target, label, secretRules) {
   );
 }
 function assertStagingRootUsable(tmpDir, secretRules) {
-  if (!fs10.existsSync(tmpDir)) return;
-  if (!fs10.statSync(tmpDir).isDirectory()) {
+  if (!fs11.existsSync(tmpDir)) return;
+  if (!fs11.statSync(tmpDir).isDirectory()) {
     throw new Error(`Refusing to write into tmpDir ${tmpDir}: it exists but is not a directory.`);
   }
-  const entries = fs10.readdirSync(tmpDir);
+  const entries = fs11.readdirSync(tmpDir);
   if (entries.length === 0) return;
   const foreign = entries.filter((name) => {
-    const full = path11.join(tmpDir, name);
+    const full = path12.join(tmpDir, name);
     if (!name.startsWith(RUN_DIR_PREFIX)) return true;
     let stats;
     try {
-      stats = fs10.statSync(full);
+      stats = fs11.statSync(full);
     } catch {
       return true;
     }
@@ -7167,7 +7391,7 @@ function assertStagingRootUsable(tmpDir, secretRules) {
     const { marker: marker2 } = readOwnershipMarker(full);
     if (marker2) return false;
     try {
-      return fs10.readdirSync(full).length > 0;
+      return fs11.readdirSync(full).length > 0;
     } catch {
       return true;
     }
@@ -7182,13 +7406,13 @@ function assertStagingRootUsable(tmpDir, secretRules) {
 function cleanStaleRunDirs(tmpDir) {
   let entries;
   try {
-    entries = fs10.readdirSync(tmpDir);
+    entries = fs11.readdirSync(tmpDir);
   } catch {
     return;
   }
   for (const name of entries) {
     if (!name.startsWith(RUN_DIR_PREFIX)) continue;
-    const full = path11.join(tmpDir, name);
+    const full = path12.join(tmpDir, name);
     const { marker: marker2 } = readOwnershipMarker(full);
     if (marker2) {
       const created = Date.parse(marker2.createdAt);
@@ -7196,33 +7420,33 @@ function cleanStaleRunDirs(tmpDir) {
       const abandoned = typeof marker2.pid === "number" && !isProcessAlive(marker2.pid);
       if (aged || abandoned) {
         try {
-          fs10.rmSync(full, { recursive: true, force: true });
+          fs11.rmSync(full, { recursive: true, force: true });
         } catch {
         }
       }
       continue;
     }
     try {
-      if (fs10.readdirSync(full).length === 0) fs10.rmSync(full, { recursive: true, force: true });
+      if (fs11.readdirSync(full).length === 0) fs11.rmSync(full, { recursive: true, force: true });
     } catch {
     }
   }
 }
 function removeIfEmpty(dir) {
   try {
-    if (fs10.readdirSync(dir).length === 0) fs10.rmSync(dir, { recursive: true, force: true });
+    if (fs11.readdirSync(dir).length === 0) fs11.rmSync(dir, { recursive: true, force: true });
   } catch {
   }
 }
 function ensureParentDirectory(target, label) {
-  const parent = path11.dirname(target);
-  if (fs10.existsSync(parent) && !fs10.statSync(parent).isDirectory()) {
+  const parent = path12.dirname(target);
+  if (fs11.existsSync(parent) && !fs11.statSync(parent).isDirectory()) {
     throw new Error(
       `Refusing to create ${label} ${target}: ${parent} exists but is not a directory.`
     );
   }
   try {
-    fs10.mkdirSync(parent, { recursive: true });
+    fs11.mkdirSync(parent, { recursive: true });
   } catch (err) {
     throw new Error(
       `Refusing to create ${label} ${target}: its parent ${parent} could not be created (${err.message}).`
@@ -7231,7 +7455,7 @@ function ensureParentDirectory(target, label) {
 }
 function acquireRunLock(stagingRoot) {
   const key = lockKeyFor(stagingRoot);
-  const lockPath = path11.join(os.tmpdir(), `codebase-snapshot-${key}.lock`);
+  const lockPath = path12.join(os.tmpdir(), `codebase-snapshot-${key}.lock`);
   const payload = `${JSON.stringify({
     pid: process.pid,
     stagingRoot,
@@ -7240,22 +7464,22 @@ function acquireRunLock(stagingRoot) {
 `;
   for (let attempt = 0; attempt < 2; attempt += 1) {
     try {
-      const handle = fs10.openSync(lockPath, "wx");
+      const handle = fs11.openSync(lockPath, "wx");
       try {
-        fs10.writeSync(handle, payload);
+        fs11.writeSync(handle, payload);
       } finally {
-        fs10.closeSync(handle);
+        fs11.closeSync(handle);
       }
       return () => {
         try {
-          fs10.rmSync(lockPath, { force: true });
+          fs11.rmSync(lockPath, { force: true });
         } catch {
         }
       };
     } catch (err) {
       if (err.code !== "EEXIST") throw err;
       if (attempt === 0 && lockOwnerIsGone(lockPath)) {
-        fs10.rmSync(lockPath, { force: true });
+        fs11.rmSync(lockPath, { force: true });
         continue;
       }
       throw new Error(
@@ -7268,7 +7492,7 @@ function acquireRunLock(stagingRoot) {
 function lockKeyFor(stagingRoot) {
   let key = stagingRoot;
   try {
-    key = fs10.realpathSync(stagingRoot);
+    key = fs11.realpathSync(stagingRoot);
   } catch {
   }
   if (process.platform === "win32" || process.platform === "darwin") key = key.toLowerCase();
@@ -7277,7 +7501,7 @@ function lockKeyFor(stagingRoot) {
 function lockOwnerIsGone(lockPath) {
   let raw;
   try {
-    raw = fs10.readFileSync(lockPath, "utf8");
+    raw = fs11.readFileSync(lockPath, "utf8");
   } catch {
     return false;
   }
@@ -7297,12 +7521,12 @@ function lockOwnerIsGone(lockPath) {
 }
 function writeManifestAtomically(manifestPath, manifest) {
   const tempPath = `${manifestPath}.${process.pid}.tmp`;
-  fs10.writeFileSync(tempPath, JSON.stringify(manifest, null, 2), "utf8");
+  fs11.writeFileSync(tempPath, JSON.stringify(manifest, null, 2), "utf8");
   try {
-    fs10.renameSync(tempPath, manifestPath);
+    fs11.renameSync(tempPath, manifestPath);
   } catch (err) {
     try {
-      fs10.rmSync(tempPath, { force: true });
+      fs11.rmSync(tempPath, { force: true });
     } catch {
     }
     throw err;
@@ -7325,31 +7549,31 @@ function swapIntoPlace(stagingDir, outDir) {
 }
 function swapOnce(stagingDir, outDir) {
   const backupDir = `${outDir}.backup-${process.pid}-${Date.now()}`;
-  const hadPrevious = fs10.existsSync(outDir);
-  if (hadPrevious) fs10.renameSync(outDir, backupDir);
+  const hadPrevious = fs11.existsSync(outDir);
+  if (hadPrevious) fs11.renameSync(outDir, backupDir);
   try {
     try {
-      fs10.renameSync(stagingDir, outDir);
+      fs11.renameSync(stagingDir, outDir);
     } catch (err) {
       if (err.code !== "EXDEV") throw err;
       const partialDir = `${outDir}.partial-${process.pid}-${Date.now()}`;
       try {
-        fs10.cpSync(stagingDir, partialDir, { recursive: true });
-        fs10.renameSync(partialDir, outDir);
-        fs10.rmSync(stagingDir, { recursive: true, force: true });
+        fs11.cpSync(stagingDir, partialDir, { recursive: true });
+        fs11.renameSync(partialDir, outDir);
+        fs11.rmSync(stagingDir, { recursive: true, force: true });
       } catch (copyErr) {
         try {
-          fs10.rmSync(partialDir, { recursive: true, force: true });
+          fs11.rmSync(partialDir, { recursive: true, force: true });
         } catch {
         }
         throw copyErr;
       }
     }
-    if (hadPrevious) fs10.rmSync(backupDir, { recursive: true, force: true });
+    if (hadPrevious) fs11.rmSync(backupDir, { recursive: true, force: true });
   } catch (err) {
-    if (hadPrevious && fs10.existsSync(backupDir)) {
-      if (fs10.existsSync(outDir)) fs10.rmSync(outDir, { recursive: true, force: true });
-      fs10.renameSync(backupDir, outDir);
+    if (hadPrevious && fs11.existsSync(backupDir)) {
+      if (fs11.existsSync(outDir)) fs11.rmSync(outDir, { recursive: true, force: true });
+      fs11.renameSync(backupDir, outDir);
     }
     throw err;
   }
@@ -7444,8 +7668,8 @@ function generateSnapshot(configInput, options) {
     // first run cannot have marked them yet, so the name alone keeps a run from recording its own
     // output — but only at these exact paths, not at every directory that shares the name.
     toolOwnedPaths: [config.outDir, config.tmpDir].map(
-      (directory) => path11.relative(config.cwd, path11.resolve(config.cwd, directory)).replace(/\\/g, "/")
-    ).filter((relative8) => relative8.length > 0 && !relative8.startsWith(".."))
+      (directory) => path12.relative(config.cwd, path12.resolve(config.cwd, directory)).replace(/\\/g, "/")
+    ).filter((relative11) => relative11.length > 0 && !relative11.startsWith(".."))
   });
   const files = [];
   const monolithBodies = /* @__PURE__ */ new Map();
@@ -7465,12 +7689,12 @@ function generateSnapshot(configInput, options) {
   let totalSizeBytes = 0;
   let largeFileCount = 0;
   for (const relativePath of collection.files) {
-    const absolutePath = path11.join(config.cwd, relativePath);
+    const absolutePath = path12.join(config.cwd, relativePath);
     let stats;
     try {
-      stats = fs10.statSync(absolutePath);
+      stats = fs11.statSync(absolutePath);
       if (!stats.isFile()) {
-        const nestedRepository = stats.isDirectory() && fs10.existsSync(path11.join(absolutePath, ".git"));
+        const nestedRepository = stats.isDirectory() && fs11.existsSync(path12.join(absolutePath, ".git"));
         skipped.push(
           nestedRepository ? {
             path: relativePath,
@@ -7490,7 +7714,7 @@ function generateSnapshot(configInput, options) {
     }
     let buffer;
     try {
-      buffer = fs10.readFileSync(absolutePath);
+      buffer = fs11.readFileSync(absolutePath);
     } catch {
       skipped.push({ path: relativePath, reason: "read-error" });
       continue;
@@ -7820,12 +8044,12 @@ function generateSnapshot(configInput, options) {
   let stagingDir = null;
   try {
     ensureParentDirectory(outDir, "outDir");
-    fs10.mkdirSync(tmpDir, { recursive: true });
+    fs11.mkdirSync(tmpDir, { recursive: true });
     cleanStaleRunDirs(tmpDir);
     const snapshotId = crypto3.randomUUID();
     const createdAt = (/* @__PURE__ */ new Date()).toISOString();
-    stagingDir = path11.join(tmpDir, `${RUN_DIR_PREFIX}${process.pid}-${snapshotId.slice(0, 8)}`);
-    fs10.mkdirSync(stagingDir);
+    stagingDir = path12.join(tmpDir, `${RUN_DIR_PREFIX}${process.pid}-${snapshotId.slice(0, 8)}`);
+    fs11.mkdirSync(stagingDir);
     writeOwnershipMarker(stagingDir, {
       generator: GENERATOR_NAME,
       version: GENERATOR_VERSION,
@@ -7835,41 +8059,41 @@ function generateSnapshot(configInput, options) {
       id: snapshotId,
       pid: process.pid
     });
-    const partsDir = path11.join(stagingDir, "parts");
-    const reportsDir = path11.join(stagingDir, "reports");
-    if (artifacts.parts) fs10.mkdirSync(partsDir, { recursive: true });
+    const partsDir = path12.join(stagingDir, "parts");
+    const reportsDir = path12.join(stagingDir, "reports");
+    if (artifacts.parts) fs11.mkdirSync(partsDir, { recursive: true });
     if (artifacts.navigation || artifacts.projectTree || artifacts.audit) {
-      fs10.mkdirSync(reportsDir, { recursive: true });
+      fs11.mkdirSync(reportsDir, { recursive: true });
     }
     if (artifacts.parts) {
       for (const part of parts) {
-        fs10.writeFileSync(path11.join(partsDir, part.filename), part.markdown, "utf8");
+        fs11.writeFileSync(path12.join(partsDir, part.filename), part.markdown, "utf8");
       }
     }
     if (projectTree !== null) {
-      fs10.writeFileSync(path11.join(reportsDir, "project-tree.md"), projectTree, "utf8");
+      fs11.writeFileSync(path12.join(reportsDir, "project-tree.md"), projectTree, "utf8");
     }
     if (artifacts.navigation) {
-      fs10.writeFileSync(path11.join(reportsDir, "navigation.md"), generateNavigation(manifest), "utf8");
+      fs11.writeFileSync(path12.join(reportsDir, "navigation.md"), generateNavigation(manifest), "utf8");
     }
     if (artifacts.audit) {
-      fs10.writeFileSync(
-        path11.join(reportsDir, "audit.md"),
+      fs11.writeFileSync(
+        path12.join(reportsDir, "audit.md"),
         generateAuditReport(manifest, secretFindings, config.secretRules),
         "utf8"
       );
     }
     if (artifacts.readme) {
-      fs10.writeFileSync(path11.join(stagingDir, "README.md"), generateReadme(manifest, artifacts), "utf8");
+      fs11.writeFileSync(path12.join(stagingDir, "README.md"), generateReadme(manifest, artifacts), "utf8");
     }
     if (artifacts.manifest) {
-      fs10.writeFileSync(path11.join(stagingDir, "manifest.json"), JSON.stringify(manifest, null, 2), "utf8");
+      fs11.writeFileSync(path12.join(stagingDir, "manifest.json"), JSON.stringify(manifest, null, 2), "utf8");
     }
     if (monolithJson !== null) {
-      fs10.writeFileSync(path11.join(stagingDir, "full-codebase.json"), monolithJson, "utf8");
+      fs11.writeFileSync(path12.join(stagingDir, "full-codebase.json"), monolithJson, "utf8");
     }
     if (monolithMarkdown !== null) {
-      fs10.writeFileSync(path11.join(stagingDir, "full-codebase.md"), monolithMarkdown, "utf8");
+      fs11.writeFileSync(path12.join(stagingDir, "full-codebase.md"), monolithMarkdown, "utf8");
     }
     writeOwnershipMarker(stagingDir, markerPayload(stagingDir, "complete", snapshotId, createdAt));
     swapIntoPlace(stagingDir, outDir);
@@ -7878,7 +8102,7 @@ function generateSnapshot(configInput, options) {
     const pendingHook = runAfterGenerate(config, manifest);
     const shipHookState = () => {
       if (artifacts.manifest && manifest.warnings.length !== warningsBeforeHook) {
-        writeManifestAtomically(path11.join(outDir, "manifest.json"), manifest);
+        writeManifestAtomically(path12.join(outDir, "manifest.json"), manifest);
       }
       writeOwnershipMarker(outDir, markerPayload(outDir, "complete", snapshotId, createdAt));
     };
@@ -7901,7 +8125,7 @@ function generateSnapshot(configInput, options) {
   } catch (err) {
     if (stagingDir !== null) {
       try {
-        fs10.rmSync(stagingDir, { recursive: true, force: true });
+        fs11.rmSync(stagingDir, { recursive: true, force: true });
       } catch {
       }
     }
@@ -7912,143 +8136,1144 @@ function generateSnapshot(configInput, options) {
   }
 }
 
-// src/agent/option-scope.ts
-var VALIDATE_OPTIONS = [
-  "cwd",
-  "out-dir",
-  "max-part-bytes",
-  "large-file-bytes",
-  "max-monolith-bytes",
-  "include-monolith",
-  "include-sensitive-files",
-  "skip-artifacts",
-  "only-artifacts",
-  "no-config",
-  "discovery",
-  "format",
-  "mode",
-  "help",
-  "version"
-];
-var COMMAND_OPTION_SCOPE = {
-  generate: [
-    "cwd",
-    "out-dir",
-    "max-part-bytes",
-    "large-file-bytes",
-    "max-monolith-bytes",
-    "include-monolith",
-    "include-sensitive-files",
-    "skip-artifacts",
-    "only-artifacts",
-    "no-config",
-    "discovery",
-    "format",
-    "mode",
-    "dry-run",
-    "watch",
-    "help",
-    "version"
-  ],
-  validate: VALIDATE_OPTIONS,
-  report: [
-    "cwd",
-    "out-dir",
-    "max-part-bytes",
-    "large-file-bytes",
-    "max-monolith-bytes",
-    "include-monolith",
-    "include-sensitive-files",
-    "skip-artifacts",
-    "only-artifacts",
-    "no-config",
-    "format",
-    "mode",
-    "help",
-    "version"
-  ],
-  explain: [
-    "cwd",
-    "out-dir",
-    "max-part-bytes",
-    "large-file-bytes",
-    "max-monolith-bytes",
-    "include-monolith",
-    "include-sensitive-files",
-    "skip-artifacts",
-    "only-artifacts",
-    "no-config",
-    "discovery",
-    "format",
-    "mode",
-    "help",
-    "version"
-  ],
-  diff: ["format", "mode", "no-config", "help", "version"],
-  describe: ["format", "mode", "help", "version"],
-  init: [
-    "cwd",
-    "out-dir",
-    "max-part-bytes",
-    "include-sensitive-files",
-    "skip-artifacts",
-    "only-artifacts",
-    "preset",
-    "include",
-    "exclude",
-    "yes",
-    "force",
-    "dry-run",
-    "format",
-    "mode",
-    "help",
-    "version"
-  ],
-  skill: ["cwd", "format", "mode", "install", "target", "help", "version"],
-  setup: [
-    "cwd",
-    "out-dir",
-    "max-part-bytes",
-    "include-sensitive-files",
-    "skip-artifacts",
-    "only-artifacts",
-    "preset",
-    "include",
-    "exclude",
-    "yes",
-    "force",
-    "no-install",
-    "dry-run",
-    "format",
-    "mode",
-    "help",
-    "version"
-  ]
-};
-var COMMAND_ORDER = [
-  "generate",
-  "validate",
-  "report",
-  "explain",
-  "init",
-  "setup",
-  "diff",
-  "describe",
-  "skill"
-];
-function commandsForOption(option) {
-  return COMMAND_ORDER.filter((command) => COMMAND_OPTION_SCOPE[command].includes(option));
+// src/mcp/tools.ts
+import * as fs13 from "fs";
+import * as path14 from "path";
+
+// src/mcp/part.ts
+var FILE_HEADING = "### FILE: ";
+var CONTENT_MARKERS = /* @__PURE__ */ new Set(["#### Content", "#### Bounded Preview"]);
+function parsePartSections(partText) {
+  const lines = partText.split("\n");
+  const sections = [];
+  let index = 0;
+  while (index < lines.length) {
+    if (!lines[index].startsWith(FILE_HEADING)) {
+      index += 1;
+      continue;
+    }
+    const heading = lines[index].slice(FILE_HEADING.length);
+    let cursor = index + 1;
+    let inclusion = null;
+    let sha256 = null;
+    let includedLines = null;
+    while (cursor < lines.length && !CONTENT_MARKERS.has(lines[cursor])) {
+      const line = lines[cursor];
+      if (line.startsWith(FILE_HEADING)) break;
+      if (line.startsWith("- Inclusion: ")) inclusion = line.slice("- Inclusion: ".length).trim();
+      else if (line.startsWith("- SHA-256: ")) sha256 = line.slice("- SHA-256: ".length).trim();
+      else if (line.startsWith("- Included Lines: ")) {
+        const value = Number(line.slice("- Included Lines: ".length).trim());
+        includedLines = Number.isFinite(value) ? value : null;
+      }
+      cursor += 1;
+    }
+    if (cursor >= lines.length || !CONTENT_MARKERS.has(lines[cursor])) {
+      index = cursor + 1;
+      continue;
+    }
+    let fenceLine = cursor + 1;
+    while (fenceLine < lines.length && lines[fenceLine].trim().length === 0) fenceLine += 1;
+    const fenceMatch = /^(`{4,})/.exec(lines[fenceLine] ?? "");
+    if (!fenceMatch) {
+      index = cursor + 1;
+      continue;
+    }
+    const fence = fenceMatch[1];
+    const body = [];
+    let bodyLine = fenceLine + 1;
+    while (bodyLine < lines.length && lines[bodyLine] !== fence) {
+      body.push(lines[bodyLine]);
+      bodyLine += 1;
+    }
+    sections.push({ path: heading, body: body.join("\n"), inclusion, sha256, includedLines });
+    index = bodyLine + 1;
+  }
+  return sections;
+}
+function findSection(sections, relativePath, sha256) {
+  const exact = sections.find((section) => section.path === relativePath);
+  if (exact) return exact;
+  if (sha256) {
+    const byHash = sections.filter((section) => section.sha256 === sha256);
+    if (byHash.length === 1) return byHash[0];
+    if (byHash.length > 1) {
+      const byPath = byHash.find(
+        (section) => section.path.toLowerCase() === relativePath.toLowerCase()
+      );
+      if (byPath) return byPath;
+    }
+  }
+  const folded = sections.filter((section) => section.path.toLowerCase() === relativePath.toLowerCase());
+  return folded.length === 1 ? folded[0] : null;
 }
-function optionAppliesTo(option) {
-  return commandsForOption(option).join("/");
+function windowText(body, fromLine, lineCount) {
+  const lines = body.split("\n");
+  const total = lines.length;
+  const start = Math.min(Math.max(1, Math.trunc(fromLine)), Math.max(1, total));
+  const end = Math.min(total, start + Math.max(1, Math.trunc(lineCount)) - 1);
+  const slice = lines.slice(start - 1, end);
+  return {
+    text: slice.join("\n"),
+    fromLine: start,
+    returnedLines: slice.length,
+    totalLines: total,
+    truncated: end < total,
+    nextFromLine: end < total ? end + 1 : null
+  };
 }
 
-// src/agent/contract.ts
-var CONTRACT_VERSION = "1.0.0";
-var PACKAGE_NAME = "codebase-snapshot";
-var MAJOR_VERSION = GENERATOR_VERSION.split(".")[0];
-var ARTIFACT_SUMMARY = {
-  readme: "README.md describing the snapshot at the output root.",
+// src/mcp/workspace.ts
+import * as fs12 from "fs";
+import * as path13 from "path";
+function foldForComparison(value) {
+  return process.platform === "win32" || process.platform === "darwin" ? value.toLowerCase() : value;
+}
+function canonicalPath(value) {
+  const absolute = path13.resolve(value);
+  try {
+    return fs12.realpathSync(absolute);
+  } catch {
+    return absolute;
+  }
+}
+function isInside2(parent, child) {
+  const foldedParent = foldForComparison(parent);
+  const foldedChild = foldForComparison(child);
+  return foldedChild === foldedParent || foldedChild.startsWith(`${foldedParent}${path13.sep}`);
+}
+function resolveRoot(requested, context) {
+  if (requested !== void 0 && (typeof requested !== "string" || requested.trim().length === 0)) {
+    return { ok: false, message: '"root" must be a non-empty string when provided.' };
+  }
+  const wanted = typeof requested === "string" ? requested.trim() : context.cwd;
+  const absolute = path13.resolve(context.cwd, wanted);
+  let stats;
+  try {
+    stats = fs12.statSync(absolute);
+  } catch {
+    return { ok: false, message: `"${wanted}" does not exist, so it cannot be a repository root.` };
+  }
+  if (!stats.isDirectory()) {
+    return { ok: false, message: `"${wanted}" is not a directory.` };
+  }
+  const resolved = canonicalPath(absolute);
+  for (const allowed of context.roots) {
+    if (isInside2(canonicalPath(allowed), resolved)) return { ok: true, root: resolved };
+  }
+  const shown = context.roots.join(", ");
+  return {
+    ok: false,
+    message: `"${wanted}" resolves outside the directories this server may read (${shown}). Restart it with --root <path> to add a repository.`
+  };
+}
+async function openWorkspace(root, overrides = {}) {
+  const loaded = await loadConfigFileDetailed(root);
+  if (loaded.errors.length > 0) {
+    return {
+      ok: false,
+      message: `The config file could not be read: ${loaded.errors.join("; ")} Fix it, or delete it to use the defaults \u2014 this server will not silently ignore it.`
+    };
+  }
+  const cliOptions = { cwd: root };
+  if (overrides.maxPartBytes !== void 0) {
+    const parsed = parseByteSize(overrides.maxPartBytes);
+    if (parsed === void 0) {
+      return {
+        ok: false,
+        message: '"maxPartBytes" must be a byte count, for example 307200 or "300k".'
+      };
+    }
+    cliOptions.maxPartBytes = parsed;
+  }
+  if (overrides.outDir !== void 0) {
+    if (typeof overrides.outDir !== "string" || overrides.outDir.trim().length === 0) {
+      return { ok: false, message: '"outDir" must be a non-empty string.' };
+    }
+    cliOptions.outDir = overrides.outDir.trim();
+  }
+  try {
+    const config = resolveConfig(loaded.config, cliOptions, root);
+    return { ok: true, workspace: { root, config, configFile: loaded.file } };
+  } catch (error) {
+    return { ok: false, message: error instanceof Error ? error.message : String(error) };
+  }
+}
+var manifestCache = /* @__PURE__ */ new Map();
+function manifestPathFor(workspace) {
+  return path13.resolve(workspace.root, workspace.config.outDir, "manifest.json");
+}
+function readManifest3(workspace) {
+  const file = manifestPathFor(workspace);
+  const shown = path13.relative(workspace.root, file).split(path13.sep).join("/") || file;
+  let stats;
+  try {
+    stats = fs12.statSync(file);
+  } catch {
+    return {
+      ok: false,
+      missing: true,
+      message: `There is no snapshot manifest at ${shown}. Call snapshot_plan to preview what would be included, or snapshot_generate to write it.`
+    };
+  }
+  const cached = manifestCache.get(file);
+  if (cached && cached.mtimeMs === stats.mtimeMs && cached.size === stats.size) {
+    return { ok: true, manifest: cached.manifest, file };
+  }
+  let raw;
+  try {
+    raw = fs12.readFileSync(file, "utf8");
+  } catch (error) {
+    return {
+      ok: false,
+      missing: false,
+      message: `${shown} exists but could not be read: ${error instanceof Error ? error.message : String(error)}`
+    };
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return { ok: false, missing: false, message: `${shown} is not valid JSON.` };
+  }
+  const problem = describeManifestShapeProblem(parsed);
+  if (problem) {
+    return { ok: false, missing: false, message: `${shown} is not a snapshot manifest: ${problem}` };
+  }
+  const manifest = parsed;
+  manifestCache.set(file, { mtimeMs: stats.mtimeMs, size: stats.size, manifest });
+  return { ok: true, manifest, file };
+}
+function forgetManifest(file) {
+  manifestCache.delete(file);
+}
+
+// src/mcp/tools.ts
+var READ_ONLY = {
+  readOnlyHint: true,
+  destructiveHint: false,
+  idempotentHint: true,
+  openWorldHint: false
+};
+var WRITES = {
+  readOnlyHint: false,
+  // It replaces the snapshot directory but never anything it did not write, so it is additive with
+  // respect to the user's files.
+  destructiveHint: false,
+  idempotentHint: true,
+  openWorldHint: false
+};
+var MAX_RESULT_BYTES = 64 * 1024;
+var ROOT_PROPERTY = {
+  type: "string",
+  description: "Repository root. Defaults to the directory this server was started in."
+};
+function failure(message) {
+  return { text: message, isError: true };
+}
+function plural(count, word) {
+  return `${count} ${word}${count === 1 ? "" : "s"}`;
+}
+function formatBytes(bytes) {
+  if (bytes < 1024) return `${bytes} B`;
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} kB`;
+  return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+}
+function relativeFor(workspace, absolute) {
+  return path14.relative(workspace.root, absolute).split(path14.sep).join("/");
+}
+function capped(values, limit = 20) {
+  return { count: values.length, sample: values.slice(0, limit) };
+}
+function summarizeDrift(drift) {
+  return {
+    missingInSnapshot: capped(drift.missingInSnapshot),
+    missingOnDisk: capped(drift.missingOnDisk),
+    unreadable: capped(drift.unreadable),
+    hashMismatches: capped(drift.hashMismatches),
+    partIssues: capped(drift.partIssues),
+    totalsMismatches: capped(drift.totalsMismatches),
+    configMismatches: capped(drift.configMismatches)
+  };
+}
+function toRelativePath(root, value) {
+  const cleaned = value.trim();
+  if (cleaned.length === 0) return null;
+  if (!path14.isAbsolute(cleaned)) {
+    return cleaned.replace(/\\/g, "/").replace(/^\.\//, "");
+  }
+  const relative11 = path14.relative(root, cleaned);
+  if (relative11.startsWith("..") || path14.isAbsolute(relative11)) return null;
+  return relative11.split(path14.sep).join("/");
+}
+function symbolsOf(entry) {
+  const summary = entry.summary;
+  if (!summary || typeof summary !== "object" || !("exports" in summary)) return [];
+  const source = summary;
+  return [...source.exports, ...source.reactComponents, ...source.routeHandlers];
+}
+async function prepare(args, context, overrides = {}) {
+  const rootOutcome = resolveRoot(args.root, context);
+  if (!rootOutcome.ok) return { ok: false, outcome: failure(rootOutcome.message) };
+  const opened = await openWorkspace(rootOutcome.root, overrides);
+  if (!opened.ok) return { ok: false, outcome: failure(opened.message) };
+  return { ok: true, workspace: opened.workspace };
+}
+var statusTool = {
+  name: "snapshot_status",
+  title: "Snapshot status",
+  description: "Report whether a snapshot exists for this repository, when it was built, and what it covers. Reads the manifest rather than the repository, so it is cheap. Call it before deciding whether a snapshot needs to be generated.",
+  inputSchema: {
+    type: "object",
+    properties: { root: ROOT_PROPERTY },
+    additionalProperties: false
+  },
+  outputSchema: {
+    type: "object",
+    properties: {
+      present: { type: "boolean" },
+      root: { type: "string" },
+      outDir: { type: "string" },
+      fingerprint: { type: "string" },
+      generatedAt: { type: "string" },
+      generatorVersion: { type: "string" },
+      generatorVersionMatches: { type: "boolean" },
+      includedFiles: { type: "integer" },
+      skippedFiles: { type: "integer" },
+      partCount: { type: "integer" },
+      warningCount: { type: "integer" }
+    }
+  },
+  annotations: READ_ONLY,
+  async handler(args, context) {
+    const prepared = await prepare(args, context);
+    if (!prepared.ok) return prepared.outcome;
+    const workspace = prepared.workspace;
+    const read = readManifest3(workspace);
+    if (!read.ok) {
+      return {
+        text: read.message,
+        structured: {
+          present: false,
+          root: workspace.root,
+          outDir: workspace.config.outDir,
+          message: read.message
+        }
+      };
+    }
+    const manifest = read.manifest;
+    const versionMatches = manifest.generator.version === GENERATOR_VERSION;
+    const lines = [
+      `Snapshot: ${workspace.config.outDir}/`,
+      `Generated: ${manifest.generatedAt} by ${manifest.generator.name} ${manifest.generator.version}`,
+      `Files: ${manifest.counts.totalFiles} included, ${manifest.counts.skippedCount} skipped, ${plural(manifest.counts.partsCount, "part")}`,
+      `Content: ${formatBytes(manifest.counts.totalSizeBytes)} of source in ${formatBytes(manifest.totals.totalContentBytes)} emitted`,
+      `Fingerprint: ${manifest.fingerprint}`,
+      `Git: ${manifest.git.branch} @ ${manifest.git.commit}${manifest.git.isDirty ? " (dirty)" : " (clean)"}`
+    ];
+    if (manifest.totals.warningCount > 0) lines.push(`Warnings: ${manifest.totals.warningCount}`);
+    if (!versionMatches) {
+      lines.push(
+        `Note: written by ${manifest.generator.version}, this server is ${GENERATOR_VERSION}. Re-run snapshot_generate if the difference matters.`
+      );
+    }
+    return {
+      text: lines.join("\n"),
+      structured: {
+        present: true,
+        root: workspace.root,
+        outDir: workspace.config.outDir,
+        fingerprint: manifest.fingerprint,
+        generatedAt: manifest.generatedAt,
+        generatorVersion: manifest.generator.version,
+        generatorVersionMatches: versionMatches,
+        includedFiles: manifest.counts.totalFiles,
+        skippedFiles: manifest.counts.skippedCount,
+        partCount: manifest.counts.partsCount,
+        warningCount: manifest.totals.warningCount,
+        preset: manifest.config.preset,
+        maxPartBytes: manifest.budgets.maxPartBytes
+      }
+    };
+  }
+};
+var planTool = {
+  name: "snapshot_plan",
+  title: "Preview a snapshot",
+  description: "Preview a snapshot without writing anything: how many files and parts it would contain, and why every excluded file was excluded. Use it to choose a part budget before generating.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      root: ROOT_PROPERTY,
+      maxPartBytes: {
+        type: "string",
+        description: 'Byte budget per part, for example 307200 or "300k". Defaults to the project configuration.'
+      }
+    },
+    additionalProperties: false
+  },
+  outputSchema: {
+    type: "object",
+    properties: {
+      files: { type: "integer" },
+      skipped: { type: "integer" },
+      parts: { type: "integer" },
+      sourceBytes: { type: "integer" },
+      emittedBytes: { type: "integer" },
+      preset: { type: "string" }
+    }
+  },
+  annotations: READ_ONLY,
+  async handler(args, context) {
+    const prepared = await prepare(args, context, { maxPartBytes: args.maxPartBytes });
+    if (!prepared.ok) return prepared.outcome;
+    const workspace = prepared.workspace;
+    let manifest;
+    try {
+      manifest = generateSnapshot(workspace.config, { dryRun: true });
+    } catch (error) {
+      return failure(error instanceof Error ? error.message : String(error));
+    }
+    const reasons = /* @__PURE__ */ new Map();
+    for (const record of manifest.skipped) {
+      reasons.set(record.reason, (reasons.get(record.reason) ?? 0) + 1);
+    }
+    const topReasons = [...reasons.entries()].sort((a, b) => b[1] - a[1] || (a[0] < b[0] ? -1 : 1)).slice(0, 8).map(([reason, count]) => ({ reason, count }));
+    const lines = [
+      "Dry run \u2014 nothing was written.",
+      `Preset: ${manifest.config.preset}`,
+      `Would include ${plural(manifest.counts.totalFiles, "file")} in ${plural(manifest.counts.partsCount, "part")} (${formatBytes(manifest.counts.totalSizeBytes)} of source, ${formatBytes(manifest.totals.totalContentBytes)} emitted).`,
+      `Would skip ${plural(manifest.counts.skippedCount, "file")}.`
+    ];
+    if (topReasons.length > 0) {
+      lines.push("Top skip reasons:");
+      for (const entry of topReasons) lines.push(`  - ${entry.reason} (${entry.count})`);
+    }
+    if (manifest.warnings.length > 0) {
+      lines.push(`Warnings (${manifest.warnings.length}):`);
+      for (const warning of manifest.warnings.slice(0, 5)) lines.push(`  - ${warning}`);
+    }
+    return {
+      text: lines.join("\n"),
+      structured: {
+        files: manifest.counts.totalFiles,
+        skipped: manifest.counts.skippedCount,
+        parts: manifest.counts.partsCount,
+        sourceBytes: manifest.counts.totalSizeBytes,
+        emittedBytes: manifest.totals.totalContentBytes,
+        preset: manifest.config.preset,
+        maxPartBytes: manifest.budgets.maxPartBytes,
+        layers: manifest.layers,
+        skipReasons: topReasons,
+        warnings: manifest.warnings.slice(0, 5),
+        warningCount: manifest.warnings.length
+      }
+    };
+  }
+};
+var generateTool = {
+  name: "snapshot_generate",
+  title: "Generate the snapshot",
+  description: "Write the snapshot to its output directory and return its fingerprint, parts and counts. Replaces the previous snapshot in that directory. A large repository can take several seconds.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      root: ROOT_PROPERTY,
+      maxPartBytes: {
+        type: "string",
+        description: 'Byte budget per part, for example 307200 or "300k". Defaults to the project configuration.'
+      },
+      outDir: {
+        type: "string",
+        description: "Output directory relative to the root. Defaults to the project configuration."
+      }
+    },
+    additionalProperties: false
+  },
+  outputSchema: {
+    type: "object",
+    properties: {
+      fingerprint: { type: "string" },
+      files: { type: "integer" },
+      skipped: { type: "integer" },
+      parts: { type: "integer" },
+      emittedBytes: { type: "integer" }
+    }
+  },
+  annotations: WRITES,
+  async handler(args, context) {
+    const prepared = await prepare(args, context, {
+      maxPartBytes: args.maxPartBytes,
+      outDir: args.outDir
+    });
+    if (!prepared.ok) return prepared.outcome;
+    const workspace = prepared.workspace;
+    let manifest;
+    try {
+      manifest = generateSnapshot(workspace.config);
+    } catch (error) {
+      return failure(error instanceof Error ? error.message : String(error));
+    }
+    forgetManifest(manifestPathFor(workspace));
+    const written = relativeFor(workspace, path14.resolve(workspace.root, workspace.config.outDir));
+    const lines = [
+      `Wrote ${written}/`,
+      `Files: ${manifest.counts.totalFiles} included, ${manifest.counts.skippedCount} skipped, ${plural(manifest.counts.partsCount, "part")}`,
+      `Parts: ${manifest.parts.map((part) => `${part.filename} (${formatBytes(part.byteSize)})`).join(", ")}`,
+      `Fingerprint: ${manifest.fingerprint}`
+    ];
+    if (manifest.warnings.length > 0) {
+      lines.push(`Warnings (${manifest.warnings.length}):`);
+      for (const warning of manifest.warnings.slice(0, 5)) lines.push(`  - ${warning}`);
+    }
+    return {
+      text: lines.join("\n"),
+      structured: {
+        fingerprint: manifest.fingerprint,
+        files: manifest.counts.totalFiles,
+        skipped: manifest.counts.skippedCount,
+        parts: manifest.counts.partsCount,
+        emittedBytes: manifest.totals.totalContentBytes,
+        outDir: written,
+        partFiles: manifest.parts.map((part) => part.filename),
+        warningCount: manifest.warnings.length
+      }
+    };
+  }
+};
+var validateTool = {
+  name: "snapshot_validate",
+  title: "Validate the snapshot",
+  description: "Re-read the repository and report whether the snapshot on disk still matches it. Use it before trusting context that came from an earlier session, or after changing the config.",
+  inputSchema: {
+    type: "object",
+    properties: { root: ROOT_PROPERTY },
+    additionalProperties: false
+  },
+  outputSchema: {
+    type: "object",
+    properties: {
+      current: { type: "boolean" },
+      manifestPresent: { type: "boolean" }
+    }
+  },
+  annotations: READ_ONLY,
+  async handler(args, context) {
+    const prepared = await prepare(args, context);
+    if (!prepared.ok) return prepared.outcome;
+    const workspace = prepared.workspace;
+    let result;
+    try {
+      result = validateSnapshot(workspace.config);
+    } catch (error) {
+      return failure(error instanceof Error ? error.message : String(error));
+    }
+    const lines = [];
+    if (result.valid) {
+      lines.push("The snapshot matches the repository.");
+    } else {
+      lines.push("The snapshot is out of date.");
+      const drift = result.drift;
+      const observations = [
+        ["file(s) changed on disk", drift.hashMismatches.length],
+        ["file(s) added since the snapshot", drift.missingInSnapshot.length],
+        ["file(s) gone since the snapshot", drift.missingOnDisk.length],
+        ["part file(s) damaged or missing", drift.partIssues.length],
+        ["setting(s) changed since the snapshot", drift.configMismatches.length],
+        ["internal count(s) disagreeing", drift.totalsMismatches.length]
+      ];
+      for (const [label, count] of observations) {
+        if (count > 0) lines.push(`  - ${count} ${label}`);
+      }
+      for (const error of result.errors.slice(0, 5)) lines.push(`  - ${error}`);
+      lines.push("Run snapshot_generate to refresh it.");
+    }
+    for (const warning of result.warnings.slice(0, 5)) lines.push(`Note: ${warning}`);
+    return {
+      text: lines.join("\n"),
+      structured: {
+        current: result.valid,
+        manifestPresent: result.manifestPresent,
+        drift: summarizeDrift(result.drift),
+        errors: result.errors.slice(0, 10),
+        warnings: result.warnings.slice(0, 10)
+      }
+      // A stale snapshot is an answer, not a tool failure: the caller asked whether it is current.
+    };
+  }
+};
+var locateTool = {
+  name: "snapshot_locate",
+  title: "Locate code in the snapshot",
+  description: "Find which part holds the code you need. Matches file paths, exported symbols, component names and routes from the snapshot's index, so one part can be read instead of all of them.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      query: {
+        type: "string",
+        description: "Text to match, case-insensitively, against paths and exported symbols."
+      },
+      by: {
+        type: "string",
+        enum: ["auto", "path", "symbol", "route", "layer", "kind"],
+        default: "auto",
+        description: "Restrict what is matched. Defaults to every category."
+      },
+      limit: {
+        type: "integer",
+        minimum: 1,
+        maximum: 100,
+        default: 20,
+        description: "Maximum matches to return."
+      },
+      root: ROOT_PROPERTY
+    },
+    required: ["query"],
+    additionalProperties: false
+  },
+  outputSchema: {
+    type: "object",
+    properties: { total: { type: "integer" } }
+  },
+  annotations: READ_ONLY,
+  async handler(args, context) {
+    const prepared = await prepare(args, context);
+    if (!prepared.ok) return prepared.outcome;
+    const workspace = prepared.workspace;
+    const read = readManifest3(workspace);
+    if (!read.ok) return failure(read.message);
+    const query = String(args.query ?? "").trim();
+    if (query.length === 0) return failure('"query" must not be empty.');
+    const needle = query.toLowerCase();
+    const by = typeof args.by === "string" ? args.by : "auto";
+    const limit = typeof args.limit === "number" ? args.limit : 20;
+    const manifest = read.manifest;
+    const matches = [];
+    const add = (entry, matchedBy, detail) => {
+      matches.push({
+        path: entry.relativePath,
+        part: entry.part,
+        layer: entry.layer,
+        kind: entry.kind,
+        matchedBy,
+        ...detail ? { detail } : {}
+      });
+    };
+    const wants = (category) => by === "auto" || by === category;
+    for (const entry of manifest.files) {
+      if (wants("path") && entry.relativePath.toLowerCase().includes(needle)) {
+        add(entry, "path");
+        continue;
+      }
+      if (wants("symbol")) {
+        const symbol = symbolsOf(entry).find((name) => name.toLowerCase().includes(needle));
+        if (symbol) {
+          add(entry, "symbol", symbol);
+          continue;
+        }
+      }
+      if (wants("layer") && entry.layer.toLowerCase() === needle) add(entry, "layer");
+      else if (wants("kind") && entry.kind.toLowerCase() === needle) add(entry, "kind");
+    }
+    if (wants("route")) {
+      for (const route of manifest.indexes.routes) {
+        if (!route.path.toLowerCase().includes(needle)) continue;
+        if (matches.some((match) => match.path === route.path)) continue;
+        matches.push({
+          path: route.path,
+          part: route.part,
+          layer: "route",
+          kind: "route",
+          matchedBy: "route",
+          detail: route.methods.join(", ")
+        });
+      }
+    }
+    if (matches.length === 0) {
+      return {
+        text: `Nothing in the snapshot matches "${query}". Try a shorter fragment, or snapshot_explain a path to see whether it is included at all.`,
+        structured: { total: 0, matches: [] }
+      };
+    }
+    const shown = matches.slice(0, limit);
+    const lines = [
+      `${matches.length} match${matches.length === 1 ? "" : "es"} for "${query}"` + (matches.length > shown.length ? ` (showing ${shown.length})` : "") + ":"
+    ];
+    for (const match of shown) {
+      const detail = match.detail ? ` \u2014 ${match.detail}` : "";
+      lines.push(`  ${match.path}${detail}  [${match.part}, ${match.layer}/${match.kind}]`);
+    }
+    if (matches.length > shown.length) {
+      lines.push("Raise `limit` to see more.");
+    }
+    return {
+      text: lines.join("\n"),
+      structured: { total: matches.length, returned: shown.length, matches: shown }
+    };
+  }
+};
+var readTool = {
+  name: "snapshot_read",
+  title: "Read a file from the snapshot",
+  description: "Return a line window of one file as the snapshot contains it: redacted, and bounded to a preview when the source is large. Reports the next `fromLine` when more remains.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      path: {
+        type: "string",
+        description: "File path relative to the repository root, as snapshot_locate reports it."
+      },
+      fromLine: {
+        type: "integer",
+        minimum: 1,
+        default: 1,
+        description: "First line to return, 1-based."
+      },
+      lines: {
+        type: "integer",
+        minimum: 1,
+        maximum: 2e3,
+        default: 200,
+        description: "How many lines to return."
+      },
+      root: ROOT_PROPERTY
+    },
+    required: ["path"],
+    additionalProperties: false
+  },
+  outputSchema: {
+    type: "object",
+    properties: {
+      path: { type: "string" },
+      part: { type: "string" },
+      fromLine: { type: "integer" },
+      returnedLines: { type: "integer" },
+      totalLines: { type: "integer" },
+      nextFromLine: { type: "integer" }
+    }
+  },
+  annotations: READ_ONLY,
+  async handler(args, context) {
+    const prepared = await prepare(args, context);
+    if (!prepared.ok) return prepared.outcome;
+    const workspace = prepared.workspace;
+    if (typeof args.path !== "string") return failure('"path" must be a string.');
+    const relativePath = toRelativePath(workspace.root, args.path);
+    if (!relativePath) {
+      return failure(
+        `"${args.path}" is outside ${workspace.root}. Paths are read relative to the repository root.`
+      );
+    }
+    const read = readManifest3(workspace);
+    if (!read.ok) return failure(read.message);
+    const manifest = read.manifest;
+    const entry = manifest.files.find((file) => file.relativePath === relativePath) ?? manifest.files.find((file) => file.relativePath.toLowerCase() === relativePath.toLowerCase());
+    if (!entry) {
+      const skipped = manifest.skipped.find((record) => record.path === relativePath);
+      if (skipped) {
+        const detail = skipped.detail ? ` (${skipped.detail})` : "";
+        return failure(
+          `${relativePath} is not in the snapshot: ${skipped.reason}${detail}. Sensitive and ignored files stay out unless they are included explicitly.`
+        );
+      }
+      return failure(
+        `${relativePath} is not in the snapshot. Call snapshot_locate to find the path, or snapshot_explain to learn why it was excluded.`
+      );
+    }
+    const partPath = path14.resolve(workspace.root, workspace.config.outDir, "parts", entry.part);
+    let partText;
+    try {
+      partText = fs13.readFileSync(partPath, "utf8");
+    } catch {
+      return failure(
+        `${entry.part} could not be read, so the snapshot is damaged. Run snapshot_generate to rebuild it.`
+      );
+    }
+    const section = findSection(parsePartSections(partText), entry.relativePath, entry.hashSha256);
+    if (!section) {
+      return failure(
+        `${relativePath} is recorded in ${entry.part} but its section could not be located there. Run snapshot_generate to rebuild the snapshot.`
+      );
+    }
+    const fromLine = typeof args.fromLine === "number" ? args.fromLine : 1;
+    const lineCount = typeof args.lines === "number" ? args.lines : 200;
+    const window = windowText(section.body, fromLine, lineCount);
+    let body = window.text;
+    let truncatedByBytes = false;
+    if (Buffer.byteLength(body, "utf8") > MAX_RESULT_BYTES) {
+      body = body.slice(0, MAX_RESULT_BYTES);
+      const lastBreak = body.lastIndexOf("\n");
+      body = lastBreak > 0 ? body.slice(0, lastBreak) : body;
+      truncatedByBytes = true;
+    }
+    const returnedLines = body.length === 0 ? 0 : body.split("\n").length;
+    const moreRemain = window.truncated || truncatedByBytes;
+    const header = [
+      `${entry.relativePath} \u2014 ${entry.part}, ${entry.layer}/${entry.kind}, ${entry.language}`,
+      section.inclusion === "preview" ? "Bounded preview: this source file is large, so the snapshot holds only its head and tail." : `Lines ${window.fromLine}\u2013${window.fromLine + returnedLines - 1} of ${window.totalLines}.`
+    ];
+    const lines = [...header, "", body];
+    if (moreRemain) {
+      const next = window.fromLine + returnedLines;
+      lines.push("", `Truncated. Call snapshot_read with fromLine=${next} for the rest.`);
+    }
+    return {
+      text: lines.join("\n"),
+      structured: {
+        path: entry.relativePath,
+        part: entry.part,
+        layer: entry.layer,
+        kind: entry.kind,
+        language: entry.language,
+        inclusion: section.inclusion ?? entry.inclusionMode,
+        fromLine: window.fromLine,
+        returnedLines,
+        totalLines: window.totalLines,
+        truncated: moreRemain,
+        nextFromLine: moreRemain ? window.fromLine + returnedLines : null,
+        sha256: entry.hashSha256
+      }
+    };
+  }
+};
+var explainTool = {
+  name: "snapshot_explain",
+  title: "Explain one path",
+  description: 'Explain how the next snapshot would treat one path: its layer, kind, language and part, or the exact reason it is excluded. Answers "why is this file missing".',
+  inputSchema: {
+    type: "object",
+    properties: {
+      path: {
+        type: "string",
+        description: "Path relative to the repository root. Directories are explained as a whole."
+      },
+      root: ROOT_PROPERTY
+    },
+    required: ["path"],
+    additionalProperties: false
+  },
+  outputSchema: {
+    type: "object",
+    properties: {
+      path: { type: "string" },
+      included: { type: "boolean" },
+      reason: { type: "string" }
+    }
+  },
+  annotations: READ_ONLY,
+  async handler(args, context) {
+    const prepared = await prepare(args, context);
+    if (!prepared.ok) return prepared.outcome;
+    const workspace = prepared.workspace;
+    if (typeof args.path !== "string") return failure('"path" must be a string.');
+    const relativePath = toRelativePath(workspace.root, args.path);
+    if (!relativePath) {
+      return failure(`"${args.path}" is outside ${workspace.root}.`);
+    }
+    let result;
+    try {
+      result = explainPath(workspace.config, relativePath);
+    } catch (error) {
+      return failure(error instanceof Error ? error.message : String(error));
+    }
+    return {
+      text: renderExplainText(result),
+      structured: {
+        path: result.path,
+        included: result.included,
+        ...result.reason ? { reason: result.reason } : {},
+        ...result.detail ? { detail: result.detail } : {},
+        ...result.layer ? { layer: result.layer } : {},
+        ...result.kind ? { kind: result.kind } : {},
+        ...result.language ? { language: result.language } : {},
+        ...result.part ? { part: result.part } : {},
+        ...result.inclusionMode ? { inclusion: result.inclusionMode } : {},
+        ...typeof result.lines === "number" ? { lines: result.lines } : {},
+        ...typeof result.bytes === "number" ? { bytes: result.bytes } : {},
+        ...typeof result.secretCount === "number" ? { secretCount: result.secretCount } : {}
+      }
+    };
+  }
+};
+function buildTools() {
+  return [
+    statusTool,
+    planTool,
+    generateTool,
+    validateTool,
+    locateTool,
+    readTool,
+    explainTool
+  ];
+}
+
+// src/mcp/prompts.ts
+var ORIENT = `You have a codebase-snapshot server for this repository. Build a map of it before reading any code.
+
+1. Call snapshot_status. If no snapshot exists, call snapshot_plan to preview it, then snapshot_generate.
+2. Call snapshot_locate for the areas that matter. Search by exported symbol, route or path fragment rather than guessing filenames.
+3. Report back: the layers present, the entry points, and the files that matter here \u2014 cited as paths with their part.
+4. Read one file at a time with snapshot_read, one window at a time. Do not read a part end to end.`;
+var KEEP_CURRENT = `Keep the context you were given provably current while you work.
+
+1. Before relying on a snapshot from an earlier session, call snapshot_validate.
+2. If it reports drift, call snapshot_generate once, then snapshot_validate again.
+3. After changes you make, call snapshot_validate and report what it said.
+4. Never call a snapshot current unless snapshot_validate said so in this session.`;
+function withFocus(base, focus) {
+  return typeof focus === "string" && focus.trim().length > 0 ? `${base}
+
+Focus for this pass: ${focus.trim()}` : base;
+}
+function buildPrompts() {
+  return [
+    {
+      name: "orient",
+      title: "Orient in this repository",
+      description: "Map the repository from the snapshot before reading any of it.",
+      arguments: [
+        {
+          name: "focus",
+          description: 'Optional area to concentrate on, for example "authentication".',
+          required: false
+        }
+      ],
+      build(args) {
+        return {
+          description: "Map the repository before reading it.",
+          messages: [{ role: "user", content: { type: "text", text: withFocus(ORIENT, args.focus) } }]
+        };
+      }
+    },
+    {
+      name: "keep-current",
+      title: "Keep the snapshot current",
+      description: "Validate before trusting earlier context, and again after making changes.",
+      arguments: [],
+      build() {
+        return {
+          description: "Keep the context current.",
+          messages: [{ role: "user", content: { type: "text", text: KEEP_CURRENT } }]
+        };
+      }
+    }
+  ];
+}
+
+// src/mcp/protocol.ts
+var LEGACY_PROTOCOL_VERSIONS = ["2025-11-25", "2025-06-18"];
+var MODERN_PROTOCOL_VERSIONS = ["2026-07-28"];
+var SUPPORTED_PROTOCOL_VERSIONS = [
+  ...MODERN_PROTOCOL_VERSIONS,
+  ...LEGACY_PROTOCOL_VERSIONS
+];
+var DEFAULT_LEGACY_PROTOCOL_VERSION = LEGACY_PROTOCOL_VERSIONS[0];
+var ERROR_CODES = {
+  parseError: -32700,
+  invalidRequest: -32600,
+  methodNotFound: -32601,
+  invalidParams: -32602,
+  internalError: -32603,
+  unsupportedProtocolVersion: -32022
+};
+var METHOD3 = {
+  initialize: "initialize",
+  initialized: "notifications/initialized",
+  discover: "server/discover",
+  ping: "ping",
+  toolsList: "tools/list",
+  toolsCall: "tools/call",
+  resourcesList: "resources/list",
+  resourcesRead: "resources/read",
+  resourceTemplatesList: "resources/templates/list",
+  promptsList: "prompts/list",
+  promptsGet: "prompts/get",
+  cancelled: "notifications/cancelled"
+};
+var META_KEYS = {
+  protocolVersion: "io.modelcontextprotocol/protocolVersion",
+  clientCapabilities: "io.modelcontextprotocol/clientCapabilities",
+  clientInfo: "io.modelcontextprotocol/clientInfo",
+  serverInfo: "io.modelcontextprotocol/serverInfo",
+  progressToken: "progressToken"
+};
+function isJsonObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function serverInfoMeta(info2) {
+  const value = { name: info2.name, version: info2.version };
+  if (info2.title) value.title = info2.title;
+  return { [META_KEYS.serverInfo]: value };
+}
+function successResponse(id, result, modern, info2) {
+  if (!modern) return { jsonrpc: "2.0", id, result };
+  const withMeta = {
+    ...result,
+    resultType: "complete",
+    _meta: { ...isJsonObject(result._meta) ? result._meta : {}, ...serverInfoMeta(info2) }
+  };
+  return { jsonrpc: "2.0", id, result: withMeta };
+}
+function errorResponse(id, code, message, data) {
+  const error = { code, message };
+  if (data !== void 0) error.data = data;
+  return { jsonrpc: "2.0", id, error };
+}
+
+// src/mcp/uris.ts
+var STATIC_RESOURCE_URIS = [
+  "snapshot://manifest",
+  "snapshot://contract",
+  "snapshot://skill",
+  "snapshot://reports/audit",
+  "snapshot://reports/tree",
+  "snapshot://reports/navigation"
+];
+var RESOURCE_TEMPLATE_URIS = ["snapshot://parts/{index}"];
+
+// src/agent/option-scope.ts
+var VALIDATE_OPTIONS = [
+  "cwd",
+  "out-dir",
+  "max-part-bytes",
+  "large-file-bytes",
+  "max-monolith-bytes",
+  "include-monolith",
+  "include-sensitive-files",
+  "skip-artifacts",
+  "only-artifacts",
+  "no-config",
+  "discovery",
+  "format",
+  "mode",
+  "help",
+  "version"
+];
+var COMMAND_OPTION_SCOPE = {
+  generate: [
+    "cwd",
+    "out-dir",
+    "max-part-bytes",
+    "large-file-bytes",
+    "max-monolith-bytes",
+    "include-monolith",
+    "include-sensitive-files",
+    "skip-artifacts",
+    "only-artifacts",
+    "no-config",
+    "discovery",
+    "format",
+    "mode",
+    "dry-run",
+    "watch",
+    "autopilot",
+    "no-install",
+    "help",
+    "version"
+  ],
+  validate: VALIDATE_OPTIONS,
+  report: [
+    "cwd",
+    "out-dir",
+    "max-part-bytes",
+    "large-file-bytes",
+    "max-monolith-bytes",
+    "include-monolith",
+    "include-sensitive-files",
+    "skip-artifacts",
+    "only-artifacts",
+    "no-config",
+    "format",
+    "mode",
+    "help",
+    "version"
+  ],
+  explain: [
+    "cwd",
+    "out-dir",
+    "max-part-bytes",
+    "large-file-bytes",
+    "max-monolith-bytes",
+    "include-monolith",
+    "include-sensitive-files",
+    "skip-artifacts",
+    "only-artifacts",
+    "no-config",
+    "discovery",
+    "format",
+    "mode",
+    "help",
+    "version"
+  ],
+  diff: ["format", "mode", "no-config", "help", "version"],
+  describe: ["format", "mode", "help", "version"],
+  init: [
+    "cwd",
+    "out-dir",
+    "max-part-bytes",
+    "include-sensitive-files",
+    "skip-artifacts",
+    "only-artifacts",
+    "preset",
+    "include",
+    "exclude",
+    "yes",
+    "force",
+    "dry-run",
+    "format",
+    "mode",
+    "help",
+    "version"
+  ],
+  skill: ["cwd", "format", "mode", "install", "target", "help", "version"],
+  // `mcp` reads the repository, so it takes --cwd. It has no --format: stdout carries JSON-RPC
+  // messages, and there is no second shape to choose, so offering the flag would be a lie.
+  mcp: ["cwd", "mode", "help", "version"],
+  setup: [
+    "cwd",
+    "out-dir",
+    "max-part-bytes",
+    "include-sensitive-files",
+    "skip-artifacts",
+    "only-artifacts",
+    "preset",
+    "include",
+    "exclude",
+    "yes",
+    "force",
+    "no-install",
+    "dry-run",
+    "format",
+    "mode",
+    "help",
+    "version"
+  ]
+};
+var COMMAND_ORDER = [
+  "generate",
+  "validate",
+  "report",
+  "explain",
+  "init",
+  "setup",
+  "diff",
+  "describe",
+  "skill",
+  "mcp"
+];
+function commandsForOption(option) {
+  return COMMAND_ORDER.filter((command) => COMMAND_OPTION_SCOPE[command].includes(option));
+}
+function optionAppliesTo(option) {
+  return commandsForOption(option).join("/");
+}
+
+// src/agent/contract.ts
+var CONTRACT_VERSION = "1.0.0";
+var PACKAGE_NAME = "codebase-snapshot";
+var MAJOR_VERSION = GENERATOR_VERSION.split(".")[0];
+var ARTIFACT_SUMMARY = {
+  readme: "README.md describing the snapshot at the output root.",
   manifest: "manifest.json: machine-readable index of every file, part, hash and config.",
   parts: "parts/*.md: the packed, budget-limited markdown parts that carry the code.",
   navigation: "reports/navigation.md: links between parts and layers.",
@@ -8108,6 +9333,19 @@ function renderContractText(contract) {
     lines.push(`  ${"".padEnd(24)} ${option.summary}`);
   }
   lines.push("");
+  lines.push("MCP:");
+  lines.push(`  command    ${contract.mcp.command}`);
+  lines.push(`  transport  ${contract.mcp.transport}`);
+  lines.push(
+    `  versions   modern ${contract.mcp.protocolVersions.modern.join(", ")} / legacy ${contract.mcp.protocolVersions.legacy.join(", ")}`
+  );
+  lines.push(
+    `  tools      ${contract.mcp.tools.map((tool) => tool.readOnly ? tool.name : `${tool.name} (writes)`).join(", ")}`
+  );
+  lines.push(`  prompts    ${contract.mcp.prompts.map((prompt) => prompt.name).join(", ")}`);
+  lines.push(`  resources  ${contract.mcp.resources.join(", ")}`);
+  lines.push(`  templates  ${contract.mcp.resourceTemplates.join(", ")}`);
+  lines.push("");
   lines.push("Safety:");
   for (const note of contract.safety) lines.push(`  - ${note}`);
   lines.push("");
@@ -8133,11 +9371,13 @@ function buildAgentContract() {
     invocation: {
       oneShot: `npx ${PACKAGE_NAME}@latest`,
       installed: "npx codebase-snapshot",
-      bins: ["codebase-snapshot", "snap"],
+      bins: ["codebase-snapshot", "snapshot"],
       notes: [
         `The bare package name also works: npx ${PACKAGE_NAME} <command>.`,
-        "Pin an exact version \u2014 for example `codebase-snapshot@0.9.0` \u2014 when you need the same build on every machine. A major range is not enough before 1.0: npm's caret on a 0.x version pins the minor, and 0.x minors are breaking by convention.",
+        "`codebase-snapshot` is the canonical name and the one to script against. `snapshot` is the short alias a global install provides; in a project that has the package installed, `npx snapshot` resolves the local bin first.",
+        `Pin an exact version \u2014 for example \`npx ${PACKAGE_NAME}@${GENERATOR_VERSION} --version\` \u2014 when you need the same build on every machine. A major range is not enough before 1.0: npm's caret on a 0.x version pins the minor, and 0.x minors are breaking by convention.`,
         "Both bin names point at the same file. npm resolves a package by its bin entries, so they must stay aliases of one executable.",
+        "A bare run in a project with no configuration asks once, sets the project up and generates \u2014 but only at a terminal. With no TTY it exits 2 and names the alternatives, so an unattended caller must say what it wants: `generate` after `init --yes`, or `--autopilot`.",
         "Human progress goes to stderr. With --format json the payload on stdout is pure JSON.",
         "A failing run also writes pure JSON to stdout: { error: { message, exitCode } }. The exit code and the stderr line are unchanged."
       ]
@@ -8192,9 +9432,9 @@ function buildAgentContract() {
       {
         name: "generate",
         aliases: ["default"],
-        summary: "Write the snapshot. This is the command you normally want.",
+        summary: "Write the snapshot. This is the command you normally want. In a project with no configuration, a terminal asks once and sets the project up first; without a terminal it exits 2 and names `--autopilot` and `init --yes`.",
         positionals: [],
-        exits: [0, 1]
+        exits: [0, 1, 2]
       },
       {
         name: "validate",
@@ -8251,6 +9491,13 @@ function buildAgentContract() {
         summary: "Print the agent skill, or --install it into the tool registries this repository's agent reads (.claude/skills, .cursor/rules). Files it creates are added to .gitignore. It never writes AGENTS.md: that file belongs to the repository.",
         positionals: [],
         exits: [0, 1, 2]
+      },
+      {
+        name: "mcp",
+        aliases: [],
+        summary: "Serve this repository to an MCP client over stdio. The tools, resources and protocol versions it offers are listed in this contract's `mcp` block.",
+        positionals: [],
+        exits: [0, 2]
       }
     ],
     exitCodes: {
@@ -8401,6 +9648,13 @@ function buildAgentContract() {
         appliesTo: optionAppliesTo("force"),
         summary: "Overwrite an existing config file."
       },
+      {
+        flag: "--autopilot",
+        type: "boolean",
+        default: false,
+        appliesTo: optionAppliesTo("autopilot"),
+        summary: "Set the project up without asking, then generate: detect the preset, write the config and .gitignore, add the npm scripts and devDependency, install with the project's own package manager, generate. Never overwrites an existing config, and never prompts. Refuses an empty directory (exit 1); contradicts --no-config (exit 2)."
+      },
       {
         flag: "--install",
         type: "boolean",
@@ -8420,7 +9674,7 @@ function buildAgentContract() {
         type: "boolean",
         default: false,
         appliesTo: optionAppliesTo("no-install"),
-        summary: "setup only: skip installing the dependency before generating (CI, offline, or a lockfile you do not want a package manager to touch)."
+        summary: "Skip installing the dependency before generating: `setup`, or `generate --autopilot` (CI, offline, or a lockfile you do not want a package manager to touch)."
       }
     ],
     presets: PRESETS.map((preset) => ({
@@ -8492,6 +9746,36 @@ function buildAgentContract() {
       "The tool refuses to replace an outDir that it did not create, so a mistyped outDir cannot delete source code.",
       "Nothing is ever written above the repository root; --out-dir may not be the root or an ancestor."
     ],
+    mcp: {
+      command: `npx ${PACKAGE_NAME} mcp`,
+      transport: "stdio",
+      protocolVersions: {
+        modern: [...MODERN_PROTOCOL_VERSIONS],
+        legacy: [...LEGACY_PROTOCOL_VERSIONS],
+        default: DEFAULT_LEGACY_PROTOCOL_VERSION
+      },
+      tools: buildTools().map((tool) => ({
+        name: tool.name,
+        title: tool.title,
+        summary: tool.description,
+        readOnly: tool.annotations.readOnlyHint,
+        parameters: Object.keys(tool.inputSchema.properties),
+        required: tool.inputSchema.required ?? []
+      })),
+      prompts: buildPrompts().map((prompt) => ({
+        name: prompt.name,
+        summary: prompt.description,
+        arguments: prompt.arguments.map((argument) => argument.name)
+      })),
+      resources: [...STATIC_RESOURCE_URIS],
+      resourceTemplates: [...RESOURCE_TEMPLATE_URIS],
+      notes: [
+        "stdout carries JSON-RPC messages only; every note and log line goes to stderr.",
+        "The server speaks both protocol eras: the legacy `initialize` handshake and the stateless revision, which is detected from `server/discover` or from per-request `_meta`.",
+        "Everything it can do is a subset of the CLI. It never installs packages and never writes a config file.",
+        "A `root` argument may name a sub-directory of the server's --cwd, and nothing outside it is readable."
+      ]
+    },
     troubleshooting: [
       {
         symptom: "Command prints nothing and exits 0",
@@ -8523,8 +9807,8 @@ function buildAgentContract() {
 }
 
 // src/agent/install-skill.ts
-import * as fs11 from "fs";
-import * as path12 from "path";
+import * as fs14 from "fs";
+import * as path15 from "path";
 
 // src/agent/skill.ts
 var PACKAGE_NAME2 = "codebase-snapshot";
@@ -8553,10 +9837,11 @@ globally, and you do not need to clone anything.
 
 **Pin a version** \u2014 \`npx ${PACKAGE_NAME2}@${GENERATOR_VERSION} <command>\` \u2014 when you
 need the same version on every machine. The bare package name works too: this package ships
-one executable file, published under two names (\`codebase-snapshot\` and \`snap\`), which is what
-lets npm pick it. If a command exits 0 printing nothing,
-the executable was not resolved \u2014 clear the npm cache and retry; do not assume the repository
-is broken.
+one executable file, published under two names (\`codebase-snapshot\` and \`snapshot\`), which is
+what lets npm pick it. A global install gives the short command \`snapshot\`; inside a project
+that has this package installed, \`npx snapshot\` resolves the local copy first. If a command
+exits 0 printing nothing, the executable was not resolved \u2014 clear the npm cache and retry;
+do not assume the repository is broken.
 
 ## Step by step
 
@@ -8581,8 +9866,11 @@ is broken.
    does steps 4\u20136 in one go with defaults: it writes the config (an existing one is kept),
    adds the npm scripts and the devDependency, installs with the project's package manager,
    and generates. Use \`--no-install\` when the machine is offline or the user does not want
-   their lockfile touched. Prefer the explicit steps below when you need to control any of
-   those, or when something fails and you want to see which part.
+   their lockfile touched. \`--autopilot\` does exactly the same thing from the default
+   command (\`npx ${PACKAGE_NAME2}@latest --autopilot\`) and is the form to reach for when a
+   single invocation must both set the project up and produce the snapshot. Prefer the
+   explicit steps below when you need to control any of those, or when something fails and
+   you want to see which part.
 
 4. **Configure (recommended).** Run \`npx ${PACKAGE_NAME2}@latest init --yes\`. It detects
    the project shape, then writes a commented config file listing **every** setting at its
@@ -8590,7 +9878,10 @@ is broken.
    the running Node can strip types (Node >= 22.6) **and** the project is an ES module
    (\`"type": "module"\` in package.json); otherwise \`snapshot.config.mjs\`. Pass
    \`--preset <name>\` only if detection is wrong; the preset names are in the contract.
-   This step is optional: without a config the tool runs on the same defaults.
+   Skipping this step is safe **at a terminal**: the first \`generate\` asks once, can write
+   the config for you and then generates. Unattended, a \`generate\` with no config exits 2 \u2014
+   run this step, or \`--autopilot\`, or pass \`--no-config\` to run deliberately on the
+   built-in defaults.
 
 5. **Generate.** Run \`npx ${PACKAGE_NAME2}@latest generate\`. Expect exit 0 and a
    \`./snapshot/\` directory. If you need a different location use \`--out-dir <path>\`; if
@@ -8638,6 +9929,10 @@ any of this to get a good first snapshot.
   deleting anything.
 - **Exit 2 is a usage error**, not a failure of the repository. Re-read the contract
   before retrying.
+- **A first run refuses rather than guessing.** In a project with no config and no previous
+  snapshot, \`generate\` without a terminal exits 2 instead of silently using defaults. That
+  is deliberate: say which set-up you want (\`--autopilot\`, \`init --yes\`, or \`--no-config\`)
+  rather than retrying the same command.
 - **\`--format json\` keeps stdout pure.** Progress goes to stderr, so \`stdout\` is safe to
   pipe into a JSON parser.
 
@@ -8653,6 +9948,14 @@ It never writes \`AGENTS.md\`. That file is the repository's own agent contract
 commands, conventions, house rules \u2014 and this tool has no business editing it. If you want
 this skill in there, run \`npx ${PACKAGE_NAME2}@latest skill\` and paste the text yourself: the
 diff, and the commit, are then yours.
+
+## When the client speaks MCP
+
+If the agent runs inside an MCP client, \`npx ${PACKAGE_NAME2}@latest mcp\` serves this repository
+as seven tools over stdio instead of shelling out. Its reads come from the snapshot rather than
+the working tree, so excluded files and redacted values never reach the context. Use
+\`snapshot_locate\` before \`snapshot_read\`, and \`snapshot_validate\` before trusting a snapshot
+from an earlier session.
 `;
 }
 
@@ -8663,17 +9966,17 @@ var LEGACY_AGENTS_MARKER = "<!-- codebase-snapshot:skill:start -->";
 function targetPath(cwd, target) {
   switch (target) {
     case "claude":
-      return path12.join(cwd, ".claude", "skills", SKILL_NAME, "SKILL.md");
+      return path15.join(cwd, ".claude", "skills", SKILL_NAME, "SKILL.md");
     case "cursor":
-      return path12.join(cwd, ".cursor", "rules", `${SKILL_NAME}.mdc`);
+      return path15.join(cwd, ".cursor", "rules", `${SKILL_NAME}.mdc`);
   }
 }
 function assertWritableInsideRepository(cwd, filePath) {
-  const root = fs11.realpathSync(cwd);
-  const shown = path12.relative(root, filePath) || filePath;
+  const root = fs14.realpathSync(cwd);
+  const shown = path15.relative(root, filePath) || filePath;
   let stat = null;
   try {
-    stat = fs11.lstatSync(filePath);
+    stat = fs14.lstatSync(filePath);
   } catch {
     stat = null;
   }
@@ -8689,32 +9992,32 @@ function assertWritableInsideRepository(cwd, filePath) {
   }
   let existing = filePath;
   const missing = [];
-  while (!fs11.existsSync(existing)) {
-    missing.unshift(path12.basename(existing));
-    const parent = path12.dirname(existing);
+  while (!fs14.existsSync(existing)) {
+    missing.unshift(path15.basename(existing));
+    const parent = path15.dirname(existing);
     if (parent === existing) break;
     existing = parent;
   }
-  const realAncestor = fs11.realpathSync(existing);
-  const resolved = missing.length === 0 ? realAncestor : path12.join(realAncestor, ...missing);
-  if (resolved !== root && !resolved.startsWith(`${root}${path12.sep}`)) {
+  const realAncestor = fs14.realpathSync(existing);
+  const resolved = missing.length === 0 ? realAncestor : path15.join(realAncestor, ...missing);
+  if (resolved !== root && !resolved.startsWith(`${root}${path15.sep}`)) {
     throw new Error(
       `${REFUSED}: ${shown} resolves outside the repository (${resolved}). Move it back inside ${root}, or remove the link, and run again.`
     );
   }
 }
 function writeIfChanged(target, filePath, content) {
-  const existing = fs11.existsSync(filePath) ? fs11.readFileSync(filePath, "utf8") : null;
+  const existing = fs14.existsSync(filePath) ? fs14.readFileSync(filePath, "utf8") : null;
   if (existing === content) return { target, path: filePath, action: "unchanged" };
-  fs11.mkdirSync(path12.dirname(filePath), { recursive: true });
-  fs11.writeFileSync(filePath, content, "utf8");
+  fs14.mkdirSync(path15.dirname(filePath), { recursive: true });
+  fs14.writeFileSync(filePath, content, "utf8");
   return { target, path: filePath, action: existing === null ? "created" : "updated" };
 }
 function legacyAgentsNote(cwd) {
-  const filePath = path12.join(cwd, "AGENTS.md");
+  const filePath = path15.join(cwd, "AGENTS.md");
   try {
-    if (!fs11.existsSync(filePath)) return null;
-    if (!fs11.readFileSync(filePath, "utf8").includes(LEGACY_AGENTS_MARKER)) return null;
+    if (!fs14.existsSync(filePath)) return null;
+    if (!fs14.readFileSync(filePath, "utf8").includes(LEGACY_AGENTS_MARKER)) return null;
   } catch {
     return null;
   }
@@ -8726,9 +10029,9 @@ function installSkill(cwd, target = "all") {
   const notes = [];
   const wanted = target === "all" ? ["claude", "cursor"] : [target];
   for (const item of wanted) assertWritableInsideRepository(cwd, targetPath(cwd, item));
-  const createsSomething = wanted.some((item) => !fs11.existsSync(targetPath(cwd, item)));
+  const createsSomething = wanted.some((item) => !fs14.existsSync(targetPath(cwd, item)));
   if (createsSomething) {
-    assertWritableInsideRepository(cwd, path12.join(cwd, ".gitignore"));
+    assertWritableInsideRepository(cwd, path15.join(cwd, ".gitignore"));
   }
   for (const item of wanted) {
     written.push(writeIfChanged(item, targetPath(cwd, item), skill));
@@ -8744,6 +10047,771 @@ function isSkillTarget(value) {
   return SKILL_TARGETS.includes(value);
 }
 
+// src/mcp/era.ts
+function createSession() {
+  return { era: null, protocolVersion: null, ready: false };
+}
+function isLegacyVersion(version) {
+  return LEGACY_PROTOCOL_VERSIONS.includes(version);
+}
+function isModernVersion(version) {
+  return MODERN_PROTOCOL_VERSIONS.includes(version);
+}
+function inspectModernMeta(params) {
+  const raw = params?._meta;
+  if (!isJsonObject(raw)) return { kind: "absent" };
+  const version = raw[META_KEYS.protocolVersion];
+  if (typeof version !== "string" || version.length === 0) {
+    return { kind: "incomplete", missing: META_KEYS.protocolVersion };
+  }
+  const capabilities2 = raw[META_KEYS.clientCapabilities];
+  if (!isJsonObject(capabilities2)) {
+    return { kind: "incomplete", missing: META_KEYS.clientCapabilities };
+  }
+  const info2 = raw[META_KEYS.clientInfo];
+  return {
+    kind: "present",
+    meta: {
+      version,
+      clientCapabilities: capabilities2,
+      clientInfo: isJsonObject(info2) ? info2 : null
+    }
+  };
+}
+function unsupportedVersionData(requested) {
+  return { requested, supported: [...SUPPORTED_PROTOCOL_VERSIONS] };
+}
+function classifyRequest(method, params, session) {
+  const inspection = inspectModernMeta(params);
+  if (session.era === "modern") {
+    if (inspection.kind === "absent") {
+      return {
+        kind: "error",
+        code: ERROR_CODES.invalidRequest,
+        message: `This request has no _meta. The modern era requires "${META_KEYS.protocolVersion}" and "${META_KEYS.clientCapabilities}" on every request.`
+      };
+    }
+    if (inspection.kind === "incomplete") {
+      return {
+        kind: "error",
+        code: ERROR_CODES.invalidParams,
+        message: `The request _meta is missing the required key "${inspection.missing}".`
+      };
+    }
+    if (!isModernVersion(inspection.meta.version)) {
+      return {
+        kind: "error",
+        code: ERROR_CODES.unsupportedProtocolVersion,
+        message: `Unsupported protocol version "${inspection.meta.version}".`,
+        data: unsupportedVersionData(inspection.meta.version)
+      };
+    }
+    return { kind: "era", era: "modern", version: inspection.meta.version };
+  }
+  if (session.era === "legacy") {
+    return { kind: "era", era: "legacy", version: session.protocolVersion };
+  }
+  if (method === METHOD3.initialize) {
+    return { kind: "era", era: "legacy", version: null };
+  }
+  if (inspection.kind === "present") {
+    if (!isModernVersion(inspection.meta.version)) {
+      return {
+        kind: "error",
+        code: ERROR_CODES.unsupportedProtocolVersion,
+        message: `Unsupported protocol version "${inspection.meta.version}".`,
+        data: unsupportedVersionData(inspection.meta.version)
+      };
+    }
+    return { kind: "era", era: "modern", version: inspection.meta.version };
+  }
+  if (inspection.kind === "incomplete") {
+    return {
+      kind: "error",
+      code: ERROR_CODES.invalidParams,
+      message: `The request _meta is missing the required key "${inspection.missing}".`
+    };
+  }
+  if (method === METHOD3.discover) {
+    return { kind: "era", era: "modern", version: MODERN_PROTOCOL_VERSIONS[0] };
+  }
+  return { kind: "era", era: "legacy", version: null };
+}
+function negotiateLegacyVersion(requested) {
+  if (typeof requested === "string" && isLegacyVersion(requested)) {
+    return { version: requested, matched: true };
+  }
+  return { version: DEFAULT_LEGACY_PROTOCOL_VERSION, matched: false };
+}
+
+// src/mcp/schema.ts
+function validateArguments(schema, value) {
+  if (value === void 0) value = {};
+  if (!isJsonObject(value)) return ["arguments must be a JSON object"];
+  const problems = [];
+  const known = new Set(Object.keys(schema.properties));
+  for (const key of Object.keys(value)) {
+    if (!known.has(key) && schema.additionalProperties !== true) {
+      const allowed = [...known].sort().join(", ");
+      problems.push(`unknown argument "${key}" (accepted: ${allowed || "none"})`);
+    }
+  }
+  for (const required of schema.required ?? []) {
+    if (value[required] === void 0) problems.push(`missing required argument "${required}"`);
+  }
+  for (const [key, propertySchema] of Object.entries(schema.properties)) {
+    const argument = value[key];
+    if (argument === void 0) continue;
+    problems.push(...checkValue(key, propertySchema, argument));
+  }
+  return problems;
+}
+function checkValue(path18, schema, value) {
+  if (schema.enum && !schema.enum.includes(value)) {
+    return [`"${path18}" must be one of: ${schema.enum.join(", ")}`];
+  }
+  switch (schema.type) {
+    case "string": {
+      if (typeof value !== "string") return [`"${path18}" must be a string`];
+      const problems = [];
+      if (schema.minLength !== void 0 && value.length < schema.minLength) {
+        problems.push(`"${path18}" must be at least ${schema.minLength} character(s)`);
+      }
+      if (schema.maxLength !== void 0 && value.length > schema.maxLength) {
+        problems.push(`"${path18}" must be at most ${schema.maxLength} character(s)`);
+      }
+      return problems;
+    }
+    case "number":
+    case "integer": {
+      if (typeof value !== "number" || Number.isNaN(value)) {
+        return [`"${path18}" must be a number`];
+      }
+      if (schema.type === "integer" && !Number.isInteger(value)) {
+        return [`"${path18}" must be an integer`];
+      }
+      const problems = [];
+      if (schema.minimum !== void 0 && value < schema.minimum) {
+        problems.push(`"${path18}" must be >= ${schema.minimum}`);
+      }
+      if (schema.maximum !== void 0 && value > schema.maximum) {
+        problems.push(`"${path18}" must be <= ${schema.maximum}`);
+      }
+      return problems;
+    }
+    case "boolean":
+      return typeof value === "boolean" ? [] : [`"${path18}" must be a boolean`];
+    case "array": {
+      if (!Array.isArray(value)) return [`"${path18}" must be an array`];
+      if (!schema.items) return [];
+      const problems = [];
+      value.forEach((item, index) => {
+        problems.push(...checkValue(`${path18}[${index}]`, schema.items, item));
+      });
+      return problems;
+    }
+    case "object":
+      return isJsonObject(value) ? [] : [`"${path18}" must be an object`];
+    default:
+      return [];
+  }
+}
+function applyDefaults(schema, value) {
+  const out = { ...value };
+  for (const [key, propertySchema] of Object.entries(schema.properties)) {
+    if (out[key] === void 0 && propertySchema.default !== void 0) {
+      out[key] = propertySchema.default;
+    }
+  }
+  return out;
+}
+
+// src/mcp/server.ts
+function capabilities() {
+  return {
+    tools: { listChanged: false },
+    resources: { subscribe: false, listChanged: false },
+    prompts: { listChanged: false }
+  };
+}
+function requestIdOf(message) {
+  const raw = message.id;
+  return typeof raw === "string" || typeof raw === "number" ? raw : null;
+}
+function createMcpServer(options) {
+  const session = createSession();
+  const toolsByName = new Map(options.tools.map((tool) => [tool.name, tool]));
+  const promptsByName = new Map(options.prompts.map((prompt) => [prompt.name, prompt]));
+  const identity = () => ({
+    name: options.info.name,
+    title: options.info.title,
+    version: options.info.version,
+    websiteUrl: options.info.websiteUrl
+  });
+  const ok = (id, result, modern) => successResponse(id, result, modern, options.info);
+  function handleNotification(method) {
+    if (method === METHOD3.initialized && session.era === "legacy") session.ready = true;
+  }
+  function initialize(id, params) {
+    const negotiation = negotiateLegacyVersion(params?.protocolVersion);
+    session.era = "legacy";
+    session.protocolVersion = negotiation.version;
+    session.ready = true;
+    options.context.log(
+      negotiation.matched ? `mcp: client initialized with protocol ${negotiation.version}` : `mcp: client asked for an unsupported version and was offered ${negotiation.version}`
+    );
+    return {
+      jsonrpc: "2.0",
+      id,
+      result: {
+        protocolVersion: negotiation.version,
+        capabilities: capabilities(),
+        serverInfo: identity(),
+        instructions: options.instructions
+      }
+    };
+  }
+  function discover(id) {
+    session.era = "modern";
+    session.ready = true;
+    return ok(
+      id,
+      {
+        supportedVersions: [...SUPPORTED_PROTOCOL_VERSIONS],
+        capabilities: capabilities(),
+        instructions: options.instructions,
+        // The capability set depends on which repository the server was started for, so the answer
+        // may be cached only by the client that asked, and not at all after this response.
+        cacheScope: "private",
+        ttlMs: 0
+      },
+      true
+    );
+  }
+  function listTools(id, modern) {
+    const tools = options.tools.map((tool) => ({
+      name: tool.name,
+      title: tool.title,
+      description: tool.description,
+      inputSchema: tool.inputSchema,
+      ...tool.outputSchema ? { outputSchema: tool.outputSchema } : {},
+      annotations: tool.annotations
+    }));
+    return ok(id, { tools }, modern);
+  }
+  async function callTool(id, modern, params) {
+    const name = params?.name;
+    if (typeof name !== "string") {
+      return errorResponse(id, ERROR_CODES.invalidParams, 'tools/call requires a "name" string.');
+    }
+    const tool = toolsByName.get(name);
+    if (!tool) {
+      const known = [...toolsByName.keys()].sort().join(", ");
+      return errorResponse(id, ERROR_CODES.invalidParams, `Unknown tool "${name}". Available: ${known}.`);
+    }
+    const rawArguments = params?.arguments ?? {};
+    if (!isJsonObject(rawArguments)) {
+      return errorResponse(id, ERROR_CODES.invalidParams, '"arguments" must be a JSON object.');
+    }
+    const problems = validateArguments(tool.inputSchema, rawArguments);
+    if (problems.length > 0) {
+      return ok(
+        id,
+        {
+          content: [{ type: "text", text: `Invalid arguments for ${tool.name}:
+- ${problems.join("\n- ")}` }],
+          isError: true
+        },
+        modern
+      );
+    }
+    const args = applyDefaults(tool.inputSchema, rawArguments);
+    let outcome;
+    try {
+      outcome = await tool.handler(args, options.context);
+    } catch (error) {
+      const detail = error instanceof Error ? error.message : String(error);
+      options.context.log(`mcp: tool ${tool.name} failed: ${detail}`);
+      return ok(
+        id,
+        { content: [{ type: "text", text: `${tool.name} failed: ${detail}` }], isError: true },
+        modern
+      );
+    }
+    return ok(
+      id,
+      {
+        content: [{ type: "text", text: outcome.text }],
+        ...outcome.structured ? { structuredContent: outcome.structured } : {},
+        ...outcome.isError ? { isError: true } : {}
+      },
+      modern
+    );
+  }
+  async function listResources(id, modern) {
+    const resources = await options.resources.list(options.context);
+    return ok(id, { resources }, modern);
+  }
+  async function readResource(id, modern, params) {
+    const uri = params?.uri;
+    if (typeof uri !== "string") {
+      return errorResponse(id, ERROR_CODES.invalidParams, 'resources/read requires a "uri" string.');
+    }
+    const contents = await options.resources.read(uri, options.context);
+    if (!contents) {
+      return errorResponse(id, ERROR_CODES.invalidParams, `Unknown resource "${uri}".`);
+    }
+    return ok(id, { contents: [contents] }, modern);
+  }
+  function listPrompts(id, modern) {
+    const prompts = options.prompts.map((prompt) => ({
+      name: prompt.name,
+      ...prompt.title ? { title: prompt.title } : {},
+      description: prompt.description,
+      arguments: prompt.arguments
+    }));
+    return ok(id, { prompts }, modern);
+  }
+  function getPrompt(id, modern, params) {
+    const name = params?.name;
+    if (typeof name !== "string") {
+      return errorResponse(id, ERROR_CODES.invalidParams, 'prompts/get requires a "name" string.');
+    }
+    const prompt = promptsByName.get(name);
+    if (!prompt) {
+      const known = [...promptsByName.keys()].sort().join(", ");
+      return errorResponse(id, ERROR_CODES.invalidParams, `Unknown prompt "${name}". Available: ${known}.`);
+    }
+    const rawArguments = params?.arguments ?? {};
+    if (!isJsonObject(rawArguments)) {
+      return errorResponse(id, ERROR_CODES.invalidParams, '"arguments" must be a JSON object.');
+    }
+    const built = prompt.build(rawArguments);
+    const messages = built.messages.map((message) => ({
+      role: message.role,
+      content: { type: "text", text: message.content.text }
+    }));
+    return ok(id, { description: built.description, messages }, modern);
+  }
+  async function route(name, id, modern, params) {
+    switch (name) {
+      case METHOD3.initialize:
+        return modern ? errorResponse(
+          id,
+          ERROR_CODES.methodNotFound,
+          '"initialize" does not exist in this protocol revision; call "server/discover".'
+        ) : initialize(id, params);
+      case METHOD3.discover:
+        return discover(id);
+      case METHOD3.ping:
+        return modern ? errorResponse(
+          id,
+          ERROR_CODES.methodNotFound,
+          '"ping" was removed in this protocol revision; call "server/discover".'
+        ) : ok(id, {}, modern);
+      default:
+        break;
+    }
+    if (!session.ready) {
+      return errorResponse(
+        id,
+        ERROR_CODES.invalidRequest,
+        'This connection has not been initialized. Send "initialize" first.'
+      );
+    }
+    switch (name) {
+      case METHOD3.toolsList:
+        return listTools(id, modern);
+      case METHOD3.toolsCall:
+        return callTool(id, modern, params);
+      case METHOD3.resourcesList:
+        return listResources(id, modern);
+      case METHOD3.resourcesRead:
+        return readResource(id, modern, params);
+      case METHOD3.resourceTemplatesList:
+        return ok(id, { resourceTemplates: options.resources.templates() }, modern);
+      case METHOD3.promptsList:
+        return listPrompts(id, modern);
+      case METHOD3.promptsGet:
+        return getPrompt(id, modern, params);
+      default:
+        return errorResponse(id, ERROR_CODES.methodNotFound, `Unknown method "${name}".`);
+    }
+  }
+  async function dispatch(message) {
+    if (!isJsonObject(message)) {
+      return errorResponse(null, ERROR_CODES.parseError, "Message is not a JSON object.");
+    }
+    const isRequest = Object.prototype.hasOwnProperty.call(message, "id");
+    const method = message.method;
+    const params = message.params;
+    if (message.jsonrpc !== "2.0" && isRequest) {
+      return errorResponse(requestIdOf(message), ERROR_CODES.invalidRequest, 'Message must carry "jsonrpc": "2.0".');
+    }
+    if (typeof method !== "string" || method.length === 0) {
+      return isRequest ? errorResponse(requestIdOf(message), ERROR_CODES.invalidRequest, 'Message must carry a "method" string.') : null;
+    }
+    if (params !== void 0 && !isJsonObject(params)) {
+      return isRequest ? errorResponse(requestIdOf(message), ERROR_CODES.invalidRequest, '"params" must be a JSON object when present.') : null;
+    }
+    const named = params;
+    const decision = classifyRequest(method, named, session);
+    const modern = decision.kind === "era" ? decision.era === "modern" : session.era === "modern";
+    if (!isRequest) {
+      if (decision.kind === "era" && session.era === null) {
+        session.era = decision.era;
+        session.protocolVersion = decision.version;
+      }
+      handleNotification(method);
+      return null;
+    }
+    const id = requestIdOf(message);
+    if (id === null) {
+      return errorResponse(null, ERROR_CODES.invalidRequest, 'A request "id" must be a string or a number.');
+    }
+    if (decision.kind === "error") {
+      return errorResponse(id, decision.code, decision.message, decision.data);
+    }
+    if (session.era === null) {
+      session.era = decision.era;
+      session.protocolVersion = decision.version;
+    }
+    return route(method, id, modern, named);
+  }
+  return {
+    session,
+    async handle(message) {
+      try {
+        return await dispatch(message);
+      } catch (error) {
+        const detail = error instanceof Error ? error.message : String(error);
+        options.context.log(`mcp: internal error: ${detail}`);
+        const id = isJsonObject(message) ? requestIdOf(message) : null;
+        return errorResponse(id, ERROR_CODES.internalError, "Internal server error.");
+      }
+    }
+  };
+}
+
+// src/mcp/resources.ts
+import * as fs15 from "fs";
+import * as path16 from "path";
+var MAX_RESOURCE_BYTES = 512 * 1024;
+var PART_URI = /^snapshot:\/\/parts\/(\d+)$/;
+var REPORT_URIS = /* @__PURE__ */ new Map([
+  ["snapshot://reports/audit", { file: "audit.md", title: "Secret audit and risk findings" }],
+  ["snapshot://reports/tree", { file: "project-tree.md", title: "Project tree" }],
+  ["snapshot://reports/navigation", { file: "navigation.md", title: "Navigation index" }]
+]);
+function formatBytes2(bytes) {
+  if (bytes < 1024) return `${bytes} B`;
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} kB`;
+  return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+}
+function truncationMarker(originalBytes) {
+  return `
+
+[truncated: ${formatBytes2(originalBytes)} total. Use the snapshot_read tool for a line window.]
+`;
+}
+function capUtf8(text2, limit) {
+  const size2 = Buffer.byteLength(text2, "utf8");
+  if (size2 <= limit) return { text: text2, truncated: false };
+  const cut = Buffer.from(text2, "utf8").subarray(0, limit).toString("utf8").replace(/\uFFFD+$/, "");
+  return { text: `${cut}${truncationMarker(size2)}`, truncated: true };
+}
+async function workspaceFor(context) {
+  const root = resolveRoot(void 0, context);
+  if (!root.ok) return { error: root.message };
+  const opened = await openWorkspace(root.root);
+  if (!opened.ok) return { error: opened.message };
+  return opened.workspace;
+}
+function readFileIfPresent(file) {
+  try {
+    return fs15.readFileSync(file, "utf8");
+  } catch {
+    return null;
+  }
+}
+function buildResourceProvider() {
+  return {
+    async list(context) {
+      const resources = [
+        {
+          uri: "snapshot://manifest",
+          name: "manifest",
+          title: "Snapshot manifest",
+          description: "Every file in the snapshot with its layer, kind, language, part and hash, plus the reason each excluded file was excluded.",
+          mimeType: "application/json"
+        },
+        {
+          uri: "snapshot://contract",
+          name: "contract",
+          title: "Tool contract",
+          description: "The machine-readable description of the codebase-snapshot command line.",
+          mimeType: "application/json"
+        },
+        {
+          uri: "snapshot://skill",
+          name: "skill",
+          title: "Agent skill",
+          description: "Usage guidance for an agent working with this tool.",
+          mimeType: "text/markdown"
+        }
+      ];
+      for (const [uri, report] of REPORT_URIS) {
+        resources.push({
+          uri,
+          name: report.file.replace(/\.md$/, ""),
+          title: report.title,
+          description: `${report.title} from the most recent snapshot.`,
+          mimeType: "text/markdown"
+        });
+      }
+      const workspace = await workspaceFor(context);
+      if ("error" in workspace) return resources;
+      const read = readManifest3(workspace);
+      if (!read.ok) return resources;
+      for (const part of read.manifest.parts) {
+        resources.push({
+          uri: `snapshot://parts/${part.index}`,
+          name: `part-${String(part.index).padStart(3, "0")}`,
+          title: `Part ${part.index} (${part.fileCount} files, ${formatBytes2(part.byteSize)})`,
+          description: `Part ${part.index} of ${read.manifest.parts.length}: ${part.fileCount} file(s), ${part.lines} line(s), ${formatBytes2(part.byteSize)}.`,
+          mimeType: "text/markdown"
+        });
+      }
+      return resources;
+    },
+    templates() {
+      return [
+        {
+          uriTemplate: "snapshot://parts/{index}",
+          name: "part",
+          title: "Snapshot part",
+          description: "One budgeted part of the snapshot, by its 1-based index.",
+          mimeType: "text/markdown"
+        }
+      ];
+    },
+    async read(uri, context) {
+      if (uri === "snapshot://contract") {
+        const contract = buildAgentContract();
+        return { uri, mimeType: "application/json", text: JSON.stringify(contract, null, 2) };
+      }
+      if (uri === "snapshot://skill") {
+        return { uri, mimeType: "text/markdown", text: renderSkill() };
+      }
+      const workspace = await workspaceFor(context);
+      if ("error" in workspace) return null;
+      const report = REPORT_URIS.get(uri);
+      if (report) {
+        const text2 = readFileIfPresent(
+          path16.resolve(workspace.root, workspace.config.outDir, "reports", report.file)
+        );
+        if (text2 === null) return null;
+        return { uri, mimeType: "text/markdown", text: capUtf8(text2, MAX_RESOURCE_BYTES).text };
+      }
+      if (uri === "snapshot://manifest") {
+        const read = readManifest3(workspace);
+        if (!read.ok) return null;
+        const text2 = readFileIfPresent(read.file) ?? JSON.stringify(read.manifest, null, 2);
+        return { uri, mimeType: "application/json", text: capUtf8(text2, MAX_RESOURCE_BYTES).text };
+      }
+      const partMatch = PART_URI.exec(uri);
+      if (partMatch) {
+        const read = readManifest3(workspace);
+        if (!read.ok) return null;
+        const index = Number(partMatch[1]);
+        const part = read.manifest.parts.find((candidate) => candidate.index === index);
+        if (!part) return null;
+        const text2 = readFileIfPresent(
+          path16.resolve(workspace.root, workspace.config.outDir, "parts", part.filename)
+        );
+        if (text2 === null) return null;
+        return { uri, mimeType: "text/markdown", text: capUtf8(text2, MAX_RESOURCE_BYTES).text };
+      }
+      return null;
+    }
+  };
+}
+
+// src/mcp/instructions.ts
+var SERVER_INSTRUCTIONS = [
+  "codebase-snapshot serves this repository as a size-budgeted snapshot, not as a directory walk.",
+  "",
+  "Work in this order:",
+  "1. snapshot_status \u2014 is there a snapshot here, and has the tree moved since it was built?",
+  "2. snapshot_locate \u2014 find which part holds the code you need.",
+  "3. snapshot_read \u2014 read a window of one file. Never read a part end to end.",
+  "4. snapshot_validate \u2014 before trusting context that came from an earlier conversation.",
+  "",
+  "Rules that matter:",
+  "- Parts are budgeted, not small: a 12-part snapshot is hundreds of kilobytes. Use snapshot_locate first.",
+  "- A file absent from the snapshot has a recorded reason. Ask snapshot_explain, do not assume.",
+  "- snapshot_generate is the only tool that writes. It never installs packages and never writes config.",
+  "- Paths are relative to the repository root the server was started for, and nothing outside it is readable."
+].join("\n");
+
+// src/mcp/stdio.ts
+var MAX_LINE_BYTES = 32 * 1024 * 1024;
+function createWriter(output) {
+  return {
+    write(value) {
+      return new Promise((resolve9, reject) => {
+        output.write(`${JSON.stringify(value)}
+`, (error) => {
+          if (error) reject(error);
+          else resolve9();
+        });
+      });
+    }
+  };
+}
+function createLineReader(input, options) {
+  let buffer = "";
+  let discarding = false;
+  let discardedBytes = 0;
+  const deliver = (line) => {
+    if (discarding) {
+      discarding = false;
+      discardedBytes = 0;
+      return;
+    }
+    const trimmed = line.endsWith("\r") ? line.slice(0, -1) : line;
+    if (trimmed.trim().length === 0) return;
+    options.onLine(trimmed);
+  };
+  const drain = () => {
+    let index = buffer.indexOf("\n");
+    while (index >= 0) {
+      const line = buffer.slice(0, index);
+      buffer = buffer.slice(index + 1);
+      deliver(line);
+      index = buffer.indexOf("\n");
+    }
+  };
+  const onData = (chunk) => {
+    if (discarding) {
+      const index = chunk.indexOf("\n");
+      if (index < 0) {
+        discardedBytes += chunk.length;
+        return;
+      }
+      buffer = chunk.slice(index + 1);
+      deliver("");
+      drain();
+      return;
+    }
+    buffer += chunk;
+    if (buffer.length > MAX_LINE_BYTES && buffer.indexOf("\n") < 0) {
+      discarding = true;
+      discardedBytes = buffer.length;
+      buffer = "";
+      options.onOverflow?.(discardedBytes);
+      return;
+    }
+    drain();
+  };
+  const onEnd = () => {
+    if (buffer.length > 0) {
+      const rest = buffer;
+      buffer = "";
+      deliver(rest);
+    }
+  };
+  input.setEncoding("utf8");
+  input.on("data", onData);
+  input.on("end", onEnd);
+  return () => {
+    input.off("data", onData);
+    input.off("end", onEnd);
+  };
+}
+
+// src/mcp/run.ts
+var PROJECT_URL = "https://ankurhalder.github.io/codebase-snapshot/";
+function createServer(options) {
+  const cwd = options.cwd;
+  const roots = options.roots && options.roots.length > 0 ? options.roots : [cwd];
+  const context = {
+    cwd,
+    roots,
+    log: options.log ?? ((line) => process.stderr.write(`${line}
+`))
+  };
+  return createMcpServer({
+    info: {
+      name: GENERATOR_NAME,
+      title: "codebase-snapshot",
+      version: GENERATOR_VERSION,
+      websiteUrl: PROJECT_URL
+    },
+    instructions: SERVER_INSTRUCTIONS,
+    tools: buildTools(),
+    resources: buildResourceProvider(),
+    prompts: buildPrompts(),
+    context
+  });
+}
+async function runStdioServer(options) {
+  const log = options.log ?? ((line) => process.stderr.write(`${line}
+`));
+  const server = createServer(options);
+  const writer = createWriter(process.stdout);
+  let writeChain = Promise.resolve();
+  const send = (message) => {
+    writeChain = writeChain.then(() => writer.write(message)).catch((error) => {
+      log(`mcp: could not write a response: ${error instanceof Error ? error.message : String(error)}`);
+    });
+    return writeChain;
+  };
+  let inFlight = 0;
+  let inputEnded = false;
+  let resolveDone = () => void 0;
+  const finished = new Promise((resolve9) => {
+    resolveDone = resolve9;
+  });
+  const finishIfIdle = () => {
+    if (inputEnded && inFlight === 0) resolveDone(0);
+  };
+  const handleLine = async (line) => {
+    let message;
+    try {
+      message = JSON.parse(line);
+    } catch {
+      await send(errorResponse(null, ERROR_CODES.parseError, "Message is not valid JSON."));
+      return;
+    }
+    const response = await server.handle(message);
+    if (response) await send(response);
+  };
+  const stopReading = createLineReader(process.stdin, {
+    onOverflow: (bytes) => log(`mcp: discarded an oversized message (${bytes} bytes)`),
+    onLine: (line) => {
+      inFlight += 1;
+      void handleLine(line).finally(() => {
+        inFlight -= 1;
+        finishIfIdle();
+      });
+    }
+  });
+  const onEnd = () => {
+    inputEnded = true;
+    finishIfIdle();
+  };
+  process.stdin.on("end", onEnd);
+  process.stdin.on("close", onEnd);
+  log(`mcp: serving ${options.cwd} over stdio`);
+  const code = await finished;
+  stopReading();
+  process.stdin.off("end", onEnd);
+  process.stdin.off("close", onEnd);
+  await writeChain;
+  return code;
+}
+
 // src/cli.ts
 var VERSION = GENERATOR_VERSION;
 var INSTALL_TIMEOUT_MS = 5 * 60 * 1e3;
@@ -8757,7 +10825,8 @@ var COMMAND_ALIASES = /* @__PURE__ */ new Map([
   ["explain", "explain"],
   ["diff", "diff"],
   ["describe", "describe"],
-  ["skill", "skill"]
+  ["skill", "skill"],
+  ["mcp", "mcp"]
 ]);
 var COMMAND_ARITY = {
   generate: 0,
@@ -8768,7 +10837,8 @@ var COMMAND_ARITY = {
   explain: 1,
   diff: 2,
   describe: 0,
-  skill: 0
+  skill: 0,
+  mcp: 0
 };
 var CLI_OPTIONS = {
   cwd: { type: "string" },
@@ -8791,6 +10861,7 @@ var CLI_OPTIONS = {
   exclude: { type: "string" },
   yes: { type: "boolean" },
   force: { type: "boolean" },
+  autopilot: { type: "boolean" },
   install: { type: "boolean" },
   "no-install": { type: "boolean" },
   target: { type: "string" },
@@ -8806,6 +10877,14 @@ Production-grade LLM codebase snapshot generator, auditor, and AST partitioner
 Usage:
   codebase-snapshot [command] [options]
 
+First run:
+  codebase-snapshot                No config yet: asks once, sets the project up, generates.
+                                   A configured project just generates. It never falls back
+                                   to defaults it was not given.
+  codebase-snapshot --autopilot    The same without questions: detect the preset, write the
+                                   config, add the npm scripts and devDependency, install,
+                                   then generate.
+
 Commands:
   setup                Everything at once: config, scripts, dependency, install, generate
   generate (default)   Generate a complete partitioned codebase snapshot
@@ -8816,6 +10895,7 @@ Commands:
   diff <a> <b>         Compare two snapshots (directories or manifest.json files)
   describe             Print the machine-readable contract (--format json for agents)
   skill                Print the bundled agent skill; --install writes it into the repo
+  mcp                  Serve this repository to an MCP client over stdio
 
 Options:
   --cwd <path>                  Target repository directory (default: current directory)
@@ -8838,6 +10918,12 @@ Options:
                                 auto: git when usable. git: require git. walk: read
                                 .gitignore directly (escape hatch for a broken .git)
 
+  generate only:
+  --autopilot                   Set the project up without asking, then generate: write the
+                                config and .gitignore, add the npm scripts and devDependency,
+                                and install with the project's own package manager.
+  --no-install                  With --autopilot: skip the dependency install.
+
   init only:
   --preset <name>               Force a project preset instead of detecting one
   --include <globs>             Comma-separated allow-list
@@ -8917,10 +11003,10 @@ function parseCliArgs(argv) {
   }
   if (values.cwd !== void 0) {
     const target = String(values.cwd);
-    if (!fs12.existsSync(target)) {
+    if (!fs16.existsSync(target)) {
       throw new UsageError(`--cwd directory does not exist: ${target}`);
     }
-    if (!fs12.statSync(target).isDirectory()) {
+    if (!fs16.statSync(target).isDirectory()) {
       throw new UsageError(`--cwd is not a directory: ${target}`);
     }
   }
@@ -9040,8 +11126,17 @@ function parseCliArgs(argv) {
       `--target must be one of: ${SKILL_TARGETS.join(", ")} (received "${String(values.target)}").`
     );
   }
+  if (values["no-install"] === true && command === "generate" && values.autopilot !== true) {
+    throw new UsageError("--no-install only applies to `setup`, or to `generate --autopilot`.");
+  }
+  if (values.autopilot === true && values["no-config"] === true) {
+    throw new UsageError(
+      "--autopilot sets a project up and writes a config; --no-config ignores config files. Pass one or the other."
+    );
+  }
   return {
     command,
+    explicitCommand: firstPositional !== void 0 || explicitMode !== void 0,
     args,
     format: rawFormat,
     dryRun: values["dry-run"] === true,
@@ -9053,10 +11148,11 @@ function parseCliArgs(argv) {
     exclude: values.exclude === void 0 ? void 0 : String(values.exclude),
     yes: values.yes === true,
     force: values.force === true,
+    autopilot: values.autopilot === true,
     install: values.install === true,
     noInstall: values["no-install"] === true,
     target: values.target === void 0 ? void 0 : String(values.target),
-    cwd: values.cwd === void 0 ? process.cwd() : path13.resolve(String(values.cwd)),
+    cwd: values.cwd === void 0 ? process.cwd() : path17.resolve(String(values.cwd)),
     outDir: values["out-dir"] === void 0 ? void 0 : String(values["out-dir"]),
     includeMonolith: values["include-monolith"] === true || onlyNamesMonolith === true ? true : void 0,
     includeSensitiveFiles: values["include-sensitive-files"] === true ? true : void 0,
@@ -9113,26 +11209,29 @@ function splitList(value) {
   return value.split(",").map((entry) => entry.trim()).filter(Boolean);
 }
 function displayOutPath(cwd, outDir, ...segments) {
-  const absolute = path13.resolve(cwd, outDir, ...segments);
-  const relative8 = path13.relative(cwd, absolute);
-  if (relative8 && !relative8.startsWith("..") && !path13.isAbsolute(relative8)) return relative8;
+  const absolute = path17.resolve(cwd, outDir, ...segments);
+  const relative11 = path17.relative(cwd, absolute);
+  if (relative11 && !relative11.startsWith("..") && !path17.isAbsolute(relative11)) return relative11;
   return absolute;
 }
 function nextStepHint(cwd, scriptsAddedNow) {
   let hasScript = scriptsAddedNow;
   if (!hasScript) {
     try {
-      const parsed = JSON.parse(fs12.readFileSync(path13.join(cwd, "package.json"), "utf8"));
+      const parsed = JSON.parse(fs16.readFileSync(path17.join(cwd, "package.json"), "utf8"));
       hasScript = typeof parsed.scripts?.snapshot === "string";
     } catch {
       hasScript = false;
     }
   }
   if (!hasScript) return `npx ${GENERATOR_NAME} generate`;
-  const bin = path13.join(cwd, "node_modules", ".bin", "codebase-snapshot");
-  const installed = fs12.existsSync(bin) || fs12.existsSync(`${bin}.cmd`);
+  const bin = path17.join(cwd, "node_modules", ".bin", "codebase-snapshot");
+  const installed = fs16.existsSync(bin) || fs16.existsSync(`${bin}.cmd`);
   return installed ? "npm run snapshot" : "npm install && npm run snapshot";
 }
+function presetSummary(init) {
+  return init.reason === null ? `preset: ${init.preset}` : `preset: ${init.preset}, because ${init.reason}`;
+}
 async function runInitCommand(invocation) {
   try {
     const result = await runInit({
@@ -9157,7 +11256,7 @@ async function runInitCommand(invocation) {
       info(result.configText);
       return 0;
     }
-    info(`\u2705 Created ${path13.basename(result.configPath)} (preset: ${result.preset})`);
+    info(`\u2705 Created ${path17.basename(result.configPath)} (${presetSummary(result)})`);
     if (result.scripts.length > 0) info(`   Added npm scripts: ${result.scripts.join(", ")}`);
     if (result.dependency.added && result.dependency.range !== null) {
       info(`   Added devDependency: ${result.dependency.name} ${result.dependency.range}`);
@@ -9177,7 +11276,7 @@ async function runInitCommand(invocation) {
   }
 }
 function detectPackageManager(cwd) {
-  const has = (name) => fs12.existsSync(path13.join(cwd, name));
+  const has = (name) => fs16.existsSync(path17.join(cwd, name));
   if (has("bun.lockb") || has("bun.lock")) return { name: "bun", command: "bun", args: ["install"] };
   if (has("pnpm-lock.yaml")) return { name: "pnpm", command: "pnpm", args: ["install"] };
   if (has("yarn.lock")) return { name: "yarn", command: "yarn", args: ["install"] };
@@ -9196,14 +11295,13 @@ function installDependencies(cwd) {
   const manager = detectPackageManager(cwd);
   const command = `${manager.command} ${manager.args.join(" ")}`;
   const started = performance.now();
-  const result = spawnSync(manager.command, manager.args, {
+  const spawnOptions = {
     cwd,
     encoding: "utf8",
-    // npm, pnpm and yarn ship as `.cmd` shims on Windows, which spawnSync cannot exec directly.
-    shell: process.platform === "win32",
     timeout: INSTALL_TIMEOUT_MS,
     env: cleanInstallEnv()
-  });
+  };
+  const result = process.platform === "win32" ? spawnSync(command, { ...spawnOptions, shell: true }) : spawnSync(manager.command, manager.args, spawnOptions);
   const seconds = `${((performance.now() - started) / 1e3).toFixed(1)}s`;
   if (result.error) {
     return { manager: manager.name, command, ok: false, detail: `${result.error.message} (${seconds})` };
@@ -9228,8 +11326,9 @@ async function captureStdout(fn) {
     process.stdout.write = original;
   }
 }
-async function runSetupCommand(invocation) {
+async function runSetupCommand(invocation, options = {}) {
   try {
+    const interactive = options.interactive === true;
     const init = await runInit({
       cwd: invocation.cwd,
       preset: invocation.preset,
@@ -9239,7 +11338,7 @@ async function runSetupCommand(invocation) {
       exclude: splitList(invocation.exclude),
       skipArtifacts: invocation.skipArtifacts,
       includeSensitiveFiles: invocation.includeSensitiveFiles,
-      yes: true,
+      yes: !interactive,
       force: invocation.force,
       reuseConfig: true,
       dryRun: invocation.dryRun
@@ -9266,7 +11365,7 @@ async function runSetupCommand(invocation) {
       }
       info("\n\u{1F9EA} Dry run \u2014 setup would:");
       info(
-        `   1. ${init.reused ? `keep ${path13.basename(init.configPath)}` : `write ${path13.basename(init.configPath)} (preset: ${init.preset})`}`
+        `   1. ${init.reused ? `keep ${path17.basename(init.configPath)}` : `write ${path17.basename(init.configPath)} (preset: ${init.preset})`}`
       );
       info("   2. add the npm scripts, the devDependency and the .gitignore entries");
       if (manager !== null) info(`   3. install with ${manager}`);
@@ -9276,11 +11375,11 @@ async function runSetupCommand(invocation) {
       return 0;
     }
     if (invocation.format !== "json") {
-      info(`\u{1F680} Setup for: ${invocation.cwd}`);
+      if (!interactive) info(`\u{1F680} Setup for: ${invocation.cwd}`);
       if (init.reused) {
-        info(`\u267B  Keeping ${path13.basename(init.configPath)} (preset: ${init.preset})`);
+        info(`\u267B  Keeping ${path17.basename(init.configPath)} (${presetSummary(init)})`);
       } else {
-        info(`\u2705 Created ${path13.basename(init.configPath)} (preset: ${init.preset})`);
+        info(`\u2705 Created ${path17.basename(init.configPath)} (${presetSummary(init)})`);
       }
       if (init.scripts.length > 0) info(`   Added npm scripts: ${init.scripts.join(", ")}`);
       if (init.dependency.added && init.dependency.range !== null) {
@@ -9309,6 +11408,7 @@ async function runSetupCommand(invocation) {
     if ((invocation.skipArtifacts ?? []).length > 0) {
       generateArgs.push("--skip-artifacts", (invocation.skipArtifacts ?? []).join(","));
     }
+    if (invocation.watch) generateArgs.push("--watch");
     if (invocation.format === "json") {
       const generated = await captureStdout(() => main(generateArgs));
       let manifest = null;
@@ -9348,6 +11448,24 @@ async function runSetupCommand(invocation) {
     return fail(invocation.format, err.message);
   }
 }
+async function firstRun(invocation) {
+  const plan = planFirstRun({
+    hasConfig: findConfigFile(invocation.cwd) !== null,
+    hasPriorSnapshot: hasPriorSnapshot(invocation.cwd, invocation.outDir ?? DEFAULT_ANSWERS.outDir),
+    // A machine must never be asked a question, and `--format json` is how a machine says so.
+    interactive: invocation.format === "text" && isInteractive(defaultIO()),
+    autopilot: invocation.autopilot,
+    emptyTarget: isEffectivelyEmpty(invocation.cwd)
+  });
+  if (plan.action === "generate") return null;
+  if (plan.action === "refuse") {
+    return fail(invocation.format, firstRunMessage(plan.reason, invocation.cwd), plan.exitCode);
+  }
+  info(
+    plan.interactive ? "\u2699  This project has no snapshot configuration yet." : "\u2699  --autopilot: setting this project up before generating."
+  );
+  return await runSetupCommand(invocation, { interactive: plan.interactive });
+}
 function runSkillCommand(invocation) {
   if (!invocation.install) {
     if (invocation.format === "json") {
@@ -9369,7 +11487,7 @@ function runSkillCommand(invocation) {
     }
     info(`\u2705 Agent skill installed (${SKILL_NAME}):`);
     for (const item of result.written) {
-      const shown = path13.relative(invocation.cwd, item.path) || item.path;
+      const shown = path17.relative(invocation.cwd, item.path) || item.path;
       info(`   - ${item.action.padEnd(9)} ${shown}`);
     }
     if (result.gitignored.length > 0) {
@@ -9464,9 +11582,16 @@ ${USAGE}
   if (invocation.command === "skill") {
     return runSkillCommand(invocation);
   }
+  if (invocation.command === "mcp") {
+    return await runStdioServer({ cwd: path17.resolve(invocation.cwd) });
+  }
   if (invocation.command === "setup") {
     return runSetupCommand(invocation);
   }
+  if (invocation.command === "generate" && !invocation.noConfig && (!invocation.explicitCommand || invocation.autopilot)) {
+    const decided = await firstRun(invocation);
+    if (decided !== null) return decided;
+  }
   const skipConfig = invocation.noConfig || invocation.command === "diff";
   const loaded = skipConfig ? { config: null, warnings: [], errors: [], file: null } : await loadConfigFileDetailed(invocation.cwd);
   if (invocation.noConfig) info("\u2699  --no-config: using built-in defaults, config file ignored");
@@ -9475,7 +11600,7 @@ ${USAGE}
     warn("\u274C The config file could not be read. Fix it, or delete it to use the defaults.");
     return 1;
   }
-  if (loaded.file) info(`\u2699  Using config ${path13.relative(process.cwd(), loaded.file) || loaded.file}`);
+  if (loaded.file) info(`\u2699  Using config ${path17.relative(process.cwd(), loaded.file) || loaded.file}`);
   const resolved = resolveConfig(
     loaded.config,
     {
@@ -9497,10 +11622,10 @@ ${USAGE}
   if (invocation.command === "validate") {
     const result = validateSnapshot(resolved);
     if (result.valid) {
-      const manifestPath = path13.resolve(resolved.cwd, resolved.outDir, "manifest.json");
+      const manifestPath = path17.resolve(resolved.cwd, resolved.outDir, "manifest.json");
       let manifest;
       try {
-        manifest = JSON.parse(fs12.readFileSync(manifestPath, "utf8"));
+        manifest = JSON.parse(fs16.readFileSync(manifestPath, "utf8"));
       } catch {
         manifest = void 0;
       }
@@ -9513,13 +11638,13 @@ ${USAGE}
     return result.valid ? 0 : 1;
   }
   if (invocation.command === "report") {
-    const manifestPath = path13.resolve(resolved.cwd, resolved.outDir, "manifest.json");
-    if (!fs12.existsSync(manifestPath)) {
+    const manifestPath = path17.resolve(resolved.cwd, resolved.outDir, "manifest.json");
+    if (!fs16.existsSync(manifestPath)) {
       return fail(invocation.format, `Manifest not found at ${manifestPath}. Run generate first.`);
     }
     let manifest;
     try {
-      manifest = JSON.parse(fs12.readFileSync(manifestPath, "utf8"));
+      manifest = JSON.parse(fs16.readFileSync(manifestPath, "utf8"));
     } catch (err) {
       return fail(invocation.format, `Could not read ${manifestPath}: ${err.message}`);
     }
@@ -9683,20 +11808,20 @@ function finishWatchRun(state, now) {
   };
 }
 function comparablePath(value) {
-  const absolute = path13.resolve(value);
+  const absolute = path17.resolve(value);
   return process.platform === "win32" ? absolute.toLowerCase() : absolute;
 }
 function isSameOrInside(parent, candidate) {
-  const relative8 = path13.relative(parent, candidate);
-  return relative8 === "" || relative8 !== ".." && !relative8.startsWith(`..${path13.sep}`) && !path13.isAbsolute(relative8);
+  const relative11 = path17.relative(parent, candidate);
+  return relative11 === "" || relative11 !== ".." && !relative11.startsWith(`..${path17.sep}`) && !path17.isAbsolute(relative11);
 }
 function isGeneratedWatchPath(candidate, paths) {
-  const absolute = comparablePath(path13.resolve(paths.cwd, candidate));
-  const outDir = comparablePath(path13.resolve(paths.cwd, paths.outDir));
-  const tmpDir = comparablePath(path13.resolve(paths.cwd, paths.tmpDir));
+  const absolute = comparablePath(path17.resolve(paths.cwd, candidate));
+  const outDir = comparablePath(path17.resolve(paths.cwd, paths.outDir));
+  const tmpDir = comparablePath(path17.resolve(paths.cwd, paths.tmpDir));
   if (isSameOrInside(outDir, absolute) || isSameOrInside(tmpDir, absolute)) return true;
-  const parent = path13.dirname(absolute);
-  if (parent === path13.dirname(outDir) && path13.basename(absolute).startsWith(`${path13.basename(outDir)}.backup-`)) {
+  const parent = path17.dirname(absolute);
+  if (parent === path17.dirname(outDir) && path17.basename(absolute).startsWith(`${path17.basename(outDir)}.backup-`)) {
     return true;
   }
   return absolute.split(/[\\/]+/).some((segment) => VCS_SEGMENTS.has(segment));
@@ -9713,8 +11838,8 @@ function decideWatchEvent(state, event, paths) {
   return { state, action: "schedule" };
 }
 async function runWatchLoop(invocation, resolved) {
-  const outDir = path13.resolve(resolved.cwd, resolved.outDir);
-  const tmpDir = path13.resolve(resolved.cwd, resolved.tmpDir);
+  const outDir = path17.resolve(resolved.cwd, resolved.outDir);
+  const tmpDir = path17.resolve(resolved.cwd, resolved.tmpDir);
   const paths = { cwd: resolved.cwd, outDir, tmpDir };
   let state = initialWatchState();
   let timer = null;
@@ -9779,11 +11904,11 @@ async function runWatchLoop(invocation, resolved) {
   };
   info("\u{1F440} Watching for changes. Press Ctrl+C to stop.");
   void regenerate();
-  const watcher = fs12.watch(resolved.cwd, { recursive: true }, (_event, filename) => {
+  const watcher = fs16.watch(resolved.cwd, { recursive: true }, (_event, filename) => {
     const decision = decideWatchEvent(
       state,
       {
-        path: filename ? path13.resolve(resolved.cwd, filename.toString()) : null,
+        path: filename ? path17.resolve(resolved.cwd, filename.toString()) : null,
         now: performance.now()
       },
       paths
@@ -9798,12 +11923,12 @@ async function runWatchLoop(invocation, resolved) {
     }
     if (decision.action === "schedule") schedule();
   });
-  await new Promise((resolve6) => {
+  await new Promise((resolve9) => {
     const stop = () => {
       stopped = true;
       if (timer) clearTimeout(timer);
       watcher.close();
-      resolve6();
+      resolve9();
     };
     process.once("SIGINT", stop);
     process.once("SIGTERM", stop);
@@ -9811,7 +11936,7 @@ async function runWatchLoop(invocation, resolved) {
   return 0;
 }
 var entryFile = process.argv[1] ?? "";
-var entryName = path13.basename(entryFile).toLowerCase();
+var entryName = path17.basename(entryFile).toLowerCase();
 var invokedDirectly = entryName === "cli.js" || entryName === "cli.cjs";
 if (invokedDirectly) {
   void main().then(