fix(installer): require --tools for fresh --yes installs; remove --tools none (closes #2326)

Fresh non-interactive installs without --tools previously produced a
config-only install (~35 files vs ~1400 in the manifest) with no warning
and a "BMAD is ready to use" success card, leaving slash commands
unreachable. --tools none was an explicit opt-in for the same broken
state.

Now: fresh install + -y without --tools throws a helpful error pointing
at --list-tools. --tools none is rejected as an unknown ID. Empty and
typo'd tool IDs are also rejected. Existing-install paths (--action
update, quick-update, modify) are unchanged - they continue to reuse
previously-configured tools when --tools is omitted.

Adds --list-tools flag that prints all 42 supported tool IDs (id, name,
target_dir, preferred star) sourced from platform-codes.yaml.

English docs updated; localized docs (vi-vn, fr, cs, etc.) will sync via
the normal translation pass.

docs/how-to/install-bmad.md

@@ -18,7 +18,7 @@ Use `npx bmad-method install` to set up BMad in your project. One command handle
 
 - **Node.js** 20+ (the installer requires it)
 - **Git** (for cloning external modules)
-- **An AI tool** such as Claude Code or Cursor — or install without one using `--tools none`
+- **An AI tool** such as Claude Code or Cursor (run `npx bmad-method install --list-tools` to see all 42 supported tools)
 
 :::
 
@@ -122,7 +122,8 @@ Under `--yes`, patch and minor upgrades apply automatically. Majors stay frozen
 | `--yes`, `-y`                                                                              | Skip all prompts; accept flag values + defaults                                    |
 | `--directory <path>`                                                                       | Install into this directory (default: current working dir)                         |
 | `--modules <a,b,c>`                                                                        | Exact module set. Core is auto-added. Not a delta — list everything you want kept. |
-| `--tools <a,b>` or `--tools none`                                                          | IDE/tool selection. `none` skips tool config entirely.                             |
+| `--tools <a,b>`                                                                            | IDE/tool selection. Required for fresh `--yes` installs. Run `--list-tools` for valid IDs. |
+| `--list-tools`                                                                             | Print all supported tool/IDE IDs (with target directories) and exit.               |
 | `--action <type>`                                                                          | `install`, `update`, or `quick-update`. Defaults based on existing install state.  |
 | `--custom-source <urls>`                                                                   | Install custom modules from Git URLs or local paths                                |
 | `--channel <stable\|next>`                                                                 | Apply to all externals (aliased as `--all-stable` / `--all-next`)                  |
@@ -165,17 +166,17 @@ npx bmad-method install --yes --modules bmm,bmb --all-next --tools claude-code
 
 ```bash
 npx bmad-method install --yes --action update \
-  --modules bmm,bmb,gds \
+  --modules bmm,bmb,gds
-  --tools none
 ```
 
+`--tools` is omitted intentionally — `--action update` reuses the tools configured during the first install.
+
 **Mix channels — bmb on next, gds on stable:**
 
 ```bash
 npx bmad-method install --yes --action update \
   --modules bmm,bmb,cis,gds \
-  --next=bmb \
+  --next=bmb
-  --tools none
 ```
 
 :::caution[Rate limit on shared IPs]
@@ -204,7 +205,7 @@ For cross-machine reproducibility, don't rely on rerunning the same `--modules`
 
 ```bash
 npx bmad-method install --yes --modules bmb,cis \
-  --pin bmb=v1.7.0 --pin cis=v0.4.2 --tools none
+  --pin bmb=v1.7.0 --pin cis=v0.4.2 --tools claude-code
 ```
 
 ## Troubleshooting

tools/installer/commands/install.js

