outfitter 0.2.4 → 0.2.6

package/dist/shared/{chunk-tpwtpa74.js → chunk-k59f60cp.js}

@@ -212,12 +212,9 @@ async function printDoctorResults(result, options) {
   await output(lines, { mode: "human" });
 }
 function doctorCommand(program) {
-  program.command("doctor").description("Validate environment and dependencies").option("--json", "Output as JSON", false).action(async (_flags, command) => {
+  program.command("doctor").description("Validate environment and dependencies").action(async (_flags, command) => {
     const resolvedFlags = command.optsWithGlobals();
     const outputOptions = resolvedFlags.json ? { mode: "json" } : undefined;
-    if (resolvedFlags.json) {
-      process.env["OUTFITTER_JSON"] = "1";
-    }
     const result = await runDoctor({ cwd: process.cwd() });
     await printDoctorResults(result, outputOptions);
     process.exit(result.exitCode);
@@ -2088,12 +2085,11 @@ function initCommand(program) {
   };
   const resolveOutputMode = (flags) => {
     if (flags.json) {
-      process.env["OUTFITTER_JSON"] = "1";
       return "json";
     }
     return;
   };
-  const withCommonOptions = (command) => command.option("-n, --name <name>", "Package name (defaults to directory name)").option("-b, --bin <name>", "Binary name (defaults to project name)").option("-p, --preset <preset>", "Preset to use (minimal|cli|mcp|daemon)").option("-s, --structure <mode>", "Project structure (single|workspace)").option("--workspace-name <name>", "Workspace root package name").option("-f, --force", "Overwrite existing files", false).option("--local", "Use workspace:* for @outfitter dependencies").option("--workspace", "Alias for --local").option("--with <blocks>", "Comma-separated tooling blocks to add").option("--no-tooling", "Skip default tooling blocks").option("-y, --yes", "Skip prompts and use defaults", false).option("--dry-run", "Preview changes without writing files", false).option("--skip-install", "Skip bun install", false).option("--skip-git", "Skip git init and initial commit", false).option("--skip-commit", "Skip initial commit only", false).option("--install-timeout <ms>", "bun install timeout in ms").option("--json", "Output as JSON", false);
+  const withCommonOptions = (command) => command.option("-n, --name <name>", "Package name (defaults to directory name)").option("-b, --bin <name>", "Binary name (defaults to project name)").option("-p, --preset <preset>", "Preset to use (minimal|cli|mcp|daemon)").option("-s, --structure <mode>", "Project structure (single|workspace)").option("--workspace-name <name>", "Workspace root package name").option("-f, --force", "Overwrite existing files", false).option("--local", "Use workspace:* for @outfitter dependencies").option("--workspace", "Alias for --local").option("--with <blocks>", "Comma-separated tooling blocks to add").option("--no-tooling", "Skip default tooling blocks").option("-y, --yes", "Skip prompts and use defaults", false).option("--dry-run", "Preview changes without writing files", false).option("--skip-install", "Skip bun install", false).option("--skip-git", "Skip git init and initial commit", false).option("--skip-commit", "Skip initial commit only", false).option("--install-timeout <ms>", "bun install timeout in ms");
   withCommonOptions(init.argument("[directory]").option("-t, --template <template>", "Template to use (deprecated)")).action(async (directory, flags, command) => {
     const targetDir = directory ?? process.cwd();
     const resolvedFlags = resolveFlags(flags, command);
@@ -2904,18 +2900,16 @@ function migrateKitCommand(program) {
   if (migrate.commands.some((command) => command.name() === "kit")) {
     return;
   }
-  migrate.command("kit [directory]").description("Migrate foundation imports and dependencies to @outfitter/kit").option("--dry-run", "Preview changes without writing files", false).option("--json", "Output result as JSON", false).action(async (directory, flags) => {
-    if (flags.json) {
-      process.env["OUTFITTER_JSON"] = "1";
-    }
+  migrate.command("kit [directory]").description("Migrate foundation imports and dependencies to @outfitter/kit").option("--dry-run", "Preview changes without writing files", false).action(async (directory, _flags, command) => {
+    const resolvedFlags = command.optsWithGlobals();
     const result = await runMigrateKit({
       ...directory ? { targetDir: directory } : {},
-      dryRun: Boolean(flags.dryRun)
+      dryRun: Boolean(resolvedFlags.dryRun)
     });
     if (result.isErr()) {
       throw result.error;
     }
-    await printMigrateKitResults(result.value, flags.json ? { mode: "json" } : undefined);
+    await printMigrateKitResults(result.value, resolvedFlags.json ? { mode: "json" } : undefined);
   });
 }
 
@@ -3395,20 +3389,21 @@ async function printScaffoldResults(result, options) {
   await output6(lines, { mode: "human" });
 }
 function scaffoldCommand(program) {
-  program.command("scaffold <target> [name]").description("Add a capability to an existing project").option("-f, --force", "Overwrite existing files", false).option("--skip-install", "Skip bun install", false).option("--dry-run", "Preview changes without executing", false).option("--with <blocks>", "Comma-separated tooling blocks to add").option("--no-tooling", "Skip default tooling blocks").option("--local", "Use workspace:* for @outfitter dependencies").option("--install-timeout <ms>", "bun install timeout in ms").option("--json", "Output as JSON", false).action(async (target, name, flags) => {
-    const mode = flags.json ? "json" : undefined;
+  program.command("scaffold <target> [name]").description("Add a capability to an existing project").option("-f, --force", "Overwrite existing files", false).option("--skip-install", "Skip bun install", false).option("--dry-run", "Preview changes without executing", false).option("--with <blocks>", "Comma-separated tooling blocks to add").option("--no-tooling", "Skip default tooling blocks").option("--local", "Use workspace:* for @outfitter dependencies").option("--install-timeout <ms>", "bun install timeout in ms").action(async (target, name, _flags, command) => {
+    const resolvedFlags = command.optsWithGlobals();
+    const mode = resolvedFlags.json ? "json" : undefined;
     const outputOptions = mode ? { mode } : undefined;
     const result = await runScaffold({
       target,
       name,
-      force: Boolean(flags.force),
-      skipInstall: Boolean(flags.skipInstall),
-      dryRun: Boolean(flags.dryRun),
-      with: flags.with,
-      noTooling: flags.noTooling,
-      local: flags.local,
+      force: Boolean(resolvedFlags.force),
+      skipInstall: Boolean(resolvedFlags.skipInstall),
+      dryRun: Boolean(resolvedFlags.dryRun),
+      with: resolvedFlags.with,
+      noTooling: resolvedFlags.noTooling,
+      local: resolvedFlags.local,
       cwd: process.cwd(),
-      ...flags.installTimeout !== undefined ? { installTimeout: flags.installTimeout } : {}
+      ...resolvedFlags.installTimeout !== undefined ? { installTimeout: resolvedFlags.installTimeout } : {}
     });
     if (result.isErr()) {
       exitWithError2(result.error, outputOptions);
@@ -3419,14 +3414,22 @@ function scaffoldCommand(program) {
 }
 
 // src/actions.ts
-import { resolve as resolve10 } from "node:path";
+import { resolve as resolve11 } from "node:path";
 import { output as output10 } from "@outfitter/cli";
-import { cwdPreset, verbosePreset } from "@outfitter/cli/flags";
+import { actionCliPresets } from "@outfitter/cli/actions";
+import {
+  booleanFlagPreset,
+  cwdPreset,
+  dryRunPreset,
+  forcePreset,
+  interactionPreset,
+  verbosePreset
+} from "@outfitter/cli/flags";
 import {
   createActionRegistry,
   defineAction,
-  InternalError as InternalError4,
-  Result as Result16
+  InternalError as InternalError5,
+  Result as Result17
 } from "@outfitter/contracts";
 import { z as z2 } from "zod";
 
@@ -3841,14 +3844,137 @@ async function runDemo(options) {
 `));
 }
 
-// src/commands/update.ts
-import { existsSync as existsSync12, readFileSync as readFileSync10 } from "node:fs";
-import { join as join13, resolve as resolve9 } from "node:path";
+// src/commands/upgrade.ts
+import { existsSync as existsSync13, mkdirSync as mkdirSync6, readFileSync as readFileSync10, writeFileSync as writeFileSync7 } from "node:fs";
+import { join as join14, resolve as resolve10 } from "node:path";
 import { output as output9 } from "@outfitter/cli";
-import { InternalError as InternalError3, Result as Result15 } from "@outfitter/contracts";
+import { InternalError as InternalError4, Result as Result16 } from "@outfitter/contracts";
 import { createTheme as createTheme3 } from "@outfitter/tui/render";
 
-// src/commands/update-planner.ts
+// src/commands/upgrade-codemods.ts
+import { existsSync as existsSync11 } from "node:fs";
+import { isAbsolute, join as join12, relative as relative4, resolve as resolve8 } from "node:path";
+import { InternalError as InternalError2, Result as Result14 } from "@outfitter/contracts";
+var CODEMOD_PATHS = [
+  "plugins/outfitter/shared/codemods",
+  "node_modules/@outfitter/kit/shared/codemods"
+];
+function findCodemodsDir(cwd, binaryDir) {
+  for (const relativePath of CODEMOD_PATHS) {
+    const dir = join12(cwd, relativePath);
+    if (existsSync11(dir))
+      return dir;
+  }
+  let current = resolve8(cwd);
+  const root = resolve8("/");
+  while (current !== root) {
+    const parent = resolve8(current, "..");
+    if (parent === current)
+      break;
+    current = parent;
+    for (const relativePath of CODEMOD_PATHS) {
+      const dir = join12(current, relativePath);
+      if (existsSync11(dir))
+        return dir;
+    }
+  }
+  const resolvedBinaryDir = binaryDir ?? resolve8(import.meta.dir, "../../../..");
+  for (const relativePath of CODEMOD_PATHS) {
+    const dir = join12(resolvedBinaryDir, relativePath);
+    if (existsSync11(dir))
+      return dir;
+  }
+  return null;
+}
+function discoverCodemods(migrationsDir, codemodsDir, shortName, fromVersion, toVersion) {
+  const resolvedCodemodsDir = resolve8(codemodsDir);
+  const docs = (() => {
+    try {
+      return readMigrationDocsWithMetadata(migrationsDir, shortName, fromVersion, toVersion);
+    } catch {
+      return [];
+    }
+  })();
+  const seen = new Set;
+  const codemods = [];
+  for (const doc of docs) {
+    if (!doc.frontmatter.changes)
+      continue;
+    for (const change of doc.frontmatter.changes) {
+      if (!change.codemod)
+        continue;
+      if (seen.has(change.codemod))
+        continue;
+      seen.add(change.codemod);
+      const absolutePath = resolveCodemodPath(resolvedCodemodsDir, change.codemod);
+      if (absolutePath === null)
+        continue;
+      if (!existsSync11(absolutePath))
+        continue;
+      codemods.push({
+        relativePath: change.codemod,
+        absolutePath
+      });
+    }
+  }
+  return codemods;
+}
+function resolveCodemodPath(codemodsDir, relativePath) {
+  if (relativePath.trim().length === 0) {
+    return null;
+  }
+  if (isAbsolute(relativePath)) {
+    return null;
+  }
+  const resolvedPath = resolve8(codemodsDir, relativePath);
+  const relPath = relative4(codemodsDir, resolvedPath);
+  if (relPath === "" || relPath.startsWith("..") || isAbsolute(relPath)) {
+    return null;
+  }
+  return resolvedPath;
+}
+async function runCodemod(codemodPath, targetDir, dryRun) {
+  let mod;
+  try {
+    mod = await import(codemodPath);
+  } catch (error) {
+    return Result14.err(InternalError2.create("Failed to load codemod", {
+      codemodPath,
+      error: error instanceof Error ? error.message : String(error)
+    }));
+  }
+  if (typeof mod["transform"] !== "function") {
+    return Result14.err(InternalError2.create(`Codemod has no transform export: ${codemodPath}`, {
+      codemodPath
+    }));
+  }
+  const transform = mod["transform"];
+  try {
+    const result = await transform({ targetDir, dryRun });
+    if (!isCodemodResult(result)) {
+      return Result14.err(InternalError2.create("Codemod returned invalid result shape", {
+        codemodPath
+      }));
+    }
+    return Result14.ok(result);
+  } catch (error) {
+    return Result14.err(InternalError2.create("Codemod execution failed", {
+      codemodPath,
+      error: error instanceof Error ? error.message : String(error)
+    }));
+  }
+}
+function isCodemodResult(value) {
+  if (typeof value !== "object" || value === null)
+    return false;
+  const candidate = value;
+  return isStringArray(candidate["changedFiles"]) && isStringArray(candidate["skippedFiles"]) && isStringArray(candidate["errors"]);
+}
+function isStringArray(value) {
+  return Array.isArray(value) && value.every((item) => typeof item === "string");
+}
+
+// src/commands/upgrade-planner.ts
 function getMajor(version) {
   const parts = version.split(".");
   return Number.parseInt(parts[0] ?? "0", 10);
@@ -3885,7 +4011,7 @@ function classify(currentVersion, latestVersion, breakingFlag) {
   }
   return "upgradableNonBreaking";
 }
-function analyzeUpdates(installed, latest, migrationDocs) {
+function analyzeUpgrades(installed, latest, migrationDocs) {
   const packages = [];
   for (const [name, currentVersion] of installed) {
     const latestInfo = latest.get(name);
@@ -3916,24 +4042,24 @@ function analyzeUpdates(installed, latest, migrationDocs) {
   return { packages, summary };
 }
 
-// src/commands/update-workspace.ts
-import { existsSync as existsSync11, readFileSync as readFileSync9 } from "node:fs";
-import { basename as basename5, dirname as dirname7, join as join12, resolve as resolve8 } from "node:path";
-import { InternalError as InternalError2, Result as Result14 } from "@outfitter/contracts";
+// src/commands/upgrade-workspace.ts
+import { existsSync as existsSync12, readFileSync as readFileSync9 } from "node:fs";
+import { basename as basename5, dirname as dirname7, join as join13, resolve as resolve9 } from "node:path";
+import { InternalError as InternalError3, Result as Result15 } from "@outfitter/contracts";
 function detectWorkspaceRoot2(cwd) {
-  let current = resolve8(cwd);
-  const root = resolve8("/");
+  let current = resolve9(cwd);
+  const root = resolve9("/");
   while (true) {
-    if (existsSync11(join12(current, "pnpm-workspace.yaml"))) {
-      return Result14.ok(current);
+    if (existsSync12(join13(current, "pnpm-workspace.yaml"))) {
+      return Result15.ok(current);
     }
-    const pkgPath = join12(current, "package.json");
-    if (existsSync11(pkgPath)) {
+    const pkgPath = join13(current, "package.json");
+    if (existsSync12(pkgPath)) {
       try {
         const raw = readFileSync9(pkgPath, "utf-8");
         const pkg = JSON.parse(raw);
         if (hasWorkspacesField3(pkg)) {
-          return Result14.ok(current);
+          return Result15.ok(current);
         }
       } catch {}
     }
@@ -3946,7 +4072,7 @@ function detectWorkspaceRoot2(cwd) {
     }
     current = parent;
   }
-  return Result14.ok(null);
+  return Result15.ok(null);
 }
 function hasWorkspacesField3(pkg) {
   const workspaces = pkg.workspaces;
@@ -3991,10 +4117,10 @@ function normalizeWorkspacePattern2(pattern) {
   return `${value}/package.json`;
 }
 function collectWorkspaceManifests(rootDir) {
-  const resolvedRoot = resolve8(rootDir);
-  const rootPackageJson = join12(resolvedRoot, "package.json");
-  if (!existsSync11(rootPackageJson)) {
-    return Result14.err(InternalError2.create("No package.json found at workspace root", {
+  const resolvedRoot = resolve9(rootDir);
+  const rootPackageJson = join13(resolvedRoot, "package.json");
+  if (!existsSync12(rootPackageJson)) {
+    return Result15.err(InternalError3.create("No package.json found at workspace root", {
       rootDir: resolvedRoot
     }));
   }
@@ -4003,7 +4129,7 @@ function collectWorkspaceManifests(rootDir) {
     const raw = readFileSync9(rootPackageJson, "utf-8");
     pkg = JSON.parse(raw);
   } catch {
-    return Result14.err(InternalError2.create("Invalid JSON in root package.json", {
+    return Result15.err(InternalError3.create("Invalid JSON in root package.json", {
       rootDir: resolvedRoot
     }));
   }
@@ -4014,13 +4140,13 @@ function collectWorkspaceManifests(rootDir) {
       continue;
     const glob = new Bun.Glob(pattern);
     for (const entry of glob.scanSync({ cwd: resolvedRoot })) {
-      const absolute = resolve8(resolvedRoot, entry);
-      if (existsSync11(absolute) && basename5(absolute) === "package.json") {
+      const absolute = resolve9(resolvedRoot, entry);
+      if (existsSync12(absolute) && basename5(absolute) === "package.json") {
         files.add(absolute);
       }
     }
   }
-  return Result14.ok(Array.from(files).sort((a, b) => a.localeCompare(b)));
+  return Result15.ok(Array.from(files).sort((a, b) => a.localeCompare(b)));
 }
 function extractOutfitterDeps(manifestPath2) {
   let pkg;
@@ -4028,7 +4154,7 @@ function extractOutfitterDeps(manifestPath2) {
     const raw = readFileSync9(manifestPath2, "utf-8");
     pkg = JSON.parse(raw);
   } catch {
-    return Result14.err(InternalError2.create("Failed to parse package.json", {
+    return Result15.err(InternalError3.create("Failed to parse package.json", {
       path: manifestPath2
     }));
   }
@@ -4064,10 +4190,10 @@ function extractOutfitterDeps(manifestPath2) {
     }
     packages.push({ name, version: cleaned });
   }
-  return Result14.ok(packages);
+  return Result15.ok(packages);
 }
 function getInstalledPackagesFromWorkspace(rootDir) {
-  const resolvedRoot = resolve8(rootDir);
+  const resolvedRoot = resolve9(rootDir);
   const wsRootResult = detectWorkspaceRoot2(resolvedRoot);
   if (wsRootResult.isErr())
     return wsRootResult;
@@ -4079,9 +4205,9 @@ function getInstalledPackagesFromWorkspace(rootDir) {
       return manifestsResult;
     manifestPaths = manifestsResult.value;
   } else {
-    const rootPkg = join12(resolvedRoot, "package.json");
-    if (!existsSync11(rootPkg)) {
-      return Result14.err(InternalError2.create("No package.json found", { cwd: resolvedRoot }));
+    const rootPkg = join13(resolvedRoot, "package.json");
+    if (!existsSync12(rootPkg)) {
+      return Result15.err(InternalError3.create("No package.json found", { cwd: resolvedRoot }));
     }
     manifestPaths = [rootPkg];
   }
@@ -4131,7 +4257,7 @@ function getInstalledPackagesFromWorkspace(rootDir) {
     }
   }
   packages.sort((a, b) => a.name.localeCompare(b.name));
-  return Result14.ok({
+  return Result15.ok({
     packages,
     conflicts,
     manifestsByPackage,
@@ -4160,7 +4286,7 @@ async function applyUpdatesToWorkspace(manifestPaths, manifestsByPackage, update
     try {
       raw = readFileSync9(manifestPath2, "utf-8");
     } catch {
-      return Result14.err(InternalError2.create("Failed to read package.json for apply", {
+      return Result15.err(InternalError3.create("Failed to read package.json for apply", {
         path: manifestPath2
       }));
     }
@@ -4168,7 +4294,7 @@ async function applyUpdatesToWorkspace(manifestPaths, manifestsByPackage, update
     try {
       pkg = JSON.parse(raw);
     } catch {
-      return Result14.err(InternalError2.create("Invalid JSON in package.json", {
+      return Result15.err(InternalError3.create("Invalid JSON in package.json", {
         path: manifestPath2
       }));
     }
@@ -4198,13 +4324,13 @@ async function applyUpdatesToWorkspace(manifestPaths, manifestsByPackage, update
 `;
         await Bun.write(manifestPath2, updated);
       } catch {
-        return Result14.err(InternalError2.create("Failed to write updated package.json", {
+        return Result15.err(InternalError3.create("Failed to write updated package.json", {
           path: manifestPath2
         }));
       }
     }
   }
-  return Result14.ok(undefined);
+  return Result15.ok(undefined);
 }
 function getVersionPrefix(specifier) {
   if (specifier.startsWith("workspace:")) {
@@ -4224,19 +4350,20 @@ async function runInstall(cwd) {
     const exitCode = await proc.exited;
     if (exitCode !== 0) {
       const stderr = await new Response(proc.stderr).text();
-      return Result14.err(InternalError2.create("bun install failed", {
+      return Result15.err(InternalError3.create("bun install failed", {
         cwd,
         exitCode,
         stderr: stderr.trim()
       }));
     }
   } catch {
-    return Result14.err(InternalError2.create("Failed to run bun install", { cwd }));
+    return Result15.err(InternalError3.create("Failed to run bun install", { cwd }));
   }
-  return Result14.ok(undefined);
+  return Result15.ok(undefined);
 }
 
-// src/commands/update.ts
+// src/commands/upgrade.ts
+var FRONTMATTER_BLOCK_REGEX = /^---\r?\n[\s\S]*?\r?\n---\r?\n*/;
 async function getLatestVersion(name) {
   try {
     const proc = Bun.spawn(["npm", "view", name, "version"], {
@@ -4257,28 +4384,28 @@ var MIGRATION_DOC_PATHS = [
   "node_modules/@outfitter/kit/shared/migrations"
 ];
 function findMigrationDocsDir(cwd, binaryDir) {
-  for (const relative4 of MIGRATION_DOC_PATHS) {
-    const dir = join13(cwd, relative4);
-    if (existsSync12(dir))
+  for (const relative5 of MIGRATION_DOC_PATHS) {
+    const dir = join14(cwd, relative5);
+    if (existsSync13(dir))
       return dir;
   }
-  let current = resolve9(cwd);
-  const root = resolve9("/");
+  let current = resolve10(cwd);
+  const root = resolve10("/");
   while (current !== root) {
-    const parent = resolve9(current, "..");
+    const parent = resolve10(current, "..");
     if (parent === current)
       break;
     current = parent;
-    for (const relative4 of MIGRATION_DOC_PATHS) {
-      const dir = join13(current, relative4);
-      if (existsSync12(dir))
+    for (const relative5 of MIGRATION_DOC_PATHS) {
+      const dir = join14(current, relative5);
+      if (existsSync13(dir))
         return dir;
     }
   }
-  const resolvedBinaryDir = binaryDir ?? resolve9(import.meta.dir, "../../../..");
-  for (const relative4 of MIGRATION_DOC_PATHS) {
-    const dir = join13(resolvedBinaryDir, relative4);
-    if (existsSync12(dir))
+  const resolvedBinaryDir = binaryDir ?? resolve10(import.meta.dir, "../../../..");
+  for (const relative5 of MIGRATION_DOC_PATHS) {
+    const dir = join14(resolvedBinaryDir, relative5);
+    if (existsSync13(dir))
       return dir;
   }
   return null;
@@ -4296,14 +4423,14 @@ function readMigrationDocs(migrationsDir, shortName, fromVersion, toVersion) {
       continue;
     if (Bun.semver.order(docVersion, toVersion) > 0)
       continue;
-    const filePath = join13(migrationsDir, entry);
+    const filePath = join14(migrationsDir, entry);
     let content;
     try {
       content = readFileSync10(filePath, "utf-8");
     } catch {
       continue;
     }
-    const body = content.replace(/^---\n[\s\S]*?\n---\n*/, "").trim();
+    const body = content.replace(FRONTMATTER_BLOCK_REGEX, "").trim();
     if (body) {
       docs.push({ version: docVersion, content: body });
     }
@@ -4312,8 +4439,8 @@ function readMigrationDocs(migrationsDir, shortName, fromVersion, toVersion) {
   return docs.map((d) => d.content);
 }
 function readMigrationBreakingFlag(migrationsDir, shortName, version) {
-  const filePath = join13(migrationsDir, `outfitter-${shortName}-${version}.md`);
-  if (!existsSync12(filePath)) {
+  const filePath = join14(migrationsDir, `outfitter-${shortName}-${version}.md`);
+  if (!existsSync13(filePath)) {
     return;
   }
   let content;
@@ -4337,23 +4464,176 @@ function readMigrationBreakingFlag(migrationsDir, shortName, version) {
     return false;
   return;
 }
+var VALID_CHANGE_TYPES = new Set([
+  "renamed",
+  "removed",
+  "signature-changed",
+  "moved",
+  "deprecated",
+  "added"
+]);
+function parseYamlValue(raw) {
+  const trimmed = raw.trim();
+  if (trimmed.startsWith('"') && trimmed.endsWith('"') || trimmed.startsWith("'") && trimmed.endsWith("'")) {
+    return trimmed.slice(1, -1);
+  }
+  return trimmed;
+}
+function parseMigrationFrontmatter(content) {
+  const fmMatch = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+  if (!fmMatch?.[1])
+    return null;
+  const fmBlock = fmMatch[1];
+  const lines = fmBlock.split(/\r?\n/);
+  let pkg;
+  let version;
+  let breaking;
+  let changesStartIdx = -1;
+  for (let i = 0;i < lines.length; i++) {
+    const line = lines[i];
+    if (line === undefined)
+      continue;
+    const trimmed = line.trimStart();
+    if (trimmed.startsWith("package:")) {
+      pkg = parseYamlValue(trimmed.slice("package:".length));
+    } else if (trimmed.startsWith("version:")) {
+      version = parseYamlValue(trimmed.slice("version:".length));
+    } else if (trimmed.startsWith("breaking:")) {
+      const val = parseYamlValue(trimmed.slice("breaking:".length));
+      if (val === "true")
+        breaking = true;
+      else if (val === "false")
+        breaking = false;
+    } else if (trimmed.startsWith("changes:")) {
+      changesStartIdx = i + 1;
+    }
+  }
+  if (pkg === undefined || version === undefined || breaking === undefined) {
+    return null;
+  }
+  let changes;
+  if (changesStartIdx >= 0) {
+    changes = parseChangesArray(lines, changesStartIdx);
+  }
+  return {
+    package: pkg,
+    version,
+    breaking,
+    ...changes !== undefined ? { changes } : {}
+  };
+}
+function parseChangesArray(lines, startIdx) {
+  const changes = [];
+  let current = null;
+  for (let i = startIdx;i < lines.length; i++) {
+    const line = lines[i];
+    if (line === undefined)
+      continue;
+    if (/^\s+-\s+/.test(line)) {
+      if (current !== null) {
+        const change = buildChange(current);
+        if (change)
+          changes.push(change);
+      }
+      current = {};
+      const afterDash = line.replace(/^\s+-\s+/, "");
+      const colonIdx = afterDash.indexOf(":");
+      if (colonIdx >= 0) {
+        const key = afterDash.slice(0, colonIdx).trim();
+        const val = parseYamlValue(afterDash.slice(colonIdx + 1));
+        current[key] = val;
+      }
+    } else if (current !== null && /^\s{4,}\S/.test(line)) {
+      const trimmed = line.trim();
+      const colonIdx = trimmed.indexOf(":");
+      if (colonIdx >= 0) {
+        const key = trimmed.slice(0, colonIdx).trim();
+        const val = parseYamlValue(trimmed.slice(colonIdx + 1));
+        current[key] = val;
+      }
+    } else if (/^\S/.test(line)) {
+      break;
+    }
+  }
+  if (current !== null) {
+    const change = buildChange(current);
+    if (change)
+      changes.push(change);
+  }
+  return changes;
+}
+function buildChange(raw) {
+  const type = raw["type"];
+  if (!(type && VALID_CHANGE_TYPES.has(type))) {
+    return null;
+  }
+  return {
+    type,
+    ...raw["from"] ? { from: raw["from"] } : {},
+    ...raw["to"] ? { to: raw["to"] } : {},
+    ...raw["path"] ? { path: raw["path"] } : {},
+    ...raw["export"] ? { export: raw["export"] } : {},
+    ...raw["detail"] ? { detail: raw["detail"] } : {},
+    ...raw["codemod"] ? { codemod: raw["codemod"] } : {}
+  };
+}
+function readMigrationDocsWithMetadata(migrationsDir, shortName, fromVersion, toVersion) {
+  const glob = new Bun.Glob(`outfitter-${shortName}-*.md`);
+  const versionPattern = new RegExp(`^outfitter-${shortName}-(\\d+\\.\\d+\\.\\d+)\\.md$`);
+  const docs = [];
+  for (const entry of glob.scanSync({ cwd: migrationsDir })) {
+    const match = entry.match(versionPattern);
+    if (!match?.[1])
+      continue;
+    const docVersion = match[1];
+    if (Bun.semver.order(docVersion, fromVersion) <= 0)
+      continue;
+    if (Bun.semver.order(docVersion, toVersion) > 0)
+      continue;
+    const filePath = join14(migrationsDir, entry);
+    let content;
+    try {
+      content = readFileSync10(filePath, "utf-8");
+    } catch {
+      continue;
+    }
+    const frontmatter = parseMigrationFrontmatter(content);
+    if (!frontmatter)
+      continue;
+    const body = content.replace(FRONTMATTER_BLOCK_REGEX, "").trim();
+    docs.push({ frontmatter, body, version: docVersion });
+  }
+  docs.sort((a, b) => Bun.semver.order(a.version, b.version));
+  return docs;
+}
 function buildMigrationGuides(packages, migrationsDir) {
   const guides = [];
   for (const pkg of packages) {
     if (!pkg.updateAvailable || pkg.latest === null)
       continue;
     let steps = [];
+    let allChanges;
     if (migrationsDir !== null) {
       const shortName = pkg.name.replace("@outfitter/", "");
-      const docs = readMigrationDocs(migrationsDir, shortName, pkg.current, pkg.latest);
-      steps = docs;
+      const metaDocs = readMigrationDocsWithMetadata(migrationsDir, shortName, pkg.current, pkg.latest);
+      steps = metaDocs.map((doc) => doc.body);
+      const changes = [];
+      for (const doc of metaDocs) {
+        if (doc.frontmatter.changes) {
+          changes.push(...doc.frontmatter.changes);
+        }
+      }
+      if (changes.length > 0) {
+        allChanges = changes;
+      }
     }
     guides.push({
       packageName: pkg.name,
       fromVersion: pkg.current,
       toVersion: pkg.latest,
       breaking: pkg.breaking,
-      steps
+      steps,
+      ...allChanges !== undefined ? { changes: allChanges } : {}
     });
   }
   return guides;
@@ -4367,18 +4647,18 @@ function getVersionPrefix2(specifier) {
   return match?.[1] ?? "";
 }
 async function applyUpdates(cwd, updates) {
-  const pkgPath = join13(cwd, "package.json");
+  const pkgPath = join14(cwd, "package.json");
   let raw;
   try {
     raw = readFileSync10(pkgPath, "utf-8");
   } catch {
-    return Result15.err(InternalError3.create("Failed to read package.json for apply", { cwd }));
+    return Result16.err(InternalError4.create("Failed to read package.json for apply", { cwd }));
   }
   let pkg;
   try {
     pkg = JSON.parse(raw);
   } catch {
-    return Result15.err(InternalError3.create("Invalid JSON in package.json", { cwd }));
+    return Result16.err(InternalError4.create("Invalid JSON in package.json", { cwd }));
   }
   const updateMap = new Map;
   for (const u of updates) {
@@ -4404,7 +4684,7 @@ async function applyUpdates(cwd, updates) {
 `;
     await Bun.write(pkgPath, updated);
   } catch {
-    return Result15.err(InternalError3.create("Failed to write updated package.json", { cwd }));
+    return Result16.err(InternalError4.create("Failed to write updated package.json", { cwd }));
   }
   try {
     const proc = Bun.spawn(["bun", "install"], {
@@ -4415,112 +4695,212 @@ async function applyUpdates(cwd, updates) {
     const exitCode = await proc.exited;
     if (exitCode !== 0) {
       const stderr = await new Response(proc.stderr).text();
-      return Result15.err(InternalError3.create("bun install failed", {
+      return Result16.err(InternalError4.create("bun install failed", {
         cwd,
         exitCode,
         stderr: stderr.trim()
       }));
     }
   } catch {
-    return Result15.err(InternalError3.create("Failed to run bun install", { cwd }));
-  }
-  return Result15.ok(undefined);
-}
-async function runUpdate(options) {
-  const cwd = resolve9(options.cwd);
-  const migrationsDir = findMigrationDocsDir(cwd);
-  const migrationFlagsDir = findMigrationDocsDir(cwd, cwd);
-  const scanResult = getInstalledPackagesFromWorkspace(cwd);
-  if (scanResult.isErr())
-    return scanResult;
-  const scan = scanResult.value;
-  const installed = scan.packages;
-  const installRoot = scan.workspaceRoot ?? cwd;
-  if (installed.length === 0) {
-    return Result15.ok({
-      packages: [],
-      total: 0,
-      updatesAvailable: 0,
-      hasBreaking: false,
+    return Result16.err(InternalError4.create("Failed to run bun install", { cwd }));
+  }
+  return Result16.ok(undefined);
+}
+async function runUpgrade(options) {
+  const cwd = resolve10(options.cwd);
+  const startedAt = new Date;
+  let workspaceRoot = null;
+  const emptyResult = {
+    packages: [],
+    total: 0,
+    updatesAvailable: 0,
+    hasBreaking: false,
+    applied: false,
+    appliedPackages: [],
+    skippedBreaking: []
+  };
+  const writeReport = (status, result, error) => {
+    writeUpgradeReportSafely(cwd, result, {
+      status,
+      startedAt,
+      workspaceRoot,
+      options,
+      ...error !== undefined ? { error } : {}
+    });
+  };
+  try {
+    const migrationsDir = findMigrationDocsDir(cwd);
+    const migrationFlagsDir = findMigrationDocsDir(cwd, cwd);
+    const scanResult = getInstalledPackagesFromWorkspace(cwd);
+    if (scanResult.isErr()) {
+      writeReport("failed", emptyResult, scanResult.error);
+      return scanResult;
+    }
+    const scan = scanResult.value;
+    workspaceRoot = scan.workspaceRoot;
+    const installed = scan.packages;
+    const installRoot = scan.workspaceRoot ?? cwd;
+    const codemodTargetDir = scan.workspaceRoot ?? cwd;
+    if (installed.length === 0) {
+      writeReport("no_updates", emptyResult);
+      return Result16.ok(emptyResult);
+    }
+    const latestVersions = new Map;
+    const installedMap = new Map;
+    const npmFailures = new Set;
+    await Promise.all(installed.map(async (pkg) => {
+      installedMap.set(pkg.name, pkg.version);
+      const latest = await getLatestVersion(pkg.name);
+      if (latest !== null) {
+        const shortName = pkg.name.replace("@outfitter/", "");
+        const docBreaking = migrationFlagsDir !== null ? readMigrationBreakingFlag(migrationFlagsDir, shortName, latest) : undefined;
+        latestVersions.set(pkg.name, {
+          version: latest,
+          ...docBreaking !== undefined ? { breaking: docBreaking } : {}
+        });
+      } else {
+        npmFailures.add(pkg.name);
+      }
+    }));
+    const plan = analyzeUpgrades(installedMap, latestVersions);
+    const packages = plan.packages.map((action) => ({
+      name: action.name,
+      current: action.currentVersion,
+      latest: npmFailures.has(action.name) ? null : action.latestVersion,
+      updateAvailable: action.classification === "upgradableNonBreaking" || action.classification === "upgradableBreaking",
+      breaking: action.breaking
+    }));
+    const updatesAvailable = packages.filter((p) => p.updateAvailable).length;
+    const hasBreaking = packages.some((p) => p.breaking);
+    const nonBreakingUpgradable = plan.packages.filter((a) => a.classification === "upgradableNonBreaking");
+    const breakingUpgradable = plan.packages.filter((a) => a.classification === "upgradableBreaking");
+    const includeBreaking = options.all === true;
+    const packagesToApply = includeBreaking ? [...nonBreakingUpgradable, ...breakingUpgradable] : nonBreakingUpgradable;
+    const skippedBreaking = includeBreaking ? [] : breakingUpgradable.map((a) => a.name);
+    let guidesData = options.guide === true ? buildMigrationGuides(packages, migrationsDir) : undefined;
+    if (guidesData !== undefined && options.guidePackages !== undefined && options.guidePackages.length > 0) {
+      const filterSet = new Set(options.guidePackages);
+      guidesData = guidesData.filter((g) => filterSet.has(g.packageName));
+    }
+    const buildResult = (overrides = {}) => ({
+      packages,
+      total: packages.length,
+      updatesAvailable,
+      hasBreaking,
       applied: false,
       appliedPackages: [],
-      skippedBreaking: []
+      skippedBreaking,
+      ...guidesData !== undefined ? { guides: guidesData } : {},
+      ...overrides
     });
-  }
-  const latestVersions = new Map;
-  const installedMap = new Map;
-  const npmFailures = new Set;
-  await Promise.all(installed.map(async (pkg) => {
-    installedMap.set(pkg.name, pkg.version);
-    const latest = await getLatestVersion(pkg.name);
-    if (latest !== null) {
-      const shortName = pkg.name.replace("@outfitter/", "");
-      const docBreaking = migrationFlagsDir !== null ? readMigrationBreakingFlag(migrationFlagsDir, shortName, latest) : undefined;
-      latestVersions.set(pkg.name, {
-        version: latest,
-        ...docBreaking !== undefined ? { breaking: docBreaking } : {}
+    if (options.dryRun) {
+      const result = buildResult();
+      writeReport("dry_run", result);
+      return Result16.ok(result);
+    }
+    if (packagesToApply.length === 0) {
+      const result = buildResult();
+      writeReport("no_updates", result);
+      return Result16.ok(result);
+    }
+    if (options.yes !== true && options.interactive !== false) {
+      const { confirmDestructive } = await import("@outfitter/tui/confirm");
+      const confirmed = await confirmDestructive({
+        message: `Apply ${packagesToApply.length} upgrade(s)?`,
+        itemCount: packagesToApply.length,
+        bypassFlag: false
       });
-    } else {
-      npmFailures.add(pkg.name);
-    }
-  }));
-  const plan = analyzeUpdates(installedMap, latestVersions);
-  const packages = plan.packages.map((action) => ({
-    name: action.name,
-    current: action.currentVersion,
-    latest: npmFailures.has(action.name) ? null : action.latestVersion,
-    updateAvailable: action.classification === "upgradableNonBreaking" || action.classification === "upgradableBreaking",
-    breaking: action.breaking
-  }));
-  const updatesAvailable = packages.filter((p) => p.updateAvailable).length;
-  const hasBreaking = packages.some((p) => p.breaking);
-  const nonBreakingUpgradable = plan.packages.filter((a) => a.classification === "upgradableNonBreaking");
-  const breakingUpgradable = plan.packages.filter((a) => a.classification === "upgradableBreaking");
-  const includeBreaking = options.apply === true && options.breaking === true;
-  const packagesToApply = includeBreaking ? [...nonBreakingUpgradable, ...breakingUpgradable] : nonBreakingUpgradable;
-  const skippedBreaking = includeBreaking ? [] : breakingUpgradable.map((a) => a.name);
-  let applied = false;
-  const appliedPackages = [];
-  if (options.apply && packagesToApply.length > 0) {
-    if (scan.workspaceRoot !== null) {
-      const applyResult = await applyUpdatesToWorkspace(scan.manifestPaths, scan.manifestsByPackage, packagesToApply);
-      if (applyResult.isErr())
-        return applyResult;
-      const installResult = await runInstall(installRoot);
-      if (installResult.isErr())
-        return installResult;
-    } else {
-      const applyResult = await applyUpdates(cwd, packagesToApply);
-      if (applyResult.isErr())
-        return applyResult;
+      if (confirmed.isErr()) {
+        const result = buildResult();
+        writeReport("cancelled", result);
+        return Result16.ok(result);
+      }
+    } else if (options.interactive === false && options.yes !== true) {
+      const result = buildResult();
+      writeReport("skipped_non_interactive", result);
+      return Result16.ok(result);
     }
-    applied = true;
-    appliedPackages.push(...packagesToApply.map((a) => a.name));
-  }
-  let guidesData = options.guide === true ? buildMigrationGuides(packages, migrationsDir) : undefined;
-  if (guidesData !== undefined && options.guidePackages !== undefined && options.guidePackages.length > 0) {
-    const filterSet = new Set(options.guidePackages);
-    guidesData = guidesData.filter((g) => filterSet.has(g.packageName));
+    let applied = false;
+    const appliedPackages = [];
+    if (packagesToApply.length > 0) {
+      if (scan.workspaceRoot !== null) {
+        const applyResult = await applyUpdatesToWorkspace(scan.manifestPaths, scan.manifestsByPackage, packagesToApply);
+        if (applyResult.isErr()) {
+          const failureResult = buildResult();
+          writeReport("failed", failureResult, applyResult.error);
+          return applyResult;
+        }
+        const installResult = await runInstall(installRoot);
+        if (installResult.isErr()) {
+          const failureResult = buildResult();
+          writeReport("failed", failureResult, installResult.error);
+          return installResult;
+        }
+      } else {
+        const applyResult = await applyUpdates(cwd, packagesToApply);
+        if (applyResult.isErr()) {
+          const failureResult = buildResult();
+          writeReport("failed", failureResult, applyResult.error);
+          return applyResult;
+        }
+      }
+      applied = true;
+      appliedPackages.push(...packagesToApply.map((a) => a.name));
+    }
+    let codemodSummary;
+    if (applied && options.noCodemods !== true && migrationsDir !== null) {
+      const codemodsDir = findCodemodsDir(cwd);
+      if (codemodsDir !== null) {
+        const allChangedFiles = [];
+        const allErrors = [];
+        let codemodCount = 0;
+        for (const pkg of packagesToApply) {
+          const shortName = pkg.name.replace("@outfitter/", "");
+          const codemods = discoverCodemods(migrationsDir, codemodsDir, shortName, installedMap.get(pkg.name) ?? "0.0.0", pkg.latestVersion);
+          for (const codemod of codemods) {
+            const codemodResult = await runCodemod(codemod.absolutePath, codemodTargetDir, false);
+            codemodCount++;
+            if (codemodResult.isOk()) {
+              allChangedFiles.push(...codemodResult.value.changedFiles);
+              allErrors.push(...codemodResult.value.errors);
+            } else {
+              allErrors.push(codemodResult.error.message);
+            }
+          }
+        }
+        if (codemodCount > 0) {
+          codemodSummary = {
+            codemodCount,
+            changedFiles: allChangedFiles,
+            errors: allErrors
+          };
+        }
+      }
+    }
+    const finalResult = buildResult({
+      applied,
+      appliedPackages,
+      ...codemodSummary !== undefined ? { codemods: codemodSummary } : {}
+    });
+    writeReport("applied", finalResult);
+    return Result16.ok(finalResult);
+  } catch (error) {
+    const normalizedError = error && typeof error === "object" && "category" in error && "message" in error ? error : InternalError4.create("Unexpected error in outfitter upgrade", {
+      cwd,
+      error: error instanceof Error ? error.message : String(error)
+    });
+    writeReport("failed", emptyResult, normalizedError);
+    return Result16.err(normalizedError);
   }
-  return Result15.ok({
-    packages,
-    total: packages.length,
-    updatesAvailable,
-    hasBreaking,
-    applied,
-    appliedPackages,
-    skippedBreaking,
-    ...guidesData !== undefined ? { guides: guidesData } : {}
-  });
 }
-async function printUpdateResults(result, options) {
+async function printUpgradeResults(result, options) {
   const structuredMode = resolveStructuredOutputMode(options?.mode);
   if (structuredMode) {
     await output9(result, { mode: structuredMode });
     return;
   }
   const theme = createTheme3();
-  const lines = ["", "Outfitter Update", "", "=".repeat(60)];
+  const lines = ["", "Outfitter Upgrade", "", "=".repeat(60)];
   if (result.packages.length === 0) {
     lines.push("No @outfitter/* packages found in package.json.");
     await output9(lines, { mode: "human" });
@@ -4549,39 +4929,60 @@ async function printUpdateResults(result, options) {
     const breakingApplied = result.appliedPackages.filter((name) => result.packages.some((p) => p.name === name && p.breaking));
     const nonBreakingApplied = result.appliedPackages.filter((name) => !result.packages.some((p) => p.name === name && p.breaking));
     if (nonBreakingApplied.length > 0) {
-      lines.push(theme.success(`Applied ${nonBreakingApplied.length} non-breaking update(s):`));
+      lines.push(theme.success(`Applied ${nonBreakingApplied.length} non-breaking upgrade(s):`));
       for (const name of nonBreakingApplied) {
         lines.push(`  - ${name}`);
       }
       lines.push("");
     }
     if (breakingApplied.length > 0) {
-      lines.push(theme.error(`Applied ${breakingApplied.length} breaking update(s):`));
+      lines.push(theme.error(`Applied ${breakingApplied.length} breaking upgrade(s):`));
       for (const name of breakingApplied) {
         const pkg = result.packages.find((p) => p.name === name);
         lines.push(`  - ${name} (${pkg?.current} -> ${pkg?.latest})`);
       }
-      lines.push("", theme.muted("Review migration guides: 'outfitter update --guide'"));
+      lines.push("", theme.muted("Review migration guides: 'outfitter upgrade --guide'"));
       lines.push("");
     }
-  } else if (options?.applied !== undefined && options.applied === false) {
-    if (result.updatesAvailable === 0) {
-      lines.push(theme.success("All packages are up to date. Nothing to apply."));
-    } else if (result.appliedPackages.length === 0 && result.skippedBreaking.length > 0) {
-      lines.push(theme.muted("No non-breaking updates to apply. All available updates contain breaking changes."));
-    }
   }
-  if (result.skippedBreaking.length > 0 && result.applied) {
-    lines.push(theme.error(`Skipped ${result.skippedBreaking.length} breaking update(s):`));
+  if (result.skippedBreaking.length > 0 && options?.all !== true) {
+    if (result.applied) {
+      lines.push(theme.error(`Skipped ${result.skippedBreaking.length} breaking upgrade(s):`));
+    } else {
+      lines.push("  Excluded (breaking):");
+    }
     for (const name of result.skippedBreaking) {
-      lines.push(`  - ${name}`);
+      const pkg = result.packages.find((p) => p.name === name);
+      const codemodHint = pkg?.breaking ? "(migration guide)" : "";
+      lines.push(`    ${name.padEnd(24)} ${(pkg?.current ?? "").padEnd(8)} -> ${(pkg?.latest ?? "").padEnd(8)} ${codemodHint}`.trimEnd());
+    }
+    lines.push("", theme.muted("  Use --all to include breaking changes"));
+    lines.push("");
+  }
+  if (result.codemods !== undefined) {
+    const uniqueChangedFiles = [
+      ...new Set(result.codemods.changedFiles)
+    ].sort();
+    lines.push(theme.info(`Ran ${result.codemods.codemodCount} codemod(s).`));
+    if (uniqueChangedFiles.length > 0) {
+      lines.push(theme.success(`Codemods changed ${uniqueChangedFiles.length} file(s):`));
+      for (const file of uniqueChangedFiles) {
+        lines.push(`  - ${file}`);
+      }
+    }
+    if (result.codemods.errors.length > 0) {
+      lines.push(theme.error(`Codemod errors (${result.codemods.errors.length}):`));
+      for (const error of result.codemods.errors) {
+        lines.push(`  - ${error}`);
+      }
     }
-    lines.push("", theme.muted("Use 'outfitter update --apply --breaking' to include breaking updates."));
     lines.push("");
   }
   if (!result.applied) {
-    if (result.updatesAvailable > 0) {
-      lines.push(theme.muted("Run 'outfitter update --guide' for migration instructions."));
+    if (options?.dryRun) {
+      lines.push(theme.muted("Dry run — no changes applied."));
+    } else if (result.updatesAvailable > 0) {
+      lines.push(theme.muted("Run 'outfitter upgrade --guide' for migration instructions."));
     } else {
       lines.push(theme.success("All packages are up to date."));
     }
@@ -4620,6 +5021,58 @@ async function printUpdateResults(result, options) {
   }
   await output9(lines, { mode: "human" });
 }
+function writeUpgradeReport(cwd, result, meta) {
+  const reportsDir = join14(cwd, ".outfitter", "reports");
+  mkdirSync6(reportsDir, { recursive: true });
+  const finishedAtIso = new Date().toISOString();
+  const errorContext = meta.error !== undefined && "context" in meta.error && meta.error.context !== undefined && typeof meta.error.context === "object" ? meta.error.context : undefined;
+  const report = {
+    $schema: "https://outfitter.dev/reports/upgrade/v1",
+    status: meta.status,
+    checkedAt: finishedAtIso,
+    startedAt: meta.startedAt.toISOString(),
+    finishedAt: finishedAtIso,
+    cwd,
+    workspaceRoot: meta.workspaceRoot,
+    flags: {
+      dryRun: meta.options.dryRun === true,
+      yes: meta.options.yes === true,
+      interactive: meta.options.interactive !== false,
+      all: meta.options.all === true,
+      noCodemods: meta.options.noCodemods === true,
+      outputMode: meta.options.outputMode ?? null
+    },
+    applied: result.applied,
+    summary: {
+      total: result.total,
+      available: result.updatesAvailable,
+      breaking: result.packages.filter((p) => p.breaking).length,
+      applied: result.appliedPackages.length
+    },
+    packages: result.packages,
+    excluded: {
+      breaking: result.skippedBreaking
+    },
+    ...result.codemods !== undefined ? { codemods: result.codemods } : {},
+    ...meta.error !== undefined ? {
+      error: {
+        message: meta.error.message,
+        category: meta.error.category,
+        ...errorContext !== undefined ? { context: errorContext } : {}
+      }
+    } : {}
+  };
+  writeFileSync7(join14(reportsDir, "upgrade.json"), JSON.stringify(report, null, 2));
+}
+function writeUpgradeReportSafely(cwd, result, meta) {
+  try {
+    writeUpgradeReport(cwd, result, meta);
+  } catch (error) {
+    const reason = error instanceof Error ? error.message : String(error);
+    process.stderr.write(`[outfitter upgrade] Failed to write report: ${reason}
+`);
+  }
+}
 
 // src/actions.ts
 var outputModeSchema = z2.enum(["human", "json", "jsonl"]).default("human");
@@ -4688,6 +5141,7 @@ function resolveLocalFlag(flags) {
 }
 function resolveInitOptions(context, presetOverride) {
   const flags = context.flags;
+  const { force, dryRun, yes } = initSharedFlags.resolve(context);
   const targetDir = context.args[0] ?? process.cwd();
   const name = resolveStringFlag(flags.name);
   const bin = resolveStringFlag(flags.bin);
@@ -4696,11 +5150,8 @@ function resolveInitOptions(context, presetOverride) {
   const structure = resolveStringFlag(flags.structure);
   const workspaceName = resolveStringFlag(flags.workspaceName);
   const local = resolveLocalFlag(flags);
-  const force = Boolean(flags.force);
   const withBlocks = resolveStringFlag(flags.with);
   const noTooling = resolveNoToolingFlag(flags);
-  const yes = Boolean(flags.yes);
-  const dryRun = Boolean(flags.dryRun ?? context.flags["dry-run"]);
   const skipInstall = Boolean(flags.skipInstall ?? context.flags["skip-install"]);
   const skipGit = Boolean(flags.skipGit ?? context.flags["skip-git"]);
   const skipCommit = Boolean(flags.skipCommit ?? context.flags["skip-commit"]);
@@ -4735,6 +5186,7 @@ function resolveInitOptions(context, presetOverride) {
 }
 function resolveScaffoldOptions(context) {
   const flags = context.flags;
+  const { force, dryRun } = scaffoldSharedFlags.resolve(context);
   const outputMode = resolveOutputModeFromContext(context.flags);
   const noTooling = resolveNoToolingFlag(flags);
   const local = resolveLocalFlag(flags);
@@ -4748,9 +5200,9 @@ function resolveScaffoldOptions(context) {
   return {
     target: String(context.args[0] ?? ""),
     name: resolveStringFlag(context.args[1]),
-    force: Boolean(flags.force),
+    force,
     skipInstall: Boolean(flags.skipInstall ?? context.flags["skip-install"]),
-    dryRun: Boolean(flags.dryRun ?? context.flags["dry-run"]),
+    dryRun,
     ...local !== undefined ? { local } : {},
     with: resolveStringFlag(flags.with),
     ...noTooling !== undefined ? { noTooling } : {},
@@ -4760,11 +5212,11 @@ function resolveScaffoldOptions(context) {
   };
 }
 function resolveMigrateKitOptions(context) {
-  const flags = context.flags;
+  const { dryRun } = migrateKitSharedFlags.resolve(context);
   const outputMode = resolveOutputModeFromContext(context.flags);
   return {
     targetDir: context.args[0] ?? process.cwd(),
-    dryRun: Boolean(flags.dryRun || context.flags["dry-run"]),
+    dryRun,
     outputMode
   };
 }
@@ -4777,11 +5229,6 @@ var commonInitOptions = [
     flags: "-b, --bin <name>",
     description: "Binary name (defaults to project name)"
   },
-  {
-    flags: "-f, --force",
-    description: "Overwrite existing files",
-    defaultValue: false
-  },
   {
     flags: "--local",
     description: "Use workspace:* for @outfitter dependencies"
@@ -4803,12 +5250,19 @@ var templateOption = {
   flags: "-t, --template <template>",
   description: "Template to use (deprecated, use --preset)"
 };
+var initSharedFlags = actionCliPresets(forcePreset(), dryRunPreset(), booleanFlagPreset({
+  id: "initYes",
+  key: "yes",
+  flags: "-y, --yes",
+  description: "Skip prompts and use defaults for missing values"
+}));
 function createInitAction(options) {
   const presetOption = {
     flags: "-p, --preset <preset>",
     description: "Preset to use (minimal, cli, mcp, daemon)"
   };
   const initOptions = [...commonInitOptions];
+  initOptions.push(...initSharedFlags.options);
   initOptions.push({
     flags: "-s, --structure <mode>",
     description: "Project structure (single|workspace)"
@@ -4817,16 +5271,6 @@ function createInitAction(options) {
     flags: "--workspace-name <name>",
     description: "Workspace root package name"
   });
-  initOptions.push({
-    flags: "-y, --yes",
-    description: "Skip prompts and use defaults for missing values",
-    defaultValue: false
-  });
-  initOptions.push({
-    flags: "--dry-run",
-    description: "Preview changes without writing files",
-    defaultValue: false
-  });
   initOptions.push({
     flags: "--skip-install",
     description: "Skip bun install",
@@ -4868,16 +5312,19 @@ function createInitAction(options) {
       const { outputMode, ...initInput } = input;
       const result = await runInit(initInput);
       if (result.isErr()) {
-        return Result16.err(new InternalError4({
+        return Result17.err(new InternalError5({
           message: result.error.message,
           context: { action: options.id }
         }));
       }
       await printInitResults(result.value, { mode: outputMode });
-      return Result16.ok(result.value);
+      return Result17.ok(result.value);
     }
   });
 }
+var scaffoldSharedFlags = actionCliPresets(forcePreset(), dryRunPreset());
+var addSharedFlags = actionCliPresets(forcePreset(), dryRunPreset());
+var migrateKitSharedFlags = actionCliPresets(dryRunPreset());
 var createAction = defineAction({
   id: "create",
   description: "Removed - use 'outfitter init' instead",
@@ -4889,7 +5336,7 @@ var createAction = defineAction({
     options: [],
     mapInput: () => ({})
   },
-  handler: async () => Result16.err(new InternalError4({
+  handler: async () => Result17.err(new InternalError5({
     message: [
       "The 'create' command has been removed.",
       "",
@@ -4914,21 +5361,12 @@ var scaffoldAction = defineAction({
     command: "scaffold <target> [name]",
     description: "Add a capability (cli, mcp, daemon, lib, ...) to an existing project",
     options: [
-      {
-        flags: "-f, --force",
-        description: "Overwrite existing files",
-        defaultValue: false
-      },
+      ...scaffoldSharedFlags.options,
       {
         flags: "--skip-install",
         description: "Skip bun install",
         defaultValue: false
       },
-      {
-        flags: "--dry-run",
-        description: "Preview changes without executing",
-        defaultValue: false
-      },
       {
         flags: "--with <blocks>",
         description: "Comma-separated tooling blocks to add"
@@ -4952,13 +5390,13 @@ var scaffoldAction = defineAction({
     const { outputMode, ...scaffoldInput } = input;
     const result = await runScaffold(scaffoldInput);
     if (result.isErr()) {
-      return Result16.err(new InternalError4({
+      return Result17.err(new InternalError5({
         message: result.error.message,
         context: { action: "scaffold" }
       }));
     }
     await printScaffoldResults(result.value, { mode: outputMode });
-    return Result16.ok(result.value);
+    return Result17.ok(result.value);
   }
 });
 var demoInputSchema = z2.object({
@@ -5004,9 +5442,9 @@ var demoAction = defineAction({
       if (result.exitCode !== 0) {
         process.exit(result.exitCode);
       }
-      return Result16.ok(result);
+      return Result17.ok(result);
     } catch (error) {
-      return Result16.err(new InternalError4({
+      return Result17.err(new InternalError5({
         message: error instanceof Error ? error.message : "Failed to run demo",
         context: { action: "demo" }
       }));
@@ -5036,7 +5474,7 @@ var doctorAction = defineAction({
     if (result.exitCode !== 0) {
       process.exit(result.exitCode);
     }
-    return Result16.ok(result);
+    return Result17.ok(result);
   }
 });
 var addInputSchema = z2.object({
@@ -5055,24 +5493,14 @@ var addAction = defineAction({
     group: "add",
     command: "<block>",
     description: "Add a block from the registry (claude, biome, lefthook, bootstrap, scaffolding)",
-    options: [
-      {
-        flags: "-f, --force",
-        description: "Overwrite existing files",
-        defaultValue: false
-      },
-      {
-        flags: "--dry-run",
-        description: "Show what would be added without making changes",
-        defaultValue: false
-      }
-    ],
+    options: [...addSharedFlags.options],
     mapInput: (context) => {
       const outputMode = resolveOutputModeFromContext(context.flags);
+      const { force, dryRun } = addSharedFlags.resolve(context);
       return {
         block: context.args[0],
-        force: Boolean(context.flags["force"]),
-        dryRun: Boolean(context.flags["dry-run"] ?? context.flags["dryRun"]),
+        force,
+        dryRun,
         cwd: process.cwd(),
         outputMode
       };
@@ -5082,13 +5510,13 @@ var addAction = defineAction({
     const { outputMode, ...addInput } = input;
     const result = await runAdd(addInput);
     if (result.isErr()) {
-      return Result16.err(new InternalError4({
+      return Result17.err(new InternalError5({
         message: result.error.message,
         context: { action: "add" }
       }));
     }
     await printAddResults(result.value, addInput.dryRun, { mode: outputMode });
-    return Result16.ok(result.value);
+    return Result17.ok(result.value);
   }
 });
 var listBlocksAction = defineAction({
@@ -5110,7 +5538,7 @@ var listBlocksAction = defineAction({
   handler: async (input) => {
     const result = listBlocks();
     if (result.isErr()) {
-      return Result16.err(new InternalError4({
+      return Result17.err(new InternalError5({
         message: result.error.message,
         context: { action: "add.list" }
       }));
@@ -5125,7 +5553,7 @@ var listBlocksAction = defineAction({
       ];
       await output10(lines, { mode: "human" });
     }
-    return Result16.ok({ blocks: result.value });
+    return Result17.ok({ blocks: result.value });
   }
 });
 var checkInputSchema = z2.object({
@@ -5163,7 +5591,7 @@ var checkAction = defineAction({
       const outputMode = resolveOutputModeFromContext(context.flags);
       const { verbose } = checkVerbose.resolve(context.flags);
       const { cwd: rawCwd } = checkCwd.resolve(context.flags);
-      const cwd = resolve10(process.cwd(), rawCwd);
+      const cwd = resolve11(process.cwd(), rawCwd);
       const block = resolveStringFlag(context.flags["block"]);
       return {
         cwd,
@@ -5179,7 +5607,7 @@ var checkAction = defineAction({
     const effectiveMode = ci ? "json" : outputMode;
     const result = await runCheck(checkInput);
     if (result.isErr()) {
-      return Result16.err(new InternalError4({
+      return Result17.err(new InternalError5({
         message: result.error.message,
         context: { action: "check" }
       }));
@@ -5191,80 +5619,100 @@ var checkAction = defineAction({
     if (result.value.driftedCount > 0 || result.value.missingCount > 0) {
       process.exit(1);
     }
-    return Result16.ok(result.value);
+    return Result17.ok(result.value);
   }
 });
-var updateInputSchema = z2.object({
+var upgradeInputSchema = z2.object({
   cwd: z2.string(),
   guide: z2.boolean(),
   guidePackages: z2.array(z2.string()).optional(),
-  apply: z2.boolean(),
-  breaking: z2.boolean(),
+  dryRun: z2.boolean(),
+  yes: z2.boolean(),
+  interactive: z2.boolean(),
+  all: z2.boolean(),
+  noCodemods: z2.boolean(),
   outputMode: outputModeSchema
 });
-var updateAction = defineAction({
-  id: "update",
+var upgradeCwd = cwdPreset();
+var upgradeDryRun = dryRunPreset();
+var upgradeInteraction = interactionPreset();
+var upgradeAll = booleanFlagPreset({
+  id: "upgradeAll",
+  key: "all",
+  flags: "--all",
+  description: "Include breaking changes in the upgrade"
+});
+var upgradeNoCodemods = booleanFlagPreset({
+  id: "upgradeNoCodemods",
+  key: "noCodemods",
+  flags: "--no-codemods",
+  description: "Skip automatic codemod execution during upgrade",
+  sources: ["noCodemods", "no-codemods"],
+  negatedSources: ["codemods"]
+});
+var upgradeGuide = booleanFlagPreset({
+  id: "upgradeGuide",
+  key: "guide",
+  flags: "--guide",
+  description: "Show migration instructions for available updates. Pass package names to filter."
+});
+var upgradeFlags = actionCliPresets(upgradeCwd, upgradeDryRun, upgradeInteraction, upgradeAll, upgradeNoCodemods, upgradeGuide);
+var upgradeAction = defineAction({
+  id: "upgrade",
   description: "Check for @outfitter/* package updates and migration guidance",
   surfaces: ["cli"],
-  input: updateInputSchema,
+  input: upgradeInputSchema,
   cli: {
-    command: "update [packages...]",
+    command: "upgrade [packages...]",
     description: "Check for @outfitter/* package updates and migration guidance",
-    options: [
-      {
-        flags: "--guide",
-        description: "Show migration instructions for available updates. Pass package names to filter.",
-        defaultValue: false
-      },
-      {
-        flags: "--apply",
-        description: "Apply non-breaking updates to package.json and run bun install",
-        defaultValue: false
-      },
-      {
-        flags: "--breaking",
-        description: "Include breaking updates when used with --apply",
-        defaultValue: false
-      },
-      {
-        flags: "--cwd <path>",
-        description: "Working directory (defaults to current directory)"
-      }
-    ],
+    options: [...upgradeFlags.options],
     mapInput: (context) => {
       const outputMode = resolveOutputModeFromContext(context.flags);
-      const cwd = typeof context.flags["cwd"] === "string" ? resolve10(process.cwd(), context.flags["cwd"]) : process.cwd();
+      const {
+        cwd: rawCwd,
+        dryRun,
+        interactive,
+        yes,
+        all,
+        noCodemods,
+        guide
+      } = upgradeFlags.resolve(context);
+      const cwd = resolve11(process.cwd(), rawCwd);
       const guidePackages = context.args.length > 0 ? context.args : undefined;
       return {
         cwd,
-        guide: Boolean(context.flags["guide"]),
+        guide,
         ...guidePackages !== undefined ? { guidePackages } : {},
-        apply: Boolean(context.flags["apply"]),
-        breaking: Boolean(context.flags["breaking"]),
+        dryRun,
+        yes,
+        interactive,
+        all,
+        noCodemods,
         outputMode
       };
     }
   },
   handler: async (input) => {
-    const { outputMode, guidePackages, ...updateInput } = input;
-    const result = await runUpdate({
-      ...updateInput,
+    const { outputMode, guidePackages, ...upgradeInput } = input;
+    const result = await runUpgrade({
+      ...upgradeInput,
+      outputMode,
       ...guidePackages !== undefined ? { guidePackages } : {}
     });
     if (result.isErr()) {
-      return Result16.err(new InternalError4({
+      return Result17.err(new InternalError5({
         message: result.error.message,
-        context: { action: "update" }
+        context: { action: "upgrade" }
       }));
     }
-    await printUpdateResults(result.value, {
+    await printUpgradeResults(result.value, {
       mode: outputMode,
-      guide: updateInput.guide,
-      cwd: updateInput.cwd,
-      applied: updateInput.apply ? result.value.applied : undefined,
-      breaking: updateInput.breaking
+      guide: upgradeInput.guide,
+      cwd: upgradeInput.cwd,
+      dryRun: upgradeInput.dryRun,
+      all: upgradeInput.all
     });
-    return Result16.ok(result.value);
+    return Result17.ok(result.value);
   }
 });
 var migrateKitAction = defineAction({
@@ -5276,26 +5724,20 @@ var migrateKitAction = defineAction({
     group: "migrate",
     command: "kit [directory]",
     description: "Migrate foundation imports and dependencies to @outfitter/kit",
-    options: [
-      {
-        flags: "--dry-run",
-        description: "Preview changes without writing files",
-        defaultValue: false
-      }
-    ],
+    options: [...migrateKitSharedFlags.options],
     mapInput: resolveMigrateKitOptions
   },
   handler: async (input) => {
     const { outputMode, ...migrateInput } = input;
     const result = await runMigrateKit(migrateInput);
     if (result.isErr()) {
-      return Result16.err(new InternalError4({
+      return Result17.err(new InternalError5({
         message: result.error.message,
         context: { action: "migrate.kit" }
       }));
     }
     await printMigrateKitResults(result.value, { mode: outputMode });
-    return Result16.ok(result.value);
+    return Result17.ok(result.value);
   }
 });
 var outfitterActions = createActionRegistry().add(createAction).add(scaffoldAction).add(createInitAction({
@@ -5319,29 +5761,40 @@ var outfitterActions = createActionRegistry().add(createAction).add(scaffoldActi
   description: "Create a new daemon project",
   command: "daemon [directory]",
   presetOverride: "daemon"
-})).add(demoAction).add(doctorAction).add(addAction).add(listBlocksAction).add(checkAction).add(migrateKitAction).add(updateAction);
+})).add(demoAction).add(doctorAction).add(addAction).add(listBlocksAction).add(checkAction).add(migrateKitAction).add(upgradeAction);
 
 // src/commands/repo.ts
-import { existsSync as existsSync14 } from "node:fs";
+import { existsSync as existsSync15 } from "node:fs";
 import { createRequire as createRequire3 } from "node:module";
-import { dirname as dirname9, join as join15, resolve as resolve11 } from "node:path";
+import { dirname as dirname9, join as join16 } from "node:path";
+import {
+  booleanFlagPreset as booleanFlagPreset2,
+  composePresets,
+  cwdPreset as cwdPreset2,
+  stringListFlagPreset
+} from "@outfitter/cli/flags";
+import {
+  resolveDocsCliOptions,
+  withDocsCommonOptions,
+  withDocsExportOptions
+} from "@outfitter/docs";
 import { Command } from "commander";
 
 // src/commands/docs-module-loader.ts
-import { existsSync as existsSync13 } from "node:fs";
+import { existsSync as existsSync14 } from "node:fs";
 import { createRequire as createRequire2 } from "node:module";
-import { dirname as dirname8, join as join14 } from "node:path";
+import { dirname as dirname8, join as join15 } from "node:path";
 import { pathToFileURL } from "node:url";
 var require2 = createRequire2(import.meta.url);
 function resolveDocsEntrypoint() {
   const packageJsonPath = require2.resolve("@outfitter/docs/package.json");
   const packageRoot = dirname8(packageJsonPath);
-  const srcEntrypoint = join14(packageRoot, "src", "index.ts");
-  if (existsSync13(srcEntrypoint)) {
+  const srcEntrypoint = join15(packageRoot, "src", "index.ts");
+  if (existsSync14(srcEntrypoint)) {
     return srcEntrypoint;
   }
-  const distEntrypoint = join14(packageRoot, "dist", "index.js");
-  if (existsSync13(distEntrypoint)) {
+  const distEntrypoint = join15(packageRoot, "dist", "index.js");
+  if (existsSync14(distEntrypoint)) {
     return distEntrypoint;
   }
   throw new Error("Unable to resolve @outfitter/docs entrypoint (expected src/index.ts or dist/index.js).");
@@ -5371,21 +5824,15 @@ function getIo(options) {
 `))
   };
 }
-function resolveCwdOption(inputCwd) {
-  if (typeof inputCwd !== "string" || inputCwd.length === 0) {
-    return process.cwd();
-  }
-  return resolve11(process.cwd(), inputCwd);
-}
 function resolveToolingCliEntrypoint() {
   const packageJsonPath = require3.resolve("@outfitter/tooling/package.json");
   const packageRoot = dirname9(packageJsonPath);
-  const srcEntrypoint = join15(packageRoot, "src", "cli", "index.ts");
-  if (existsSync14(srcEntrypoint)) {
+  const srcEntrypoint = join16(packageRoot, "src", "cli", "index.ts");
+  if (existsSync15(srcEntrypoint)) {
     return srcEntrypoint;
   }
-  const distEntrypoint = join15(packageRoot, "dist", "cli", "index.js");
-  if (existsSync14(distEntrypoint)) {
+  const distEntrypoint = join16(packageRoot, "dist", "cli", "index.js");
+  if (existsSync15(distEntrypoint)) {
     return distEntrypoint;
   }
   throw new Error("Unable to resolve @outfitter/tooling CLI entrypoint (expected dist/cli/index.js or src/cli/index.ts).");
@@ -5417,97 +5864,112 @@ function applyExitCode(code) {
     process.exitCode = code;
   }
 }
+function applyPresetOptions(command, preset) {
+  for (const option of preset.options) {
+    command.option(option.flags, option.description, option.defaultValue);
+  }
+  return command;
+}
 function addDocsCheckSubcommand(command, options) {
-  command.command("docs").description("Check whether assembled package docs are in sync").option("--cwd <path>", "Workspace root to operate in").option("--packages-dir <path>", "Packages directory relative to workspace").option("--output-dir <path>", "Output directory relative to workspace").option("--mdx-mode <mode>", "MDX handling mode: strict or lossy").action(async (cmdOptions) => {
-    const code = await options.runDocsCheck({
-      ...cmdOptions,
-      ...cmdOptions.cwd ? { cwd: resolveCwdOption(cmdOptions.cwd) } : {}
-    }, options.io);
+  const docsCheckCommand = command.command("docs").description("Check whether assembled package docs are in sync");
+  withDocsCommonOptions(docsCheckCommand).action(async (cmdOptions) => {
+    const code = await options.runDocsCheck(resolveDocsCliOptions(cmdOptions), options.io);
     applyExitCode(code);
   });
 }
 function addDocsSyncSubcommand(command, options) {
-  command.command("docs").description("Assemble package docs into docs/packages").option("--cwd <path>", "Workspace root to operate in").option("--packages-dir <path>", "Packages directory relative to workspace").option("--output-dir <path>", "Output directory relative to workspace").option("--mdx-mode <mode>", "MDX handling mode: strict or lossy").action(async (cmdOptions) => {
-    const code = await options.runDocsSync({
-      ...cmdOptions,
-      ...cmdOptions.cwd ? { cwd: resolveCwdOption(cmdOptions.cwd) } : {}
-    }, options.io);
+  const docsSyncCommand = command.command("docs").description("Assemble package docs into docs/packages");
+  withDocsCommonOptions(docsSyncCommand).action(async (cmdOptions) => {
+    const code = await options.runDocsSync(resolveDocsCliOptions(cmdOptions), options.io);
     applyExitCode(code);
   });
 }
 function addDocsExportSubcommand(command, options) {
-  command.command("docs").description("Export docs artifacts for packages and LLM targets").option("--cwd <path>", "Workspace root to operate in").option("--packages-dir <path>", "Packages directory relative to workspace").option("--output-dir <path>", "Output directory relative to workspace").option("--mdx-mode <mode>", "MDX handling mode: strict or lossy").option("--llms-file <path>", "llms.txt output path relative to workspace").option("--llms-full-file <path>", "llms-full.txt output path relative to workspace").option("--target <target>", "Export target: packages, llms, llms-full, all", "all").action(async (cmdOptions) => {
-    const code = await options.runDocsExport({
-      ...cmdOptions,
-      ...cmdOptions.cwd ? { cwd: resolveCwdOption(cmdOptions.cwd) } : {}
-    }, options.io);
+  const docsExportCommand = command.command("docs").description("Export docs artifacts for packages and LLM targets");
+  withDocsExportOptions(docsExportCommand).action(async (cmdOptions) => {
+    const code = await options.runDocsExport(resolveDocsCliOptions(cmdOptions), options.io);
     applyExitCode(code);
   });
 }
 function addToolingCheckSubcommands(command, runToolingCommand) {
-  command.command("exports").description("Validate package.json exports match source entry points").option("--json", "Output results as JSON").option("--cwd <path>", "Workspace root to operate in").action(async (cmdOptions) => {
-    const args = [];
-    if (cmdOptions.json) {
-      args.push("--json");
-    }
-    const code = await runToolingCommand({
-      command: "check-exports",
-      args,
-      cwd: resolveCwdOption(cmdOptions.cwd)
-    });
-    applyExitCode(code);
+  const cwdFlag = cwdPreset2();
+  const jsonFlag = booleanFlagPreset2({
+    id: "repo-check-json",
+    key: "json",
+    flags: "--json",
+    description: "Output results as JSON"
   });
-  command.command("readme").description("Validate README import examples match package exports").option("--json", "Output results as JSON").option("--cwd <path>", "Workspace root to operate in").action(async (cmdOptions) => {
-    const args = [];
-    if (cmdOptions.json) {
-      args.push("--json");
-    }
-    const code = await runToolingCommand({
-      command: "check-readme-imports",
-      args,
-      cwd: resolveCwdOption(cmdOptions.cwd)
-    });
-    applyExitCode(code);
+  const skipFlag = booleanFlagPreset2({
+    id: "repo-check-skip",
+    key: "skip",
+    flags: "-s, --skip",
+    description: "Skip changeset check"
   });
-  command.command("registry").description("Validate packages with bunup --filter are registered in bunup.config.ts").option("--cwd <path>", "Workspace root to operate in").action(async (cmdOptions) => {
-    const code = await runToolingCommand({
-      command: "check-bunup-registry",
-      args: [],
-      cwd: resolveCwdOption(cmdOptions.cwd)
-    });
-    applyExitCode(code);
+  const pathsFlag = stringListFlagPreset({
+    id: "repo-check-paths",
+    key: "paths",
+    flags: "--paths <paths...>",
+    description: "Limit check to specific paths"
   });
-  command.command("changeset").description("Validate PRs touching package source include a changeset").option("-s, --skip", "Skip changeset check").option("--cwd <path>", "Workspace root to operate in").action(async (cmdOptions) => {
-    const args = [];
-    if (cmdOptions.skip) {
-      args.push("--skip");
-    }
-    const code = await runToolingCommand({
-      command: "check-changeset",
-      args,
-      cwd: resolveCwdOption(cmdOptions.cwd)
+  const toolingWithCwd = composePresets(cwdFlag);
+  const toolingWithJsonAndCwd = composePresets(jsonFlag, cwdFlag);
+  const toolingWithSkipAndCwd = composePresets(skipFlag, cwdFlag);
+  const toolingWithPathsAndCwd = composePresets(pathsFlag, cwdFlag);
+  function registerToolingCheckSubcommand(config) {
+    const subcommand = command.command(config.name).description(config.description);
+    applyPresetOptions(subcommand, config.preset);
+    subcommand.action(async (cmdOptions) => {
+      const resolved = config.preset.resolve(cmdOptions);
+      const cwd = resolveDocsCliOptions({ cwd: resolved.cwd }).cwd || process.cwd();
+      const code = await runToolingCommand({
+        command: config.toolingCommand,
+        args: config.buildArgs(resolved),
+        cwd
+      });
+      applyExitCode(code);
     });
-    applyExitCode(code);
+  }
+  registerToolingCheckSubcommand({
+    name: "exports",
+    description: "Validate package.json exports match source entry points",
+    toolingCommand: "check-exports",
+    preset: toolingWithJsonAndCwd,
+    buildArgs: (resolved) => resolved["json"] ? ["--json"] : []
   });
-  command.command("tree").description("Assert working tree is clean (no modified or untracked files)").option("--paths <paths...>", "Limit check to specific paths").option("--cwd <path>", "Workspace root to operate in").action(async (cmdOptions) => {
-    const args = [];
-    if (Array.isArray(cmdOptions.paths) && cmdOptions.paths.length > 0) {
-      args.push("--paths", ...cmdOptions.paths);
-    }
-    const code = await runToolingCommand({
-      command: "check-clean-tree",
-      args,
-      cwd: resolveCwdOption(cmdOptions.cwd)
-    });
-    applyExitCode(code);
+  registerToolingCheckSubcommand({
+    name: "readme",
+    description: "Validate README import examples match package exports",
+    toolingCommand: "check-readme-imports",
+    preset: toolingWithJsonAndCwd,
+    buildArgs: (resolved) => resolved["json"] ? ["--json"] : []
   });
-  command.command("boundary-invocations").description("Validate root/app scripts do not execute packages/*/src entrypoints directly").option("--cwd <path>", "Workspace root to operate in").action(async (cmdOptions) => {
-    const code = await runToolingCommand({
-      command: "check-boundary-invocations",
-      args: [],
-      cwd: resolveCwdOption(cmdOptions.cwd)
-    });
-    applyExitCode(code);
+  registerToolingCheckSubcommand({
+    name: "registry",
+    description: "Validate packages with bunup --filter are registered in bunup.config.ts",
+    toolingCommand: "check-bunup-registry",
+    preset: toolingWithCwd,
+    buildArgs: () => []
+  });
+  registerToolingCheckSubcommand({
+    name: "changeset",
+    description: "Validate PRs touching package source include a changeset",
+    toolingCommand: "check-changeset",
+    preset: toolingWithSkipAndCwd,
+    buildArgs: (resolved) => resolved["skip"] ? ["--skip"] : []
+  });
+  registerToolingCheckSubcommand({
+    name: "tree",
+    description: "Assert working tree is clean (no modified or untracked files)",
+    toolingCommand: "check-clean-tree",
+    preset: toolingWithPathsAndCwd,
+    buildArgs: (resolved) => Array.isArray(resolved["paths"]) && resolved["paths"].length > 0 ? ["--paths", ...resolved["paths"]] : []
+  });
+  registerToolingCheckSubcommand({
+    name: "boundary-invocations",
+    description: "Validate root/app scripts do not execute packages/*/src entrypoints directly",
+    toolingCommand: "check-boundary-invocations",
+    preset: toolingWithCwd,
+    buildArgs: () => []
   });
 }
 function createRepoCommand(options) {