agentvibes 2.14.13 → 2.14.14

package/.claude/hooks/stop.sh

@@ -0,0 +1,221 @@
+#!/usr/bin/env bash
+#
+# File: .claude/hooks/user-prompt-output.sh
+#
+# AgentVibes - Finally, your AI Agents can Talk Back! Text-to-Speech WITH personality for AI Assistants!
+# Website: https://agentvibes.org
+# Repository: https://github.com/paulpreibisch/AgentVibes
+#
+# Co-created by Paul Preibisch with Claude AI
+# Copyright (c) 2025 Paul Preibisch
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+# DISCLAIMER: This software is provided "AS IS", WITHOUT WARRANTY OF ANY KIND,
+# express or implied, including but not limited to the warranties of
+# merchantability, fitness for a particular purpose and noninfringement.
+# In no event shall the authors or copyright holders be liable for any claim,
+# damages or other liability, whether in an action of contract, tort or
+# otherwise, arising from, out of or in connection with the software or the
+# use or other dealings in the software.
+#
+# ---
+#
+# @fileoverview Auto-detects emoji markers and BMAD party mode in Claude's output and triggers TTS
+# @context Implements verbosity system by detecting 💭 🤔 ✓ markers and BMAD party mode agent dialogues
+# @architecture Stdin reader, regex matcher, async TTS trigger, agent voice switching
+# @dependencies play-tts.sh, tts-verbosity.txt, bmad-voice-manager.sh, .bmad/_cfg/agent-manifest.csv
+# @entrypoints Called by Claude Code after each assistant response (user-prompt-output hook)
+# @patterns Text stream processing, background job execution, marker-based triggers, party mode detection
+# @related session-start-tts.sh, verbosity-manager.sh, bmad-voice-manager.sh, Issue #32, Issue #33
+# @aiNotes This hook enables natural emoji-based TTS + BMAD party mode voice switching
+
+# Fix locale warnings
+export LC_ALL=C
+
+# Get script directory and project root
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
+PLAY_TTS="$SCRIPT_DIR/play-tts.sh"
+
+# Read JSON input from stdin
+INPUT=$(cat)
+
+# Extract transcript path from JSON
+TRANSCRIPT_PATH=$(echo "$INPUT" | grep -o '"transcript_path":"[^"]*"' | cut -d'"' -f4)
+
+# If no transcript path, exit (shouldn't happen but be safe)
+[[ -z "$TRANSCRIPT_PATH" || ! -f "$TRANSCRIPT_PATH" ]] && exit 0
+
+# Get the last assistant message from transcript
+# The transcript is JSONL format - each line is a JSON object
+# Extract all text content blocks from the last message and join them
+LAST_RESPONSE=$(tail -1 "$TRANSCRIPT_PATH" | jq -r '.message.content[] | select(.type == "text") | .text' 2>/dev/null)
+
+# Get verbosity level
+VERBOSITY=$(cat "$PROJECT_ROOT/.claude/tts-verbosity.txt" 2>/dev/null || cat ~/.claude/tts-verbosity.txt 2>/dev/null || echo "low")
+
+# Exit early if play-tts.sh doesn't exist (AgentVibes not installed)
+[[ ! -f "$PLAY_TTS" ]] && exit 0
+
+#
+# @function extract_and_speak
+# @context Extracts text after emoji markers and triggers TTS asynchronously
+# @architecture Uses grep to find markers, extracts text, launches TTS in background
+# @dependencies play-tts.sh
+# @entrypoints Called based on verbosity level
+# @aiNotes Background execution (&) prevents blocking Claude's output
+#
+extract_and_speak() {
+  local pattern="$1"
+
+  # Extract lines matching the pattern
+  # Pattern format: "emoji text" or "emoji [text]"
+  while IFS= read -r line; do
+    # Try to extract text after emoji
+    # Handles formats: "💭 text", "💭 [text]", "💭text"
+    if echo "$line" | grep -qE "$pattern"; then
+      # Extract everything after the emoji (and optional space/bracket)
+      text=$(echo "$line" | sed -E "s/^.*($pattern)[[:space:]]*\[?[[:space:]]*//" | sed 's/\]$//')
+
+      # Skip if text is empty or too short
+      [[ -z "$text" || ${#text} -lt 3 ]] && continue
+
+      # Speak it in background (don't block)
+      bash "$PLAY_TTS" "$text" >/dev/null 2>&1 &
+    fi
+  done <<< "$LAST_RESPONSE"
+}
+
+#
+# @function is_party_mode_enabled
+# @context Check if BMAD party mode voice integration is enabled
+# @architecture Auto-enable for BMAD users, opt-out via disable flag
+# @dependencies .bmad/_cfg/agent-manifest.csv, .claude/config/bmad-voices-enabled.flag
+# @returns 0=enabled, 1=disabled
+# @aiNotes Auto-enabled when BMAD detected, respects opt-out flag for user control
+#
+is_party_mode_enabled() {
+  # Explicit opt-out takes precedence
+  [[ -f "$PROJECT_ROOT/.claude/plugins/bmad-party-mode-disabled.flag" ]] && return 1
+
+  # Auto-enable if BMAD detected + voice plugin enabled
+  if [[ -f "$PROJECT_ROOT/.bmad/_cfg/agent-manifest.csv" ]] && \
+     [[ -f "$PROJECT_ROOT/.claude/config/bmad-voices-enabled.flag" ]]; then
+    return 0
+  fi
+
+  return 1
+}
+
+#
+# @function map_display_name_to_agent_id
+# @context Map BMAD agent display name to agent ID for voice lookup
+# @architecture Parses agent-manifest.csv, matches displayName column to name column
+# @dependencies .bmad/_cfg/agent-manifest.csv
+# @param $1 Display name (e.g., "Winston", "John", "Amelia")
+# @returns Agent ID (e.g., "architect", "pm", "dev") or empty string if not found
+# @aiNotes Case-insensitive matching, handles quoted CSV values
+#
+map_display_name_to_agent_id() {
+  local display_name="$1"
+
+  # Check for BMAD v6 manifest
+  if [[ ! -f "$PROJECT_ROOT/.bmad/_cfg/agent-manifest.csv" ]]; then
+    return 1
+  fi
+
+  # CSV format: name,displayName,title,icon,role,...
+  # Extract 'name' (column 1) where displayName (column 2) matches
+  # Case-insensitive grep, remove quotes, get first match
+  local agent_id=$(grep -i ",\"*${display_name}\"*," "$PROJECT_ROOT/.bmad/_cfg/agent-manifest.csv" | \
+                   head -1 | \
+                   cut -d',' -f1 | \
+                   tr -d '"')
+
+  echo "$agent_id"
+}
+
+#
+# @function detect_and_speak_party_mode_dialogue
+# @context Detect BMAD party mode agent responses and speak with agent-specific voices
+# @architecture Pattern matches [Agent Name]: format, maps to agent voice, triggers TTS
+# @dependencies map_display_name_to_agent_id, bmad-voice-manager.sh, play-tts.sh
+# @aiNotes Runs in background to avoid blocking, graceful fallback for unmapped agents
+#
+detect_and_speak_party_mode_dialogue() {
+  # Pattern: [Agent Name]: dialogue
+  # Must start at beginning of line, agent name can include spaces/hyphens
+  while IFS= read -r line; do
+    if echo "$line" | grep -qE '^\[([A-Za-z\s-]+)\]:'; then
+      # Extract agent display name and dialogue
+      local agent_name=$(echo "$line" | sed -E 's/^\[([A-Za-z\s-]+)\]:.*/\1/')
+      local dialogue=$(echo "$line" | sed -E 's/^\[[^]]+\]:[[:space:]]*//')
+
+      # Skip if dialogue is empty or too short
+      [[ -z "$dialogue" || ${#dialogue} -lt 3 ]] && continue
+
+      # Map display name to agent ID
+      local agent_id=$(map_display_name_to_agent_id "$agent_name")
+
+      # Get agent's voice from bmad-voice-manager.sh
+      local agent_voice=""
+      if [[ -n "$agent_id" ]] && [[ -f "$SCRIPT_DIR/bmad-voice-manager.sh" ]]; then
+        agent_voice=$("$SCRIPT_DIR/bmad-voice-manager.sh" get-voice "$agent_id" 2>/dev/null)
+      fi
+
+      # Speak with agent's voice (or default if not mapped)
+      # Run in foreground to ensure audio completes
+      if [[ -n "$agent_voice" ]]; then
+        bash "$PLAY_TTS" "$dialogue" "$agent_voice" &
+      else
+        # Fallback to default voice if agent not in voice mapping
+        bash "$PLAY_TTS" "$dialogue" &
+      fi
+    fi
+  done
+}
+
+# Process based on verbosity level
+case "$VERBOSITY" in
+  high)
+    # HIGH: Speak ALL markers (💭 🤔 ✓)
+    # Don't speak ✅ here - that's handled by manual TTS completion call
+    extract_and_speak "💭|🤔|✓"
+    ;;
+
+  medium)
+    # MEDIUM: Speak decisions and findings (🤔 ✓)
+    extract_and_speak "🤔|✓"
+    ;;
+
+  low)
+    # LOW: No automatic extraction (only manual ACK/COMPLETE TTS calls)
+    # Don't process any markers
+    ;;
+esac
+
+# BMAD Party Mode Integration (Issue #33)
+# Auto-enabled for BMAD users, opt-out available
+if is_party_mode_enabled; then
+  # Detect party mode activation announcement
+  if echo "$LAST_RESPONSE" | grep -q "🎉 PARTY MODE ACTIVATED! 🎉"; then
+    bash "$PLAY_TTS" "Party Mode Activated! All agents are here for a group discussion!" &
+  fi
+
+  # Detect agent dialogues
+  echo "$LAST_RESPONSE" | detect_and_speak_party_mode_dialogue
+fi
+
+# Exit successfully
+exit 0

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

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

package/.mcp.json

@@ -0,0 +1,88 @@
+{
+  "mcpServers": {
+    "sentry": {
+      "command": "npx",
+      "args": [
+        "@sentry/mcp-server@latest",
+        "--host=sentry.io"
+      ],
+      "env": {
+        "SENTRY_ACCESS_TOKEN": "${SENTRY_ACCESS_TOKEN}",
+        "OPENAI_API_KEY": "${OPENAI_API_KEY}"
+      }
+    },
+     "whatsapp": {
+      "command": "/home/fire/.local/bin/uv",
+      "args": [
+        "--directory",
+        "/home/fire/claude/whatsapp-mcp/whatsapp-mcp-server",
+        "run",
+        "main.py"
+      ]
+    },
+     "chrome-devtools": {
+      "command": "/home/fire/.nvm/versions/node/v22.20.0/bin/npx",
+      "args": [
+        "chrome-devtools-mcp@latest",
+        "--browserUrl=http://localhost:9222"
+      ],
+      "env": {
+        "PATH": "/home/fire/.nvm/versions/node/v22.20.0/bin:${PATH}",
+        "NODE_PATH": "/home/fire/.nvm/versions/node/v22.20.0/lib/node_modules"
+      }
+    },
+    "obsidian": {
+      "command": "/home/fire/.local/bin/uv",
+      "args": [
+        "--directory",
+        "/home/fire/claude/mcp_obsidian",
+        "run",
+        "mcp-obsidian"
+      ],
+      "env": {
+        "OBSIDIAN_API_KEY": "${MAIN_VAULT_OBSIDIAN_KEY}",
+        "OBSIDIAN_HOST": "${OBSIDIAN_HOST:-127.0.0.1}",
+        "OBSIDIAN_PORT": "27124",
+        "OBSIDIAN_HTTPS": "true",
+        "OBSIDIAN_VERIFY_SSL": "false"
+      }
+    },
+    "elevenlabs": {
+      "command": "npx",
+      "args": ["@microagents/mcp-server-elevenlabs"],
+      "env": {
+        "ELEVENLABS_API_KEY": "${ELEVENLABS_API_KEY}",
+        "ELEVENLABS_MCP_BASE_PATH": "/home/fire/claude/SoraSage/teams/team-10/dev__globify__production/.claude/audio"
+      }
+    },
+    "spaceship": {
+      "command": "node",
+      "args": [
+        "/home/fire/claude/spaceship-mcp/dist/index.js"
+      ],
+      "env": {
+        "SPACESHIP_API_KEY": "${SPACESHIP_API_KEY}",
+        "SPACESHIP_API_SECRET": "${SPACESHIP_API_SECRET}"
+      }
+    },
+    "sonarqube": {
+      "command": "docker",
+      "args": [
+        "run",
+        "-i",
+        "--name",
+        "sonarqube-mcp-server-agentvibes",
+        "--rm",
+        "-e",
+        "SONARQUBE_TOKEN",
+        "-e",
+        "SONARQUBE_ORG",
+        "mcp/sonarqube"
+      ],
+      "env": {
+        "SONARQUBE_TOKEN": "${AGENTVIBES_SONARQUBE_TOKEN}",
+        "SONARQUBE_ORG": "${AGENTVIBES_SONARQUBE_ORG}"
+      }
+    }
+  }
+}

package/README.md

@@ -4,14 +4,14 @@
 >
 > 🌐 **[agentvibes.org](https://agentvibes.org)**
 >
-> Professional text-to-speech for **Claude Code**, **Claude Desktop**, and **Warp Terminal** - **ElevenLabs AI**, **Piper TTS (Free!)**, or **macOS Say (Built-in!)**
+> Professional text-to-speech for **Claude Code**, **Claude Desktop**, and **Warp Terminal** - **[ElevenLabs AI](https://try.elevenlabs.io/agentvibes)**, **Piper TTS (Free!)**, or **macOS Say (Built-in!)**
 
 [![npm version](https://img.shields.io/npm/v/agentvibes)](https://www.npmjs.com/package/agentvibes)
 [![Test Suite](https://github.com/paulpreibisch/AgentVibes/actions/workflows/test.yml/badge.svg)](https://github.com/paulpreibisch/AgentVibes/actions/workflows/test.yml)
 [![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.14.13
+**Author**: Paul Preibisch ([@997Fire](https://x.com/997Fire)) | **Version**: v2.14.14
 
 ---
 
@@ -40,7 +40,7 @@ Whether you're coding in Claude Code, chatting in Claude Desktop, or using Warp
 - 🎙️ **AgentVibes MCP** - **NEW!** Natural language control for Claude Code, Claude Desktop & Warp (no slash commands!)
 - 📚 **Language Learning Mode** - **NEW!** Learn a second language while you program (e.g., Learn Spanish as you code!)
 - 🔊 **SSH Audio Optimization** - **NEW!** Auto-detects remote sessions and eliminates static (VS Code Remote SSH, cloud dev)
-- 🎭 **Multi-Provider Support** - Choose ElevenLabs (150+ premium voices), Piper TTS (50+ free voices), or macOS Say (100+ built-in voices)
+- 🎭 **Multi-Provider Support** - Choose [ElevenLabs](https://try.elevenlabs.io/agentvibes) (150+ premium voices), Piper TTS (50+ free voices), or macOS Say (100+ built-in voices)
 - 🌍 **30+ Languages** - Multilingual support with native voice quality
 - 🎙️ **27+ Professional AI Voices** - Character voices, accents, and unique personalities
 - 🎭 **19 Built-in Personalities** - From sarcastic to flirty, pirate to dry humor
@@ -94,15 +94,15 @@ Whether you're coding in Claude Code, chatting in Claude Desktop, or using Warp
 
 ## 📰 Latest Release
 
-**[v2.14.13 - Free Providers as Default](https://github.com/paulpreibisch/AgentVibes/releases/tag/v2.14.13)** 🎉
+**[v2.14.14 - Test Suite Fixes & Affiliate Links](https://github.com/paulpreibisch/AgentVibes/releases/tag/v2.14.14)** 🎉
 
-AgentVibes v2.14.13 changes the `--yes` flag to always use free TTS providers by default. No more failures from expired ElevenLabs API keys! macOS defaults to macOS Say, Linux defaults to Piper TTS.
+AgentVibes v2.14.14 fixes critical test suite failures from voice names with spaces causing bash syntax errors. Also adds ElevenLabs affiliate links and requires tests to pass before releases.
 
 **Key Highlights:**
-- 🆓 **Free-First Defaults** - `--yes` flag now always picks free providers
-- 🍎 **macOS Default** - macOS Say (built-in, zero setup)
-- 🐧 **Linux Default** - Piper TTS (free, offline)
-- 🎤 **ElevenLabs Manual** - Requires interactive selection (no more expired key failures)
+- 🐛 **Test Fix** - Fixed syntax errors from voice names with spaces in bash
+- 🧪 **CI/CD** - All 132 bats + 12 Node.js tests now pass
+- 📚 **Release Safety** - `/release` command now requires tests to pass first
+- 🔗 **Affiliate Links** - ElevenLabs URLs updated to affiliate link
 
 💡 **Tip:** If `npx agentvibes` shows an older version or missing commands, clear your npm cache: `npm cache clean --force && npx agentvibes@latest --help`
 
@@ -172,7 +172,7 @@ npx agentvibes install
 |----------|----------|------|---------|-------|
 | **macOS Say** | macOS only | Free (built-in) | ⭐⭐⭐⭐ | Zero config |
 | **Piper** | Linux/WSL | Free | ⭐⭐⭐⭐ | Auto-downloads |
-| **ElevenLabs** | All | Free tier + paid | ⭐⭐⭐⭐⭐ | API key required |
+| **[ElevenLabs](https://try.elevenlabs.io/agentvibes)** | All | Free tier + paid | ⭐⭐⭐⭐⭐ | [API key required](https://try.elevenlabs.io/agentvibes) |
 
 On macOS, the native `say` provider is automatically detected and recommended!
 
@@ -279,7 +279,7 @@ Every task acknowledgment plays **twice** - first in English, then in your targe
 
 ## 🗣️ Voice Library
 
-AgentVibes includes **27 unique ElevenLabs voices** with multilingual support.
+AgentVibes includes **27 unique [ElevenLabs](https://try.elevenlabs.io/agentvibes) voices** with multilingual support.
 
 💡 **Tip:** Click voice names to hear samples on ElevenLabs!
 🎧 **Try in Claude Code:** `/agent-vibes:preview` to hear all voices
@@ -382,7 +382,7 @@ AgentVibes supports **custom personalities** and **custom voices**.
 
 - 🎤 **[WhisperTyping](https://whispertyping.com/)** - Fast voice-to-text typing for developers
 - 🗣️ **[OpenWhisper (Azure)](https://learn.microsoft.com/en-us/azure/ai-services/speech-service/whisper-overview)** - Microsoft's speech-to-text service
-- 🎙️ **[ElevenLabs](https://elevenlabs.io/)** - Premium AI voice synthesis
+- 🎙️ **[ElevenLabs](https://try.elevenlabs.io/agentvibes)** - Premium AI voice synthesis
 - 🆓 **[Piper TTS](https://github.com/rhasspy/piper)** - Free offline neural TTS
 - 🤖 **[Claude Code](https://claude.com/claude-code)** - AI coding assistant
 - 🎭 **[BMAD METHOD](https://github.com/bmad-code-org/BMAD-METHOD)** - Multi-agent framework

package/RELEASE_NOTES.md

@@ -1,3 +1,82 @@
+# Release v2.14.14 - Test Suite Fixes & Affiliate Links
+
+**Release Date:** 2025-12-01
+**Type:** Patch Release (Bug Fix + Documentation)
+
+## AI Summary
+
+AgentVibes v2.14.14 fixes critical test suite failures that were blocking CI/CD pipelines. The root cause was the `voices-config.sh` refactoring for bash 3.2 (macOS) compatibility - it switched from associative arrays to functions, but some files still used the old syntax. Voice names with spaces like "Ralf Eisend" and "Cowboy Bob" caused syntax errors. This release also adds ElevenLabs affiliate links and makes the `/release` command require passing tests before publishing.
+
+**Key Highlights:**
+- 🐛 **Test Fix** - Fixed syntax errors from voice names with spaces in bash
+- 🧪 **CI/CD** - All 132 bats + 12 Node.js tests now pass
+- 📚 **Release Safety** - `/release` command now requires tests to pass first
+- 🔗 **Affiliate Links** - ElevenLabs URLs updated to affiliate link
+
+---
+
+## Bug Fixes
+
+### Voice Lookup Syntax Errors
+**Files:** `.claude/hooks/play-tts-elevenlabs.sh`, `test/unit/personality-voice-mapping.bats`
+
+The `voices-config.sh` was refactored to use functions (`get_voice_id()`) instead of associative arrays for bash 3.2 compatibility. However, two files still used the old `${VOICES[...]}` syntax:
+
+```bash
+# Before: Caused syntax errors with spaced names
+if [[ -n "${VOICES[$VOICE_OVERRIDE]}" ]]; then
+  VOICE_ID="${VOICES[$VOICE_OVERRIDE]}"
+# Error: "syntax error in expression (error token is "Eisend")"
+```
+
+**Fix:** Updated to use the new function-based lookup:
+
+```bash
+# After: Works with all voice names
+OVERRIDE_VOICE_ID=$(get_voice_id "$VOICE_OVERRIDE")
+if [[ -n "$OVERRIDE_VOICE_ID" ]]; then
+  VOICE_ID="$OVERRIDE_VOICE_ID"
+```
+
+---
+
+## Documentation Updates
+
+### Release Workflow Safety
+**File:** `.claude/commands/release.md`
+
+Added mandatory test suite execution as the first step of the release process. If any tests fail, the release is immediately aborted to prevent publishing broken code to npm.
+
+### ElevenLabs Affiliate Links
+**Files:** `README.md`, `src/installer.js`, `mcp-server/docs/elevenlabs-setup.md`
+
+Updated ElevenLabs URLs to use affiliate link (`https://try.elevenlabs.io/agentvibes`) for sign-up references while keeping functional links (dashboard, pricing, privacy) pointing to their actual pages.
+
+---
+
+## Files Modified
+
+| File | Changes |
+|------|---------|
+| `.claude/hooks/play-tts-elevenlabs.sh` | Fixed voice lookup to use `get_voice_id()` function |
+| `test/unit/personality-voice-mapping.bats` | Fixed test assertions to use `get_voice_id()` function |
+| `.claude/commands/release.md` | Added mandatory test requirement before release |
+| `README.md` | Added ElevenLabs affiliate links |
+| `src/installer.js` | Added ElevenLabs affiliate link to API key prompt |
+| `mcp-server/docs/elevenlabs-setup.md` | Added ElevenLabs affiliate link to setup guide |
+
+---
+
+## Upgrade
+
+```bash
+npx agentvibes update
+```
+
+---
+
+---
+
 # Release v2.14.13 - Free Providers as Default
 
 **Release Date:** 2025-12-01

package/RELEASE_NOTES_v2.4.0_DRAFT.md

@@ -0,0 +1,116 @@
+# Release v2.4.0 - macOS Piper TTS Support (2025-01-15)
+
+## 🤖 AI Summary
+
+This minor release brings **full Piper TTS support to macOS** via precompiled binaries, eliminating the Python dependency conflicts that previously prevented macOS users from using free offline TTS. Mac users can now install Piper TTS with zero Python dependencies - just download and run! The installer automatically detects your Mac architecture (Intel or Apple Silicon) and downloads the appropriate binary. This release also includes comprehensive GitHub Actions CI testing to validate Piper installation across all macOS versions (13, 14, 15) and both architectures.
+
+## 📋 Changes
+
+### ✨ New Features
+- **macOS Piper TTS Support via Precompiled Binaries**
+  - Downloads official Piper binaries from rhasspy/piper releases
+  - Automatic architecture detection (Apple Silicon M1/M2/M3 vs Intel)
+  - Installs to `~/.local/bin/piper` with no Python dependencies
+  - Zero pipx or pip conflicts - pure binary installation
+  - Supports both `arm64` (Apple Silicon) and `x86_64` (Intel) architectures
+
+- **Comprehensive macOS CI Testing**
+  - Tests Piper binary installation on macOS 13, 14, and 15
+  - Tests user-reported `--no-deps` pip workaround method
+  - Validates both Intel and Apple Silicon architectures
+  - Confirms standard pipx failure and binary success
+  - Runs across 9 macOS configurations (3 OS × 3 Node versions)
+
+### 🐛 Bug Fixes
+- **Fixed macOS Piper Installation Failures**
+  - Resolved pipx dependency conflict issues reported by users
+  - Removed incorrect platform restriction blocking macOS
+  - Fixed "Piper TTS is only supported on WSL and Linux" error
+
+### 📚 Documentation
+- **Updated Provider Documentation**
+  - Corrected platform support matrix to include macOS
+  - Added macOS-specific installation requirements
+  - Clarified binary vs pipx installation methods
+  - Updated "Choose Piper TTS if" section with macOS callout
+
+- **Installer Script Documentation**
+  - Added platform detection logic documentation
+  - Documented binary download and extraction process
+  - Added PATH setup instructions for macOS users
+
+### 🔧 Maintenance
+- **Refactored Release Process**
+  - Extracted `showReleaseInfo()` function for code reuse
+  - Added critical ordering warning to `/release` command
+  - Documented README update before npm publish requirement
+
+## 🎯 User Impact
+
+**For macOS Users**: You can now use **completely free offline Piper TTS** on your Mac! No more ElevenLabs API key required. No more Python/pipx dependency hell. Just run `.claude/hooks/piper-installer.sh` and you're done. Works on both Intel Macs and Apple Silicon (M1/M2/M3).
+
+**For All Users**: The updated documentation now correctly reflects that Piper TTS works on **ALL platforms**: Windows, macOS, Linux, and WSL.
+
+**Installation is Simple**:
+```bash
+# Run AgentVibes installer
+npx agentvibes install --yes
+
+# Or directly run Piper installer
+.claude/hooks/piper-installer.sh
+
+# Add to PATH (if needed)
+echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
+source ~/.zshrc
+```
+
+**Architecture Support**:
+- ✅ Apple Silicon (M1/M2/M3): Downloads `piper_macos_aarch64.tar.gz`
+- ✅ Intel Mac (x86_64): Downloads `piper_macos_x64.tar.gz`
+
+## 📦 Files Changed
+
+### Modified
+- `.claude/hooks/piper-installer.sh` - Added macOS binary installation support
+- `.github/workflows/test-macos.yml` - Added comprehensive Piper installation tests
+- `docs/providers.md` - Updated macOS support documentation
+- `.claude/commands/release.md` - Added README update ordering warning
+- `src/installer.js` - Refactored release info display
+
+### Statistics
+- 5 files changed
+- 241 insertions(+)
+- 130 deletions(-)
+
+## 🔄 Breaking Changes
+
+None. This release is fully backward compatible. Linux/WSL users continue using pipx installation, macOS users now get binary installation.
+
+## 🚀 Upgrade Notes
+
+Simply run:
+```bash
+npx agentvibes@latest install --yes
+```
+
+Existing configurations are preserved. If you're on macOS and previously couldn't install Piper, it will work now!
+
+## 🙏 Credits
+
+Special thanks to:
+- **BMadCode** for reporting the macOS installation issue
+- **rhasspy/piper** project for providing macOS binaries
+- Community members who suggested the `--no-deps` workaround
+
+## 📊 Testing
+
+This release includes extensive CI testing:
+- ✅ 9 macOS configurations (macOS 13/14/15 × Node 18/20/22)
+- ✅ Both architecture types (Intel and Apple Silicon)
+- ✅ Binary download and extraction validation
+- ✅ Piper execution tests
+- ✅ Fallback to pipx testing (confirms original issue)
+
+---
+
+**Full Changelog**: https://github.com/paulpreibisch/AgentVibes/compare/v2.3.1...v2.4.0

package/RELEASE_NOTES_v2.4.1_DRAFT.md

@@ -0,0 +1,61 @@
+# Release v2.4.1 - macOS Audio Playback Fix (2025-01-15)
+
+## 🤖 AI Summary
+
+This patch release fixes a critical audio playback issue on macOS where Piper TTS audio files were being created but not playing. The fix adds platform detection to use the native macOS `afplay` audio player instead of trying to use Linux-only audio players (mpv/aplay/paplay) that don't exist on macOS.
+
+## 📋 Changes
+
+### 🐛 Bug Fixes
+- **Fixed macOS Audio Playback in Piper TTS**
+  - Added platform detection to use `afplay` on macOS (Darwin)
+  - Keeps existing Linux audio players (mpv/aplay/paplay) for WSL/Linux
+  - Audio files now play correctly on macOS instead of silently failing
+  - File: `.claude/hooks/play-tts-piper.sh` line 329-339
+
+## 🎯 User Impact
+
+**For macOS Users**: Audio playback now works! If you were seeing "🎵 Saved to:" messages but hearing no sound, this update fixes that. Simply run `npx agentvibes@latest install --yes` to get the fix.
+
+**What Was Broken**: After v2.4.0 added macOS Piper TTS support, audio files were being generated successfully but the playback failed silently because the script was trying to use Linux audio players that don't exist on macOS.
+
+**What's Fixed**: The script now detects macOS and uses the native `afplay` command for audio playback.
+
+## 📦 Files Changed
+
+### Modified
+- `.claude/hooks/play-tts-piper.sh` - Added macOS platform detection for audio playback
+
+### Statistics
+- 1 file changed
+- 10 insertions(+)
+- 2 deletions(-)
+
+## 🔄 Breaking Changes
+
+None. This is a pure bug fix release.
+
+## 🚀 Upgrade Notes
+
+Simply run:
+```bash
+npx agentvibes@latest install --yes
+```
+
+This will update the hooks with the fixed audio playback script.
+
+## 🙏 Credits
+
+Special thanks to:
+- **BMadCode** for reporting the issue and testing on macOS! (Official AgentVibes contributor 🎉)
+- macOS users who helped identify the silent audio playback problem
+
+## 🔗 Related
+
+- v2.4.0 - Initial macOS Piper TTS support
+- Issue: Audio files created but not playing on macOS
+- Fix: Platform detection for native audio player selection
+
+---
+
+**Full Changelog**: https://github.com/paulpreibisch/AgentVibes/compare/v2.4.0...v2.4.1