bmad-plus 0.12.0 → 0.12.2

package/tools/cli/commands/install.js

@@ -1,495 +1,598 @@
-/**
- * BMAD+ Install Command
- * Installs agents, skills, and IDE configs into the current project
- * Supports 10 languages: EN, FR, ES, DE, PT-BR, RU, ZH, HE, JA, IT
- *
- * Author: Laurent Rochetta
- */
-
-const path = require('node:path');
-const fs = require('node:fs');
-const fsExtra = require('fs-extra');
-const clack = require('@clack/prompts');
-const pc = require('picocolors');
-const { t, getLanguageOptions, getCommLanguageOptions } = require('../i18n');
-const { PACKS } = require('../lib/packs');
-const { copyPackFiles } = require('../lib/pack-copy');
-const { initMemory } = require('../lib/memory-init');
-const { generateIDEConfig, IDE_CONFIGS } = require('../lib/ide-config');
-const { validateUserName } = require('../lib/validate');
-const { provisionPack } = require('../lib/python-provision');
-
-// Packs whose runtime includes Python (registry.yaml: runtime includes "python").
-// Provisioned only when the user opts in with --provision-python, so the default
-// install (and the test suite) never spawns Python. Kills SEO "broken on arrival".
-const PYTHON_PACKS = {
-  seo: {
-    requirements: ['oveanet-pack', 'seo-audit-360', 'requirements.txt'],
-    verifyModules: ['requests', 'bs4', 'defusedxml', 'lxml'],
-  },
-  memory: {
-    requirements: ['mcp-server', 'requirements.txt'],
-    verifyModules: ['chromadb'],
-  },
-};
-
-// Pack definitions are imported from the shared module: require('../lib/packs').PACKS
-
-module.exports = {
-  command: 'install',
-  description: 'Install BMAD+ agents and skills into your project',
-  options: [
-    ['-d, --directory <path>', 'Installation directory (default: current directory)'],
-    ['-p, --packs <packs>', 'Comma-separated pack IDs: core,osint,all (default: interactive)'],
-    ['-y, --yes', 'Accept all defaults, skip prompts'],
-    ['-l, --lang <code>', 'Language code: en, fr, es, de, pt-br, ru, zh, he, ja, it (overrides auto-detection)'],
-    ['--tools <tools>', 'Comma-separated IDE IDs (default: auto-detect)'],
-    ['--provision-python', 'Provision an isolated Python env for packs that need one (seo, memory)'],
-  ],
-  action: async (options) => {
-    const projectDir = path.resolve(options.directory || process.cwd());
-    const bmadSrc = path.join(__dirname, '..', '..', '..', 'src', 'bmad-plus');
-
-    // ── Step 0: Language Selection ──
-    const pkgJson = require('../../../package.json');
-    clack.intro(pc.bgCyan(pc.black(` BMAD+ Installer v${pkgJson.version} `)));
-    clack.log.info(pc.dim('✨ Created by Laurent Rochetta — github.com/lrochetta/BMAD-PLUS'));
-
-    let lang = options.lang || 'en';
-    if (!options.yes && !options.lang) {
-      const langChoice = await clack.select({
-        message: '🌐 Select your language / Choisissez votre langue / 选择语言',
-        options: getLanguageOptions(),
-      });
-
-      if (clack.isCancel(langChoice)) {
-        clack.cancel('Installation cancelled.');
-        throw new Error('Installation cancelled.');
-      }
-      lang = langChoice;
-    }
-
-    const i = t(lang); // Get translations for selected language
-
-    // Verify source exists
-    if (!fs.existsSync(bmadSrc)) {
-      clack.log.error(`${i.source_not_found}: ${bmadSrc}`);
-      clack.outro(pc.red(i.failed));
-      throw new Error(`Source not found: ${bmadSrc}`);
-    }
-
-    clack.log.info(`${i.installing_to}: ${pc.cyan(projectDir)}`);
-
-    // ── Step 1: Pack Selection ──
-    let selectedPacks = ['core']; // Core always included
-
-    if (options.packs) {
-      const requested = options.packs.split(',').map(p => p.trim());
-      if (requested.includes('all')) {
-        selectedPacks = Object.keys(PACKS).filter(k => !PACKS[k].disabled);
-      } else {
-        selectedPacks = [...new Set(['core', ...requested.filter(p => PACKS[p] && !PACKS[p].disabled)])];
-      }
-    } else if (!options.yes) {
-      const packChoice = await clack.multiselect({
-        message: i.select_packs,
-        options: Object.entries(PACKS)
-          .filter(([, p]) => !p.required)
-          .map(([key, pack]) => ({
-            value: key,
-            label: `${pack.icon} ${pack.name}`,
-            hint: pack.disabled ? i.soon : (pack.desc || pack.description || ''),
-            disabled: pack.disabled,
-          })),
-        required: false,
-      });
-
-      if (clack.isCancel(packChoice)) {
-        clack.cancel(i.cancelled);
-        throw new Error(i.cancelled);
-      }
-
-      selectedPacks = [...new Set(['core', ...packChoice])];
-    }
-
-    clack.log.success(`${i.selected_packs}: ${selectedPacks.map(p => `${PACKS[p].icon} ${PACKS[p].name}`).join(', ')}`);
-
-    // ── Step 2: IDE Detection ──
-    let detectedIDEs = [];
-
-    if (options.tools) {
-      if (options.tools === 'none' || options.tools === 'skip') {
-        detectedIDEs = [];
-      } else {
-        detectedIDEs = options.tools.split(',').map(t => t.trim()).filter(t => IDE_CONFIGS[t]);
-      }
-    } else {
-      // Auto-detect
-      for (const [id, ide] of Object.entries(IDE_CONFIGS)) {
-        for (const marker of ide.detect) {
-          if (fs.existsSync(path.join(projectDir, marker))) {
-            detectedIDEs.push(id);
-            break;
-          }
-        }
-      }
-
-      // If nothing detected, ask
-      if (detectedIDEs.length === 0 && !options.yes) {
-        const ideChoice = await clack.multiselect({
-          message: i.select_ide,
-          options: Object.entries(IDE_CONFIGS).map(([key, ide]) => ({
-            value: key,
-            label: ide.name,
-          })),
-          required: false,
-        });
-
-        if (!clack.isCancel(ideChoice)) {
-          detectedIDEs = ideChoice;
-        }
-      }
-
-      // Default to all if --yes
-      if (detectedIDEs.length === 0 && options.yes) {
-        detectedIDEs = Object.keys(IDE_CONFIGS);
-      }
-    }
-
-    if (detectedIDEs.length > 0) {
-      clack.log.info(`${i.detected_ides}: ${detectedIDEs.map(id => IDE_CONFIGS[id].name).join(', ')}`);
-    } else if (options.tools === 'none' || options.tools === 'skip') {
-      clack.log.info(pc.dim('⏭️  IDE config skipped (--tools none) — existing configs preserved'));
-    }
-
-    // ── Step 3: User Config ──
-    let userName = process.env.USER || process.env.USERNAME || 'Developer';
-    let commLang = 'French';
-
-    if (!options.yes) {
-      const userConfig = await clack.group({
-        userName: () => clack.text({
-          message: i.enter_name,
-          placeholder: userName,
-          defaultValue: userName,
-        }),
-        commLang: () => clack.select({
-          message: i.comm_language,
-          options: getCommLanguageOptions(),
-        }),
-        execMode: () => clack.select({
-          message: i.exec_mode,
-          options: [
-            { value: 'manual', label: i.exec_manual },
-            { value: 'autopilot', label: i.exec_autopilot },
-            { value: 'hybrid', label: i.exec_hybrid },
-          ],
-        }),
-      });
-
-      if (clack.isCancel(userConfig)) {
-        clack.cancel(i.cancelled);
-        throw new Error(i.cancelled);
-      }
-
-      // Validate user-provided name
-      const rawName = userConfig.userName;
-      const fb = process.env.USER || process.env.USERNAME || 'Developer';
-      const { name: validatedName, warnings } = validateUserName(rawName, fb);
-      for (const w of warnings) clack.log.warn(w);
-      userName = validatedName;
-      commLang = userConfig.commLang;
-    }
-
-    // ── Step 4: Install Files ──
-    const spinner = clack.spinner();
-    spinner.start(i.installing_files);
-
-    const targetAgentsDir = path.join(projectDir, '.agents', 'skills');
-    const targetDataDir = path.join(projectDir, '.agents', 'data');
-    const targetBmadDir = path.join(projectDir, '_bmad');
-
-    // Create directories
-    fsExtra.ensureDirSync(targetAgentsDir);
-    fsExtra.ensureDirSync(targetDataDir);
-    fsExtra.ensureDirSync(targetBmadDir);
-
-    let copiedAgents = 0;
-    let copiedSkills = 0;
-    let copiedFiles = 0;
-
-    const projectRoot = path.join(bmadSrc, '..', '..');
-
-    for (const packId of selectedPacks) {
-      const pack = PACKS[packId];
-      if (!pack || pack.disabled) continue;
-
-      const result = copyPackFiles({
-        bmadSrc,
-        targetAgentsDir,
-        targetDataDir,
-        projectRoot,
-        pack,
-      });
-      copiedAgents += result.copiedAgents;
-      copiedSkills += result.copiedSkills;
-      copiedFiles += result.copiedFiles;
-
-      // Memory pack: initialize brain with existing brain detection
-      if (packId === 'memory' && pack.packDir) {
-        initMemory({ projectDir, bmadSrc, userName, commLang, selectedPacks });
-      }
-    }
-
-    // ── Python provisioning (opt-in) — for packs whose runtime needs Python ──
-    // Off by default so `install` never spawns Python unless asked. Closes the
-    // "SEO pack ships prompts that call scripts never installed" gap (PROD-02).
-    if (options.provisionPython) {
-      const pythonPacks = selectedPacks.filter((p) => PYTHON_PACKS[p]);
-      for (const packId of pythonPacks) {
-        const cfg = PYTHON_PACKS[packId];
-        const requirementsPath = path.join(projectRoot, ...cfg.requirements);
-        if (!fs.existsSync(requirementsPath)) {
-          clack.log.warn(`Python provisioning skipped for ${packId}: ${requirementsPath} not found.`);
-          continue;
-        }
-        const pySpinner = clack.spinner();
-        pySpinner.start(`Provisioning Python runtime for ${PACKS[packId].name}…`);
-        const res = provisionPack({
-          envDir: path.join(projectDir, '.bmad', 'venv', packId),
-          requirementsPath,
-          verifyModules: cfg.verifyModules,
-        });
-        pySpinner.stop(
-          res.ok
-            ? `${PACKS[packId].name}: Python runtime ready (${res.tool}).`
-            : `${PACKS[packId].name}: Python not provisioned — ${res.messages[res.messages.length - 1] || 'see guidance'}`
-        );
-        if (!res.ok) {
-          clack.log.warn(`Run \`${PACKS[packId].name}\` Python tools after installing Python ≥3.11; the pack's prompts still work, only the local scripts need the runtime.`);
-        }
-      }
-    }
-
-    // Copy module config
-    const moduleYaml = path.join(bmadSrc, 'module.yaml');
-    if (fs.existsSync(moduleYaml)) {
-      fsExtra.copySync(moduleYaml, path.join(targetBmadDir, 'module.yaml'));
-      copiedFiles++;
-    }
-
-    const helpCsv = path.join(bmadSrc, 'module-help.csv');
-    if (fs.existsSync(helpCsv)) {
-      fsExtra.copySync(helpCsv, path.join(targetBmadDir, 'module-help.csv'));
-      copiedFiles++;
-    }
-
-    spinner.stop(i.installed_summary(copiedAgents, copiedSkills, copiedFiles));
-
-    // ── Step 5: Generate IDE Configs ──
-    if (detectedIDEs.length > 0) {
-      const ideSpinner = clack.spinner();
-      ideSpinner.start(i.configuring_ides);
-
-      const configContent = generateIDEConfig(userName, commLang, selectedPacks);
-      // Marker present in every BMAD+-generated IDE config (see lib/ide-config.js).
-      const BMAD_MARKER = 'BMAD+ — AI Agent Configuration';
-
-      for (const ideId of detectedIDEs) {
-        const ide = IDE_CONFIGS[ideId];
-        if (!ide) continue;
-
-        const configPath = path.join(projectDir, ide.configFile);
-
-        // NODE-02: never clobber a hand-authored config without protecting it.
-        if (fs.existsSync(configPath)) {
-          const existing = fs.readFileSync(configPath, 'utf8');
-          if (!existing.includes(BMAD_MARKER)) {
-            if (!options.yes) {
-              // Interactive: keep the user's file untouched.
-              clack.log.warn(`⚠️  ${ide.configFile} already exists and was not created by BMAD+ — kept your file (skipped). Re-run with --yes to back it up and overwrite.`);
-              continue;
-            }
-            // Non-interactive: back up before overwriting, never destroy data.
-            let backupPath = `${configPath}.bak`;
-            if (fs.existsSync(backupPath)) backupPath = `${configPath}.${Date.now()}.bak`;
-            fs.copyFileSync(configPath, backupPath);
-            clack.log.warn(`⚠️  Backed up existing ${ide.configFile} → ${path.basename(backupPath)}`);
-          }
-        }
-
-        fs.writeFileSync(configPath, configContent, 'utf8');
-      }
-
-      ideSpinner.stop(i.ide_configured(detectedIDEs.length));
-    }
-
-    // ── Step 6: Create config.yaml ──
-    const configYaml = generateConfigYaml(userName, commLang, projectDir);
-    const configPath = path.join(targetBmadDir, 'config.yaml');
-    fs.writeFileSync(configPath, configYaml, 'utf8');
-
-    // ── Step 7: Create output directories ──
-    const outputDir = path.join(projectDir, '_bmad-output');
-    fsExtra.ensureDirSync(path.join(outputDir, 'discovery'));
-    fsExtra.ensureDirSync(path.join(outputDir, 'build'));
-    fsExtra.ensureDirSync(path.join(projectDir, 'docs'));
-
-    // ── Step 8: Write install manifest ──
-    const pkgVersion = require('../../../package.json').version;
-    const manifest = {
-      version: pkgVersion,
-      uiLanguage: lang,
-      installed: new Date().toISOString(),
-      packs: selectedPacks,
-      ides: detectedIDEs,
-      user: userName,
-      language: commLang,
-    };
-    fs.writeFileSync(
-      path.join(targetBmadDir, '.bmad-plus-install.json'),
-      JSON.stringify(manifest, null, 2),
-      'utf8'
-    );
-
-    // ── Summary — Contextual Getting Started ──
-    const agentGuide = [
-      i.guide_who,
-      '',
-      `  ${i.guide_idea.padEnd(28)} →  "Atlas, [...]"`,
-      `  ${i.guide_prd.padEnd(28)} →  "Atlas, create PRD"`,
-      `  ${i.guide_arch.padEnd(28)} →  "Forge, propose architecture"`,
-      `  ${i.guide_code.padEnd(28)} →  "Forge, implement story [X]"`,
-      `  ${i.guide_test.padEnd(28)} →  "Sentinel, review module [X]"`,
-      `  ${i.guide_sprint.padEnd(28)} →  "Nexus, create epics"`,
-      `  ${i.guide_auto.padEnd(28)} →  "autopilot"`,
-    ];
-
-    if (selectedPacks.includes('osint')) {
-      agentGuide.push(`  ${i.guide_osint.padEnd(28)} →  "Shadow, investigate [name]"`);
-    }
-
-    if (selectedPacks.includes('maker')) {
-      agentGuide.push(`  ${i.guide_maker.padEnd(28)} →  "Maker, create agent [desc]"`);
-    }
-
-    if (selectedPacks.includes('seo')) {
-      agentGuide.push(`  ${i.guide_seo.padEnd(28)} →  "/seo audit <url>"`);
-    }
-
-    if (selectedPacks.includes('backup')) {
-      agentGuide.push(`  ${i.guide_backup.padEnd(28)} →  "/backup create"`);
-    }
-
-    if (selectedPacks.includes('animated')) {
-      agentGuide.push(`  ${i.guide_animated.padEnd(28)} →  "/animated build <video>"`);
-    }
-
-    if (selectedPacks.includes('shield')) {
-      agentGuide.push(`  ${(i.guide_shield || '🛡️ GRC Compliance').padEnd(28)} →  "Shield, audit my SaaS for GDPR"`);
-    }
-
-    if (selectedPacks.includes('memory')) {
-      agentGuide.push(`  ${(i.guide_memory || '🧠 Memory Brain').padEnd(28)} →  "Zecher, scan projects in [path]"`);
-    }
-
-    if (selectedPacks.includes('dev-studio')) {
-      agentGuide.push(`  ${(i.guide_dev_studio || '🏗️ Dev Studio').padEnd(28)} →  "Miriam, brainstorm my app idea"`);
-    }
-
-    agentGuide.push(
-      '',
-      i.guide_workflow,
-      '  1. Atlas (idea → brief → PRD)',
-      '  2. Forge (architecture → code)',
-      '  3. Sentinel (tests → review)',
-      '',
-      i.guide_or_auto,
-      '',
-      `${i.guide_output}: _bmad-output/discovery/ & _bmad-output/build/`,
-      '',
-      '─'.repeat(50),
-      '',
-      `📦 ${i.guide_cli_title || 'CLI Commands'}:`,
-      `  npx bmad-plus install    ${i.guide_cli_install || '— Install agents & skills'}`,
-      `  npx bmad-plus update     ${i.guide_cli_update || '— Update agents (keeps config)'}`,
-      `  npx bmad-plus doctor     ${i.guide_cli_doctor || '— Check installation health'}`,
-      `  npx bmad-plus uninstall  ${i.guide_cli_uninstall || '— Remove BMAD+ from project'}`,
-    );
-
-    // Add pack-specific examples
-    const examples = [];
-    if (selectedPacks.includes('seo')) {
-      examples.push(`  ${i.guide_example_seo || '🔍 SEO: "/seo audit https://example.com"'}`);
-    }
-    if (selectedPacks.includes('backup')) {
-      examples.push(`  ${i.guide_example_backup || '🗂️  Backup: "/backup create" → ZIP timestamped'}`);
-    }
-    if (selectedPacks.includes('animated')) {
-      examples.push(`  ${i.guide_example_animated || '🎬 Animated: "/animated build hero.mp4"'}`);
-    }
-    if (selectedPacks.includes('osint')) {
-      examples.push(`  ${i.guide_example_osint || '🔍 OSINT: "Shadow, investigate John Doe"'}`);
-    }
-    if (selectedPacks.includes('shield')) {
-      examples.push(
-        `  ${i.guide_example_shield_1 || '🛡️ GRC: "Shield, audit my app for GDPR compliance"'}`,
-        `  ${i.guide_example_shield_2 || '🛡️ GRC: "Shield, gap analysis ISO 27001 vs NIST CSF"'}`,
-        `  ${i.guide_example_shield_3 || '🛡️ GRC: "Shield, generate SOC 2 evidence checklist"'}`,
-      );
-    }
-    if (selectedPacks.includes('dev-studio')) {
-      examples.push(
-        `  ${i.guide_example_dev_studio_1 || '🏗️ Dev Studio: "Miriam, brainstorm a productivity app"'}`,
-        `  ${i.guide_example_dev_studio_2 || '🏗️ Dev Studio: "Bezalel, design the architecture"'}`,
-        `  ${i.guide_example_dev_studio_3 || '🏗️ Dev Studio: "Oholiab, implement story S1"'}`,
-      );
-    }
-    if (selectedPacks.includes('memory')) {
-      examples.push(
-        `  ${i.guide_example_memory_1 || '🧠 Memory: "Zecher, scan projects in D:\\travail\\DEV"'}`,
-        `  ${i.guide_example_memory_2 || '🧠 Memory: "Zecher, where were we?"'}`,
-        `  ${i.guide_example_memory_3 || '🧠 Memory: "Zecher, consolidate memory"'}`,
-      );
-    }
-
-    if (examples.length > 0) {
-      agentGuide.push(
-        '',
-        `💡 ${i.guide_examples_title || 'Quick Examples'}:`,
-        ...examples
-      );
-    }
-
-    agentGuide.push(
-      '',
-      '---',
-      i.guide_credits
-    );
-
-    clack.note(agentGuide.join('\n'), i.guide_title);
-
-    clack.outro(pc.green(i.guide_ready));
-  },
-};
-
-
-// ── Helpers ──
-
-function generateConfigYaml(userName, language, projectDir) {
-  const projectName = path.basename(projectDir);
-  return `# BMAD+ Project Configuration
-# Generated by bmad-plus install
-
-user_name: "${userName}"
-communication_language: "${language}"
-document_output_language: "${language}"
-output_folder: "_bmad-output"
-project_name: "${projectName}"
-
-# Execution settings
-execution_mode: "manual"
-auto_role_activation: true
-parallel_execution: true
-`;
-}
+/**
+ * BMAD+ Install Command
+ * Installs agents, skills, and IDE configs into the current project
+ * Supports 10 languages: EN, FR, ES, DE, PT-BR, RU, ZH, HE, JA, IT
+ *
+ * Author: Laurent Rochetta
+ */
+
+const path = require('node:path');
+const fs = require('node:fs');
+const fsExtra = require('fs-extra');
+const clack = require('@clack/prompts');
+const pc = require('picocolors');
+const { t, getLanguageOptions, getCommLanguageOptions } = require('../i18n');
+const { PACKS } = require('../lib/packs');
+const { copyPackFiles } = require('../lib/pack-copy');
+const { initMemory } = require('../lib/memory-init');
+const { generateIDEConfig, IDE_CONFIGS } = require('../lib/ide-config');
+const { validateUserName } = require('../lib/validate');
+const { provisionPack } = require('../lib/python-provision');
+
+// Packs whose runtime includes Python (registry.yaml: runtime includes "python").
+// Provisioned only when the user opts in with --provision-python, so the default
+// install (and the test suite) never spawns Python. Kills SEO "broken on arrival".
+// Paths are resolved relative to the PACKAGE root (projectRoot below), so they
+// must live under a directory shipped in package.json "files". The SEO toolkit
+// is embarked in-pack (src/bmad-plus/packs/pack-seo) precisely so npm consumers
+// receive the scripts + requirements the SKILL.md commands them to run.
+const PYTHON_PACKS = {
+  seo: {
+    requirements: ['src', 'bmad-plus', 'packs', 'pack-seo', 'requirements.txt'],
+    verifyModules: ['requests', 'bs4', 'defusedxml', 'lxml'],
+  },
+  memory: {
+    // NOTE: mcp-server is not in package.json "files" → this still warn-skips for
+    // npm consumers (memory RAG provisioning is a separate, pre-existing gap).
+    requirements: ['mcp-server', 'requirements.txt'],
+    verifyModules: ['chromadb'],
+  },
+};
+
+// Pack definitions are imported from the shared module: require('../lib/packs').PACKS
+
+// ── Root-config ownership markers (PROD-01) ──
+//
+// install writes CLAUDE.md / GEMINI.md / AGENTS.md, but TWO producers own those
+// same paths, each stamping its own marker:
+//   - lib/ide-config.js                 → INSTALLER_MARKER (this installer's template)
+//   - tools/build/generate-adapters.js  → GENERATED_MARKER (registry-generated spine)
+// Recognizing only the first is what let `install --yes` clobber a generated spine.
+const INSTALLER_MARKER = 'BMAD+ — AI Agent Configuration';
+const GENERATOR_MARKER_FALLBACK = 'AUTO-GENERATED by tools/build/generate-adapters.js';
+
+/**
+ * The marker the adapter generator stamps on every root file it owns.
+ * Read from the generator's own export so the two cannot drift apart — a
+ * hand-typed copy is how INSTALLER_MARKER drifted from the spine in the first
+ * place. The fallback only covers trees published without the build tooling;
+ * tests/unit/install-spine.test.js pins both values to their real producer.
+ */
+function resolveGeneratorMarker() {
+  try {
+    return require('../../build/generate-adapters').GENERATED_MARKER || GENERATOR_MARKER_FALLBACK;
+  } catch {
+    return GENERATOR_MARKER_FALLBACK;
+  }
+}
+
+module.exports = {
+  command: 'install',
+  description: 'Install BMAD+ agents and skills into your project',
+  options: [
+    ['-d, --directory <path>', 'Installation directory (default: current directory)'],
+    ['-p, --packs <packs>', 'Comma-separated pack IDs: core,osint,all (default: interactive)'],
+    ['-y, --yes', 'Accept all defaults, skip prompts'],
+    ['-l, --lang <code>', 'Language code: en, fr, es, de, pt-br, ru, zh, he, ja, it (overrides auto-detection)'],
+    ['--tools <tools>', 'Comma-separated IDE IDs (default: auto-detect)'],
+    ['--provision-python', 'Provision an isolated Python env for packs that need one (seo, memory)'],
+  ],
+  action: async (options) => {
+    const projectDir = path.resolve(options.directory || process.cwd());
+    const bmadSrc = path.join(__dirname, '..', '..', '..', 'src', 'bmad-plus');
+
+    // ── Step 0: Language Selection ──
+    const pkgJson = require('../../../package.json');
+    clack.intro(pc.bgCyan(pc.black(` BMAD+ Installer v${pkgJson.version} `)));
+    clack.log.info(pc.dim('✨ Created by Laurent Rochetta — github.com/lrochetta/BMAD-PLUS'));
+
+    let lang = options.lang || 'en';
+    if (!options.yes && !options.lang) {
+      const langChoice = await clack.select({
+        message: '🌐 Select your language / Choisissez votre langue / 选择语言',
+        options: getLanguageOptions(),
+      });
+
+      if (clack.isCancel(langChoice)) {
+        clack.cancel('Installation cancelled.');
+        throw new Error('Installation cancelled.');
+      }
+      lang = langChoice;
+    }
+
+    const i = t(lang); // Get translations for selected language
+
+    // Verify source exists
+    if (!fs.existsSync(bmadSrc)) {
+      clack.log.error(`${i.source_not_found}: ${bmadSrc}`);
+      clack.outro(pc.red(i.failed));
+      throw new Error(`Source not found: ${bmadSrc}`);
+    }
+
+    clack.log.info(`${i.installing_to}: ${pc.cyan(projectDir)}`);
+
+    // ── Step 1: Pack Selection ──
+    let selectedPacks = ['core']; // Core always included
+
+    if (options.packs) {
+      const requested = options.packs.split(',').map(p => p.trim());
+      if (requested.includes('all')) {
+        selectedPacks = Object.keys(PACKS).filter(k => !PACKS[k].disabled);
+      } else {
+        selectedPacks = [...new Set(['core', ...requested.filter(p => PACKS[p] && !PACKS[p].disabled)])];
+      }
+    } else if (!options.yes) {
+      const packChoice = await clack.multiselect({
+        message: i.select_packs,
+        options: Object.entries(PACKS)
+          .filter(([, p]) => !p.required)
+          .map(([key, pack]) => ({
+            value: key,
+            label: `${pack.icon} ${pack.name}`,
+            hint: pack.disabled ? i.soon : (pack.desc || pack.description || ''),
+            disabled: pack.disabled,
+          })),
+        required: false,
+      });
+
+      if (clack.isCancel(packChoice)) {
+        clack.cancel(i.cancelled);
+        throw new Error(i.cancelled);
+      }
+
+      selectedPacks = [...new Set(['core', ...packChoice])];
+    }
+
+    clack.log.success(`${i.selected_packs}: ${selectedPacks.map(p => `${PACKS[p].icon} ${PACKS[p].name}`).join(', ')}`);
+
+    // ── Step 2: IDE Detection ──
+    let detectedIDEs = [];
+
+    if (options.tools) {
+      if (options.tools === 'none' || options.tools === 'skip') {
+        detectedIDEs = [];
+      } else {
+        detectedIDEs = options.tools.split(',').map(t => t.trim()).filter(t => IDE_CONFIGS[t]);
+      }
+    } else {
+      // Auto-detect
+      for (const [id, ide] of Object.entries(IDE_CONFIGS)) {
+        for (const marker of ide.detect) {
+          if (fs.existsSync(path.join(projectDir, marker))) {
+            detectedIDEs.push(id);
+            break;
+          }
+        }
+      }
+
+      // If nothing detected, ask
+      if (detectedIDEs.length === 0 && !options.yes) {
+        const ideChoice = await clack.multiselect({
+          message: i.select_ide,
+          options: Object.entries(IDE_CONFIGS).map(([key, ide]) => ({
+            value: key,
+            label: ide.name,
+          })),
+          required: false,
+        });
+
+        if (!clack.isCancel(ideChoice)) {
+          detectedIDEs = ideChoice;
+        }
+      }
+
+      // Default to all if --yes
+      if (detectedIDEs.length === 0 && options.yes) {
+        detectedIDEs = Object.keys(IDE_CONFIGS);
+      }
+    }
+
+    if (detectedIDEs.length > 0) {
+      clack.log.info(`${i.detected_ides}: ${detectedIDEs.map(id => IDE_CONFIGS[id].name).join(', ')}`);
+    } else if (options.tools === 'none' || options.tools === 'skip') {
+      clack.log.info(pc.dim('⏭️  IDE config skipped (--tools none) — existing configs preserved'));
+    }
+
+    // ── Step 3: User Config ──
+    let userName = process.env.USER || process.env.USERNAME || 'Developer';
+    let commLang = 'French';
+
+    if (!options.yes) {
+      const userConfig = await clack.group({
+        userName: () => clack.text({
+          message: i.enter_name,
+          placeholder: userName,
+          defaultValue: userName,
+        }),
+        commLang: () => clack.select({
+          message: i.comm_language,
+          options: getCommLanguageOptions(),
+        }),
+        execMode: () => clack.select({
+          message: i.exec_mode,
+          options: [
+            { value: 'manual', label: i.exec_manual },
+            { value: 'autopilot', label: i.exec_autopilot },
+            { value: 'hybrid', label: i.exec_hybrid },
+          ],
+        }),
+      });
+
+      if (clack.isCancel(userConfig)) {
+        clack.cancel(i.cancelled);
+        throw new Error(i.cancelled);
+      }
+
+      // Validate user-provided name
+      const rawName = userConfig.userName;
+      const fb = process.env.USER || process.env.USERNAME || 'Developer';
+      const { name: validatedName, warnings } = validateUserName(rawName, fb);
+      for (const w of warnings) clack.log.warn(w);
+      userName = validatedName;
+      commLang = userConfig.commLang;
+    }
+
+    // ── Step 4: Install Files ──
+    const spinner = clack.spinner();
+    spinner.start(i.installing_files);
+
+    const targetAgentsDir = path.join(projectDir, '.agents', 'skills');
+    const targetDataDir = path.join(projectDir, '.agents', 'data');
+    const targetBmadDir = path.join(projectDir, '_bmad');
+
+    // Create directories
+    fsExtra.ensureDirSync(targetAgentsDir);
+    fsExtra.ensureDirSync(targetDataDir);
+    fsExtra.ensureDirSync(targetBmadDir);
+
+    let copiedAgents = 0;
+    let copiedSkills = 0;
+    let copiedFiles = 0;
+
+    const projectRoot = path.join(bmadSrc, '..', '..');
+
+    for (const packId of selectedPacks) {
+      const pack = PACKS[packId];
+      if (!pack || pack.disabled) continue;
+
+      const result = copyPackFiles({
+        bmadSrc,
+        targetAgentsDir,
+        targetDataDir,
+        projectRoot,
+        pack,
+      });
+      copiedAgents += result.copiedAgents;
+      copiedSkills += result.copiedSkills;
+      copiedFiles += result.copiedFiles;
+
+      // Memory pack: initialize brain with existing brain detection.
+      // Non-fatal: a read-only or missing home dir (containers, CI) must not
+      // abort the install mid-flight and leave a manifest-less partial tree.
+      if (packId === 'memory' && pack.packDir) {
+        try {
+          initMemory({ projectDir, bmadSrc, userName, commLang, selectedPacks });
+        } catch (err) {
+          clack.log.warn(`Memory/brain initialization failed (non-fatal, install continues): ${err.message}`);
+        }
+      }
+    }
+
+    // ── Python provisioning (opt-in) — for packs whose runtime needs Python ──
+    // Off by default so `install` never spawns Python unless asked. Closes the
+    // "SEO pack ships prompts that call scripts never installed" gap (PROD-02).
+    if (options.provisionPython) {
+      const pythonPacks = selectedPacks.filter((p) => PYTHON_PACKS[p]);
+      for (const packId of pythonPacks) {
+        const cfg = PYTHON_PACKS[packId];
+        const requirementsPath = path.join(projectRoot, ...cfg.requirements);
+        if (!fs.existsSync(requirementsPath)) {
+          clack.log.warn(`Python provisioning skipped for ${packId}: ${requirementsPath} not found.`);
+          continue;
+        }
+        const pySpinner = clack.spinner();
+        pySpinner.start(`Provisioning Python runtime for ${PACKS[packId].name}…`);
+        const res = provisionPack({
+          envDir: path.join(projectDir, '.bmad', 'venv', packId),
+          requirementsPath,
+          verifyModules: cfg.verifyModules,
+        });
+        pySpinner.stop(
+          res.ok
+            ? `${PACKS[packId].name}: Python runtime ready (${res.tool}).`
+            : `${PACKS[packId].name}: Python not provisioned — ${res.messages[res.messages.length - 1] || 'see guidance'}`
+        );
+        if (!res.ok) {
+          clack.log.warn(`Run \`${PACKS[packId].name}\` Python tools after installing Python ≥3.11; the pack's prompts still work, only the local scripts need the runtime.`);
+        }
+      }
+    }
+
+    // Copy module config
+    const moduleYaml = path.join(bmadSrc, 'module.yaml');
+    if (fs.existsSync(moduleYaml)) {
+      fsExtra.copySync(moduleYaml, path.join(targetBmadDir, 'module.yaml'));
+      copiedFiles++;
+    }
+
+    const helpCsv = path.join(bmadSrc, 'module-help.csv');
+    if (fs.existsSync(helpCsv)) {
+      fsExtra.copySync(helpCsv, path.join(targetBmadDir, 'module-help.csv'));
+      copiedFiles++;
+    }
+
+    spinner.stop(i.installed_summary(copiedAgents, copiedSkills, copiedFiles));
+
+    // ── Step 5: Generate IDE Configs ──
+    if (detectedIDEs.length > 0) {
+      const ideSpinner = clack.spinner();
+      ideSpinner.start(i.configuring_ides);
+
+      writeIDEConfigs({
+        projectDir,
+        detectedIDEs,
+        configContent: generateIDEConfig(userName, commLang, selectedPacks),
+        yes: options.yes,
+      });
+
+      ideSpinner.stop(i.ide_configured(detectedIDEs.length));
+    }
+
+    // ── Step 6: Create config.yaml ──
+    const configYaml = generateConfigYaml(userName, commLang, projectDir);
+    const configPath = path.join(targetBmadDir, 'config.yaml');
+    fs.writeFileSync(configPath, configYaml, 'utf8');
+
+    // ── Step 7: Create output directories ──
+    const outputDir = path.join(projectDir, '_bmad-output');
+    fsExtra.ensureDirSync(path.join(outputDir, 'discovery'));
+    fsExtra.ensureDirSync(path.join(outputDir, 'build'));
+    fsExtra.ensureDirSync(path.join(projectDir, 'docs'));
+
+    // ── Step 8: Write install manifest ──
+    const pkgVersion = require('../../../package.json').version;
+    const manifest = {
+      version: pkgVersion,
+      uiLanguage: lang,
+      installed: new Date().toISOString(),
+      packs: selectedPacks,
+      ides: detectedIDEs,
+      user: userName,
+      language: commLang,
+    };
+    fs.writeFileSync(
+      path.join(targetBmadDir, '.bmad-plus-install.json'),
+      JSON.stringify(manifest, null, 2),
+      'utf8'
+    );
+
+    // ── Summary — Contextual Getting Started ──
+    const agentGuide = [
+      i.guide_who,
+      '',
+      `  ${i.guide_idea.padEnd(28)} →  "Atlas, [...]"`,
+      `  ${i.guide_prd.padEnd(28)} →  "Atlas, create PRD"`,
+      `  ${i.guide_arch.padEnd(28)} →  "Forge, propose architecture"`,
+      `  ${i.guide_code.padEnd(28)} →  "Forge, implement story [X]"`,
+      `  ${i.guide_test.padEnd(28)} →  "Sentinel, review module [X]"`,
+      `  ${i.guide_sprint.padEnd(28)} →  "Nexus, create epics"`,
+      `  ${i.guide_auto.padEnd(28)} →  "autopilot"`,
+    ];
+
+    if (selectedPacks.includes('osint')) {
+      agentGuide.push(`  ${i.guide_osint.padEnd(28)} →  "Shadow, investigate [name]"`);
+    }
+
+    if (selectedPacks.includes('maker')) {
+      agentGuide.push(`  ${i.guide_maker.padEnd(28)} →  "Maker, create agent [desc]"`);
+    }
+
+    if (selectedPacks.includes('seo')) {
+      agentGuide.push(`  ${i.guide_seo.padEnd(28)} →  "/seo audit <url>"`);
+    }
+
+    if (selectedPacks.includes('backup')) {
+      agentGuide.push(`  ${i.guide_backup.padEnd(28)} →  "/backup create"`);
+    }
+
+    if (selectedPacks.includes('animated')) {
+      agentGuide.push(`  ${i.guide_animated.padEnd(28)} →  "/animated build <video>"`);
+    }
+
+    if (selectedPacks.includes('shield')) {
+      agentGuide.push(`  ${(i.guide_shield || '🛡️ GRC Compliance').padEnd(28)} →  "Shield, audit my SaaS for GDPR"`);
+    }
+
+    if (selectedPacks.includes('memory')) {
+      agentGuide.push(`  ${(i.guide_memory || '🧠 Memory Brain').padEnd(28)} →  "Zecher, scan projects in [path]"`);
+    }
+
+    if (selectedPacks.includes('dev-studio')) {
+      agentGuide.push(`  ${(i.guide_dev_studio || '🏗️ Dev Studio').padEnd(28)} →  "Miriam, brainstorm my app idea"`);
+    }
+
+    agentGuide.push(
+      '',
+      i.guide_workflow,
+      '  1. Atlas (idea → brief → PRD)',
+      '  2. Forge (architecture → code)',
+      '  3. Sentinel (tests → review)',
+      '',
+      i.guide_or_auto,
+      '',
+      `${i.guide_output}: _bmad-output/discovery/ & _bmad-output/build/`,
+      '',
+      '─'.repeat(50),
+      '',
+      `📦 ${i.guide_cli_title || 'CLI Commands'}:`,
+      `  npx bmad-plus install    ${i.guide_cli_install || '— Install agents & skills'}`,
+      `  npx bmad-plus update     ${i.guide_cli_update || '— Update agents (keeps config)'}`,
+      `  npx bmad-plus doctor     ${i.guide_cli_doctor || '— Check installation health'}`,
+      `  npx bmad-plus uninstall  ${i.guide_cli_uninstall || '— Remove BMAD+ from project'}`,
+    );
+
+    // Add pack-specific examples
+    const examples = [];
+    if (selectedPacks.includes('seo')) {
+      examples.push(`  ${i.guide_example_seo || '🔍 SEO: "/seo audit https://example.com"'}`);
+    }
+    if (selectedPacks.includes('backup')) {
+      examples.push(`  ${i.guide_example_backup || '🗂️  Backup: "/backup create" → ZIP timestamped'}`);
+    }
+    if (selectedPacks.includes('animated')) {
+      examples.push(`  ${i.guide_example_animated || '🎬 Animated: "/animated build hero.mp4"'}`);
+    }
+    if (selectedPacks.includes('osint')) {
+      examples.push(`  ${i.guide_example_osint || '🔍 OSINT: "Shadow, investigate John Doe"'}`);
+    }
+    if (selectedPacks.includes('shield')) {
+      examples.push(
+        `  ${i.guide_example_shield_1 || '🛡️ GRC: "Shield, audit my app for GDPR compliance"'}`,
+        `  ${i.guide_example_shield_2 || '🛡️ GRC: "Shield, gap analysis ISO 27001 vs NIST CSF"'}`,
+        `  ${i.guide_example_shield_3 || '🛡️ GRC: "Shield, generate SOC 2 evidence checklist"'}`,
+      );
+    }
+    if (selectedPacks.includes('dev-studio')) {
+      examples.push(
+        `  ${i.guide_example_dev_studio_1 || '🏗️ Dev Studio: "Miriam, brainstorm a productivity app"'}`,
+        `  ${i.guide_example_dev_studio_2 || '🏗️ Dev Studio: "Bezalel, design the architecture"'}`,
+        `  ${i.guide_example_dev_studio_3 || '🏗️ Dev Studio: "Oholiab, implement story S1"'}`,
+      );
+    }
+    if (selectedPacks.includes('memory')) {
+      examples.push(
+        `  ${i.guide_example_memory_1 || '🧠 Memory: "Zecher, scan projects in D:\\travail\\DEV"'}`,
+        `  ${i.guide_example_memory_2 || '🧠 Memory: "Zecher, where were we?"'}`,
+        `  ${i.guide_example_memory_3 || '🧠 Memory: "Zecher, consolidate memory"'}`,
+      );
+    }
+
+    if (examples.length > 0) {
+      agentGuide.push(
+        '',
+        `💡 ${i.guide_examples_title || 'Quick Examples'}:`,
+        ...examples
+      );
+    }
+
+    agentGuide.push(
+      '',
+      '---',
+      i.guide_credits
+    );
+
+    clack.note(agentGuide.join('\n'), i.guide_title);
+
+    clack.outro(pc.green(i.guide_ready));
+  },
+  // Exported for functional testing (not part of the public API)
+  _internal: {
+    INSTALLER_MARKER,
+    GENERATOR_MARKER_FALLBACK,
+    resolveGeneratorMarker,
+    writeIDEConfigs,
+  },
+};
+
+
+// ── Helpers ──
+
+/**
+ * Write the IDE config files, never destroying one this installer does not own.
+ *
+ * An existing config falls into one of three classes, tested in this order:
+ *
+ *  1. GENERATOR-MANAGED (carries the adapter generator's marker) — SKIPPED, even
+ *     under --yes. Such a file is a pure function of registry.yaml +
+ *     tools/build/adapters.config.js, and the installer template is a strict
+ *     subset of it (no registry facts), so overwriting is a downgrade that also
+ *     breaks the `generate-adapters.js --check` drift gate. A .bak does not
+ *     rescue it: every tool reads the live path, not the backup. The repair is
+ *     regeneration, not merging — so install defers and points at the generator.
+ *  2. HAND-AUTHORED (no BMAD+ marker) — kept as-is interactively; backed up then
+ *     overwritten under --yes (NODE-02).
+ *  3. INSTALLER-GENERATED (carries INSTALLER_MARKER) — refreshed in place.
+ *
+ * @param {object} args
+ * @param {string} args.projectDir - Absolute path to the target project
+ * @param {string[]} args.detectedIDEs - IDE ids to configure (keys of IDE_CONFIGS)
+ * @param {string} args.configContent - Rendered config body to write
+ * @param {boolean} [args.yes] - Non-interactive mode (--yes)
+ * @returns {{written: string[], skipped: string[], backedUp: string[]}} config file names per outcome
+ */
+function writeIDEConfigs({ projectDir, detectedIDEs, configContent, yes }) {
+  const generatorMarker = resolveGeneratorMarker();
+  // Several IDEs share one file (gemini-cli + antigravity → GEMINI.md): dedupe
+  // outcomes by file name so a shared file is reported — and warned about — once.
+  const outcome = { written: new Set(), skipped: new Set(), backedUp: new Set() };
+
+  for (const ideId of detectedIDEs) {
+    const ide = IDE_CONFIGS[ideId];
+    if (!ide) continue;
+
+    const configPath = path.join(projectDir, ide.configFile);
+
+    if (fs.existsSync(configPath)) {
+      const existing = fs.readFileSync(configPath, 'utf8');
+
+      // PROD-01: the adapter generator owns this file — defer to it.
+      if (existing.includes(generatorMarker)) {
+        if (!outcome.skipped.has(ide.configFile)) {
+          clack.log.warn(
+            `⚠️  ${ide.configFile} is generated by tools/build/generate-adapters.js — left untouched. ` +
+              `Run \`node tools/build/generate-adapters.js --adopt\` to refresh it from registry.yaml.`
+          );
+        }
+        outcome.skipped.add(ide.configFile);
+        continue;
+      }
+
+      // NODE-02: never clobber a hand-authored config without protecting it.
+      if (!existing.includes(INSTALLER_MARKER)) {
+        if (!yes) {
+          // Interactive: keep the user's file untouched.
+          if (!outcome.skipped.has(ide.configFile)) {
+            clack.log.warn(`⚠️  ${ide.configFile} already exists and was not created by BMAD+ — kept your file (skipped). Re-run with --yes to back it up and overwrite.`);
+          }
+          outcome.skipped.add(ide.configFile);
+          continue;
+        }
+        // Non-interactive: back up before overwriting, never destroy data.
+        if (!outcome.backedUp.has(ide.configFile)) {
+          let backupPath = `${configPath}.bak`;
+          if (fs.existsSync(backupPath)) backupPath = `${configPath}.${Date.now()}.bak`;
+          fs.copyFileSync(configPath, backupPath);
+          clack.log.warn(`⚠️  Backed up existing ${ide.configFile} → ${path.basename(backupPath)}`);
+          outcome.backedUp.add(ide.configFile);
+        }
+      }
+    }
+
+    fs.writeFileSync(configPath, configContent, 'utf8');
+    outcome.written.add(ide.configFile);
+  }
+
+  return {
+    written: [...outcome.written],
+    skipped: [...outcome.skipped],
+    backedUp: [...outcome.backedUp],
+  };
+}
+
+function generateConfigYaml(userName, language, projectDir) {
+  const projectName = path.basename(projectDir);
+  return `# BMAD+ Project Configuration
+# Generated by bmad-plus install
+
+user_name: "${userName}"
+communication_language: "${language}"
+document_output_language: "${language}"
+output_folder: "_bmad-output"
+project_name: "${projectName}"
+
+# Execution settings
+execution_mode: "manual"
+auto_role_activation: true
+parallel_execution: true
+`;
+}