bmad-method 6.9.1-next.13 → 6.9.1-next.15

package/bmad-modules.yaml

@@ -7,6 +7,25 @@
 # default_channel (optional) — the install channel when the user does not
 # override with --channel/--pin/--next. Valid values: stable | next.
 # Omit to inherit the installer's hardcoded default (stable).
+#
+# deprecated (optional, default false) — when true, the module is hidden from
+# the installer picker UNLESS it is already installed (so existing users can
+# still see/manage it, but new users are not offered it).
+# deprecation-message (optional) — surfaced in the picker hint for a deprecated
+# module that is still installed; use it to point users to the replacement.
+#
+# marketplace-plugin (optional, default false) — when true, the module's
+# installable skills are resolved from its .claude-plugin/marketplace.json via
+# the plugin resolver (instead of copying the single module-definition dir).
+# Use this for modules whose module.yaml does not sit alongside the skill
+# folders. module-definition should still point at the real module.yaml so
+# config/version lookups work.
+#
+# post-install-message (optional) — an "action needed" notice shown to the user
+# after install completes, once for each install run that includes the module.
+# Interactive installs require the user to acknowledge it (press Enter);
+# non-interactive (--yes) installs print it and continue. Use for required
+# follow-up steps (e.g. "run the X setup skill").
 
 modules:
   bmad-method-test-architecture-enterprise:
@@ -41,6 +60,29 @@ modules:
     type: experimental
     npmPackage: bmad-story-automator
     default_channel: next
+    deprecated: true
+    deprecation-message: "BMad Automator has been deprecated and is replaced by BMad Auto (bmad-auto). Install BMad Auto instead."
+
+  bmad-auto:
+    url: https://github.com/bmad-code-org/bmad-auto
+    module-definition: src/automator/data/skills/bmad-auto-setup/assets/module.yaml
+    code: bauto
+    name: "BMad Auto"
+    description: "Automation-mode skills driven by the bmad-auto orchestrator: unattended dev, adversarial review, and deferred-work sweep triage"
+    defaultSelected: false
+    type: bmad-org
+    default_channel: stable
+    # Skills live outside a single module.yaml dir; resolve them from
+    # .claude-plugin/marketplace.json via the plugin resolver (see external-manager).
+    marketplace-plugin: true
+    post-install-message: |
+      BMad Auto installed. To finish setup, run the bmad-auto-setup skill
+      from your agent:
+
+        > use the bmad-auto-setup skill
+
+      It installs the bmad-auto orchestrator tool and wires up the per-project
+      hooks and policy. The automation skills don't run until setup completes.
 
   bmad-creative-intelligence-suite:
     url: https://github.com/bmad-code-org/bmad-module-creative-intelligence-suite

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "bmad-method",
-  "version": "6.9.1-next.13",
+  "version": "6.9.1-next.15",
   "description": "Breakthrough Method of Agile AI-driven Development",
   "keywords": [
     "agile",

package/src/bmm-skills/4-implementation/bmad-code-review/steps/step-02-review.md

@@ -7,23 +7,29 @@ failed_layers: '' # set at runtime: comma-separated list of layers that failed o
 ## RULES
 
 - YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}`
-- The Blind Hunter subagent receives NO project context — diff only.
-- The Edge Case Hunter subagent receives diff and project read access.
-- The Acceptance Auditor subagent receives diff, spec, and context docs.
 - All review subagents must run at the same model capability as the current session.
 
 ## INSTRUCTIONS
 
 1. If `{review_mode}` = `"no-spec"`, note to the user: "Acceptance Auditor skipped — no spec file provided."
 
-2. Launch parallel subagents without conversation context. If subagents are not available, generate prompt files in `{implementation_artifacts}` — one per reviewer role below — and HALT. Ask the user to run each in a separate session (ideally a different LLM) and paste back the findings. When findings are pasted, resume from this point and proceed to step 3.
+2. Launch Blind Hunter and Edge Case Hunter in parallel without prior conversation context. If `{review_mode}` = `"full"`, include the Acceptance Auditor in the same parallel launch. If subagents are not available, generate prompt files in `{implementation_artifacts}` for each applicable reviewer role and HALT. Ask the user to run each in a separate session (ideally a different LLM) and paste back the findings. When findings are pasted, resume from this point and proceed to step 3.
 
-   - **Blind Hunter** — prompt: "Use the `bmad-review-adversarial-general` skill on `{diff_output}`."
+   - **Blind Hunter** — prompt:
+     > Invoke the `bmad-review-adversarial-general` skill on this diff:
+     >
+     > {diff_output}
 
-   - **Edge Case Hunter** — prompt: "Use the `bmad-review-edge-case-hunter` skill on `{diff_output}`."
+   - **Edge Case Hunter** — prompt:
+     > Invoke the `bmad-review-edge-case-hunter` skill on this diff:
+     >
+     > {diff_output}
 
-   - **Acceptance Auditor** (only if `{review_mode}` = `"full"`) — receives `{diff_output}`, the content of the file at `{spec_file}`, and any loaded context docs. Its prompt:
-     > You are an Acceptance Auditor. Review this diff against the spec and context docs. Check for: violations of acceptance criteria, deviations from spec intent, missing implementation of specified behavior, contradictions between spec constraints and actual code. Output findings as a Markdown list. Each finding: one-line title, which AC/constraint it violates, and evidence from the diff.
+   - **Acceptance Auditor** (only if `{review_mode}` = `"full"`) — prompt:
+     > You are an Acceptance Auditor. Review the provided diff against `{spec_file}` and any loaded context docs. Check for: violations of acceptance criteria, deviations from spec intent, missing implementation of specified behavior, contradictions between spec constraints and actual code. Output findings as a Markdown list. Each finding: one-line title, which AC/constraint it violates, and evidence from the diff.
+     >
+     > Diff:
+     > {diff_output}
 
 3. **Subagent failure handling**: If any subagent fails, times out, or returns empty results, append the layer name to `{failed_layers}` (comma-separated) and proceed with findings from the remaining layers.
 

package/src/bmm-skills/4-implementation/bmad-dev-auto/step-04-review.md

@@ -8,7 +8,6 @@ deferred_work_file: '{implementation_artifacts}/deferred-work.md'
 
 - YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}`
 - No human interaction: do not ask questions or wait for approval in this step.
