agentvibes 2.0.5 → 2.0.7

package/.claude/commands/agent-vibes/preview.md

@@ -1,16 +1,17 @@
 ---
-description: Preview ElevenLabs TTS voices by playing audio samples
+description: Preview TTS voices by playing audio samples (provider-aware)
 argument-hint: [voice_name|first|last] [N]
 ---
 
-Preview ElevenLabs TTS voices by playing audio samples.
+Preview TTS voices by playing audio samples from your active provider.
 
 Usage examples:
 - `/agent-vibes:preview` - Preview first 3 voices (default)
 - `/agent-vibes:preview 5` - Preview first 5 voices
-- `/agent-vibes:preview Jessica` - Preview Jessica Anne Bogart voice
+- `/agent-vibes:preview Jessica` - Preview Jessica Anne Bogart voice (ElevenLabs)
+- `/agent-vibes:preview lessac` - Preview Lessac voice (Piper)
 - `/agent-vibes:preview "Northern Terry"` - Preview Northern Terry voice
 - `/agent-vibes:preview first 10` - Preview first 10 voices
 - `/agent-vibes:preview last 5` - Preview last 5 voices
 
-!bash .claude/hooks/voice-manager.sh preview $ARGUMENTS
+!bash .claude/hooks/provider-commands.sh preview $ARGUMENTS

package/.claude/hooks/language-manager.sh

@@ -139,52 +139,54 @@ get_best_voice_for_language() {
     echo "${LANGUAGE_VOICES[$lang]}"
 }
 
-# Main command handler
-case "${1:-}" in
-    set)
-        if [[ -z "$2" ]]; then
-            echo "Usage: language-manager.sh set <language>"
+# Main command handler - only run if script is executed directly, not sourced
+if [[ "${BASH_SOURCE[0]}" == "${0}" ]]; then
+    case "${1:-}" in
+        set)
+            if [[ -z "$2" ]]; then
+                echo "Usage: language-manager.sh set <language>"
+                exit 1
+            fi
+            set_language "$2"
+            ;;
+        get)
+            get_language
+            ;;
+        code)
+            get_language_code
+            ;;
+        check-voice)
+            if [[ -z "$2" ]]; then
+                echo "Usage: language-manager.sh check-voice <voice-name>"
+                exit 1
+            fi
+            if is_voice_multilingual "$2"; then
+                echo "yes"
+            else
+                echo "no"
+            fi
+            ;;
+        best-voice)
+            get_best_voice_for_language
+            ;;
+        list)
+            echo "Supported languages and recommended voices:"
+            echo ""
+            for lang in "${!LANGUAGE_VOICES[@]}"; do
+                printf "%-15s → %s\n" "$lang" "${LANGUAGE_VOICES[$lang]}"
+            done | sort
+            ;;
+        *)
+            echo "AgentVibes Language Manager"
+            echo ""
+            echo "Usage:"
+            echo "  language-manager.sh set <language>     Set language"
+            echo "  language-manager.sh get                Get current language"
+            echo "  language-manager.sh code               Get language code only"
+            echo "  language-manager.sh check-voice <name> Check if voice is multilingual"
+            echo "  language-manager.sh best-voice         Get best voice for current language"
+            echo "  language-manager.sh list               List all supported languages"
             exit 1
-        fi
-        set_language "$2"
-        ;;
-    get)
-        get_language
-        ;;
-    code)
-        get_language_code
-        ;;
-    check-voice)
-        if [[ -z "$2" ]]; then
-            echo "Usage: language-manager.sh check-voice <voice-name>"
-            exit 1
-        fi
-        if is_voice_multilingual "$2"; then
-            echo "yes"
-        else
-            echo "no"
-        fi
-        ;;
-    best-voice)
-        get_best_voice_for_language
-        ;;
-    list)
-        echo "Supported languages and recommended voices:"
-        echo ""
-        for lang in "${!LANGUAGE_VOICES[@]}"; do
-            printf "%-15s → %s\n" "$lang" "${LANGUAGE_VOICES[$lang]}"
-        done | sort
-        ;;
-    *)
-        echo "AgentVibes Language Manager"
-        echo ""
-        echo "Usage:"
-        echo "  language-manager.sh set <language>     Set language"
-        echo "  language-manager.sh get                Get current language"
-        echo "  language-manager.sh code               Get language code only"
-        echo "  language-manager.sh check-voice <name> Check if voice is multilingual"
-        echo "  language-manager.sh best-voice         Get best voice for current language"
-        echo "  language-manager.sh list               List all supported languages"
-        exit 1
-        ;;
-esac
+            ;;
+    esac
+fi

