bmad-method 6.0.0-alpha.9 → 6.0.1

package/tools/cli/installers/lib/core/installer.js

@@ -1,7 +1,5 @@
 const path = require('node:path');
 const fs = require('fs-extra');
-const chalk = require('chalk');
-const ora = require('ora');
 const { Detector } = require('./detector');
 const { Manifest } = require('./manifest');
 const { ModuleManager } = require('../modules/manager');
@@ -11,12 +9,13 @@ const { Config } = require('../../../lib/config');
 const { XmlHandler } = require('../../../lib/xml-handler');
 const { DependencyResolver } = require('./dependency-resolver');
 const { ConfigCollector } = require('./config-collector');
-// processInstallation no longer needed - LLMs understand {project-root}
 const { getProjectRoot, getSourcePath, getModulePath } = require('../../../lib/project-root');
-const { AgentPartyGenerator } = require('../../../lib/agent-party-generator');
 const { CLIUtils } = require('../../../lib/cli-utils');
 const { ManifestGenerator } = require('./manifest-generator');
 const { IdeConfigManager } = require('./ide-config-manager');
+const { CustomHandler } = require('../custom/handler');
+const prompts = require('../../../lib/prompts');
+const { BMAD_FOLDER_NAME } = require('../ide/shared/path-utils');
 
 class Installer {
   constructor() {
@@ -30,53 +29,58 @@ class Installer {
     this.dependencyResolver = new DependencyResolver();
     this.configCollector = new ConfigCollector();
     this.ideConfigManager = new IdeConfigManager();
-    this.installedFiles = []; // Track all installed files
+    this.installedFiles = new Set(); // Track all installed files
+    this.bmadFolderName = BMAD_FOLDER_NAME;
   }
 
   /**
    * Find the bmad installation directory in a project
-   * V6+ installations can use ANY folder name but ALWAYS have _cfg/manifest.yaml
+   * Always uses the standard _bmad folder name
+   * Also checks for legacy _cfg folder for migration
    * @param {string} projectDir - Project directory
-   * @returns {Promise<string>} Path to bmad directory
+   * @returns {Promise<Object>} { bmadDir: string, hasLegacyCfg: boolean }
    */
   async findBmadDir(projectDir) {
+    const bmadDir = path.join(projectDir, BMAD_FOLDER_NAME);
+
     // Check if project directory exists
     if (!(await fs.pathExists(projectDir))) {
       // Project doesn't exist yet, return default
-      return path.join(projectDir, 'bmad');
+      return { bmadDir, hasLegacyCfg: false };
     }
 
-    // V6+ strategy: Look for ANY directory with _cfg/manifest.yaml
-    // This is the definitive marker of a V6+ installation
-    try {
-      const entries = await fs.readdir(projectDir, { withFileTypes: true });
-      for (const entry of entries) {
-        if (entry.isDirectory()) {
-          const manifestPath = path.join(projectDir, entry.name, '_cfg', 'manifest.yaml');
-          if (await fs.pathExists(manifestPath)) {
-            // Found a V6+ installation
-            return path.join(projectDir, entry.name);
-          }
-        }
+    // Check for legacy _cfg folder if bmad directory exists
+    let hasLegacyCfg = false;
+    if (await fs.pathExists(bmadDir)) {
+      const legacyCfgPath = path.join(bmadDir, '_cfg');
+      if (await fs.pathExists(legacyCfgPath)) {
+        hasLegacyCfg = true;
       }
-    } catch {
-      // Ignore errors, fall through to default
     }
 
-    // No V6+ installation found, return default
-    // This will be used for new installations
-    return path.join(projectDir, 'bmad');
+    return { bmadDir, hasLegacyCfg };
   }
 
   /**
-   * Copy a file and replace {bmad_folder} placeholder with actual folder name
-   * @param {string} sourcePath - Source file path
-   * @param {string} targetPath - Target file path
-   * @param {string} bmadFolderName - The bmad folder name to use for replacement
+   * @function copyFileWithPlaceholderReplacement
+   * @intent Copy files from BMAD source to installation directory with dynamic content transformation
+   * @why Enables installation-time customization: _bmad replacement
+   * @param {string} sourcePath - Absolute path to source file in BMAD repository
+   * @param {string} targetPath - Absolute path to destination file in user's project
+   * @param {string} bmadFolderName - User's chosen bmad folder name (default: 'bmad')
+   * @returns {Promise<void>} Resolves when file copy and transformation complete
+   * @sideeffects Writes transformed file to targetPath, creates parent directories if needed
+   * @edgecases Binary files bypass transformation, falls back to raw copy if UTF-8 read fails
+   * @calledby installCore(), installModule(), IDE installers during file vendoring
+   * @calls fs.readFile(), fs.writeFile(), fs.copy()
+   *
+
+   *
+   * 3. Document marker in instructions.md (if applicable)
    */
-  async copyFileWithPlaceholderReplacement(sourcePath, targetPath, bmadFolderName) {
+  async copyFileWithPlaceholderReplacement(sourcePath, targetPath) {
     // List of text file extensions that should have placeholder replacement
-    const textExtensions = ['.md', '.yaml', '.yml', '.txt', '.json', '.js', '.ts', '.html', '.css', '.sh', '.bat', '.csv'];
+    const textExtensions = ['.md', '.yaml', '.yml', '.txt', '.json', '.js', '.ts', '.html', '.css', '.sh', '.bat', '.csv', '.xml'];
     const ext = path.extname(sourcePath).toLowerCase();
 
     // Check if this is a text file that might contain placeholders
@@ -85,11 +89,6 @@ class Installer {
         // Read the file content
         let content = await fs.readFile(sourcePath, 'utf8');
 
-        // Replace {bmad_folder} placeholder with actual folder name
-        if (content.includes('{bmad_folder}')) {
-          content = content.replaceAll('{bmad_folder}', bmadFolderName);
-        }
-
         // Write to target with replaced content
         await fs.ensureDir(path.dirname(targetPath));
         await fs.writeFile(targetPath, content, 'utf8');
@@ -110,16 +109,24 @@ class Installer {
    * @param {boolean} isFullReinstall - Whether this is a full reinstall
    * @param {Array} previousIdes - Previously configured IDEs (for reinstalls)
    * @param {Array} preSelectedIdes - Pre-selected IDEs from early prompt (optional)
+   * @param {boolean} skipPrompts - Skip prompts and use defaults (for --yes flag)
    * @returns {Object} Tool/IDE selection and configurations
    */
-  async collectToolConfigurations(projectDir, selectedModules, isFullReinstall = false, previousIdes = [], preSelectedIdes = null) {
+  async collectToolConfigurations(
+    projectDir,
+    selectedModules,
+    isFullReinstall = false,
+    previousIdes = [],
+    preSelectedIdes = null,
+    skipPrompts = false,
+  ) {
     // Use pre-selected IDEs if provided, otherwise prompt
     let toolConfig;
     if (preSelectedIdes === null) {
       // Fallback: prompt for tool selection (backwards compatibility)
       const { UI } = require('../../../lib/ui');
       const ui = new UI();
-      toolConfig = await ui.promptToolSelection(projectDir, selectedModules);
+      toolConfig = await ui.promptToolSelection(projectDir);
     } else {
       // IDEs were already selected during initial prompts
       toolConfig = {
@@ -131,7 +138,7 @@ class Installer {
     // Check for already configured IDEs
     const { Detector } = require('./detector');
     const detector = new Detector();
-    const bmadDir = path.join(projectDir, this.bmadFolderName || 'bmad');
+    const bmadDir = path.join(projectDir, BMAD_FOLDER_NAME);
 
     // During full reinstall, use the saved previous IDEs since bmad dir was deleted
     // Otherwise detect from existing installation
@@ -158,54 +165,40 @@ class Installer {
     }
 
     if (!toolConfig.skipIde && toolConfig.ides && toolConfig.ides.length > 0) {
+      // Ensure IDE manager is initialized
+      await this.ideManager.ensureInitialized();
+
       // Determine which IDEs are newly selected (not previously configured)
       const newlySelectedIdes = toolConfig.ides.filter((ide) => !previouslyConfiguredIdes.includes(ide));
 
       if (newlySelectedIdes.length > 0) {
-        console.log('\n'); // Add spacing before IDE questions
-
+        // Collect configuration for IDEs that support it
         for (const ide of newlySelectedIdes) {
-          // List of IDEs that have interactive prompts
-          const needsPrompts = ['claude-code', 'github-copilot', 'roo', 'cline', 'auggie', 'codex', 'qwen', 'gemini'].includes(ide);
-
-          if (needsPrompts) {
-            // Get IDE handler and collect configuration
-            try {
-              // Dynamically load the IDE setup module
-              const ideModule = require(`../ide/${ide}`);
-
-              // Get the setup class (handle different export formats)
-              let SetupClass;
-              const className =
-                ide
-                  .split('-')
-                  .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
-                  .join('') + 'Setup';
-
-              if (ideModule[className]) {
-                SetupClass = ideModule[className];
-              } else if (ideModule.default) {
-                SetupClass = ideModule.default;
-              } else {
-                // Skip if no setup class found
-                continue;
-              }
+          try {
+            const handler = this.ideManager.handlers.get(ide);
 
-              const ideSetup = new SetupClass();
+            if (!handler) {
+              await prompts.log.warn(`Warning: IDE '${ide}' handler not found`);
+              continue;
+            }
 
-              // Check if this IDE has a collectConfiguration method
-              if (typeof ideSetup.collectConfiguration === 'function') {
-                console.log(chalk.cyan(`\nConfiguring ${ide}...`));
-                ideConfigurations[ide] = await ideSetup.collectConfiguration({
-                  selectedModules: selectedModules || [],
-                  projectDir,
-                  bmadDir,
-                });
-              }
-            } catch {
-              // IDE doesn't have a setup file or collectConfiguration method
-              console.warn(chalk.yellow(`Warning: Could not load configuration for ${ide}`));
+            // Check if this IDE handler has a collectConfiguration method
+            // (custom installers like Codex, Kilo may have this)
+            if (typeof handler.collectConfiguration === 'function') {
+              await prompts.log.info(`Configuring ${ide}...`);
+              ideConfigurations[ide] = await handler.collectConfiguration({
+                selectedModules: selectedModules || [],
+                projectDir,
+                bmadDir,
+                skipPrompts,
+              });
+            } else {
+              // Config-driven IDEs don't need configuration - mark as ready
+              ideConfigurations[ide] = { _noConfigNeeded: true };
             }
+          } catch (error) {
+            // IDE doesn't support configuration or has an error
+            await prompts.log.warn(`Warning: Could not load configuration for ${ide}: ${error.message}`);
           }
         }
       }
@@ -213,7 +206,7 @@ class Installer {
       // Log which IDEs are already configured and being kept
       const keptIdes = toolConfig.ides.filter((ide) => previouslyConfiguredIdes.includes(ide));
       if (keptIdes.length > 0) {
-        console.log(chalk.dim(`\nKeeping existing configuration for: ${keptIdes.join(', ')}`));
+        await prompts.log.message(`Keeping existing configuration for: ${keptIdes.join(', ')}`);
       }
     }
 
@@ -233,20 +226,30 @@ class Installer {
    * @param {string[]} config.ides - IDEs to configure
    * @param {boolean} config.skipIde - Skip IDE configuration
    */
-  async install(config) {
-    // Display BMAD logo
-    CLIUtils.displayLogo();
+  async install(originalConfig) {
+    // Clone config to avoid mutating the caller's object
+    const config = { ...originalConfig };
+
+    // Check if core config was already collected in UI
+    const hasCoreConfig = config.coreConfig && Object.keys(config.coreConfig).length > 0;
 
-    // Display welcome message
-    CLIUtils.displaySection('BMAD™ Installation', 'Version ' + require(path.join(getProjectRoot(), 'package.json')).version);
+    // Only display logo if core config wasn't already collected (meaning we're not continuing from UI)
+    if (!hasCoreConfig) {
+      // Display BMAD logo
+      await CLIUtils.displayLogo();
+
+      // Display welcome message
+      await CLIUtils.displaySection('BMad™  Installation', 'Version ' + require(path.join(getProjectRoot(), 'package.json')).version);
+    }
 
     // Note: Legacy V4 detection now happens earlier in UI.promptInstall()
     // before any config collection, so we don't need to check again here
 
     const projectDir = path.resolve(config.directory);
+    const bmadDir = path.join(projectDir, BMAD_FOLDER_NAME);
 
     // If core config was pre-collected (from interactive mode), use it
-    if (config.coreConfig) {
+    if (config.coreConfig && Object.keys(config.coreConfig).length > 0) {
       this.configCollector.collectedConfig.core = config.coreConfig;
       // Also store in allAnswers for cross-referencing
       this.configCollector.allAnswers = {};
@@ -257,190 +260,307 @@ class Installer {
 
     // Collect configurations for modules (skip if quick update already collected them)
     let moduleConfigs;
+    let customModulePaths = new Map();
+
     if (config._quickUpdate) {
       // Quick update already collected all configs, use them directly
       moduleConfigs = this.configCollector.collectedConfig;
-    } else {
-      // Regular install - collect configurations (core was already collected in UI.promptInstall if interactive)
-      moduleConfigs = await this.configCollector.collectAllConfigurations(config.modules || [], path.resolve(config.directory));
-    }
-
-    // Get bmad_folder from config (default to 'bmad' for backwards compatibility)
-    const bmadFolderName = moduleConfigs.core && moduleConfigs.core.bmad_folder ? moduleConfigs.core.bmad_folder : 'bmad';
-    this.bmadFolderName = bmadFolderName; // Store for use in other methods
-
-    // Set bmad folder name on module manager and IDE manager for placeholder replacement
-    this.moduleManager.setBmadFolderName(bmadFolderName);
-    this.ideManager.setBmadFolderName(bmadFolderName);
 
-    // Tool selection will be collected after we determine if it's a reinstall/update/new install
+      // For quick update, populate customModulePaths from _customModuleSources
+      if (config._customModuleSources) {
+        for (const [moduleId, customInfo] of config._customModuleSources) {
+          customModulePaths.set(moduleId, customInfo.sourcePath);
+        }
+      }
+    } else {
+      // For regular updates (modify flow), check manifest for custom module sources
+      if (config._isUpdate && config._existingInstall && config._existingInstall.customModules) {
+        for (const customModule of config._existingInstall.customModules) {
+          // Ensure we have an absolute sourcePath
+          let absoluteSourcePath = customModule.sourcePath;
+
+          // Check if sourcePath is a cache-relative path (starts with _config)
+          if (absoluteSourcePath && absoluteSourcePath.startsWith('_config')) {
+            // Convert cache-relative path to absolute path
+            absoluteSourcePath = path.join(bmadDir, absoluteSourcePath);
+          }
+          // If no sourcePath but we have relativePath, convert it
+          else if (!absoluteSourcePath && customModule.relativePath) {
+            // relativePath is relative to the project root (parent of bmad dir)
+            absoluteSourcePath = path.resolve(projectDir, customModule.relativePath);
+          }
+          // Ensure sourcePath is absolute for anything else
+          else if (absoluteSourcePath && !path.isAbsolute(absoluteSourcePath)) {
+            absoluteSourcePath = path.resolve(absoluteSourcePath);
+          }
 
-    const spinner = ora('Preparing installation...').start();
+          if (absoluteSourcePath) {
+            customModulePaths.set(customModule.id, absoluteSourcePath);
+          }
+        }
+      }
 
-    try {
-      // Resolve target directory (path.resolve handles platform differences)
-      const projectDir = path.resolve(config.directory);
+      // Build custom module paths map from customContent
 
-      // Check if bmad_folder has changed from existing installation (only if project dir exists)
-      let existingBmadDir = null;
-      let existingBmadFolderName = null;
+      // Handle selectedFiles (from existing install path or manual directory input)
+      if (config.customContent && config.customContent.selected && config.customContent.selectedFiles) {
+        const customHandler = new CustomHandler();
+        for (const customFile of config.customContent.selectedFiles) {
+          const customInfo = await customHandler.getCustomInfo(customFile, path.resolve(config.directory));
+          if (customInfo && customInfo.id) {
+            customModulePaths.set(customInfo.id, customInfo.path);
+          }
+        }
+      }
 
-      if (await fs.pathExists(projectDir)) {
-        existingBmadDir = await this.findBmadDir(projectDir);
-        existingBmadFolderName = path.basename(existingBmadDir);
+      // Handle new custom content sources from UI
+      if (config.customContent && config.customContent.sources) {
+        for (const source of config.customContent.sources) {
+          customModulePaths.set(source.id, source.path);
+        }
       }
 
-      const targetBmadDir = path.join(projectDir, bmadFolderName);
+      // Handle cachedModules (from new install path where modules are cached)
+      // Only include modules that were actually selected for installation
+      if (config.customContent && config.customContent.cachedModules) {
+        // Get selected cached module IDs (if available)
+        const selectedCachedIds = config.customContent.selectedCachedModules || [];
+        // If no selection info, include all cached modules (for backward compatibility)
+        const shouldIncludeAll = selectedCachedIds.length === 0 && config.customContent.selected;
+
+        for (const cachedModule of config.customContent.cachedModules) {
+          // For cached modules, the path is the cachePath which contains the module.yaml
+          if (
+            cachedModule.id &&
+            cachedModule.cachePath && // Include if selected or if we should include all
+            (shouldIncludeAll || selectedCachedIds.includes(cachedModule.id))
+          ) {
+            customModulePaths.set(cachedModule.id, cachedModule.cachePath);
+          }
+        }
+      }
 
-      // If bmad_folder changed during update/upgrade, back up old folder and do fresh install
-      if (existingBmadDir && (await fs.pathExists(existingBmadDir)) && existingBmadFolderName !== bmadFolderName) {
-        spinner.stop();
-        console.log(chalk.yellow(`\n⚠️  bmad_folder has changed: ${existingBmadFolderName} → ${bmadFolderName}`));
-        console.log(chalk.yellow('This will result in a fresh installation to the new folder.'));
+      // Get list of all modules including custom modules
+      // Order: core first, then official modules, then custom modules
+      const allModulesForConfig = ['core'];
 
-        const inquirer = require('inquirer');
-        const { confirmFreshInstall } = await inquirer.prompt([
-          {
-            type: 'confirm',
-            name: 'confirmFreshInstall',
-            message: chalk.cyan('Proceed with fresh install? (Your old folder will be backed up)'),
-            default: true,
-          },
-        ]);
+      // Add official modules (excluding core and any custom modules)
+      const officialModules = (config.modules || []).filter((m) => m !== 'core' && !customModulePaths.has(m));
+      allModulesForConfig.push(...officialModules);
 
-        if (!confirmFreshInstall) {
-          console.log(chalk.yellow('Installation cancelled.'));
-          return { success: false, cancelled: true };
+      // Add custom modules at the end
+      for (const [moduleId] of customModulePaths) {
+        if (!allModulesForConfig.includes(moduleId)) {
+          allModulesForConfig.push(moduleId);
         }
+      }
 
-        spinner.start('Backing up existing installation...');
-
-        // Find a unique backup name
-        let backupDir = `${existingBmadDir}-bak`;
-        let counter = 1;
-        while (await fs.pathExists(backupDir)) {
-          backupDir = `${existingBmadDir}-bak-${counter}`;
-          counter++;
-        }
+      // Check if core was already collected in UI
+      if (config.coreConfig && Object.keys(config.coreConfig).length > 0) {
+        // Core already collected, skip it in config collection
+        const modulesWithoutCore = allModulesForConfig.filter((m) => m !== 'core');
+        moduleConfigs = await this.configCollector.collectAllConfigurations(modulesWithoutCore, path.resolve(config.directory), {
+          customModulePaths,
+          skipPrompts: config.skipPrompts,
+        });
+      } else {
+        // Core not collected yet, include it
+        moduleConfigs = await this.configCollector.collectAllConfigurations(allModulesForConfig, path.resolve(config.directory), {
+          customModulePaths,
+          skipPrompts: config.skipPrompts,
+        });
+      }
+    }
 
-        // Rename the old folder to backup
-        await fs.move(existingBmadDir, backupDir);
+    // Set bmad folder name on module manager and IDE manager for placeholder replacement
+    this.moduleManager.setBmadFolderName(BMAD_FOLDER_NAME);
+    this.moduleManager.setCoreConfig(moduleConfigs.core || {});
+    this.moduleManager.setCustomModulePaths(customModulePaths);
+    this.ideManager.setBmadFolderName(BMAD_FOLDER_NAME);
 
-        spinner.succeed(`Backed up ${existingBmadFolderName} → ${path.basename(backupDir)}`);
-        console.log(chalk.cyan('\n📋 Important:'));
-        console.log(chalk.dim(`  - Your old installation has been backed up to: ${path.basename(backupDir)}`));
-        console.log(chalk.dim(`  - If you had custom agents or configurations, copy them from:`));
-        console.log(chalk.dim(`    ${path.basename(backupDir)}/_cfg/`));
-        console.log(chalk.dim(`  - To the new location:`));
-        console.log(chalk.dim(`    ${bmadFolderName}/_cfg/`));
-        console.log('');
+    // Tool selection will be collected after we determine if it's a reinstall/update/new install
 
-        spinner.start('Starting fresh installation...');
-      }
+    const spinner = await prompts.spinner();
+    spinner.start('Preparing installation...');
 
+    try {
       // Create a project directory if it doesn't exist (user already confirmed)
       if (!(await fs.pathExists(projectDir))) {
-        spinner.text = 'Creating installation directory...';
+        spinner.message('Creating installation directory...');
         try {
           // fs.ensureDir handles platform-specific directory creation
           // It will recursively create all necessary parent directories
           await fs.ensureDir(projectDir);
         } catch (error) {
-          spinner.fail('Failed to create installation directory');
-          console.error(chalk.red(`Error: ${error.message}`));
+          spinner.error('Failed to create installation directory');
+          await prompts.log.error(`Error: ${error.message}`);
           // More detailed error for common issues
           if (error.code === 'EACCES') {
-            console.error(chalk.red('Permission denied. Check parent directory permissions.'));
+            await prompts.log.error('Permission denied. Check parent directory permissions.');
           } else if (error.code === 'ENOSPC') {
-            console.error(chalk.red('No space left on device.'));
+            await prompts.log.error('No space left on device.');
           }
           throw new Error(`Cannot create directory: ${projectDir}`);
         }
       }
 
-      const bmadDir = path.join(projectDir, bmadFolderName);
-
       // Check existing installation
-      spinner.text = 'Checking for existing installation...';
+      spinner.message('Checking for existing installation...');
       const existingInstall = await this.detector.detect(bmadDir);
 
       if (existingInstall.installed && !config.force && !config._quickUpdate) {
-        spinner.stop();
+        spinner.stop('Existing installation detected');
 
         // Check if user already decided what to do (from early menu in ui.js)
         let action = null;
-        if (config._requestedReinstall) {
-          action = 'reinstall';
-        } else if (config.actionType === 'update') {
+        if (config.actionType === 'update') {
+          action = 'update';
+        } else if (config.skipPrompts) {
+          // Non-interactive mode: default to update
           action = 'update';
         } else {
           // Fallback: Ask the user (backwards compatibility for other code paths)
-          console.log(chalk.yellow('\n⚠️  Existing BMAD installation detected'));
-          console.log(chalk.dim(`  Location: ${bmadDir}`));
-          console.log(chalk.dim(`  Version: ${existingInstall.version}`));
+          await prompts.log.warn('Existing BMAD installation detected');
+          await prompts.log.message(`  Location: ${bmadDir}`);
+          await prompts.log.message(`  Version: ${existingInstall.version}`);
 
           const promptResult = await this.promptUpdateAction();
           action = promptResult.action;
         }
 
-        if (action === 'cancel') {
-          console.log('Installation cancelled.');
-          return { success: false, cancelled: true };
-        }
+        if (action === 'update') {
+          // Store that we're updating for later processing
+          config._isUpdate = true;
+          config._existingInstall = existingInstall;
 
-        if (action === 'reinstall') {
-          // Warn about destructive operation
-          console.log(chalk.red.bold('\n⚠️  WARNING: This is a destructive operation!'));
-          console.log(chalk.red('All custom files and modifications in the bmad directory will be lost.'));
-
-          const inquirer = require('inquirer');
-          const { confirmReinstall } = await inquirer.prompt([
-            {
-              type: 'confirm',
-              name: 'confirmReinstall',
-              message: chalk.yellow('Are you sure you want to delete and reinstall?'),
-              default: false,
-            },
-          ]);
+          // Detect modules that were previously installed but are NOT in the new selection (to be removed)
+          const previouslyInstalledModules = new Set(existingInstall.modules.map((m) => m.id));
+          const newlySelectedModules = new Set(config.modules || []);
+
+          // Find modules to remove (installed but not in new selection)
+          // Exclude 'core' from being removable
+          const modulesToRemove = [...previouslyInstalledModules].filter((m) => !newlySelectedModules.has(m) && m !== 'core');
+
+          // If there are modules to remove, ask for confirmation
+          if (modulesToRemove.length > 0) {
+            if (config.skipPrompts) {
+              // Non-interactive mode: preserve modules (matches prompt default: false)
+              for (const moduleId of modulesToRemove) {
+                if (!config.modules) config.modules = [];
+                config.modules.push(moduleId);
+              }
+              spinner.start('Preparing update...');
+            } else {
+              if (spinner.isSpinning) {
+                spinner.stop('Module changes reviewed');
+              }
 
-          if (!confirmReinstall) {
-            console.log('Installation cancelled.');
-            return { success: false, cancelled: true };
-          }
+              await prompts.log.warn('Modules to be removed:');
+              for (const moduleId of modulesToRemove) {
+                const moduleInfo = existingInstall.modules.find((m) => m.id === moduleId);
+                const displayName = moduleInfo?.name || moduleId;
+                const modulePath = path.join(bmadDir, moduleId);
+                await prompts.log.error(`  - ${displayName} (${modulePath})`);
+              }
 
-          // Remember previously configured IDEs before deleting
-          config._previouslyConfiguredIdes = existingInstall.ides || [];
+              const confirmRemoval = await prompts.confirm({
+                message: `Remove ${modulesToRemove.length} module(s) from BMAD installation?`,
+                default: false,
+              });
 
-          // Remove existing installation
-          await fs.remove(bmadDir);
-          console.log(chalk.green('✓ Removed existing installation\n'));
+              if (confirmRemoval) {
+                // Remove module folders
+                for (const moduleId of modulesToRemove) {
+                  const modulePath = path.join(bmadDir, moduleId);
+                  try {
+                    if (await fs.pathExists(modulePath)) {
+                      await fs.remove(modulePath);
+                      await prompts.log.message(`  Removed: ${moduleId}`);
+                    }
+                  } catch (error) {
+                    await prompts.log.warn(`  Warning: Failed to remove ${moduleId}: ${error.message}`);
+                  }
+                }
+                await prompts.log.success(`  Removed ${modulesToRemove.length} module(s)`);
+              } else {
+                await prompts.log.message('  Module removal cancelled');
+                // Add the modules back to the selection since user cancelled removal
+                for (const moduleId of modulesToRemove) {
+                  if (!config.modules) config.modules = [];
+                  config.modules.push(moduleId);
+                }
+              }
 
-          // Mark this as a full reinstall so we re-collect IDE configurations
-          config._isFullReinstall = true;
-        } else if (action === 'update') {
-          // Store that we're updating for later processing
-          config._isUpdate = true;
-          config._existingInstall = existingInstall;
+              spinner.start('Preparing update...');
+            }
+          }
 
           // Detect custom and modified files BEFORE updating (compare current files vs files-manifest.csv)
           const existingFilesManifest = await this.readFilesManifest(bmadDir);
-          console.log(chalk.dim(`DEBUG: Read ${existingFilesManifest.length} files from manifest`));
-          console.log(chalk.dim(`DEBUG: Manifest has hashes: ${existingFilesManifest.some((f) => f.hash)}`));
-
           const { customFiles, modifiedFiles } = await this.detectCustomFiles(bmadDir, existingFilesManifest);
 
-          console.log(chalk.dim(`DEBUG: Found ${customFiles.length} custom files, ${modifiedFiles.length} modified files`));
-          if (modifiedFiles.length > 0) {
-            console.log(chalk.yellow('DEBUG: Modified files:'));
-            for (const f of modifiedFiles) console.log(chalk.dim(`  - ${f.path}`));
-          }
-
           config._customFiles = customFiles;
           config._modifiedFiles = modifiedFiles;
 
+          // Preserve existing core configuration during updates
+          // Read the current core config.yaml to maintain user's settings
+          const coreConfigPath = path.join(bmadDir, 'core', 'config.yaml');
+          if ((await fs.pathExists(coreConfigPath)) && (!config.coreConfig || Object.keys(config.coreConfig).length === 0)) {
+            try {
+              const yaml = require('yaml');
+              const coreConfigContent = await fs.readFile(coreConfigPath, 'utf8');
+              const existingCoreConfig = yaml.parse(coreConfigContent);
+
+              // Store in config.coreConfig so it's preserved through the installation
+              config.coreConfig = existingCoreConfig;
+
+              // Also store in configCollector for use during config collection
+              this.configCollector.collectedConfig.core = existingCoreConfig;
+            } catch (error) {
+              await prompts.log.warn(`Warning: Could not read existing core config: ${error.message}`);
+            }
+          }
+
+          // Also check cache directory for custom modules (like quick update does)
+          const cacheDir = path.join(bmadDir, '_config', 'custom');
+          if (await fs.pathExists(cacheDir)) {
+            const cachedModules = await fs.readdir(cacheDir, { withFileTypes: true });
+
+            for (const cachedModule of cachedModules) {
+              const moduleId = cachedModule.name;
+              const cachedPath = path.join(cacheDir, moduleId);
+
+              // Skip if path doesn't exist (broken symlink, deleted dir) - avoids lstat ENOENT
+              if (!(await fs.pathExists(cachedPath)) || !cachedModule.isDirectory()) {
+                continue;
+              }
+
+              // Skip if we already have this module from manifest
+              if (customModulePaths.has(moduleId)) {
+                continue;
+              }
+
+              // Check if this is an external official module - skip cache for those
+              const isExternal = await this.moduleManager.isExternalModule(moduleId);
+              if (isExternal) {
+                // External modules are handled via cloneExternalModule, not from cache
+                continue;
+              }
+
+              // Check if this is actually a custom module (has module.yaml)
+              const moduleYamlPath = path.join(cachedPath, 'module.yaml');
+              if (await fs.pathExists(moduleYamlPath)) {
+                customModulePaths.set(moduleId, cachedPath);
+              }
+            }
+
+            // Update module manager with the new custom module paths from cache
+            this.moduleManager.setCustomModulePaths(customModulePaths);
+          }
+
           // If there are custom files, back them up temporarily
           if (customFiles.length > 0) {
-            const tempBackupDir = path.join(projectDir, '.bmad-custom-backup-temp');
+            const tempBackupDir = path.join(projectDir, '_bmad-custom-backup-temp');
             await fs.ensureDir(tempBackupDir);
 
             spinner.start(`Backing up ${customFiles.length} custom files...`);
@@ -450,35 +570,31 @@ class Installer {
               await fs.ensureDir(path.dirname(backupPath));
               await fs.copy(customFile, backupPath);
             }
-            spinner.succeed(`Backed up ${customFiles.length} custom files`);
+            spinner.stop(`Backed up ${customFiles.length} custom files`);
 
             config._tempBackupDir = tempBackupDir;
           }
 
           // For modified files, back them up to temp directory (will be restored as .bak files after install)
           if (modifiedFiles.length > 0) {
-            const tempModifiedBackupDir = path.join(projectDir, '.bmad-modified-backup-temp');
+            const tempModifiedBackupDir = path.join(projectDir, '_bmad-modified-backup-temp');
             await fs.ensureDir(tempModifiedBackupDir);
 
-            console.log(chalk.yellow(`\nDEBUG: Backing up ${modifiedFiles.length} modified files to temp location`));
             spinner.start(`Backing up ${modifiedFiles.length} modified files...`);
             for (const modifiedFile of modifiedFiles) {
               const relativePath = path.relative(bmadDir, modifiedFile.path);
               const tempBackupPath = path.join(tempModifiedBackupDir, relativePath);
-              console.log(chalk.dim(`DEBUG: Backing up ${relativePath} to temp`));
               await fs.ensureDir(path.dirname(tempBackupPath));
               await fs.copy(modifiedFile.path, tempBackupPath, { overwrite: true });
             }
-            spinner.succeed(`Backed up ${modifiedFiles.length} modified files`);
+            spinner.stop(`Backed up ${modifiedFiles.length} modified files`);
 
             config._tempModifiedBackupDir = tempModifiedBackupDir;
-          } else {
-            console.log(chalk.dim('DEBUG: No modified files detected'));
           }
         }
       } else if (existingInstall.installed && config._quickUpdate) {
         // Quick update mode - automatically treat as update without prompting
-        spinner.text = 'Preparing quick update...';
+        spinner.message('Preparing quick update...');
         config._isUpdate = true;
         config._existingInstall = existingInstall;
 
@@ -489,9 +605,46 @@ class Installer {
         config._customFiles = customFiles;
         config._modifiedFiles = modifiedFiles;
 
+        // Also check cache directory for custom modules (like quick update does)
+        const cacheDir = path.join(bmadDir, '_config', 'custom');
+        if (await fs.pathExists(cacheDir)) {
+          const cachedModules = await fs.readdir(cacheDir, { withFileTypes: true });
+
+          for (const cachedModule of cachedModules) {
+            const moduleId = cachedModule.name;
+            const cachedPath = path.join(cacheDir, moduleId);
+
+            // Skip if path doesn't exist (broken symlink, deleted dir) - avoids lstat ENOENT
+            if (!(await fs.pathExists(cachedPath)) || !cachedModule.isDirectory()) {
+              continue;
+            }
+
+            // Skip if we already have this module from manifest
+            if (customModulePaths.has(moduleId)) {
+              continue;
+            }
+
+            // Check if this is an external official module - skip cache for those
+            const isExternal = await this.moduleManager.isExternalModule(moduleId);
+            if (isExternal) {
+              // External modules are handled via cloneExternalModule, not from cache
+              continue;
+            }
+
+            // Check if this is actually a custom module (has module.yaml)
+            const moduleYamlPath = path.join(cachedPath, 'module.yaml');
+            if (await fs.pathExists(moduleYamlPath)) {
+              customModulePaths.set(moduleId, cachedPath);
+            }
+          }
+
+          // Update module manager with the new custom module paths from cache
+          this.moduleManager.setCustomModulePaths(customModulePaths);
+        }
+
         // Back up custom files
         if (customFiles.length > 0) {
-          const tempBackupDir = path.join(projectDir, '.bmad-custom-backup-temp');
+          const tempBackupDir = path.join(projectDir, '_bmad-custom-backup-temp');
           await fs.ensureDir(tempBackupDir);
 
           spinner.start(`Backing up ${customFiles.length} custom files...`);
@@ -501,13 +654,13 @@ class Installer {
             await fs.ensureDir(path.dirname(backupPath));
             await fs.copy(customFile, backupPath);
           }
-          spinner.succeed(`Backed up ${customFiles.length} custom files`);
+          spinner.stop(`Backed up ${customFiles.length} custom files`);
           config._tempBackupDir = tempBackupDir;
         }
 
         // Back up modified files
         if (modifiedFiles.length > 0) {
-          const tempModifiedBackupDir = path.join(projectDir, '.bmad-modified-backup-temp');
+          const tempModifiedBackupDir = path.join(projectDir, '_bmad-modified-backup-temp');
           await fs.ensureDir(tempModifiedBackupDir);
 
           spinner.start(`Backing up ${modifiedFiles.length} modified files...`);
@@ -517,14 +670,14 @@ class Installer {
             await fs.ensureDir(path.dirname(tempBackupPath));
             await fs.copy(modifiedFile.path, tempBackupPath, { overwrite: true });
           }
-          spinner.succeed(`Backed up ${modifiedFiles.length} modified files`);
+          spinner.stop(`Backed up ${modifiedFiles.length} modified files`);
           config._tempModifiedBackupDir = tempModifiedBackupDir;
         }
       }
 
       // Now collect tool configurations after we know if it's a reinstall
       // Skip for quick update since we already have the IDE list
-      spinner.stop();
+      spinner.stop('Pre-checks complete');
       let toolSelection;
       if (config._quickUpdate) {
         // Quick update already has IDEs configured, use saved configurations
@@ -547,13 +700,15 @@ class Installer {
       } else {
         // Pass pre-selected IDEs from early prompt (if available)
         // This allows IDE selection to happen before file copying, improving UX
-        const preSelectedIdes = config.ides && config.ides.length > 0 ? config.ides : null;
+        // Use config.ides if it's an array (even if empty), null means prompt
+        const preSelectedIdes = Array.isArray(config.ides) ? config.ides : null;
         toolSelection = await this.collectToolConfigurations(
           path.resolve(config.directory),
           config.modules,
           config._isFullReinstall || false,
           config._previouslyConfiguredIdes || [],
           preSelectedIdes,
+          config.skipPrompts || false,
         );
       }
 
@@ -562,356 +717,802 @@ class Installer {
       config.skipIde = toolSelection.skipIde;
       const ideConfigurations = toolSelection.configurations;
 
-      spinner.start('Continuing installation...');
-
-      // Create bmad directory structure
-      spinner.text = 'Creating directory structure...';
-      await this.createDirectoryStructure(bmadDir);
-
-      // Resolve dependencies for selected modules
-      spinner.text = 'Resolving dependencies...';
-      const projectRoot = getProjectRoot();
-      const modulesToInstall = config.installCore ? ['core', ...config.modules] : config.modules;
-
-      // For dependency resolution, we need to pass the project root
-      const resolution = await this.dependencyResolver.resolve(projectRoot, config.modules || [], { verbose: config.verbose });
-
-      if (config.verbose) {
-        spinner.succeed('Dependencies resolved');
-      } else {
-        spinner.succeed('Dependencies resolved');
-      }
+      // Detect IDEs that were previously installed but are NOT in the new selection (to be removed)
+      if (config._isUpdate && config._existingInstall) {
+        const previouslyInstalledIdes = new Set(config._existingInstall.ides || []);
+        const newlySelectedIdes = new Set(config.ides || []);
+
+        const idesToRemove = [...previouslyInstalledIdes].filter((ide) => !newlySelectedIdes.has(ide));
+
+        if (idesToRemove.length > 0) {
+          if (config.skipPrompts) {
+            // Non-interactive mode: silently preserve existing IDE configs
+            if (!config.ides) config.ides = [];
+            const savedIdeConfigs = await this.ideConfigManager.loadAllIdeConfigs(bmadDir);
+            for (const ide of idesToRemove) {
+              config.ides.push(ide);
+              if (savedIdeConfigs[ide] && !ideConfigurations[ide]) {
+                ideConfigurations[ide] = savedIdeConfigs[ide];
+              }
+            }
+          } else {
+            if (spinner.isSpinning) {
+              spinner.stop('IDE changes reviewed');
+            }
 
-      // Install core if requested or if dependencies require it
-      if (config.installCore || resolution.byModule.core) {
-        spinner.start('Installing BMAD core...');
-        await this.installCoreWithDependencies(bmadDir, resolution.byModule.core);
-        spinner.succeed('Core installed');
-      }
+            await prompts.log.warn('IDEs to be removed:');
+            for (const ide of idesToRemove) {
+              await prompts.log.error(`  - ${ide}`);
+            }
 
-      // Install modules with their dependencies
-      if (config.modules && config.modules.length > 0) {
-        for (const moduleName of config.modules) {
-          spinner.start(`Installing module: ${moduleName}...`);
-          await this.installModuleWithDependencies(moduleName, bmadDir, resolution.byModule[moduleName]);
-          spinner.succeed(`Module installed: ${moduleName}`);
-        }
+            const confirmRemoval = await prompts.confirm({
+              message: `Remove BMAD configuration for ${idesToRemove.length} IDE(s)?`,
+              default: false,
+            });
 
-        // Install partial modules (only dependencies)
-        for (const [module, files] of Object.entries(resolution.byModule)) {
-          if (!config.modules.includes(module) && module !== 'core') {
-            const totalFiles =
-              files.agents.length +
-              files.tasks.length +
-              files.tools.length +
-              files.templates.length +
-              files.data.length +
-              files.other.length;
-            if (totalFiles > 0) {
-              spinner.start(`Installing ${module} dependencies...`);
-              await this.installPartialModule(module, bmadDir, files);
-              spinner.succeed(`${module} dependencies installed`);
+            if (confirmRemoval) {
+              await this.ideManager.ensureInitialized();
+              for (const ide of idesToRemove) {
+                try {
+                  const handler = this.ideManager.handlers.get(ide);
+                  if (handler) {
+                    await handler.cleanup(projectDir);
+                  }
+                  await this.ideConfigManager.deleteIdeConfig(bmadDir, ide);
+                  await prompts.log.message(`  Removed: ${ide}`);
+                } catch (error) {
+                  await prompts.log.warn(`  Warning: Failed to remove ${ide}: ${error.message}`);
+                }
+              }
+              await prompts.log.success(`  Removed ${idesToRemove.length} IDE(s)`);
+            } else {
+              await prompts.log.message('  IDE removal cancelled');
+              // Add IDEs back to selection and restore their saved configurations
+              if (!config.ides) config.ides = [];
+              const savedIdeConfigs = await this.ideConfigManager.loadAllIdeConfigs(bmadDir);
+              for (const ide of idesToRemove) {
+                config.ides.push(ide);
+                if (savedIdeConfigs[ide] && !ideConfigurations[ide]) {
+                  ideConfigurations[ide] = savedIdeConfigs[ide];
+                }
+              }
             }
+
+            spinner.start('Preparing installation...');
           }
         }
       }
 
-      // Generate clean config.yaml files for each installed module
-      spinner.start('Generating module configurations...');
-      await this.generateModuleConfigs(bmadDir, moduleConfigs);
-      spinner.succeed('Module configurations generated');
+      // Results collector for consolidated summary
+      const results = [];
+      const addResult = (step, status, detail = '') => results.push({ step, status, detail });
 
-      // Create agent configuration files
-      // Note: Legacy createAgentConfigs removed - using YAML customize system instead
-      // Customize templates are now created in processAgentFiles when building YAML agents
+      if (spinner.isSpinning) {
+        spinner.message('Preparing installation...');
+      } else {
+        spinner.start('Preparing installation...');
+      }
 
-      // Pre-register manifest files that will be created (except files-manifest.csv to avoid recursion)
-      const cfgDir = path.join(bmadDir, '_cfg');
-      this.installedFiles.push(
-        path.join(cfgDir, 'manifest.yaml'),
-        path.join(cfgDir, 'workflow-manifest.csv'),
-        path.join(cfgDir, 'agent-manifest.csv'),
-        path.join(cfgDir, 'task-manifest.csv'),
-      );
+      // Create bmad directory structure
+      spinner.message('Creating directory structure...');
+      await this.createDirectoryStructure(bmadDir);
 
-      // Generate CSV manifests for workflows, agents, tasks AND ALL FILES with hashes BEFORE IDE setup
-      spinner.start('Generating workflow and agent manifests...');
-      const manifestGen = new ManifestGenerator();
+      // Cache custom modules if any
+      if (customModulePaths && customModulePaths.size > 0) {
+        spinner.message('Caching custom modules...');
+        const { CustomModuleCache } = require('./custom-module-cache');
+        const customCache = new CustomModuleCache(bmadDir);
 
-      // Include preserved modules (from quick update) in the manifest
-      const allModulesToList = config._preserveModules ? [...(config.modules || []), ...config._preserveModules] : config.modules || [];
+        for (const [moduleId, sourcePath] of customModulePaths) {
+          const cachedInfo = await customCache.cacheModule(moduleId, sourcePath, {
+            sourcePath: sourcePath, // Store original path for updates
+          });
 
-      const manifestStats = await manifestGen.generateManifests(bmadDir, config.modules || [], this.installedFiles, {
-        ides: config.ides || [],
-        preservedModules: config._preserveModules || [], // Scan these from installed bmad/ dir
-      });
+          // Update the customModulePaths to use the cached location
+          customModulePaths.set(moduleId, cachedInfo.cachePath);
+        }
 
-      spinner.succeed(
-        `Manifests generated: ${manifestStats.workflows} workflows, ${manifestStats.agents} agents, ${manifestStats.tasks} tasks, ${manifestStats.tools} tools, ${manifestStats.files} files`,
-      );
+        // Update module manager with the cached paths
+        this.moduleManager.setCustomModulePaths(customModulePaths);
+        addResult('Custom modules cached', 'ok');
+      }
 
-      // Configure IDEs and copy documentation
-      if (!config.skipIde && config.ides && config.ides.length > 0) {
-        // Filter out any undefined/null values from the IDE list
-        const validIdes = config.ides.filter((ide) => ide && typeof ide === 'string');
+      const projectRoot = getProjectRoot();
 
-        if (validIdes.length === 0) {
-          console.log(chalk.yellow('⚠️  No valid IDEs selected. Skipping IDE configuration.'));
-        } else {
-          // Check if any IDE might need prompting (no pre-collected config)
-          const needsPrompting = validIdes.some((ide) => !ideConfigurations[ide]);
+      // Custom content is already handled in UI before module selection
+      const finalCustomContent = config.customContent;
 
-          if (!needsPrompting) {
-            spinner.start('Configuring IDEs...');
-          }
+      // Prepare modules list including cached custom modules
+      let allModules = [...(config.modules || [])];
 
-          // Temporarily suppress console output if not verbose
-          const originalLog = console.log;
-          if (!config.verbose) {
-            console.log = () => {};
+      // During quick update, we might have custom module sources from the manifest
+      if (config._customModuleSources) {
+        // Add custom modules from stored sources
+        for (const [moduleId, customInfo] of config._customModuleSources) {
+          if (!allModules.includes(moduleId) && (await fs.pathExists(customInfo.sourcePath))) {
+            allModules.push(moduleId);
           }
+        }
+      }
 
-          for (const ide of validIdes) {
-            // Only show spinner if we have pre-collected config (no prompts expected)
-            if (ideConfigurations[ide] && !needsPrompting) {
-              spinner.text = `Configuring ${ide}...`;
-            } else if (!ideConfigurations[ide]) {
-              // Stop spinner before prompting
-              if (spinner.isSpinning) {
-                spinner.stop();
-              }
-              console.log(chalk.cyan(`\nConfiguring ${ide}...`));
-            }
-
-            // Pass pre-collected configuration to avoid re-prompting
-            await this.ideManager.setup(ide, projectDir, bmadDir, {
-              selectedModules: config.modules || [],
-              preCollectedConfig: ideConfigurations[ide] || null,
-              verbose: config.verbose,
-            });
-
-            // Save IDE configuration for future updates
-            if (ideConfigurations[ide] && !ideConfigurations[ide]._alreadyConfigured) {
-              await this.ideConfigManager.saveIdeConfig(bmadDir, ide, ideConfigurations[ide]);
-            }
-
-            // Restart spinner if we stopped it
-            if (!ideConfigurations[ide] && !spinner.isSpinning) {
-              spinner.start('Configuring IDEs...');
-            }
+      // Add cached custom modules
+      if (finalCustomContent && finalCustomContent.cachedModules) {
+        for (const cachedModule of finalCustomContent.cachedModules) {
+          if (!allModules.includes(cachedModule.id)) {
+            allModules.push(cachedModule.id);
           }
+        }
+      }
 
-          // Restore console.log
-          console.log = originalLog;
-
-          if (spinner.isSpinning) {
-            spinner.succeed(`Configured ${validIdes.length} IDE${validIdes.length > 1 ? 's' : ''}`);
-          } else {
-            console.log(chalk.green(`✓ Configured ${validIdes.length} IDE${validIdes.length > 1 ? 's' : ''}`));
+      // Regular custom content from user input (non-cached)
+      if (finalCustomContent && finalCustomContent.selected && finalCustomContent.selectedFiles) {
+        // Add custom modules to the installation list
+        const customHandler = new CustomHandler();
+        for (const customFile of finalCustomContent.selectedFiles) {
+          const customInfo = await customHandler.getCustomInfo(customFile, projectDir);
+          if (customInfo && customInfo.id) {
+            allModules.push(customInfo.id);
           }
         }
+      }
 
-        // Copy IDE-specific documentation (only for valid IDEs)
-        const validIdesForDocs = (config.ides || []).filter((ide) => ide && typeof ide === 'string');
-        if (validIdesForDocs.length > 0) {
-          spinner.start('Copying IDE documentation...');
-          await this.copyIdeDocumentation(validIdesForDocs, bmadDir);
-          spinner.succeed('IDE documentation copied');
-        }
+      // Don't include core again if already installed
+      if (config.installCore) {
+        allModules = allModules.filter((m) => m !== 'core');
       }
 
-      // Run module-specific installers after IDE setup
-      spinner.start('Running module-specific installers...');
+      // For dependency resolution, we only need regular modules (not custom modules)
+      // Custom modules are already installed in _bmad and don't need dependency resolution from source
+      const regularModulesForResolution = allModules.filter((module) => {
+        // Check if this is a custom module
+        const isCustom =
+          customModulePaths.has(module) ||
+          (finalCustomContent && finalCustomContent.cachedModules && finalCustomContent.cachedModules.some((cm) => cm.id === module)) ||
+          (finalCustomContent &&
+            finalCustomContent.selected &&
+            finalCustomContent.selectedFiles &&
+            finalCustomContent.selectedFiles.some((f) => f.includes(module)));
+        return !isCustom;
+      });
+
+      // Stop spinner before tasks() takes over progress display
+      spinner.stop('Preparation complete');
+
+      // ─────────────────────────────────────────────────────────────────────────
+      // FIRST TASKS BLOCK: Core installation through manifests (non-interactive)
+      // ─────────────────────────────────────────────────────────────────────────
+      const isQuickUpdate = config._quickUpdate || false;
 
-      // Run core module installer if core was installed
-      if (config.installCore || resolution.byModule.core) {
-        spinner.text = 'Running core module installer...';
+      // Shared resolution result across task callbacks (closure-scoped, not on `this`)
+      let taskResolution;
 
-        await this.moduleManager.runModuleInstaller('core', bmadDir, {
-          installedIDEs: config.ides || [],
-          moduleConfig: moduleConfigs.core || {},
-          logger: {
-            log: (msg) => console.log(msg),
-            error: (msg) => console.error(msg),
-            warn: (msg) => console.warn(msg),
+      // Collect directory creation results for output after tasks() completes
+      const dirResults = { createdDirs: [], movedDirs: [], createdWdsFolders: [] };
+
+      // Build task list conditionally
+      const installTasks = [];
+
+      // Core installation task
+      if (config.installCore) {
+        installTasks.push({
+          title: isQuickUpdate ? 'Updating BMAD core' : 'Installing BMAD core',
+          task: async (message) => {
+            await this.installCoreWithDependencies(bmadDir, { core: {} });
+            addResult('Core', 'ok', isQuickUpdate ? 'updated' : 'installed');
+            await this.generateModuleConfigs(bmadDir, { core: config.coreConfig || {} });
+            return isQuickUpdate ? 'Core updated' : 'Core installed';
           },
         });
       }
 
-      // Run installers for user-selected modules
-      if (config.modules && config.modules.length > 0) {
-        for (const moduleName of config.modules) {
-          spinner.text = `Running ${moduleName} module installer...`;
+      // Dependency resolution task
+      installTasks.push({
+        title: 'Resolving dependencies',
+        task: async (message) => {
+          // Create a temporary module manager that knows about custom content locations
+          const tempModuleManager = new ModuleManager({
+            bmadDir: bmadDir,
+          });
 
-          // Pass installed IDEs and module config to module installer
-          await this.moduleManager.runModuleInstaller(moduleName, bmadDir, {
-            installedIDEs: config.ides || [],
-            moduleConfig: moduleConfigs[moduleName] || {},
-            logger: {
-              log: (msg) => console.log(msg),
-              error: (msg) => console.error(msg),
-              warn: (msg) => console.warn(msg),
-            },
+          taskResolution = await this.dependencyResolver.resolve(projectRoot, regularModulesForResolution, {
+            verbose: config.verbose,
+            moduleManager: tempModuleManager,
           });
-        }
-      }
+          return 'Dependencies resolved';
+        },
+      });
+
+      // Module installation task
+      if (allModules && allModules.length > 0) {
+        installTasks.push({
+          title: isQuickUpdate ? `Updating ${allModules.length} module(s)` : `Installing ${allModules.length} module(s)`,
+          task: async (message) => {
+            const resolution = taskResolution;
+            const installedModuleNames = new Set();
+
+            for (const moduleName of allModules) {
+              if (installedModuleNames.has(moduleName)) continue;
+              installedModuleNames.add(moduleName);
+
+              message(`${isQuickUpdate ? 'Updating' : 'Installing'} ${moduleName}...`);
+
+              // Check if this is a custom module
+              let isCustomModule = false;
+              let customInfo = null;
+
+              // First check if we have a cached version
+              if (finalCustomContent && finalCustomContent.cachedModules) {
+                const cachedModule = finalCustomContent.cachedModules.find((m) => m.id === moduleName);
+                if (cachedModule) {
+                  isCustomModule = true;
+                  customInfo = { id: moduleName, path: cachedModule.cachePath, config: {} };
+                }
+              }
 
-      spinner.succeed('Module-specific installers completed');
+              // Then check custom module sources from manifest (for quick update)
+              if (!isCustomModule && config._customModuleSources && config._customModuleSources.has(moduleName)) {
+                customInfo = config._customModuleSources.get(moduleName);
+                isCustomModule = true;
+                if (customInfo.sourcePath && !customInfo.path) {
+                  customInfo.path = path.isAbsolute(customInfo.sourcePath)
+                    ? customInfo.sourcePath
+                    : path.join(bmadDir, customInfo.sourcePath);
+                }
+              }
 
-      // Note: Manifest files are already created by ManifestGenerator above
-      // No need to create legacy manifest.csv anymore
+              // Finally check regular custom content
+              if (!isCustomModule && finalCustomContent && finalCustomContent.selected && finalCustomContent.selectedFiles) {
+                const customHandler = new CustomHandler();
+                for (const customFile of finalCustomContent.selectedFiles) {
+                  const info = await customHandler.getCustomInfo(customFile, projectDir);
+                  if (info && info.id === moduleName) {
+                    isCustomModule = true;
+                    customInfo = info;
+                    break;
+                  }
+                }
+              }
 
-      // If this was an update, restore custom files
-      let customFiles = [];
-      let modifiedFiles = [];
-      if (config._isUpdate) {
-        if (config._customFiles && config._customFiles.length > 0) {
-          spinner.start(`Restoring ${config._customFiles.length} custom files...`);
+              if (isCustomModule && customInfo) {
+                if (!customModulePaths.has(moduleName) && customInfo.path) {
+                  customModulePaths.set(moduleName, customInfo.path);
+                  this.moduleManager.setCustomModulePaths(customModulePaths);
+                }
 
-          for (const originalPath of config._customFiles) {
-            const relativePath = path.relative(bmadDir, originalPath);
-            const backupPath = path.join(config._tempBackupDir, relativePath);
+                const collectedModuleConfig = moduleConfigs[moduleName] || {};
+                await this.moduleManager.install(
+                  moduleName,
+                  bmadDir,
+                  (filePath) => {
+                    this.installedFiles.add(filePath);
+                  },
+                  {
+                    isCustom: true,
+                    moduleConfig: collectedModuleConfig,
+                    isQuickUpdate: isQuickUpdate,
+                    installer: this,
+                    silent: true,
+                  },
+                );
+                await this.generateModuleConfigs(bmadDir, {
+                  [moduleName]: { ...config.coreConfig, ...customInfo.config, ...collectedModuleConfig },
+                });
+              } else {
+                if (!resolution || !resolution.byModule) {
+                  addResult(`Module: ${moduleName}`, 'warn', 'skipped (no resolution data)');
+                  continue;
+                }
+                if (moduleName === 'core') {
+                  await this.installCoreWithDependencies(bmadDir, resolution.byModule[moduleName]);
+                } else {
+                  await this.installModuleWithDependencies(moduleName, bmadDir, resolution.byModule[moduleName]);
+                }
+              }
 
-            if (await fs.pathExists(backupPath)) {
-              await fs.ensureDir(path.dirname(originalPath));
-              await fs.copy(backupPath, originalPath, { overwrite: true });
+              addResult(`Module: ${moduleName}`, 'ok', isQuickUpdate ? 'updated' : 'installed');
             }
-          }
 
-          // Clean up temp backup
-          if (config._tempBackupDir && (await fs.pathExists(config._tempBackupDir))) {
-            await fs.remove(config._tempBackupDir);
-          }
-
-          spinner.succeed(`Restored ${config._customFiles.length} custom files`);
-          customFiles = config._customFiles;
-        }
+            // Install partial modules (only dependencies)
+            if (!resolution || !resolution.byModule) {
+              return `${allModules.length} module(s) ${isQuickUpdate ? 'updated' : 'installed'}`;
+            }
+            for (const [module, files] of Object.entries(resolution.byModule)) {
+              if (!allModules.includes(module) && module !== 'core') {
+                const totalFiles =
+                  files.agents.length +
+                  files.tasks.length +
+                  files.tools.length +
+                  files.templates.length +
+                  files.data.length +
+                  files.other.length;
+                if (totalFiles > 0) {
+                  message(`Installing ${module} dependencies...`);
+                  await this.installPartialModule(module, bmadDir, files);
+                }
+              }
+            }
 
-        if (config._modifiedFiles && config._modifiedFiles.length > 0) {
-          modifiedFiles = config._modifiedFiles;
+            return `${allModules.length} module(s) ${isQuickUpdate ? 'updated' : 'installed'}`;
+          },
+        });
+      }
 
-          // Restore modified files as .bak files
-          if (config._tempModifiedBackupDir && (await fs.pathExists(config._tempModifiedBackupDir))) {
-            spinner.start(`Restoring ${modifiedFiles.length} modified files as .bak...`);
+      // Module directory creation task
+      installTasks.push({
+        title: 'Creating module directories',
+        task: async (message) => {
+          const resolution = taskResolution;
+          if (!resolution || !resolution.byModule) {
+            addResult('Module directories', 'warn', 'no resolution data');
+            return 'Module directories skipped (no resolution data)';
+          }
+          const verboseMode = process.env.BMAD_VERBOSE_INSTALL === 'true' || config.verbose;
+          const moduleLogger = {
+            log: async (msg) => (verboseMode ? await prompts.log.message(msg) : undefined),
+            error: async (msg) => await prompts.log.error(msg),
+            warn: async (msg) => await prompts.log.warn(msg),
+          };
 
-            for (const modifiedFile of modifiedFiles) {
-              const relativePath = path.relative(bmadDir, modifiedFile.path);
-              const tempBackupPath = path.join(config._tempModifiedBackupDir, relativePath);
-              const bakPath = modifiedFile.path + '.bak';
+          // Core module directories
+          if (config.installCore || resolution.byModule.core) {
+            const result = await this.moduleManager.createModuleDirectories('core', bmadDir, {
+              installedIDEs: config.ides || [],
+              moduleConfig: moduleConfigs.core || {},
+              existingModuleConfig: this.configCollector.existingConfig?.core || {},
+              coreConfig: moduleConfigs.core || {},
+              logger: moduleLogger,
+              silent: true,
+            });
+            if (result) {
+              dirResults.createdDirs.push(...result.createdDirs);
+              dirResults.movedDirs.push(...(result.movedDirs || []));
+              dirResults.createdWdsFolders.push(...result.createdWdsFolders);
+            }
+          }
 
-              if (await fs.pathExists(tempBackupPath)) {
-                await fs.ensureDir(path.dirname(bakPath));
-                await fs.copy(tempBackupPath, bakPath, { overwrite: true });
+          // User-selected module directories
+          if (config.modules && config.modules.length > 0) {
+            for (const moduleName of config.modules) {
+              message(`Setting up ${moduleName}...`);
+              const result = await this.moduleManager.createModuleDirectories(moduleName, bmadDir, {
+                installedIDEs: config.ides || [],
+                moduleConfig: moduleConfigs[moduleName] || {},
+                existingModuleConfig: this.configCollector.existingConfig?.[moduleName] || {},
+                coreConfig: moduleConfigs.core || {},
+                logger: moduleLogger,
+                silent: true,
+              });
+              if (result) {
+                dirResults.createdDirs.push(...result.createdDirs);
+                dirResults.movedDirs.push(...(result.movedDirs || []));
+                dirResults.createdWdsFolders.push(...result.createdWdsFolders);
               }
             }
+          }
 
-            // Clean up temp backup
-            await fs.remove(config._tempModifiedBackupDir);
+          addResult('Module directories', 'ok');
+          return 'Module directories created';
+        },
+      });
 
-            spinner.succeed(`Restored ${modifiedFiles.length} modified files as .bak`);
+      // Configuration generation task (stored as named reference for deferred execution)
+      const configTask = {
+        title: 'Generating configurations',
+        task: async (message) => {
+          // Generate clean config.yaml files for each installed module
+          await this.generateModuleConfigs(bmadDir, moduleConfigs);
+          addResult('Configurations', 'ok', 'generated');
+
+          // Pre-register manifest files
+          const cfgDir = path.join(bmadDir, '_config');
+          this.installedFiles.add(path.join(cfgDir, 'manifest.yaml'));
+          this.installedFiles.add(path.join(cfgDir, 'workflow-manifest.csv'));
+          this.installedFiles.add(path.join(cfgDir, 'agent-manifest.csv'));
+          this.installedFiles.add(path.join(cfgDir, 'task-manifest.csv'));
+
+          // Generate CSV manifests for workflows, agents, tasks AND ALL FILES with hashes
+          // This must happen BEFORE mergeModuleHelpCatalogs because it depends on agent-manifest.csv
+          message('Generating manifests...');
+          const manifestGen = new ManifestGenerator();
+
+          const allModulesForManifest = config._quickUpdate
+            ? config._existingModules || allModules || []
+            : config._preserveModules
+              ? [...allModules, ...config._preserveModules]
+              : allModules || [];
+
+          let modulesForCsvPreserve;
+          if (config._quickUpdate) {
+            modulesForCsvPreserve = config._existingModules || allModules || [];
+          } else {
+            modulesForCsvPreserve = config._preserveModules ? [...allModules, ...config._preserveModules] : allModules;
           }
-        }
-      }
 
-      spinner.stop();
+          const manifestStats = await manifestGen.generateManifests(bmadDir, allModulesForManifest, [...this.installedFiles], {
+            ides: config.ides || [],
+            preservedModules: modulesForCsvPreserve,
+          });
 
-      // Report custom and modified files if any were found
-      if (customFiles.length > 0) {
-        console.log(chalk.cyan(`\n📁 Custom files preserved: ${customFiles.length}`));
-        console.log(chalk.dim('The following custom files were found and restored:\n'));
-        for (const file of customFiles) {
-          console.log(chalk.dim(`  - ${path.relative(bmadDir, file)}`));
-        }
-        console.log('');
-      }
+          addResult(
+            'Manifests',
+            'ok',
+            `${manifestStats.workflows} workflows, ${manifestStats.agents} agents, ${manifestStats.tasks} tasks, ${manifestStats.tools} tools`,
+          );
 
-      if (modifiedFiles.length > 0) {
-        console.log(chalk.yellow(`\n⚠️  Modified files detected: ${modifiedFiles.length}`));
-        console.log(chalk.dim('The following files were modified and backed up with .bak extension:\n'));
-        for (const file of modifiedFiles) {
-          console.log(chalk.dim(`  - ${file.relativePath} → ${file.relativePath}.bak`));
-        }
-        console.log(chalk.dim('\nThese files have been updated with the new version.'));
-        console.log(chalk.dim('Review the .bak files to see your changes and merge if needed.\n'));
-      }
+          // Merge help catalogs
+          message('Generating help catalog...');
+          await this.mergeModuleHelpCatalogs(bmadDir);
+          addResult('Help catalog', 'ok');
 
-      // Display completion message
-      const { UI } = require('../../../lib/ui');
-      const ui = new UI();
-      ui.showInstallSummary({
-        path: bmadDir,
-        modules: config.modules,
-        ides: config.ides,
-        customFiles: customFiles.length > 0 ? customFiles : undefined,
-      });
+          return 'Configurations generated';
+        },
+      };
+      installTasks.push(configTask);
 
-      return { success: true, path: bmadDir, modules: config.modules, ides: config.ides };
-    } catch (error) {
-      spinner.fail('Installation failed');
-      throw error;
+      // Run all tasks except config (which runs after directory output)
+      const mainTasks = installTasks.filter((t) => t !== configTask);
+      await prompts.tasks(mainTasks);
+
+      // Render directory creation output right after directory task
+      const color = await prompts.getColor();
+      if (dirResults.movedDirs.length > 0) {
+        const lines = dirResults.movedDirs.map((d) => `  ${d}`).join('\n');
+        await prompts.log.message(color.cyan(`Moved directories:\n${lines}`));
+      }
+      if (dirResults.createdDirs.length > 0) {
+        const lines = dirResults.createdDirs.map((d) => `  ${d}`).join('\n');
+        await prompts.log.message(color.yellow(`Created directories:\n${lines}`));
+      }
+      if (dirResults.createdWdsFolders.length > 0) {
+        const lines = dirResults.createdWdsFolders.map((f) => color.dim(`  \u2713 ${f}/`)).join('\n');
+        await prompts.log.message(color.cyan(`Created WDS folder structure:\n${lines}`));
+      }
+
+      // Now run configuration generation
+      await prompts.tasks([configTask]);
+
+      // Resolution is now available via closure-scoped taskResolution
+      const resolution = taskResolution;
+
+      // ─────────────────────────────────────────────────────────────────────────
+      // IDE SETUP: Keep as spinner since it may prompt for user input
+      // ─────────────────────────────────────────────────────────────────────────
+      if (!config.skipIde && config.ides && config.ides.length > 0) {
+        await this.ideManager.ensureInitialized();
+        const validIdes = config.ides.filter((ide) => ide && typeof ide === 'string');
+
+        if (validIdes.length === 0) {
+          addResult('IDE configuration', 'warn', 'no valid IDEs selected');
+        } else {
+          const needsPrompting = validIdes.some((ide) => !ideConfigurations[ide]);
+          const ideSpinner = await prompts.spinner();
+          ideSpinner.start('Configuring tools...');
+
+          try {
+            for (const ide of validIdes) {
+              if (!needsPrompting || ideConfigurations[ide]) {
+                ideSpinner.message(`Configuring ${ide}...`);
+              } else {
+                if (ideSpinner.isSpinning) {
+                  ideSpinner.stop('Ready for IDE configuration');
+                }
+              }
+
+              // Suppress stray console output for pre-configured IDEs (no user interaction)
+              const ideHasConfig = Boolean(ideConfigurations[ide]);
+              const originalLog = console.log;
+              if (!config.verbose && ideHasConfig) {
+                console.log = () => {};
+              }
+              try {
+                const setupResult = await this.ideManager.setup(ide, projectDir, bmadDir, {
+                  selectedModules: allModules || [],
+                  preCollectedConfig: ideConfigurations[ide] || null,
+                  verbose: config.verbose,
+                  silent: ideHasConfig,
+                });
+
+                if (ideConfigurations[ide] && !ideConfigurations[ide]._alreadyConfigured) {
+                  await this.ideConfigManager.saveIdeConfig(bmadDir, ide, ideConfigurations[ide]);
+                }
+
+                if (setupResult.success) {
+                  addResult(ide, 'ok', setupResult.detail || '');
+                } else {
+                  addResult(ide, 'error', setupResult.error || 'failed');
+                }
+              } finally {
+                console.log = originalLog;
+              }
+
+              if (needsPrompting && !ideSpinner.isSpinning) {
+                ideSpinner.start('Configuring tools...');
+              }
+            }
+          } finally {
+            if (ideSpinner.isSpinning) {
+              ideSpinner.stop('Tool configuration complete');
+            }
+          }
+        }
+      }
+
+      // ─────────────────────────────────────────────────────────────────────────
+      // SECOND TASKS BLOCK: Post-IDE operations (non-interactive)
+      // ─────────────────────────────────────────────────────────────────────────
+      const postIdeTasks = [];
+
+      // File restoration task (only for updates)
+      if (
+        config._isUpdate &&
+        ((config._customFiles && config._customFiles.length > 0) || (config._modifiedFiles && config._modifiedFiles.length > 0))
+      ) {
+        postIdeTasks.push({
+          title: 'Finalizing installation',
+          task: async (message) => {
+            let customFiles = [];
+            let modifiedFiles = [];
+
+            if (config._customFiles && config._customFiles.length > 0) {
+              message(`Restoring ${config._customFiles.length} custom files...`);
+
+              for (const originalPath of config._customFiles) {
+                const relativePath = path.relative(bmadDir, originalPath);
+                const backupPath = path.join(config._tempBackupDir, relativePath);
+
+                if (await fs.pathExists(backupPath)) {
+                  await fs.ensureDir(path.dirname(originalPath));
+                  await fs.copy(backupPath, originalPath, { overwrite: true });
+                }
+              }
+
+              if (config._tempBackupDir && (await fs.pathExists(config._tempBackupDir))) {
+                await fs.remove(config._tempBackupDir);
+              }
+
+              customFiles = config._customFiles;
+            }
+
+            if (config._modifiedFiles && config._modifiedFiles.length > 0) {
+              modifiedFiles = config._modifiedFiles;
+
+              if (config._tempModifiedBackupDir && (await fs.pathExists(config._tempModifiedBackupDir))) {
+                message(`Restoring ${modifiedFiles.length} modified files as .bak...`);
+
+                for (const modifiedFile of modifiedFiles) {
+                  const relativePath = path.relative(bmadDir, modifiedFile.path);
+                  const tempBackupPath = path.join(config._tempModifiedBackupDir, relativePath);
+                  const bakPath = modifiedFile.path + '.bak';
+
+                  if (await fs.pathExists(tempBackupPath)) {
+                    await fs.ensureDir(path.dirname(bakPath));
+                    await fs.copy(tempBackupPath, bakPath, { overwrite: true });
+                  }
+                }
+
+                await fs.remove(config._tempModifiedBackupDir);
+              }
+            }
+
+            // Store for summary access
+            config._restoredCustomFiles = customFiles;
+            config._restoredModifiedFiles = modifiedFiles;
+
+            return 'Installation finalized';
+          },
+        });
+      }
+
+      await prompts.tasks(postIdeTasks);
+
+      // Retrieve restored file info for summary
+      const customFiles = config._restoredCustomFiles || [];
+      const modifiedFiles = config._restoredModifiedFiles || [];
+
+      // Render consolidated summary
+      await this.renderInstallSummary(results, {
+        bmadDir,
+        modules: config.modules,
+        ides: config.ides,
+        customFiles: customFiles.length > 0 ? customFiles : undefined,
+        modifiedFiles: modifiedFiles.length > 0 ? modifiedFiles : undefined,
+      });
+
+      return {
+        success: true,
+        path: bmadDir,
+        modules: config.modules,
+        ides: config.ides,
+        projectDir: projectDir,
+      };
+    } catch (error) {
+      try {
+        if (spinner.isSpinning) {
+          spinner.error('Installation failed');
+        } else {
+          await prompts.log.error('Installation failed');
+        }
+      } catch {
+        // Ensure the original error is never swallowed by a logging failure
+      }
+      throw error;
+    }
+  }
+
+  /**
+   * Render a consolidated install summary using prompts.note()
+   * @param {Array} results - Array of {step, status: 'ok'|'error'|'warn', detail}
+   * @param {Object} context - {bmadDir, modules, ides, customFiles, modifiedFiles}
+   */
+  async renderInstallSummary(results, context = {}) {
+    const color = await prompts.getColor();
+
+    // Build step lines with status indicators
+    const lines = [];
+    for (const r of results) {
+      let icon;
+      if (r.status === 'ok') {
+        icon = color.green('\u2713');
+      } else if (r.status === 'warn') {
+        icon = color.yellow('!');
+      } else {
+        icon = color.red('\u2717');
+      }
+      const detail = r.detail ? color.dim(` (${r.detail})`) : '';
+      lines.push(`  ${icon}  ${r.step}${detail}`);
     }
+
+    // Context and warnings
+    lines.push('');
+    if (context.bmadDir) {
+      lines.push(`  Installed to: ${color.dim(context.bmadDir)}`);
+    }
+    if (context.customFiles && context.customFiles.length > 0) {
+      lines.push(`  ${color.cyan(`Custom files preserved: ${context.customFiles.length}`)}`);
+    }
+    if (context.modifiedFiles && context.modifiedFiles.length > 0) {
+      lines.push(`  ${color.yellow(`Modified files backed up (.bak): ${context.modifiedFiles.length}`)}`);
+    }
+
+    // Next steps
+    lines.push(
+      '',
+      '  Next steps:',
+      `    Read our new Docs Site: ${color.dim('https://docs.bmad-method.org/')}`,
+      `    Join our Discord: ${color.dim('https://discord.gg/gk8jAdXWmj')}`,
+      `    Star us on GitHub: ${color.dim('https://github.com/bmad-code-org/BMAD-METHOD/')}`,
+      `    Subscribe on YouTube: ${color.dim('https://www.youtube.com/@BMadCode')}`,
+      `    Run ${color.cyan('/bmad-help')} with your IDE Agent and ask it how to get started`,
+    );
+
+    await prompts.note(lines.join('\n'), 'BMAD is ready to use!');
   }
 
   /**
    * Update existing installation
    */
   async update(config) {
-    const spinner = ora('Checking installation...').start();
+    const spinner = await prompts.spinner();
+    spinner.start('Checking installation...');
 
     try {
       const projectDir = path.resolve(config.directory);
-      const bmadDir = await this.findBmadDir(projectDir);
+      const { bmadDir } = await this.findBmadDir(projectDir);
       const existingInstall = await this.detector.detect(bmadDir);
 
       if (!existingInstall.installed) {
-        spinner.fail('No BMAD installation found');
+        spinner.stop('No BMAD installation found');
         throw new Error(`No BMAD installation found at ${bmadDir}`);
       }
 
-      spinner.text = 'Analyzing update requirements...';
+      spinner.message('Analyzing update requirements...');
 
       // Compare versions and determine what needs updating
       const currentVersion = existingInstall.version;
       const newVersion = require(path.join(getProjectRoot(), 'package.json')).version;
 
+      // Check for custom modules with missing sources before update
+      const customModuleSources = new Map();
+
+      // Check manifest for backward compatibility
+      if (existingInstall.customModules) {
+        for (const customModule of existingInstall.customModules) {
+          customModuleSources.set(customModule.id, customModule);
+        }
+      }
+
+      // Also check cache directory
+      const cacheDir = path.join(bmadDir, '_config', 'custom');
+      if (await fs.pathExists(cacheDir)) {
+        const cachedModules = await fs.readdir(cacheDir, { withFileTypes: true });
+
+        for (const cachedModule of cachedModules) {
+          if (cachedModule.isDirectory()) {
+            const moduleId = cachedModule.name;
+
+            // Skip if we already have this module
+            if (customModuleSources.has(moduleId)) {
+              continue;
+            }
+
+            // Check if this is an external official module - skip cache for those
+            const isExternal = await this.moduleManager.isExternalModule(moduleId);
+            if (isExternal) {
+              // External modules are handled via cloneExternalModule, not from cache
+              continue;
+            }
+
+            const cachedPath = path.join(cacheDir, moduleId);
+
+            // Check if this is actually a custom module (has module.yaml)
+            const moduleYamlPath = path.join(cachedPath, 'module.yaml');
+            if (await fs.pathExists(moduleYamlPath)) {
+              customModuleSources.set(moduleId, {
+                id: moduleId,
+                name: moduleId,
+                sourcePath: path.join('_config', 'custom', moduleId), // Relative path
+                cached: true,
+              });
+            }
+          }
+        }
+      }
+
+      if (customModuleSources.size > 0) {
+        spinner.stop('Update analysis complete');
+        await prompts.log.warn('Checking custom module sources before update...');
+
+        const projectRoot = getProjectRoot();
+        await this.handleMissingCustomSources(
+          customModuleSources,
+          bmadDir,
+          projectRoot,
+          'update',
+          existingInstall.modules.map((m) => m.id),
+          config.skipPrompts || false,
+        );
+
+        spinner.start('Preparing update...');
+      }
+
       if (config.dryRun) {
-        spinner.stop();
-        console.log(chalk.cyan('\n🔍 Update Preview (Dry Run)\n'));
-        console.log(chalk.bold('Current version:'), currentVersion);
-        console.log(chalk.bold('New version:'), newVersion);
-        console.log(chalk.bold('Core:'), existingInstall.hasCore ? 'Will be updated' : 'Not installed');
+        spinner.stop('Dry run analysis complete');
+        let dryRunContent = `Current version: ${currentVersion}\n`;
+        dryRunContent += `New version: ${newVersion}\n`;
+        dryRunContent += `Core: ${existingInstall.hasCore ? 'Will be updated' : 'Not installed'}`;
 
         if (existingInstall.modules.length > 0) {
-          console.log(chalk.bold('\nModules to update:'));
+          dryRunContent += '\n\nModules to update:';
           for (const mod of existingInstall.modules) {
-            console.log(`  - ${mod.id}`);
+            dryRunContent += `\n  - ${mod.id}`;
           }
         }
+        await prompts.note(dryRunContent, 'Update Preview (Dry Run)');
         return;
       }
 
       // Perform actual update
       if (existingInstall.hasCore) {
-        spinner.text = 'Updating core...';
+        spinner.message('Updating core...');
         await this.updateCore(bmadDir, config.force);
       }
 
       for (const module of existingInstall.modules) {
-        spinner.text = `Updating module: ${module.id}...`;
-        await this.moduleManager.update(module.id, bmadDir, config.force);
+        spinner.message(`Updating module: ${module.id}...`);
+        await this.moduleManager.update(module.id, bmadDir, config.force, { installer: this });
       }
 
       // Update manifest
-      spinner.text = 'Updating manifest...';
+      spinner.message('Updating manifest...');
       await this.manifest.update(bmadDir, {
         version: newVersion,
         updateDate: new Date().toISOString(),
       });
 
-      spinner.succeed('Update complete');
+      spinner.stop('Update complete');
       return { success: true };
     } catch (error) {
-      spinner.fail('Update failed');
+      spinner.error('Update failed');
       throw error;
     }
   }
@@ -921,7 +1522,7 @@ class Installer {
    */
   async getStatus(directory) {
     const projectDir = path.resolve(directory);
-    const bmadDir = await this.findBmadDir(projectDir);
+    const { bmadDir } = await this.findBmadDir(projectDir);
     return await this.detector.detect(bmadDir);
   }
 
@@ -933,29 +1534,401 @@ class Installer {
   }
 
   /**
-   * Uninstall BMAD
+   * Uninstall BMAD with selective removal options
+   * @param {string} directory - Project directory
+   * @param {Object} options - Uninstall options
+   * @param {boolean} [options.removeModules=true] - Remove _bmad/ directory
+   * @param {boolean} [options.removeIdeConfigs=true] - Remove IDE configurations
+   * @param {boolean} [options.removeOutputFolder=false] - Remove user artifacts output folder
+   * @returns {Object} Result with success status and removed components
    */
-  async uninstall(directory) {
+  async uninstall(directory, options = {}) {
     const projectDir = path.resolve(directory);
-    const bmadDir = await this.findBmadDir(projectDir);
+    const { bmadDir } = await this.findBmadDir(projectDir);
+
+    if (!(await fs.pathExists(bmadDir))) {
+      return { success: false, reason: 'not-installed' };
+    }
+
+    // 1. DETECT: Read state BEFORE deleting anything
+    const existingInstall = await this.detector.detect(bmadDir);
+    const outputFolder = await this._readOutputFolder(bmadDir);
+
+    const removed = { modules: false, ideConfigs: false, outputFolder: false };
+
+    // 2. IDE CLEANUP (before _bmad/ deletion so configs are accessible)
+    if (options.removeIdeConfigs !== false) {
+      await this.uninstallIdeConfigs(projectDir, existingInstall, { silent: options.silent });
+      removed.ideConfigs = true;
+    }
+
+    // 3. OUTPUT FOLDER (only if explicitly requested)
+    if (options.removeOutputFolder === true && outputFolder) {
+      removed.outputFolder = await this.uninstallOutputFolder(projectDir, outputFolder);
+    }
+
+    // 4. BMAD DIRECTORY (last, after everything that needs it)
+    if (options.removeModules !== false) {
+      removed.modules = await this.uninstallModules(projectDir);
+    }
+
+    return { success: true, removed, version: existingInstall.version };
+  }
+
+  /**
+   * Uninstall IDE configurations only
+   * @param {string} projectDir - Project directory
+   * @param {Object} existingInstall - Detection result from detector.detect()
+   * @param {Object} [options] - Options (e.g. { silent: true })
+   * @returns {Promise<Object>} Results from IDE cleanup
+   */
+  async uninstallIdeConfigs(projectDir, existingInstall, options = {}) {
+    await this.ideManager.ensureInitialized();
+    const cleanupOptions = { isUninstall: true, silent: options.silent };
+    const ideList = existingInstall.ides || [];
+    if (ideList.length > 0) {
+      return this.ideManager.cleanupByList(projectDir, ideList, cleanupOptions);
+    }
+    return this.ideManager.cleanup(projectDir, cleanupOptions);
+  }
 
+  /**
+   * Remove user artifacts output folder
+   * @param {string} projectDir - Project directory
+   * @param {string} outputFolder - Output folder name (relative)
+   * @returns {Promise<boolean>} Whether the folder was removed
+   */
+  async uninstallOutputFolder(projectDir, outputFolder) {
+    if (!outputFolder) return false;
+    const resolvedProject = path.resolve(projectDir);
+    const outputPath = path.resolve(resolvedProject, outputFolder);
+    if (!outputPath.startsWith(resolvedProject + path.sep)) {
+      return false;
+    }
+    if (await fs.pathExists(outputPath)) {
+      await fs.remove(outputPath);
+      return true;
+    }
+    return false;
+  }
+
+  /**
+   * Remove the _bmad/ directory
+   * @param {string} projectDir - Project directory
+   * @returns {Promise<boolean>} Whether the directory was removed
+   */
+  async uninstallModules(projectDir) {
+    const { bmadDir } = await this.findBmadDir(projectDir);
     if (await fs.pathExists(bmadDir)) {
       await fs.remove(bmadDir);
+      return true;
+    }
+    return false;
+  }
+
+  /**
+   * Get the configured output folder name for a project
+   * Resolves bmadDir internally from projectDir
+   * @param {string} projectDir - Project directory
+   * @returns {string} Output folder name (relative, default: '_bmad-output')
+   */
+  async getOutputFolder(projectDir) {
+    const { bmadDir } = await this.findBmadDir(projectDir);
+    return this._readOutputFolder(bmadDir);
+  }
+
+  /**
+   * Read the output_folder setting from module config files
+   * Checks bmm/config.yaml first, then other module configs
+   * @param {string} bmadDir - BMAD installation directory
+   * @returns {string} Output folder path or default
+   */
+  async _readOutputFolder(bmadDir) {
+    const yaml = require('yaml');
+
+    // Check bmm/config.yaml first (most common)
+    const bmmConfigPath = path.join(bmadDir, 'bmm', 'config.yaml');
+    if (await fs.pathExists(bmmConfigPath)) {
+      try {
+        const content = await fs.readFile(bmmConfigPath, 'utf8');
+        const config = yaml.parse(content);
+        if (config && config.output_folder) {
+          // Strip {project-root}/ prefix if present
+          return config.output_folder.replace(/^\{project-root\}[/\\]/, '');
+        }
+      } catch {
+        // Fall through to other modules
+      }
     }
 
-    // Clean up IDE configurations
-    await this.ideManager.cleanup(projectDir);
+    // Scan other module config.yaml files
+    try {
+      const entries = await fs.readdir(bmadDir, { withFileTypes: true });
+      for (const entry of entries) {
+        if (!entry.isDirectory() || entry.name === 'bmm' || entry.name.startsWith('_')) continue;
+        const configPath = path.join(bmadDir, entry.name, 'config.yaml');
+        if (await fs.pathExists(configPath)) {
+          try {
+            const content = await fs.readFile(configPath, 'utf8');
+            const config = yaml.parse(content);
+            if (config && config.output_folder) {
+              return config.output_folder.replace(/^\{project-root\}[/\\]/, '');
+            }
+          } catch {
+            // Continue scanning
+          }
+        }
+      }
+    } catch {
+      // Directory scan failed
+    }
 
-    return { success: true };
+    // Default fallback
+    return '_bmad-output';
   }
 
   /**
    * Private: Create directory structure
    */
+  /**
+   * Merge all module-help.csv files into a single bmad-help.csv
+   * Scans all installed modules for module-help.csv and merges them
+   * Enriches agent info from agent-manifest.csv
+   * Output is written to _bmad/_config/bmad-help.csv
+   * @param {string} bmadDir - BMAD installation directory
+   */
+  async mergeModuleHelpCatalogs(bmadDir) {
+    const allRows = [];
+    const headerRow =
+      'module,phase,name,code,sequence,workflow-file,command,required,agent-name,agent-command,agent-display-name,agent-title,options,description,output-location,outputs';
+
+    // Load agent manifest for agent info lookup
+    const agentManifestPath = path.join(bmadDir, '_config', 'agent-manifest.csv');
+    const agentInfo = new Map(); // agent-name -> {command, displayName, title+icon}
+
+    if (await fs.pathExists(agentManifestPath)) {
+      const manifestContent = await fs.readFile(agentManifestPath, 'utf8');
+      const lines = manifestContent.split('\n').filter((line) => line.trim());
+
+      for (const line of lines) {
+        if (line.startsWith('name,')) continue; // Skip header
+
+        const cols = line.split(',');
+        if (cols.length >= 4) {
+          const agentName = cols[0].replaceAll('"', '').trim();
+          const displayName = cols[1].replaceAll('"', '').trim();
+          const title = cols[2].replaceAll('"', '').trim();
+          const icon = cols[3].replaceAll('"', '').trim();
+          const module = cols[10] ? cols[10].replaceAll('"', '').trim() : '';
+
+          // Build agent command: bmad:module:agent:name
+          const agentCommand = module ? `bmad:${module}:agent:${agentName}` : `bmad:agent:${agentName}`;
+
+          agentInfo.set(agentName, {
+            command: agentCommand,
+            displayName: displayName || agentName,
+            title: icon && title ? `${icon} ${title}` : title || agentName,
+          });
+        }
+      }
+    }
+
+    // Get all installed module directories
+    const entries = await fs.readdir(bmadDir, { withFileTypes: true });
+    const installedModules = entries
+      .filter((entry) => entry.isDirectory() && entry.name !== '_config' && entry.name !== 'docs' && entry.name !== '_memory')
+      .map((entry) => entry.name);
+
+    // Add core module to scan (it's installed at root level as _config, but we check src/core)
+    const coreModulePath = getSourcePath('core');
+    const modulePaths = new Map();
+
+    // Map all module source paths
+    if (await fs.pathExists(coreModulePath)) {
+      modulePaths.set('core', coreModulePath);
+    }
+
+    // Map installed module paths
+    for (const moduleName of installedModules) {
+      const modulePath = path.join(bmadDir, moduleName);
+      modulePaths.set(moduleName, modulePath);
+    }
+
+    // Scan each module for module-help.csv
+    for (const [moduleName, modulePath] of modulePaths) {
+      const helpFilePath = path.join(modulePath, 'module-help.csv');
+
+      if (await fs.pathExists(helpFilePath)) {
+        try {
+          const content = await fs.readFile(helpFilePath, 'utf8');
+          const lines = content.split('\n').filter((line) => line.trim() && !line.startsWith('#'));
+
+          for (const line of lines) {
+            // Skip header row
+            if (line.startsWith('module,')) {
+              continue;
+            }
+
+            // Parse the line - handle quoted fields with commas
+            const columns = this.parseCSVLine(line);
+            if (columns.length >= 12) {
+              // Map old schema to new schema
+              // Old: module,phase,name,code,sequence,workflow-file,command,required,agent,options,description,output-location,outputs
+              // New: module,phase,name,code,sequence,workflow-file,command,required,agent-name,agent-command,agent-display-name,agent-title,options,description,output-location,outputs
+
+              const [
+                module,
+                phase,
+                name,
+                code,
+                sequence,
+                workflowFile,
+                command,
+                required,
+                agentName,
+                options,
+                description,
+                outputLocation,
+                outputs,
+              ] = columns;
+
+              // If module column is empty, set it to this module's name (except for core which stays empty for universal tools)
+              const finalModule = (!module || module.trim() === '') && moduleName !== 'core' ? moduleName : module || '';
+
+              // Lookup agent info
+              const cleanAgentName = agentName ? agentName.trim() : '';
+              const agentData = agentInfo.get(cleanAgentName) || { command: '', displayName: '', title: '' };
+
+              // Build new row with agent info
+              const newRow = [
+                finalModule,
+                phase || '',
+                name || '',
+                code || '',
+                sequence || '',
+                workflowFile || '',
+                command || '',
+                required || 'false',
+                cleanAgentName,
+                agentData.command,
+                agentData.displayName,
+                agentData.title,
+                options || '',
+                description || '',
+                outputLocation || '',
+                outputs || '',
+              ];
+
+              allRows.push(newRow.map((c) => this.escapeCSVField(c)).join(','));
+            }
+          }
+
+          if (process.env.BMAD_VERBOSE_INSTALL === 'true') {
+            await prompts.log.message(`  Merged module-help from: ${moduleName}`);
+          }
+        } catch (error) {
+          await prompts.log.warn(`  Warning: Failed to read module-help.csv from ${moduleName}: ${error.message}`);
+        }
+      }
+    }
+
+    // Sort by module, then phase, then sequence
+    allRows.sort((a, b) => {
+      const colsA = this.parseCSVLine(a);
+      const colsB = this.parseCSVLine(b);
+
+      // Module comparison (empty module/universal tools come first)
+      const moduleA = (colsA[0] || '').toLowerCase();
+      const moduleB = (colsB[0] || '').toLowerCase();
+      if (moduleA !== moduleB) {
+        return moduleA.localeCompare(moduleB);
+      }
+
+      // Phase comparison
+      const phaseA = colsA[1] || '';
+      const phaseB = colsB[1] || '';
+      if (phaseA !== phaseB) {
+        return phaseA.localeCompare(phaseB);
+      }
+
+      // Sequence comparison
+      const seqA = parseInt(colsA[4] || '0', 10);
+      const seqB = parseInt(colsB[4] || '0', 10);
+      return seqA - seqB;
+    });
+
+    // Write merged catalog
+    const outputDir = path.join(bmadDir, '_config');
+    await fs.ensureDir(outputDir);
+    const outputPath = path.join(outputDir, 'bmad-help.csv');
+
+    const mergedContent = [headerRow, ...allRows].join('\n');
+    await fs.writeFile(outputPath, mergedContent, 'utf8');
+
+    // Track the installed file
+    this.installedFiles.add(outputPath);
+
+    if (process.env.BMAD_VERBOSE_INSTALL === 'true') {
+      await prompts.log.message(`  Generated bmad-help.csv: ${allRows.length} workflows`);
+    }
+  }
+
+  /**
+   * Parse a CSV line, handling quoted fields
+   * @param {string} line - CSV line to parse
+   * @returns {Array} Array of field values
+   */
+  parseCSVLine(line) {
+    const result = [];
+    let current = '';
+    let inQuotes = false;
+
+    for (let i = 0; i < line.length; i++) {
+      const char = line[i];
+      const nextChar = line[i + 1];
+
+      if (char === '"') {
+        if (inQuotes && nextChar === '"') {
+          // Escaped quote
+          current += '"';
+          i++; // Skip next quote
+        } else {
+          // Toggle quote mode
+          inQuotes = !inQuotes;
+        }
+      } else if (char === ',' && !inQuotes) {
+        result.push(current);
+        current = '';
+      } else {
+        current += char;
+      }
+    }
+    result.push(current);
+    return result;
+  }
+
+  /**
+   * Escape a CSV field if it contains special characters
+   * @param {string} field - Field value to escape
+   * @returns {string} Escaped field
+   */
+  escapeCSVField(field) {
+    if (field === null || field === undefined) {
+      return '';
+    }
+    const str = String(field);
+    // If field contains comma, quote, or newline, wrap in quotes and escape inner quotes
+    if (str.includes(',') || str.includes('"') || str.includes('\n')) {
+      return `"${str.replaceAll('"', '""')}"`;
+    }
+    return str;
+  }
+
   async createDirectoryStructure(bmadDir) {
     await fs.ensureDir(bmadDir);
-    await fs.ensureDir(path.join(bmadDir, '_cfg'));
-    await fs.ensureDir(path.join(bmadDir, '_cfg', 'agents'));
+    await fs.ensureDir(path.join(bmadDir, '_config'));
+    await fs.ensureDir(path.join(bmadDir, '_config', 'agents'));
+    await fs.ensureDir(path.join(bmadDir, '_config', 'custom'));
   }
 
   /**
@@ -964,7 +1937,7 @@ class Installer {
    * @param {Object} moduleConfigs - Collected configuration values
    */
   async generateModuleConfigs(bmadDir, moduleConfigs) {
-    const yaml = require('js-yaml');
+    const yaml = require('yaml');
 
     // Extract core config values to share with other modules
     const coreConfig = moduleConfigs.core || {};
@@ -972,7 +1945,7 @@ class Installer {
     // Get all installed module directories
     const entries = await fs.readdir(bmadDir, { withFileTypes: true });
     const installedModules = entries
-      .filter((entry) => entry.isDirectory() && entry.name !== '_cfg' && entry.name !== 'docs')
+      .filter((entry) => entry.isDirectory() && entry.name !== '_config' && entry.name !== 'docs')
       .map((entry) => entry.name);
 
     // Generate config.yaml for each installed module
@@ -1010,12 +1983,14 @@ class Installer {
           coreSection = '\n# Core Configuration Values\n';
         }
 
+        // Clean the config to remove any non-serializable values (like functions)
+        const cleanConfig = structuredClone(finalConfig);
+
         // Convert config to YAML
-        let yamlContent = yaml.dump(finalConfig, {
+        let yamlContent = yaml.stringify(cleanConfig, {
           indent: 2,
-          lineWidth: -1,
-          noRefs: true,
-          sortKeys: false,
+          lineWidth: 0,
+          minContentWidth: 0,
         });
 
         // If we have core values, reorganize the YAML to group them with their comment
@@ -1047,7 +2022,7 @@ class Installer {
         await fs.writeFile(configPath, content.endsWith('\n') ? content : content + '\n', 'utf8');
 
         // Track the config file in installedFiles
-        this.installedFiles.push(configPath);
+        this.installedFiles.add(configPath);
       }
     }
   }
@@ -1060,14 +2035,7 @@ class Installer {
   async installCoreWithDependencies(bmadDir, coreFiles) {
     const sourcePath = getModulePath('core');
     const targetPath = path.join(bmadDir, 'core');
-
-    // Install full core
     await this.installCore(bmadDir);
-
-    // If there are specific dependency files, ensure they're included
-    if (coreFiles) {
-      // Already handled by installCore for core module
-    }
   }
 
   /**
@@ -1086,11 +2054,13 @@ class Installer {
       moduleName,
       bmadDir,
       (filePath) => {
-        this.installedFiles.push(filePath);
+        this.installedFiles.add(filePath);
       },
       {
         skipModuleInstaller: true, // We'll run it later after IDE setup
         moduleConfig: moduleConfig, // Pass module config for conditional filtering
+        installer: this,
+        silent: true,
       },
     );
 
@@ -1122,8 +2092,8 @@ class Installer {
         const targetPath = path.join(agentsDir, fileName);
 
         if (await fs.pathExists(sourcePath)) {
-          await this.copyFileWithPlaceholderReplacement(sourcePath, targetPath, this.bmadFolderName || 'bmad');
-          this.installedFiles.push(targetPath);
+          await this.copyFileWithPlaceholderReplacement(sourcePath, targetPath);
+          this.installedFiles.add(targetPath);
         }
       }
     }
@@ -1138,8 +2108,8 @@ class Installer {
         const targetPath = path.join(tasksDir, fileName);
 
         if (await fs.pathExists(sourcePath)) {
-          await this.copyFileWithPlaceholderReplacement(sourcePath, targetPath, this.bmadFolderName || 'bmad');
-          this.installedFiles.push(targetPath);
+          await this.copyFileWithPlaceholderReplacement(sourcePath, targetPath);
+          this.installedFiles.add(targetPath);
         }
       }
     }
@@ -1154,8 +2124,8 @@ class Installer {
         const targetPath = path.join(toolsDir, fileName);
 
         if (await fs.pathExists(sourcePath)) {
-          await this.copyFileWithPlaceholderReplacement(sourcePath, targetPath, this.bmadFolderName || 'bmad');
-          this.installedFiles.push(targetPath);
+          await this.copyFileWithPlaceholderReplacement(sourcePath, targetPath);
+          this.installedFiles.add(targetPath);
         }
       }
     }
@@ -1170,8 +2140,8 @@ class Installer {
         const targetPath = path.join(templatesDir, fileName);
 
         if (await fs.pathExists(sourcePath)) {
-          await this.copyFileWithPlaceholderReplacement(sourcePath, targetPath, this.bmadFolderName || 'bmad');
-          this.installedFiles.push(targetPath);
+          await this.copyFileWithPlaceholderReplacement(sourcePath, targetPath);
+          this.installedFiles.add(targetPath);
         }
       }
     }
@@ -1185,8 +2155,8 @@ class Installer {
         await fs.ensureDir(path.dirname(targetPath));
 
         if (await fs.pathExists(dataPath)) {
-          await this.copyFileWithPlaceholderReplacement(dataPath, targetPath, this.bmadFolderName || 'bmad');
-          this.installedFiles.push(targetPath);
+          await this.copyFileWithPlaceholderReplacement(dataPath, targetPath);
+          this.installedFiles.add(targetPath);
         }
       }
     }
@@ -1207,25 +2177,55 @@ class Installer {
     const sourcePath = getModulePath('core');
     const targetPath = path.join(bmadDir, 'core');
 
-    // Copy core files with filtering for localskip agents
-    await this.copyDirectoryWithFiltering(sourcePath, targetPath);
+    // Copy core files (skip .agent.yaml files like modules do)
+    await this.copyCoreFiles(sourcePath, targetPath);
+
+    // Compile agents using the same compiler as modules
+    const { ModuleManager } = require('../modules/manager');
+    const moduleManager = new ModuleManager();
+    await moduleManager.compileModuleAgents(sourcePath, targetPath, 'core', bmadDir, this);
 
     // Process agent files to inject activation block
     await this.processAgentFiles(targetPath, 'core');
   }
 
   /**
-   * Copy directory with filtering for localskip agents
-   * @param {string} sourcePath - Source directory path
-   * @param {string} targetPath - Target directory path
+   * Copy core files (similar to copyModuleWithFiltering but for core)
+   * @param {string} sourcePath - Source path
+   * @param {string} targetPath - Target path
    */
-  async copyDirectoryWithFiltering(sourcePath, targetPath) {
-    // Get all files in source directory
+  async copyCoreFiles(sourcePath, targetPath) {
+    // Get all files in source
     const files = await this.getFileList(sourcePath);
 
     for (const file of files) {
+      // Skip sub-modules directory - these are IDE-specific and handled separately
+      if (file.startsWith('sub-modules/')) {
+        continue;
+      }
+
+      // Skip sidecar directories - they are handled separately during agent compilation
+      if (
+        path
+          .dirname(file)
+          .split('/')
+          .some((dir) => dir.toLowerCase().includes('sidecar'))
+      ) {
+        continue;
+      }
+
+      // Skip module.yaml at root - it's only needed at install time
+      if (file === 'module.yaml') {
+        continue;
+      }
+
       // Skip config.yaml templates - we'll generate clean ones with actual values
-      if (file === 'config.yaml' || file.endsWith('/config.yaml')) {
+      if (file === 'config.yaml' || file.endsWith('/config.yaml') || file === 'custom.yaml' || file.endsWith('/custom.yaml')) {
+        continue;
+      }
+
+      // Skip .agent.yaml files - they will be compiled separately
+      if (file.endsWith('.agent.yaml')) {
         continue;
       }
 
@@ -1233,23 +2233,24 @@ class Installer {
       const targetFile = path.join(targetPath, file);
 
       // Check if this is an agent file
-      if (file.includes('agents/') && file.endsWith('.md')) {
+      if (file.startsWith('agents/') && file.endsWith('.md')) {
         // Read the file to check for localskip
         const content = await fs.readFile(sourceFile, 'utf8');
 
         // Check for localskip="true" in the agent tag
         const agentMatch = content.match(/<agent[^>]*\slocalskip="true"[^>]*>/);
         if (agentMatch) {
-          console.log(chalk.dim(`  Skipping web-only agent: ${path.basename(file)}`));
+          await prompts.log.message(`  Skipping web-only agent: ${path.basename(file)}`);
           continue; // Skip this agent
         }
       }
 
       // Copy the file with placeholder replacement
-      await this.copyFileWithPlaceholderReplacement(sourceFile, targetFile, this.bmadFolderName || 'bmad');
+      await fs.ensureDir(path.dirname(targetFile));
+      await this.copyFileWithPlaceholderReplacement(sourceFile, targetFile);
 
       // Track the installed file
-      this.installedFiles.push(targetFile);
+      this.installedFiles.add(targetFile);
     }
   }
 
@@ -1267,10 +2268,6 @@ class Installer {
       const fullPath = path.join(dir, entry.name);
 
       if (entry.isDirectory()) {
-        // Skip _module-installer directories
-        if (entry.name === '_module-installer') {
-          continue;
-        }
         const subFiles = await this.getFileList(fullPath, baseDir);
         files.push(...subFiles);
       } else {
@@ -1296,372 +2293,42 @@ class Installer {
 
     // Determine project directory (parent of bmad/ directory)
     const bmadDir = path.dirname(modulePath);
-    const projectDir = path.dirname(bmadDir);
-    const cfgAgentsDir = path.join(bmadDir, '_cfg', 'agents');
+    const cfgAgentsDir = path.join(bmadDir, '_config', 'agents');
 
-    // Ensure _cfg/agents directory exists
+    // Ensure _config/agents directory exists
     await fs.ensureDir(cfgAgentsDir);
 
     // Get all agent files
     const agentFiles = await fs.readdir(agentsPath);
 
     for (const agentFile of agentFiles) {
-      // Handle YAML agents - build them to .md
+      // Skip .agent.yaml files - they should already be compiled by compileModuleAgents
       if (agentFile.endsWith('.agent.yaml')) {
-        const agentName = agentFile.replace('.agent.yaml', '');
-        const yamlPath = path.join(agentsPath, agentFile);
-        const mdPath = path.join(agentsPath, `${agentName}.md`);
-        const customizePath = path.join(cfgAgentsDir, `${moduleName}-${agentName}.customize.yaml`);
-
-        // Create customize template if it doesn't exist
-        if (!(await fs.pathExists(customizePath))) {
-          const genericTemplatePath = getSourcePath('utility', 'templates', 'agent.customize.template.yaml');
-          if (await fs.pathExists(genericTemplatePath)) {
-            await this.copyFileWithPlaceholderReplacement(genericTemplatePath, customizePath, this.bmadFolderName || 'bmad');
-            console.log(chalk.dim(`  Created customize: ${moduleName}-${agentName}.customize.yaml`));
+        continue;
+      }
+
+      // Only process .md files (already compiled from YAML)
+      if (!agentFile.endsWith('.md')) {
+        continue;
+      }
+
+      const agentName = agentFile.replace('.md', '');
+      const mdPath = path.join(agentsPath, agentFile);
+      const customizePath = path.join(cfgAgentsDir, `${moduleName}-${agentName}.customize.yaml`);
+
+      // For .md files that are already compiled, we don't need to do much
+      // Just ensure the customize template exists
+      if (!(await fs.pathExists(customizePath))) {
+        const genericTemplatePath = getSourcePath('utility', 'agent-components', 'agent.customize.template.yaml');
+        if (await fs.pathExists(genericTemplatePath)) {
+          await this.copyFileWithPlaceholderReplacement(genericTemplatePath, customizePath);
+          if (process.env.BMAD_VERBOSE_INSTALL === 'true') {
+            await prompts.log.message(`  Created customize: ${moduleName}-${agentName}.customize.yaml`);
           }
         }
-
-        // Build YAML + customize to .md
-        const customizeExists = await fs.pathExists(customizePath);
-        const xmlContent = await this.xmlHandler.buildFromYaml(yamlPath, customizeExists ? customizePath : null, {
-          includeMetadata: true,
-        });
-
-        // DO NOT replace {project-root} - LLMs understand this placeholder at runtime
-        // const processedContent = xmlContent.replaceAll('{project-root}', projectDir);
-
-        // Write the built .md file to bmad/{module}/agents/ with POSIX-compliant final newline
-        const content = xmlContent.endsWith('\n') ? xmlContent : xmlContent + '\n';
-        await fs.writeFile(mdPath, content, 'utf8');
-        this.installedFiles.push(mdPath);
-
-        // Remove the source YAML file - we can regenerate from installer source if needed
-        await fs.remove(yamlPath);
-
-        console.log(chalk.dim(`  Built agent: ${agentName}.md`));
-      }
-      // Handle legacy .md agents - inject activation if needed
-      else if (agentFile.endsWith('.md')) {
-        const agentPath = path.join(agentsPath, agentFile);
-        let content = await fs.readFile(agentPath, 'utf8');
-
-        // Check if content has agent XML and no activation block
-        if (content.includes('<agent') && !content.includes('<activation')) {
-          // Inject the activation block using XML handler
-          content = this.xmlHandler.injectActivationSimple(content);
-          // Ensure POSIX-compliant final newline
-          const finalContent = content.endsWith('\n') ? content : content + '\n';
-          await fs.writeFile(agentPath, finalContent, 'utf8');
-        }
-      }
-    }
-  }
-
-  /**
-   * Build standalone agents in bmad/agents/ directory
-   * @param {string} bmadDir - Path to bmad directory
-   * @param {string} projectDir - Path to project directory
-   */
-  async buildStandaloneAgents(bmadDir, projectDir) {
-    const standaloneAgentsPath = path.join(bmadDir, 'agents');
-    const cfgAgentsDir = path.join(bmadDir, '_cfg', 'agents');
-
-    // Check if standalone agents directory exists
-    if (!(await fs.pathExists(standaloneAgentsPath))) {
-      return;
-    }
-
-    // Get all subdirectories in agents/
-    const agentDirs = await fs.readdir(standaloneAgentsPath, { withFileTypes: true });
-
-    for (const agentDir of agentDirs) {
-      if (!agentDir.isDirectory()) continue;
-
-      const agentDirPath = path.join(standaloneAgentsPath, agentDir.name);
-
-      // Find any .agent.yaml file in the directory
-      const files = await fs.readdir(agentDirPath);
-      const yamlFile = files.find((f) => f.endsWith('.agent.yaml'));
-
-      if (!yamlFile) continue;
-
-      const agentName = path.basename(yamlFile, '.agent.yaml');
-      const sourceYamlPath = path.join(agentDirPath, yamlFile);
-      const targetMdPath = path.join(agentDirPath, `${agentName}.md`);
-      const customizePath = path.join(cfgAgentsDir, `${agentName}.customize.yaml`);
-
-      // Check for customizations
-      const customizeExists = await fs.pathExists(customizePath);
-      let customizedFields = [];
-
-      if (customizeExists) {
-        const customizeContent = await fs.readFile(customizePath, 'utf8');
-        const yaml = require('js-yaml');
-        const customizeYaml = yaml.load(customizeContent);
-
-        // Detect what fields are customized (similar to rebuildAgentFiles)
-        if (customizeYaml) {
-          if (customizeYaml.persona) {
-            for (const [key, value] of Object.entries(customizeYaml.persona)) {
-              if (value !== '' && value !== null && !(Array.isArray(value) && value.length === 0)) {
-                customizedFields.push(`persona.${key}`);
-              }
-            }
-          }
-          if (customizeYaml.agent?.metadata) {
-            for (const [key, value] of Object.entries(customizeYaml.agent.metadata)) {
-              if (value !== '' && value !== null) {
-                customizedFields.push(`metadata.${key}`);
-              }
-            }
-          }
-          if (customizeYaml.critical_actions && customizeYaml.critical_actions.length > 0) {
-            customizedFields.push('critical_actions');
-          }
-          if (customizeYaml.menu && customizeYaml.menu.length > 0) {
-            customizedFields.push('menu');
-          }
-        }
-      }
-
-      // Build YAML to XML .md
-      const xmlContent = await this.xmlHandler.buildFromYaml(sourceYamlPath, customizeExists ? customizePath : null, {
-        includeMetadata: true,
-      });
-
-      // DO NOT replace {project-root} - LLMs understand this placeholder at runtime
-      // const processedContent = xmlContent.replaceAll('{project-root}', projectDir);
-
-      // Write the built .md file with POSIX-compliant final newline
-      const content = xmlContent.endsWith('\n') ? xmlContent : xmlContent + '\n';
-      await fs.writeFile(targetMdPath, content, 'utf8');
-
-      // Display result
-      if (customizedFields.length > 0) {
-        console.log(chalk.dim(`  Built standalone agent: ${agentName}.md `) + chalk.yellow(`(customized: ${customizedFields.join(', ')})`));
-      } else {
-        console.log(chalk.dim(`  Built standalone agent: ${agentName}.md`));
-      }
-    }
-  }
-
-  /**
-   * Rebuild agent files from installer source (for compile command)
-   * @param {string} modulePath - Path to module in bmad/ installation
-   * @param {string} moduleName - Module name
-   */
-  async rebuildAgentFiles(modulePath, moduleName) {
-    // Get source agents directory from installer
-    const sourceAgentsPath =
-      moduleName === 'core' ? path.join(getModulePath('core'), 'agents') : path.join(getSourcePath(`modules/${moduleName}`), 'agents');
-
-    if (!(await fs.pathExists(sourceAgentsPath))) {
-      return; // No source agents to rebuild
-    }
-
-    // Determine project directory (parent of bmad/ directory)
-    const bmadDir = path.dirname(modulePath);
-    const projectDir = path.dirname(bmadDir);
-    const cfgAgentsDir = path.join(bmadDir, '_cfg', 'agents');
-    const targetAgentsPath = path.join(modulePath, 'agents');
-
-    // Ensure target directory exists
-    await fs.ensureDir(targetAgentsPath);
-
-    // Get all YAML agent files from source
-    const sourceFiles = await fs.readdir(sourceAgentsPath);
-
-    for (const file of sourceFiles) {
-      if (file.endsWith('.agent.yaml')) {
-        const agentName = file.replace('.agent.yaml', '');
-        const sourceYamlPath = path.join(sourceAgentsPath, file);
-        const targetMdPath = path.join(targetAgentsPath, `${agentName}.md`);
-        const customizePath = path.join(cfgAgentsDir, `${moduleName}-${agentName}.customize.yaml`);
-
-        // Check for customizations
-        const customizeExists = await fs.pathExists(customizePath);
-        let customizedFields = [];
-
-        if (customizeExists) {
-          const customizeContent = await fs.readFile(customizePath, 'utf8');
-          const yaml = require('js-yaml');
-          const customizeYaml = yaml.load(customizeContent);
-
-          // Detect what fields are customized
-          if (customizeYaml) {
-            if (customizeYaml.persona) {
-              for (const [key, value] of Object.entries(customizeYaml.persona)) {
-                if (value !== '' && value !== null && !(Array.isArray(value) && value.length === 0)) {
-                  customizedFields.push(`persona.${key}`);
-                }
-              }
-            }
-            if (customizeYaml.agent?.metadata) {
-              for (const [key, value] of Object.entries(customizeYaml.agent.metadata)) {
-                if (value !== '' && value !== null) {
-                  customizedFields.push(`metadata.${key}`);
-                }
-              }
-            }
-            if (customizeYaml.critical_actions && customizeYaml.critical_actions.length > 0) {
-              customizedFields.push('critical_actions');
-            }
-            if (customizeYaml.memories && customizeYaml.memories.length > 0) {
-              customizedFields.push('memories');
-            }
-            if (customizeYaml.menu && customizeYaml.menu.length > 0) {
-              customizedFields.push('menu');
-            }
-            if (customizeYaml.prompts && customizeYaml.prompts.length > 0) {
-              customizedFields.push('prompts');
-            }
-          }
-        }
-
-        // Build YAML + customize to .md
-        const xmlContent = await this.xmlHandler.buildFromYaml(sourceYamlPath, customizeExists ? customizePath : null, {
-          includeMetadata: true,
-        });
-
-        // DO NOT replace {project-root} - LLMs understand this placeholder at runtime
-        // const processedContent = xmlContent.replaceAll('{project-root}', projectDir);
-
-        // Write the rebuilt .md file with POSIX-compliant final newline
-        const content = xmlContent.endsWith('\n') ? xmlContent : xmlContent + '\n';
-        await fs.writeFile(targetMdPath, content, 'utf8');
-
-        // Display result with customizations if any
-        if (customizedFields.length > 0) {
-          console.log(chalk.dim(`  Rebuilt agent: ${agentName}.md `) + chalk.yellow(`(customized: ${customizedFields.join(', ')})`));
-        } else {
-          console.log(chalk.dim(`  Rebuilt agent: ${agentName}.md`));
-        }
-      }
-    }
-  }
-
-  /**
-   * Compile/rebuild all agents and tasks for quick updates
-   * @param {Object} config - Compilation configuration
-   * @returns {Object} Compilation results
-   */
-  async compileAgents(config) {
-    const ora = require('ora');
-    const spinner = ora('Starting agent compilation...').start();
-
-    try {
-      const projectDir = path.resolve(config.directory);
-      const bmadDir = await this.findBmadDir(projectDir);
-
-      // Check if bmad directory exists
-      if (!(await fs.pathExists(bmadDir))) {
-        spinner.fail('No BMAD installation found');
-        throw new Error(`BMAD not installed at ${bmadDir}`);
-      }
-
-      let agentCount = 0;
-      let taskCount = 0;
-
-      // Process all modules in bmad directory
-      spinner.text = 'Rebuilding agent files...';
-      const entries = await fs.readdir(bmadDir, { withFileTypes: true });
-
-      for (const entry of entries) {
-        if (entry.isDirectory() && entry.name !== '_cfg' && entry.name !== 'docs') {
-          const modulePath = path.join(bmadDir, entry.name);
-
-          // Special handling for standalone agents in bmad/agents/ directory
-          if (entry.name === 'agents') {
-            spinner.text = 'Building standalone agents...';
-            await this.buildStandaloneAgents(bmadDir, projectDir);
-
-            // Count standalone agents
-            const standaloneAgentsPath = path.join(bmadDir, 'agents');
-            const standaloneAgentDirs = await fs.readdir(standaloneAgentsPath, { withFileTypes: true });
-            for (const agentDir of standaloneAgentDirs) {
-              if (agentDir.isDirectory()) {
-                const agentDirPath = path.join(standaloneAgentsPath, agentDir.name);
-                const agentFiles = await fs.readdir(agentDirPath);
-                agentCount += agentFiles.filter((f) => f.endsWith('.md') && !f.endsWith('.agent.yaml')).length;
-              }
-            }
-          } else {
-            // Rebuild module agents from installer source
-            const agentsPath = path.join(modulePath, 'agents');
-            if (await fs.pathExists(agentsPath)) {
-              await this.rebuildAgentFiles(modulePath, entry.name);
-              const agentFiles = await fs.readdir(agentsPath);
-              agentCount += agentFiles.filter((f) => f.endsWith('.md')).length;
-            }
-
-            // Count tasks (already built)
-            const tasksPath = path.join(modulePath, 'tasks');
-            if (await fs.pathExists(tasksPath)) {
-              const taskFiles = await fs.readdir(tasksPath);
-              taskCount += taskFiles.filter((f) => f.endsWith('.md')).length;
-            }
-          }
-        }
-      }
-
-      // Regenerate manifests after compilation
-      spinner.start('Regenerating manifests...');
-      const installedModules = entries
-        .filter((e) => e.isDirectory() && e.name !== '_cfg' && e.name !== 'docs' && e.name !== 'agents' && e.name !== 'core')
-        .map((e) => e.name);
-      const manifestGen = new ManifestGenerator();
-
-      // Get existing IDE list from manifest
-      const existingManifestPath = path.join(bmadDir, '_cfg', 'manifest.yaml');
-      let existingIdes = [];
-      if (await fs.pathExists(existingManifestPath)) {
-        const manifestContent = await fs.readFile(existingManifestPath, 'utf8');
-        const yaml = require('js-yaml');
-        const manifest = yaml.load(manifestContent);
-        existingIdes = manifest.ides || [];
-      }
-
-      await manifestGen.generateManifests(bmadDir, installedModules, [], {
-        ides: existingIdes,
-      });
-      spinner.succeed('Manifests regenerated');
-
-      // Update IDE configurations using the existing IDE list from manifest
-      if (existingIdes && existingIdes.length > 0) {
-        spinner.start('Updating IDE configurations...');
-
-        for (const ide of existingIdes) {
-          spinner.text = `Updating ${ide}...`;
-
-          // Stop spinner before IDE setup to prevent blocking any potential prompts
-          // However, we pass _alreadyConfigured to skip all prompts during compile
-          spinner.stop();
-
-          await this.ideManager.setup(ide, projectDir, bmadDir, {
-            selectedModules: installedModules,
-            skipModuleInstall: true, // Skip module installation, just update IDE files
-            verbose: config.verbose,
-            preCollectedConfig: { _alreadyConfigured: true }, // Skip all interactive prompts during compile
-          });
-
-          // Restart spinner for next IDE
-          if (existingIdes.indexOf(ide) < existingIdes.length - 1) {
-            spinner.start('Updating IDE configurations...');
-          }
-        }
-
-        console.log(chalk.green('✓ IDE configurations updated'));
-      } else {
-        console.log(chalk.yellow('⚠️  No IDEs configured. Skipping IDE update.'));
-      }
-
-      return { agentCount, taskCount };
-    } catch (error) {
-      spinner.fail('Compilation failed');
-      throw error;
-    }
-  }
+      }
+    }
+  }
 
   /**
    * Private: Update core
@@ -1676,6 +2343,12 @@ class Installer {
     } else {
       // Selective update - preserve user modifications
       await this.fileOps.syncDirectory(sourcePath, targetPath);
+
+      // Recompile agents (#1133)
+      const { ModuleManager } = require('../modules/manager');
+      const moduleManager = new ModuleManager();
+      await moduleManager.compileModuleAgents(sourcePath, targetPath, 'core', bmadDir, this);
+      await this.processAgentFiles(targetPath, 'core');
     }
   }
 
@@ -1685,45 +2358,172 @@ class Installer {
    * @returns {Object} Update result
    */
   async quickUpdate(config) {
-    const ora = require('ora');
-    const spinner = ora('Starting quick update...').start();
+    const spinner = await prompts.spinner();
+    spinner.start('Starting quick update...');
 
     try {
       const projectDir = path.resolve(config.directory);
-      const bmadDir = await this.findBmadDir(projectDir);
+      const { bmadDir } = await this.findBmadDir(projectDir);
 
       // Check if bmad directory exists
       if (!(await fs.pathExists(bmadDir))) {
-        spinner.fail('No BMAD installation found');
+        spinner.stop('No BMAD installation found');
         throw new Error(`BMAD not installed at ${bmadDir}. Use regular install for first-time setup.`);
       }
 
-      spinner.text = 'Detecting installed modules and configuration...';
+      spinner.message('Detecting installed modules and configuration...');
 
       // Detect existing installation
       const existingInstall = await this.detector.detect(bmadDir);
       const installedModules = existingInstall.modules.map((m) => m.id);
       const configuredIdes = existingInstall.ides || [];
+      const projectRoot = path.dirname(bmadDir);
+
+      // Get custom module sources: first from --custom-content (re-cache from source), then from cache
+      const customModuleSources = new Map();
+      if (config.customContent?.sources?.length > 0) {
+        for (const source of config.customContent.sources) {
+          if (source.id && source.path && (await fs.pathExists(source.path))) {
+            customModuleSources.set(source.id, {
+              id: source.id,
+              name: source.name || source.id,
+              sourcePath: source.path,
+              cached: false, // From CLI, will be re-cached
+            });
+          }
+        }
+      }
+      const cacheDir = path.join(bmadDir, '_config', 'custom');
+      if (await fs.pathExists(cacheDir)) {
+        const cachedModules = await fs.readdir(cacheDir, { withFileTypes: true });
+
+        for (const cachedModule of cachedModules) {
+          const moduleId = cachedModule.name;
+          const cachedPath = path.join(cacheDir, moduleId);
+
+          // Skip if path doesn't exist (broken symlink, deleted dir) - avoids lstat ENOENT
+          if (!(await fs.pathExists(cachedPath))) {
+            continue;
+          }
+          if (!cachedModule.isDirectory()) {
+            continue;
+          }
+
+          // Skip if we already have this module from manifest
+          if (customModuleSources.has(moduleId)) {
+            continue;
+          }
+
+          // Check if this is an external official module - skip cache for those
+          const isExternal = await this.moduleManager.isExternalModule(moduleId);
+          if (isExternal) {
+            // External modules are handled via cloneExternalModule, not from cache
+            continue;
+          }
+
+          // Check if this is actually a custom module (has module.yaml)
+          const moduleYamlPath = path.join(cachedPath, 'module.yaml');
+          if (await fs.pathExists(moduleYamlPath)) {
+            // For quick update, we always rebuild from cache
+            customModuleSources.set(moduleId, {
+              id: moduleId,
+              name: moduleId, // We'll read the actual name if needed
+              sourcePath: cachedPath,
+              cached: true, // Flag to indicate this is from cache
+            });
+          }
+        }
+      }
 
       // Load saved IDE configurations
       const savedIdeConfigs = await this.ideConfigManager.loadAllIdeConfigs(bmadDir);
 
       // Get available modules (what we have source for)
-      const availableModules = await this.moduleManager.listAvailable();
-      const availableModuleIds = new Set(availableModules.map((m) => m.id));
+      const availableModulesData = await this.moduleManager.listAvailable();
+      const availableModules = [...availableModulesData.modules, ...availableModulesData.customModules];
+
+      // Add external official modules to available modules
+      // These can always be obtained by cloning from their remote URLs
+      const { ExternalModuleManager } = require('../modules/external-manager');
+      const externalManager = new ExternalModuleManager();
+      const externalModules = await externalManager.listAvailable();
+      for (const externalModule of externalModules) {
+        // Only add if not already in the list and is installed
+        if (installedModules.includes(externalModule.code) && !availableModules.some((m) => m.id === externalModule.code)) {
+          availableModules.push({
+            id: externalModule.code,
+            name: externalModule.name,
+            isExternal: true,
+            fromExternal: true,
+          });
+        }
+      }
+
+      // Add custom modules from manifest if their sources exist
+      for (const [moduleId, customModule] of customModuleSources) {
+        // Use the absolute sourcePath
+        const sourcePath = customModule.sourcePath;
+
+        // Check if source exists at the recorded path
+        if (
+          sourcePath &&
+          (await fs.pathExists(sourcePath)) && // Add to available modules if not already there
+          !availableModules.some((m) => m.id === moduleId)
+        ) {
+          availableModules.push({
+            id: moduleId,
+            name: customModule.name || moduleId,
+            path: sourcePath,
+            isCustom: true,
+            fromManifest: true,
+          });
+        }
+      }
+
+      // Handle missing custom module sources using shared method
+      const customModuleResult = await this.handleMissingCustomSources(
+        customModuleSources,
+        bmadDir,
+        projectRoot,
+        'update',
+        installedModules,
+        config.skipPrompts || false,
+      );
+
+      const { validCustomModules, keptModulesWithoutSources } = customModuleResult;
+
+      const customModulesFromManifest = validCustomModules.map((m) => ({
+        ...m,
+        isCustom: true,
+        hasUpdate: true,
+      }));
+
+      const allAvailableModules = [...availableModules, ...customModulesFromManifest];
+      const availableModuleIds = new Set(allAvailableModules.map((m) => m.id));
+
+      // Core module is special - never include it in update flow
+      const nonCoreInstalledModules = installedModules.filter((id) => id !== 'core');
 
       // Only update modules that are BOTH installed AND available (we have source for)
-      const modulesToUpdate = installedModules.filter((id) => availableModuleIds.has(id));
-      const skippedModules = installedModules.filter((id) => !availableModuleIds.has(id));
+      const modulesToUpdate = nonCoreInstalledModules.filter((id) => availableModuleIds.has(id));
+      const skippedModules = nonCoreInstalledModules.filter((id) => !availableModuleIds.has(id));
+
+      // Add custom modules that were kept without sources to the skipped modules
+      // This ensures their agents are preserved in the manifest
+      for (const keptModule of keptModulesWithoutSources) {
+        if (!skippedModules.includes(keptModule)) {
+          skippedModules.push(keptModule);
+        }
+      }
 
-      spinner.succeed(`Found ${modulesToUpdate.length} module(s) to update and ${configuredIdes.length} configured tool(s)`);
+      spinner.stop(`Found ${modulesToUpdate.length} module(s) to update and ${configuredIdes.length} configured tool(s)`);
 
       if (skippedModules.length > 0) {
-        console.log(chalk.yellow(`⚠️  Skipping ${skippedModules.length} module(s) - no source available: ${skippedModules.join(', ')}`));
+        await prompts.log.warn(`Skipping ${skippedModules.length} module(s) - no source available: ${skippedModules.join(', ')}`);
       }
 
       // Load existing configs and collect new fields (if any)
-      console.log(chalk.cyan('\n📋 Checking for new configuration options...'));
+      await prompts.log.info('Checking for new configuration options...');
       await this.configCollector.loadExistingConfig(projectDir);
 
       let promptedForNewFields = false;
@@ -1743,7 +2543,7 @@ class Installer {
       }
 
       if (!promptedForNewFields) {
-        console.log(chalk.green('✓ All configuration is up to date, no new options to configure'));
+        await prompts.log.success('All configuration is up to date, no new options to configure');
       }
 
       // Add metadata
@@ -1753,9 +2553,6 @@ class Installer {
         lastModified: new Date().toISOString(),
       };
 
-      // Now run the full installation with the collected configs
-      spinner.start('Updating BMAD installation...');
-
       // Build the config object for the installer
       const installConfig = {
         directory: projectDir,
@@ -1768,12 +2565,19 @@ class Installer {
         _quickUpdate: true, // Flag to skip certain prompts
         _preserveModules: skippedModules, // Preserve these in manifest even though we didn't update them
         _savedIdeConfigs: savedIdeConfigs, // Pass saved IDE configs to installer
+        _customModuleSources: customModuleSources, // Pass custom module sources for updates
+        _existingModules: installedModules, // Pass all installed modules for manifest generation
+        customContent: config.customContent, // Pass through for re-caching from source
       };
 
       // Call the standard install method
       const result = await this.install(installConfig);
 
-      spinner.succeed('Quick update complete!');
+      // Only succeed the spinner if it's still spinning
+      // (install method might have stopped it if folder name changed)
+      if (spinner.isSpinning) {
+        spinner.stop('Quick update complete!');
+      }
 
       return {
         success: true,
@@ -1784,115 +2588,170 @@ class Installer {
         ides: configuredIdes,
       };
     } catch (error) {
-      spinner.fail('Quick update failed');
+      spinner.error('Quick update failed');
       throw error;
     }
   }
 
   /**
-   * Private: Prompt for update action
-   */
-  async promptUpdateAction() {
-    const inquirer = require('inquirer');
-    return await inquirer.prompt([
-      {
-        type: 'list',
-        name: 'action',
-        message: 'What would you like to do?',
-        choices: [
-          { name: 'Update existing installation', value: 'update' },
-          { name: 'Remove and reinstall', value: 'reinstall' },
-          { name: 'Cancel', value: 'cancel' },
-        ],
-      },
-    ]);
-  }
-
-  /**
-   * Handle legacy BMAD v4 migration with automatic backup
-   * @param {string} projectDir - Project directory
-   * @param {Object} legacyV4 - Legacy V4 detection result with offenders array
+   * Compile agents with customizations only
+   * @param {Object} config - Configuration with directory
+   * @returns {Object} Compilation result
    */
-  async handleLegacyV4Migration(projectDir, legacyV4) {
-    console.log(chalk.yellow.bold('\n⚠️  Legacy BMAD v4 detected'));
-    console.log(chalk.dim('The installer found legacy artefacts in your project.\n'));
-
-    // Separate .bmad* folders (auto-backup) from other offending paths (manual cleanup)
-    const bmadFolders = legacyV4.offenders.filter((p) => {
-      const name = path.basename(p);
-      return name.startsWith('.bmad'); // Only dot-prefixed folders get auto-backed up
-    });
-    const otherOffenders = legacyV4.offenders.filter((p) => {
-      const name = path.basename(p);
-      return !name.startsWith('.bmad'); // Everything else is manual cleanup
-    });
+  async compileAgents(config) {
+    // Using @clack prompts
+    const { ModuleManager } = require('../modules/manager');
+    const { getSourcePath } = require('../../../lib/project-root');
 
-    const inquirer = require('inquirer');
+    const spinner = await prompts.spinner();
+    spinner.start('Recompiling agents with customizations...');
 
-    // Show warning for other offending paths FIRST
-    if (otherOffenders.length > 0) {
-      console.log(chalk.yellow('⚠️  Recommended cleanup:'));
-      console.log(chalk.dim('It is recommended to remove the following items before proceeding:\n'));
-      for (const p of otherOffenders) console.log(chalk.dim(` - ${p}`));
+    try {
+      const projectDir = path.resolve(config.directory);
+      const { bmadDir } = await this.findBmadDir(projectDir);
 
-      console.log(chalk.cyan('\nCleanup commands you can copy/paste:'));
-      console.log(chalk.dim('macOS/Linux:'));
-      for (const p of otherOffenders) console.log(chalk.dim(`  rm -rf '${p}'`));
-      console.log(chalk.dim('Windows:'));
-      for (const p of otherOffenders) console.log(chalk.dim(`  rmdir /S /Q "${p}"`));
+      // Check if bmad directory exists
+      if (!(await fs.pathExists(bmadDir))) {
+        spinner.stop('No BMAD installation found');
+        throw new Error(`BMAD not installed at ${bmadDir}. Use regular install for first-time setup.`);
+      }
 
-      const { cleanedUp } = await inquirer.prompt([
-        {
-          type: 'confirm',
-          name: 'cleanedUp',
-          message: 'Have you completed the recommended cleanup? (You can proceed without it, but it is recommended)',
-          default: false,
-        },
-      ]);
+      // Detect existing installation
+      const existingInstall = await this.detector.detect(bmadDir);
+      const installedModules = existingInstall.modules.map((m) => m.id);
 
-      if (cleanedUp) {
-        console.log(chalk.green('✓ Cleanup acknowledged\n'));
-      } else {
-        console.log(chalk.yellow('⚠️  Proceeding without recommended cleanup\n'));
+      // Initialize module manager
+      const moduleManager = new ModuleManager();
+      moduleManager.setBmadFolderName(path.basename(bmadDir));
+
+      let totalAgentCount = 0;
+
+      // Get custom module sources from cache
+      const customModuleSources = new Map();
+      const cacheDir = path.join(bmadDir, '_config', 'custom');
+      if (await fs.pathExists(cacheDir)) {
+        const cachedModules = await fs.readdir(cacheDir, { withFileTypes: true });
+
+        for (const cachedModule of cachedModules) {
+          if (cachedModule.isDirectory()) {
+            const moduleId = cachedModule.name;
+            const cachedPath = path.join(cacheDir, moduleId);
+            const moduleYamlPath = path.join(cachedPath, 'module.yaml');
+
+            // Check if this is actually a custom module
+            if (await fs.pathExists(moduleYamlPath)) {
+              // Check if this is an external official module - skip cache for those
+              const isExternal = await this.moduleManager.isExternalModule(moduleId);
+              if (isExternal) {
+                // External modules are handled via cloneExternalModule, not from cache
+                continue;
+              }
+              customModuleSources.set(moduleId, cachedPath);
+            }
+          }
+        }
       }
-    }
 
-    // Handle .bmad* folders with automatic backup
-    if (bmadFolders.length > 0) {
-      console.log(chalk.cyan('The following legacy folders will be moved to v4-backup:'));
-      for (const p of bmadFolders) console.log(chalk.dim(` - ${p}`));
+      // Process each installed module
+      for (const moduleId of installedModules) {
+        spinner.message(`Recompiling agents in ${moduleId}...`);
 
-      const { proceed } = await inquirer.prompt([
-        {
-          type: 'confirm',
-          name: 'proceed',
-          message: 'Proceed with backing up legacy v4 folders?',
-          default: true,
-        },
-      ]);
+        // Get source path
+        let sourcePath;
+        if (moduleId === 'core') {
+          sourcePath = getSourcePath('core');
+        } else {
+          // First check if it's in the custom cache
+          if (customModuleSources.has(moduleId)) {
+            sourcePath = customModuleSources.get(moduleId);
+          } else {
+            sourcePath = await moduleManager.findModuleSource(moduleId);
+          }
+        }
 
-      if (proceed) {
-        const backupDir = path.join(projectDir, 'v4-backup');
-        await fs.ensureDir(backupDir);
+        if (!sourcePath) {
+          await prompts.log.warn(`Source not found for module ${moduleId}, skipping...`);
+          continue;
+        }
 
-        for (const folder of bmadFolders) {
-          const folderName = path.basename(folder);
-          const backupPath = path.join(backupDir, folderName);
+        const targetPath = path.join(bmadDir, moduleId);
 
-          // If backup already exists, add timestamp
-          let finalBackupPath = backupPath;
-          if (await fs.pathExists(backupPath)) {
-            const timestamp = new Date().toISOString().replaceAll(/[:.]/g, '-').split('T')[0];
-            finalBackupPath = path.join(backupDir, `${folderName}-${timestamp}`);
-          }
+        // Compile agents for this module
+        await moduleManager.compileModuleAgents(sourcePath, targetPath, moduleId, bmadDir, this);
 
-          await fs.move(folder, finalBackupPath, { overwrite: false });
-          console.log(chalk.green(`✓ Moved ${folderName} to ${path.relative(projectDir, finalBackupPath)}`));
+        // Count agents (rough estimate based on files)
+        const agentsPath = path.join(targetPath, 'agents');
+        if (await fs.pathExists(agentsPath)) {
+          const agentFiles = await fs.readdir(agentsPath);
+          const agentCount = agentFiles.filter((f) => f.endsWith('.md')).length;
+          totalAgentCount += agentCount;
         }
-      } else {
-        throw new Error('Installation cancelled by user');
       }
+
+      spinner.stop('Agent recompilation complete!');
+
+      return {
+        success: true,
+        agentCount: totalAgentCount,
+        modules: installedModules,
+      };
+    } catch (error) {
+      spinner.error('Agent recompilation failed');
+      throw error;
+    }
+  }
+
+  /**
+   * Private: Prompt for update action
+   */
+  async promptUpdateAction() {
+    const action = await prompts.select({
+      message: 'What would you like to do?',
+      choices: [{ name: 'Update existing installation', value: 'update' }],
+    });
+    return { action };
+  }
+
+  /**
+   * Handle legacy BMAD v4 detection with simple warning
+   * @param {string} _projectDir - Project directory (unused in simplified version)
+   * @param {Object} _legacyV4 - Legacy V4 detection result (unused in simplified version)
+   */
+  async handleLegacyV4Migration(_projectDir, _legacyV4) {
+    await prompts.note(
+      'Found .bmad-method folder from BMAD v4 installation.\n\n' +
+        'Before continuing with installation, we recommend:\n' +
+        '  1. Remove the .bmad-method folder, OR\n' +
+        '  2. Back it up by renaming it to another name (e.g., bmad-method-backup)\n\n' +
+        'If your v4 installation set up rules or commands, you should remove those as well.',
+      'Legacy BMAD v4 detected',
+    );
+
+    const proceed = await prompts.select({
+      message: 'What would you like to do?',
+      choices: [
+        {
+          name: 'Exit and clean up manually (recommended)',
+          value: 'exit',
+          hint: 'Exit installation',
+        },
+        {
+          name: 'Continue with installation anyway',
+          value: 'continue',
+          hint: 'Continue',
+        },
+      ],
+      default: 'exit',
+    });
+
+    if (proceed === 'exit') {
+      await prompts.log.info('Please remove the .bmad-method folder and any v4 rules/commands, then run the installer again.');
+      // Allow event loop to flush pending I/O before exit
+      setImmediate(() => process.exit(0));
+      return;
     }
+
+    await prompts.log.warn('Proceeding with installation despite legacy v4 folder');
   }
 
   /**
@@ -1901,7 +2760,7 @@ class Installer {
    * @returns {Array} Array of file entries from files-manifest.csv
    */
   async readFilesManifest(bmadDir) {
-    const filesManifestPath = path.join(bmadDir, '_cfg', 'files-manifest.csv');
+    const filesManifestPath = path.join(bmadDir, '_config', 'files-manifest.csv');
     if (!(await fs.pathExists(filesManifestPath))) {
       return [];
     }
@@ -1946,7 +2805,7 @@ class Installer {
 
       return files;
     } catch (error) {
-      console.warn('Warning: Could not read files-manifest.csv:', error.message);
+      await prompts.log.warn('Could not read files-manifest.csv: ' + error.message);
       return [];
     }
   }
@@ -1961,6 +2820,9 @@ class Installer {
     const customFiles = [];
     const modifiedFiles = [];
 
+    // Memory is always in _bmad/_memory
+    const bmadMemoryPath = '_memory';
+
     // Check if the manifest has hashes - if not, we can't detect modifications
     let manifestHasHashes = false;
     if (existingFilesManifest && existingFilesManifest.length > 0) {
@@ -1971,13 +2833,10 @@ class Installer {
     const installedFilesMap = new Map();
     for (const fileEntry of existingFilesManifest) {
       if (fileEntry.path) {
-        // Files in manifest are stored as relative paths starting with 'bmad/'
-        // Convert to absolute path
-        const relativePath = fileEntry.path.startsWith('bmad/') ? fileEntry.path.slice(5) : fileEntry.path;
-        const absolutePath = path.join(bmadDir, relativePath);
+        const absolutePath = path.join(bmadDir, fileEntry.path);
         installedFilesMap.set(path.normalize(absolutePath), {
           hash: fileEntry.hash,
-          relativePath: relativePath,
+          relativePath: fileEntry.path,
         });
       }
     }
@@ -2003,20 +2862,47 @@ class Installer {
             const relativePath = path.relative(bmadDir, fullPath);
             const fileName = path.basename(fullPath);
 
-            // Skip _cfg directory - system files
-            if (relativePath.startsWith('_cfg/') || relativePath.startsWith('_cfg\\')) {
+            // Skip _config directory EXCEPT for modified agent customizations
+            if (relativePath.startsWith('_config/') || relativePath.startsWith('_config\\')) {
+              // Special handling for .customize.yaml files - only preserve if modified
+              if (relativePath.includes('/agents/') && fileName.endsWith('.customize.yaml')) {
+                // Check if the customization file has been modified from manifest
+                const manifestPath = path.join(bmadDir, '_config', 'manifest.yaml');
+                if (await fs.pathExists(manifestPath)) {
+                  const crypto = require('node:crypto');
+                  const currentContent = await fs.readFile(fullPath, 'utf8');
+                  const currentHash = crypto.createHash('sha256').update(currentContent).digest('hex');
+
+                  const yaml = require('yaml');
+                  const manifestContent = await fs.readFile(manifestPath, 'utf8');
+                  const manifestData = yaml.parse(manifestContent);
+                  const originalHash = manifestData.agentCustomizations?.[relativePath];
+
+                  // Only add to customFiles if hash differs (user modified)
+                  if (originalHash && currentHash !== originalHash) {
+                    customFiles.push(fullPath);
+                  }
+                }
+              }
+              continue;
+            }
+
+            if (relativePath.startsWith(bmadMemoryPath + '/') && path.dirname(relativePath).includes('-sidecar')) {
               continue;
             }
 
             // Skip config.yaml files - these are regenerated on each install/update
-            // Users should use _cfg/agents/ override files instead
             if (fileName === 'config.yaml') {
               continue;
             }
 
             if (!fileInfo) {
               // File not in manifest = custom file
-              customFiles.push(fullPath);
+              // EXCEPT: Agent .md files in module folders are generated files, not custom
+              // Only treat .md files under _config/agents/ as custom
+              if (!(fileName.endsWith('.md') && relativePath.includes('/agents/') && !relativePath.startsWith('_config/'))) {
+                customFiles.push(fullPath);
+              }
             } else if (manifestHasHashes && fileInfo.hash) {
               // File in manifest with hash - check if it was modified
               const currentHash = await this.manifest.calculateFileHash(fullPath);
@@ -2028,8 +2914,6 @@ class Installer {
                 });
               }
             }
-            // If manifest doesn't have hashes, we can't detect modifications
-            // so we just skip files that are in the manifest
           }
         }
       } catch {
@@ -2042,206 +2926,236 @@ class Installer {
   }
 
   /**
-   * Private: Create agent configuration files
-   * @param {string} bmadDir - BMAD installation directory
-   * @param {Object} userInfo - User information including name and language
+   * Handle missing custom module sources interactively
+   * @param {Map} customModuleSources - Map of custom module ID to info
+   * @param {string} bmadDir - BMAD directory
+   * @param {string} projectRoot - Project root directory
+   * @param {string} operation - Current operation ('update', 'compile', etc.)
+   * @param {Array} installedModules - Array of installed module IDs (will be modified)
+   * @param {boolean} [skipPrompts=false] - Skip interactive prompts and keep all modules with missing sources
+   * @returns {Object} Object with validCustomModules array and keptModulesWithoutSources array
    */
-  async createAgentConfigs(bmadDir, userInfo = null) {
-    const agentConfigDir = path.join(bmadDir, '_cfg', 'agents');
-    await fs.ensureDir(agentConfigDir);
-
-    // Get all agents from all modules
-    const agents = [];
-    const agentDetails = []; // For manifest generation
-
-    // Check modules for agents (including core)
-    const entries = await fs.readdir(bmadDir, { withFileTypes: true });
-    for (const entry of entries) {
-      if (entry.isDirectory() && entry.name !== '_cfg') {
-        const moduleAgentsPath = path.join(bmadDir, entry.name, 'agents');
-        if (await fs.pathExists(moduleAgentsPath)) {
-          const agentFiles = await fs.readdir(moduleAgentsPath);
-          for (const agentFile of agentFiles) {
-            if (agentFile.endsWith('.md')) {
-              const agentPath = path.join(moduleAgentsPath, agentFile);
-              const agentContent = await fs.readFile(agentPath, 'utf8');
-
-              // Skip agents with localskip="true"
-              const hasLocalSkip = agentContent.match(/<agent[^>]*\slocalskip="true"[^>]*>/);
-              if (hasLocalSkip) {
-                continue; // Skip this agent - it should not have been installed
-              }
-
-              const agentName = path.basename(agentFile, '.md');
-
-              // Extract any nodes with agentConfig="true"
-              const agentConfigNodes = this.extractAgentConfigNodes(agentContent);
-
-              agents.push({
-                name: agentName,
-                module: entry.name,
-                agentConfigNodes: agentConfigNodes,
-              });
-
-              // Use shared AgentPartyGenerator to extract details
-              let details = AgentPartyGenerator.extractAgentDetails(agentContent, entry.name, agentName);
-
-              // Apply config overrides if they exist
-              if (details) {
-                const configPath = path.join(agentConfigDir, `${entry.name}-${agentName}.md`);
-                if (await fs.pathExists(configPath)) {
-                  const configContent = await fs.readFile(configPath, 'utf8');
-                  details = AgentPartyGenerator.applyConfigOverrides(details, configContent);
-                }
-                agentDetails.push(details);
-              }
-            }
-          }
+  async handleMissingCustomSources(customModuleSources, bmadDir, projectRoot, operation, installedModules, skipPrompts = false) {
+    const validCustomModules = [];
+    const keptModulesWithoutSources = []; // Track modules kept without sources
+    const customModulesWithMissingSources = [];
+
+    // Check which sources exist
+    for (const [moduleId, customInfo] of customModuleSources) {
+      if (await fs.pathExists(customInfo.sourcePath)) {
+        validCustomModules.push({
+          id: moduleId,
+          name: customInfo.name,
+          path: customInfo.sourcePath,
+          info: customInfo,
+        });
+      } else {
+        // For cached modules that are missing, we just skip them without prompting
+        if (customInfo.cached) {
+          // Skip cached modules without prompting
+          keptModulesWithoutSources.push({
+            id: moduleId,
+            name: customInfo.name,
+            cached: true,
+          });
+        } else {
+          customModulesWithMissingSources.push({
+            id: moduleId,
+            name: customInfo.name,
+            sourcePath: customInfo.sourcePath,
+            relativePath: customInfo.relativePath,
+            info: customInfo,
+          });
         }
       }
     }
 
-    // Create config file for each agent
-    let createdCount = 0;
-    let skippedCount = 0;
-
-    // Load agent config template
-    const templatePath = getSourcePath('utility', 'models', 'agent-config-template.md');
-    const templateContent = await fs.readFile(templatePath, 'utf8');
-
-    for (const agent of agents) {
-      const configPath = path.join(agentConfigDir, `${agent.module}-${agent.name}.md`);
+    // If no missing sources, return immediately
+    if (customModulesWithMissingSources.length === 0) {
+      return {
+        validCustomModules,
+        keptModulesWithoutSources: [],
+      };
+    }
 
-      // Skip if config file already exists (preserve custom configurations)
-      if (await fs.pathExists(configPath)) {
-        skippedCount++;
-        continue;
+    // Non-interactive mode: keep all modules with missing sources
+    if (skipPrompts) {
+      for (const missing of customModulesWithMissingSources) {
+        keptModulesWithoutSources.push(missing.id);
       }
+      return { validCustomModules, keptModulesWithoutSources };
+    }
 
-      // Build config content header
-      let configContent = `# Agent Config: ${agent.name}\n\n`;
+    await prompts.log.warn(`Found ${customModulesWithMissingSources.length} custom module(s) with missing sources:`);
 
-      // Process template and add agent-specific config nodes
-      let processedTemplate = templateContent;
+    let keptCount = 0;
+    let updatedCount = 0;
+    let removedCount = 0;
 
-      // Replace {core:user_name} placeholder with actual user name if available
-      if (userInfo && userInfo.userName) {
-        processedTemplate = processedTemplate.replaceAll('{core:user_name}', userInfo.userName);
-      }
+    for (const missing of customModulesWithMissingSources) {
+      await prompts.log.message(
+        `${missing.name} (${missing.id})\n  Original source: ${missing.relativePath}\n  Full path: ${missing.sourcePath}`,
+      );
 
-      // Replace {core:communication_language} placeholder with actual language if available
-      if (userInfo && userInfo.responseLanguage) {
-        processedTemplate = processedTemplate.replaceAll('{core:communication_language}', userInfo.responseLanguage);
+      const choices = [
+        {
+          name: 'Keep installed (will not be processed)',
+          value: 'keep',
+          hint: 'Keep',
+        },
+        {
+          name: 'Specify new source location',
+          value: 'update',
+          hint: 'Update',
+        },
+      ];
+
+      // Only add remove option if not just compiling agents
+      if (operation !== 'compile-agents') {
+        choices.push({
+          name: '⚠️  REMOVE module completely (destructive!)',
+          value: 'remove',
+          hint: 'Remove',
+        });
       }
 
-      // If this agent has agentConfig nodes, add them after the existing comment
-      if (agent.agentConfigNodes && agent.agentConfigNodes.length > 0) {
-        // Find the agent-specific configuration nodes comment
-        const commentPattern = /(\s*<!-- Agent-specific configuration nodes -->)/;
-        const commentMatch = processedTemplate.match(commentPattern);
+      const action = await prompts.select({
+        message: `How would you like to handle "${missing.name}"?`,
+        choices,
+      });
+
+      switch (action) {
+        case 'update': {
+          // Use sync validation because @clack/prompts doesn't support async validate
+          const newSourcePath = await prompts.text({
+            message: 'Enter the new path to the custom module:',
+            default: missing.sourcePath,
+            validate: (input) => {
+              if (!input || input.trim() === '') {
+                return 'Please enter a path';
+              }
+              const expandedPath = path.resolve(input.trim());
+              if (!fs.pathExistsSync(expandedPath)) {
+                return 'Path does not exist';
+              }
+              // Check if it looks like a valid module
+              const moduleYamlPath = path.join(expandedPath, 'module.yaml');
+              const agentsPath = path.join(expandedPath, 'agents');
+              const workflowsPath = path.join(expandedPath, 'workflows');
+
+              if (!fs.pathExistsSync(moduleYamlPath) && !fs.pathExistsSync(agentsPath) && !fs.pathExistsSync(workflowsPath)) {
+                return 'Path does not appear to contain a valid custom module';
+              }
+              return; // clack expects undefined for valid input
+            },
+          });
 
-        if (commentMatch) {
-          // Add nodes right after the comment
-          let agentSpecificNodes = '';
-          for (const node of agent.agentConfigNodes) {
-            agentSpecificNodes += `\n    ${node}`;
+          // Defensive: handleCancel should have exited, but guard against symbol propagation
+          if (typeof newSourcePath !== 'string') {
+            keptCount++;
+            keptModulesWithoutSources.push(missing.id);
+            continue;
           }
 
-          processedTemplate = processedTemplate.replace(commentPattern, `$1${agentSpecificNodes}`);
-        }
-      }
+          // Update the source in manifest
+          const resolvedPath = path.resolve(newSourcePath.trim());
+          missing.info.sourcePath = resolvedPath;
+          // Remove relativePath - we only store absolute sourcePath now
+          delete missing.info.relativePath;
+          await this.manifest.addCustomModule(bmadDir, missing.info);
+
+          validCustomModules.push({
+            id: missing.id,
+            name: missing.name,
+            path: resolvedPath,
+            info: missing.info,
+          });
 
-      configContent += processedTemplate;
+          updatedCount++;
+          await prompts.log.success('Updated source location');
 
-      // Ensure POSIX-compliant final newline
-      if (!configContent.endsWith('\n')) {
-        configContent += '\n';
-      }
+          break;
+        }
+        case 'remove': {
+          // Extra confirmation for destructive remove
+          await prompts.log.error(
+            `WARNING: This will PERMANENTLY DELETE "${missing.name}" and all its files!\n  Module location: ${path.join(bmadDir, missing.id)}`,
+          );
+
+          const confirmDelete = await prompts.confirm({
+            message: 'Are you absolutely sure you want to delete this module?',
+            default: false,
+          });
 
-      await fs.writeFile(configPath, configContent, 'utf8');
-      this.installedFiles.push(configPath); // Track agent config files
-      createdCount++;
-    }
+          if (confirmDelete) {
+            const typedConfirm = await prompts.text({
+              message: 'Type "DELETE" to confirm permanent deletion:',
+              validate: (input) => {
+                if (input !== 'DELETE') {
+                  return 'You must type "DELETE" exactly to proceed';
+                }
+                return; // clack expects undefined for valid input
+              },
+            });
 
-    // Generate agent manifest with overrides applied
-    await this.generateAgentManifest(bmadDir, agentDetails);
+            if (typedConfirm === 'DELETE') {
+              // Remove the module from filesystem and manifest
+              const modulePath = path.join(bmadDir, missing.id);
+              if (await fs.pathExists(modulePath)) {
+                const fsExtra = require('fs-extra');
+                await fsExtra.remove(modulePath);
+                await prompts.log.warn(`Deleted module directory: ${path.relative(projectRoot, modulePath)}`);
+              }
 
-    return { total: agents.length, created: createdCount, skipped: skippedCount };
-  }
+              await this.manifest.removeModule(bmadDir, missing.id);
+              await this.manifest.removeCustomModule(bmadDir, missing.id);
+              await prompts.log.warn('Removed from manifest');
 
-  /**
-   * Generate agent manifest XML file
-   * @param {string} bmadDir - BMAD installation directory
-   * @param {Array} agentDetails - Array of agent details
-   */
-  async generateAgentManifest(bmadDir, agentDetails) {
-    const manifestPath = path.join(bmadDir, '_cfg', 'agent-manifest.csv');
-    await AgentPartyGenerator.writeAgentParty(manifestPath, agentDetails, { forWeb: false });
-  }
+              // Also remove from installedModules list
+              if (installedModules && installedModules.includes(missing.id)) {
+                const index = installedModules.indexOf(missing.id);
+                if (index !== -1) {
+                  installedModules.splice(index, 1);
+                }
+              }
 
-  /**
-   * Extract nodes with agentConfig="true" from agent content
-   * @param {string} content - Agent file content
-   * @returns {Array} Array of XML nodes that should be added to agent config
-   */
-  extractAgentConfigNodes(content) {
-    const nodes = [];
+              removedCount++;
+              await prompts.log.error(`"${missing.name}" has been permanently removed`);
+            } else {
+              await prompts.log.message('Removal cancelled - module will be kept');
+              keptCount++;
+            }
+          } else {
+            await prompts.log.message('Removal cancelled - module will be kept');
+            keptCount++;
+          }
 
-    try {
-      // Find all XML nodes with agentConfig="true"
-      // Match self-closing tags and tags with content
-      const selfClosingPattern = /<([a-zA-Z][a-zA-Z0-9_-]*)\s+[^>]*agentConfig="true"[^>]*\/>/g;
-      const withContentPattern = /<([a-zA-Z][a-zA-Z0-9_-]*)\s+[^>]*agentConfig="true"[^>]*>([\s\S]*?)<\/\1>/g;
-
-      // Extract self-closing tags
-      let match;
-      while ((match = selfClosingPattern.exec(content)) !== null) {
-        // Extract just the tag without children (structure only)
-        const tagMatch = match[0].match(/<([a-zA-Z][a-zA-Z0-9_-]*)([^>]*)\/>/);
-        if (tagMatch) {
-          const tagName = tagMatch[1];
-          const attributes = tagMatch[2].replace(/\s*agentConfig="true"/, ''); // Remove agentConfig attribute
-          nodes.push(`<${tagName}${attributes}></${tagName}>`);
+          break;
         }
-      }
-
-      // Extract tags with content
-      while ((match = withContentPattern.exec(content)) !== null) {
-        const fullMatch = match[0];
-        const tagName = match[1];
+        case 'keep': {
+          keptCount++;
+          keptModulesWithoutSources.push(missing.id);
+          await prompts.log.message('Module will be kept as-is');
 
-        // Extract opening tag with attributes (removing agentConfig="true")
-        const openingTagMatch = fullMatch.match(new RegExp(`<${tagName}([^>]*)>`));
-        if (openingTagMatch) {
-          const attributes = openingTagMatch[1].replace(/\s*agentConfig="true"/, '');
-          // Add empty node structure (no children)
-          nodes.push(`<${tagName}${attributes}></${tagName}>`);
+          break;
         }
+        // No default
       }
-    } catch (error) {
-      console.error('Error extracting agentConfig nodes:', error);
     }
 
-    return nodes;
-  }
-
-  /**
-   * Copy IDE-specific documentation to BMAD docs
-   * @param {Array} ides - List of selected IDEs
-   * @param {string} bmadDir - BMAD installation directory
-   */
-  async copyIdeDocumentation(ides, bmadDir) {
-    const docsDir = path.join(bmadDir, 'docs');
-    await fs.ensureDir(docsDir);
-
-    for (const ide of ides) {
-      const sourceDocPath = path.join(getProjectRoot(), 'docs', 'ide-info', `${ide}.md`);
-      const targetDocPath = path.join(docsDir, `${ide}-instructions.md`);
-
-      if (await fs.pathExists(sourceDocPath)) {
-        await this.copyFileWithPlaceholderReplacement(sourceDocPath, targetDocPath, this.bmadFolderName || 'bmad');
-      }
+    // Show summary
+    if (keptCount > 0 || updatedCount > 0 || removedCount > 0) {
+      let summary = 'Summary for custom modules with missing sources:';
+      if (keptCount > 0) summary += `\n  • ${keptCount} module(s) kept as-is`;
+      if (updatedCount > 0) summary += `\n  • ${updatedCount} module(s) updated with new sources`;
+      if (removedCount > 0) summary += `\n  • ${removedCount} module(s) permanently deleted`;
+      await prompts.log.message(summary);
     }
+
+    return {
+      validCustomModules,
+      keptModulesWithoutSources,
+    };
   }
 }