-- Review subagents get no prior session context.
 - All review subagents must run at the same model capability as the current session.
 
 ## INSTRUCTIONS
@@ -23,10 +22,16 @@ Do NOT `git add` anything — this is read-only inspection.
 
 ### Review
 
-Launch two subagents without prior session context.
+Launch Blind Hunter and Edge Case Hunter in parallel without prior conversation context.
 
-- **Blind hunter** — prompt: "Use the `bmad-review-adversarial-general` skill on `{diff_output}`."
-- **Edge case hunter** — prompt: "Use the `bmad-review-edge-case-hunter` skill on `{diff_output}`."
+- **Blind Hunter** — prompt:
+  > Invoke the `bmad-review-adversarial-general` skill on this diff:
+  >
+  > {diff_output}
+- **Edge Case Hunter** — prompt:
+  > Invoke the `bmad-review-edge-case-hunter` skill on this diff:
+  >
+  > {diff_output}
 
 ### Classify
 

package/src/bmm-skills/4-implementation/bmad-quick-dev/step-04-review.md

@@ -7,7 +7,6 @@ deferred_work_file: '{implementation_artifacts}/deferred-work.md'
 ## RULES
 
 - YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}`
-- Review subagents get NO conversation context.
 - All review subagents must run at the same model capability as the current session.
 
 ## INSTRUCTIONS
@@ -22,10 +21,16 @@ Do NOT `git add` anything — this is read-only inspection.
 
 ### Review
 
-Launch two subagents without conversation context. If no subagents are available, generate two review prompt files in `{implementation_artifacts}` — one per reviewer role below — and HALT. Ask the human to run each in a separate session (ideally a different LLM) and paste back the findings.
+Launch Blind Hunter and Edge Case Hunter in parallel without prior conversation context. If no subagents are available, generate two review prompt files in `{implementation_artifacts}` — one per reviewer role below — and HALT. Ask the human to run each in a separate session (ideally a different LLM) and paste back the findings.
 
-- **Blind hunter** — prompt: "Use the `bmad-review-adversarial-general` skill on `{diff_output}`."
-- **Edge case hunter** — prompt: "Use the `bmad-review-edge-case-hunter` skill on `{diff_output}`."
+- **Blind Hunter** — prompt:
+  > Invoke the `bmad-review-adversarial-general` skill on this diff:
+  >
+  > {diff_output}
+- **Edge Case Hunter** — prompt:
+  > Invoke the `bmad-review-edge-case-hunter` skill on this diff:
+  >
+  > {diff_output}
 
 ### Classify
 

package/src/bmm-skills/4-implementation/bmad-quick-dev/step-oneshot.md

@@ -8,6 +8,7 @@ deferred_work_file: '{implementation_artifacts}/deferred-work.md'
 
 - YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}`
 - NEVER auto-push.