package/.claude/hooks/piper-voice-manager.sh

@@ -17,11 +17,44 @@ PIPER_VOICES_BASE_URL="https://huggingface.co/rhasspy/piper-voices/resolve/main"
 # @why Voice models are large (~25MB each) and should be shared globally across all projects
 # @returns Echoes path to voice storage directory (~/.claude/piper-voices)
 # @sideeffects Creates directory if it doesn't exist
-# @architecture Always uses global storage to avoid redundant downloads per project
+# @architecture Supports custom path via PIPER_VOICES_DIR env var, defaults to global storage
 get_voice_storage_dir() {
-  # Always use global storage for voice models
-  # This prevents downloading 125MB+ of models into every project
-  local voice_dir="$HOME/.claude/piper-voices"
+  local voice_dir
+
+  # Check for custom path in environment or config file
+  if [[ -n "$PIPER_VOICES_DIR" ]]; then
+    voice_dir="$PIPER_VOICES_DIR"
+  else
+    # Check for config file (project-local first, then global)
+    local config_file
+    if [[ -n "$CLAUDE_PROJECT_DIR" ]] && [[ -f "$CLAUDE_PROJECT_DIR/.claude/piper-voices-dir.txt" ]]; then
+      config_file="$CLAUDE_PROJECT_DIR/.claude/piper-voices-dir.txt"
+    else
+      # Search up directory tree for .claude/
+      local current_dir="$PWD"
+      while [[ "$current_dir" != "/" ]]; do
+        if [[ -f "$current_dir/.claude/piper-voices-dir.txt" ]]; then
+          config_file="$current_dir/.claude/piper-voices-dir.txt"
+          break
+        fi
+        current_dir=$(dirname "$current_dir")
+      done
+
+      # Check global config
+      if [[ -z "$config_file" ]] && [[ -f "$HOME/.claude/piper-voices-dir.txt" ]]; then
+        config_file="$HOME/.claude/piper-voices-dir.txt"
+      fi
+    fi
+
+    if [[ -n "$config_file" ]]; then
+      voice_dir=$(cat "$config_file" | tr -d '[:space:]')
+    fi
+  fi
+
+  # Fallback to default global storage
+  if [[ -z "$voice_dir" ]]; then
+    voice_dir="$HOME/.claude/piper-voices"
+  fi
 
   mkdir -p "$voice_dir"
   echo "$voice_dir"

package/.claude/hooks/play-tts-piper.sh

@@ -32,7 +32,7 @@ DEFAULT_VOICE="en_US-lessac-medium"
 VOICE_MODEL=""
 
 # Get current language setting
-CURRENT_LANGUAGE=$(get_current_language)
+CURRENT_LANGUAGE=$(get_language_code)
 
 if [[ -n "$VOICE_OVERRIDE" ]]; then
   # Use override if provided

package/.claude/hooks/play-tts.sh

@@ -1,138 +1,40 @@
 #!/bin/bash
-# Quick TTS playback script with session-specific voice support
-# Usage: play-tts.sh "Text to speak" [voice_name_or_id]
 #
-# Examples:
-#   play-tts.sh "Hello world"                           # Uses default voice from voice manager
-#   play-tts.sh "Hello world" "Sarah"                   # Uses Sarah voice by name
-#   play-tts.sh "Hello world" "KTPVrSVAEUSJRClDzBw7"   # Uses voice by direct ID
+# @fileoverview TTS Provider Router
+# @context Routes TTS requests to active provider (ElevenLabs or Piper)
+# @architecture Provider abstraction layer - single entry point for all TTS
+# @dependencies provider-manager.sh, play-tts-elevenlabs.sh, play-tts-piper.sh
+# @entrypoints Called by hooks, slash commands, and personality-manager.sh
+# @patterns Provider pattern - delegates to provider-specific implementations
+# @related provider-manager.sh, play-tts-elevenlabs.sh, play-tts-piper.sh
 #
-# This allows different sessions to use different voices for easy identification!
 
 # Fix locale warnings
 export LC_ALL=C
 
 TEXT="$1"
-VOICE_OVERRIDE="$2"  # Optional: voice name or direct voice ID
-API_KEY="${ELEVENLABS_API_KEY}"
+VOICE_OVERRIDE="$2"  # Optional: voice name or ID
 
-# Check for project-local pretext configuration
-CONFIG_DIR="${CLAUDE_PROJECT_DIR:-.}/.claude/config"
-CONFIG_FILE="$CONFIG_DIR/agentvibes.json"
-
-if [[ -f "$CONFIG_FILE" ]] && command -v jq &> /dev/null; then
-  PRETEXT=$(jq -r '.pretext // empty' "$CONFIG_FILE" 2>/dev/null)
-  if [[ -n "$PRETEXT" ]]; then
-    TEXT="$PRETEXT: $TEXT"
-  fi
-fi
-
-# Limit text length to prevent API issues (max 500 chars for safety)
-if [ ${#TEXT} -gt 500 ]; then
-  TEXT="${TEXT:0:497}..."
-  echo "⚠️ Text truncated to 500 characters for API safety"
-fi
-
-# Source the single voice configuration file
+# Get script directory
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-source "$SCRIPT_DIR/voices-config.sh"
-
-# Determine which voice to use
-VOICE_ID=""
-
-if [[ -n "$VOICE_OVERRIDE" ]]; then
-  # Check if override is a voice name (lookup in mapping)
-  if [[ -n "${VOICES[$VOICE_OVERRIDE]}" ]]; then
-    VOICE_ID="${VOICES[$VOICE_OVERRIDE]}"
-    echo "🎤 Using voice: $VOICE_OVERRIDE (session-specific)"
-  # Check if override looks like a voice ID (alphanumeric string ~20 chars)
-  elif [[ "$VOICE_OVERRIDE" =~ ^[a-zA-Z0-9]{15,30}$ ]]; then
-    VOICE_ID="$VOICE_OVERRIDE"
-    echo "🎤 Using custom voice ID (session-specific)"
-  else
-    echo "⚠️ Unknown voice '$VOICE_OVERRIDE', using default"
-  fi
-fi
-
-# If no override or invalid override, use default from voice manager
-if [[ -z "$VOICE_ID" ]]; then
-  VOICE_MANAGER_SCRIPT="$(dirname "$0")/voice-manager.sh"
-  if [[ -f "$VOICE_MANAGER_SCRIPT" ]]; then
-    VOICE_NAME=$("$VOICE_MANAGER_SCRIPT" get)
-    VOICE_ID="${VOICES[$VOICE_NAME]}"
-  fi
-
-  # Final fallback to Cowboy Bob default
-  if [[ -z "$VOICE_ID" ]]; then
-    echo "⚠️ No voice configured, using Cowboy Bob default"
-    VOICE_ID="${VOICES[Cowboy Bob]}"
-  fi
-fi
-
-if [ -z "$TEXT" ]; then
-  echo "Usage: $0 \"text to speak\""
-  exit 1
-fi
-
-if [ -z "$API_KEY" ]; then
-  echo "Error: ELEVENLABS_API_KEY not set"
-  exit 1
-fi
-
-# Create audio file in project-local storage
-# Use project directory if available, otherwise fall back to global
-if [[ -n "$CLAUDE_PROJECT_DIR" ]]; then
-  AUDIO_DIR="$CLAUDE_PROJECT_DIR/.claude/audio"
-else
-  # Fallback: try to find .claude directory in current path
-  CURRENT_DIR="$PWD"
-  while [[ "$CURRENT_DIR" != "/" ]]; do
-    if [[ -d "$CURRENT_DIR/.claude" ]]; then
-      AUDIO_DIR="$CURRENT_DIR/.claude/audio"
-      break
-    fi
-    CURRENT_DIR=$(dirname "$CURRENT_DIR")
-  done
-  # Final fallback to global if no project .claude found
-  if [[ -z "$AUDIO_DIR" ]]; then
-    AUDIO_DIR="$HOME/.claude/audio"
-  fi
-fi
-
-mkdir -p "$AUDIO_DIR"
-TEMP_FILE="$AUDIO_DIR/tts-$(date +%s).mp3"
-
-# Generate audio
-curl -s -X POST "https://api.elevenlabs.io/v1/text-to-speech/${VOICE_ID}" \
-  -H "xi-api-key: ${API_KEY}" \
-  -H "Content-Type: application/json" \
-  -d "{\"text\":\"${TEXT}\",\"model_id\":\"eleven_monolingual_v1\",\"voice_settings\":{\"stability\":0.5,\"similarity_boost\":0.75}}" \
-  -o "${TEMP_FILE}"
-
-# Add silence padding to prevent WSL audio static
-if [ -f "${TEMP_FILE}" ]; then
-  # Check if ffmpeg is available for adding padding
-  if command -v ffmpeg &> /dev/null; then
-    PADDED_FILE="$AUDIO_DIR/tts-padded-$(date +%s).mp3"
-    # Add 200ms of silence at the beginning to prevent static
-    ffmpeg -f lavfi -i anullsrc=r=44100:cl=stereo:d=0.2 -i "${TEMP_FILE}" \
-      -filter_complex "[0:a][1:a]concat=n=2:v=0:a=1[out]" \
-      -map "[out]" -y "${PADDED_FILE}" 2>/dev/null
-
-    if [ -f "${PADDED_FILE}" ]; then
-      # Use padded file and clean up original
-      rm -f "${TEMP_FILE}"
-      TEMP_FILE="${PADDED_FILE}"
-    fi
-    # If padding failed, just use original file
-  fi
 
-  # Play audio (WSL/Linux) in background to avoid blocking
-  (paplay "${TEMP_FILE}" 2>/dev/null || aplay "${TEMP_FILE}" 2>/dev/null || mpg123 "${TEMP_FILE}" 2>/dev/null) &
-  # Keep temp files for later review - cleaned up weekly by cron
-  echo "🎵 Saved to: ${TEMP_FILE}"
-  echo "🎤 Voice used: ${VOICE_NAME} (${VOICE_ID})"
-else
-  echo "Failed to generate audio"
-  exit 1
-fi
+# Source provider manager to get active provider
+source "$SCRIPT_DIR/provider-manager.sh"
+
+# Get active provider
+ACTIVE_PROVIDER=$(get_active_provider)
+
+# Route to appropriate provider implementation
+case "$ACTIVE_PROVIDER" in
+  elevenlabs)
+    exec "$SCRIPT_DIR/play-tts-elevenlabs.sh" "$TEXT" "$VOICE_OVERRIDE"
+    ;;
+  piper)
+    exec "$SCRIPT_DIR/play-tts-piper.sh" "$TEXT" "$VOICE_OVERRIDE"
+    ;;
+  *)
+    echo "❌ Unknown provider: $ACTIVE_PROVIDER"
+    echo "   Run: /agent-vibes:provider list"
+    exit 1
+    ;;
+esac