@@ -15,8 +15,9 @@ module.exports = {
     ['--modules <modules>', 'Comma-separated list of module IDs to install (e.g., "bmm,bmb")'],
     [
       '--tools <tools>',
-      'Comma-separated list of tool/IDE IDs to configure (e.g., "claude-code,cursor"). Use "none" to skip tool configuration.',
+      'Comma-separated list of tool/IDE IDs to configure (e.g., "claude-code,cursor"). Required for fresh non-interactive (--yes) installs. Run with --list-tools to see all valid IDs.',
     ],
+    ['--list-tools', 'Print all supported tool/IDE IDs (with target directories) and exit.'],
     ['--action <type>', 'Action type for existing installations: install, update, or quick-update'],
     ['--user-name <name>', 'Name for agents to use (default: system username)'],
     ['--communication-language <lang>', 'Language for agent communication (default: English)'],
@@ -40,6 +41,12 @@ module.exports = {
   ],
   action: async (options) => {
     try {
+      if (options.listTools) {
+        const { formatPlatformList } = require('../ide/platform-codes');
+        process.stdout.write((await formatPlatformList()) + '\n');
+        process.exit(0);
+      }
+
       // Set debug flag as environment variable for all components
       if (options.debug) {
         process.env.BMAD_DEBUG_MANIFEST = 'true';
@@ -81,7 +88,7 @@ module.exports = {
         } else {
           await prompts.log.error(`Installation failed: ${error.message}`);
         }
-        if (error.stack) {
+        if (error.stack && !error.expected) {
           await prompts.log.message(error.stack);
         }
       } catch {

tools/installer/ide/platform-codes.js

@@ -31,7 +31,63 @@ function clearCache() {
   _cachedPlatformCodes = null;
 }
 
+/**
+ * Format the platform list for human-readable output (used by --list-tools).
+ * @returns {Promise<string>} Formatted multi-line string with id, name, target_dir, preferred flag.
+ */
+async function formatPlatformList() {
+  const config = await loadPlatformCodes();
+  const platforms = config.platforms || {};
+
+  const entries = Object.entries(platforms).map(([id, p]) => ({
+    id,
+    name: p.name || id,
+    targetDir: p.installer?.target_dir || '',
+    preferred: p.preferred === true,
+    suspended: typeof p.suspended === 'string' ? p.suspended : null,
+  }));
+
+  entries.sort((a, b) => {
+    if (a.preferred !== b.preferred) return a.preferred ? -1 : 1;
+    return a.id.localeCompare(b.id);
+  });
+
+  const idWidth = Math.max(...entries.map((e) => e.id.length), 'ID'.length);
+  const nameWidth = Math.max(...entries.map((e) => e.name.length), 'Name'.length);
+
+  const pad = (s, w) => s + ' '.repeat(Math.max(0, w - s.length));
+  const lines = [
+    `Supported tool IDs (pass via --tools <id>[,<id>...]):`,
+    '',
+    `  ${pad('ID', idWidth)}  ${pad('Name', nameWidth)}  Target dir`,
+    `  ${pad('-'.repeat(idWidth), idWidth)}  ${pad('-'.repeat(nameWidth), nameWidth)}  ${'-'.repeat(10)}`,
+  ];
+
+  for (const e of entries) {
+    const star = e.preferred ? ' *' : '  ';
+    const suffix = e.suspended ? `  [suspended: ${e.suspended}]` : '';
+    lines.push(`${star}${pad(e.id, idWidth)}  ${pad(e.name, nameWidth)}  ${e.targetDir}${suffix}`);
+  }
+
+  lines.push('', '* = recommended / preferred', '', 'Example: bmad-method install --modules bmm --tools claude-code');
+
+  return lines.join('\n');
+}
+
+/**
+ * @returns {Promise<string[]>} List of valid platform IDs (suspended ones excluded).
+ */
+async function getValidPlatformIds() {
+  const config = await loadPlatformCodes();
+  const platforms = config.platforms || {};
+  return Object.entries(platforms)
+    .filter(([, p]) => !p.suspended)
+    .map(([id]) => id);
+}
+
 module.exports = {
   loadPlatformCodes,
   clearCache,
+  formatPlatformList,
+  getValidPlatformIds,
 };

tools/installer/ui.js

@@ -404,6 +404,37 @@ class UI {
    * @param {Object} options - Command-line options
    * @returns {Object} Tool configuration
    */
+  _parseToolsFlag(toolsArg, allKnownValues) {
+    const selectedIdes = String(toolsArg)
+      .split(',')
+      .map((t) => t.trim())
+      .filter(Boolean);
+
+    if (selectedIdes.length === 0) {
+      const err = new Error(
+        '--tools was passed empty. Provide at least one tool ID (e.g. --tools claude-code) or run with --list-tools to see valid IDs.',
+      );
+      err.expected = true;
+      throw err;
+    }
+
+    const unknown = selectedIdes.filter((id) => !allKnownValues.has(id));
+    if (unknown.length > 0) {
+      const err = new Error(
+        [
+          `Unknown tool ID${unknown.length === 1 ? '' : 's'}: ${unknown.join(', ')}`,
+          '',
+          'Run with --list-tools to see all valid IDs.',
+          'Common: claude-code, cursor, copilot, windsurf, cline',
+        ].join('\n'),
+      );
+      err.expected = true;
+      throw err;
+    }
+
+    return selectedIdes;
+  }
+
   async promptToolSelection(projectDir, options = {}) {
     const { ExistingInstall } = require('./core/existing-install');
     const { Installer } = require('./core/installer');
@@ -439,14 +470,7 @@ class UI {
 
       // Non-interactive: handle --tools and --yes flags before interactive prompt
       if (options.tools) {
-        if (options.tools.toLowerCase() === 'none') {
+        const selectedIdes = this._parseToolsFlag(options.tools, allKnownValues);
-          await prompts.log.info('Skipping tool configuration (--tools none)');
-          return { ides: [], skipIde: true };
-        }
-        const selectedIdes = options.tools
-          .split(',')
-          .map((t) => t.trim())
-          .filter(Boolean);
         await prompts.log.info(`Using tools from command-line: ${selectedIdes.join(', ')}`);
         await this.displaySelectedTools(selectedIdes, preferredIdes, allTools);
         return { ides: selectedIdes, skipIde: false };
@@ -524,19 +548,10 @@ class UI {
 
     // Check if tools are provided via command-line
     if (options.tools) {
-      // Check for explicit "none" value to skip tool installation
+      selectedIdes = this._parseToolsFlag(options.tools, allKnownValues);
-      if (options.tools.toLowerCase() === 'none') {
+      await prompts.log.info(`Using tools from command-line: ${selectedIdes.join(', ')}`);
-        await prompts.log.info('Skipping tool configuration (--tools none)');
+      await this.displaySelectedTools(selectedIdes, preferredIdes, allTools);
-        return { ides: [], skipIde: true };
+      return { ides: selectedIdes, skipIde: false };
-      } else {
-        selectedIdes = options.tools
-          .split(',')
-          .map((t) => t.trim())
-          .filter(Boolean);
-        await prompts.log.info(`Using tools from command-line: ${selectedIdes.join(', ')}`);
-        await this.displaySelectedTools(selectedIdes, preferredIdes, allTools);
-        return { ides: selectedIdes, skipIde: false };
-      }
     } else if (options.yes) {
       // If --yes flag is set, skip tool prompt and use previously configured tools or empty
       if (configuredIdes.length > 0) {
@@ -544,8 +559,20 @@ class UI {
         await this.displaySelectedTools(configuredIdes, preferredIdes, allTools);
         return { ides: configuredIdes, skipIde: false };
       } else {
-        await prompts.log.info('Skipping tool configuration (--yes flag, no previous tools)');
+        {
-        return { ides: [], skipIde: true };
+          const err = new Error(
+            [
+              '--tools is required for non-interactive install (--yes / -y) when no tools are previously configured.',
+              '',
+              'Common: claude-code, cursor, copilot, windsurf, cline',
+              'See all supported tools: bmad-method install --list-tools',
+              '',
+              'Example: bmad-method install --modules bmm --tools claude-code -y',
+            ].join('\n'),
+          );
+          err.expected = true;
+          throw err;
+        }
       }
     }