+- All review subagents must run at the same model capability as the current session.
 
 ## INSTRUCTIONS
 
@@ -19,7 +20,9 @@ Implement the clarified intent directly.
 
 ### Review
 
-Invoke the `bmad-review-adversarial-general` skill in a subagent with the changed files. The subagent gets NO conversation context — to avoid anchoring bias. Launch at the same model capability as the current session. If no subagents are available, write the changed files to a review prompt file in `{implementation_artifacts}` and HALT. Ask the human to run the review in a separate session and paste back the findings.
+Launch Blind Hunter without prior conversation context. If no subagents are available, generate one review prompt file in `{implementation_artifacts}` and HALT. Ask the human to run it in a separate session and paste back the findings.
+
+- **Blind Hunter** — prompt: "Invoke the `bmad-review-adversarial-general` skill on the changed files."
 
 ### Classify
 

package/tools/installer/core/installer.js

@@ -102,6 +102,11 @@ class Installer {
 
       const restoreResult = await this._restoreUserFiles(paths, updateState);
 
+      // Surface any "action needed" post-install messages for installed modules
+      // (e.g. run a setup skill) and let the user acknowledge them before the
+      // final summary, so "BMAD is ready to use!" stays the last thing shown.
+      await this._displayPostInstallMessages(config, officialModules);
+
       // Render consolidated summary
       await this.renderInstallSummary(results, {
         bmadDir: paths.bmadDir,
@@ -1246,6 +1251,56 @@ class Installer {
     });
   }
 
+  /**
+   * Display registry-defined post-install messages for the modules installed in
+   * this run. These are "action needed" notices (e.g. "run the bmad-auto-setup
+   * skill") that the user must see to finish setup. They are defined via the
+   * `post-install-message` property on a module's bmad-modules.yaml entry.
+   *
+   * Interactive installs require the user to acknowledge each message (press
+   * Enter); non-interactive (--yes / skipPrompts) installs print the message
+   * and continue without blocking, so CI/scripted installs don't hang.
+   *
+   * @param {Object} config - Install config (config.modules, config.skipPrompts)
+   * @param {Object} officialModules - OfficialModules instance (carries the registry)
+   */
+  async _displayPostInstallMessages(config, officialModules) {
+    const moduleCodes = config.modules || [];
+    if (moduleCodes.length === 0) return;
+
+    const externalManager = officialModules.externalModuleManager;
+    if (!externalManager) return;
+
+    const color = await prompts.getColor();
+
+    for (const code of moduleCodes) {
+      let moduleInfo;
+      try {
+        moduleInfo = await externalManager.getModuleByCode(code);
+      } catch {
+        continue; // Built-in modules (core/bmm) aren't in the registry — skip.
+      }
+
+      const message = moduleInfo && moduleInfo.postInstallMessage;
+      if (!message) continue;
+
+      await prompts.box(String(message).trim(), `⚑ Action needed — ${moduleInfo.name || code}`, {
+        rounded: true,
+        formatBorder: color.yellow,
+      });
+
+      // Interactive: require the user to acknowledge before continuing. Skip the
+      // blocking prompt in non-interactive installs (the message is still shown).
+      if (!config.skipPrompts) {
+        await prompts.text({
+          message: 'Press Enter to acknowledge',
+          placeholder: '',
+          default: '',
+        });
+      }
+    }
+  }
+
   /**
    * Quick update method - preserves all settings and only prompts for new config fields
    * @param {Object} config - Configuration with directory

package/tools/installer/modules/external-manager.js

@@ -62,6 +62,13 @@ class ExternalModuleManager {
   // ExternalModuleManager) sees resolutions made during install.
   static _resolutions = new Map();
 
+  // moduleCode → ResolvedModule (from PluginResolver). Populated for registry
+  // modules flagged `marketplace-plugin: true`, whose installable skills live
+  // outside a single module.yaml directory and must be resolved from
+  // .claude-plugin/marketplace.json. Shared across instances so install() can
+  // pick up the resolution computed during findExternalModuleSource.
+  static _pluginResolutions = new Map();
+
   constructor() {}
 
   /**
@@ -73,6 +80,15 @@ class ExternalModuleManager {
     return ExternalModuleManager._resolutions.get(moduleCode) || null;
   }
 
+  /**
+   * Get the cached marketplace-plugin resolution for a module (if any).
+   * @param {string} moduleCode
+   * @returns {Object|null} ResolvedModule from PluginResolver, or null
+   */
+  getPluginResolution(moduleCode) {
+    return ExternalModuleManager._pluginResolutions.get(moduleCode) || null;
+  }
+
   /**
    * Load the official modules registry from the bundled YAML file.
    * @returns {Object} Parsed YAML content with modules array
@@ -113,6 +129,10 @@ class ExternalModuleManager {
       npmPackage: mod.npm_package || mod.npmPackage || null,
       pluginName: mod.plugin_name || mod.pluginName || null,
       defaultChannel: normalizeChannelName(mod.default_channel || mod.defaultChannel) || 'stable',
+      deprecated: mod.deprecated === true,
+      deprecationMessage: mod.deprecation_message || mod['deprecation-message'] || mod.deprecationMessage || null,
+      marketplacePlugin: mod.marketplace_plugin === true || mod['marketplace-plugin'] === true || mod.marketplacePlugin === true,
+      postInstallMessage: mod.post_install_message || mod['post-install-message'] || mod.postInstallMessage || null,
       builtIn: mod.built_in === true,
       isExternal: mod.built_in !== true,
     };
@@ -468,6 +488,19 @@ class ExternalModuleManager {
       return null;
     }
 
+    // Marketplace-plugin modules (registry entries flagged `marketplace-plugin`)
+    // ship a .claude-plugin/marketplace.json and keep their module.yaml inside a
+    // skill's assets/ rather than in one directory alongside the skills. Resolve
+    // them through the PluginResolver (the same machinery custom-URL installs
+    // use) and return the directory that holds module.yaml so config/version/
+    // directory callers work; install() copies the resolved skill dirs.
+    if (moduleInfo.marketplacePlugin) {
+      const pluginMod = await this.resolvePluginModule(moduleCode, options);
+      if (pluginMod && pluginMod.moduleYamlPath) {
+        return path.dirname(pluginMod.moduleYamlPath);
+      }
+    }
+
     // Clone the external module repo
     const cloneDir = await this.cloneExternalModule(moduleCode, options);
 
@@ -521,6 +554,84 @@ class ExternalModuleManager {
         `The repository may have been restructured after this release was tagged.${channelHint}`,
     );
   }
+
+  /**
+   * Resolve a marketplace-plugin registry module to an installable plugin
+   * definition. Clones the repo (respecting the channel plan), reads its
+   * .claude-plugin/marketplace.json, and runs the PluginResolver against the
+   * plugin matching this module. The result (skillPaths + module.yaml +
+   * module-help.csv) is cached so install() can copy the resolved skill dirs.
+   *
+   * @param {string} moduleCode - Code of the external module
+   * @param {Object} options - Options passed to cloneExternalModule
+   * @returns {Promise<Object|null>} ResolvedModule from PluginResolver, or null
+   *   when the module is not a marketplace plugin or cannot be resolved.
+   */
+  async resolvePluginModule(moduleCode, options = {}) {
+    const moduleInfo = await this.getModuleByCode(moduleCode);
+    if (!moduleInfo || moduleInfo.builtIn || !moduleInfo.marketplacePlugin) {
+      return null;
+    }
+
+    const cloneDir = await this.cloneExternalModule(moduleCode, options);
+
+    const marketplacePath = path.join(cloneDir, '.claude-plugin', 'marketplace.json');
+    if (!(await fs.pathExists(marketplacePath))) {
+      return null;
+    }
+
+    let marketplace;
+    try {
+      marketplace = JSON.parse(await fs.readFile(marketplacePath, 'utf8'));
+    } catch {
+      return null;
+    }
+
+    const plugins = Array.isArray(marketplace.plugins) ? marketplace.plugins : [];
+    if (plugins.length === 0) {
+      return null;
+    }
+
+    // Prefer the plugin whose name matches the registry's plugin_name (or code),
+    // falling back to any plugin that declares skills.
+    const preferredName = moduleInfo.pluginName || moduleInfo.code;
+    const ordered = [...plugins].sort((a, b) => {
+      const am = a?.name === preferredName ? 0 : 1;
+      const bm = b?.name === preferredName ? 0 : 1;
+      return am - bm;
+    });
+
+    const { PluginResolver } = require('./plugin-resolver');
+    const resolver = new PluginResolver();
+
+    for (const plugin of ordered) {
+      if (!plugin || !Array.isArray(plugin.skills) || plugin.skills.length === 0) {
+        continue;
+      }
+      let resolvedMods;
+      try {
+        resolvedMods = await resolver.resolve(cloneDir, plugin);
+      } catch {
+        continue;
+      }
+      if (!resolvedMods || resolvedMods.length === 0) {
+        continue;
+      }
+      // Match the registry code, then the preferred plugin name, then accept a
+      // lone resolved module.
+      const match =
+        resolvedMods.find((mod) => mod.code === moduleCode) ||
+        resolvedMods.find((mod) => mod.code === preferredName) ||
+        (resolvedMods.length === 1 ? resolvedMods[0] : null);
+      if (match) {
+        match.repoUrl = moduleInfo.url;
+        ExternalModuleManager._pluginResolutions.set(moduleCode, match);
+        return match;
+      }
+    }
+
+    return null;
+  }
   cachedModules = null;
 }
 