package/.claude/hooks/provider-commands.sh

@@ -292,10 +292,49 @@ provider_preview() {
       ;;
     piper)
       # Use the Piper voice manager's list functionality
-      # For Piper, we'll list and play sample from available voices
       source "$SCRIPT_DIR/piper-voice-manager.sh"
 
-      # Play intro announcement
+      # Check if a specific voice was requested
+      local voice_arg="$1"
+
+      if [[ -n "$voice_arg" ]]; then
+        # User requested a specific voice - check if it's a valid Piper voice
+        # Piper voice names are like: en_US-lessac-medium
+        # Try to find a matching voice model
+
+        # Check if the voice arg looks like a Piper model name (contains underscores/hyphens)
+        if [[ "$voice_arg" =~ ^[a-z]{2}_[A-Z]{2}- ]]; then
+          # Looks like a Piper voice model name
+          if verify_voice "$voice_arg"; then
+            echo "🎤 Previewing Piper voice: $voice_arg"
+            echo ""
+            "$SCRIPT_DIR/play-tts.sh" "Hello, this is the $voice_arg voice. How do you like it?" "$voice_arg"
+          else
+            echo "❌ Voice model not found: $voice_arg"
+            echo ""
+            echo "💡 Piper voice names look like: en_US-lessac-medium"
+            echo "   Run /agent-vibes:list to see available Piper voices"
+          fi
+        else
+          # Looks like an ElevenLabs voice name (like "Antoni", "Jessica")
+          echo "❌ '$voice_arg' appears to be an ElevenLabs voice"
+          echo ""
+          echo "You're currently using Piper TTS (free provider)."
+          echo "Piper has different voices than ElevenLabs."
+          echo ""
+          echo "Options:"
+          echo "  1. Run /agent-vibes:list to see available Piper voices"
+          echo "  2. Switch to ElevenLabs: /agent-vibes:provider switch elevenlabs"
+          echo ""
+          echo "Popular Piper voices to try:"
+          echo "  • en_US-lessac-medium  (clear, professional)"
+          echo "  • en_US-amy-medium     (warm, friendly)"
+          echo "  • en_US-joe-medium     (casual, natural)"
+        fi
+        return
+      fi
+
+      # No specific voice - preview first 3 voices
       echo "🎤 Piper Preview of 3 people"
       echo ""
 

