agentvibes 3.5.9 → 4.0.0

package/src/installer.js

@@ -45,9 +45,12 @@ import { program } from 'commander';
 import path from 'node:path';
 import fs from 'node:fs/promises';
 import fsSync from 'node:fs';
-import { execSync, execFileSync, spawn } from 'node:child_process';
+import { execSync, execFileSync, spawn, spawnSync } from 'node:child_process';
+import os from 'node:os';
+import crypto from 'node:crypto';
 import chalk from 'chalk';
 import inquirer from 'inquirer';
+import search from '@inquirer/search';
 import figlet from 'figlet';
 import { detectBMAD } from './bmad-detector.js';
 import boxen from 'boxen';
@@ -67,6 +70,8 @@ import {
   getProviderDisplayName,
   attemptProviderInstallation,
 } from './utils/provider-validator.js';
+import { promptForCustomMusic } from './installer/music-file-input.js';
+import { createPreviewListPrompt } from './utils/preview-list-prompt.js';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
@@ -77,6 +82,31 @@ const packageJson = JSON.parse(
 );
 const VERSION = packageJson.version;
 
+// Personality emoji mapping for quick visual recognition
+const personalityEmojis = {
+  'angry': '😠',
+  'annoying': '😤',
+  'crass': '🤬',
+  'dramatic': '🎭',
+  'dry-humor': '😐',
+  'flirty': '😘',
+  'funny': '😂',
+  'grandpa': '👴',
+  'millennial': '🙄',
+  'moody': '😒',
+  'none': '😊',
+  'normal': '😊',
+  'pirate': '🏴‍☠️',
+  'poetic': '📜',
+  'professional': '👔',
+  'rapper': '🎤',
+  'robot': '🤖',
+  'sarcastic': '😏',
+  'sassy': '💁',
+  'surfer-dude': '🏄',
+  'zen': '🧘'
+};
+
 // Validate Node.js executable is available (CLAUDE.md - early validation)
 if (!process.execPath) {
   console.error('❌ Error: Node.js executable path not found');
@@ -122,15 +152,244 @@ function hasPulseAudioTunnel() {
          process.env.PULSE_SERVER.toLowerCase().startsWith('tcp:');
 }
 
+/**
+ * Story 2.3: Detect terminal emoji support
+ * Checks $TERM, locale, and platform to determine emoji capability
+ * @returns {boolean} True if terminal supports emoji
+ */
+function supportsEmoji() {
+  // Check TERM environment variable
+  const term = process.env.TERM || '';
+  const lang = process.env.LANG || '';
+  const lcAll = process.env.LC_ALL || '';
+
+  // Explicitly unsupported terminals
+  const unsupportedTerminals = ['dumb', 'emacs', 'ansi'];
+  if (unsupportedTerminals.includes(term.toLowerCase())) {
+    return false;
+  }
+
+  // Check for UTF-8 locale (required for emoji)
+  const isUtf8 = lang.includes('utf8') || lang.includes('UTF-8') ||
+                 lcAll.includes('utf8') || lcAll.includes('UTF-8');
+
+  // Modern terminals (check common ones)
+  const modernTerminals = [
+    'xterm-256color', 'screen-256color', 'tmux-256color',
+    'iterm2', 'iterm', 'vscode', 'alacritty', 'kitty',
+    'wezterm', 'windows-terminal', 'conemu'
+  ];
+
+  const isModernTerminal = modernTerminals.some(t => term.toLowerCase().includes(t));
+
+  // Windows Terminal always supports emoji
+  const isWindowsTerminal = process.platform === 'win32' &&
+                            (process.env.WT_SESSION || process.env.WT_PROFILE_ID);
+
+  // macOS Terminal and iTerm2
+  const isMacOS = process.platform === 'darwin';
+
+  // Linux with proper UTF-8
+  const isLinuxWithUtf8 = process.platform === 'linux' && isUtf8;
+
+  // Unknown terminal with UTF-8: Only enable emoji if TERM is not explicitly unsupported AND has UTF-8
+  // This prevents false positives like "vt100" with UTF-8 reporting emoji support
+  const unknownTerminalWithUtf8 = term &&
+                                 !unsupportedTerminals.includes(term.toLowerCase()) &&
+                                 isUtf8;
+
+  // Default to true for: modern terms, Windows Terminal, macOS, Linux with UTF-8, or unknown term with UTF-8
+  // Default to false for: dumb/emacs/ansi terminals or environments without UTF-8
+  return isModernTerminal || isWindowsTerminal || isMacOS || isLinuxWithUtf8 || unknownTerminalWithUtf8;
+}
+
+/**
+ * Story 2.4: Get personality display with emoji or text fallback
+ * Returns emoji if supported, otherwise returns text label like "[personality]"
+ * @param {string} personality - Personality name
+ * @param {boolean} emojiSupported - Pre-computed emoji support (avoids redundant env var reads)
+ * @returns {string} Either emoji or "[personality-name]" fallback
+ */
+function getPersonalityIcon(personality, emojiSupported) {
+  const emoji = personalityEmojis[personality] || '✨';
+
+  // Use provided emojiSupported to avoid recalculating for every personality (performance)
+  if (emojiSupported) {
+    return emoji;
+  }
+
+  // Text fallback for unsupported terminals: [personality-name]
+  return `[${personality}]`;
+}
+
+/**
+ * Check if Piper TTS is installed
+ * @returns {boolean} True if piper command exists
+ */
+function isPiperInstalled() {
+  try {
+    execSync('which piper', {
+      stdio: 'pipe',
+      timeout: 3000
+    });
+    return true;
+  } catch (e) {
+    return false;
+  }
+}
+
+/**
+ * Check if Soprano TTS is installed
+ * @returns {boolean} True if soprano-tts or soprano-webui command exists
+ */
+function isSopranoInstalled() {
+  try {
+    execSync('which soprano-tts || which soprano-webui', {
+      stdio: 'pipe',
+      timeout: 3000
+    });
+    return true;
+  } catch (e) {
+    return false;
+  }
+}
+
+/**
+ * Play voice sample for preview during voice selection
+ * @param {string} voiceName - Name of the voice (e.g., 'en_US-lessac-medium', 'soprano-default')
+ * @param {string} provider - TTS provider ('piper' or 'soprano')
+ * @returns {Promise<boolean>} True if sample played successfully
+ */
+async function playVoiceSample(voiceName, provider) {
+  try {
+    const samplesDir = path.join(__dirname, '..', '.claude', 'audio', 'voice-samples', provider);
+
+    // Try friendly name first (e.g., "ryan.wav")
+    let sampleFile = path.join(samplesDir, `${voiceName}.wav`);
+
+    // If not found and looks like a Piper ID, try that too
+    if (!fsSync.existsSync(sampleFile) && voiceName.includes('-')) {
+      sampleFile = path.join(samplesDir, `${voiceName}.wav`);
+    }
+
+    // Check if pre-recorded sample exists
+    if (fsSync.existsSync(sampleFile)) {
+      console.log(chalk.cyan('  🔊 Playing voice sample...'));
+
+      // Play using sox/aplay - use spawn for non-blocking playback
+      try {
+        // Play using aplay directly (no shell interpolation — prevents command injection)
+        const player = spawn('aplay', [sampleFile], {
+          detached: false,
+          stdio: 'ignore'
+        });
+
+        // Return the process so it can be killed
+        return player;
+      } catch (e) {
+        // Fallback: generate on-the-fly if provider is available
+      }
+    }
+
+    // Generate sample on-the-fly if provider is running
+    if (provider === 'piper' && isPiperInstalled()) {
+      const text = `Hi, I'm ${voiceName.split('-')[1] || 'Piper'}`;
+      // Use bash -c with positional args to prevent command injection via text/voiceName
+      spawnSync('bash', ['-c', 'echo "$1" | piper --model "$2" --output_raw | aplay -r 22050 -f S16_LE -t raw -', '_', text, voiceName], {
+        stdio: 'inherit',
+        timeout: 15000
+      });
+      return true;
+    } else if (provider === 'soprano' && await isSopranoRunning()) {
+      // Generate via Soprano API
+      const text = "Hi, I'm Soprano";
+      const response = await fetch('http://localhost:7860/api/tts', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ text, voice: 'soprano-default' }),
+        signal: AbortSignal.timeout(5000)
+      });
+
+      if (response.ok) {
+        const audio = await response.arrayBuffer();
+        // Save temporarily and play
+        const tempFile = path.join(os.tmpdir(), `soprano-sample-${crypto.randomBytes(8).toString('hex')}.wav`);
+        fsSync.writeFileSync(tempFile, Buffer.from(audio));
+        try {
+          // Use spawnSync with argument array to prevent command injection
+          spawnSync('aplay', [tempFile], { stdio: 'pipe', timeout: 5000 });
+        } finally {
+          fsSync.unlinkSync(tempFile);
+        }
+        return true;
+      }
+    }
+
+    return false;
+  } catch (e) {
+    console.log(chalk.gray('  (Preview not available)'));
+    return false;
+  }
+}
+
+/**
+ * Check if Soprano server is running on port 7860
+ * @returns {Promise<boolean>} True if server responds to health check
+ */
+async function isSopranoRunning() {
+  try {
+    const response = await fetch('http://localhost:7860/health', {
+      signal: AbortSignal.timeout(2000)
+    });
+    return response.ok;
+  } catch (e) {
+    return false;
+  }
+}
+
+/**
+ * Start Soprano TTS server in background
+ * @returns {Promise<boolean>} True if successfully started
+ */
+async function startSopranoServer() {
+  try {
+    console.log(chalk.gray('🚀 Starting Soprano TTS server...'));
+
+    // Start soprano-webui in background
+    const sopranoProcess = spawn('soprano-webui', ['--port', '7860'], {
+      detached: true,
+      stdio: 'ignore'
+    });
+
+    sopranoProcess.unref(); // Allow parent to exit independently
+
+    // Wait up to 10 seconds for server to be ready
+    for (let i = 0; i < 20; i++) {
+      await new Promise(resolve => setTimeout(resolve, 500));
+      if (await isSopranoRunning()) {
+        console.log(chalk.green('✓ Soprano TTS server started successfully\n'));
+        return true;
+      }
+    }
+
+    console.log(chalk.yellow('⚠️  Soprano server started but not responding yet\n'));
+    return false;
+  } catch (e) {
+    console.log(chalk.yellow('⚠️  Failed to start Soprano server:', e.message, '\n'));
+    return false;
+  }
+}
+
 /**
  * Detect system capabilities for smart provider recommendations
- * @returns {Promise<Object>} System info including GPU, memory, platform
+ * @returns {Promise<Object>} System info including GPU, memory, platform, Soprano availability
  */
 async function detectSystemCapabilities() {
   const isMacOS = process.platform === 'darwin';
   const isAndroid = isTermux();
   let hasGPU = false;
   let totalRAM = 0;
+  let sopranoAvailable = false;
 
   try {
     // Detect NVIDIA GPU
@@ -183,12 +442,24 @@ async function detectSystemCapabilities() {
     totalRAM = 4096;
   }
 
+  // Detect and auto-start Soprano if installed
+  if (isSopranoInstalled()) {
+    const isRunning = await isSopranoRunning();
+    if (isRunning) {
+      sopranoAvailable = true;
+    } else {
+      // Soprano installed but not running - try to start it
+      sopranoAvailable = await startSopranoServer();
+    }
+  }
+
   return {
     hasGPU,
     lowMemory: totalRAM < 4096,
     totalRAM,
     isMacOS,
-    isAndroid
+    isAndroid,
+    sopranoAvailable
   };
 }
 
@@ -397,7 +668,8 @@ async function showPaginatedContent(pages, options = {}) {
     const { action } = await inquirer.prompt([{
       type: 'list',
       name: 'action',
-      message: '', // Hide the "Use arrow keys" message
+      message: chalk.cyan('💡 Try these AgentVibes commands in Claude Code terminal'),
+      prefix: '',
       choices,
       default: currentPage < pages.length - 1 ? 'next' : 'continue'
     }]);
@@ -425,11 +697,12 @@ async function showPaginatedContent(pages, options = {}) {
 function getPageTitle(pageNum) {
   const titles = {
     0: '🔧 System Dependencies',
-    1: '🎙️ TTS Provider Configuration',
+    1: '🔌 TTS Provider Configuration',
     2: '🎤 Voice Selection',
     3: '😎 Personality Selection',
-    4: '💧 Audio Settings',
-    5: '🔊 Verbosity Settings'
+    4: '🎛️ Reverb Settings',
+    5: '🎵 Background Music',
+    6: '🔊 Verbosity Settings'
   };
   return titles[pageNum] || 'Configuration';
 }
@@ -442,8 +715,8 @@ async function handleSystemDependenciesPage() {
   const { checkDependencies, getInstallCommands } = await import('./utils/dependency-checker.js');
   const depResults = checkDependencies();
 
-  let depContent = chalk.gray('System dependencies are tools AgentVibes needs to function properly.\n');
-  depContent += chalk.gray('Required tools must be installed, optional tools enable extra features.\n\n');
+  let depContent = chalk.gray('System dependencies detected and already installed.\n');
+  depContent += chalk.gray('These tools enable AgentVibes features and functionality.\n\n');
 
   // Satisfied dependencies
   if (depResults.core.node?.isCompatible) {
@@ -477,6 +750,39 @@ async function handleSystemDependenciesPage() {
     depContent += chalk.green('✓ audio player (paplay/aplay/mpv)\n');
   }
 
+  // Check TTS providers
+  const piperInstalled = isPiperInstalled();
+  const sopranoInstalled = isSopranoInstalled();
+
+  if (piperInstalled || sopranoInstalled) {
+    depContent += '\n' + chalk.gray('─'.repeat(50)) + '\n\n';
+    depContent += chalk.cyan.bold('TTS Providers Already Installed:\n\n');
+
+    if (piperInstalled) {
+      try {
+        const piperPath = execSync('which piper 2>/dev/null', { encoding: 'utf8' }).trim();
+        depContent += chalk.green('✓ Piper TTS (offline voice synthesis)\n');
+        depContent += chalk.gray(`  ${piperPath}\n`);
+      } catch (e) {
+        depContent += chalk.green('✓ Piper TTS (offline voice synthesis)\n');
+      }
+    }
+    if (sopranoInstalled) {
+      try {
+        let sopranoPath = '';
+        try {
+          sopranoPath = execSync('which soprano-tts 2>/dev/null', { encoding: 'utf8' }).trim();
+        } catch (e) {
+          sopranoPath = execSync('which soprano-webui 2>/dev/null', { encoding: 'utf8' }).trim();
+        }
+        depContent += chalk.green('✓ Soprano TTS (premium quality)\n');
+        depContent += chalk.gray(`  ${sopranoPath}\n`);
+      } catch (e) {
+        depContent += chalk.green('✓ Soprano TTS (premium quality)\n');
+      }
+    }
+  }
+
   // Missing dependencies
   if (Object.keys(depResults.missing).length > 0) {
     depContent += '\n' + chalk.gray('─'.repeat(50)) + '\n\n';
@@ -492,8 +798,7 @@ async function handleSystemDependenciesPage() {
 
     depContent += '\n' + chalk.gray('TTS will still work without optional tools');
 
-    // Add install commands
-    const os = await import('os');
+    // Add install commands (os imported at top level)
     const platform = os.platform();
     const installCmds = getInstallCommands(depResults.missing, platform);
 
@@ -517,6 +822,185 @@ async function handleSystemDependenciesPage() {
   });
 
   console.log(depsBoxen);
+
+  // Return status for navigation message
+  return {
+    allMet: Object.keys(depResults.missing).length === 0,
+    missingCount: Object.keys(depResults.missing).length
+  };
+}
+
+/**
+ * Validate and copy custom music track to .claude/audio/tracks directory
+ * @param {string} userFilePath - Path provided by user
+ * @param {string} tracksDir - Target directory for audio tracks
+ * @returns {Promise<string|null>} Filename if successful, null if cancelled
+ */
+async function handleCustomMusicTrack(userFilePath, tracksDir) {
+  try {
+    // Validate file exists and resolve path securely
+    const resolvedPath = path.resolve(userFilePath.trim());
+
+    if (!fsSync.existsSync(resolvedPath)) {
+      console.error(chalk.red('✗ File not found. Please check the path.'));
+      return null;
+    }
+
+    // Validate file extension (whitelist approach per CLAUDE.md)
+    const ext = path.extname(resolvedPath).toLowerCase();
+    const supportedFormats = ['.mp3', '.wav', '.ogg', '.m4a'];
+    if (!supportedFormats.includes(ext)) {
+      console.error(chalk.red('✗ Unsupported format. Use: .mp3, .wav, .ogg, or .m4a'));
+      return null;
+    }
+
+    // Verify file is within expected directory (prevent path traversal)
+    if (!resolvedPath.startsWith(path.resolve(os.homedir()))) {
+      console.error(chalk.red('✗ File must be in your home directory or subdirectories.'));
+      return null;
+    }
+
+    // Get original filename and sanitize it
+    let originalFilename = path.basename(resolvedPath);
+    const sanitizedFilename = originalFilename.replace(/[^a-zA-Z0-9._-]/g, '_');
+
+    // Create tracks directory if needed
+    await fs.mkdir(tracksDir, { recursive: true });
+
+    // Copy file to tracks directory
+    const destPath = path.join(tracksDir, sanitizedFilename);
+    await fs.copyFile(resolvedPath, destPath);
+
+    return sanitizedFilename;
+  } catch (err) {
+    console.error(chalk.red(`✗ Error: ${err.message}`));
+    return null;
+  }
+}
+
+/**
+ * Load custom tracks from global registry
+ * @returns {Promise<Array>} Array of custom track objects {name, filename}
+ */
+async function loadCustomTracks() {
+  try {
+    const registryPath = path.join(process.env.HOME || process.env.USERPROFILE, '.agentvibes', 'custom-tracks.json');
+    if (fsSync.existsSync(registryPath)) {
+      const content = await fs.readFile(registryPath, 'utf-8');
+      return JSON.parse(content);
+    }
+  } catch (err) {
+    // Silently fail - registry may not exist yet
+  }
+  return [];
+}
+
+/**
+ * Save custom tracks to global registry
+ * @param {Array} tracks - Array of custom track objects
+ */
+async function saveCustomTracks(tracks) {
+  try {
+    const registryDir = path.join(process.env.HOME || process.env.USERPROFILE, '.agentvibes');
+    await fs.mkdir(registryDir, { recursive: true });
+    const registryPath = path.join(registryDir, 'custom-tracks.json');
+    await fs.writeFile(registryPath, JSON.stringify(tracks, null, 2));
+  } catch (err) {
+    // Silently fail - non-critical
+  }
+}
+
+// Track currently playing audio preview to prevent overlaps
+let currentAudioPreview = null;
+
+/**
+ * Preview audio track using available audio player
+ * @param {string} trackName - Name of the track file to preview
+ * @param {string} tracksDir - Directory containing audio tracks
+ * @returns {Promise<boolean>} True if preview was attempted, false if no audio tools available
+ */
+async function previewAudioTrack(trackName, tracksDir) {
+  // Stop any currently playing preview
+  if (currentAudioPreview && !currentAudioPreview.killed) {
+    currentAudioPreview.kill('SIGTERM');
+    currentAudioPreview = null;
+  }
+
+  const trackPath = path.join(tracksDir, trackName);
+
+  // Verify track exists
+  if (!fsSync.existsSync(trackPath)) {
+    console.log(chalk.yellow('⚠️  Track file not found'));
+    return false;
+  }
+
+  // Try available audio players in order of preference
+  const audioPlayers = ['ffplay', 'play', 'mpv'];
+  let playerAvailable = false;
+
+  for (const player of audioPlayers) {
+    try {
+      execSync(`which ${player}`, { stdio: 'ignore' });
+      playerAvailable = true;
+
+      console.log(chalk.cyan('▶  Playing preview (10 seconds)...'));
+
+      // Build appropriate command for each player
+      let playerArgs = [];
+      if (player === 'ffplay') {
+        playerArgs = ['-nodisp', '-autoexit', '-t', '10', '-volume', '30', trackPath];
+      } else if (player === 'play') {
+        playerArgs = [trackPath, 'trim', '0', '10'];
+      } else if (player === 'mpv') {
+        playerArgs = ['--no-video', '--duration=10', '--volume=30', trackPath];
+      }
+
+      // Spawn player process (manual setTimeout below handles the safety kill)
+      const audioProcess = spawn(player, playerArgs, {
+        stdio: ['ignore', 'ignore', 'ignore']
+      });
+
+      // Store reference to current preview
+      currentAudioPreview = audioProcess;
+
+      // Handle process completion
+      return new Promise((resolve) => {
+        const timeoutHandle = setTimeout(() => {
+          if (audioProcess && !audioProcess.killed) {
+            audioProcess.kill('SIGTERM');
+          }
+          if (currentAudioPreview === audioProcess) {
+            currentAudioPreview = null;
+          }
+          resolve(true);
+        }, 11000); // 11 second timeout
+
+        audioProcess.on('close', () => {
+          clearTimeout(timeoutHandle);
+          if (currentAudioPreview === audioProcess) {
+            currentAudioPreview = null;
+          }
+          resolve(true);
+        });
+
+        audioProcess.on('error', () => {
+          clearTimeout(timeoutHandle);
+          if (currentAudioPreview === audioProcess) {
+            currentAudioPreview = null;
+          }
+          resolve(true);
+        });
+      });
+    } catch (err) {
+      // This player not available, try next
+      continue;
+    }
+  }
+
+  if (!playerAvailable) {
+    console.log(chalk.yellow('⚠️  Audio preview requires ffplay, sox (play), or mpv'));
+  }
+  return false;
 }
 
 /**
@@ -530,6 +1014,7 @@ async function collectConfiguration(options = {}) {
     piperPath: null,
     sshHost: null,
     defaultVoice: null,
+    pretext: '',
     personality: 'none',
     reverb: 'light',
     backgroundMusic: {
@@ -539,6 +1024,22 @@ async function collectConfiguration(options = {}) {
     verbosity: 'high'
   };
 
+  // Load existing pretext from file if it exists (Story 1.2: File Persistence)
+  const homeDir = process.env.HOME || process.env.USERPROFILE;
+  const claudeDir = path.join(homeDir, '.claude');
+  const pretextFile = path.join(claudeDir, 'config', 'tts-pretext.txt');
+  try {
+    if (fsSync.existsSync(pretextFile)) {
+      const existingPretext = fsSync.readFileSync(pretextFile, 'utf-8').trim();
+      if (existingPretext) {
+        config.pretext = existingPretext;
+      }
+    }
+  } catch (err) {
+    // Gracefully handle read errors (file permissions, encoding issues, etc.)
+    // Pretext will remain empty string if file can't be read
+  }
+
   // Detect environment type
   const environment = detectEnvironment();
   const isAndroid = isTermux();
@@ -573,7 +1074,7 @@ async function collectConfiguration(options = {}) {
   }
 
   let currentPage = 0;
-  const sectionPages = 6; // System Dependencies, Provider, Voice Selection, Personality Selection, Audio Settings, Verbosity
+  const sectionPages = 7; // System Dependencies, Provider, Voice Selection, Personality Selection, Reverb, Background Music, Verbosity
   const pageOffset = options.pageOffset || 0;
   const totalPages = options.totalPages || sectionPages;
 
@@ -593,8 +1094,10 @@ async function collectConfiguration(options = {}) {
     const { header, footer } = createPageHeaderFooter(pageTitle, currentPage, totalPages, pageOffset);
     console.log(header);
 
+    let pageStatus = null; // Track page completion status for navigation message
+
     if (currentPage === 0) {
-      await handleSystemDependenciesPage();
+      pageStatus = await handleSystemDependenciesPage();
     } else if (currentPage === 1) {
       // Page 2: TTS Provider & Voice Storage
 
@@ -880,6 +1383,57 @@ async function collectConfiguration(options = {}) {
 
         // Validate provider installation before accepting selection
         console.log(chalk.gray(`\n   Checking for ${getProviderDisplayName(provider)}...`));
+
+        // Special handling for Soprano - check if running, auto-start if installed
+        if (provider === 'soprano') {
+          const sopranoInstalled = isSopranoInstalled();
+          const sopranoRunning = await isSopranoRunning();
+
+          if (sopranoInstalled && !sopranoRunning) {
+            // Soprano installed but not running - offer to start it
+            console.log(chalk.yellow('\n⚠️  Soprano TTS is installed but server is not running'));
+
+            const { startAction } = await inquirer.prompt([{
+              type: 'list',
+              name: 'startAction',
+              message: 'What would you like to do?',
+              choices: [
+                { name: chalk.green('Start Soprano server now (recommended)'), value: 'start' },
+                { name: 'I\'ll start it myself', value: 'manual' },
+                { name: 'Choose a different provider', value: 'back' }
+              ]
+            }]);
+
+            if (startAction === 'start') {
+              const started = await startSopranoServer();
+              if (started) {
+                config.provider = provider;
+                providerSelected = true;
+                continue;
+              } else {
+                console.log(chalk.yellow('\n⚠️  Failed to start Soprano automatically'));
+                console.log(chalk.cyan('   Try starting manually:'));
+                console.log(chalk.gray('   $ soprano-webui --port 7860\n'));
+                continue;
+              }
+            } else if (startAction === 'manual') {
+              console.log(chalk.cyan('\n📝 To start Soprano manually, run:'));
+              console.log(chalk.gray('   $ soprano-webui --port 7860\n'));
+              continue;
+            } else {
+              // User chose to go back
+              continue;
+            }
+          } else if (sopranoInstalled && sopranoRunning) {
+            // Soprano installed and running - all good!
+            console.log(chalk.green('\n✓ Soprano TTS detected and running!\n'));
+            config.provider = provider;
+            providerSelected = true;
+            continue;
+          }
+          // If not installed, fall through to normal validation below
+        }
+
         const validation = await validateProvider(provider);
 
         if (!validation.installed) {
@@ -956,6 +1510,9 @@ async function collectConfiguration(options = {}) {
           console.log(chalk.green(`\n✓ ${displayName} Detected and selected!\n`));
           config.provider = provider;
           providerSelected = true; // Exit provider selection loop
+
+          // Auto-advance flag for navigation
+          config._autoAdvance = true;
         }
       }
 
@@ -1148,36 +1705,105 @@ async function collectConfiguration(options = {}) {
       ));
 
       if (config.provider === 'piper') {
-        // Piper voices - popular selections
-        const piperVoices = [
-          { name: chalk.cyan('en_US-ryan-high') + chalk.gray(' (Male, American, High Quality)'), value: 'en_US-ryan-high' },
-          { name: chalk.magenta('en_US-amy-medium') + chalk.gray(' (Female, American, Clear)'), value: 'en_US-amy-medium' },
-          { name: chalk.cyan('en_US-joe-medium') + chalk.gray(' (Male, American, Warm)'), value: 'en_US-joe-medium' },
-          { name: chalk.magenta('en_US-lessac-medium') + chalk.gray(' (Female, American, Professional)'), value: 'en_US-lessac-medium' },
-          { name: chalk.cyan('en_GB-alan-medium') + chalk.gray(' (Male, British, Refined)'), value: 'en_GB-alan-medium' },
-          { name: chalk.magenta('en_GB-southern_english_female-medium') + chalk.gray(' (Female, British)'), value: 'en_GB-southern_english_female-medium' },
+        // Check if Piper is installed for voice previews
+        const piperAvailable = isPiperInstalled();
+
+        // Load voice metadata for friendly names
+        let voiceMetadata;
+        try {
+          const metadataPath = path.join(__dirname, '..', '.agentvibes', 'config', 'voice-metadata.json');
+          voiceMetadata = JSON.parse(await fs.readFile(metadataPath, 'utf-8'));
+        } catch (e) {
+          voiceMetadata = null;
+        }
+
+        // Build voice choices
+        const previewHint = piperAvailable ? ' ' + chalk.gray('[SPACE to preview]') : '';
+        let piperVoices;
+
+        if (voiceMetadata && voiceMetadata.installerVoices) {
+          // Use voice metadata system - all 10 voices with friendly names
+          piperVoices = voiceMetadata.installerVoices.map(friendlyName => {
+            const voice = voiceMetadata.voices[friendlyName];
+            const isMale = voice.gender === 'male';
+            const color = isMale ? chalk.cyan : chalk.hex('#FF69B4'); // Lighter pink for females
+
+            return {
+              name: color(voice.displayName) + chalk.gray(` (${voice.gender}, ${voice.accent}, ${voice.quality})`) + previewHint,
+              value: friendlyName  // Store friendly name
+            };
+          });
+        } else {
+          // Fallback to old hardcoded list
+          piperVoices = [
+            { name: chalk.cyan('en_US-ryan-high') + chalk.gray(' (Male, American, High Quality)') + previewHint, value: 'en_US-ryan-high' },
+            { name: chalk.magenta('en_US-amy-medium') + chalk.gray(' (Female, American, Clear)') + previewHint, value: 'en_US-amy-medium' },
+            { name: chalk.cyan('en_US-joe-medium') + chalk.gray(' (Male, American, Warm)') + previewHint, value: 'en_US-joe-medium' },
+            { name: chalk.magenta('en_US-lessac-medium') + chalk.gray(' (Female, American, Professional)') + previewHint, value: 'en_US-lessac-medium' },
+            { name: chalk.cyan('en_GB-alan-medium') + chalk.gray(' (Male, British, Refined)') + previewHint, value: 'en_GB-alan-medium' },
+            { name: chalk.magenta('en_GB-southern_english_female-medium') + chalk.gray(' (Female, British)') + previewHint, value: 'en_GB-southern_english_female-medium' }
+          ];
+        }
+
+        piperVoices.push(
           new inquirer.Separator(),
           { name: chalk.yellow('Skip - I\'ll set this later'), value: '__skip__' },
           { name: chalk.magentaBright('← Back to Provider Selection'), value: '__back__' }
-        ];
+        );
 
-        const { selectedVoice } = await inquirer.prompt([{
-          type: 'list',
-          name: 'selectedVoice',
-          message: chalk.yellow('Select your default Piper voice:'),
-          choices: piperVoices,
-          default: 'en_US-ryan-high',
-          pageSize: 12
-        }]);
+        let selectedVoice;
+        if (piperAvailable) {
+          const result = await createPreviewListPrompt(inquirer, {
+            name: 'selectedVoice',
+            message: chalk.yellow('Select your default Piper voice:'),
+            choices: piperVoices,
+            default: 'en_US-ryan-high',
+            pageSize: 12,
+            onPreview: async (voiceName) => {
+              await playVoiceSample(voiceName, 'piper');
+            }
+          });
+          selectedVoice = result.selectedVoice;
+        } else {
+          const result = await inquirer.prompt([{
+            type: 'list',
+            name: 'selectedVoice',
+            message: chalk.yellow('Select your default Piper voice:'),
+            choices: piperVoices,
+            default: 'en_US-ryan-high',
+            pageSize: 12
+          }]);
+          selectedVoice = result.selectedVoice;
+        }
 
         if (selectedVoice === '__back__') {
           return null;
         }
 
         if (selectedVoice !== '__skip__') {
-          config.defaultVoice = selectedVoice;
+          // Convert friendly name to Piper ID if using metadata
+          if (voiceMetadata && voiceMetadata.voices[selectedVoice]) {
+            config.defaultVoice = voiceMetadata.voices[selectedVoice].id;
+            console.log(chalk.green(`\n✓ Voice selected: ${voiceMetadata.voices[selectedVoice].displayName} (${config.defaultVoice})\n`));
+          } else {
+            config.defaultVoice = selectedVoice;
+            console.log(chalk.green(`\n✓ Voice selected: ${selectedVoice}\n`));
+          }
+
+          // Show hint about voice browser
+          console.log(boxen(
+            chalk.cyan('💡 Want to explore 914+ voices?\n\n') +
+            chalk.white('Run: ') + chalk.yellow('npx agentvibes-voice-browser') + chalk.gray('\n\nBrowse all LibriTTS voices with preview, search, and install.'),
+            {
+              padding: { top: 0, bottom: 0, left: 1, right: 1 },
+              margin: { top: 0, bottom: 1, left: 0, right: 0 },
+              borderStyle: 'round',
+              borderColor: 'cyan',
+              dimBorder: true
+            }
+          ));
+
           // Auto-advance to next page after selection
-          console.log(chalk.green(`\n✓ Voice selected: ${selectedVoice}\n`));
           currentPage++; // Skip to next page immediately
           continue; // Skip navigation and go to next iteration
         } else {
@@ -1215,9 +1841,24 @@ async function collectConfiguration(options = {}) {
         }
 
         if (selectedVoice !== '__skip__') {
+          // macOS voices use their name directly (no piper metadata conversion needed)
           config.defaultVoice = selectedVoice;
-          // Auto-advance to next page after selection
           console.log(chalk.green(`\n✓ Voice selected: ${selectedVoice}\n`));
+
+          // Show hint about voice browser
+          console.log(boxen(
+            chalk.cyan('💡 Want to explore 914+ voices?\n\n') +
+            chalk.white('Run: ') + chalk.yellow('npx agentvibes-voice-browser') + chalk.gray('\n\nBrowse all LibriTTS voices with preview, search, and install.'),
+            {
+              padding: { top: 0, bottom: 0, left: 1, right: 1 },
+              margin: { top: 0, bottom: 1, left: 0, right: 0 },
+              borderStyle: 'round',
+              borderColor: 'cyan',
+              dimBorder: true
+            }
+          ));
+
+          // Auto-advance to next page after selection
           currentPage++; // Skip to next page immediately
           continue; // Skip navigation and go to next iteration
         } else {
@@ -1314,7 +1955,69 @@ async function collectConfiguration(options = {}) {
       }
 
     } else if (currentPage === 3) {
-      // Page 4: Personality Selection
+      // Page 4: Pretext and Personality Selection
+      console.log(boxen(
+        chalk.white('Customize your Agent\'s introduction!\n\n') +
+        chalk.gray('Add optional intro text that prefixes all TTS messages.\n') +
+        chalk.gray('Examples: "FireBot: ", "Agent: ", "🤖 Assistant: "\n\n') +
+        chalk.gray('You can change this anytime with: ') + chalk.cyan('/agent-vibes:set-pretext <text>'),
+        {
+          padding: 1,
+          margin: { top: 0, bottom: 0, left: 0, right: 0 },
+          borderStyle: 'round',
+          borderColor: 'gray',
+          width: 80
+        }
+      ));
+
+      // Pretext input with validation
+      let pretextValid = false;
+      let pretext = config.pretext || '';
+
+      while (!pretextValid) {
+        const { pretextInput } = await inquirer.prompt([{
+          type: 'input',
+          name: 'pretextInput',
+          message: chalk.yellow('Enter intro text (optional, max 50 chars):'),
+          default: pretext,
+          // Live character count display in prompt
+          prefix: `${chalk.cyan('[Intro Text]')}`,
+          validate: (input) => {
+            // Trim first for consistent length checking
+            const trimmed = input.trim();
+            // Check for newlines
+            if (input.includes('\n') || input.includes('\r')) {
+              return chalk.red('Error: Newlines not allowed');
+            }
+            // Check length after trimming for consistency with display
+            if (trimmed.length > 50) {
+              return chalk.red(`Too long: ${trimmed.length}/50 characters`);
+            }
+            return true;
+          },
+          filter: (input) => {
+            // Trim and treat whitespace-only as empty
+            const trimmed = input.trim();
+            return trimmed;
+          }
+        }]);
+
+        pretext = pretextInput;
+
+        // Display preview
+        if (pretext) {
+          console.log(chalk.yellow(`\nCharacter count: ${pretext.length}/50`));
+          console.log(chalk.cyan(`Preview: "${pretext}" This is how it will sound\n`));
+          console.log(chalk.green(`✓ Intro text set: "${pretext}"\n`));
+        } else {
+          console.log(chalk.gray('→ No intro text (messages will speak normally)\n'));
+        }
+
+        config.pretext = pretext;
+        pretextValid = true;
+      }
+
+      // Page 5: Personality Selection
       console.log(boxen(
         chalk.white('Give your Agent a personality!\n\n') +
         chalk.gray('Personalities add character and style to TTS responses.\n') +
@@ -1334,6 +2037,9 @@ async function collectConfiguration(options = {}) {
       const personalitiesDir = path.join(__dirname, '..', '.claude', 'personalities');
       let personalityChoices = [];
 
+      // Story 2.3 & 2.4: Check emoji support once, pass to all personality icons (performance fix)
+      const emojiSupported = supportsEmoji();
+
       try {
         const personalityFiles = await fs.readdir(personalitiesDir);
         const personalities = [];
@@ -1359,16 +2065,18 @@ async function collectConfiguration(options = {}) {
         personalities.sort((a, b) => a.name.localeCompare(b.name));
 
         // Add "none" as first option (default)
+        const noneIcon = getPersonalityIcon('none', emojiSupported);
         personalityChoices.push(
-          { name: chalk.green('none') + chalk.gray(' (Professional, no personality) - Recommended'), value: 'none' },
+          { name: noneIcon + ' ' + chalk.green('none') + chalk.gray(' (Professional, no personality) - Recommended'), value: 'none' },
           new inquirer.Separator(chalk.gray('─'.repeat(60)))
         );
 
         // Add all other personalities
         for (const p of personalities) {
           if (p.name !== 'normal') { // Skip 'normal' as it's similar to 'none'
+            const icon = getPersonalityIcon(p.name, emojiSupported);
             personalityChoices.push({
-              name: chalk.cyan(p.name) + chalk.gray(` - ${p.description}`),
+              name: icon + ' ' + chalk.cyan(p.name) + chalk.gray(` - ${p.description}`),
               value: p.name
             });
           }
@@ -1387,14 +2095,28 @@ async function collectConfiguration(options = {}) {
         ];
       }
 
-      const { selectedPersonality } = await inquirer.prompt([{
-        type: 'list',
-        name: 'selectedPersonality',
-        message: chalk.yellow('Select your default personality:'),
-        choices: personalityChoices,
-        default: 'none',
+      // Story 2.3 & 2.4: Show emoji support status in help text (reuse emojiSupported from above)
+      const emojiNote = emojiSupported
+        ? chalk.gray('(Emoji icons shown for visual recognition)')
+        : chalk.gray('(Text labels shown - emoji not supported in this terminal)');
+
+      // Use search prompt for keyboard navigation (type to filter)
+      const selectedPersonality = await search({
+        message: chalk.yellow('Select your default personality (type to search):') + ' ' + emojiNote,
+        source: async (input) => {
+          // Filter personalityChoices based on input
+          if (!input) {
+            return personalityChoices;
+          }
+          return personalityChoices.filter(choice => {
+            // Check if choice is a Separator, if so skip it
+            if (!choice.value) return false;
+            return choice.value.toLowerCase().includes(input.toLowerCase()) ||
+                   (choice.name && choice.name.toLowerCase().includes(input.toLowerCase()));
+          });
+        },
         pageSize: 15
-      }]);
+      });
 
       if (selectedPersonality === '__back__') {
         currentPage--; // Go back to voice selection
@@ -1487,15 +2209,45 @@ async function collectConfiguration(options = {}) {
           { name: 'Light (Small room) - Recommended', value: 'light' },
           { name: 'Medium (Conference room)', value: 'medium' },
           { name: 'Heavy (Large hall)', value: 'heavy' },
-          { name: 'Cathedral (Epic space)', value: 'cathedral' }
+          { name: 'Cathedral (Epic space)', value: 'cathedral' },
+          new inquirer.Separator(),
+          { name: chalk.magentaBright('← Previous'), value: '__back__' }
         ],
         default: config.reverb || 'light'
       }]);
 
+      if (reverbLevel === '__back__') {
+        currentPage--;
+        continue;
+      }
+
       config.reverb = reverbLevel;
 
-      // Add spacing before next question
-      console.log('');
+      console.log(chalk.green('\n✓ Reverb level set\n'));
+      currentPage++;
+      continue;
+
+    } else if (currentPage === 5) {
+      // Page 6: Background Music Settings
+
+      // Skip for termux-ssh - background music doesn't work with SSH text-only TTS
+      if (config.provider === 'termux-ssh' || config.provider === 'ssh-pulseaudio') {
+        console.log(boxen(
+          chalk.white('SSH-Remote: Audio Effects Apply on Android\n\n') +
+          chalk.green('✅ Background music works:\n') +
+          chalk.gray('   • Music plays on Android device\n') +
+          chalk.gray('   • All settings configured below will apply\n\n') +
+          chalk.cyan('Configure background music below!'),
+          {
+            padding: 1,
+            margin: { top: 0, bottom: 0, left: 0, right: 0 },
+            borderStyle: 'round',
+            borderColor: 'green',
+            width: 80
+          }
+        ));
+        console.log('');
+      }
 
       // Background music
       console.log(chalk.gray('🎵 Background music plays ambient tracks during TTS for a more engaging experience.'));
@@ -1510,48 +2262,194 @@ async function collectConfiguration(options = {}) {
       config.backgroundMusic.enabled = enableMusic;
 
       if (enableMusic) {
+        // Check if an MP3-capable player is available; offer to install ffmpeg if not
+        const { execSync: _execSync } = await import('child_process');
+        const _mp3Players = ['ffplay', 'mpg123', 'mpv', 'cvlc'];
+        const _hasPlayer = _mp3Players.some(p => {
+          try { _execSync(`which ${p}`, { stdio: 'pipe' }); return true; } catch { return false; }
+        });
+        if (!_hasPlayer) {
+          console.log('');
+          console.log(chalk.yellow('⚠️  No MP3 player found — background music requires one.'));
+          console.log(chalk.gray('   ffmpeg is recommended (provides ffplay for MP3 playback).\n'));
+
+          const _osPlatform = process.platform;
+          let _installCmd;
+          if (_osPlatform === 'darwin') {
+            _installCmd = 'brew install ffmpeg';
+          } else {
+            // Prefer pkexec (GUI password dialog) when available — works in
+            // environments where sudo lacks a tty (e.g., AI assistant terminals).
+            // Fall back to sudo for headless/SSH setups.
+            let _hasPkexec = false;
+            try { _execSync('which pkexec', { stdio: 'pipe' }); _hasPkexec = true; } catch {}
+            _installCmd = _hasPkexec
+              ? 'pkexec apt-get install -y ffmpeg'
+              : 'sudo apt-get install -y ffmpeg';
+          }
+
+          if (!options.yes) {
+            const { installFfmpeg } = await inquirer.prompt([{
+              type: 'confirm',
+              name: 'installFfmpeg',
+              message: chalk.yellow(`Install ffmpeg now? (${_installCmd})`),
+              default: true,
+            }]);
+            if (installFfmpeg) {
+              try {
+                console.log(chalk.cyan(`\n📦 Running: ${_installCmd}\n`));
+                const { execSync: _exec } = await import('child_process');
+                _exec(_installCmd, { stdio: 'inherit', timeout: 120000 });
+                console.log(chalk.green('\n✅ ffmpeg installed successfully!\n'));
+              } catch {
+                console.log(chalk.yellow('\n⚠️  ffmpeg installation failed. You can install it manually:'));
+                console.log(chalk.cyan(`   ${_installCmd}\n`));
+              }
+            } else {
+              console.log(chalk.gray(`   Install later with: ${_installCmd}\n`));
+            }
+          }
+        }
+
+        // Check for sox — required to mix background music into TTS audio
+        let _hasSox = false;
+        try { _execSync('which sox', { stdio: 'pipe' }); _hasSox = true; } catch {}
+        if (!_hasSox) {
+          console.log('');
+          console.log(chalk.yellow('⚠️  sox not found — required to mix background music into voice audio.'));
+          console.log(chalk.gray('   Without sox, you\'ll hear voice only, no background music.\n'));
+
+          const _osPlatform2 = process.platform;
+          let _soxCmd;
+          if (_osPlatform2 === 'darwin') {
+            _soxCmd = 'brew install sox';
+          } else {
+            let _hasPkexec2 = false;
+            try { _execSync('which pkexec', { stdio: 'pipe' }); _hasPkexec2 = true; } catch {}
+            _soxCmd = _hasPkexec2
+              ? 'pkexec apt-get install -y sox libsox-fmt-mp3'
+              : 'sudo apt-get install -y sox libsox-fmt-mp3';
+          }
+
+          if (!options.yes) {
+            const { installSox } = await inquirer.prompt([{
+              type: 'confirm',
+              name: 'installSox',
+              message: chalk.yellow(`Install sox now? (${_soxCmd})`),
+              default: true,
+            }]);
+            if (installSox) {
+              try {
+                console.log(chalk.cyan(`\n📦 Running: ${_soxCmd}\n`));
+                _execSync(_soxCmd, { stdio: 'inherit', timeout: 120000 });
+                console.log(chalk.green('\n✅ sox installed successfully!\n'));
+              } catch {
+                console.log(chalk.yellow('\n⚠️  sox installation failed. You can install it manually:'));
+                console.log(chalk.cyan(`   ${_soxCmd}\n`));
+              }
+            } else {
+              console.log(chalk.gray(`   Install later with: ${_soxCmd}\n`));
+            }
+          }
+        }
+
         // Add spacing before track selection
         console.log('');
         console.log(chalk.gray('🎼 Choose your default background music genre (you can change this anytime).'));
 
+        // Load custom tracks from registry
+        const customTracks = await loadCustomTracks();
+        const customTrackChoices = customTracks.map(track => ({
+          name: `📁 ${track.name} ` + chalk.gray('[SPACE to preview]'),
+          value: track.filename
+        }));
+
         const trackChoices = [
-          { name: '🎻 Soft Flamenco (Spanish guitar)', value: 'agentvibes_soft_flamenco_loop.mp3' },
-          { name: '🎺 Bachata (Latin - Romantic guitar & bongos)', value: 'agent_vibes_bachata_v1_loop.mp3' },
-          { name: '💃 Salsa (Latin - Upbeat brass & percussion)', value: 'agent_vibes_salsa_v2_loop.mp3' },
-          { name: '🎸 Cumbia (Latin - Accordion & drums)', value: 'agent_vibes_cumbia_v1_loop.mp3' },
-          { name: '🌸 Bossa Nova (Brazilian jazz)', value: 'agent_vibes_bossa_nova_v2_loop.mp3' },
-          { name: '🏙️  Japanese City Pop (80s synth)', value: 'agent_vibes_japanese_city_pop_v1_loop.mp3' },
-          { name: '🌊 Chillwave (Electronic ambient)', value: 'agent_vibes_chillwave_v2_loop.mp3' },
-          { name: '🎹 Dreamy House (Electronic dance)', value: 'dreamy_house_loop.mp3' },
-          { name: '🌙 Dark Chill Step (Electronic bass)', value: 'agent_vibes_dark_chill_step_loop.mp3' },
-          { name: '🕉️  Goa Trance (Psychedelic electronic)', value: 'agent_vibes_goa_trance_v2_loop.mp3' },
-          { name: '🎼 Harpsichord (Baroque classical)', value: 'agent_vibes_harpsichord_v2_loop.mp3' },
-          { name: '🎻 Celtic Harp (Irish traditional)', value: 'agent_vibes_celtic_harp_v1_loop.mp3' },
-          { name: '🌺 Hawaiian Slack Key Guitar', value: 'agent_vibes_hawaiian_slack_key_guitar_v2_loop.mp3' },
-          { name: '🏜️  Arabic Oud (Middle Eastern)', value: 'agent_vibes_arabic_v2_loop.mp3' },
-          { name: '🪘 Gnawa Ambient (North African)', value: 'agent_vibes_ganawa_ambient_v2_loop.mp3' },
-          { name: '🥁 Tabla Dream Pop (Indian percussion)', value: 'agent_vibes_tabla_dream_pop_v1_loop.mp3' }
+          { name: '🎻 Soft Flamenco (Spanish guitar) ' + chalk.gray('[SPACE to preview]'), value: 'agentvibes_soft_flamenco_loop.mp3' },
+          { name: '🎺 Bachata (Latin - Romantic guitar & bongos) ' + chalk.gray('[SPACE to preview]'), value: 'agent_vibes_bachata_v1_loop.mp3' },
+          { name: '💃 Salsa (Latin - Upbeat brass & percussion) ' + chalk.gray('[SPACE to preview]'), value: 'agent_vibes_salsa_v2_loop.mp3' },
+          { name: '🎸 Cumbia (Latin - Accordion & drums) ' + chalk.gray('[SPACE to preview]'), value: 'agent_vibes_cumbia_v1_loop.mp3' },
+          { name: '🌸 Bossa Nova (Brazilian jazz) ' + chalk.gray('[SPACE to preview]'), value: 'agent_vibes_bossa_nova_v2_loop.mp3' },
+          { name: '🏙️  Japanese City Pop (80s synth) ' + chalk.gray('[SPACE to preview]'), value: 'agent_vibes_japanese_city_pop_v1_loop.mp3' },
+          { name: '🌊 Chillwave (Electronic ambient) ' + chalk.gray('[SPACE to preview]'), value: 'agent_vibes_chillwave_v2_loop.mp3' },
+          { name: '🌙 Dark Chill Step (Electronic bass) ' + chalk.gray('[SPACE to preview]'), value: 'agent_vibes_dark_chill_step_loop.mp3' },
+          { name: '🕉️  Goa Trance (Psychedelic electronic) ' + chalk.gray('[SPACE to preview]'), value: 'agent_vibes_goa_trance_v2_loop.mp3' },
+          { name: '🎼 Harpsichord (Baroque classical) ' + chalk.gray('[SPACE to preview]'), value: 'agent_vibes_harpsichord_v2_loop.mp3' },
+          { name: '🎻 Celtic Harp (Irish traditional) ' + chalk.gray('[SPACE to preview]'), value: 'agent_vibes_celtic_harp_v1_loop.mp3' },
+          { name: '🌺 Hawaiian Slack Key Guitar ' + chalk.gray('[SPACE to preview]'), value: 'agent_vibes_hawaiian_slack_key_guitar_v2_loop.mp3' },
+          { name: '🏜️  Arabic Oud (Middle Eastern) ' + chalk.gray('[SPACE to preview]'), value: 'agent_vibes_arabic_v2_loop.mp3' },
+          { name: '🪘 Gnawa Ambient (North African) ' + chalk.gray('[SPACE to preview]'), value: 'agent_vibes_ganawa_ambient_v2_loop.mp3' },
+          { name: '🥁 Tabla Dream Pop (Indian percussion) ' + chalk.gray('[SPACE to preview]'), value: 'agent_vibes_tabla_dream_pop_v1_loop.mp3' }
         ];
 
-        const { selectedTrack } = await inquirer.prompt([{
-          type: 'list',
+        // Add custom tracks separator and options if any exist
+        if (customTrackChoices.length > 0) {
+          trackChoices.push(
+            new inquirer.Separator(chalk.gray('─'.repeat(50))),
+            ...customTrackChoices
+          );
+        }
+
+        // Add custom track option
+        trackChoices.push(
+          new inquirer.Separator(chalk.gray('─'.repeat(50))),
+          { name: '➕ Add Custom Track...', value: '__custom__' }
+        );
+
+        // Interactive track selection - Enter=Select, Spacebar=Preview
+        const tracksDir = path.join(__dirname, '..', '.claude', 'audio', 'tracks');
+
+        const result = await createPreviewListPrompt(inquirer, {
           name: 'selectedTrack',
-          message: chalk.yellow('Choose default background music track:'),
+          message: chalk.yellow('Choose background music:'),
           choices: trackChoices,
           default: config.backgroundMusic.track || 'agentvibes_soft_flamenco_loop.mp3',
-          pageSize: 16
-        }]);
+          pageSize: 18,
+          loop: false,
+          onPreview: async (trackFile) => {
+            console.log(chalk.cyan('\n  🔊 Playing preview...\n'));
+            await previewAudioTrack(trackFile, tracksDir);
+          }
+        });
+        const selectedTrack = result.selectedTrack;
+
+        // Handle custom track selection
+        if (selectedTrack === '__custom__') {
+          console.log('');
+          const result = await promptForCustomMusic(claudeDir);
+
+          if (result.success && result.filename) {
+            config.backgroundMusic.track = result.filename;
+
+            // Update registry
+            const allCustomTracks = await loadCustomTracks();
+            if (!allCustomTracks.some(t => t.filename === result.filename)) {
+              const trackName = path.basename(result.filename, path.extname(result.filename));
+              allCustomTracks.push({ name: trackName, filename: result.filename });
+              await saveCustomTracks(allCustomTracks);
+            }
+          } else {
+            // Fallback to default
+            config.backgroundMusic.track = 'agentvibes_soft_flamenco_loop.mp3';
+            if (result.error) {
+              console.log(chalk.yellow(`⚠️  ${result.error}`));
+            }
+            console.log(chalk.yellow('⚠️  Using default track'));
+          }
+        } else {
+          config.backgroundMusic.track = selectedTrack;
+        }
 
-        config.backgroundMusic.track = selectedTrack;
+        console.log(chalk.green(`\n✓ Selected: ${config.backgroundMusic.track}\n`));
       }
 
       // Auto-advance to next page after audio settings
-      console.log(chalk.green('\n✓ Audio settings configured\n'));
+      console.log(chalk.green('✓ Background music configured\n'));
       currentPage++;
       continue;
 
-    } else if (currentPage === 5) {
-      // Page 6: Verbosity Settings
+    } else if (currentPage === 6) {
+      // Page 7: Verbosity Settings
       console.log(boxen(
         chalk.white('Choose how much Claude speaks during interactions.\n\n') +
         chalk.yellow('🔊 High:\n') +
@@ -1582,23 +2480,39 @@ async function collectConfiguration(options = {}) {
         choices: [
           { name: '🔊 High - Maximum transparency', value: 'high' },
           { name: '🔉 Medium - Balanced', value: 'medium' },
-          { name: '🔈 Low - Minimal', value: 'low' }
+          { name: '🔈 Low - Minimal', value: 'low' },
+          new inquirer.Separator(),
+          { name: chalk.magentaBright('← Previous'), value: '__back__' }
         ],
         default: config.verbosity || 'high'
       }]);
 
+      if (verbosity === '__back__') {
+        currentPage--;
+        continue;
+      }
+
       config.verbosity = verbosity;
 
-      // Auto-advance - verbosity is the last page, so we're done
+      // Show confirmation and auto-advance to next page
       console.log(chalk.green('\n✓ Verbosity level set\n'));
       currentPage++;
       continue;
     }
 
-    // Navigation
+    // Auto-advance if provider was just detected (skip navigation prompt)
+    if (config._autoAdvance) {
+      delete config._autoAdvance;
+      await new Promise(resolve => setTimeout(resolve, 800)); // Brief pause
+      currentPage++;
+      continue;
+    }
+
+    // Navigation with page titles
     const navChoices = [];
     if (currentPage < totalPages - 1) {
-      navChoices.push({ name: chalk.green('Next →'), value: 'next' });
+      const nextPageTitle = getPageTitle(currentPage + 1).replace(/[🔧🎙️🎤😎💧🔊]\s*/, ''); // Remove emoji
+      navChoices.push({ name: chalk.green('Next →') + chalk.gray(` (${nextPageTitle})`), value: 'next' });
     } else {
       navChoices.push({ name: chalk.cyan('✓ Continue to Installation'), value: 'continue' });
     }
@@ -1607,13 +2521,23 @@ async function collectConfiguration(options = {}) {
     if (currentPage === 0) {
       navChoices.push({ name: chalk.magentaBright('← Back to Welcome'), value: 'back' });
     } else {
-      navChoices.push({ name: chalk.magentaBright('← Previous'), value: 'prev' });
+      const prevPageTitle = getPageTitle(currentPage - 1).replace(/[🔧🎙️🎤😎💧🔊]\s*/, ''); // Remove emoji
+      navChoices.push({ name: chalk.magentaBright('← Previous') + chalk.gray(` (${prevPageTitle})`), value: 'prev' });
+    }
+
+    // Set navigation message based on page status
+    let navMessage = '';
+    if (currentPage === 0 && pageStatus) {
+      navMessage = pageStatus.allMet
+        ? chalk.green('✓') + chalk.cyan(' All system dependencies met')
+        : chalk.yellow('⚠') + chalk.cyan(` ${pageStatus.missingCount} optional tool${pageStatus.missingCount > 1 ? 's' : ''} missing`);
     }
 
     const { action } = await inquirer.prompt([{
       type: 'list',
       name: 'action',
-      message: '',
+      message: navMessage,
+      prefix: '',
       choices: navChoices,
       default: 'next'
     }]);
@@ -1690,22 +2614,22 @@ function showWelcome() {
  * Shown during install and update commands
  */
 function getReleaseInfoBoxen() {
-  return chalk.cyan.bold('📦 AgentVibes v3.5.8 - Provider Validation Security & UX Improvements\n\n') +
+  return chalk.cyan.bold('📦 AgentVibes v4.0.0 - Interactive Console & Voice Explorer\n\n') +
     chalk.green.bold('🎙️ WHAT\'S NEW:\n\n') +
-    chalk.cyan('Critical security and reliability update for provider detection. Fixes command injection\n') +
-    chalk.cyan('vulnerabilities, prevents HOME directory injection attacks, and improves UX with explicit\n') +
-    chalk.cyan('provider detection messaging. Soprano TTS installed via pipx now correctly detected.\n\n') +
+    chalk.cyan('Major release with a full interactive TUI console, voice browser with 914+ voices,\n') +
+    chalk.cyan('and comprehensive platform support. Includes 58 security fixes, reliable TTS hooks,\n') +
+    chalk.cyan('and support for Windows, macOS, Android/Termux, and SSH-remote audio.\n\n') +
     chalk.green.bold('✨ KEY HIGHLIGHTS:\n\n') +
-    chalk.gray('   🔐 Security Fixes - Fixed command injection, HOME injection prevention, path traversal\n') +
-    chalk.gray('   ✅ Provider Detection - Soprano via pipx now correctly detected\n') +
-    chalk.gray('   💬 Better Messaging - Explicit detection confirmation, detailed error messages\n') +
-    chalk.gray('   🧪 Enhanced Tests - Verification of actual detection values\n') +
-    chalk.gray('   🐛 Debug Support - Added logging for troubleshooting\n\n') +
+    chalk.gray('   🖥️  Interactive TUI Console - Settings, Voices, Music tabs with live preview\n') +
+    chalk.gray('   🎤 Voice Browser - Browse and preview 914+ Piper TTS voices\n') +
+    chalk.gray('   🔧 Reliable TTS Hooks - JSON context injection, auto git-init\n') +
+    chalk.gray('   🌍 Multi-Platform - Windows, macOS, Android/Termux, SSH-remote\n') +
+    chalk.gray('   🔐 Security Hardened - 58 issues fixed, 180+ security tests\n\n') +
     chalk.gray('📖 Full Release Notes: RELEASE_NOTES.md\n') +
     chalk.gray('🌐 Website: https://agentvibes.org\n') +
     chalk.gray('📦 Repository: https://github.com/paulpreibisch/AgentVibes\n\n') +
     chalk.gray('Co-created by Paul Preibisch with Claude AI\n') +
-    chalk.gray('Copyright © 2025 Paul Preibisch | Apache-2.0 License');
+    chalk.gray('Copyright © 2026 Paul Preibisch | Apache-2.0 License');
 }
 
 /**
@@ -2509,30 +3433,6 @@ async function copyPersonalityFiles(targetDir, spinner) {
     content += chalk.gray('Personalities change how Claude speaks - adding humor, emotion, or style.\n');
     content += chalk.gray('Change with: ') + chalk.yellow('/agent-vibes:personality <name>') + chalk.gray(' or say "change personality to sassy"\n\n');
 
-    // Map personalities to emojis
-    const personalityEmojis = {
-      'angry': '😠',
-      'annoying': '😤',
-      'crass': '🤬',
-      'dramatic': '🎭',
-      'dry-humor': '😐',
-      'flirty': '😘',
-      'funny': '😂',
-      'grandpa': '👴',
-      'millennial': '🙄',
-      'moody': '😒',
-      'normal': '😊',
-      'pirate': '🏴‍☠️',
-      'poetic': '📜',
-      'professional': '👔',
-      'rapper': '🎤',
-      'robot': '🤖',
-      'sarcastic': '😏',
-      'sassy': '💁',
-      'surfer-dude': '🏄',
-      'zen': '🧘'
-    };
-
     // Display personalities in two columns
     const personalities = installedPersonalities.map(file => {
       const name = file.replace('.md', '');
@@ -2859,8 +3759,33 @@ async function configureSessionStartHook(targetDir, spinner) {
     } else {
       spinner.info(chalk.yellow('SessionStart hook already configured\n'));
     }
-  } catch (error) {
-    spinner.fail(chalk.red('Failed to configure hook: ' + error.message + '\n'));
+  } catch (error) {
+    spinner.fail(chalk.red('Failed to configure hook: ' + error.message + '\n'));
+  }
+}
+
+/**
+ * Ensure target directory is a git repo (required for Claude Code hook context injection)
+ * @param {string} targetDir - Target installation directory
+ * @param {Object} spinner - Ora spinner instance
+ */
+async function ensureGitRepo(targetDir, spinner) {
+  const gitDir = path.join(targetDir, '.git');
+  try {
+    await fs.access(gitDir);
+    // Already a git repo
+  } catch {
+    console.log(chalk.cyan('\n🔧 Initializing git repository (required for Claude Code hooks)...'));
+    try {
+      const { execSync: execSyncLocal } = await import('child_process');
+      execSyncLocal('git init', { cwd: targetDir, stdio: 'pipe' });
+      // Stage only files that exist
+      execSyncLocal('git add .', { cwd: targetDir, stdio: 'pipe' });
+      execSyncLocal('git commit -m "chore: initialize AgentVibes"', { cwd: targetDir, stdio: 'pipe' });
+      console.log(chalk.green('✓ Git repository initialized (required for TTS hooks)'));
+    } catch (error) {
+      console.log(chalk.yellow(`⚠ Could not initialize git repo - TTS hooks may not work: ${error.message}`));
+    }
   }
 }
 
@@ -2932,7 +3857,7 @@ async function checkAndInstallPiper(targetDir, options) {
       try {
         if (fsSync.existsSync(piperDownloadPath)) {
           execScript(`${piperDownloadPath} --yes`, {
-            stdio: 'inherit',
+            stdio: options.silent ? 'pipe' : 'inherit',
             env: process.env
           });
           console.log(chalk.green('\n✅ Voice models downloaded successfully!\n'));
@@ -2976,7 +3901,7 @@ async function checkAndInstallPiper(targetDir, options) {
 
         try {
           execScript(`${piperInstallerPath} --non-interactive`, {
-            stdio: 'inherit',
+            stdio: options.silent ? 'pipe' : 'inherit',
             env: process.env
           });
           console.log(chalk.green('\n✅ Piper TTS installed successfully!\n'));
@@ -3522,12 +4447,9 @@ async function executeMigrationScript(migrationScript, targetDir, spinner) {
   try {
     await fs.access(migrationScript);
 
-    // Execute migration script using execFile to prevent command injection
-    const { execFile } = require('child_process');
-    const { promisify } = require('util');
-    const execFilePromise = promisify(execFile);
-
-    await execFilePromise('bash', [migrationScript], { cwd: targetDir });
+    // Execute migration script using execFileSync to prevent command injection
+    // Uses top-level import of execFileSync (ESM-compatible, no require())
+    execFileSync('bash', [migrationScript], { cwd: targetDir, stdio: 'pipe' });
 
     spinner.succeed(chalk.green('✓ Configuration migrated to .agentvibes/'));
     console.log(chalk.gray('   Old locations: .claude/config/, .claude/plugins/'));
@@ -3770,7 +4692,8 @@ async function updatePersonalityFiles(targetDir, srcPersonalitiesDir) {
  * @returns {Object} Mock spinner object
  */
 function createSilentSpinner() {
-  return { start: () => {}, succeed: () => {}, info: () => {}, fail: () => {} };
+  const s = { start: () => s, succeed: () => s, info: () => s, fail: () => s, warn: () => s, stop: () => s };
+  return s;
 }
 
 /**
@@ -3845,6 +4768,7 @@ async function performUpdateOperations(targetDir, spinner) {
   // Update settings.json
   spinner.text = 'Updating AgentVibes hook configuration...';
   await configureSessionStartHook(targetDir, silentSpinner);
+  await ensureGitRepo(targetDir, silentSpinner);
 
   // Detect and migrate old configuration
   spinner.text = 'Checking for old configuration...';
@@ -3955,157 +4879,7 @@ async function install(options = {}) {
   const piperVoicesPath = userConfig.piperPath;
   const targetDir = options.directory || currentDir;
 
-  // Collect pre-install information pages
-  const preInstallPages = [];
-
-  // Page 1: Configuration Summary
-  const providerLabels = {
-    piper: 'Piper TTS',
-    macos: 'macOS Say',
-    soprano: 'Soprano TTS',
-    'termux-ssh': 'Termux SSH (Android)',
-    'ssh-pulseaudio': 'PulseAudio Tunnel',
-    pulseaudio: 'PulseAudio Tunnel',
-    'windows-piper': 'Windows Piper TTS',
-    'windows-sapi': 'Windows SAPI'
-  };
-  const reverbLabels = {
-    off: 'Off',
-    light: 'Light',
-    medium: 'Medium',
-    heavy: 'Heavy',
-    cathedral: 'Cathedral'
-  };
-  const verbosityLabels = {
-    high: 'High',
-    medium: 'Medium',
-    low: 'Low'
-  };
-
-  let configContent = chalk.bold('Your Configuration\n\n');
-  configContent += chalk.cyan('🎤 TTS Provider:\n');
-  configContent += chalk.white(`   ${providerLabels[selectedProvider]}\n`);
-  if (selectedProvider === 'piper' && piperVoicesPath) {
-    configContent += chalk.gray(`   Voice storage: ${piperVoicesPath}\n`);
-  }
-  if (selectedProvider === 'termux-ssh') {
-    if (userConfig.sshHost) {
-      configContent += chalk.gray(`   SSH host: ${userConfig.sshHost}\n`);
-    } else {
-      configContent += chalk.yellow(`   SSH host: Not configured (set later)\n`);
-    }
-  }
-  configContent += '\n';
-  configContent += chalk.cyan('🎛️  Audio Settings:\n');
-  configContent += chalk.white(`   Reverb: ${reverbLabels[userConfig.reverb]}\n`);
-  configContent += chalk.white(`   Background Music: ${userConfig.backgroundMusic.enabled ? 'Enabled' : 'Disabled'}\n`);
-  if (userConfig.backgroundMusic.enabled) {
-    // Find the track name from the track choices
-    const trackChoices = {
-      'agentvibes_soft_flamenco_loop.mp3': 'Soft Flamenco',
-      'agent_vibes_bachata_v1_loop.mp3': 'Bachata',
-      'agent_vibes_salsa_v2_loop.mp3': 'Salsa',
-      'agent_vibes_cumbia_v1_loop.mp3': 'Cumbia',
-      'agent_vibes_bossa_nova_v2_loop.mp3': 'Bossa Nova',
-      'agent_vibes_japanese_city_pop_v1_loop.mp3': 'Japanese City Pop',
-      'agent_vibes_chillwave_v2_loop.mp3': 'Chillwave',
-      'dreamy_house_loop.mp3': 'Dreamy House',
-      'agent_vibes_dark_chill_step_loop.mp3': 'Dark Chill Step',
-      'agent_vibes_goa_trance_v2_loop.mp3': 'Goa Trance',
-      'agent_vibes_harpsichord_v2_loop.mp3': 'Harpsichord',
-      'agent_vibes_celtic_harp_v1_loop.mp3': 'Celtic Harp',
-      'agent_vibes_hawaiian_slack_key_guitar_v2_loop.mp3': 'Hawaiian Slack Key Guitar',
-      'agent_vibes_arabic_v2_loop.mp3': 'Arabic Oud',
-      'agent_vibes_ganawa_ambient_v2_loop.mp3': 'Gnawa Ambient',
-      'agent_vibes_tabla_dream_pop_v1_loop.mp3': 'Tabla Dream Pop'
-    };
-    const trackName = trackChoices[userConfig.backgroundMusic.track] || userConfig.backgroundMusic.track;
-    configContent += chalk.gray(`   Default track: ${trackName}\n`);
-  }
-  configContent += '\n';
-  configContent += chalk.cyan('😎 Personality:\n');
-  const personalityDisplay = userConfig.personality === 'none' ? 'None (Professional)' : userConfig.personality.charAt(0).toUpperCase() + userConfig.personality.slice(1);
-  configContent += chalk.white(`   ${personalityDisplay}\n`);
-  configContent += '\n';
-  configContent += chalk.cyan('🔊 Verbosity:\n');
-  configContent += chalk.white(`   ${verbosityLabels[userConfig.verbosity]}\n`);
-
-  const configBoxen = boxen(configContent.trim(), {
-    padding: 1,
-    margin: { top: 0, bottom: 0, left: 0, right: 0 },
-    borderStyle: 'round',
-    borderColor: 'green',
-    width: 80
-  });
-
-  // Don't add Configuration Summary to preInstallPages yet - we'll handle it specially
-
-  // Show pre-install pages up to (but NOT including) Configuration Summary
-  if (!options.yes && preInstallPages.length > 0) {
-    console.log(chalk.cyan('\n📖 Installation Preview\n'));
-    const preInstallOffset = 4; // After 4 config pages (System Dependencies + Provider + Audio + Verbosity)
-    // For pre-install, estimate post-install pages (will be exact in post-install)
-    const estimatedPostInstall = 7; // Typical: 5 summaries + 1 BMAD/recommendation + 1 complete
-    const estimatedTotal = configPages + preInstallPages.length + 1 + estimatedPostInstall; // +1 for Config Summary
-
-    const result = await showPaginatedContent(preInstallPages, {
-      ...options,
-      continueLabel: '✓ Next',
-      pageOffset: preInstallOffset,
-      totalPages: estimatedTotal,
-      showPreviousOnFirst: true
-    });
-
-    // If user went back from first pre-install page, restart configuration
-    if (result === 'prev') {
-      console.log(chalk.yellow('\n↩️  Returning to configuration...\n'));
-      return install(options); // Restart the install function
-    }
-  }
-
-  // Handle Configuration Summary page specially with welcome message prompt
-  if (!options.yes) {
-    // Show Configuration Summary page
-    console.clear();
-    const currentPageNum = 4 + preInstallPages.length; // After config pages + pre-install pages
-    const estimatedPostInstall = 7;
-    const estimatedTotal = configPages + preInstallPages.length + 1 + estimatedPostInstall;
-    const { header } = createPageHeaderFooter('Configuration Summary', currentPageNum, estimatedTotal, 0);
-
-    console.log(header);
-    console.log(configBoxen);
-    console.log('');
-    // Don't show welcome message text for termux-ssh (it won't work)
-    if (userConfig.provider !== 'termux-ssh') {
-      console.log(chalk.gray('Play audio welcome message from Paul, creator of AgentVibes.\n'));
-    }
-  }
-
-  // Ask welcome message question BEFORE showing navigation
-  // Skip for termux-ssh - welcome audio plays locally, not on Android device
-  if (!options.yes && userConfig.provider !== 'termux-ssh') {
-    // Ask if user wants to hear welcome message
-    const { playWelcome } = await inquirer.prompt([
-      {
-        type: 'confirm',
-        name: 'playWelcome',
-        message: chalk.yellow('🎵 Listen to Welcome Message?'),
-        default: false,
-      },
-    ]);
-
-    if (playWelcome) {
-      console.log(''); // Spacing before spinner
-      const spinner = ora('Playing welcome message...').start();
-      await playWelcomeDemo(targetDir, spinner, options);
-      spinner.succeed(chalk.green('Welcome message complete!'));
-      console.log(''); // Spacing after completion
-    }
-  } else if (!options.yes && userConfig.provider === 'termux-ssh' || userConfig.provider === 'ssh-pulseaudio') {
-    console.log(chalk.yellow('⊘ Welcome message skipped (not available for Termux SSH)\n'));
-  }
-
-  // Now show navigation menu (Continue to installation)
+  // Confirm and start installation
   const { startInstall } = await inquirer.prompt([
     {
       type: 'confirm',
@@ -4120,59 +4894,36 @@ async function install(options = {}) {
     process.exit(0);
   }
 
-  // User already confirmed by pressing "Start Installation", so no need for another confirmation
+  // Silent spinner for copy functions — suppresses per-file output
+  const silentSpinner = createSilentSpinner();
+
   console.log('');
-  const spinner = ora('Checking installation directory...').start();
+  const spinner = ora('Installing AgentVibes...').start();
 
   try {
     // Create .claude directory structure
     const claudeDir = path.join(targetDir, '.claude');
     const commandsDir = path.join(claudeDir, 'commands');
     const hooksDir = path.join(claudeDir, isNativeWindows() ? 'hooks-windows' : 'hooks');
-
-    let exists = false;
-    try {
-      await fs.access(claudeDir);
-      exists = true;
-    } catch {}
-
-    if (!exists) {
-      spinner.info(chalk.yellow('Creating .claude directory structure...'));
-      const audioDir = path.join(claudeDir, 'audio');
-      const tracksDir = path.join(audioDir, 'tracks');
-      console.log(chalk.gray(`   → ${commandsDir}`));
-      console.log(chalk.gray(`   → ${hooksDir}`));
-      console.log(chalk.gray(`   → ${audioDir}`));
-      console.log(chalk.gray(`   → ${tracksDir}`));
-      await fs.mkdir(commandsDir, { recursive: true });
-      await fs.mkdir(hooksDir, { recursive: true });
-      await fs.mkdir(tracksDir, { recursive: true });
-      console.log(chalk.green('   ✓ Directories created!\n'));
-    } else {
-      spinner.succeed(chalk.green('.claude directory found!'));
-      console.log(chalk.gray(`   Location: ${claudeDir}\n`));
-
-      // Ensure audio/tracks directory exists even if .claude already exists
-      const audioDir = path.join(claudeDir, 'audio');
-      const tracksDir = path.join(audioDir, 'tracks');
-      await fs.mkdir(tracksDir, { recursive: true });
-    }
-
-    // Copy all files using helper functions
-    const commandResult = await copyCommandFiles(targetDir, spinner);
-    const hookResult = await copyHookFiles(targetDir, spinner);
-    const personalityResult = await copyPersonalityFiles(targetDir, spinner);
-    const pluginFileCount = await copyPluginFiles(targetDir, spinner);
-    const bmadConfigFileCount = await copyBmadConfigFiles(targetDir, spinner);
-    const backgroundMusicResult = await copyBackgroundMusicFiles(targetDir, spinner);
-    const configFileCount = await copyConfigFiles(targetDir, spinner);
-
-    // Configure hooks and manifests
-    await configureSessionStartHook(targetDir, spinner);
-    await installPluginManifest(targetDir, spinner);
+    const audioDir = path.join(claudeDir, 'audio');
+    const tracksDir = path.join(audioDir, 'tracks');
+    await fs.mkdir(commandsDir, { recursive: true });
+    await fs.mkdir(hooksDir, { recursive: true });
+    await fs.mkdir(tracksDir, { recursive: true });
+
+    // Copy all files silently
+    await copyCommandFiles(targetDir, silentSpinner);
+    await copyHookFiles(targetDir, silentSpinner);
+    await copyPersonalityFiles(targetDir, silentSpinner);
+    await copyPluginFiles(targetDir, silentSpinner);
+    await copyBmadConfigFiles(targetDir, silentSpinner);
+    await copyBackgroundMusicFiles(targetDir, silentSpinner);
+    await copyConfigFiles(targetDir, silentSpinner);
+    await configureSessionStartHook(targetDir, silentSpinner);
+    await installPluginManifest(targetDir, silentSpinner);
+    await ensureGitRepo(targetDir, silentSpinner);
 
     // Save provider configuration
-    spinner.start('Saving provider configuration...');
     const providerConfigPath = path.join(claudeDir, 'tts-provider.txt');
     await fs.writeFile(providerConfigPath, selectedProvider);
 
@@ -4188,29 +4939,20 @@ async function install(options = {}) {
 
     // Set up receiver script if in receiver mode (Termux)
     if (userConfig.isReceiver) {
-      spinner.start('Setting up receiver script...');
-
       const receiverDir = path.join(process.env.HOME || process.env.USERPROFILE, '.agentvibes');
       await fs.mkdir(receiverDir, { recursive: true, mode: 0o700 });
-
       const receiverScriptPath = path.join(receiverDir, 'receiver.sh');
       const templatePath = path.join(__dirname, '..', 'templates', 'agentvibes-receiver.sh');
-
       try {
         const templateContent = await fs.readFile(templatePath, 'utf8');
         await fs.writeFile(receiverScriptPath, templateContent, { mode: 0o755 });
-        spinner.succeed(chalk.green('Receiver script installed!'));
-        console.log(chalk.gray(`   Location: ${receiverScriptPath}\n`));
-      } catch (error) {
-        spinner.warn(chalk.yellow('Could not install receiver script'));
-        console.log(chalk.gray(`   Error: ${error.message}\n`));
+      } catch {
+        // Receiver script install failed — non-fatal
       }
     }
 
-    // Save setup guide for SSH-remote installations
+    // Save setup guide for SSH-remote installations (file only, no terminal output)
     if (selectedProvider === 'termux-ssh' || selectedProvider === 'ssh-pulseaudio') {
-      spinner.start('Saving setup guide...');
-
       const agentvibesDir = path.join(process.env.HOME || process.env.USERPROFILE, '.agentvibes');
       await fs.mkdir(agentvibesDir, { recursive: true, mode: 0o700 });
 
@@ -4271,397 +5013,100 @@ Troubleshooting:
 - Verify AgentVibes on receiver: ssh ${userConfig.sshHost || 'phone'} which agentvibes
 - Test receiver script: ssh ${userConfig.sshHost || 'phone'} ~/.agentvibes/receiver.sh "Test"
 `;
-
       try {
         await fs.writeFile(setupGuidePath, setupGuideContent);
-        spinner.succeed(chalk.green('Setup guide saved!'));
-        console.log(chalk.gray(`   Location: ${setupGuidePath}\n`));
-      } catch (error) {
-        spinner.warn(chalk.yellow('Could not save setup guide'));
-        console.log(chalk.gray(`   Error: ${error.message}\n`));
+      } catch {
+        // Setup guide write failed — non-fatal
       }
     }
 
-    // Set default voice based on user selection or provider defaults
+    // Set default voice
     const voiceConfigPath = path.join(claudeDir, 'tts-voice.txt');
     let defaultVoice = userConfig.defaultVoice;
-
-    // Fallback to defaults if voice wasn't selected
     if (!defaultVoice) {
       switch (selectedProvider) {
-        case 'piper':
-          defaultVoice = 'en_US-ryan-high';
-          break;
-        case 'macos':
-          defaultVoice = 'Samantha';
-          break;
-        case 'windows-piper':
-          defaultVoice = 'en_US-ryan-high';
-          break;
-        case 'windows-sapi':
-          defaultVoice = 'Microsoft David Desktop';
-          break;
-        case 'soprano':
-          defaultVoice = 'soprano-default';
-          break;
-        case 'termux-ssh':
-          // Android TTS voices are managed in Android settings, not here
-          defaultVoice = 'android-system-default';
-          break;
-        default:
-          defaultVoice = 'Samantha';
-          break;
+        case 'piper':          defaultVoice = 'en_US-ryan-high'; break;
+        case 'macos':          defaultVoice = 'Samantha'; break;
+        case 'windows-piper':  defaultVoice = 'en_US-ryan-high'; break;
+        case 'windows-sapi':   defaultVoice = 'Microsoft David Desktop'; break;
+        case 'soprano':        defaultVoice = 'soprano-default'; break;
+        case 'termux-ssh':     defaultVoice = 'android-system-default'; break;
+        default:               defaultVoice = 'Samantha'; break;
       }
     }
     await fs.writeFile(voiceConfigPath, defaultVoice);
 
-    spinner.succeed();
-
     // Detect and migrate old configuration
-    await detectAndMigrateOldConfig(targetDir, spinner);
-
-    // Snapshot existing Piper voices BEFORE installation (for proper summary display)
-    let preExistingVoices = [];
-    if (selectedProvider === 'piper') {
-      const piperVoicesDir = path.join(process.env.HOME || process.env.USERPROFILE, '.claude', 'piper-voices');
-      try {
-        if (fsSync.existsSync(piperVoicesDir)) {
-          const files = fsSync.readdirSync(piperVoicesDir);
-          preExistingVoices = files
-            .filter(f => f.endsWith('.onnx'))
-            .map(f => f.replace('.onnx', ''));
-        }
-      } catch {
-        // Ignore errors
-      }
-    }
+    await detectAndMigrateOldConfig(targetDir, silentSpinner);
 
     // Auto-install Piper if selected
     if (selectedProvider === 'piper') {
+      spinner.text = 'Installing Piper TTS...';
       await checkAndInstallPiper(targetDir, options);
     } else if (selectedProvider === 'windows-piper') {
+      spinner.text = 'Installing Piper TTS for Windows...';
       await checkAndInstallPiperWindows(targetDir, options);
-    } else if (selectedProvider === 'soprano') {
-      console.log(chalk.magenta('⚡ Soprano TTS selected'));
-      console.log(chalk.gray('   Install: pip install soprano-tts'));
-      console.log(chalk.gray('   GPU:     pip install soprano-tts[lmdeploy]'));
-      console.log(chalk.gray('   Start:   soprano-webui\n'));
-    } else if (selectedProvider === 'windows-sapi') {
-      console.log(chalk.green('✓ Windows SAPI provider selected - no additional setup needed\n'));
     }
 
-    // Apply background music configuration from userConfig
-    if (backgroundMusicResult.count > 0) {
-      const configDir = path.join(claudeDir, 'config');
-      await fs.mkdir(configDir, { recursive: true });
-
-      if (userConfig.backgroundMusic.enabled) {
-        // Write enabled flag
-        const enabledFile = path.join(configDir, 'background-music-enabled.txt');
-        await fs.writeFile(enabledFile, 'true');
-
-        // Update audio-effects.cfg with selected track
+    // Apply background music configuration
+    const configDir = path.join(claudeDir, 'config');
+    await fs.mkdir(configDir, { recursive: true });
+    if (userConfig.backgroundMusic?.enabled) {
+      await fs.writeFile(path.join(configDir, 'background-music-enabled.txt'), 'true');
+      try {
         const audioEffectsPath = path.join(configDir, 'audio-effects.cfg');
         let audioEffectsContent = await fs.readFile(audioEffectsPath, 'utf-8');
-
-        // Update the default entry with selected track
         audioEffectsContent = audioEffectsContent.replace(
           /^default\|([^|]*)\|([^|]*)\|(.*)$/m,
           `default|$1|${userConfig.backgroundMusic.track}|$3`
         );
-
         await fs.writeFile(audioEffectsPath, audioEffectsContent);
+      } catch {
+        // Audio effects config not yet available — non-fatal
       }
     }
 
-    // Apply reverb configuration from userConfig
-    const selectedReverb = userConfig.reverb;
-
-    // Apply verbosity configuration from userConfig
-    const verbosityFile = path.join(claudeDir, 'tts-verbosity.txt');
-    await fs.writeFile(verbosityFile, userConfig.verbosity);
-
-    // Apply personality configuration from userConfig
+    // Apply verbosity, personality, pretext
+    await fs.writeFile(path.join(claudeDir, 'tts-verbosity.txt'), userConfig.verbosity);
     if (userConfig.personality && userConfig.personality !== 'none') {
-      const personalityFile = path.join(claudeDir, 'tts-personality.txt');
-      await fs.writeFile(personalityFile, userConfig.personality);
-    }
-
-    // Initialize piperVoicesBoxen outside the conditional for proper scoping
-    let piperVoicesBoxen = null;
-
-    if (selectedProvider === 'macos') {
-      // macOS Say provider summary
-      console.log(chalk.white(`   • Using macOS built-in Say command`));
-      console.log(chalk.white(`   • System voices available (Samantha, Alex, etc.)`));
-      console.log(chalk.green(`   • No API key needed ✓`));
-      console.log(chalk.green(`   • Zero setup required ✓`));
-    } else {
-      // Check for installed Piper voices
-      const piperVoicesDir = path.join(process.env.HOME || process.env.USERPROFILE, '.claude', 'piper-voices');
-      let installedVoices = [];
-      let missingVoices = [];
-
-      const commonVoices = [
-        'en_US-lessac-medium',
-        'en_US-amy-medium',
-        'en_US-joe-medium',
-        'en_US-ryan-high',
-        'en_US-libritts-high',
-        '16Speakers'
-      ];
-
-      try {
-        if (fsSync.existsSync(piperVoicesDir)) {
-          const files = fsSync.readdirSync(piperVoicesDir);
-          installedVoices = files
-            .filter(f => f.endsWith('.onnx'))
-            .map(f => {
-              const voiceName = f.replace('.onnx', '');
-              const voicePath = path.join(piperVoicesDir, f);
-              try {
-                const stats = fsSync.statSync(voicePath);
-                const sizeMB = (stats.size / 1024 / 1024).toFixed(1);
-                return { name: voiceName, path: voicePath, size: `${sizeMB}M` };
-              } catch (statErr) {
-                // Skip files that can't be read (broken symlinks, etc)
-                return null;
-              }
-            })
-            .filter(v => v !== null);
-
-          // Check which common voices are missing
-          for (const voice of commonVoices) {
-            if (!installedVoices.some(v => v.name === voice)) {
-              missingVoices.push(voice);
-            }
-          }
-        } else {
-          missingVoices = commonVoices;
-        }
-      } catch (err) {
-        // On error, show default message
-        installedVoices = [];
-        missingVoices = commonVoices;
-      }
-
-      // Create Piper voices boxen (only if newly installed)
-      if (installedVoices.length > 0) {
-        // Separate newly installed from pre-existing voices
-        const newlyInstalled = installedVoices.filter(v => !preExistingVoices.includes(v.name));
-        const alreadyInstalled = installedVoices.filter(v => preExistingVoices.includes(v.name));
-
-        // Only create boxen if there are newly installed voices
-        if (newlyInstalled.length > 0) {
-          let content = chalk.bold.green(`${newlyInstalled.length} Newly Installed\n\n`);
-          newlyInstalled.forEach(voice => {
-            content += chalk.green(`✓ ${voice.name}`) + chalk.gray(` (${voice.size})\n`);
-            content += chalk.dim(`  ${voice.path}\n`);
-          });
-
-          if (alreadyInstalled.length > 0) {
-            content += '\n' + chalk.gray('─'.repeat(60)) + '\n\n';
-            content += chalk.bold.cyan(`${alreadyInstalled.length} Already Installed\n\n`);
-            alreadyInstalled.forEach(voice => {
-              content += chalk.cyan(`✓ ${voice.name}`) + chalk.gray(` (${voice.size})\n`);
-              content += chalk.dim(`  ${voice.path}\n`);
-            });
-          }
-
-          // Add additional info at the bottom of boxen
-          content += '\n' + chalk.gray('─'.repeat(60)) + '\n\n';
-          content += chalk.white('• 18 languages supported\n');
-          content += chalk.green('• No API key needed ✓');
-
-          piperVoicesBoxen = boxen(content.trim(), {
-            padding: 1,
-            margin: 1,
-            borderStyle: 'round',
-            borderColor: 'cyan',
-            title: chalk.bold(`🎤 Piper Voices (${installedVoices.length} total)`),
-            titleAlignment: 'center'
-          });
-        }
-      }
-
-      if (missingVoices.length > 0) {
-        console.log(chalk.yellow(`   • ${missingVoices.length} voices to download:`));
-        missingVoices.forEach(voice => {
-          console.log(chalk.gray(`     → ${voice}`));
-        });
-      }
-
-      if (installedVoices.length === 0 && missingVoices.length === 0) {
-        console.log(chalk.white(`   • 50+ Piper neural voices available (free!)`));
-      }
-    }
-    console.log('');
-
-    // Collect all boxens for pagination
-    const pages = [];
-    if (commandResult.boxen) {
-      pages.push({ title: 'Summary: Slash Commands', content: commandResult.boxen });
-    }
-    if (backgroundMusicResult.boxen) {
-      pages.push({ title: 'Summary: Background Music', content: backgroundMusicResult.boxen });
-    }
-    if (hookResult.boxen) {
-      pages.push({ title: 'Summary: TTS Scripts', content: hookResult.boxen });
-    }
-    if (personalityResult.boxen) {
-      pages.push({ title: 'Summary: Personalities', content: personalityResult.boxen });
+      await fs.writeFile(path.join(claudeDir, 'tts-personality.txt'), userConfig.personality);
     }
-    if (piperVoicesBoxen) {
-      pages.push({ title: 'Summary: Piper Voices', content: piperVoicesBoxen });
-    }
-
-    // Recent Changes already shown on page 2 after welcome banner - no need to show again
-
-    // Handle MCP configuration - offer to create .mcp.json if not exists
-    await handleMcpConfiguration(targetDir, options);
-
-    // Create default BMAD voice assignments (works even if BMAD not installed yet)
-    await createDefaultBmadVoiceAssignmentsProactive(targetDir);
-
-    // Handle BMAD integration
-    const bmadDetection = await handleBmadIntegration(targetDir, options);
-    const bmadDetected = bmadDetection.installed;
-
-    if (bmadDetected) {
-      const versionLabel = bmadDetection.version === 6
-        ? `v${bmadDetection.detailedVersion}`
-        : 'v4';
-
-      const bmadContent =
-        chalk.green.bold(`🎉 BMAD-METHOD™ ${versionLabel} Detected!\n\n`) +
-        chalk.white.bold('We detected you ALREADY have the BMAD-METHOD™\n') +
-        chalk.white.bold('The Universal AI Agent Framework installed!\n\n') +
-        chalk.cyan('✨ Try the Party Mode command:\n') +
-        chalk.yellow.bold('   /bmad:core:workflows:party-mode\n\n') +
-        chalk.gray('AgentVibes will assign a unique voice to each agent\n') +
-        chalk.gray('while they help you with your project!\n\n') +
-        chalk.cyan('Other Commands:\n') +
-        chalk.gray('  • /agent-vibes:bmad status - View voice assignments\n') +
-        chalk.gray('  • /agent-vibes:bmad set <agent> <voice> - Customize voices');
-
-      pages.push({ title: 'BMAD Integration', content: bmadContent });
+    if (userConfig.pretext && userConfig.pretext.trim()) {
+      await fs.writeFile(path.join(configDir, 'tts-pretext.txt'), userConfig.pretext, { mode: 0o600 });
     } else {
-      const bmadRecommendBoxen = boxen(
-        chalk.cyan.bold('💡 We also Recommend:\n\n') +
-        chalk.white.bold('BMAD-METHOD™: Universal AI Agent Framework\n\n') +
-        chalk.gray('AgentVibes auto-detects BMAD and assigns voices to agents!\n\n') +
-        chalk.cyan('https://github.com/bmad-code-org/BMAD-METHOD'),
-        {
-          padding: 1,
-          margin: 1,
-          borderStyle: 'round',
-          borderColor: 'cyan',
-        }
-      );
-
-      pages.push({ title: 'Recommended Tools', content: bmadRecommendBoxen });
+      try { await fs.unlink(path.join(configDir, 'tts-pretext.txt')); } catch { /* ok */ }
     }
 
-    // Apply reverb setting if not "off" (using dynamic import for ES modules)
+    // Apply reverb setting
+    const selectedReverb = userConfig.reverb;
     if (selectedReverb && selectedReverb !== 'off') {
       const effectsManagerPath = path.join(targetDir, '.claude', 'hooks', 'effects-manager.sh');
-      // Validate reverb value to prevent command injection
       const validReverb = ['light', 'medium', 'heavy', 'cathedral'];
       if (validReverb.includes(selectedReverb)) {
         try {
-          execFileSync('bash', [effectsManagerPath, 'set-reverb', selectedReverb, 'default'], {
-            stdio: 'pipe',
-          });
-        } catch (error) {
-          // Silent fail - will be shown in success message if needed
+          execFileSync('bash', [effectsManagerPath, 'set-reverb', selectedReverb, 'default'], { stdio: 'pipe' });
+        } catch {
+          // Reverb setting failed — non-fatal
         }
       }
     }
 
-    // Success message as final page (no boxen) - Customize based on setup type
-    let successContent = chalk.green.bold('✨ Installation Complete! ✨\n\n');
-
-    // Receiver mode success message (Termux/Phone)
-    if (userConfig.isReceiver) {
-      successContent +=
-        chalk.green('✓ Receiver mode configured!\n') +
-        chalk.green('✓ Receiver script: ~/.agentvibes/receiver.sh\n') +
-        chalk.green('✓ Provider: piper (local playback)\n\n') +
-        chalk.cyan('📋 Next: On your server, set this device as target:\n') +
-        chalk.white('    echo "phone" > ~/.claude/ssh-remote-host.txt\n\n') +
-        chalk.gray('(Use your SSH hostname or Tailscale name)\n\n');
-    }
-    // SSH-Remote success message (Voiceless server)
-    else if (selectedProvider === 'termux-ssh' || selectedProvider === 'ssh-pulseaudio') {
-      successContent +=
-        chalk.green('✓ Provider configured: ssh-remote\n\n') +
-        chalk.cyan('📋 Setup Instructions Saved:\n') +
-        chalk.white('   ~/.agentvibes/setup-guide.txt\n\n') +
-        chalk.cyan('Quick Start:\n') +
-        chalk.white('1. Install AgentVibes on target device\n') +
-        chalk.white('2. Configure SSH/Tailscale access\n') +
-        chalk.white('3. Test: agentvibes tts "Hello!"\n\n');
-    }
-    // Standard installation success message
-    else {
-      successContent +=
-        chalk.green('✅ AgentVibes TTS is now active via SessionStart hook!\n') +
-        chalk.gray('   (No additional setup needed - TTS protocol auto-loads on every session)\n\n');
-    }
-
-    // Common commands section for all installations
-    successContent +=
-      chalk.white('🎤 Available Commands:\n\n') +
-      chalk.cyan('  /agent-vibes') + chalk.gray(' .................... Show all commands\n') +
-      chalk.cyan('  /agent-vibes:list') + chalk.gray(' ............... List available voices\n') +
-      chalk.cyan('  /agent-vibes:preview') + chalk.gray(' ............ Preview voice samples\n') +
-      chalk.cyan('  /agent-vibes:switch <name>') + chalk.gray(' ...... Change active voice\n') +
-      chalk.cyan('  /agent-vibes:replay [N]') + chalk.gray(' ......... Replay last audio\n') +
-      chalk.cyan('  /agent-vibes:whoami') + chalk.gray(' .............. Show current voice\n\n');
-
-    if (!userConfig.isReceiver) {
-      successContent += chalk.yellow('🎵 Try: ') + chalk.cyan('/agent-vibes:preview') + chalk.yellow(' to hear the voices!\n\n');
-    }
-
-    successContent +=
-      chalk.gray('📦 Repo: ') + chalk.cyan('https://github.com/paulpreibisch/AgentVibes\n') +
-      chalk.gray('📖 Docs: ') + chalk.cyan('https://github.com/paulpreibisch/AgentVibes/blob/master/README.md');
-
-    pages.push({ title: 'Installation Complete', content: successContent });
-
-    // Show all pages with pagination navigation
-    const postInstallOffset = configPages + preInstallPages.length; // After config + pre-install pages
-    const actualTotalPages = configPages + preInstallPages.length + pages.length;
-
-    await showPaginatedContent(pages, {
-      ...options,
-      continueLabel: '✓ Installation Complete',
-      pageOffset: postInstallOffset,
-      totalPages: actualTotalPages
-    });
-
-    // Final message after pagination
-    console.log(chalk.green.bold('\n✅ AgentVibes is Ready!\n'));
-
-    // Check for .mcp.json file
-    const mcpConfigPath = path.join(targetDir, '.mcp.json');
-    const hasMcpConfig = fsSync.existsSync(mcpConfigPath);
-
-    if (hasMcpConfig) {
-      console.log(chalk.white('   Launch Claude Code with MCP:'));
-      console.log(chalk.cyan('   claude --mcp-config .mcp.json\n'));
-    } else {
-      console.log(chalk.white('   Start a new session to activate TTS.\n'));
-    }
+    // MCP configuration and BMAD voice assignments (silent)
+    await handleMcpConfiguration(targetDir, { ...options, yes: true });
+    await createDefaultBmadVoiceAssignmentsProactive(targetDir);
+    await handleBmadIntegration(targetDir, { ...options, yes: true });
 
-    console.log(chalk.white('   • /agent-vibes:list') + chalk.gray(' - See all available voices'));
-    console.log(chalk.white('   • /agent-vibes:switch <name>') + chalk.gray(' - Change your voice'));
-    console.log(chalk.white('   • /agent-vibes:personality <style>') + chalk.gray(' - Set personality\n'));
+    spinner.succeed(chalk.green('AgentVibes installed successfully!'));
 
-    // Play welcome demo with harpsichord intro and reverb voice (opt-in only)
-    if (options.withAudio) {
-      await playWelcomeDemo(targetDir, spinner, options);
-    }
+    // Clean final summary
+    console.log('');
+    console.log(chalk.green.bold('  ✅ Installation Complete'));
+    console.log(chalk.gray(`     Provider:  ${selectedProvider}`));
+    console.log(chalk.gray(`     Location:  ${targetDir}/.claude/`));
+    console.log(chalk.gray(`     Version:   ${VERSION}`));
+    console.log('');
+    console.log(chalk.white('  Run ') + chalk.cyan('npx agentvibes') + chalk.white(' to open the console.'));
+    console.log('');
 
   } catch (error) {
     spinner.fail('Installation failed!');
@@ -4680,7 +5125,6 @@ program
   .description('Install AgentVibes voice commands')
   .option('-d, --directory <path>', 'Installation directory (default: current directory)')
   .option('-y, --yes', 'Skip confirmation prompt (auto-confirm)')
-  .option('--with-audio', 'Play welcome demo audio after installation')
   .action(async (options) => {
     await install(options);
   });
@@ -4700,7 +5144,8 @@ program
     console.log(chalk.gray(`   Update location: ${targetDir}/.claude/`));
     console.log(chalk.gray(`   Package version: ${VERSION}`));
 
-    showReleaseInfo();
+    const releaseInfo = getReleaseInfoBoxen();
+    if (releaseInfo) console.log(releaseInfo);
 
     // Check if already installed
     const commandsDir = path.join(targetDir, '.claude', 'commands', 'agent-vibes');
@@ -5055,6 +5500,232 @@ program
     await resetBmadVoices(options);
   });
 
+// Story 1.4: Config Command - Post-install configuration
+program
+  .command('config <setting>')
+  .description('Configure AgentVibes settings after installation')
+  .usage('intro-text [--no-default]')
+  .action(async (setting, options) => {
+    if (setting === 'intro-text' || setting === 'pretext') {
+      const homeDir = process.env.HOME || process.env.USERPROFILE;
+      const claudeDir = path.join(homeDir, '.claude');
+      const pretextFile = path.join(claudeDir, 'config', 'tts-pretext.txt');
+
+      // Read current pretext if it exists
+      let currentPretext = '';
+      try {
+        if (fsSync.existsSync(pretextFile)) {
+          currentPretext = fsSync.readFileSync(pretextFile, 'utf-8').trim();
+        }
+      } catch (err) {
+        // Ignore read errors
+      }
+
+      // Prompt for new intro text
+      const { newPretext } = await inquirer.prompt([
+        {
+          type: 'input',
+          name: 'newPretext',
+          message: chalk.yellow('Enter new intro text (max 50 chars):'),
+          default: currentPretext || '(none)',
+          validate: (input) => {
+            if (input === '(none)') return true;
+            if (input.length > 50) return 'Max 50 characters';
+            if (input.includes('\n') || input.includes('\r')) return 'No newlines allowed';
+            return true;
+          }
+        }
+      ]);
+
+      // Handle the response
+      if (newPretext === '(none)' || newPretext === '') {
+        // Remove pretext
+        try {
+          await fs.unlink(pretextFile);
+          console.log(chalk.green('✓ Intro text cleared\n'));
+        } catch (err) {
+          // File doesn't exist - that's fine
+          console.log(chalk.green('✓ No intro text configured\n'));
+        }
+      } else {
+        // Save new pretext
+        try {
+          const configDir = path.join(claudeDir, 'config');
+          await fs.mkdir(configDir, { recursive: true });
+          await fs.writeFile(pretextFile, newPretext, { mode: 0o600 });
+          console.log(chalk.green(`✓ Intro text updated: "${newPretext}"\n`));
+          console.log(chalk.cyan('Preview: ') + chalk.gray(`"${newPretext}" This is a sample response\n`));
+        } catch (err) {
+          console.log(chalk.red(`❌ Error saving intro text: ${err.message}\n`));
+          process.exit(1);
+        }
+      }
+    } else if (setting === 'music') {
+      const homeDir = process.env.HOME || process.env.USERPROFILE;
+      const claudeDir = path.join(homeDir, '.claude');
+      const musicTracksDir = path.join(claudeDir, 'audio', 'custom-music', 'tracks');
+      const musicConfigFile = path.join(claudeDir, 'config', 'background-music.txt');
+      const musicEnabledFile = path.join(claudeDir, 'config', 'background-music-enabled.txt');
+
+      console.log(boxen(
+        chalk.cyan.bold('🎵 Background Music Configuration\n\n') +
+        chalk.white('Manage your custom background music settings.'),
+        { padding: 1, borderColor: 'cyan', borderStyle: 'round' }
+      ));
+
+      // Read current music setting
+      let currentMusic = null;
+      let musicEnabled = false;
+
+      try {
+        if (fsSync.existsSync(musicEnabledFile)) {
+          const enabled = fsSync.readFileSync(musicEnabledFile, 'utf-8').trim();
+          musicEnabled = enabled === 'true' || enabled === '1';
+        }
+        if (fsSync.existsSync(musicConfigFile)) {
+          currentMusic = fsSync.readFileSync(musicConfigFile, 'utf-8').trim();
+        }
+      } catch (err) {
+        // Ignore read errors
+      }
+
+      // Display current setting
+      console.log(chalk.gray('\nCurrent Settings:'));
+      console.log(chalk.gray('  Background Music: ') + (musicEnabled ? chalk.green('Enabled') : chalk.yellow('Disabled')));
+
+      if (currentMusic && musicEnabled) {
+        const isCustom = currentMusic.startsWith('custom-') || !currentMusic.includes('agentvibes_');
+        if (isCustom) {
+          console.log(chalk.gray('  Track: ') + chalk.cyan(currentMusic) + chalk.yellow(' (Custom)'));
+        } else {
+          console.log(chalk.gray('  Track: ') + chalk.white(currentMusic) + chalk.gray(' (Default)'));
+        }
+      } else if (!musicEnabled) {
+        console.log(chalk.gray('  Track: ') + chalk.gray('(None - music disabled)'));
+      }
+      console.log('');
+
+      // Show menu
+      const { action } = await inquirer.prompt([{
+        type: 'list',
+        name: 'action',
+        message: chalk.yellow('What would you like to do?'),
+        choices: [
+          { name: '🎵 Change custom music file', value: 'change' },
+          { name: '🗑️  Remove custom music (use defaults)', value: 'remove' },
+          { name: '🔄 Reset to factory defaults', value: 'reset' },
+          { name: musicEnabled ? '🔇 Disable background music' : '🔊 Enable background music', value: 'toggle' },
+          new inquirer.Separator(),
+          { name: '← Back', value: 'back' }
+        ]
+      }]);
+
+      if (action === 'change') {
+        // Change music - reuse promptForCustomMusic from Story 4.5
+        console.log('');
+        const result = await promptForCustomMusic(claudeDir);
+
+        if (result.success && result.filename) {
+          // Update config to point to custom music
+          const configDir = path.join(claudeDir, 'config');
+          await fs.mkdir(configDir, { recursive: true });
+          await fs.writeFile(musicConfigFile, result.filename, { mode: 0o600 });
+
+          // Ensure music is enabled
+          await fs.writeFile(musicEnabledFile, 'true', { mode: 0o644 });
+
+          console.log(chalk.green(`\n✓ Background music updated to: ${result.filename}`));
+          console.log(chalk.gray('  Changes take effect immediately\n'));
+        } else if (result.error) {
+          console.log(chalk.yellow(`\n⚠️  ${result.error}`));
+          console.log(chalk.gray('  Keeping previous setting\n'));
+        } else {
+          console.log(chalk.gray('\n  No changes made\n'));
+        }
+
+      } else if (action === 'remove') {
+        // Remove custom music - keep defaults
+        const customMusicFiles = fsSync.existsSync(musicTracksDir) ?
+          fsSync.readdirSync(musicTracksDir) : [];
+
+        if (customMusicFiles.length === 0) {
+          console.log(chalk.yellow('\n⚠️  No custom music files found\n'));
+        } else {
+          const { confirm } = await inquirer.prompt([{
+            type: 'confirm',
+            name: 'confirm',
+            message: 'Remove all custom music files?',
+            default: false
+          }]);
+
+          if (confirm) {
+            try {
+              // Remove custom music files
+              for (const file of customMusicFiles) {
+                await fs.unlink(path.join(musicTracksDir, file));
+              }
+
+              // Reset to default music
+              await fs.writeFile(musicConfigFile, 'agentvibes_soft_flamenco_loop.mp3', { mode: 0o600 });
+
+              console.log(chalk.green('\n✓ Custom music removed, reverted to defaults\n'));
+            } catch (err) {
+              console.log(chalk.red(`\n❌ Error removing custom music: ${err.message}\n`));
+            }
+          } else {
+            console.log(chalk.gray('\n  Cancelled\n'));
+          }
+        }
+
+      } else if (action === 'reset') {
+        // Reset to factory defaults
+        const { confirm } = await inquirer.prompt([{
+          type: 'confirm',
+          name: 'confirm',
+          message: 'Reset all music settings to factory defaults?',
+          default: false
+        }]);
+
+        if (confirm) {
+          try {
+            // Reset to default track
+            await fs.writeFile(musicConfigFile, 'agentvibes_soft_flamenco_loop.mp3', { mode: 0o600 });
+
+            // Enable music
+            await fs.writeFile(musicEnabledFile, 'true', { mode: 0o644 });
+
+            console.log(chalk.green('\n✓ Reset to factory defaults'));
+            console.log(chalk.gray('  Track: Soft Flamenco (Spanish guitar)'));
+            console.log(chalk.gray('  Status: Enabled\n'));
+          } catch (err) {
+            console.log(chalk.red(`\n❌ Error resetting settings: ${err.message}\n`));
+          }
+        } else {
+          console.log(chalk.gray('\n  Cancelled\n'));
+        }
+
+      } else if (action === 'toggle') {
+        // Toggle music on/off
+        try {
+          const newState = !musicEnabled;
+          await fs.writeFile(musicEnabledFile, newState ? 'true' : 'false', { mode: 0o644 });
+
+          console.log(chalk.green(`\n✓ Background music ${newState ? 'enabled' : 'disabled'}\n`));
+        } catch (err) {
+          console.log(chalk.red(`\n❌ Error toggling music: ${err.message}\n`));
+        }
+
+      } else if (action === 'back') {
+        console.log(chalk.gray('\n  No changes made\n'));
+      }
+
+    } else {
+      console.log(chalk.red(`❌ Unknown setting: ${setting}`));
+      console.log(chalk.gray('Available settings: intro-text, music\n'));
+      process.exit(1);
+    }
+  });
+
 // BMAD PR Testing Command
 program
   .command('test-bmad-pr [pr-number]')
@@ -5096,5 +5767,11 @@ if (__entryFile === __argvFile) {
 }
 /* c8 ignore stop */
 
-// Export functions for testing
-export { isTermux, isNativeWindows, detectAndNotifyTermux };
+// Export functions for testing and TUI installer
+export {
+  isTermux, isNativeWindows, detectAndNotifyTermux,
+  copyCommandFiles, copyHookFiles, copyPersonalityFiles,
+  copyPluginFiles, copyBmadConfigFiles, copyBackgroundMusicFiles,
+  copyConfigFiles, configureSessionStartHook, ensureGitRepo,
+  installPluginManifest, checkAndInstallPiper,
+};