package/tools/installer/modules/official-modules.js

@@ -277,7 +277,29 @@ class OfficialModules {
       await fs.remove(targetPath);
     }
 
-    await this.copyModuleWithFiltering(sourcePath, targetPath, fileTrackingCallback, options.moduleConfig);
+    // Marketplace-plugin registry modules keep their installable skills outside
+    // the directory that holds module.yaml (sourcePath points at the -setup
+    // skill's assets/), so they cannot be installed by copying sourcePath. Copy
+    // the resolved skill directories instead, matching how custom marketplace
+    // installs lay out a module. Everything else (manifest, version info) flows
+    // through the standard external-module path below.
+    const moduleInfo = await this.externalModuleManager.getModuleByCode(moduleName);
+    if (moduleInfo && moduleInfo.marketplacePlugin) {
+      const pluginResolution = this.externalModuleManager.getPluginResolution(moduleName);
+      // Fail loud: copying sourcePath here would install only the -setup skill's
+      // assets/ (module.yaml + module-help.csv) and none of the skills — a
+      // silent, broken partial install. Abort instead.
+      if (!pluginResolution || !Array.isArray(pluginResolution.skillPaths) || pluginResolution.skillPaths.length === 0) {
+        throw new Error(
+          `Module '${moduleName}' is registered as a marketplace plugin but its skills could not be resolved ` +
+            `from .claude-plugin/marketplace.json (missing or malformed on the selected channel). ` +
+            `Aborting to avoid a partial install with no skills.`,
+        );
+      }
+      await this._copyResolvedSkills(pluginResolution, targetPath, fileTrackingCallback, options.moduleConfig);
+    } else {
+      await this.copyModuleWithFiltering(sourcePath, targetPath, fileTrackingCallback, options.moduleConfig);
+    }
 
     if (!options.skipModuleInstaller) {
       await this.createModuleDirectories(moduleName, bmadDir, options);
@@ -304,41 +326,66 @@ class OfficialModules {
   }
 
   /**
-   * Install a module from a PluginResolver resolution result.
-   * Copies specific skill directories and places module-help.csv at the target root.
+   * Lay out a PluginResolver resolution on disk: copy each resolved skill
+   * directory (flattened by leaf name) into targetPath and place module-help.csv
+   * at the module root. Shared by both custom marketplace installs
+   * (installFromResolution) and official marketplace-plugin registry installs
+   * (install), so the two paths cannot drift.
    * @param {Object} resolved - ResolvedModule from PluginResolver
-   * @param {string} bmadDir - Target bmad directory
+   * @param {string} targetPath - Destination module directory (e.g. bmadDir/<code>)
    * @param {Function} fileTrackingCallback - Optional callback to track installed files
-   * @param {Object} options - Installation options
+   * @param {Object} moduleConfig - Module configuration passed to copy filtering
    */
-  async installFromResolution(resolved, bmadDir, fileTrackingCallback = null, options = {}) {
-    const targetPath = path.join(bmadDir, resolved.code);
-
-    if (await fs.pathExists(targetPath)) {
-      await fs.remove(targetPath);
-    }
-
+  async _copyResolvedSkills(resolved, targetPath, fileTrackingCallback = null, moduleConfig = {}) {
     await fs.ensureDir(targetPath);
 
-    // Copy each skill directory, flattened by leaf name
+    // Copy each skill directory, flattened by leaf name. Leaf names must be
+    // unique — two skills that flatten to the same directory would silently
+    // overwrite each other, so fail loud instead.
+    const seenLeaves = new Map();
     for (const skillPath of resolved.skillPaths) {
       const skillDirName = path.basename(skillPath);
+      if (seenLeaves.has(skillDirName)) {
+        throw new Error(
+          `Cannot install module '${resolved.code}': skill directories '${seenLeaves.get(skillDirName)}' and ` +
+            `'${skillPath}' share the leaf name '${skillDirName}' and would overwrite each other. ` +
+            `Skill directory names must be unique.`,
+        );
+      }
+      seenLeaves.set(skillDirName, skillPath);
       const skillTarget = path.join(targetPath, skillDirName);
-      await this.copyModuleWithFiltering(skillPath, skillTarget, fileTrackingCallback, options.moduleConfig);
+      await this.copyModuleWithFiltering(skillPath, skillTarget, fileTrackingCallback, moduleConfig);
     }
 
-    // Place module-help.csv at the module root
+    // Place module-help.csv at the module root.
+    const helpTarget = path.join(targetPath, 'module-help.csv');
     if (resolved.moduleHelpCsvPath) {
-      // Strategies 1-4: copy the existing file
-      const helpTarget = path.join(targetPath, 'module-help.csv');
+      // Strategies 1-4: copy the existing file.
       await fs.copy(resolved.moduleHelpCsvPath, helpTarget, { overwrite: true });
       if (fileTrackingCallback) fileTrackingCallback(helpTarget);
     } else if (resolved.synthesizedHelpCsv) {
-      // Strategy 5: write synthesized content
-      const helpTarget = path.join(targetPath, 'module-help.csv');
+      // Strategy 5: write synthesized content.
       await fs.writeFile(helpTarget, resolved.synthesizedHelpCsv, 'utf8');
       if (fileTrackingCallback) fileTrackingCallback(helpTarget);
     }
+  }
+
+  /**
+   * Install a module from a PluginResolver resolution result.
+   * Copies specific skill directories and places module-help.csv at the target root.
+   * @param {Object} resolved - ResolvedModule from PluginResolver
+   * @param {string} bmadDir - Target bmad directory
+   * @param {Function} fileTrackingCallback - Optional callback to track installed files
+   * @param {Object} options - Installation options
+   */
+  async installFromResolution(resolved, bmadDir, fileTrackingCallback = null, options = {}) {
+    const targetPath = path.join(bmadDir, resolved.code);
+
+    if (await fs.pathExists(targetPath)) {
+      await fs.remove(targetPath);
+    }
+
+    await this._copyResolvedSkills(resolved, targetPath, fileTrackingCallback, options.moduleConfig);
 
     // Create directories declared in module.yaml (strategies 1-4 may have these)
     if (!options.skipModuleInstaller) {

package/tools/installer/ui.js

@@ -944,25 +944,32 @@ class UI {
       }
     }
 
-    // Add external registry modules (skip built-in duplicates)
-    const externalRegistryModules = registryModules.filter((mod) => !mod.builtIn && !builtInCodes.has(mod.code));
+    // Add external registry modules (skip built-in duplicates and deprecated
+    // modules that are not already installed — deprecated modules stay visible
+    // only so existing users can continue to manage them).
+    const externalRegistryModules = registryModules.filter(
+      (mod) => !mod.builtIn && !builtInCodes.has(mod.code) && (!mod.deprecated || installedModuleIds.has(mod.code)),
+    );
     let externalRegistryEntries = [];
     if (externalRegistryModules.length > 0) {
       const spinner = await prompts.spinner();
       spinner.start('Checking latest module versions...');
 
       externalRegistryEntries = await Promise.all(
-        externalRegistryModules.map(async (mod) => ({
-          code: mod.code,
-          entry: await buildModuleEntry(
+        externalRegistryModules.map(async (mod) => {
+          const entry = await buildModuleEntry(
             mod.code,
             mod.name,
             mod.description,
             mod.defaultSelected,
             mod.url || null,
             mod.defaultChannel || null,
-          ),
-        })),
+          );
+          if (mod.deprecated && mod.deprecationMessage) {
+            entry.hint = entry.hint ? `${entry.hint} — ${mod.deprecationMessage}` : mod.deprecationMessage;
+          }
+          return { code: mod.code, entry };
+        }),
       );
 
       spinner.stop('Checked latest module versions.');