package/.claude/piper-voices-dir.txt

@@ -0,0 +1 @@
+/home/fire/.claude/piper-voices

package/README.md

@@ -11,7 +11,7 @@
 [![Publish](https://github.com/paulpreibisch/AgentVibes/actions/workflows/publish.yml/badge.svg)](https://github.com/paulpreibisch/AgentVibes/actions/workflows/publish.yml)
 [![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
 
-**Author**: Paul Preibisch ([@997Fire](https://x.com/997Fire)) | **Version**: v2.0.3
+**Author**: Paul Preibisch ([@997Fire](https://x.com/997Fire)) | **Version**: v2.0.7
 
 ---
 
@@ -45,7 +45,7 @@
 
 ## 📰 Latest Release
 
-**[v2.0.0 - The Multi-Provider Revolution](https://github.com/paulpreibisch/AgentVibes/releases/tag/v2.0.3)** 🎉
+**[v2.0.0 - The Multi-Provider Revolution](https://github.com/paulpreibisch/AgentVibes/releases/tag/v2.0.7)** 🎉
 
 The biggest update ever! **Multi-provider TTS support** (ElevenLabs + Piper TTS), **30+ languages**, expanded voice library (27+ voices), advanced sentiment system, enhanced BMAD integration, and comprehensive multilingual support. Choose between premium ElevenLabs voices or free offline Piper TTS!
 

package/RELEASE_NOTES.md

@@ -1,5 +1,207 @@
 # 🎤 AgentVibes Release Notes
 
+## 📦 v2.0.7 - Bug Fixes & UX Improvements (2025-01-07)
+
+### 🤖 AI Summary
+
+This patch release fixes critical issues with the voice preview command and significantly improves the installer UX. The `/agent-vibes:preview` command now correctly handles provider-specific voices and provides helpful guidance when users try to preview voices from the wrong provider. The installer adds interactive provider selection with automatic API key setup and shell configuration, making first-time setup much smoother.
+
+### 🐛 Bug Fixes
+
+#### Voice Preview Command Fixed
+- **Fixed provider-aware voice previewing** - The `/agent-vibes:preview` command now correctly routes through the provider system instead of directly calling ElevenLabs-specific code
+- **Intelligent voice detection** - Detects when you try to preview an ElevenLabs voice (like "Antoni") while using Piper and provides helpful guidance with alternatives
+- **Support for specific voice previews** - Can now preview individual Piper voices by model name (e.g., `/agent-vibes:preview en_US-lessac-medium`)
+- **Fixed language-manager error** - Resolved issue where sourcing `language-manager.sh` would trigger unwanted command handler execution showing "AgentVibes Language Manager" usage text
+- **Fixed function name mismatch** - Corrected `get_current_language` to `get_language_code` in play-tts-piper.sh
+
+#### Provider Routing Improvements
+- **Simplified play-tts.sh router** - Streamlined routing logic for cleaner provider delegation
+- **Fixed provider routing** - Ensures TTS requests always route to the active provider correctly
+- **Better error handling** - Clear, helpful messages when voice/provider mismatch occurs
+
+### ✨ Installer UX Enhancements
+
+#### Interactive Provider Selection
+- **Provider choice prompt** - Installer now asks which TTS provider you want (Piper or ElevenLabs) with clear descriptions
+- **Automatic API key setup** - Detects your shell (bash/zsh) and offers to add ELEVENLABS_API_KEY to shell config file
+- **Shell detection** - Intelligently detects whether you're using bash or zsh and configures the correct file
+- **Multiple setup paths** - Choose between automatic shell config, manual setup, or skip API key configuration
+- **Piper voices path configuration** - Added prompt for custom Piper voice storage location
+
+#### Clearer Installation Messaging
+- **Better location explanation** - Clear explanation of why AgentVibes installs in `.claude/` directory (Claude Code auto-discovery)
+- **Removed confusing prompts** - Simplified installation directory selection to avoid confusion
+- **Better confirmation flow** - Two-step confirmation: location first, then provider/installation
+- **Installation summary** - Shows exactly what will be installed before proceeding
+
+### 🔧 Update Command Improvements
+
+- **Fixed version display** - Update command now correctly shows v2.0.x instead of v1.1.3
+- **Synced with install command** - Both install and update commands now show identical release notes and formatting
+- **Directory filtering** - Properly filters out directories when counting hooks and personalities
+- **Consistent formatting** - Matches install command's beautiful display style
+
+### 🛠️ Code Quality
+
+- **Fixed undefined variable** - Replaced `srcPersonalityFiles` with correct variable name
+- **Proper scope management** - Moved `piperVoicesPath` declaration to correct scope to avoid undefined errors
+- **Command handler isolation** - Wrapped language-manager.sh case statement to only run when executed directly, not when sourced
+
+---
+
+### 📊 Changes Summary
+
+**Files Modified:** 8 files
+- `.claude/commands/agent-vibes/preview.md` - Provider-aware routing
+- `.claude/hooks/language-manager.sh` - Command handler isolation fix
+- `.claude/hooks/play-tts-piper.sh` - Function name correction
+- `.claude/hooks/play-tts.sh` - Simplified router
+- `.claude/hooks/provider-commands.sh` - Enhanced Piper preview support
+- `src/installer.js` - Interactive setup & UX improvements
+- `.claude/commands/release.md` - Documentation update
+- `.claude/piper-voices-dir.txt` - Storage config
+
+**Lines Changed:**
+- Added: 275 lines
+- Removed: 354 lines
+- Net: -79 lines (cleaner codebase!)
+
+---
+
+### 🎯 What's Improved
+
+#### For New Users
+- **Much easier setup** - Interactive prompts guide you through provider selection and API key configuration
+- **Clearer explanations** - Better messaging about where files are installed and why (Claude Code auto-discovery)
+- **Faster onboarding** - Shell detection and automatic config file modification save manual steps
+
+#### For Existing Users
+- **Preview command works correctly** - No more language-manager errors when previewing voices
+- **Provider switching is seamless** - Better error messages when voice/provider mismatch occurs
+- **Update command is accurate** - Shows correct version and release notes instead of old v1.1.3
+
+#### For Developers
+- **Cleaner codebase** - Removed 79 lines of unnecessary code
+- **Better separation of concerns** - Command handlers only run when appropriate
+- **Improved maintainability** - More consistent code patterns across scripts
+
+---
+
+### 🔧 Technical Details
+
+#### Provider Preview Architecture
+The preview command now uses a three-tier detection system:
+
+1. **ElevenLabs Provider**: Routes to `voice-manager.sh preview` for ElevenLabs voice listing
+2. **Piper Provider with voice arg**:
+   - Detects Piper voice format (`en_US-*-medium`)
+   - Detects ElevenLabs voice names (shows helpful error with alternatives)
+   - Validates voice model exists before previewing
+3. **Piper Provider without args**: Shows first 3 sample voices (Lessac, Amy, Joe)
+
+#### Language Manager Fix
+The `language-manager.sh` script now checks if it's being executed directly vs sourced:
+
+```bash
+if [[ "${BASH_SOURCE[0]}" == "${0}" ]]; then
+    # Only run command handler when executed directly
+    case "${1:-}" in
+        set|get|code|check-voice|best-voice|list)
+            # Handle commands
+        ;;
+    esac
+fi
+```
+
+This prevents the case statement from executing when the script is sourced by other scripts like `play-tts-piper.sh`.
+
+#### Installer Flow
+```
+1. Show installation details and location
+2. Provider selection (Piper/ElevenLabs)
+   ├─ If ElevenLabs: Check for API key
+   │  ├─ Detect shell (bash/zsh)
+   │  ├─ Offer to add to shell config
+   │  ├─ Manual setup option
+   │  └─ Skip option
+   └─ If Piper: Ask for voice storage path
+3. Explain .claude/ installation location with reasoning
+4. Confirm installation location
+5. Show installation summary
+6. Final confirmation
+7. Install all files
+8. Show success summary with next steps
+```
+
+---
+
+### 💡 Usage Examples
+
+#### Preview Commands
+```bash
+# Preview with Piper (no args = first 3 voices)
+/agent-vibes:preview
+
+# Preview specific Piper voice
+/agent-vibes:preview en_US-lessac-medium
+
+# Try to preview ElevenLabs voice while using Piper
+/agent-vibes:preview Antoni
+# ❌ 'Antoni' appears to be an ElevenLabs voice
+# You're currently using Piper TTS (free provider).
+# Options:
+#   1. Run /agent-vibes:list to see available Piper voices
+#   2. Switch to ElevenLabs: /agent-vibes:provider switch elevenlabs
+```
+
+#### Installer Provider Selection
+```bash
+npx agentvibes install
+
+# 🎭 Choose Your TTS Provider:
+# ? Which TTS provider would you like to use?
+#   🆓 Piper TTS (Free, Offline) - 50+ neural voices, no API key needed
+#   🎤 ElevenLabs (Premium) - 150+ AI voices, requires API key
+```
+
+---
+
+### 📦 Upgrade Notes
+
+**From v2.0.6:**
+```bash
+npm update -g agentvibes
+# or
+/agent-vibes:update
+```
+
+**No breaking changes** - This is a pure bug fix and UX improvement release. All existing configurations, voices, personalities, and settings are preserved.
+
+---
+
+### 🙏 Credits
+
+- **Voice Preview Fix**: Resolved GitHub issue reported by users experiencing language-manager errors
+- **Provider Architecture**: Multi-provider system improvements continue to mature
+- **Installer UX**: Community feedback on first-time setup experience led to these improvements
+
+---
+
+### 📚 Resources
+
+- **Documentation**: https://agentvibes.org
+- **GitHub**: https://github.com/paulpreibisch/AgentVibes
+- **Issues**: https://github.com/paulpreibisch/AgentVibes/issues
+
+---
+
+🤖 Generated with [Claude Code](https://claude.com/claude-code)
+
+Co-Authored-By: Claude <noreply@anthropic.com>
+
+---
+
 ## 📦 v1.1.3 - Symlink Support & Audio Fixes (2025-10-04)
 
 ### 🤖 AI Summary

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "agentvibes",
-  "version": "2.0.5",
+  "version": "2.0.7",
   "description": "Bring your Claude Code sessions to life with voice! Professional TTS narration with multi-provider support.",
   "homepage": "https://agentvibes.org",
   "keywords": [