agentvibes 5.10.1 → 5.11.0

package/.mcp.json

@@ -1,34 +1,21 @@
 {
   "mcpServers": {
-    "firecrawl": {
-      "command": "npx",
-      "args": [
-        "firecrawl-mcp"
-      ]
-    },
-    "context7": {
+    "firecrawl-mcp": {
       "command": "npx",
       "args": [
         "-y",
-        "@upstash/context7-mcp"
-      ],
-      "env": {
-        "CONTEXT7_API_KEY": "${CONTEXT7_API_KEY}"
-      }
-    }
-  }
-}
-awl-mcp"
+        "firecrawl-mcp"
       ]
     },
-    "context7": {
+    "agentvibes": {
       "command": "npx",
       "args": [
         "-y",
-        "@upstash/context7-mcp"
+        "--package=agentvibes",
+        "agentvibes-mcp-server"
       ],
       "env": {
-        "CONTEXT7_API_KEY": "${CONTEXT7_API_KEY}"
+        "AGENTVIBES_MCP_FALLBACK": "copilot"
       }
     }
   }

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**: v5.10.0
+**Author**: Paul Preibisch ([@997Fire](https://x.com/997Fire)) | **Version**: v5.11.0
 
 ---
 
@@ -347,7 +347,7 @@ All 50+ Piper voices AgentVibes provides are sourced from Hugging Face's open-so
   - [🎤 Voices Tab](#-voices-tab) - Browse & sample 914 voices in the TUI
   - [💬 Intro Text](#-intro-text-pretext---your-personal-ai-branding) - Custom TTS prefixes
   - [🎵 Custom Background Music](#-custom-background-music---complete-audio-control) - Upload your own tracks
-- [📰 Latest Release](#-latest-release) - v5.5.0 with Per-LLM Audio Routing, Windows Installer Resilience
+- [📰 Latest Release](#-latest-release) - v5.11.0 with Kokoro & ElevenLabs Providers, Audio Effects
 - [🪟 Windows Setup Guide for Claude Desktop](mcp-server/WINDOWS_SETUP.md) - Complete Windows installation with WSL & Python
 
 ### AgentVibes MCP (Natural Language Control)
@@ -394,94 +394,20 @@ All 50+ Piper voices AgentVibes provides are sourced from Hugging Face's open-so
 
 ## 📰 Latest Release
 
-**[v3.6.0 - "Voice Explorer" Release](https://github.com/paulpreibisch/AgentVibes/releases/tag/v5.7.5)** 🎉
+**[v5.11.0 — Kokoro & ElevenLabs Providers + Audio Effects](https://github.com/paulpreibisch/AgentVibes/releases/tag/v5.11.0)** 🎉
 
-### 🎤 Voices Tab — Browse & Sample 914 Voices
+AgentVibes 5.11.0 adds two new TTS engines, combinable audio effects, a streamlined voices tab, and a deterministically green test suite.
 
-**Built into the TUI — launch with `npx agentvibes` then press V**
+### ✨ Highlights
 
-![AgentVibes Voices Tab](https://raw.githubusercontent.com/paulpreibisch/AgentVibes/master/docs/installation-screenshots/screenshot-voices.png)
+- **🆕 Kokoro provider** — high-quality **local neural** voices (CPU, no GPU needed), including Chinese / Japanese / Korean, with in-TUI dependency install.
+- **🆕 ElevenLabs provider** — premium **cloud** voices via an in-app API-key dialog.
+- **🎚️ Combinable audio effects** — stack **Reverb** (Room / Hall / Cathedral), **Echo** (short / cave), and **Chorus**; preview live with Space.
+- **🪟 Windows SAPI** routing fixed, and a **🎨 unified selector chrome** across every picker.
+- **🎤 Streamlined voices tab** — keystroke-only (Enter selects, `f` favorites ★); **BMAD auto-assign** now follows the active provider.
+- **🧪 Rock-solid CI** — eliminated the flaky failures; the test suite is deterministically green.
 
-- 🎧 Real-time voice sampling - press Space to hear before you choose
-- ⭐ Favorite system - mark your top voices
-- 🔍 Search & filter - find voices by personality, accent, gender
-- 📦 One-click select - press Enter to install directly
-- 🎨 Beautiful UI - built into the AgentVibes TUI
-
-**914 Total Voices:**
-- 904 Piper speaker variations (libritts-high)
-- 10 curated personality voices
-
-### 🎯 Major Features
-
-**🏷️ Friendly Voice Names**
-- No more cryptic IDs! Switch voices with names like "Ryan", "Joe", "Sarah"
-- All 904+ voices have memorable, personality-matched names
-- Voice metadata includes personalities, accents, and recommendations
-
-```bash
-# Before: /agent-vibes:switch en_US-libritts_r-medium-speaker-123
-# After:
-/agent-vibes:switch Ryan
-```
-
-**💬 Intro Text (Pretext) Feature**
-- Custom prefix for all TTS announcements
-- Set during installation or anytime after
-- Perfect for personal branding: "FireBot: Starting analysis..."
-- Up to 50 characters, UTF-8 and emoji support
-
-```bash
-npx agentvibes config intro-text
-```
-
-**🎵 Custom Background Music**
-- Upload your own audio files (.mp3, .wav, .ogg, .m4a)
-- **Battle-tested security:** 180+ attack variations blocked
-- Magic number validation ensures real audio files
-- File ownership verification (UID checks)
-- Audio duration validation (30-90s recommended, 300s max)
-- Secure storage with 600 permissions
-- Perfect for team audio branding
-
-```bash
-npx agentvibes config music
-```
-
-**🎨 Interactive Installer**
-- Preview voices during installation
-- Sample all 16 background music tracks
-- Audio environment auto-detection
-- Cross-platform preview support
-
-**🛡️ Security Hardening**
-- **180+ attack variations tested** - Path traversal, symlinks, Unicode, null bytes
-- **100% attack rejection rate** - All malicious attempts blocked
-- **OWASP compliant** - CWE-22 path traversal prevention verified
-- **Production certified** - Comprehensive security audit completed
-- **Defense-in-depth** - 7 validation layers protect your system
-- File ownership verification and secure storage (600 permissions)
-- Security audit report: `docs/security/SECURITY-AUDIT.md`
-
-### Quick Install
-
-```bash
-# Install AgentVibes
-npx agentvibes install
-
-# Browse voices in the TUI
-npx agentvibes  # press V for Voices tab
-```
-
-**🐞 Bug Fixes in v3.6.0:**
-- Fixed `get_verbosity` MCP tool returning wrong level after fresh install (now reads from correct project directory, defaults to `high`)
-- Fixed Voice Browser Soprano TTS detection, Custom Music race conditions, installer emoji rendering
-
-💡 **Tip:** If `npx agentvibes` shows an older version, clear cache: `npm cache clean --force && npx agentvibes@latest --help`
-
-🐛 **Found a bug?** Report at [GitHub Issues](https://github.com/paulpreibisch/AgentVibes/issues)
-
-[→ View Complete Release Notes](RELEASE_NOTES_v3.6.0.md) | [→ View All Releases](https://github.com/paulpreibisch/AgentVibes/releases)
+📖 Full details: [RELEASE_NOTES.md](RELEASE_NOTES.md) | [→ All Releases](https://github.com/paulpreibisch/AgentVibes/releases)
 
 [↑ Back to top](#-table-of-contents)
 

package/RELEASE_NOTES.md

@@ -1,5 +1,65 @@
 # AgentVibes Release Notes
 
+## 🎙️ v5.11.0 — Kokoro & ElevenLabs Providers, Unified Pickers, Windows SAPI, Rock-Solid CI
+
+**Released:** 2026-06-26
+
+This is a big one. AgentVibes gains two new TTS engines — **Kokoro** (high-quality local neural voices, including Chinese/Japanese/Korean) and **ElevenLabs** (premium cloud voices) — combinable audio effects, a unified selector UI, a Windows SAPI routing fix, and a deterministically green test suite. It also rolls up everything from the earlier 5.11.0 preview (LibriTTS 900+ voices, setup UX).
+
+### 🆕 New TTS Provider: Kokoro (local neural voices)
+- Browse and preview Kokoro voices from the Setup tab using the standardized picker.
+- **CPU synthesis** path so it runs without a GPU.
+- Smart dependency detection with in-TUI install dialogs — installs `kokoro`, `soundfile`, and `numpy` together, with a real progress bar (not just a spinner).
+- **CJK support**: Chinese, Japanese, and Korean voices, with per-language `misaki` / `pyopenjtalk` dependency handling and native sample phrases.
+- Windows playback fixed (Forms assembly load, correct paths, clearer exit-code errors).
+- A readiness "bling" cue (bundled CC0 sound) signals when a voice is ready to preview.
+
+### 🆕 New TTS Provider: ElevenLabs (premium cloud voices)
+- API-key dialog built into the Setup tab, with a navigation hint and Escape-to-close.
+- Routed through the same per-LLM voice system as every other provider.
+
+### 🎚️ New: Combinable Audio Effects — Reverb · Echo · Chorus
+Give any voice real character. A new multi-select effects modal lets you stack **reverb**, **echo**, and **chorus** independently:
+- **Reverb:** Room, Hall, Cathedral, and Warm (reverb + bass).
+- **Echo:** Echo (short delay) and Cave Echo (long) — brand new; there was no echo before.
+- **Chorus** for a richer, doubled timbre.
+- Effects **combine** (e.g. a little reverb *plus* a short echo), preview live with Space, and the picker now speaks the effect name and shows a spinner while auditioning.
+
+### 🎨 Unified Selector Chrome
+- All selector pickers (voices, tracks, reverb/effects) now share a common help bar, title style, and a fixed-width voice-row formatter — a consistent look and aligned status columns across every picker.
+
+### 🪟 Windows SAPI Routing Fixed
+- The bash hook router now recognizes the `sapi` / `windows-sapi` provider and routes to `play-tts-sapi.ps1` correctly (previously errored with "Unknown provider: sapi").
+
+### 🎤 Voices & BMAD Tab Improvements
+- **Streamlined, keystroke-only voice list.** Removed the redundant Switch / Favorite / Download button row — **Enter** selects (and downloads an uninstalled Piper voice first), **Space** previews, and **`f`** toggles a favorite ★. Thumbs-up/thumbs-down collapsed into a single favorite star.
+- **Removed the confusing "Install BMAD Voices" button.** Bulk voice downloads are available from the CLI (`npx agentvibes voices download`) instead.
+- **BMAD auto-assign now respects the active provider.** Pressing **[A] Auto-assign** previously always picked Piper voices; it now assigns voices from whichever provider is currently selected (Piper, Kokoro, ElevenLabs, soprano, …).
+
+### 🎛️ Picker & Preview Polish
+- **Effects preview:** correct voice + effect routing, an inline spinner on the item row, and a `pyopenjtalk` install prompt where needed.
+- **Track picker:** uses an `ffmpeg → pacat` pipe on headless PulseAudio TCP servers so previews work in remote/headless setups.
+- **Navigation:** pressing a tab's shortcut key while already on that tab is now a no-op.
+
+### 🧪 Rock-Solid CI (no more flaky failures)
+- Eliminated the intermittent CI red: fixed a `blessed.log()`-after-teardown crash in the Voices tab that randomly failed an innocent test file, and added a coverage runner (`scripts/run-coverage.mjs`) that gates on the actual reported test results instead of node's flaky `--test-force-exit` exit code. Real failures still fail the build; node's force-exit artifacts are tolerated.
+- Test audio is fully silenced during runs (marker file + env flags) so the suite never bleeds to your speakers.
+
+### 🐛 Audio Robustness Fixes
+- `getAudioDuration()` now attaches an error listener to its `which ffprobe` probe (previously this could throw an unhandled error and crash on Windows, where `which` doesn't exist) and bounds both spawns with 5s/10s timeouts so a stalled `ffprobe` can never hang the caller.
+- The interactive voice-preview prompt now releases (`pause()`) the stdin handle it opens, so the process exits cleanly instead of lingering.
+
+### 📦 Also in 5.11.0 (earlier preview)
+- LibriTTS 900+ voice library offer during install (~114 MB, 904 speakers).
+- Linux Piper install now uses the project's own `piper-installer.sh --non-interactive`.
+- Setup tab: spinner during engine install, smarter Tab navigation to Continue, install timeout raised to 30 minutes.
+
+### 🛡️ Quality
+- Full test suite green. New audio code covered: `audio-duration-validator` 96%, `preview-list-prompt` 90%.
+- Known pre-existing: `piper-voice-manager.sh` / `piper-installer.sh` use partial shell strict mode; tracked for a future hardening pass.
+
+---
+
 ## 🔧 v5.9.0 — SSH Remote + Windows Home Directory Fixes
 
 **Released:** 2026-05-18

package/WINDOWS-SETUP.md

@@ -1,208 +1,208 @@
-# AgentVibes Windows Native Setup
-
-This folder contains AgentVibes configured for **native Windows** (not WSL) with three TTS providers available.
-
-## Quick Start
-
-### 1. Open in VS Code (Native Windows)
-
-- **File > Open Folder** > Select this folder (`agentvibes-in-windows`)
-- Make sure you're opening in **native Windows VS Code** (not WSL remote)
-
-### 2. Open PowerShell Terminal
-
-- **Terminal > New Terminal**
-- Change shell to **PowerShell** (if needed)
-
-### 3. Run Setup
-
-```powershell
-.\setup-windows.ps1
-```
-
-This script will:
-- Check PowerShell version (5.1+)
-- Create `.claude` directories
-- Let you choose TTS provider (Piper or SAPI)
-- Install Piper if you choose it
-- Download a default voice model
-- Test TTS
-- Configure for first use
-
-### 4. Install Dependencies
-
-```powershell
-npm install
-```
-
-### 5. Start Using AgentVibes
-
-Open a Claude Code session in this project. The SessionStart hook will automatically inject TTS protocol instructions, causing Claude to speak all responses.
-
-## TTS Providers
-
-### Option 1: Soprano (Best Quality)
-- **Quality**: Ultra-high (80M parameter neural model)
-- **Voices**: Single high-quality voice (Soprano-1.1-80M)
-- **Download**: `pip install soprano-tts`
-- **Setup**: Start WebUI with `soprano-webui` or API with `uvicorn soprano.server:app`
-- **Speed**: GPU-accelerated, very fast
-- **Features**: Gradio WebUI mode, OpenAI-compatible API mode, CLI fallback
-
-To set up Soprano:
-```powershell
-# Install Soprano
-pip install soprano-tts
-
-# Start WebUI (recommended - stays running in background)
-soprano-webui
-
-# Set provider
-.\.claude\hooks-windows\provider-manager.ps1 set soprano
-
-# Test
-.\.claude\hooks-windows\play-tts-soprano.ps1 "Hello from Soprano"
-```
-
-### Option 2: Windows Piper (Recommended for Offline)
-- **Quality**: High (neural voices)
-- **Voices**: 50+ available
-- **Download**: ~100MB
-- **Setup**: Automatic (run `setup-windows.ps1`)
-- **Speed**: Offline synthesis
-- **Features**: All AgentVibes features supported
-
-### Option 3: Windows SAPI (Built-in, Zero Setup)
-- **Quality**: Basic
-- **Voices**: ~10 built-in (David, Zira, Mark)
-- **Download**: 0 MB (no installation needed)
-- **Setup**: Select during `setup-windows.ps1`
-- **Speed**: Fast
-- **Features**: Core TTS only
-
-## Claude Code Integration
-
-AgentVibes hooks into Claude Code via `.claude/settings.json`. The SessionStart hook runs automatically when Claude starts a session:
-
-```json
-{
-  "hooks": {
-    "SessionStart": [{
-      "hooks": [{
-        "type": "command",
-        "command": "powershell -NoProfile -ExecutionPolicy Bypass -File \"$CLAUDE_PROJECT_DIR\\.claude\\hooks-windows\\session-start-tts.ps1\""
-      }]
-    }]
-  }
-}
-```
-
-This injects TTS protocol instructions so Claude speaks every response using the configured provider.
-
-## Manual Commands
-
-Test TTS manually:
-
-```powershell
-# Test current provider
-.\.claude\hooks-windows\play-tts.ps1 "Hello from Windows"
-
-# Test specific providers
-.\.claude\hooks-windows\play-tts-windows-sapi.ps1 "Hello SAPI"
-.\.claude\hooks-windows\play-tts-windows-piper.ps1 "Hello Piper"
-.\.claude\hooks-windows\play-tts-soprano.ps1 "Hello Soprano"
-
-# List available voices
-.\.claude\hooks-windows\voice-manager-windows.ps1 list
-
-# Switch voice (for Piper/SAPI)
-.\.claude\hooks-windows\voice-manager-windows.ps1 switch "en_US-lessac-high"
-
-# List providers
-.\.claude\hooks-windows\provider-manager.ps1 list
-
-# Switch provider
-.\.claude\hooks-windows\provider-manager.ps1 set soprano
-.\.claude\hooks-windows\provider-manager.ps1 set windows-piper
-.\.claude\hooks-windows\provider-manager.ps1 set windows-sapi
-```
-
-## Troubleshooting
-
-### PowerShell Execution Policy Error
-
-If you get an "execution policy" error, run:
-
-```powershell
-Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
-```
-
-Then try again.
-
-### No Audio Playing
-
-1. Check Windows volume isn't muted
-2. Try switching to SAPI provider (zero-setup): `.\.claude\hooks-windows\provider-manager.ps1 set windows-sapi`
-3. Test SAPI directly: `.\.claude\hooks-windows\play-tts-windows-sapi.ps1 "test"`
-
-### Soprano Not Detected
-
-1. Ensure soprano-webui is running: `soprano-webui`
-2. Check port 7860 is accessible: `Test-NetConnection -ComputerName 127.0.0.1 -Port 7860`
-3. Set custom port if needed: `$env:SOPRANO_PORT = "8080"` before running TTS
-
-### Piper Installation Failed
-
-1. Check internet connection
-2. Run setup again: `.\setup-windows.ps1`
-3. Or manually download from: https://github.com/rhasspy/piper/releases
-
-### Can't Find Voice
-
-For Piper, voices are stored in: `%USERPROFILE%\.claude\piper-voices\`
-
-You can download additional voices with `.\download-piper-voices.ps1`.
-
-## Architecture
-
-```
-agentvibes-in-windows/
-├── .claude/
-│   ├── hooks-windows/               # PowerShell TTS scripts
-│   │   ├── play-tts.ps1             # Main router (dispatches to active provider)
-│   │   ├── play-tts-soprano.ps1     # Soprano provider
-│   │   ├── play-tts-windows-piper.ps1  # Piper provider
-│   │   ├── play-tts-windows-sapi.ps1   # SAPI provider
-│   │   ├── soprano-gradio-synth.py  # Python helper for Soprano Gradio API
-│   │   ├── provider-manager.ps1     # Provider switching
-│   │   ├── voice-manager-windows.ps1   # Voice management
-│   │   ├── session-start-tts.ps1    # SessionStart hook (injects TTS protocol)
-│   │   └── audio-cache-utils.ps1    # Audio cache cleanup
-│   ├── settings.json                # Claude Code hooks config
-│   ├── audio/                       # Audio cache (auto-created)
-│   ├── piper-voices/                # Piper voice models (auto-created)
-│   └── tts-provider.txt             # Active provider config
-├── setup-windows.ps1                # Installation script
-├── download-piper-voices.ps1        # Download additional Piper voices
-└── WINDOWS-SETUP.md                 # This file
-```
-
-## What's Different from WSL
-
-| Feature | WSL Version | Windows Native |
-|---------|-------------|----------------|
-| **TTS Scripts** | Bash shell scripts (.sh) | PowerShell scripts (.ps1) |
-| **Audio** | PulseAudio/paplay | System.Media.SoundPlayer |
-| **Providers** | Piper, macOS, Termux, Soprano | Piper, SAPI, Soprano |
-| **Setup** | WSL + PulseAudio config | Native Windows only |
-| **Hook Dir** | `.claude/hooks/` | `.claude/hooks-windows/` |
-
-## Support
-
-- **Documentation**: https://agentvibes.org
-- **Issues**: https://github.com/paulpreibisch/AgentVibes/issues
-
----
-
-**Version**: 2.0 (Windows Native + Soprano)
-**Last Updated**: 2026-02-11
+# AgentVibes Windows Native Setup
+
+This folder contains AgentVibes configured for **native Windows** (not WSL) with three TTS providers available.
+
+## Quick Start
+
+### 1. Open in VS Code (Native Windows)
+
+- **File > Open Folder** > Select this folder (`agentvibes-in-windows`)
+- Make sure you're opening in **native Windows VS Code** (not WSL remote)
+
+### 2. Open PowerShell Terminal
+
+- **Terminal > New Terminal**
+- Change shell to **PowerShell** (if needed)
+
+### 3. Run Setup
+
+```powershell
+.\setup-windows.ps1
+```
+
+This script will:
+- Check PowerShell version (5.1+)
+- Create `.claude` directories
+- Let you choose TTS provider (Piper or SAPI)
+- Install Piper if you choose it
+- Download a default voice model
+- Test TTS
+- Configure for first use
+
+### 4. Install Dependencies
+
+```powershell
+npm install
+```
+
+### 5. Start Using AgentVibes
+
+Open a Claude Code session in this project. The SessionStart hook will automatically inject TTS protocol instructions, causing Claude to speak all responses.
+
+## TTS Providers
+
+### Option 1: Soprano (Best Quality)
+- **Quality**: Ultra-high (80M parameter neural model)
+- **Voices**: Single high-quality voice (Soprano-1.1-80M)
+- **Download**: `pip install soprano-tts`
+- **Setup**: Start WebUI with `soprano-webui` or API with `uvicorn soprano.server:app`
+- **Speed**: GPU-accelerated, very fast
+- **Features**: Gradio WebUI mode, OpenAI-compatible API mode, CLI fallback
+
+To set up Soprano:
+```powershell
+# Install Soprano
+pip install soprano-tts
+
+# Start WebUI (recommended - stays running in background)
+soprano-webui
+
+# Set provider
+.\.claude\hooks-windows\provider-manager.ps1 set soprano
+
+# Test
+.\.claude\hooks-windows\play-tts-soprano.ps1 "Hello from Soprano"
+```
+
+### Option 2: Windows Piper (Recommended for Offline)
+- **Quality**: High (neural voices)
+- **Voices**: 50+ available
+- **Download**: ~100MB
+- **Setup**: Automatic (run `setup-windows.ps1`)
+- **Speed**: Offline synthesis
+- **Features**: All AgentVibes features supported
+
+### Option 3: Windows SAPI (Built-in, Zero Setup)
+- **Quality**: Basic
+- **Voices**: ~10 built-in (David, Zira, Mark)
+- **Download**: 0 MB (no installation needed)
+- **Setup**: Select during `setup-windows.ps1`
+- **Speed**: Fast
+- **Features**: Core TTS only
+
+## Claude Code Integration
+
+AgentVibes hooks into Claude Code via `.claude/settings.json`. The SessionStart hook runs automatically when Claude starts a session:
+
+```json
+{
+  "hooks": {
+    "SessionStart": [{
+      "hooks": [{
+        "type": "command",
+        "command": "powershell -NoProfile -ExecutionPolicy Bypass -File \"$CLAUDE_PROJECT_DIR\\.claude\\hooks-windows\\session-start-tts.ps1\""
+      }]
+    }]
+  }
+}
+```
+
+This injects TTS protocol instructions so Claude speaks every response using the configured provider.
+
+## Manual Commands
+
+Test TTS manually:
+
+```powershell
+# Test current provider
+.\.claude\hooks-windows\play-tts.ps1 "Hello from Windows"
+
+# Test specific providers
+.\.claude\hooks-windows\play-tts-windows-sapi.ps1 "Hello SAPI"
+.\.claude\hooks-windows\play-tts-windows-piper.ps1 "Hello Piper"
+.\.claude\hooks-windows\play-tts-soprano.ps1 "Hello Soprano"
+
+# List available voices
+.\.claude\hooks-windows\voice-manager-windows.ps1 list
+
+# Switch voice (for Piper/SAPI)
+.\.claude\hooks-windows\voice-manager-windows.ps1 switch "en_US-lessac-high"
+
+# List providers
+.\.claude\hooks-windows\provider-manager.ps1 list
+
+# Switch provider
+.\.claude\hooks-windows\provider-manager.ps1 set soprano
+.\.claude\hooks-windows\provider-manager.ps1 set windows-piper
+.\.claude\hooks-windows\provider-manager.ps1 set windows-sapi
+```
+
+## Troubleshooting
+
+### PowerShell Execution Policy Error
+
+If you get an "execution policy" error, run:
+
+```powershell
+Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
+```
+
+Then try again.
+
+### No Audio Playing
+
+1. Check Windows volume isn't muted
+2. Try switching to SAPI provider (zero-setup): `.\.claude\hooks-windows\provider-manager.ps1 set windows-sapi`
+3. Test SAPI directly: `.\.claude\hooks-windows\play-tts-windows-sapi.ps1 "test"`
+
+### Soprano Not Detected
+
+1. Ensure soprano-webui is running: `soprano-webui`
+2. Check port 7860 is accessible: `Test-NetConnection -ComputerName 127.0.0.1 -Port 7860`
+3. Set custom port if needed: `$env:SOPRANO_PORT = "8080"` before running TTS
+
+### Piper Installation Failed
+
+1. Check internet connection
+2. Run setup again: `.\setup-windows.ps1`
+3. Or manually download from: https://github.com/rhasspy/piper/releases
+
+### Can't Find Voice
+
+For Piper, voices are stored in: `%USERPROFILE%\.claude\piper-voices\`
+
+You can download additional voices with `.\download-piper-voices.ps1`.
+
+## Architecture
+
+```
+agentvibes-in-windows/
+├── .claude/
+│   ├── hooks-windows/               # PowerShell TTS scripts
+│   │   ├── play-tts.ps1             # Main router (dispatches to active provider)
+│   │   ├── play-tts-soprano.ps1     # Soprano provider
+│   │   ├── play-tts-windows-piper.ps1  # Piper provider
+│   │   ├── play-tts-windows-sapi.ps1   # SAPI provider
+│   │   ├── soprano-gradio-synth.py  # Python helper for Soprano Gradio API
+│   │   ├── provider-manager.ps1     # Provider switching
+│   │   ├── voice-manager-windows.ps1   # Voice management
+│   │   ├── session-start-tts.ps1    # SessionStart hook (injects TTS protocol)
+│   │   └── audio-cache-utils.ps1    # Audio cache cleanup
+│   ├── settings.json                # Claude Code hooks config
+│   ├── audio/                       # Audio cache (auto-created)
+│   ├── piper-voices/                # Piper voice models (auto-created)
+│   └── tts-provider.txt             # Active provider config
+├── setup-windows.ps1                # Installation script
+├── download-piper-voices.ps1        # Download additional Piper voices
+└── WINDOWS-SETUP.md                 # This file
+```
+
+## What's Different from WSL
+
+| Feature | WSL Version | Windows Native |
+|---------|-------------|----------------|
+| **TTS Scripts** | Bash shell scripts (.sh) | PowerShell scripts (.ps1) |
+| **Audio** | PulseAudio/paplay | System.Media.SoundPlayer |
+| **Providers** | Piper, macOS, Termux, Soprano | Piper, SAPI, Soprano |
+| **Setup** | WSL + PulseAudio config | Native Windows only |
+| **Hook Dir** | `.claude/hooks/` | `.claude/hooks-windows/` |
+
+## Support
+
+- **Documentation**: https://agentvibes.org
+- **Issues**: https://github.com/paulpreibisch/AgentVibes/issues
+
+---
+
+**Version**: 2.0 (Windows Native + Soprano)
+**Last Updated**: 2026-02-11