agentvibes 5.12.0 → 5.13.0

package/.claude/hooks-windows/provider-manager.ps1

@@ -15,7 +15,25 @@ param(
 
 $ClaudeDir = "$env:USERPROFILE\.claude"
 $ProviderFile = "$ClaudeDir\tts-provider.txt"
-$ValidProviders = @('windows-piper', 'windows-sapi', 'soprano')
+# $ValidProviders DERIVES from the generated Provider Catalog (SSOT): the Windows
+# platform set (kokoro is cross-platform — play-tts-kokoro.ps1 exists; elevenlabs
+# is NOT playable on Windows and is therefore absent). Dot-source the generated
+# provider-catalog.ps1 and pull `windows`. FAIL-SAFE: the literal below is the
+# legacy fallback used when the catalog artifact is missing (installed-tree skew)
+# — mirrors AVI-S9.3's probe/fallback pattern. See AVI-S8.1 / AVI-S9.5.
+$ValidProviders = @('windows-piper', 'windows-sapi', 'soprano', 'kokoro')
+$__CatalogPs1 = Join-Path $PSScriptRoot 'provider-catalog.ps1'
+if (Test-Path $__CatalogPs1) {
+    try {
+        . $__CatalogPs1
+        if (Get-Command Get-CatalogProvidersForPlatform -ErrorAction SilentlyContinue) {
+            $__WinSet = @(Get-CatalogProvidersForPlatform 'windows')
+            if ($__WinSet.Count -gt 0) { $ValidProviders = $__WinSet }
+        }
+    } catch {
+        # Keep the legacy fallback literal on any catalog load error.
+    }
+}
 
 # Ensure claude directory exists
 if (-not (Test-Path $ClaudeDir)) {
@@ -35,6 +53,14 @@ function Get-ActiveProvider {
 function Get-AvailableProviders {
     $available = @()
 
+    # Fast path: skip the live install probes (soprano HTTP + kokoro python
+    # spawns). Those probes are what make `provider list` occasionally stall for
+    # tens of seconds under load; when the caller only needs the provider NAMES
+    # (e.g. the parallel test harness, or an offline listing) set
+    # AGENTVIBES_PROVIDER_LIST_NO_PROBE=1 to report installed=$false without
+    # touching the network or spawning interpreters. Default behavior unchanged.
+    $noProbe = ($env:AGENTVIBES_PROVIDER_LIST_NO_PROBE -eq '1')
+
     # Always available
     $available += @{
         name = "windows-sapi"
@@ -59,15 +85,18 @@ function Get-AvailableProviders {
         $null = Get-Command soprano -ErrorAction Stop
         $sopranoInstalled = $true
     } catch {
-        # Also check if a Soprano server is running (try both API paths)
-        try {
-            $null = Invoke-WebRequest -Uri "http://127.0.0.1:${sopranoPort}/gradio_api/info" -TimeoutSec 1 -UseBasicParsing -ErrorAction Stop
-            $sopranoInstalled = $true
-        } catch {
+        # Also check if a Soprano server is running (try both API paths) — unless
+        # the fast path is requested, in which case skip the network probes.
+        if (-not $noProbe) {
             try {
-                $null = Invoke-WebRequest -Uri "http://127.0.0.1:${sopranoPort}/info" -TimeoutSec 1 -UseBasicParsing -ErrorAction Stop
+                $null = Invoke-WebRequest -Uri "http://127.0.0.1:${sopranoPort}/gradio_api/info" -TimeoutSec 1 -UseBasicParsing -ErrorAction Stop
                 $sopranoInstalled = $true
-            } catch {}
+            } catch {
+                try {
+                    $null = Invoke-WebRequest -Uri "http://127.0.0.1:${sopranoPort}/info" -TimeoutSec 1 -UseBasicParsing -ErrorAction Stop
+                    $sopranoInstalled = $true
+                } catch {}
+            }
         }
     }
 
@@ -77,6 +106,32 @@ function Get-AvailableProviders {
         installed = $sopranoInstalled
     }
 
+    # Check if Kokoro is installed. Mirror validateKokoroInstallation() in
+    # src/utils/provider-validator.js, but use importlib.util.find_spec so we do
+    # NOT actually import kokoro — importing the 82M-param neural lib takes
+    # several seconds and would make `provider list` hang (AVI-S8.1). find_spec
+    # only confirms the packages are importable, which is all we need here.
+    $kokoroInstalled = $false
+    $kokoroProbe = "import importlib.util as u,sys; sys.exit(0 if all(u.find_spec(m) for m in ('kokoro','soundfile','numpy')) else 1)"
+    foreach ($py in ($(if ($noProbe) { @() } else { @('py', 'python', 'python3') }))) {
+        if (-not (Get-Command $py -ErrorAction SilentlyContinue)) { continue }
+        try {
+            $null = & $py -c $kokoroProbe 2>$null
+            # Only stop once an interpreter actually HAS the packages — mirrors
+            # validateKokoroInstallation(), which tries every interpreter (the
+            # packages may live under python/python3, not the `py` launcher).
+            if ($LASTEXITCODE -eq 0) { $kokoroInstalled = $true; break }
+        } catch {
+            # interpreter present but failed to run the probe — try next
+        }
+    }
+
+    $available += @{
+        name = "kokoro"
+        description = "Kokoro TTS (Neural, pip install kokoro-onnx soundfile numpy)"
+        installed = $kokoroInstalled
+    }
+
     return $available
 }
 

package/.claude/hooks-windows/tts-watcher.ps1

@@ -52,7 +52,7 @@ try {
                     }
                     if ($req.kind -eq 'music') {
                         $trackName = [string]$req.music
-                        if ($trackName -match '^[A-Za-z0-9._][A-Za-z0-9._\-]*\.mp3$') {
+                        if ($trackName -match '^[A-Za-z0-9._][A-Za-z0-9._ \-]*\.mp3$') {
                             $tracksDir = Join-Path $env:USERPROFILE '.claude\audio\tracks'
                             $full     = [System.IO.Path]::GetFullPath((Join-Path $tracksDir $trackName))
                             $baseFull = [System.IO.Path]::GetFullPath($tracksDir)
@@ -61,6 +61,17 @@ try {
                                 $ffplay = Get-Command ffplay -ErrorAction SilentlyContinue
                                 if ($ffplay) {
                                     Write-WatcherLog "INFO" "music-preview id=$($req.id) track=$trackName"
+                                    # Readiness bling — a short cue played in THIS (audio-capable) watcher
+                                    # session BEFORE the track so a listener knows music is incoming. Launched
+                                    # async (NOT -Wait — the wav's shimmer tail is long); a fixed 0.3s gap then
+                                    # lets the music follow tightly. Best-effort: a missing wav / player error
+                                    # never blocks the track.
+                                    $blingWav = Join-Path $env:USERPROFILE '.claude\audio\ui\bling-success.wav'
+                                    if (-not (Test-Path $blingWav)) { $blingWav = Join-Path $env:USERPROFILE '.agentvibes\bling-success.wav' }
+                                    if (Test-Path $blingWav) {
+                                        try { Start-Process -FilePath $ffplay.Source -ArgumentList @('-autoexit','-nodisp','-loglevel','quiet',$blingWav) -WindowStyle Hidden | Out-Null } catch { }
+                                        Start-Sleep -Milliseconds 300
+                                    }
                                     $mp = Start-Process -FilePath $ffplay.Source -ArgumentList @('-autoexit','-nodisp','-loglevel','quiet','-volume','80',$full) -WindowStyle Hidden -PassThru
                                     if ($mp) { Set-Content -Path $pidFile -Value $mp.Id -NoNewline -ErrorAction SilentlyContinue }
                                 } else {
@@ -83,9 +94,9 @@ try {
                 $safeVoice = if ($req.voice -and $req.voice -match '^[a-zA-Z0-9_\-\. :]+$') { $req.voice } else { "" }
                 $env:CLAUDE_PROJECT_DIR = $env:USERPROFILE
                 $env:AGENTVIBES_NO_PRETEXT = "1"
-                # Carry the sender's project (folder name/path) through to the
-                # TalkingHead forward so the avatar badge/tab shows the real remote
-                # origin instead of this machine's own profile dir. (Grafted from master WIP.)
+                # Carry the sender's project (folder name/path) through so a
+                # downstream receiver shows the real remote origin instead of
+                # this machine's own profile dir.
                 if ($req.project) { $env:AGENTVIBES_PROJECT = $req.project }
                 else { [System.Environment]::SetEnvironmentVariable("AGENTVIBES_PROJECT", $null, "Process") }
                 if ($req.projectPath) { $env:AGENTVIBES_PROJECT_PATH = $req.projectPath }
@@ -99,16 +110,26 @@ try {
                 else { [System.Environment]::SetEnvironmentVariable("AGENTVIBES_OVERRIDE_EFFECTS", $null, "Process") }
 
                 if (Test-Path $PlayTts) {
-                    # Play remote arrival prefix sound if configured
-                    $prefixSoundFile = "$env:USERPROFILE\.agentvibes\remote-prefix-sound.txt"
-                    if (Test-Path $prefixSoundFile) {
-                        $prefixSound = (Get-Content $prefixSoundFile -Raw).Trim()
-                        if ($prefixSound -and (Test-Path $prefixSound)) {
-                            $ffplay = Get-Command ffplay -ErrorAction SilentlyContinue
-                            if ($ffplay) {
-                                & $ffplay.Source -autoexit -nodisp -loglevel quiet $prefixSound 2>$null
+                    # Always play a crisp local "incoming" bling so the user KNOWS audio is
+                    # on the way — even when audio is routed to a downstream receiver
+                    # instead of the local speakers. Standard bling-success.wav, async
+                    # with a 0.3s gap (same as the music-preview path); fall back to the
+                    # user-configured remote-prefix-sound.txt if the bling wav is missing.
+                    $ffplay = Get-Command ffplay -ErrorAction SilentlyContinue
+                    if ($ffplay) {
+                        $blingWav = Join-Path $env:USERPROFILE '.claude\audio\ui\bling-success.wav'
+                        if (-not (Test-Path $blingWav)) { $blingWav = Join-Path $env:USERPROFILE '.agentvibes\bling-success.wav' }
+                        if (-not (Test-Path $blingWav)) {
+                            $prefixSoundFile = "$env:USERPROFILE\.agentvibes\remote-prefix-sound.txt"
+                            if (Test-Path $prefixSoundFile) {
+                                $ps = (Get-Content $prefixSoundFile -Raw).Trim()
+                                if ($ps -and (Test-Path $ps)) { $blingWav = $ps }
                             }
                         }
+                        if (Test-Path $blingWav) {
+                            try { Start-Process -FilePath $ffplay.Source -ArgumentList @('-autoexit','-nodisp','-loglevel','quiet',$blingWav) -WindowStyle Hidden | Out-Null } catch { }
+                            Start-Sleep -Milliseconds 300
+                        }
                     }
 
                     $tempText = Join-Path $env:TEMP "agentvibes-tts-$($req.id).txt"

package/.claude/hooks-windows/voice-manager-windows.ps1

@@ -17,6 +17,14 @@ $ClaudeDir = "$env:USERPROFILE\.claude"
 $ProviderFile = "$ClaudeDir\tts-provider.txt"
 $VoiceSapiFile = "$ClaudeDir\tts-voice-sapi.txt"
 $VoicePiperFile = "$ClaudeDir\tts-voice-piper.txt"
+$VoiceKokoroFile = "$ClaudeDir\tts-voice-kokoro.txt"
+
+# Load the generated Provider Catalog (SSOT) for kokoro switch-time validation.
+# FAIL-SAFE: consumers probe `Get-Command Test-CatalogVoice` and fall back to the
+# legacy shape regex when the artifact is missing (installed-tree skew) — mirrors
+# play-tts.sh's PLAN_OK legacy fallback. Switch never breaks on a missing catalog.
+$CatalogPs1 = Join-Path $PSScriptRoot 'provider-catalog.ps1'
+if (Test-Path $CatalogPs1) { . $CatalogPs1 }
 
 # Get active provider
 $ActiveProvider = "windows-sapi"
@@ -129,6 +137,47 @@ function Switch-Voice {
         Write-Host "[INFO] Soprano uses a single fixed voice (Soprano-1.1-80M)" -ForegroundColor Cyan
         return $true
     }
+    elseif ($ActiveProvider -eq "kokoro") {
+        # Kokoro switch-time validation via the generated Provider Catalog (SSOT):
+        # MEMBERSHIP + canonical case-fold, so a typo like af_hart is rejected HERE
+        # and never reaches tts-voice-kokoro.txt to die silently at the model.
+        # Escape hatch AGENTVIBES_ALLOW_UNLISTED_VOICE=1 bypasses MEMBERSHIP (not
+        # shape) so a voice from a newer kokoro model still switches. FAIL-SAFE:
+        # fall back to the legacy shape regex when the catalog artifact is missing.
+        $kokoroVoice = $NewVoice.ToLower()
+        $allowUnlisted = ($env:AGENTVIBES_ALLOW_UNLISTED_VOICE -eq '1')
+        if (Get-Command Test-CatalogVoice -ErrorAction SilentlyContinue) {
+            $canon = Test-CatalogVoice -Provider 'kokoro' -Voice $NewVoice
+            if ($canon) {
+                Set-Content -Path $VoiceKokoroFile -Value $canon
+                Write-Host "[OK] Voice set to: $canon" -ForegroundColor Green
+                return $true
+            }
+            elseif ($allowUnlisted -and $kokoroVoice -match '^[a-z]{2}_[a-z0-9_]+$') {
+                Write-Host "[WARN] '$NewVoice' is not in the shipped Kokoro catalog; allowing it (AGENTVIBES_ALLOW_UNLISTED_VOICE=1)." -ForegroundColor Yellow
+                Set-Content -Path $VoiceKokoroFile -Value $kokoroVoice
+                Write-Host "[OK] Voice set to: $kokoroVoice" -ForegroundColor Green
+                return $true
+            }
+            else {
+                Write-Host "[ERROR] Kokoro voice not found: $NewVoice" -ForegroundColor Red
+                Write-Host "That is not a known Kokoro voice. Examples: af_heart, am_michael, bf_emma, bm_george, jf_alpha, zf_xiaoxiao, ef_dora." -ForegroundColor Yellow
+                Write-Host "Set AGENTVIBES_ALLOW_UNLISTED_VOICE=1 to allow a newer-model voice." -ForegroundColor Yellow
+                return $false
+            }
+        }
+        else {
+            # FAIL-SAFE legacy path (catalog artifact missing): shape-only regex.
+            if ($kokoroVoice -notmatch '^[a-z]{2}_[a-z0-9_]+$') {
+                Write-Host "[ERROR] Kokoro voice not found: $NewVoice" -ForegroundColor Red
+                Write-Host "Kokoro ids look like <lang><sex>_name, e.g. af_heart, am_michael, bf_emma." -ForegroundColor Yellow
+                return $false
+            }
+            Set-Content -Path $VoiceKokoroFile -Value $kokoroVoice
+            Write-Host "[OK] Voice set to: $kokoroVoice" -ForegroundColor Green
+            return $true
+        }
+    }
 
     if ($ValidVoices -notcontains $NewVoice) {
         Write-Host "[ERROR] Voice not found: $NewVoice" -ForegroundColor Red

package/.mcp.json

@@ -1,12 +1,5 @@
 {
   "mcpServers": {
-    "firecrawl-mcp": {
-      "command": "npx",
-      "args": [
-        "-y",
-        "firecrawl-mcp"
-      ]
-    },
     "agentvibes": {
       "command": "npx",
       "args": [

package/README.md

@@ -58,9 +58,18 @@ New here? The [**Quick Start guide**](docs/quick-start.md) walks you through you
 
 ---
 
-## 🆕 A stronger core (v5.12.0)
+## 🆕 Your voices everywhere (v5.13.0)
 
-During a week of early access to Anthropic's new **Fable** model, we rebuilt the heart of AgentVibes into **one shared core**. The voice / engine / routing / volume / mute logic that used to be copied across four scripts (and drift apart) now lives in a single place — simpler, more consistent, and steadier.
+Pick the voices built into **Windows** or **Mac** and hear them wherever you're listening — even when your agents run on another computer. Plus a friendly heads-up chime so you always know sound is coming.
+
+- **🖥️ Your computer's own voices, from anywhere** — choose Windows or Mac voices and hear them on your machine; every voice is shown, with unavailable ones clearly marked.
+- **🗂️ All voices in one list** — Piper, Kokoro, ElevenLabs, Windows, Mac, and Soprano in one place, so what you see is what you can use.
+- **🔔 Heads-up chime** — a short sound plays just before a voice or music preview, so you know audio is on the way.
+- **🆔 Agents that introduce themselves** — optional self-introductions so you know who's talking in a team.
+
+### v5.12.0 — A stronger core
+
+During a week of early access to Anthropic's new **Fable** model, we rebuilt the heart of AgentVibes into **one shared core**. The voice / engine / routing / volume / mute logic now lives in a single place — simpler, more consistent, and steadier.
 
 - **🔊 Previews play in the right place** — with SSH remote configured, voice and **music previews** play on your receiver; otherwise they play locally.
 - **🧠 One shared core** — Kokoro-on-Linux silence and per-voice drift fixed at the source, with a safe fallback if needed.
@@ -224,7 +233,7 @@ Running a full BMAD agent team? **Every agent gets its own distinct voice**, aut
 
 ## About
 
-**AgentVibes** · v5.12.0 · Licensed under [Apache-2.0](LICENSE)
+**AgentVibes** · v5.13.0 · Licensed under [Apache-2.0](LICENSE)
 
 Built by **Paul Preibisch** — [@997Fire on X](https://x.com/997Fire) · [agentvibes.org](https://agentvibes.org) · [github.com/paulpreibisch/AgentVibes](https://github.com/paulpreibisch/AgentVibes)
 

package/RELEASE_NOTES.md

@@ -1,5 +1,48 @@
 # AgentVibes Release Notes
 
+## 🎉 v5.13.0 — Your Voices Everywhere, With a Heads-Up
+
+**Released:** 2026-07-16 · on `latest` — `npm install agentvibes`
+
+What's new:
+
+### 🖥️ Use your computer's own voices, from anywhere
+
+Run your agents on one machine and listen on another? You can now pick the voices built into **Windows** (David, Zira, Mark) or **Mac**, and hear them right where you're sitting. AgentVibes shows you every voice and clearly marks the ones your listening device can play.
+
+### 🗂️ All your voices in one tidy list
+
+Piper, Kokoro, ElevenLabs, Windows, Mac, Soprano — every voice now comes from a single list, so what you see is always what you can use.
+
+### 🔔 A "heads-up" chime before sound plays
+
+Just before a voice line or music preview starts, you'll hear a short chime — so you always know audio is on the way, even if it takes a moment.
+
+### 🎵 Music previews follow your sound
+
+Preview a track and it plays wherever your audio is set to go — including on another computer.
+
+### 🆔 Agents that introduce themselves
+
+Turn on self-introductions and each agent says who it is when it starts — handy when a whole team is talking.
+
+### 🛟 Your own edits are kept safe when you update
+
+Tinkered with one of the AgentVibes files in your `.claude/hooks` folder? From this version on, updating never throws your work away. If we need to update a file you'd changed, we tuck your copy in beside it with `.user.bak` on the end — like `play-tts.sh.user.bak`.
+
+**That file is made by AgentVibes — nothing is broken and nothing else put it there.** It's simply your old version, saved so you can peek at it or copy your changes back into the new one. Delete it whenever you're done with it.
+
+If you customized files in an older version, it's worth a quick look in `.claude/hooks` for anything you'd want to put back.
+
+### ✨ More voices, smoother ride
+
+- **ElevenLabs** voices fully supported
+- More **Kokoro** voices, working great on Windows
+- Faster, more reliable setup on Windows
+- **3,263 automated tests passing** — steady and dependable
+
+---
+
 ## 🎉 v5.12.0 — The Fable Week Overhaul (Stable)
 
 **Released:** 2026-07-05 · now on `latest` — `npm install agentvibes`

package/mcp-server/server.py

@@ -46,6 +46,7 @@ import os
 import platform
 import re as _re
 import subprocess
+import sys
 from dataclasses import dataclass
 from pathlib import Path
 from typing import Optional
@@ -61,6 +62,53 @@ import mcp.server.stdio
 DEFAULT_SCRIPT_TIMEOUT = 30.0
 
 
+# ── Provider Catalog (SSOT Layer 2) — platform allowlists + display names ────
+#
+# server.py DERIVES its per-platform provider allowlists and provider display
+# names from the shipped provider-catalog.json (generated from
+# src/services/provider-catalog.js). The literals below are an EMBEDDED FALLBACK
+# used ONLY when that JSON is missing or unreadable (installed-tree skew) —
+# degraded, never dead: the MCP server MUST start without the file.
+#
+# Bidirectional parity (embedded fallback ≡ catalog, per platform, BOTH
+# directions) is asserted by test/unit/provider-catalog-conformance.test.js so
+# the fallback can never silently drift from the catalog (design §8 — a
+# one-directional check is the exact gap that let elevenlabs-on-Windows through
+# the old positive-only test).
+#
+# The non-Windows fallback mirrors the catalog's DARWIN set (the superset that
+# also covers Linux: darwin adds macOS `say`, which a Linux box simply won't
+# have installed — availability is enforced by the dispatchers downstream, not
+# here). Windows uses the catalog WINDOWS set. elevenlabs is deliberately ABSENT
+# from Windows: there is NO play-tts-elevenlabs.ps1 runtime (AVI-S9.1 /
+# provider-catalog.js: elevenlabs.runtime.windows === null).
+_FALLBACK_PROVIDERS_WINDOWS = ["windows-piper", "windows-sapi", "soprano", "kokoro"]
+_FALLBACK_PROVIDERS_NON_WINDOWS = ["piper", "macos", "soprano", "kokoro", "elevenlabs"]
+
+# termux-ssh is a TRANSPORT (relays TTS over SSH to a phone), NOT a synthesis
+# provider: it has no catalog record and no play-tts-termux-ssh runtime. It is
+# accepted on non-Windows as a documented non-catalog transport token, and is
+# EXCLUDED BY NAME from the catalog parity assertion (AC6) so it can neither be
+# silently dropped nor silently drift INTO the catalog.
+_TRANSPORT_TOKENS = ["termux-ssh"]
+
+# Embedded fallback display names — byte-equal to catalog.json `displayNames`
+# (group-8 parity). termux-ssh is NOT here (it has no catalog record); its
+# display name is added separately as a transport token.
+_FALLBACK_DISPLAY_NAMES = {
+    "soprano": "Soprano TTS",
+    "piper": "Piper TTS",
+    "kokoro": "Kokoro TTS",
+    "elevenlabs": "ElevenLabs",
+    "macos": "macOS Say",
+    "windows-sapi": "Windows SAPI",
+    "windows-piper": "Piper TTS",
+}
+_TRANSPORT_DISPLAY_NAMES = {
+    "termux-ssh": "Termux SSH",
+}
+
+
 @dataclass
 class ScriptResult:
     """Structured result of running a hook script.
@@ -127,6 +175,91 @@ class AgentVibesServer:
         # the same file at the same time is not covered; see story 8.2 notes).
         self._override_lock = asyncio.Lock()
 
+        # provider-catalog.json is read lazily once and cached (design: no
+        # blocking I/O per call; load at first use, not per set_provider).
+        self._provider_catalog = None
+        self._provider_catalog_loaded = False
+
+    def _load_provider_catalog(self) -> Optional[dict]:
+        """Load the shipped provider-catalog.json ONCE (cached).
+
+        Generated from src/services/provider-catalog.js into
+        .claude/hooks/provider-catalog.json and shipped beside the hooks, it is
+        the SSOT for per-platform provider allowlists and display names. Returns
+        the parsed dict, or None on ANY failure (missing / unreadable /
+        malformed) so the MCP server always starts — callers then fall back to
+        the embedded literals that conformance asserts are equivalent.
+        """
+        if self._provider_catalog_loaded:
+            return self._provider_catalog
+        self._provider_catalog_loaded = True
+        catalog = None
+        try:
+            # catalog.json lives under hooks/ on EVERY platform (program data,
+            # not a per-platform hook script — the generator only writes it there).
+            path = self.claude_dir / "hooks" / "provider-catalog.json"
+            if path.exists() and not path.is_symlink():
+                parsed = json.loads(path.read_text(encoding="utf-8"))
+                if isinstance(parsed, dict):
+                    catalog = parsed
+        except (OSError, ValueError):
+            catalog = None
+        if catalog is None:
+            # Degraded, never dead. Warn on stderr ONLY (stdout is the MCP
+            # JSON-RPC stream); one terse line, since a missing file is the
+            # common installed-tree-skew case.
+            print(
+                "agentvibes: provider-catalog.json unavailable; using embedded provider fallback",
+                file=sys.stderr,
+            )
+        self._provider_catalog = catalog
+        return catalog
+
+    def _valid_providers(self) -> list:
+        """Per-platform provider allowlist, DERIVED from provider-catalog.json.
+
+        Windows → catalog `platforms.windows`; non-Windows → catalog
+        `platforms.darwin` (the superset covering both Linux and macOS). Falls
+        back to the embedded literals when the catalog is unavailable. Transport
+        tokens (termux-ssh) are appended on non-Windows only.
+        """
+        catalog = self._load_provider_catalog()
+        base = None
+        if catalog:
+            platforms = catalog.get("platforms")
+            if isinstance(platforms, dict):
+                key = "windows" if self.is_windows else "darwin"
+                derived = platforms.get(key)
+                if isinstance(derived, list) and derived:
+                    base = list(derived)
+        if base is None:
+            base = list(
+                _FALLBACK_PROVIDERS_WINDOWS if self.is_windows else _FALLBACK_PROVIDERS_NON_WINDOWS
+            )
+        if not self.is_windows:
+            for token in _TRANSPORT_TOKENS:
+                if token not in base:
+                    base.append(token)
+        return base
+
+    def _provider_display_names(self) -> dict:
+        """Provider display names, DERIVED from provider-catalog.json.
+
+        Falls back to the embedded dict when the catalog is unavailable. Non-
+        catalog transport tokens (termux-ssh) are always merged in.
+        """
+        catalog = self._load_provider_catalog()
+        names = None
+        if catalog:
+            derived = catalog.get("displayNames")
+            if isinstance(derived, dict) and derived:
+                names = dict(derived)
+        if names is None:
+            names = dict(_FALLBACK_DISPLAY_NAMES)
+        for token, label in _TRANSPORT_DISPLAY_NAMES.items():
+            names.setdefault(token, label)
+        return names
+
     def _find_claude_dir(self) -> Path:
         """Find the .claude directory relative to this script"""
         # Get the AgentVibes root directory (parent of mcp-server)
@@ -728,33 +861,31 @@ class AgentVibesServer:
 
     async def set_provider(self, provider: str) -> str:
         """
-        Switch TTS provider between Piper, macOS, and Termux SSH.
+        Switch TTS provider between the supported synthesis engines.
 
         Args:
-            provider: Provider name ("piper", "macos", or "termux-ssh")
+            provider: Provider name. Non-Windows: "piper", "macos", "termux-ssh",
+                "soprano", "kokoro", "elevenlabs". Windows: "windows-piper",
+                "windows-sapi", "soprano", "kokoro".
 
         Returns:
             Success or error message
         """
         provider = provider.lower()
-        if self.is_windows:
-            valid_providers = ["windows-piper", "windows-sapi", "soprano"]
-        else:
-            valid_providers = ["piper", "macos", "termux-ssh", "soprano"]
+        # Platform allowlist + display names DERIVE from provider-catalog.json
+        # (SSOT), with embedded fallbacks (module constants above). kokoro is
+        # cross-platform; elevenlabs is Unix-only (NO play-tts-elevenlabs.ps1, so
+        # it is absent from the Windows set — switching to it on Windows would be
+        # silently unplayable). See AVI-S9.1 / AVI-S9.5 and provider-catalog.js
+        # (elevenlabs.runtime.windows === null).
+        valid_providers = self._valid_providers()
         if provider not in valid_providers:
             return f"❌ Invalid provider: {provider}. Choose from: {', '.join(valid_providers)}"
 
         result = await self._run_script("provider-manager.sh", ["switch", provider])
         if result.ok:
-            # Automatically speak confirmation in the new provider's voice
-            provider_names = {
-                "macos": "macOS",
-                "termux-ssh": "Termux SSH",
-                "piper": "Piper",
-                "windows-piper": "Windows Piper",
-                "windows-sapi": "Windows SAPI",
-                "soprano": "Soprano",
-            }
+            # Automatically speak confirmation in the new provider's voice.
+            provider_names = self._provider_display_names()
             provider_name = provider_names.get(provider, provider.title())
             confirmation_text = f"Successfully switched to {provider_name} provider"
 
@@ -775,24 +906,6 @@ class AgentVibesServer:
 
         return f"❌ Failed to switch provider: {result.error_detail}"
 
-    async def set_learn_mode(self, enabled: bool) -> str:
-        """
-        Enable or disable language learning mode.
-
-        When enabled, TTS speaks in both your main language and target language.
-
-        Args:
-            enabled: True to enable, False to disable
-
-        Returns:
-            Success or error message
-        """
-        action = "enable" if enabled else "disable"
-        result = await self._run_script("learn-manager.sh", [action])
-        if result.ok:
-            return result.stdout if "✓" in result.stdout else f"✓ {result.stdout}"
-        return f"❌ Failed to set learn mode: {result.error_detail}"
-
     async def set_speed(self, speed: str, target: bool = False) -> str:
         """
         Set speech speed for main or target voice.
@@ -1591,20 +1704,6 @@ Examples:
                 "required": ["provider"],
             },
         ),
-        Tool(
-            name="set_learn_mode",
-            description="Enable or disable language learning mode. When ON, TTS speaks in both your main language and target language for bilingual learning.",
-            inputSchema={
-                "type": "object",
-                "properties": {
-                    "enabled": {
-                        "type": "boolean",
-                        "description": "True to enable learning mode, False to disable"
-                    }
-                },
-                "required": ["enabled"],
-            },
-        ),
         Tool(
             name="set_speed",
             description="Set speech speed for main or target voice. Works with both Piper and macOS providers. Use this to make voices faster or slower.",
@@ -1900,8 +1999,6 @@ async def call_tool(name: str, arguments: dict) -> list[TextContent] | CallToolR
             result = await agent_vibes.replay_audio(n)
         elif name == "set_provider":
             result = await agent_vibes.set_provider(arguments["provider"])
-        elif name == "set_learn_mode":
-            result = await agent_vibes.set_learn_mode(arguments["enabled"])
         elif name == "set_speed":
             target = arguments.get("target", False)
             result = await agent_vibes.set_speed(arguments["speed"], target)

package/mcp-server/test_mcp_correctness.py

@@ -122,13 +122,12 @@ def test_set_personality_fails_on_nonzero_exit_despite_matching_marker_text():
     "method_name,call_args,plain_stdout",
     [
         ("set_language", ("spanish",), "Language set to: spanish"),
-        ("set_learn_mode", (True,), "Learn mode enabled"),
         ("set_verbosity", ("high",), "Verbosity set to: high (project-local)"),
         ("replay_audio", (1,), "Replaying audio #1: tts-foo.wav"),
     ],
 )
 def test_windows_style_plain_text_success_is_not_treated_as_failure(method_name, call_args, plain_stdout):
-    """set_language / set_learn_mode / set_verbosity / replay_audio must all
+    """set_language / set_verbosity / replay_audio must all
     report success from returncode==0 alone, even when stdout carries none of
     the emoji markers the old code sniffed for (✓ / ✅ / 🔊)."""
     server = AgentVibesServer()
@@ -482,5 +481,24 @@ def test_tool_descriptions_state_20_percent_default_not_30():
     assert "0.30" not in volume_desc
 
 
+def test_valid_providers_derives_from_catalog_and_excludes_elevenlabs_on_windows():
+    """AVI-S9.5: _valid_providers() derives the per-platform allowlist from
+    provider-catalog.json (or the embedded fallback ≡ catalog). ElevenLabs has
+    no Windows runtime (no play-tts-elevenlabs.ps1), so it must be ABSENT from
+    the Windows allowlist and PRESENT on non-Windows — the exact bug class the
+    Provider Catalog closes."""
+    server = AgentVibesServer()
+
+    server.is_windows = True
+    win = server._valid_providers()
+    assert "elevenlabs" not in win, f"elevenlabs must not be a Windows provider: {win}"
+    assert "kokoro" in win and "soprano" in win
+
+    server.is_windows = False
+    non_win = server._valid_providers()
+    assert "elevenlabs" in non_win, f"elevenlabs must be a non-Windows provider: {non_win}"
+    assert "kokoro" in non_win and "soprano" in non_win
+
+
 if __name__ == "__main__":
     sys.exit(pytest.main([__file__, "-v"]))

package/mcp-server/test_windows_script_parity.py

@@ -42,7 +42,6 @@ HOOKS_LINUX = PROJECT_ROOT / ".claude" / "hooks"
 # The auto-conversion (server.py:902-903) converts .sh -> .ps1
 MCP_HARDCODED_SCRIPTS = [
     "provider-manager",
-    "learn-manager",
     "speed-manager",
     "download-extra-voices",
     "verbosity-manager",
@@ -159,7 +158,6 @@ def test_run_script_error_for_missing():
 MCP_TOOL_SCRIPT_MAP = {
     "set_speed": "speed-manager",
     "get_speed": "speed-manager",
-    "set_learn_mode": "learn-manager",
     "set_verbosity": "verbosity-manager",
     "get_verbosity": "verbosity-manager",
     "mute": "verbosity-manager",

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "agentvibes",
-  "version": "5.12.0",
+  "version": "5.13.0",
   "description": "Now your AI Agents can finally talk back! Professional TTS voice for Claude Code, Claude Desktop (via MCP), and Clawdbot with multi-provider support.",
   "homepage": "https://agentvibes.org",
   "keywords": [