@ai-driven-dev/cli 3.1.0 → 3.1.2

package/dist/cli.js

@@ -71,7 +71,8 @@ var init_prompter_adapter = __esm({
             choices: choices.map((c) => ({
               name: c.name,
               value: c.value,
-              disabled: c.disabled === true ? "Disabled" : c.disabled || false
+              disabled: c.disabled === true ? "Disabled" : c.disabled || false,
+              description: c.description
             }))
           },
           this.context
@@ -133,6 +134,7 @@ var init_sync_status_use_case = __esm({
 });
 
 // src/cli.ts
+import { spawn } from "child_process";
 import { platform as platform2 } from "os";
 import { Command as Command3 } from "commander";
 
@@ -1430,7 +1432,7 @@ var cursorToolConfig = {
   toolSuffix: TOOL_SUFFIX3,
   signalDir: ".cursor/commands",
   rewriteContent(content, docsDir) {
-    return baseRewriteContent(content, DIRECTORY3, docsDir).replace(/(@\.cursor\/commands\/)(\d+)[_-][^/]+\/([^\s]+)/g, "$1aidd/$2/$3").replace(/(@\.cursor\/rules\/[^\s]+)\.md\b/g, "$1.mdc");
+    return baseRewriteContent(content, DIRECTORY3, docsDir).replace(/(@?)\.cursor\/commands\/(\d+)[_-][^/]+\/([^\s]+)/g, "$1.cursor/commands/aidd/$2/$3").replace(/(@\.cursor\/rules\/[^\s]+)\.md\b/g, "$1.mdc");
   },
   reverseRewriteContent(content, docsDir) {
     return baseReverseRewriteContent(
@@ -1541,6 +1543,14 @@ var ConfigConflictError = class extends Error {
     this.name = "ConfigConflictError";
   }
 };
+var UpdateError = class extends Error {
+  constructor() {
+    super(
+      "Update failed. If you saw a 403 error above, ensure your GitHub token includes both repo and read:packages scopes.\nUpdate your token at https://github.com/settings/tokens, then re-run `aidd auth login`."
+    );
+    this.name = "UpdateError";
+  }
+};
 
 // src/domain/tools/opencode.ts
 var DIRECTORY4 = ".opencode/";
@@ -1558,10 +1568,10 @@ function transformMcpToOpencode(content) {
   const mcp = {};
   for (const [name, server] of Object.entries(parsed.mcpServers ?? {})) {
     if ("command" in server) {
-      const { command, args: args2 = [], env } = server;
+      const { command, args = [], env } = server;
       const local = {
         type: "local",
-        command: [command, ...args2],
+        command: [command, ...args],
         enabled: true
       };
       if (env && Object.keys(env).length > 0) local.environment = env;
@@ -1588,8 +1598,8 @@ var opencodeToolConfig = {
   signalDir: ".opencode/commands",
   rewriteContent(content, docsDir) {
     return baseRewriteContent(content, DIRECTORY4, docsDir).replace(
-      /(@\.opencode\/commands\/)(\d+)[_-][^/]+\/([^\s]+)/g,
-      "$1aidd/$2/$3"
+      /(@?)\.opencode\/commands\/(\d+)[_-][^/]+\/([^\s]+)/g,
+      "$1.opencode/commands/aidd/$2/$3"
     );
   },
   reverseRewriteContent(content, docsDir) {
@@ -1938,7 +1948,8 @@ function detectPackageManager() {
   const whichCommand = platform() === "win32" ? "where aidd" : "which aidd";
   let binaryPath;
   try {
-    binaryPath = execSync2(whichCommand, { encoding: "utf8" }).trim();
+    const raw = execSync2(whichCommand, { encoding: "utf8" });
+    binaryPath = raw.trim().split(/\r?\n/)[0].trim();
   } catch {
     throw new Error(
       `Could not detect package manager. Run manually:
@@ -1948,9 +1959,12 @@ function detectPackageManager() {
   ${PM_INSTALL_COMMANDS.bun}`
     );
   }
-  if (binaryPath.includes("/pnpm/")) return { pm: "pnpm", binaryPath };
-  if (binaryPath.includes("/.yarn/")) return { pm: "yarn", binaryPath };
-  if (binaryPath.includes("/bun/")) return { pm: "bun", binaryPath };
+  const normalised = binaryPath.replace(/\\/g, "/");
+  if (normalised.includes("/pnpm/")) return { pm: "pnpm", binaryPath };
+  if (normalised.includes("/.yarn/") || normalised.toLowerCase().includes("/yarn/bin/"))
+    return { pm: "yarn", binaryPath };
+  if (normalised.includes("/.bun/") || normalised.toLowerCase().includes("/bun/bin/"))
+    return { pm: "bun", binaryPath };
   return { pm: "npm", binaryPath };
 }
 function parseCliRelease(body, url) {
@@ -1978,7 +1992,11 @@ var CliUpdaterAdapter = class {
   }
   install() {
     const { pm, binaryPath } = detectPackageManager();
-    execSync2(PM_INSTALL_COMMANDS[pm], { stdio: "inherit" });
+    try {
+      execSync2(PM_INSTALL_COMMANDS[pm], { stdio: "inherit" });
+    } catch {
+      throw new UpdateError();
+    }
     return binaryPath;
   }
 };
@@ -1986,7 +2004,7 @@ var CliUpdaterAdapter = class {
 // package.json
 var package_default = {
   name: "@ai-driven-dev/cli",
-  version: "3.1.0",
+  version: "3.1.2",
   description: "AI-Driven Development CLI \u2014 distribute the AIDD framework across AI coding assistants",
   type: "module",
   main: "dist/cli.js",
@@ -2005,6 +2023,9 @@ var package_default = {
     build: "tsup",
     dev: "tsup --watch",
     test: "pnpm build && vitest run",
+    "test:unit": "vitest run --project=unit",
+    "test:integration": "vitest run --project=integration",
+    "test:e2e": "pnpm build && vitest run --project=e2e",
     "test:watch": "vitest",
     typecheck: "tsc --noEmit",
     lint: "biome check .",
@@ -2142,7 +2163,7 @@ var FileSystemAdapter = class {
     let existing = {};
     try {
       const raw = await readFile3(path, "utf-8");
-      existing = JSON.parse(raw);
+      existing = JSON.parse(stripJsoncComments(raw));
     } catch (err) {
       const code = err.code;
       if (code !== "ENOENT") {
@@ -2208,6 +2229,14 @@ function stripJsoncComments(content) {
       i += 2;
       continue;
     }
+    if (ch === ",") {
+      let j = i + 1;
+      while (j < content.length && " 	\n\r".includes(content[j])) j++;
+      if (content[j] === "}" || content[j] === "]") {
+        i++;
+        continue;
+      }
+    }
     result += ch;
     i++;
   }
@@ -2592,7 +2621,16 @@ var TarExtractor = class {
 };
 
 // src/infrastructure/deps.ts
+var _cache = /* @__PURE__ */ new Map();
+function createMenuDeps(projectRoot) {
+  return {
+    manifestRepo: new ManifestRepositoryAdapter(projectRoot),
+    prompter: process.stdout.isTTY ? new InquirerPrompterAdapter() : new SilentPrompterAdapter()
+  };
+}
 async function createDeps(projectRoot, options, output) {
+  const cached = _cache.get(projectRoot);
+  if (cached !== void 0) return cached;
   const hasher = new HasherAdapter();
   const fs = new FileSystemAdapter(hasher);
   const loader = new FrameworkLoaderAdapter();
@@ -2627,7 +2665,7 @@ async function createDeps(projectRoot, options, output) {
   const git = new GitAdapter(fs);
   const platform3 = new PlatformAdapter();
   const prompter = process.stdout.isTTY ? new InquirerPrompterAdapter() : new SilentPrompterAdapter();
-  return {
+  const deps = {
     fs,
     manifestRepo,
     loader,
@@ -2642,6 +2680,8 @@ async function createDeps(projectRoot, options, output) {
     authReader,
     authStorage
   };
+  _cache.set(projectRoot, deps);
+  return deps;
 }
 
 // src/application/commands/cache.ts
@@ -3619,6 +3659,29 @@ ${invocation} ${SCRIPT_RELATIVE_PATH}
   }
 };
 
+// src/application/use-cases/shared/post-install-pipeline-use-case.ts
+var PostInstallPipelineUseCase = class {
+  constructor(fs, manifestRepo, hasher, git) {
+    this.fs = fs;
+    this.manifestRepo = manifestRepo;
+    this.hasher = hasher;
+    this.git = git;
+  }
+  async execute(options) {
+    const { projectRoot, version, descriptor, contentFiles, manifest, docsDir } = options;
+    await new MemoryScriptUseCase(this.fs, this.hasher, this.git).execute({
+      projectRoot,
+      version,
+      descriptor,
+      contentFiles,
+      manifest
+    });
+    await this.manifestRepo.save(manifest);
+    await new CatalogUseCase(this.fs).execute({ manifest, docsDir, projectRoot });
+    await new GitignoreUseCase(this.fs).execute(projectRoot, [".aidd/cache/"]);
+  }
+};
+
 // src/application/use-cases/install-use-case.ts
 var InstallUseCase = class {
   constructor(fs, manifestRepo, loader, hasher, logger, git, platform3, prompter) {
@@ -3633,100 +3696,115 @@ var InstallUseCase = class {
   }
   async execute(options) {
     const { frameworkPath, version, projectRoot, force = false, repo } = options;
-    const interactive = options.interactive ?? false;
     const manifest = await this.manifestRepo.load();
-    if (manifest === null) {
-      throw new NoManifestError(repo);
-    }
+    if (manifest === null) throw new NoManifestError(repo);
     const docsDir = options.docsDir ?? manifest.docsDir;
-    let toolIds;
-    if (options.all) {
-      toolIds = [...VALID_TOOL_IDS];
-    } else if (options.toolIds !== void 0 && options.toolIds.length > 0) {
-      toolIds = options.toolIds;
-    } else if (interactive && this.prompter !== void 0) {
-      const installedIds = manifest.getInstalledToolIds();
-      const choices = VALID_TOOL_IDS.map(
-        (id) => installedIds.includes(id) ? { name: id, value: id, checked: true, disabled: "(already installed)" } : { name: id, value: id, checked: false }
-      );
-      const selected = await this.prompter.checkbox("Which tools do you want to install?", choices);
-      if (selected.length === 0) throw new Error("No tools selected.");
-      toolIds = selected;
-    } else {
-      throw new Error(
-        `At least one tool ID is required. Valid tools: ${VALID_TOOL_IDS.join(", ")}`
-      );
-    }
+    const toolIds = await this.resolveToolIds(options, manifest);
     assertValidToolIds(toolIds);
     const { descriptor, contentFiles } = await this.loader.loadFromDirectory(
       frameworkPath,
       version
     );
+    const results = await this.installAllTools(
+      toolIds,
+      manifest,
+      descriptor,
+      contentFiles,
+      docsDir,
+      projectRoot,
+      force
+    );
+    await new PostInstallPipelineUseCase(this.fs, this.manifestRepo, this.hasher, this.git).execute(
+      { projectRoot, version, descriptor, contentFiles, manifest, docsDir }
+    );
+    return results;
+  }
+  async installAllTools(toolIds, manifest, descriptor, contentFiles, docsDir, projectRoot, force) {
     const results = [];
     for (const toolId of toolIds) {
-      if (manifest.hasTool(toolId) && !force) {
-        results.push({ toolId, fileCount: 0, files: [], skipped: true, warnings: [] });
-        continue;
-      }
-      const config = getToolConfig(toolId);
-      const warnings = [];
-      if (!manifest.hasTool(toolId) && force) {
-        const toolDir = join19(projectRoot, config.directory);
-        if (await this.fs.fileExists(toolDir)) {
-          warnings.push(
-            `Directory ${config.directory} exists but tool is not in manifest. Files will be overwritten.`
-          );
-        }
-      }
-      this.logger.info(`Generating ${toolId} distribution...`);
-      const generated = await generateDistribution(
+      const result = await this.installOneTool(
+        toolId,
+        manifest,
         descriptor,
-        config,
-        docsDir,
         contentFiles,
-        this.hasher,
-        this.platform,
+        docsDir,
         projectRoot,
-        this.fs
+        force
       );
-      if (manifest.hasTool(toolId)) {
-        const newPaths = new Set(generated.map((f) => f.relativePath));
-        for (const oldFile of manifest.getToolFiles(toolId)) {
-          if (!newPaths.has(oldFile.relativePath)) {
-            await this.fs.deleteFile(join19(projectRoot, oldFile.relativePath));
-          }
-        }
-      }
-      const { files: finalFiles, userFileConflicts } = await this.writeToolFiles(
-        generated,
-        projectRoot,
-        manifest
+      results.push(result);
+    }
+    return results;
+  }
+  /** Resolves which tool IDs to install from the 4-branch selection logic. */
+  async resolveToolIds(options, manifest) {
+    const interactive = options.interactive ?? false;
+    if (options.all) return [...VALID_TOOL_IDS];
+    if (options.toolIds !== void 0 && options.toolIds.length > 0) return options.toolIds;
+    if (interactive && this.prompter !== void 0) return this.promptToolIds(manifest);
+    throw new Error(`At least one tool ID is required. Valid tools: ${VALID_TOOL_IDS.join(", ")}`);
+  }
+  async promptToolIds(manifest) {
+    if (this.prompter === void 0) throw new Error("Prompter is required for interactive mode.");
+    const installedIds = manifest.getInstalledToolIds();
+    const choices = VALID_TOOL_IDS.map(
+      (id) => installedIds.includes(id) ? { name: id, value: id, checked: true, disabled: "(already installed)" } : { name: id, value: id, checked: false }
+    );
+    const selected = await this.prompter.checkbox("Which tools do you want to install?", choices);
+    if (selected.length === 0) throw new Error("No tools selected.");
+    return selected;
+  }
+  /** Installs a single tool and updates the manifest in place. */
+  async installOneTool(toolId, manifest, descriptor, contentFiles, docsDir, projectRoot, force) {
+    if (manifest.hasTool(toolId) && !force) {
+      return { toolId, fileCount: 0, files: [], skipped: true, warnings: [] };
+    }
+    const config = getToolConfig(toolId);
+    const warnings = await this.checkForceWarning(toolId, config, manifest, projectRoot, force);
+    this.logger.info(`Generating ${toolId} distribution...`);
+    const generated = await generateDistribution(
+      descriptor,
+      config,
+      docsDir,
+      contentFiles,
+      this.hasher,
+      this.platform,
+      projectRoot,
+      this.fs
+    );
+    await this.removeStaleFiles(toolId, manifest, generated, projectRoot);
+    const { files: finalFiles, userFileConflicts } = await this.writeToolFiles(
+      generated,
+      projectRoot,
+      manifest
+    );
+    for (const relativePath of userFileConflicts) {
+      warnings.push(
+        `\`${relativePath}\` already exists and was not installed by AIDD \u2014 skipped to preserve user file`
       );
-      for (const relativePath of userFileConflicts) {
+    }
+    manifest.addTool(toolId, descriptor.version, finalFiles);
+    return { toolId, fileCount: generated.length, files: generated, skipped: false, warnings };
+  }
+  async checkForceWarning(toolId, config, manifest, projectRoot, force) {
+    const warnings = [];
+    if (!manifest.hasTool(toolId) && force) {
+      const toolDir = join19(projectRoot, config.directory);
+      if (await this.fs.fileExists(toolDir)) {
         warnings.push(
-          `\`${relativePath}\` already exists and was not installed by AIDD \u2014 skipped to preserve user file`
+          `Directory ${config.directory} exists but tool is not in manifest. Files will be overwritten.`
         );
       }
-      manifest.addTool(toolId, descriptor.version, finalFiles);
-      results.push({
-        toolId,
-        fileCount: generated.length,
-        files: generated,
-        skipped: false,
-        warnings
-      });
     }
-    await new MemoryScriptUseCase(this.fs, this.hasher, this.git).execute({
-      projectRoot,
-      version,
-      descriptor,
-      contentFiles,
-      manifest
-    });
-    await this.manifestRepo.save(manifest);
-    await new CatalogUseCase(this.fs).execute({ manifest, docsDir, projectRoot });
-    await new GitignoreUseCase(this.fs).execute(projectRoot, [".aidd/cache/"]);
-    return results;
+    return warnings;
+  }
+  async removeStaleFiles(toolId, manifest, generated, projectRoot) {
+    if (!manifest.hasTool(toolId)) return;
+    const newPaths = new Set(generated.map((f) => f.relativePath));
+    for (const oldFile of manifest.getToolFiles(toolId)) {
+      if (!newPaths.has(oldFile.relativePath)) {
+        await this.fs.deleteFile(join19(projectRoot, oldFile.relativePath));
+      }
+    }
   }
   async writeToolFiles(generated, projectRoot, manifest) {
     const filesByPath = /* @__PURE__ */ new Map();
@@ -3922,14 +4000,14 @@ function buildDocsDistribution(docsFiles, docsDir, hasher) {
 
 // src/application/use-cases/restore-use-case.ts
 var RestoreUseCase = class {
-  constructor(fs, manifestRepo, loader, hasher, logger, prompter, platform3) {
+  constructor(fs, manifestRepo, loader, hasher, logger, platform3, prompter) {
     this.fs = fs;
     this.manifestRepo = manifestRepo;
     this.loader = loader;
     this.hasher = hasher;
     this.logger = logger;
-    this.prompter = prompter;
     this.platform = platform3;
+    this.prompter = prompter;
   }
   async execute(options) {
     const {
@@ -3942,67 +4020,136 @@ var RestoreUseCase = class {
       repo
     } = options;
     const docsOnly = options.docsOnly ?? false;
-    const fileFilter = buildFileFilter(options.files);
     const manifest = options.manifest ?? await this.manifestRepo.load();
     if (manifest === null) throw new NoManifestError(repo);
-    const toolIds = docsOnly ? [] : options.toolIds && options.toolIds.length > 0 ? options.toolIds : manifest.getInstalledToolIds();
     const { descriptor, contentFiles, docsFiles } = await this.loader.loadFromDirectory(
       frameworkPath,
       version
     );
+    const fileFilter = buildFileFilter(options.files);
+    return this.executeRestore({
+      options,
+      docsOnly,
+      manifest,
+      descriptor,
+      contentFiles,
+      docsFiles,
+      docsDir,
+      projectRoot,
+      version,
+      force,
+      interactive,
+      fileFilter
+    });
+  }
+  async executeRestore(ctx) {
+    const {
+      options,
+      docsOnly,
+      manifest,
+      descriptor,
+      contentFiles,
+      docsFiles,
+      docsDir,
+      projectRoot,
+      version,
+      force,
+      interactive,
+      fileFilter
+    } = ctx;
+    const toolIds = this.resolveToolIds(options, docsOnly, manifest);
+    const toolResults = await this.restoreAllTools(
+      toolIds,
+      manifest,
+      descriptor,
+      contentFiles,
+      docsDir,
+      projectRoot,
+      version,
+      force,
+      interactive,
+      fileFilter
+    );
+    const hasExplicitToolFilter = !docsOnly && options.toolIds !== void 0 && options.toolIds.length > 0;
+    const docsResult = hasExplicitToolFilter ? null : await this.restoreDocs(
+      manifest,
+      docsFiles,
+      docsDir,
+      projectRoot,
+      version,
+      force,
+      interactive,
+      fileFilter
+    );
+    const hasChanges = toolResults.some((t) => t.restored.length > 0) || docsResult !== null && docsResult.restored.length > 0;
+    if (hasChanges) await this.manifestRepo.save(manifest);
+    return this.buildRestoreTotals(toolResults, docsResult);
+  }
+  resolveToolIds(options, docsOnly, manifest) {
+    if (docsOnly) return [];
+    return options.toolIds?.length ? options.toolIds : manifest.getInstalledToolIds();
+  }
+  async restoreAllTools(toolIds, manifest, descriptor, contentFiles, docsDir, projectRoot, version, force, interactive, fileFilter) {
     const toolResults = [];
     for (const toolId of toolIds) {
-      this.logger.info(`Checking ${toolId} for files to restore...`);
-      const config = getToolConfig(toolId);
-      const manifestFiles = manifest.getToolFiles(toolId);
-      const distribution = await generateDistribution(
+      const result = await this.restoreOneTool(
+        toolId,
+        manifest,
         descriptor,
-        config,
-        docsDir,
         contentFiles,
-        this.hasher,
-        this.platform,
-        projectRoot,
-        this.fs
-      );
-      const distMap = new Map(distribution.map((f) => [f.relativePath, f]));
-      const drift = await this.collectDrift(manifestFiles, distMap, projectRoot, fileFilter);
-      if (drift.length === 0) {
-        toolResults.push({ toolId, nothingToRestore: true, restored: [], kept: [] });
-        continue;
-      }
-      const { restored, kept, updatedHashMap } = await this.applyRestorations(
-        drift,
-        new Map(manifestFiles.map((f) => [f.relativePath, f.hash])),
+        docsDir,
         projectRoot,
+        version,
         force,
-        interactive
+        interactive,
+        fileFilter
       );
-      manifest.addTool(
-        toolId,
-        manifest.getToolVersion(toolId) ?? version,
-        Array.from(updatedHashMap.entries()).map(
-          ([relativePath, hash]) => new GeneratedFile({ relativePath, content: "", hash })
-        )
-      );
-      toolResults.push({ toolId, nothingToRestore: false, restored, kept });
+      toolResults.push(result);
     }
-    const hasExplicitToolFilter = !docsOnly && options.toolIds !== void 0 && options.toolIds.length > 0;
-    const docsResult = hasExplicitToolFilter ? null : await this.restoreDocs(
-      manifest,
-      docsFiles,
+    return toolResults;
+  }
+  async restoreOneTool(toolId, manifest, descriptor, contentFiles, docsDir, projectRoot, version, force, interactive, fileFilter) {
+    this.logger.info(`Checking ${toolId} for files to restore...`);
+    const config = getToolConfig(toolId);
+    const manifestFiles = manifest.getToolFiles(toolId);
+    const distribution = await generateDistribution(
+      descriptor,
+      config,
       docsDir,
+      contentFiles,
+      this.hasher,
+      this.platform,
+      projectRoot,
+      this.fs
+    );
+    const distMap = new Map(distribution.map((f) => [f.relativePath, f]));
+    const section = await this.restoreSection(
+      manifestFiles,
+      distMap,
       projectRoot,
-      version,
       force,
       interactive,
       fileFilter
     );
-    const hasChanges = toolResults.some((t) => t.restored.length > 0) || docsResult !== null && docsResult.restored.length > 0;
-    if (hasChanges) await this.manifestRepo.save(manifest);
-    const totalRestored = toolResults.reduce((s, t) => s + t.restored.length, 0) + (docsResult?.restored.length ?? 0);
-    const totalKept = toolResults.reduce((s, t) => s + t.kept.length, 0) + (docsResult?.kept.length ?? 0);
-    return { tools: toolResults, docs: docsResult, totalRestored, totalKept };
+    if (section === null) return { toolId, nothingToRestore: true, restored: [], kept: [] };
+    manifest.addTool(toolId, manifest.getToolVersion(toolId) ?? version, section.updatedFiles);
+    return { toolId, nothingToRestore: false, restored: section.restored, kept: section.kept };
+  }
+  /** Shared restoration logic for both tool files and docs files. Returns null when nothing to restore. */
+  async restoreSection(manifestFiles, distMap, projectRoot, force, interactive, fileFilter) {
+    const drift = await this.collectDrift(manifestFiles, distMap, projectRoot, fileFilter);
+    if (drift.length === 0) return null;
+    const { restored, kept, updatedHashMap } = await this.applyRestorations(
+      drift,
+      new Map(manifestFiles.map((f) => [f.relativePath, f.hash])),
+      projectRoot,
+      force,
+      interactive
+    );
+    const updatedFiles = Array.from(updatedHashMap.entries()).map(
+      ([relativePath, hash]) => new GeneratedFile({ relativePath, content: "", hash })
+    );
+    return { restored, kept, updatedFiles };
   }
   async restoreDocs(manifest, docsFiles, docsDir, projectRoot, version, force, interactive, fileFilter) {
     const docsManifestFiles = manifest.getDocsFiles();
@@ -4011,22 +4158,22 @@ var RestoreUseCase = class {
     this.logger.info("Checking docs for files to restore...");
     const distribution = buildDocsDistribution(docsFiles, docsDir, this.hasher);
     const distMap = new Map(distribution.map((f) => [f.relativePath, f]));
-    const drift = await this.collectDrift(docsManifestFiles, distMap, projectRoot, fileFilter);
-    if (drift.length === 0) return { nothingToRestore: true, restored: [], kept: [] };
-    const { restored, kept, updatedHashMap } = await this.applyRestorations(
-      drift,
-      new Map(docsManifestFiles.map((f) => [f.relativePath, f.hash])),
+    const section = await this.restoreSection(
+      docsManifestFiles,
+      distMap,
       projectRoot,
       force,
-      interactive
-    );
-    manifest.addDocs(
-      manifest.getDocsVersion() ?? version,
-      Array.from(updatedHashMap.entries()).map(
-        ([relativePath, hash]) => new GeneratedFile({ relativePath, content: "", hash })
-      )
+      interactive,
+      fileFilter
     );
-    return { nothingToRestore: false, restored, kept };
+    if (section === null) return { nothingToRestore: true, restored: [], kept: [] };
+    manifest.addDocs(manifest.getDocsVersion() ?? version, section.updatedFiles);
+    return { nothingToRestore: false, restored: section.restored, kept: section.kept };
+  }
+  buildRestoreTotals(toolResults, docsResult) {
+    const totalRestored = toolResults.reduce((s, t) => s + t.restored.length, 0) + (docsResult?.restored.length ?? 0);
+    const totalKept = toolResults.reduce((s, t) => s + t.kept.length, 0) + (docsResult?.kept.length ?? 0);
+    return { tools: toolResults, docs: docsResult, totalRestored, totalKept };
   }
   async collectDrift(manifestFiles, distMap, projectRoot, fileFilter) {
     const drift = [];
@@ -4240,8 +4387,8 @@ function registerRestoreCommand(program2) {
           deps.loader,
           deps.hasher,
           deps.logger,
-          prompter,
-          deps.platform
+          deps.platform,
+          prompter
         );
         const result = await restoreUseCase.execute({
           frameworkPath,
@@ -4370,6 +4517,45 @@ var AdoptUseCase = class {
   }
   async execute(options) {
     const { toolIds, frameworkPath, docsDir, projectRoot, version } = options;
+    this.validateToolIds(toolIds);
+    const existing = await this.manifestRepo.load();
+    if (existing !== null) throw new Error("Already initialized. Use `aidd update` to upgrade.");
+    await this.deleteLegacyConfig(projectRoot);
+    const { descriptor, contentFiles, docsFiles } = await this.loader.loadFromDirectory(
+      frameworkPath,
+      version
+    );
+    const manifest = Manifest.create(docsDir);
+    const toolResults = await this.registerAllTools(
+      toolIds,
+      manifest,
+      descriptor,
+      contentFiles,
+      docsDir,
+      projectRoot,
+      version
+    );
+    const docsRegistered = await this.registerDocs(
+      manifest,
+      docsFiles,
+      docsDir,
+      projectRoot,
+      version
+    );
+    await this.persistAdopt(manifest, docsDir, projectRoot, version);
+    return {
+      tools: toolResults,
+      totalRegistered: toolResults.reduce((sum, r) => sum + r.registered.length, 0),
+      docsRegistered
+    };
+  }
+  /** Finalizes catalog, saves manifest, and writes gitignore entry. */
+  async persistAdopt(manifest, docsDir, projectRoot, version) {
+    await this.finalizeCatalog(manifest, docsDir, projectRoot, version);
+    await this.manifestRepo.save(manifest);
+    await new GitignoreUseCase(this.fs).execute(projectRoot, [".aidd/cache/"]);
+  }
+  validateToolIds(toolIds) {
     const invalid = toolIds.filter((t) => !VALID_TOOL_IDS.includes(t));
     if (invalid.length > 0) {
       throw new Error(
@@ -4379,16 +4565,8 @@ var AdoptUseCase = class {
     if (toolIds.length === 0) {
       throw new Error("No tools specified. Use --tools to specify at least one tool.");
     }
-    const existing = await this.manifestRepo.load();
-    if (existing !== null) {
-      throw new Error("Already initialized. Use `aidd update` to upgrade.");
-    }
-    await this.deleteLegacyConfig(projectRoot);
-    const { descriptor, contentFiles, docsFiles } = await this.loader.loadFromDirectory(
-      frameworkPath,
-      version
-    );
-    const manifest = Manifest.create(docsDir);
+  }
+  async registerAllTools(toolIds, manifest, descriptor, contentFiles, docsDir, projectRoot, version) {
     const toolResults = [];
     for (const toolId of toolIds) {
       this.logger.info(`Adopting ${toolId}...`);
@@ -4416,37 +4594,33 @@ var AdoptUseCase = class {
       manifest.addTool(toolId, version, registeredFiles);
       toolResults.push({ toolId, registered: registeredFiles.map((f) => f.relativePath) });
     }
-    let docsRegistered = 0;
+    return toolResults;
+  }
+  async registerDocs(manifest, docsFiles, docsDir, projectRoot, version) {
     const docsAbsDir = join22(projectRoot, docsDir);
-    if (await this.fs.fileExists(docsAbsDir)) {
-      this.logger.info("Adopting docs...");
-      const docsDistribution = buildDocsDistribution(docsFiles, docsDir, this.hasher);
-      const registeredFiles = await this.matchDistributionToDisk(docsDistribution, projectRoot);
-      manifest.addDocs(version, registeredFiles);
-      docsRegistered = registeredFiles.length;
-    }
+    if (!await this.fs.fileExists(docsAbsDir)) return 0;
+    this.logger.info("Adopting docs...");
+    const docsDistribution = buildDocsDistribution(docsFiles, docsDir, this.hasher);
+    const registeredFiles = await this.matchDistributionToDisk(docsDistribution, projectRoot);
+    manifest.addDocs(version, registeredFiles);
+    return registeredFiles.length;
+  }
+  async finalizeCatalog(manifest, docsDir, projectRoot, version) {
     await new CatalogUseCase(this.fs).execute({ manifest, docsDir, projectRoot });
     const catalogRelPath = `${docsDir}/CATALOG.md`;
     const catalogAbsPath = join22(projectRoot, catalogRelPath);
-    if (await this.fs.fileExists(catalogAbsPath)) {
-      const catalogHash = await this.fs.readFileHash(catalogAbsPath);
-      const currentDocsFiles = manifest.getDocsFiles();
-      const updatedDocsFiles = currentDocsFiles.map(
-        (f) => f.relativePath === catalogRelPath ? new GeneratedFile({ relativePath: f.relativePath, content: "", hash: catalogHash }) : new GeneratedFile({ relativePath: f.relativePath, content: "", hash: f.hash })
+    if (!await this.fs.fileExists(catalogAbsPath)) return;
+    const catalogHash = await this.fs.readFileHash(catalogAbsPath);
+    const currentDocsFiles = manifest.getDocsFiles();
+    const updatedDocsFiles = currentDocsFiles.map(
+      (f) => f.relativePath === catalogRelPath ? new GeneratedFile({ relativePath: f.relativePath, content: "", hash: catalogHash }) : new GeneratedFile({ relativePath: f.relativePath, content: "", hash: f.hash })
+    );
+    if (!currentDocsFiles.some((f) => f.relativePath === catalogRelPath)) {
+      updatedDocsFiles.push(
+        new GeneratedFile({ relativePath: catalogRelPath, content: "", hash: catalogHash })
       );
-      if (!currentDocsFiles.some((f) => f.relativePath === catalogRelPath)) {
-        updatedDocsFiles.push(
-          new GeneratedFile({ relativePath: catalogRelPath, content: "", hash: catalogHash })
-        );
-      }
-      manifest.addDocs(manifest.getDocsVersion() ?? version, updatedDocsFiles);
     }
-    await this.manifestRepo.save(manifest);
-    return {
-      tools: toolResults,
-      totalRegistered: toolResults.reduce((sum, r) => sum + r.registered.length, 0),
-      docsRegistered
-    };
+    manifest.addDocs(manifest.getDocsVersion() ?? version, updatedDocsFiles);
   }
   async matchDistributionToDisk(distribution, projectRoot) {
     const result = [];
@@ -4514,39 +4688,71 @@ var InitUseCase = class {
   }
   async execute(options) {
     const { frameworkPath, version, projectRoot, force = false } = options;
-    const interactive = options.interactive ?? false;
-    let docsDir = options.docsDir;
-    let explicitDocsDir = options.explicitDocsDir;
-    let repo = options.repo;
-    if (interactive && !force && docsDir === void 0 && this.prompter !== void 0) {
-      const docsDirInput = await this.prompter.input(
-        "Documentation directory name:",
-        Manifest.DEFAULT_DOCS_DIR
-      );
-      docsDir = docsDirInput || Manifest.DEFAULT_DOCS_DIR;
-      explicitDocsDir = docsDir;
-      const repoInput = await this.prompter.input(
-        "Framework repository (owner/repo, leave blank to skip):",
-        options.repo ?? ""
-      );
-      if (repoInput !== "") {
-        repo = repoInput.trim();
-      }
-    }
+    const { docsDir, explicitDocsDir, repo } = await this.resolveInitConfig(options);
     const resolvedInputDocsDir = docsDir ?? Manifest.DEFAULT_DOCS_DIR;
     Manifest.validateDocsDir(resolvedInputDocsDir);
-    await this.checkPreconditions({ docsDir: resolvedInputDocsDir, projectRoot, force, repo });
     const existing = await this.manifestRepo.load();
+    await this.checkPreconditions({ docsDir: resolvedInputDocsDir, projectRoot, force, repo });
     const resolvedDocsDir = force && existing !== null && explicitDocsDir === void 0 ? existing.docsDir : resolvedInputDocsDir;
     const { descriptor, docsFiles } = await this.loader.loadFromDirectory(frameworkPath, version);
+    const generated = await this.writeDocsFiles(
+      docsFiles,
+      resolvedDocsDir,
+      projectRoot,
+      force,
+      existing
+    );
+    if (force && existing !== null)
+      await this.removeStaleDocsFiles(generated, existing, projectRoot);
+    const manifest = this.buildManifest(existing, resolvedDocsDir, repo, force);
+    manifest.addDocs(descriptor.version, generated);
+    await this.persistInit(manifest, resolvedDocsDir, projectRoot, force);
+    return { docsDir: resolvedDocsDir, fileCount: generated.length, manifest };
+  }
+  buildManifest(existing, resolvedDocsDir, repo, force) {
+    return force && existing !== null ? existing.withDocsDir(resolvedDocsDir) : Manifest.create(resolvedDocsDir, repo);
+  }
+  /** Saves manifest, regenerates catalog, and conditionally adds gitignore entry. */
+  async persistInit(manifest, docsDir, projectRoot, force) {
+    await this.manifestRepo.save(manifest);
+    await new CatalogUseCase(this.fs).execute({ manifest, docsDir, projectRoot });
+    if (!force) {
+      await new GitignoreUseCase(this.fs).execute(projectRoot, [".aidd/cache/"]);
+    }
+  }
+  /** Resolves interactive config (docsDir, repo) if prompted, otherwise uses options as-is. */
+  async resolveInitConfig(options) {
+    const interactive = options.interactive ?? false;
+    const force = options.force ?? false;
+    if (!interactive || force || options.docsDir !== void 0 || this.prompter === void 0) {
+      return {
+        docsDir: options.docsDir,
+        explicitDocsDir: options.explicitDocsDir,
+        repo: options.repo
+      };
+    }
+    const docsDirInput = await this.prompter.input(
+      "Documentation directory name:",
+      Manifest.DEFAULT_DOCS_DIR
+    );
+    const docsDir = docsDirInput || Manifest.DEFAULT_DOCS_DIR;
+    const repoInput = await this.prompter.input(
+      "Framework repository (owner/repo, leave blank to skip):",
+      options.repo ?? ""
+    );
+    const repo = repoInput !== "" ? repoInput.trim() : options.repo;
+    return { docsDir, explicitDocsDir: docsDir, repo };
+  }
+  /** Writes docs files to disk, skipping CATALOG.md. Returns the list of generated files. */
+  async writeDocsFiles(docsFiles, docsDir, projectRoot, force, existing) {
     const generated = [];
     for (const [frameworkRelPath, rawContent] of docsFiles.entries()) {
       if (frameworkRelPath.endsWith("CATALOG.md")) continue;
-      const outputRelPath = remapDocsPath(frameworkRelPath, resolvedDocsDir);
+      const outputRelPath = remapDocsPath(frameworkRelPath, docsDir);
       const outputPath = join23(projectRoot, outputRelPath);
-      const content = rewriteDocsContent(rawContent, resolvedDocsDir);
+      const content = rewriteDocsContent(rawContent, docsDir);
       const newHash = this.hasher.hash(content);
-      if (force && await this.fs.fileExists(outputPath)) {
+      if (force && existing !== null && await this.fs.fileExists(outputPath)) {
         const diskHash = await this.fs.readFileHash(outputPath);
         if (!diskHash.equals(newHash)) {
           this.logger.warn(`Overwriting modified file: ${outputRelPath}`);
@@ -4557,28 +4763,74 @@ var InitUseCase = class {
       }
       generated.push(new GeneratedFile({ relativePath: outputRelPath, content, hash: newHash }));
     }
-    if (force && existing !== null) {
-      const newPaths = new Set(generated.map((f) => f.relativePath));
-      for (const oldFile of existing.getDocsFiles()) {
-        if (!newPaths.has(oldFile.relativePath)) {
-          await this.fs.deleteFile(join23(projectRoot, oldFile.relativePath));
-        }
+    return generated;
+  }
+  async removeStaleDocsFiles(generated, existing, projectRoot) {
+    const newPaths = new Set(generated.map((f) => f.relativePath));
+    for (const oldFile of existing.getDocsFiles()) {
+      if (!newPaths.has(oldFile.relativePath)) {
+        await this.fs.deleteFile(join23(projectRoot, oldFile.relativePath));
       }
     }
-    const manifest = force && existing !== null ? existing.withDocsDir(resolvedDocsDir) : Manifest.create(resolvedDocsDir, repo);
-    manifest.addDocs(descriptor.version, generated);
-    await this.manifestRepo.save(manifest);
-    await new CatalogUseCase(this.fs).execute({ manifest, docsDir: resolvedDocsDir, projectRoot });
-    if (!force) {
-      await new GitignoreUseCase(this.fs).execute(projectRoot, [".aidd/cache/"]);
+  }
+};
+
+// src/application/use-cases/shared/setup-state-detector.ts
+var SetupStateDetector = class {
+  constructor(manifestRepo, fs, resolver) {
+    this.manifestRepo = manifestRepo;
+    this.fs = fs;
+    this.resolver = resolver;
+  }
+  async detect(projectRoot) {
+    const manifest = await this.manifestRepo.load();
+    if (manifest === null) {
+      return this.detectWithoutManifest(projectRoot);
     }
-    return { docsDir: resolvedDocsDir, fileCount: generated.length, manifest };
+    const installedIds = manifest.getInstalledToolIds();
+    if (installedIds.length === 0) {
+      return { kind: "needs-install" };
+    }
+    return this.detectUpdateState(manifest, installedIds);
+  }
+  async detectWithoutManifest(projectRoot) {
+    for (const tool of getAllRegisteredTools().values()) {
+      if (await hasToolSignals(this.fs, tool, projectRoot)) return { kind: "needs-adopt" };
+    }
+    return { kind: "needs-init" };
+  }
+  async detectUpdateState(manifest, installedIds) {
+    try {
+      const latestVersion = await this.resolver.fetchLatestVersion(manifest.repo);
+      const installedVersions = installedIds.map((id) => manifest.getToolVersion(id)).filter((v) => v !== void 0);
+      const currentVersion2 = installedVersions[0] ?? "unknown";
+      const needsUpdate = isSemver(latestVersion) && installedVersions.some((v) => !isSemver(v) || compareSemver(v, latestVersion) < 0);
+      if (needsUpdate) {
+        return { kind: "needs-update", currentVersion: currentVersion2, latestVersion };
+      }
+    } catch {
+    }
+    return { kind: "up-to-date" };
   }
 };
 
 // src/application/use-cases/update-use-case.ts
 import { join as join24 } from "path";
 
+// src/domain/models/update-scope.ts
+function parseUpdateScope(raw) {
+  if (raw === "all") return { kind: "all" };
+  if (raw === "docs") return { kind: "docs" };
+  if (raw.startsWith("tool:")) {
+    const toolId = raw.slice(5);
+    return { kind: "tool", toolId };
+  }
+  throw new Error(`Invalid update scope: "${raw}"`);
+}
+function formatToolScopeValue(toolId) {
+  return `tool:${toolId}`;
+}
+
 // src/application/use-cases/conflict-resolution-use-case.ts
 var ConflictResolutionUseCase = class {
   constructor(prompter) {
@@ -4642,51 +4894,70 @@ var UpdateUseCase = class {
   }
   async execute(options) {
     const { force = false, dryRun = false } = options;
-    const interactive = options.interactive ?? false;
     const conflictResolution = new ConflictResolutionUseCase(this.prompter);
-    const isInteractive = interactive && !force && !dryRun && options.toolIds === void 0 && !(options.docsOnly ?? false);
-    if (isInteractive) {
-      const dryRunResult = await this.executeInternal(options, {
-        dryRun: true,
-        force: false,
-        conflictResolution
-      });
-      const changedTools = dryRunResult.tools.filter(
-        (t) => t.diff.some((d) => d.kind !== "unchanged")
-      );
-      const docsChanged = dryRunResult.docs?.diff.some((d) => d.kind !== "unchanged") ?? false;
-      if (changedTools.length === 0 && !docsChanged) {
-        return this.executeInternal(
-          { ...options, force: true },
-          { dryRun: false, force: true, conflictResolution }
-        ).then((r) => ({ ...r, cancelled: false, version: options.version }));
-      }
-      const scopeChoices = [
-        { name: "All", value: "all" },
-        ...changedTools.map((t) => ({ name: `${t.toolId} only`, value: `tool:${t.toolId}` })),
-        ...docsChanged ? [{ name: "docs only", value: "docs" }] : []
-      ];
-      const scopeSelection = await this.prompter.select("What to update?", scopeChoices);
-      const confirmed = await this.prompter.confirm("Apply update?");
-      if (!confirmed) {
-        return { ...dryRunResult, cancelled: true, version: options.version };
-      }
-      let toolIds;
-      let docsOnly = false;
-      if (scopeSelection === "docs") {
-        docsOnly = true;
-      } else if (scopeSelection.startsWith("tool:")) {
-        toolIds = [scopeSelection.slice(5)];
-      }
-      return this.executeInternal(
-        { ...options, toolIds, docsOnly, force: true },
+    const isInteractive = this.resolveInteractiveFlag(options, force, dryRun);
+    if (!isInteractive) {
+      return this.executeInternal(options, { dryRun, force, conflictResolution }).then((r) => ({
+        ...r,
+        version: options.version
+      }));
+    }
+    return this.executeInteractive(options, conflictResolution);
+  }
+  resolveInteractiveFlag(options, force, dryRun) {
+    return (options.interactive ?? false) && !force && !dryRun && options.toolIds === void 0 && !(options.docsOnly ?? false);
+  }
+  async executeInteractive(options, conflictResolution) {
+    const dryRunResult = await this.executeInternal(options, {
+      dryRun: true,
+      force: false,
+      conflictResolution
+    });
+    const outcome = await this.buildInteractiveScope(dryRunResult, options, conflictResolution);
+    if (outcome.kind === "already-applied") {
+      return { ...outcome.result, version: options.version };
+    }
+    if (outcome.kind === "cancelled") {
+      return { ...dryRunResult, cancelled: true, version: options.version };
+    }
+    return this.executeInternal(
+      { ...options, toolIds: outcome.toolIds, docsOnly: outcome.docsOnly, force: true },
+      { dryRun: false, force: true, conflictResolution }
+    ).then((r) => ({ ...r, cancelled: false, version: options.version }));
+  }
+  /** Resolves the interactive update scope after a dry-run. */
+  async buildInteractiveScope(dryRunResult, options, conflictResolution) {
+    const changedTools = dryRunResult.tools.filter(
+      (t) => t.diff.some((d) => d.kind !== "unchanged")
+    );
+    const docsChanged = dryRunResult.docs?.diff.some((d) => d.kind !== "unchanged") ?? false;
+    if (changedTools.length === 0 && !docsChanged) {
+      const result = await this.executeInternal(
+        { ...options, force: true },
         { dryRun: false, force: true, conflictResolution }
-      ).then((r) => ({ ...r, cancelled: false, version: options.version }));
+      );
+      return { kind: "already-applied", result };
+    }
+    const scopeChoices = [
+      { name: "All", value: "all" },
+      ...changedTools.map((t) => ({
+        name: `${t.toolId} only`,
+        value: formatToolScopeValue(t.toolId)
+      })),
+      ...docsChanged ? [{ name: "docs only", value: "docs" }] : []
+    ];
+    const scopeSelection = await this.prompter.select("What to update?", scopeChoices);
+    const confirmed = await this.prompter.confirm("Apply update?");
+    if (!confirmed) return { kind: "cancelled" };
+    const scope = parseUpdateScope(scopeSelection);
+    let toolIds;
+    let docsOnly = false;
+    if (scope.kind === "docs") {
+      docsOnly = true;
+    } else if (scope.kind === "tool") {
+      toolIds = [scope.toolId];
     }
-    return this.executeInternal(options, { dryRun, force, conflictResolution }).then((r) => ({
-      ...r,
-      version: options.version
-    }));
+    return { kind: "scope", toolIds, docsOnly };
   }
   async executeInternal(options, internal) {
     const { frameworkPath, version, projectRoot, repo } = options;
@@ -4699,78 +4970,18 @@ var UpdateUseCase = class {
       frameworkPath,
       version
     );
-    const toolResults = [];
-    if (options.toolIds && options.toolIds.length > 0) {
-      const installedIds = new Set(manifest.getInstalledToolIds());
-      const notInstalled = options.toolIds.filter((id) => !installedIds.has(id));
-      if (notInstalled.length > 0) {
-        throw new Error(
-          `${notInstalled.join(", ")} ${notInstalled.length === 1 ? "is" : "are"} not installed. Use \`aidd install ${notInstalled.join(" ")}\` first.`
-        );
-      }
-    }
-    const effectiveToolIds = docsOnly ? [] : options.toolIds && options.toolIds.length > 0 ? options.toolIds : manifest.getInstalledToolIds();
-    for (const toolId of effectiveToolIds) {
-      this.logger.debug(`Checking ${toolId} for updates...`);
-      const config = getToolConfig(toolId);
-      const manifestFiles = manifest.getToolFiles(toolId);
-      const manifestMap = new Map(manifestFiles.map((f) => [f.relativePath, f.hash]));
-      const newDistribution = await generateDistribution(
-        descriptor,
-        config,
-        docsDir,
-        contentFiles,
-        this.hasher,
-        this.platform,
-        projectRoot,
-        this.fs
-      );
-      const newDistMap = new Map(newDistribution.map((f) => [f.relativePath, f]));
-      const diff = await this.computeDiff(newDistribution, newDistMap, manifestMap, projectRoot);
-      let result = {
-        kept: [],
-        written: [],
-        deleted: [],
-        backedUp: [],
-        userFileConflicts: []
-      };
-      if (!dryRun) {
-        const mergedHashMap = /* @__PURE__ */ new Map();
-        for (const newFile of newDistribution) {
-          if (!newFile.merge) continue;
-          const outputPath = join24(projectRoot, newFile.relativePath);
-          await this.fs.mergeJsonFile(outputPath, newFile.content);
-          const diskHash = await this.fs.readFileHash(outputPath);
-          manifest.syncFileHashAcrossTools(newFile.relativePath, diskHash);
-          mergedHashMap.set(newFile.relativePath, diskHash);
-        }
-        const conflictDecisions = await this.resolveConflicts(diff, force, conflictResolution);
-        result = await this.applyDiff(diff, newDistMap, projectRoot, conflictDecisions, manifest);
-        for (const relativePath of result.userFileConflicts) {
-          this.logger.warn(
-            `\`${relativePath}\` already exists and was not installed by AIDD \u2014 skipped to preserve user file`
-          );
-        }
-        const nonMergedFinal = newDistribution.filter((f) => !f.merge).filter(
-          (f) => !result.deleted.includes(f.relativePath) && !result.kept.includes(f.relativePath) && !result.userFileConflicts.includes(f.relativePath)
-        );
-        const keptFiles = manifestFiles.filter((f) => result.kept.includes(f.relativePath)).map(
-          (f) => new GeneratedFile({ relativePath: f.relativePath, content: "", hash: f.hash })
-        );
-        const mergedFiles = manifestFiles.filter((f) => newDistMap.get(f.relativePath)?.merge === true).map((f) => {
-          const hash = mergedHashMap.get(f.relativePath) ?? f.hash;
-          return new GeneratedFile({ relativePath: f.relativePath, content: "", hash });
-        });
-        manifest.addTool(toolId, version, [...nonMergedFinal, ...keptFiles, ...mergedFiles]);
-      }
-      toolResults.push({
-        toolId,
-        alreadyUpToDate: !diff.some((d) => d.kind !== "unchanged"),
-        dryRun,
-        diff,
-        ...result
-      });
-    }
+    this.validateToolIds(options.toolIds, manifest);
+    const effectiveToolIds = this.resolveEffectiveToolIds(options, docsOnly, manifest);
+    const toolResults = await this.updateAllTools(
+      effectiveToolIds,
+      manifest,
+      descriptor,
+      contentFiles,
+      docsDir,
+      projectRoot,
+      version,
+      internal
+    );
     const hasExplicitToolFilter = !docsOnly && options.toolIds !== void 0 && options.toolIds.length > 0;
     const docsResult = hasExplicitToolFilter ? null : await this.updateDocs(
       manifest,
@@ -4783,17 +4994,131 @@ var UpdateUseCase = class {
       conflictResolution
     );
     if (!dryRun) {
-      await new MemoryScriptUseCase(this.fs, this.hasher, this.git).execute({
+      await new PostInstallPipelineUseCase(
+        this.fs,
+        this.manifestRepo,
+        this.hasher,
+        this.git
+      ).execute({
         projectRoot,
         version,
         descriptor,
         contentFiles,
-        manifest
+        manifest,
+        docsDir
       });
-      await this.manifestRepo.save(manifest);
-      await new CatalogUseCase(this.fs).execute({ manifest, docsDir, projectRoot });
-      await new GitignoreUseCase(this.fs).execute(projectRoot, [".aidd/cache/"]);
     }
+    return this.buildTotals(toolResults, docsResult, dryRun);
+  }
+  validateToolIds(toolIds, manifest) {
+    if (!toolIds || toolIds.length === 0) return;
+    const installedIds = new Set(manifest.getInstalledToolIds());
+    const notInstalled = toolIds.filter((id) => !installedIds.has(id));
+    if (notInstalled.length > 0) {
+      throw new Error(
+        `${notInstalled.join(", ")} ${notInstalled.length === 1 ? "is" : "are"} not installed. Use \`aidd install ${notInstalled.join(" ")}\` first.`
+      );
+    }
+  }
+  resolveEffectiveToolIds(options, docsOnly, manifest) {
+    if (docsOnly) return [];
+    if (options.toolIds && options.toolIds.length > 0) return options.toolIds;
+    return manifest.getInstalledToolIds();
+  }
+  async updateAllTools(toolIds, manifest, descriptor, contentFiles, docsDir, projectRoot, version, internal) {
+    const toolResults = [];
+    for (const toolId of toolIds) {
+      this.logger.debug(`Checking ${toolId} for updates...`);
+      const result = await this.updateToolSection(
+        toolId,
+        manifest,
+        descriptor,
+        contentFiles,
+        docsDir,
+        projectRoot,
+        version,
+        internal
+      );
+      toolResults.push(result);
+    }
+    return toolResults;
+  }
+  async updateToolSection(toolId, manifest, descriptor, contentFiles, docsDir, projectRoot, version, internal) {
+    const { dryRun, force, conflictResolution } = internal;
+    const config = getToolConfig(toolId);
+    const manifestFiles = manifest.getToolFiles(toolId);
+    const manifestMap = new Map(manifestFiles.map((f) => [f.relativePath, f.hash]));
+    const newDistribution = await generateDistribution(
+      descriptor,
+      config,
+      docsDir,
+      contentFiles,
+      this.hasher,
+      this.platform,
+      projectRoot,
+      this.fs
+    );
+    const newDistMap = new Map(newDistribution.map((f) => [f.relativePath, f]));
+    const diff = await this.computeDiff(newDistribution, newDistMap, manifestMap, projectRoot);
+    let result = this.emptyApplyDiffResult();
+    if (!dryRun) {
+      const mergedHashMap = await this.applyMergeFiles(newDistribution, projectRoot, manifest);
+      const conflictDecisions = await this.resolveConflicts(diff, force, conflictResolution);
+      result = await this.applyDiff(diff, newDistMap, projectRoot, conflictDecisions, manifest);
+      this.warnUserFileConflicts(result.userFileConflicts);
+      this.registerToolFiles(
+        toolId,
+        version,
+        manifest,
+        newDistribution,
+        manifestFiles,
+        result,
+        mergedHashMap,
+        newDistMap
+      );
+    }
+    return {
+      toolId,
+      alreadyUpToDate: !diff.some((d) => d.kind !== "unchanged"),
+      dryRun,
+      diff,
+      ...result
+    };
+  }
+  emptyApplyDiffResult() {
+    return { kept: [], written: [], deleted: [], backedUp: [], userFileConflicts: [] };
+  }
+  warnUserFileConflicts(conflicts) {
+    for (const relativePath of conflicts) {
+      this.logger.warn(
+        `\`${relativePath}\` already exists and was not installed by AIDD \u2014 skipped to preserve user file`
+      );
+    }
+  }
+  async applyMergeFiles(newDistribution, projectRoot, manifest) {
+    const mergedHashMap = /* @__PURE__ */ new Map();
+    for (const newFile of newDistribution) {
+      if (!newFile.merge) continue;
+      const outputPath = join24(projectRoot, newFile.relativePath);
+      await this.fs.mergeJsonFile(outputPath, newFile.content);
+      const diskHash = await this.fs.readFileHash(outputPath);
+      manifest.syncFileHashAcrossTools(newFile.relativePath, diskHash);
+      mergedHashMap.set(newFile.relativePath, diskHash);
+    }
+    return mergedHashMap;
+  }
+  registerToolFiles(toolId, version, manifest, newDistribution, manifestFiles, result, mergedHashMap, newDistMap) {
+    const nonMergedFinal = newDistribution.filter((f) => !f.merge).filter(
+      (f) => !result.deleted.includes(f.relativePath) && !result.kept.includes(f.relativePath) && !result.userFileConflicts.includes(f.relativePath)
+    );
+    const keptFiles = manifestFiles.filter((f) => result.kept.includes(f.relativePath)).map((f) => new GeneratedFile({ relativePath: f.relativePath, content: "", hash: f.hash }));
+    const mergedFiles = manifestFiles.filter((f) => newDistMap.get(f.relativePath)?.merge === true).map((f) => {
+      const hash = mergedHashMap.get(f.relativePath) ?? f.hash;
+      return new GeneratedFile({ relativePath: f.relativePath, content: "", hash });
+    });
+    manifest.addTool(toolId, version, [...nonMergedFinal, ...keptFiles, ...mergedFiles]);
+  }
+  buildTotals(toolResults, docsResult, dryRun) {
     const totalWritten = toolResults.reduce((s, t) => s + t.written.length, 0) + (docsResult?.written.length ?? 0);
     const totalDeleted = toolResults.reduce((s, t) => s + t.deleted.length, 0) + (docsResult?.deleted.length ?? 0);
     const toolCount = toolResults.filter((t) => !t.alreadyUpToDate).length;
@@ -4822,21 +5147,11 @@ var UpdateUseCase = class {
     const manifestFiles = manifest.getDocsFiles();
     const manifestMap = new Map(manifestFiles.map((f) => [f.relativePath, f.hash]));
     const diff = await this.computeDiff(newDistribution, newDistMap, manifestMap, projectRoot);
-    let result = {
-      kept: [],
-      written: [],
-      deleted: [],
-      backedUp: [],
-      userFileConflicts: []
-    };
+    let result = this.emptyApplyDiffResult();
     if (!dryRun) {
       const conflictDecisions = await this.resolveConflicts(diff, force, conflictResolution);
       result = await this.applyDiff(diff, newDistMap, projectRoot, conflictDecisions, manifest);
-      for (const relativePath of result.userFileConflicts) {
-        this.logger.warn(
-          `\`${relativePath}\` already exists and was not installed by AIDD \u2014 skipped to preserve user file`
-        );
-      }
+      this.warnUserFileConflicts(result.userFileConflicts);
       const finalFiles = newDistribution.filter(
         (f) => !result.deleted.includes(f.relativePath) && !result.kept.includes(f.relativePath) && !result.userFileConflicts.includes(f.relativePath)
       );
@@ -4965,10 +5280,7 @@ var SetupUseCase = class {
   }
   frameworkResolver;
   async execute(options) {
-    const state = await detectSetupState(
-      this.manifestRepo,
-      this.fs,
-      this.resolver,
+    const state = await new SetupStateDetector(this.manifestRepo, this.fs, this.resolver).detect(
       options.projectRoot
     );
     switch (state.kind) {
@@ -4985,79 +5297,23 @@ var SetupUseCase = class {
     }
   }
   async handleInit(options) {
-    const { projectRoot, release, repo } = options;
-    let docsDir;
-    let explicitDocsDir;
-    if (options.docsDir !== void 0) {
-      docsDir = options.docsDir;
-      explicitDocsDir = options.docsDir;
-      Manifest.validateDocsDir(docsDir);
-    } else if (!options.interactive) {
-      docsDir = Manifest.DEFAULT_DOCS_DIR;
-      explicitDocsDir = "";
-    } else {
-      const docsDirInput = await this.prompter.input(
-        "Documentation directory name:",
-        Manifest.DEFAULT_DOCS_DIR
-      );
-      docsDir = docsDirInput || Manifest.DEFAULT_DOCS_DIR;
-      explicitDocsDir = docsDirInput;
-      Manifest.validateDocsDir(docsDir);
-    }
-    let frameworkPath;
-    let frameworkRepo;
-    if (options.path !== void 0) {
-      if (options.path) {
-        if (isLocalPath(options.path)) {
-          frameworkPath = options.path;
-        } else {
-          frameworkRepo = options.path;
-        }
-      }
-    } else {
-      const existingManifest = await this.manifestRepo.load();
-      const sourceDefault = existingManifest?.repo ?? this.resolver.getDefaultRepo() ?? "";
-      const sourceInput = options.interactive ? await this.prompter.input("Framework source (owner/repo or local path):", sourceDefault) : sourceDefault;
-      if (sourceInput) {
-        if (isLocalPath(sourceInput)) {
-          frameworkPath = sourceInput;
-        } else {
-          frameworkRepo = sourceInput;
-        }
-      }
-    }
-    let resolvedRelease = release;
-    if (!frameworkPath && !release) {
-      if (options.interactive) {
-        const latest = await this.resolver.fetchLatestVersion(frameworkRepo).catch(() => "");
-        resolvedRelease = await this.prompter.input(
-          latest ? `Framework release tag (latest: ${latest}):` : "Framework release tag:",
-          latest
-        ) || latest || void 0;
-      } else {
-        resolvedRelease = await this.resolver.fetchLatestVersion(frameworkRepo).catch(() => void 0);
-      }
-    }
+    const { projectRoot, repo } = options;
+    const { docsDir, explicitDocsDir } = await this.resolveDocsDir(options);
+    const { frameworkPath, frameworkRepo } = await this.resolveFrameworkSource(options);
+    const resolvedRelease = await this.resolveRelease(frameworkRepo, options);
     const resolved = await this.frameworkResolver.execute({
       path: frameworkPath,
       release: resolvedRelease
     });
     const repoForManifest = frameworkRepo ?? repo;
-    const initResult = await new InitUseCase(
-      this.fs,
-      this.manifestRepo,
-      this.loader,
-      this.hasher,
-      this.logger
-    ).execute({
-      frameworkPath: resolved.path,
-      version: resolved.version,
+    const initResult = await this.runInit(
+      resolved.path,
+      resolved.version,
       docsDir,
       explicitDocsDir,
       projectRoot,
-      force: false,
-      repo: repoForManifest
-    });
+      repoForManifest
+    );
     const installResults = await this.runInstall(
       resolved.path,
       resolved.version,
@@ -5073,40 +5329,94 @@ var SetupUseCase = class {
       install: { results: installResults }
     };
   }
+  async runInit(frameworkPath, version, docsDir, explicitDocsDir, projectRoot, repo) {
+    return new InitUseCase(
+      this.fs,
+      this.manifestRepo,
+      this.loader,
+      this.hasher,
+      this.logger
+    ).execute({
+      frameworkPath,
+      version,
+      docsDir,
+      explicitDocsDir,
+      projectRoot,
+      force: false,
+      repo
+    });
+  }
+  async resolveDocsDir(options) {
+    if (options.docsDir !== void 0) {
+      Manifest.validateDocsDir(options.docsDir);
+      return { docsDir: options.docsDir, explicitDocsDir: options.docsDir };
+    }
+    if (!options.interactive) {
+      return { docsDir: Manifest.DEFAULT_DOCS_DIR, explicitDocsDir: "" };
+    }
+    const docsDirInput = await this.prompter.input(
+      "Documentation directory name:",
+      Manifest.DEFAULT_DOCS_DIR
+    );
+    const docsDir = docsDirInput || Manifest.DEFAULT_DOCS_DIR;
+    Manifest.validateDocsDir(docsDir);
+    return { docsDir, explicitDocsDir: docsDirInput };
+  }
+  async resolveFrameworkSource(options) {
+    if (options.path !== void 0) {
+      if (!options.path) return {};
+      if (isLocalPath(options.path)) return { frameworkPath: options.path };
+      return { frameworkRepo: options.path };
+    }
+    const existingManifest = await this.manifestRepo.load();
+    const sourceDefault = existingManifest?.repo ?? this.resolver.getDefaultRepo() ?? "";
+    const sourceInput = options.interactive ? await this.prompter.input("Framework source (owner/repo or local path):", sourceDefault) : sourceDefault;
+    if (!sourceInput) return {};
+    if (isLocalPath(sourceInput)) return { frameworkPath: sourceInput };
+    return { frameworkRepo: sourceInput };
+  }
+  async resolveRelease(frameworkRepo, options) {
+    if (options.path && isLocalPath(options.path)) return options.release;
+    if (options.release) return options.release;
+    if (options.interactive) {
+      const latest = await this.resolver.fetchLatestVersion(frameworkRepo).catch(() => "");
+      const label = latest ? `Framework release tag (latest: ${latest}):` : "Framework release tag:";
+      return await this.prompter.input(label, latest) || latest || void 0;
+    }
+    return this.resolver.fetchLatestVersion(frameworkRepo).catch(() => void 0);
+  }
   async handleAdopt(options) {
     const { projectRoot, repo } = options;
+    this.validateAdoptNonInteractive(options, repo);
+    const selected = await this.resolveAdoptTools(options);
+    const fromInput = await this.resolveAdoptFrom(options, repo);
+    const { path: frameworkPath, version } = await this.frameworkResolver.execute({
+      from: fromInput
+    });
+    const adoptResult = await this.runAdopt(
+      selected,
+      frameworkPath,
+      projectRoot,
+      version
+    );
+    return {
+      kind: "adopted",
+      version,
+      toolCount: adoptResult.tools.length,
+      totalRegistered: adoptResult.totalRegistered,
+      docsRegistered: adoptResult.docsRegistered
+    };
+  }
+  validateAdoptNonInteractive(options, repo) {
     if (!options.interactive) {
       if (!options.toolIds || options.toolIds.length === 0) {
         throw new Error("--tools <ids> is required for adopt in non-interactive mode.");
       }
-      if (options.from === void 0) {
-        throw new AdoptRequiresVersionError(repo);
-      }
-    }
-    let selected;
-    if (options.toolIds !== void 0 && options.toolIds.length > 0) {
-      selected = options.toolIds;
-    } else {
-      const choices = VALID_TOOL_IDS.map((id) => ({ name: id, value: id, checked: false }));
-      const checkedIds = await this.prompter.checkbox("Which tools do you want to adopt?", choices);
-      if (checkedIds.length === 0) throw new Error("No tools selected.");
-      selected = checkedIds;
+      if (options.from === void 0) throw new AdoptRequiresVersionError(repo);
     }
-    let fromInput;
-    if (options.from !== void 0) {
-      fromInput = options.from;
-      if (!fromInput) throw new AdoptRequiresVersionError(repo);
-    } else {
-      fromInput = await this.prompter.input(
-        "Which version of the framework do you already have installed? (e.g. v1.2.3 or local path):",
-        ""
-      );
-      if (!fromInput) throw new AdoptRequiresVersionError(repo);
-    }
-    const { path: frameworkPath, version } = await this.frameworkResolver.execute({
-      from: fromInput
-    });
-    const adoptResult = await new AdoptUseCase(
+  }
+  async runAdopt(toolIds, frameworkPath, projectRoot, version) {
+    return new AdoptUseCase(
       this.fs,
       this.manifestRepo,
       this.loader,
@@ -5114,19 +5424,33 @@ var SetupUseCase = class {
       this.logger,
       this.platform
     ).execute({
-      toolIds: selected,
+      toolIds,
       frameworkPath,
       docsDir: Manifest.DEFAULT_DOCS_DIR,
       projectRoot,
       version
     });
-    return {
-      kind: "adopted",
-      version,
-      toolCount: adoptResult.tools.length,
-      totalRegistered: adoptResult.totalRegistered,
-      docsRegistered: adoptResult.docsRegistered
-    };
+  }
+  async resolveAdoptTools(options) {
+    if (options.toolIds !== void 0 && options.toolIds.length > 0) {
+      return options.toolIds;
+    }
+    const choices = VALID_TOOL_IDS.map((id) => ({ name: id, value: id, checked: false }));
+    const checkedIds = await this.prompter.checkbox("Which tools do you want to adopt?", choices);
+    if (checkedIds.length === 0) throw new Error("No tools selected.");
+    return checkedIds;
+  }
+  async resolveAdoptFrom(options, repo) {
+    if (options.from !== void 0) {
+      if (!options.from) throw new AdoptRequiresVersionError(repo);
+      return options.from;
+    }
+    const fromInput = await this.prompter.input(
+      "Which version of the framework do you already have installed? (e.g. v1.2.3 or local path):",
+      ""
+    );
+    if (!fromInput) throw new AdoptRequiresVersionError(repo);
+    return fromInput;
   }
   async handleInstall(options) {
     const { projectRoot, path, release, repo } = options;
@@ -5168,9 +5492,17 @@ var SetupUseCase = class {
       interactive: options.interactive ?? false,
       repo
     });
-    if (updateResult.cancelled) {
-      return { kind: "update-cancelled" };
-    }
+    if (updateResult.cancelled) return { kind: "update-cancelled" };
+    return this.buildUpdateResult(
+      updateResult,
+      frameworkPath,
+      version,
+      projectRoot,
+      repo,
+      options.interactive
+    );
+  }
+  async buildUpdateResult(updateResult, frameworkPath, version, projectRoot, repo, interactive) {
     const updatedManifest = await this.manifestRepo.load();
     const updatedInstalledIds = updatedManifest?.getInstalledToolIds() ?? [];
     const missingTools = VALID_TOOL_IDS.filter((id) => !updatedInstalledIds.includes(id));
@@ -5180,7 +5512,7 @@ var SetupUseCase = class {
       version,
       projectRoot,
       repo,
-      options.interactive
+      interactive
     );
     return {
       kind: "updated",
@@ -5196,16 +5528,13 @@ var SetupUseCase = class {
     const manifest = await this.manifestRepo.load();
     const installedIds = manifest?.getInstalledToolIds() ?? [];
     const missingTools = VALID_TOOL_IDS.filter((id) => !installedIds.includes(id));
-    if (missingTools.length === 0) {
-      return { kind: "up-to-date", hasAdditionalTools: false };
-    }
-    if (!options.interactive) {
-      return { kind: "up-to-date", hasAdditionalTools: true };
-    }
+    if (missingTools.length === 0) return { kind: "up-to-date", hasAdditionalTools: false };
+    if (!options.interactive) return { kind: "up-to-date", hasAdditionalTools: true };
     const wantsMore = await this.prompter.confirm("Install additional tools?");
-    if (!wantsMore) {
-      return { kind: "up-to-date", hasAdditionalTools: true };
-    }
+    if (!wantsMore) return { kind: "up-to-date", hasAdditionalTools: true };
+    return this.installAdditionalTools(path, release, repo, projectRoot);
+  }
+  async installAdditionalTools(path, release, repo, projectRoot) {
     const { path: frameworkPath, version } = await this.frameworkResolver.execute({
       path,
       release,
@@ -5264,30 +5593,6 @@ var SetupUseCase = class {
     });
   }
 };
-async function detectSetupState(manifestRepo, fs, resolver, projectRoot) {
-  const manifest = await manifestRepo.load();
-  if (manifest === null) {
-    for (const tool of getAllRegisteredTools().values()) {
-      if (await hasToolSignals(fs, tool, projectRoot)) return { kind: "needs-adopt" };
-    }
-    return { kind: "needs-init" };
-  }
-  const installedIds = manifest.getInstalledToolIds();
-  if (installedIds.length === 0) {
-    return { kind: "needs-install" };
-  }
-  try {
-    const latestVersion = await resolver.fetchLatestVersion(manifest.repo);
-    const installedVersions = installedIds.map((id) => manifest.getToolVersion(id)).filter((v) => v !== void 0);
-    const currentVersion2 = installedVersions[0] ?? "unknown";
-    const needsUpdate = isSemver(latestVersion) && installedVersions.some((v) => !isSemver(v) || compareSemver(v, latestVersion) < 0);
-    if (needsUpdate) {
-      return { kind: "needs-update", currentVersion: currentVersion2, latestVersion };
-    }
-  } catch {
-  }
-  return { kind: "up-to-date" };
-}
 
 // src/application/commands/setup.ts
 function displayInstall(output, results, verbose) {
@@ -5427,7 +5732,7 @@ function registerStatusCommand(program2) {
         filterDocs,
         repo
       });
-      if (report.tools.length === 0 && !filterToolId) {
+      if (report.tools.length === 0 && !filterToolId && !filterDocs) {
         output.print("No tools installed. Run `aidd install <tool>` to get started.");
         if (report.inSync) return;
       } else if (report.inSync) {
@@ -5460,6 +5765,27 @@ docs (v${report.docs.version}):`);
 
 // src/application/use-cases/sync-use-case.ts
 import { join as join26 } from "path";
+
+// src/domain/models/sync-exclusions.ts
+var SYNC_EXCLUDED_FILES = /* @__PURE__ */ new Set([
+  "CLAUDE.md",
+  "AGENTS.md",
+  ".github/copilot-instructions.md",
+  ".mcp.json",
+  ".cursor/mcp.json",
+  ".vscode/mcp.json",
+  "opencode.json",
+  "opencode.jsonc"
+]);
+function isSyncExcluded(relativePath, docsDir) {
+  if (SYNC_EXCLUDED_FILES.has(relativePath)) return true;
+  if (relativePath.startsWith(".vscode/")) return true;
+  if (relativePath.startsWith(`${docsDir}/`)) return true;
+  if (relativePath.startsWith(".aidd/")) return true;
+  return false;
+}
+
+// src/application/use-cases/sync-use-case.ts
 function getSectionKeyFromFrameworkPath(frameworkPath) {
   if (frameworkPath.startsWith("agents/"))
     return { section: "agents", key: frameworkPath.slice("agents/".length) };
@@ -5482,23 +5808,6 @@ function transformContent(content, sourceConfig, targetConfig, sectionKey, docsD
   const targetBody = targetConfig.rewriteContent(canonicalBody, docsDir);
   return serializeFrontmatter(targetFrontmatter, targetBody);
 }
-var EXCLUDED_FILES = /* @__PURE__ */ new Set([
-  "CLAUDE.md",
-  "AGENTS.md",
-  ".github/copilot-instructions.md",
-  ".mcp.json",
-  ".cursor/mcp.json",
-  ".vscode/mcp.json",
-  "opencode.json",
-  "opencode.jsonc"
-]);
-function isExcluded(relativePath, docsDir) {
-  if (EXCLUDED_FILES.has(relativePath)) return true;
-  if (relativePath.startsWith(".vscode/")) return true;
-  if (relativePath.startsWith(`${docsDir}/`)) return true;
-  if (relativePath.startsWith(".aidd/")) return true;
-  return false;
-}
 function buildTargetPath(targetConfig, sectionKey) {
   return targetConfig[sectionKey.section]().buildFilePath(sectionKey.key);
 }
@@ -5512,143 +5821,166 @@ var SyncUseCase = class {
   }
   async execute(options) {
     const { projectRoot, force = false, includeUserFiles = false, repo } = options;
-    const interactive = options.interactive ?? false;
     const manifest = await this.manifestRepo.load();
-    if (manifest === null) {
-      throw new NoManifestError(repo);
-    }
+    if (manifest === null) throw new NoManifestError(repo);
     const docsDir = options.docsDir ?? manifest.docsDir;
-    let sourceTool;
-    let targetTools = options.targetTools;
-    if (options.sourceTool === void 0) {
-      if (!interactive || this.prompter === void 0) {
-        throw new Error("Source tool required in non-interactive mode.");
-      }
-      const { SyncStatusUseCase: SyncStatusUseCase2 } = await Promise.resolve().then(() => (init_sync_status_use_case(), sync_status_use_case_exports));
-      const installedIds = manifest.getInstalledToolIds();
-      if (installedIds.length < 2) {
-        throw new Error("Sync requires at least 2 installed tools.");
-      }
-      const modCounts = await new SyncStatusUseCase2(this.fs).execute(
-        manifest,
-        installedIds,
-        projectRoot
-      );
-      const hasAnyChanges = installedIds.some((id) => {
-        const { modified, deleted } = modCounts[id] ?? { modified: 0, deleted: 0 };
-        return modified > 0 || deleted > 0;
-      });
-      if (!hasAnyChanges) {
-        return {
-          sourceTool: installedIds[0],
-          tools: [],
-          totalWritten: 0,
-          totalDeleted: 0,
-          totalConflicts: 0,
-          totalSkipped: 0
-        };
-      }
-      const sourceChoices = installedIds.map((id) => {
-        const { modified, deleted } = modCounts[id] ?? { modified: 0, deleted: 0 };
-        const hasChanges = modified > 0 || deleted > 0;
-        const parts = [];
-        if (modified > 0) parts.push(`${modified} modified`);
-        if (deleted > 0) parts.push(`${deleted} deleted`);
-        const label = hasChanges ? ` (${parts.join(", ")})` : "";
-        return {
-          name: `${id}${label}`,
-          value: id,
-          disabled: hasChanges ? false : "(no changes)"
-        };
-      });
-      sourceTool = await this.prompter.select("Source tool to sync from?", sourceChoices);
-      const targetChoices = installedIds.filter((id) => id !== sourceTool).map((id) => ({ name: id, value: id }));
-      targetTools = await this.prompter.checkbox("Target tools?", targetChoices);
-      if (targetTools.length === 0) throw new Error("No target tools selected.");
-    } else {
-      sourceTool = options.sourceTool;
-      if (!manifest.hasTool(sourceTool)) {
-        throw new Error(`Source tool '${sourceTool}' is not installed.`);
-      }
-      const installedToolIds = manifest.getInstalledToolIds();
-      if (installedToolIds.length < 2) {
-        throw new Error("Sync requires at least 2 installed tools.");
-      }
-      targetTools = targetTools && targetTools.length > 0 ? targetTools : installedToolIds.filter((id) => id !== sourceTool);
-      for (const target of targetTools) {
-        if (target === sourceTool) {
-          throw new Error("Source and target cannot be the same tool.");
-        }
-        if (!manifest.hasTool(target)) {
-          throw new Error(`Target tool '${target}' is not installed.`);
-        }
-      }
-    }
+    const { sourceTool, targetTools } = await this.selectSyncScope(
+      options,
+      manifest,
+      options.interactive ?? false
+    );
     const sourceConfig = getToolConfig(sourceTool);
     const sourceManifestFiles = manifest.getToolFiles(sourceTool);
     const sourceManifestMap = new Map(sourceManifestFiles.map((f) => [f.relativePath, f.hash]));
+    const toolResults = await this.syncAllTargets(
+      targetTools,
+      sourceTool,
+      sourceConfig,
+      sourceManifestFiles,
+      sourceManifestMap,
+      manifest,
+      projectRoot,
+      docsDir,
+      force,
+      includeUserFiles
+    );
+    return this.buildSyncTotals(sourceTool, toolResults);
+  }
+  async syncAllTargets(targetTools, sourceTool, sourceConfig, sourceManifestFiles, sourceManifestMap, manifest, projectRoot, docsDir, force, includeUserFiles) {
     const toolResults = [];
-    for (const targetToolId of targetTools ?? []) {
+    for (const targetToolId of targetTools) {
       this.logger.info(`Syncing ${sourceTool} \u2192 ${targetToolId}...`);
-      const targetConfig = getToolConfig(targetToolId);
-      const targetManifestFiles = manifest.getToolFiles(targetToolId);
-      const targetManifestMap = new Map(targetManifestFiles.map((f) => [f.relativePath, f.hash]));
-      const targetByFrameworkPath = new Map(
-        targetManifestFiles.filter((f) => f.frameworkPath !== void 0).map((f) => [f.frameworkPath, f.relativePath])
-      );
-      const fileResults = [];
-      await this.propagateModified({
-        sourceManifestFiles,
+      const result = await this.syncOneTool(
+        targetToolId,
         sourceConfig,
-        targetConfig,
-        targetManifestMap,
-        targetByFrameworkPath,
-        fileResults,
-        projectRoot,
-        docsDir,
-        force
-      });
-      await this.propagateAdded({
+        sourceManifestFiles,
         sourceManifestMap,
-        sourceConfig,
-        targetConfig,
-        fileResults,
+        manifest,
         projectRoot,
         docsDir,
+        force,
         includeUserFiles
-      });
-      await this.propagateDeleted({
-        sourceManifestFiles,
-        targetByFrameworkPath,
-        fileResults,
-        projectRoot,
-        docsDir
-      });
-      toolResults.push({ targetToolId, files: fileResults });
+      );
+      toolResults.push(result);
     }
-    const totalWritten = toolResults.reduce(
-      (s, t) => s + t.files.filter((f) => f.written).length,
-      0
-    );
-    const totalDeleted = toolResults.reduce(
-      (s, t) => s + t.files.filter((f) => f.deleted).length,
-      0
-    );
-    const totalConflicts = toolResults.reduce(
-      (s, t) => s + t.files.filter((f) => f.conflict && !f.written).length,
-      0
+    return toolResults;
+  }
+  async syncOneTool(targetToolId, sourceConfig, sourceManifestFiles, sourceManifestMap, manifest, projectRoot, docsDir, force, includeUserFiles) {
+    const targetConfig = getToolConfig(targetToolId);
+    const targetManifestFiles = manifest.getToolFiles(targetToolId);
+    const targetManifestMap = new Map(targetManifestFiles.map((f) => [f.relativePath, f.hash]));
+    const targetByFrameworkPath = new Map(
+      targetManifestFiles.filter((f) => f.frameworkPath !== void 0).map((f) => [f.frameworkPath, f.relativePath])
     );
-    const totalSkipped = toolResults.reduce(
-      (s, t) => s + t.files.filter((f) => f.skipped).length,
-      0
+    const fileResults = [];
+    await this.propagateModified({
+      sourceManifestFiles,
+      sourceConfig,
+      targetConfig,
+      targetManifestMap,
+      targetByFrameworkPath,
+      fileResults,
+      projectRoot,
+      docsDir,
+      force
+    });
+    await this.propagateAdded({
+      sourceManifestMap,
+      sourceConfig,
+      targetConfig,
+      fileResults,
+      projectRoot,
+      docsDir,
+      includeUserFiles
+    });
+    await this.propagateDeleted({
+      sourceManifestFiles,
+      targetByFrameworkPath,
+      fileResults,
+      projectRoot,
+      docsDir
+    });
+    return { targetToolId, files: fileResults };
+  }
+  /** Resolves sourceTool and targetTools from options — prompts if interactive. */
+  async selectSyncScope(options, manifest, interactive) {
+    if (options.sourceTool !== void 0) {
+      return this.resolveExplicitScope(options, manifest);
+    }
+    return this.resolveInteractiveScope(manifest, interactive, options.projectRoot);
+  }
+  resolveExplicitScope(options, manifest) {
+    const sourceTool = options.sourceTool;
+    if (!manifest.hasTool(sourceTool)) {
+      throw new Error(`Source tool '${sourceTool}' is not installed.`);
+    }
+    const installedToolIds = manifest.getInstalledToolIds();
+    if (installedToolIds.length < 2) {
+      throw new Error("Sync requires at least 2 installed tools.");
+    }
+    const targetTools = options.targetTools && options.targetTools.length > 0 ? options.targetTools : installedToolIds.filter((id) => id !== sourceTool);
+    for (const target of targetTools) {
+      if (target === sourceTool) {
+        throw new Error("Source and target cannot be the same tool.");
+      }
+      if (!manifest.hasTool(target)) {
+        throw new Error(`Target tool '${target}' is not installed.`);
+      }
+    }
+    return { sourceTool, targetTools };
+  }
+  async resolveInteractiveScope(manifest, interactive, projectRoot) {
+    if (!interactive || this.prompter === void 0) {
+      throw new Error("Source tool required in non-interactive mode.");
+    }
+    const { SyncStatusUseCase: SyncStatusUseCase2 } = await Promise.resolve().then(() => (init_sync_status_use_case(), sync_status_use_case_exports));
+    const installedIds = manifest.getInstalledToolIds();
+    if (installedIds.length < 2) {
+      throw new Error("Sync requires at least 2 installed tools.");
+    }
+    const modCounts = await new SyncStatusUseCase2(this.fs).execute(
+      manifest,
+      installedIds,
+      projectRoot
     );
+    const hasAnyChanges = installedIds.some((id) => {
+      const { modified, deleted } = modCounts[id] ?? { modified: 0, deleted: 0 };
+      return modified > 0 || deleted > 0;
+    });
+    if (!hasAnyChanges) {
+      return { sourceTool: installedIds[0], targetTools: [] };
+    }
+    return this.promptSyncScope(installedIds, modCounts, this.prompter);
+  }
+  async promptSyncScope(installedIds, modCounts, prompter) {
+    const sourceChoices = installedIds.map((id) => {
+      const { modified, deleted } = modCounts[id] ?? { modified: 0, deleted: 0 };
+      const hasChanges = modified > 0 || deleted > 0;
+      const parts = [];
+      if (modified > 0) parts.push(`${modified} modified`);
+      if (deleted > 0) parts.push(`${deleted} deleted`);
+      const label = hasChanges ? ` (${parts.join(", ")})` : "";
+      return {
+        name: `${id}${label}`,
+        value: id,
+        disabled: hasChanges ? false : "(no changes)"
+      };
+    });
+    const sourceTool = await prompter.select("Source tool to sync from?", sourceChoices);
+    const targetChoices = installedIds.filter((id) => id !== sourceTool).map((id) => ({ name: id, value: id }));
+    const targetTools = await prompter.checkbox("Target tools?", targetChoices);
+    if (targetTools.length === 0) throw new Error("No target tools selected.");
+    return { sourceTool, targetTools };
+  }
+  buildSyncTotals(sourceTool, toolResults) {
+    const count = (pred) => toolResults.reduce((s, t) => s + t.files.filter(pred).length, 0);
     return {
       sourceTool,
       tools: toolResults,
-      totalWritten,
-      totalDeleted,
-      totalConflicts,
-      totalSkipped
+      totalWritten: count((f) => f.written),
+      totalDeleted: count((f) => Boolean(f.deleted)),
+      totalConflicts: count((f) => f.conflict && !f.written),
+      totalSkipped: count((f) => f.skipped)
     };
   }
   async propagateModified(ctx) {
@@ -5664,64 +5996,71 @@ var SyncUseCase = class {
       force
     } = ctx;
     for (const sourceManifestFile of sourceManifestFiles) {
-      const { relativePath, hash: manifestHash, frameworkPath } = sourceManifestFile;
-      if (isExcluded(relativePath, docsDir)) continue;
-      if (frameworkPath === void 0) continue;
-      const diskSourcePath = join26(projectRoot, relativePath);
-      if (!await this.fs.fileExists(diskSourcePath)) continue;
-      const diskSourceHash = await this.fs.readFileHash(diskSourcePath);
-      if (diskSourceHash.value === manifestHash.value) continue;
-      const sectionKey = getSectionKeyFromFrameworkPath(frameworkPath);
-      if (sectionKey === null) continue;
-      const targetRelativePath = targetByFrameworkPath.get(frameworkPath);
-      if (targetRelativePath === void 0) continue;
-      const diskSourceContent = await this.fs.readFile(diskSourcePath);
-      const targetContent = transformContent(
-        diskSourceContent,
+      await this.propagateOneModified(
+        sourceManifestFile,
         sourceConfig,
         targetConfig,
-        sectionKey,
-        docsDir
+        targetManifestMap,
+        targetByFrameworkPath,
+        fileResults,
+        projectRoot,
+        docsDir,
+        force
       );
-      const diskTargetPath = join26(projectRoot, targetRelativePath);
-      const diskTargetExists = await this.fs.fileExists(diskTargetPath);
-      let conflict = false;
-      if (diskTargetExists) {
-        const diskTargetHash = await this.fs.readFileHash(diskTargetPath);
-        const targetManifestHash = targetManifestMap.get(targetRelativePath);
-        if (targetManifestHash !== void 0 && diskTargetHash.value !== targetManifestHash.value) {
-          conflict = true;
-        }
-      }
-      if (diskTargetExists) {
-        const currentTargetContent = await this.fs.readFile(diskTargetPath);
-        if (currentTargetContent === targetContent) {
-          fileResults.push({
-            relativePath: targetRelativePath,
-            conflict: false,
-            skipped: true,
-            written: false
-          });
-          continue;
-        }
-      }
-      if (conflict && !force) {
-        fileResults.push({
-          relativePath: targetRelativePath,
-          conflict: true,
-          skipped: false,
-          written: false
-        });
-        continue;
-      }
-      await this.fs.writeFile(diskTargetPath, targetContent);
+    }
+  }
+  async propagateOneModified(sourceManifestFile, sourceConfig, targetConfig, targetManifestMap, targetByFrameworkPath, fileResults, projectRoot, docsDir, force) {
+    const { relativePath, hash: manifestHash, frameworkPath } = sourceManifestFile;
+    if (isSyncExcluded(relativePath, docsDir) || frameworkPath === void 0) return;
+    const diskSourcePath = join26(projectRoot, relativePath);
+    if (!await this.fs.fileExists(diskSourcePath)) return;
+    const diskSourceHash = await this.fs.readFileHash(diskSourcePath);
+    if (diskSourceHash.value === manifestHash.value) return;
+    const sectionKey = getSectionKeyFromFrameworkPath(frameworkPath);
+    const targetRelativePath = targetByFrameworkPath.get(frameworkPath);
+    if (sectionKey === null || targetRelativePath === void 0) return;
+    const diskSourceContent = await this.fs.readFile(diskSourcePath);
+    const targetContent = transformContent(
+      diskSourceContent,
+      sourceConfig,
+      targetConfig,
+      sectionKey,
+      docsDir
+    );
+    const diskTargetPath = join26(projectRoot, targetRelativePath);
+    const diskTargetExists = await this.fs.fileExists(diskTargetPath);
+    const conflict = await this.detectTargetConflict(
+      diskTargetExists,
+      diskTargetPath,
+      targetRelativePath,
+      targetManifestMap
+    );
+    if (diskTargetExists && await this.fs.readFile(diskTargetPath) === targetContent) {
+      fileResults.push({
+        relativePath: targetRelativePath,
+        conflict: false,
+        skipped: true,
+        written: false
+      });
+      return;
+    }
+    if (conflict && !force) {
       fileResults.push({
         relativePath: targetRelativePath,
-        conflict,
+        conflict: true,
         skipped: false,
-        written: true
+        written: false
       });
+      return;
     }
+    await this.fs.writeFile(diskTargetPath, targetContent);
+    fileResults.push({ relativePath: targetRelativePath, conflict, skipped: false, written: true });
+  }
+  async detectTargetConflict(diskTargetExists, diskTargetPath, targetRelativePath, targetManifestMap) {
+    if (!diskTargetExists) return false;
+    const diskTargetHash = await this.fs.readFileHash(diskTargetPath);
+    const targetManifestHash = targetManifestMap.get(targetRelativePath);
+    return targetManifestHash !== void 0 && diskTargetHash.value !== targetManifestHash.value;
   }
   async propagateAdded(ctx) {
     const {
@@ -5738,65 +6077,80 @@ var SyncUseCase = class {
     if (!sourceDirExists) return;
     const sourceDiskFiles = await this.fs.listDirectory(join26(projectRoot, sourceConfig.directory));
     for (const diskRelative of sourceDiskFiles) {
-      const sourceRelativePath = `${sourceConfig.directory}${diskRelative}`;
-      if (isExcluded(sourceRelativePath, docsDir)) continue;
-      if (sourceManifestMap.has(sourceRelativePath)) continue;
-      const sectionKey = sourceConfig.detectUserFileSectionKey(sourceRelativePath);
-      if (sectionKey === null) continue;
-      const targetRelativePath = buildTargetPath(targetConfig, sectionKey);
-      if (targetRelativePath === null) continue;
-      const diskSourceContent = await this.fs.readFile(join26(projectRoot, sourceRelativePath));
-      const targetContent = transformContent(
-        diskSourceContent,
+      await this.propagateOneAdded(
+        diskRelative,
+        sourceManifestMap,
         sourceConfig,
         targetConfig,
-        sectionKey,
+        fileResults,
+        projectRoot,
         docsDir
       );
-      const diskTargetPath = join26(projectRoot, targetRelativePath);
-      const diskTargetExists = await this.fs.fileExists(diskTargetPath);
-      if (diskTargetExists) {
-        const current = await this.fs.readFile(diskTargetPath);
-        if (current === targetContent) {
-          fileResults.push({
-            relativePath: targetRelativePath,
-            conflict: false,
-            skipped: true,
-            written: false
-          });
-          continue;
-        }
-      }
-      await this.fs.writeFile(diskTargetPath, targetContent);
+    }
+  }
+  async propagateOneAdded(diskRelative, sourceManifestMap, sourceConfig, targetConfig, fileResults, projectRoot, docsDir) {
+    const sourceRelativePath = `${sourceConfig.directory}${diskRelative}`;
+    if (isSyncExcluded(sourceRelativePath, docsDir) || sourceManifestMap.has(sourceRelativePath))
+      return;
+    const sectionKey = sourceConfig.detectUserFileSectionKey(sourceRelativePath);
+    if (sectionKey === null) return;
+    const targetRelativePath = buildTargetPath(targetConfig, sectionKey);
+    if (targetRelativePath === null) return;
+    const diskSourceContent = await this.fs.readFile(join26(projectRoot, sourceRelativePath));
+    const targetContent = transformContent(
+      diskSourceContent,
+      sourceConfig,
+      targetConfig,
+      sectionKey,
+      docsDir
+    );
+    const diskTargetPath = join26(projectRoot, targetRelativePath);
+    if (await this.fs.fileExists(diskTargetPath) && await this.fs.readFile(diskTargetPath) === targetContent) {
       fileResults.push({
         relativePath: targetRelativePath,
         conflict: false,
-        skipped: false,
-        written: true
+        skipped: true,
+        written: false
       });
+      return;
     }
+    await this.fs.writeFile(diskTargetPath, targetContent);
+    fileResults.push({
+      relativePath: targetRelativePath,
+      conflict: false,
+      skipped: false,
+      written: true
+    });
   }
   async propagateDeleted(ctx) {
     const { sourceManifestFiles, targetByFrameworkPath, fileResults, projectRoot, docsDir } = ctx;
     for (const sourceManifestFile of sourceManifestFiles) {
-      const { relativePath, frameworkPath } = sourceManifestFile;
-      if (isExcluded(relativePath, docsDir)) continue;
-      if (frameworkPath === void 0) continue;
-      if (await this.fs.fileExists(join26(projectRoot, relativePath))) continue;
-      const targetRelativePath = targetByFrameworkPath.get(frameworkPath);
-      if (targetRelativePath === void 0) continue;
-      const diskTargetPath = join26(projectRoot, targetRelativePath);
-      if (!await this.fs.fileExists(diskTargetPath)) continue;
-      await this.fs.deleteFile(diskTargetPath);
-      fileResults.push({
-        relativePath: targetRelativePath,
-        conflict: false,
-        skipped: false,
-        written: false,
-        deleted: true
-      });
+      await this.propagateOneDeleted(
+        sourceManifestFile,
+        targetByFrameworkPath,
+        fileResults,
+        projectRoot,
+        docsDir
+      );
     }
   }
+  async propagateOneDeleted(sourceManifestFile, targetByFrameworkPath, fileResults, projectRoot, docsDir) {
+    const { relativePath, frameworkPath } = sourceManifestFile;
+    if (isSyncExcluded(relativePath, docsDir) || frameworkPath === void 0) return;
+    if (await this.fs.fileExists(join26(projectRoot, relativePath))) return;
+    const targetRelativePath = targetByFrameworkPath.get(frameworkPath);
+    if (targetRelativePath === void 0) return;
+    const diskTargetPath = join26(projectRoot, targetRelativePath);
+    if (!await this.fs.fileExists(diskTargetPath)) return;
+    await this.fs.deleteFile(diskTargetPath);
+    fileResults.push({
+      relativePath: targetRelativePath,
+      conflict: false,
+      skipped: false,
+      written: false,
+      deleted: true
+    });
+  }
 };
 
 // src/application/commands/sync.ts
@@ -6212,6 +6566,230 @@ var BannerUseCase = class {
   }
 };
 
+// src/application/use-cases/interactive-menu-use-case.ts
+function isBranch(node) {
+  return "children" in node;
+}
+function toChoice(node) {
+  return { name: node.name, value: node.value, description: node.description };
+}
+var FRESH_NODES = [
+  {
+    name: "Install AIDD in this project",
+    value: "setup",
+    description: "Set up the AI-Driven Development framework",
+    command: ["setup"]
+  }
+];
+var INSTALLED_NODES = [
+  {
+    name: "Inspect",
+    value: "inspect",
+    description: "Check status, health and drift detection",
+    children: [
+      {
+        name: "Status",
+        value: "status",
+        description: "Show installed files and detect drift",
+        command: ["status"]
+      },
+      {
+        name: "Doctor",
+        value: "doctor",
+        description: "Run a structural health check",
+        command: ["doctor"]
+      }
+    ]
+  },
+  {
+    name: "Manage tools",
+    value: "manage-tools",
+    description: "Install, remove and sync AI tools",
+    children: [
+      {
+        name: "Install",
+        value: "install",
+        description: "Add AI tools to this project",
+        command: ["install"]
+      },
+      {
+        name: "Uninstall",
+        value: "uninstall",
+        description: "Remove installed tools",
+        command: ["uninstall"]
+      },
+      {
+        name: "Sync",
+        value: "sync",
+        description: "Propagate changes across installed tools",
+        command: ["sync"]
+      }
+    ]
+  },
+  {
+    name: "Maintain & repair",
+    value: "maintain",
+    description: "Update, restore and clean your files",
+    children: [
+      {
+        name: "Update",
+        value: "update",
+        description: "Pull the latest framework version",
+        command: ["update"]
+      },
+      {
+        name: "Restore",
+        value: "restore",
+        description: "Restore modified or deleted tracked files",
+        command: ["restore"]
+      },
+      {
+        name: "Clean",
+        value: "clean",
+        description: "Remove untracked or orphaned files",
+        command: ["clean"]
+      }
+    ]
+  },
+  {
+    name: "System",
+    value: "system",
+    description: "CLI updates, configuration and cache",
+    children: [
+      {
+        name: "Self-update",
+        value: "self-update",
+        description: "Update the AIDD CLI binary",
+        command: ["self-update"]
+      },
+      {
+        name: "Config",
+        value: "config",
+        description: "View or edit project settings",
+        children: [
+          {
+            name: "Show all settings",
+            value: "list",
+            description: "List all config values",
+            command: ["config", "list"]
+          },
+          {
+            name: "Get a value",
+            value: "get",
+            description: "Read a specific config key",
+            children: [
+              { name: "Docs directory", value: "docsDir", command: ["config", "get", "docsDir"] },
+              { name: "Repository", value: "repo", command: ["config", "get", "repo"] },
+              { name: "Installed tools", value: "tools", command: ["config", "get", "tools"] }
+            ]
+          },
+          {
+            name: "Set docs directory",
+            value: "set-docs",
+            description: "Change the docs folder name",
+            command: ["config", "set", "docsDir"],
+            inputPrompt: "New value for docsDir",
+            commandSuffix: ["--force"]
+          },
+          {
+            name: "Set repository",
+            value: "set-repo",
+            description: "Change the framework repository",
+            command: ["config", "set", "repo"],
+            inputPrompt: "New value for repo",
+            commandSuffix: ["--force"]
+          }
+        ]
+      },
+      {
+        name: "Cache",
+        value: "cache",
+        description: "Manage cached framework versions",
+        children: [
+          {
+            name: "List cached versions",
+            value: "list",
+            description: "Show all cached framework versions",
+            command: ["cache", "list"]
+          },
+          {
+            name: "Clear a specific version",
+            value: "clear-version",
+            description: "Remove one cached version",
+            command: ["cache", "clear"],
+            inputPrompt: "Version to clear (e.g. v3.2.0)"
+          },
+          {
+            name: "Clear all versions",
+            value: "clear-all",
+            description: "Remove all cached versions",
+            command: ["cache", "clear", "--all"]
+          }
+        ]
+      }
+    ]
+  }
+];
+var BACK = { name: "\u2190 Back", value: "back" };
+var EXIT = { name: "Exit", value: "exit" };
+var InteractiveMenuUseCase = class {
+  constructor(manifestRepo, prompter) {
+    this.manifestRepo = manifestRepo;
+    this.prompter = prompter;
+  }
+  async execute(options) {
+    const manifest = await this.manifestRepo.load();
+    const rootNodes = manifest === null ? FRESH_NODES : INSTALLED_NODES;
+    const result = await this.navigateFrom(
+      rootNodes,
+      "What would you like to do?",
+      options?.startAt ?? [],
+      []
+    );
+    if (result.type !== "command") return { command: ["exit"] };
+    return {
+      command: result.command,
+      returnTo: result.returnTo.length > 0 ? result.returnTo : void 0
+    };
+  }
+  async navigateFrom(nodes, label, path, breadcrumb) {
+    if (path.length > 0) {
+      const [head, ...tail] = path;
+      const node = nodes.find((n) => n.value === head);
+      if (node && isBranch(node)) {
+        const result = await this.navigateFrom(node.children, node.name, tail, [
+          ...breadcrumb,
+          node.value
+        ]);
+        if (result.type === "back") return this.showMenu(nodes, label, breadcrumb);
+        return result;
+      }
+    }
+    return this.showMenu(nodes, label, breadcrumb);
+  }
+  async showMenu(nodes, label, breadcrumb) {
+    const nav = breadcrumb.length > 0 ? [BACK, EXIT] : [EXIT];
+    const picked = await this.prompter.select(label, [...nodes.map(toChoice), ...nav]);
+    if (picked === "exit") return { type: "exit" };
+    if (picked === "back") return { type: "back" };
+    const node = nodes.find((n) => n.value === picked);
+    if (!node) return { type: "exit" };
+    if (isBranch(node)) {
+      const result = await this.showMenu(node.children, node.name, [...breadcrumb, node.value]);
+      if (result.type === "back") return this.showMenu(nodes, label, breadcrumb);
+      return result;
+    }
+    return { type: "command", command: await this.resolveCommand(node), returnTo: breadcrumb };
+  }
+  async resolveCommand(node) {
+    if (node.inputPrompt !== void 0) {
+      const input2 = await this.prompter.input(node.inputPrompt);
+      return [...node.command, input2, ...node.commandSuffix ?? []];
+    }
+    return node.command;
+  }
+};
+
 // src/cli.ts
 function formatVersion(version) {
   return `aidd/${version} node/${process.versions.node} ${platform2()}-${process.arch}`;
@@ -6253,8 +6831,37 @@ program.hook("preAction", async (_thisCommand, actionCommand) => {
     );
   }
 });
-var args = process.argv.slice(2);
-if (args.length === 0 || args.includes("--help") || args.includes("-h")) {
+var cliArgs = process.argv.slice(2);
+if (cliArgs.length === 0 || cliArgs.includes("--help") || cliArgs.includes("-h")) {
   await new BannerUseCase().execute();
 }
-program.parse(process.argv);
+if (cliArgs.length === 0 && process.stdout.isTTY) {
+  runMenuLoop();
+} else {
+  program.parse(process.argv);
+}
+async function runMenuLoop() {
+  const { manifestRepo, prompter } = createMenuDeps(process.cwd());
+  let returnTo;
+  for (; ; ) {
+    try {
+      const result = await new InteractiveMenuUseCase(manifestRepo, prompter).execute({
+        startAt: returnTo
+      });
+      if (result.command[0] === "exit") process.exit(0);
+      returnTo = result.returnTo;
+      await spawnCliCommand(result.command);
+    } catch (error) {
+      if (error instanceof Error && error.name === "ExitPromptError") process.exit(0);
+      returnTo = void 0;
+    }
+  }
+}
+function spawnCliCommand(command) {
+  return new Promise((resolve) => {
+    spawn(process.execPath, [process.argv[1], ...command], { stdio: "inherit" }).on(
+      "close",
+      resolve
+    );
+  });
+}