agentvibes 5.11.2 → 5.12.0-alpha.0

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

@@ -213,7 +213,7 @@ if ($BgEnabled -or $HasReverb) {
 #   1. Key           - Must start with "llm:" followed by the LLM name
 #   2. REVERB_PRESET - One of: off, light, medium, heavy, cathedral (or blank)
 #   3. BACKGROUND_FILE - Filename relative to .claude/audio/tracks/ (or blank)
-#   4. BACKGROUND_VOLUME - Float 0.0-1.0 (or blank for default 0.25)
+#   4. BACKGROUND_VOLUME - Float 0.0-1.0 (or blank for default 0.20)
 #   5. VOICE         - Provider voice name to use (or blank for global default)
 #   6. PRETEXT       - Text prepended to all TTS utterances (or blank)
 #   7. ENGINE        - Windows engine: windows-sapi, windows-piper, soprano (or blank)
@@ -263,6 +263,99 @@ if (-not $llm) {
 # the POSIX play-tts.sh so the cross-platform contract is symmetric.
 $env:AGENTVIBES_LLM_KEY = "llm:$llm"
 
+# ── Utterance Resolver (AVI-S8.5 Stage 2) ────────────────────────────────────
+# Single source of truth for the voice + engine decision, mirroring the bash
+# play-tts.sh port. Resolve the plan ONCE and adopt its voice (per-LLM voice
+# wins over an LLM-echoed explicit override — R2) and, below, its local engine
+# (a kokoro-shaped voice forces the kokoro engine and engine aliases normalize —
+# R1/F5). FAIL-SAFE: if node or the resolver bundle isn't reachable (e.g. an
+# installed ~/.claude that predates the bundle-shipping installer), $PlanOk
+# stays $false and the legacy logic below runs unchanged — Windows TTS never
+# breaks on a missing bridge. AGENTVIBES_RESOLVER_CLI lets the installer (or
+# tests) point at the resolver bundle when it lives outside the hooks tree.
+
+# Map a resolver engine name to its Windows provider script. Returns $null for
+# engines with no local Windows script (e.g. elevenlabs/macos) so the caller
+# keeps the current provider rather than breaking playback.
+function Resolve-ProviderScriptForEngine {
+    param([string]$Engine, [string]$HooksRoot)
+    switch ($Engine) {
+        { $_ -in "windows-sapi", "sapi" } {
+            $s = "$HooksRoot\play-tts-sapi.ps1"
+            if (-not (Test-Path $s)) { $s = "$HooksRoot\play-tts-windows-sapi.ps1" }
+            return $s
+        }
+        { $_ -in "windows-piper", "piper" } {
+            $s = "$HooksRoot\play-tts-piper.ps1"
+            if (-not (Test-Path $s)) { $s = "$HooksRoot\play-tts-windows-piper.ps1" }
+            return $s
+        }
+        "soprano" { return "$HooksRoot\play-tts-soprano.ps1" }
+        "kokoro"  { return "$HooksRoot\play-tts-kokoro.ps1" }
+        default   { return $null }
+    }
+}
+
+$_OrigExplicitVoice = $VoiceOverride   # raw positional voice, before any per-LLM override
+$PlanOk         = $false
+$PlanVoice      = ""
+$PlanEngine     = ""
+$PlanVoiceIsOverride = $false
+# F-3: the SSH-receiver watcher forwards the sender's engine via -ProviderOverride
+# (a parameter the resolver can't see). Seed AGENTVIBES_FORCE_PROVIDER from it so
+# the resolver honors the forwarded provider instead of defaulting the plan engine
+# to piper (which dropped a forwarded windows-sapi/soprano voice → wrong/no audio).
+if ($ProviderOverride) {
+    # A fresh -ProviderOverride for THIS request must win over any stale/inherited
+    # AGENTVIBES_FORCE_PROVIDER in the environment (a validated allowlist only).
+    switch ($ProviderOverride) {
+        { $_ -in @('piper','soprano','macos','windows-sapi','sapi','kokoro','elevenlabs','windows-piper') } {
+            $env:AGENTVIBES_FORCE_PROVIDER = $ProviderOverride
+        }
+    }
+}
+$_ResolverCli = ""
+foreach ($_cand in @(
+        $env:AGENTVIBES_RESOLVER_CLI,
+        (Join-Path $ScriptPath "..\agentvibes-resolver\bin\resolve-utterance.js"),
+        (Join-Path $ScriptPath "..\..\bin\resolve-utterance.js"),
+        (Join-Path $ScriptPath "resolve-utterance.js"))) {
+    if ($_cand -and (Test-Path $_cand)) { $_ResolverCli = $_cand; break }
+}
+$_NodeCmd = Get-Command node -ErrorAction SilentlyContinue
+if ($_ResolverCli -and $_NodeCmd) {
+    # Voice provenance (F-1): AGENTVIBES_VOICE_SOURCE lets a caller declare it
+    # (MCP/watcher → user-explicit/agent-profile); audition never demotes; else
+    # llm-echo (parroted get_config voice, which the per-LLM row overrides — R2).
+    $_VoiceSource = if ($env:AGENTVIBES_VOICE_SOURCE) { $env:AGENTVIBES_VOICE_SOURCE }
+                    elseif ($env:AGENTVIBES_EFFECTS_PREVIEW) { "audition" }
+                    else { "llm-echo" }
+    $_ResolverPackageRoot = Split-Path -Parent $ClaudeDir
+    $_ResolverProjectDir = if ($env:CLAUDE_PROJECT_DIR) { $env:CLAUDE_PROJECT_DIR } else { $_ResolverPackageRoot }
+    $_ResolverArgs = @('--format', 'json', '--text', $Text, '--llm', $llm,
+                       '--voice-source', $_VoiceSource, '--project-dir', $_ResolverProjectDir,
+                       '--package-root', $_ResolverPackageRoot)
+    # Only pass --voice when there IS an explicit voice; an absent flag tells the
+    # resolver "no explicit override" (so per-LLM routing applies cleanly).
+    if ($_OrigExplicitVoice) { $_ResolverArgs += @('--voice', $_OrigExplicitVoice) }
+    try {
+        $_PlanJson = & $_NodeCmd.Source $_ResolverCli @_ResolverArgs 2>$null
+        if ($LASTEXITCODE -eq 0 -and $_PlanJson) {
+            $_Plan = ($_PlanJson | Out-String).Trim() | ConvertFrom-Json
+            if ($_Plan) {
+                $PlanOk = $true
+                if ($_Plan.voice)  { $PlanVoice  = [string]$_Plan.voice }
+                if ($_Plan.engine) { $PlanEngine = [string]$_Plan.engine }
+                $PlanVoiceIsOverride = [bool]$_Plan.voiceIsOverride
+            }
+        }
+    } catch {
+        # Any bridge failure (bad JSON, nonzero exit, missing bundle) fails safe
+        # to the legacy logic below.
+        $PlanOk = $false
+    }
+}
+
 # --- Lookup per-LLM config in audio-effects.cfg ------------------------------
 # Scan project config first, then user-profile config.  Stop at first match.
 # Variables are intentionally prefixed with _ to distinguish LLM-local state
@@ -320,8 +413,20 @@ $_LlmFound = $false
 # 3. BMAD agent voice from bmad-voice-map.json (resolved in provider scripts)
 # 4. Global active voice from tts-provider.txt / active-voice.txt
 
-# Apply LLM-specific voice only when no explicit -VoiceOverride was passed
-if ($_LlmVoice -and -not $VoiceOverride) {
+# Adopt the resolver's voice when a plan resolved (AVI-S8.5 Stage 2). The plan
+# already applied the R2 precedence (per-LLM voice wins over an LLM-echoed
+# explicit override; genuine explicit/audition voices still win), so take it
+# verbatim. FAIL-SAFE fallback: with no plan, use the legacy explicit-wins order
+# (explicit -VoiceOverride > per-LLM voice).
+# F-2: adopt the plan voice ONLY when it's a real override (explicit pick or
+# per-LLM row) — not the provider's stored voice file. A plain provider-file
+# voice is left empty here so the provider script does its own file+model+speaker
+# resolution (adopting it as an explicit override skips piper's multi-speaker
+# lookup and plays speaker 0). Engine coupling (R1) still applies regardless.
+if ($PlanOk -and $PlanVoiceIsOverride -and $PlanVoice) {
+    $VoiceOverride = $PlanVoice
+}
+elseif (-not $PlanOk -and $_LlmVoice -and -not $VoiceOverride) {
     $VoiceOverride = $_LlmVoice
 }
 
@@ -398,31 +503,45 @@ if ($OverrideEffects -ne "" -and $OverrideEffects -in @("off", "light", "medium"
 # piper/sapi for that LLM's normal text responses that use Piper voices — must
 # NOT redirect it to an incompatible engine, or synthesis fails silently
 # (Piper can't find the Kokoro voice model → no audio, exit 0).
-$_VoiceIsKokoro = $VoiceOverride -match '^[a-z]{2}_[a-z0-9_]+$'
-if ($_VoiceIsKokoro) {
-    # A Kokoro-format voice forces the Kokoro engine regardless of the per-LLM
-    # ENGINE column or the global tts-provider.txt default.
-    $ProviderScript = "$HooksDir\play-tts-kokoro.ps1"
-}
-elseif ($_LlmEngine) {
-    # Accept both canonical Windows names and the cross-platform aliases the TUI
-    # writes (e.g. "piper" saved on a Linux/WSL install that is later read on
-    # Windows, or "sapi" as a short form).  Unknown values keep the global default.
-    # Mirror the global-provider switch: prefer the PS-5.1-compatible script name,
-    # fall back to the alternate name if the first doesn't exist on disk.
-    switch ($_LlmEngine) {
-        { $_ -in "windows-sapi", "sapi" } {
-            $ProviderScript = "$HooksDir\play-tts-sapi.ps1"
-            if (-not (Test-Path $ProviderScript)) { $ProviderScript = "$HooksDir\play-tts-windows-sapi.ps1" }
-        }
-        { $_ -in "windows-piper", "piper" } {
-            $ProviderScript = "$HooksDir\play-tts-piper.ps1"
-            if (-not (Test-Path $ProviderScript)) { $ProviderScript = "$HooksDir\play-tts-windows-piper.ps1" }
-        }
-        "soprano" { $ProviderScript = "$HooksDir\play-tts-soprano.ps1" }
-        "kokoro" { $ProviderScript = "$HooksDir\play-tts-kokoro.ps1" }
-        default {
-            Write-Host "[INFO] play-tts.ps1: Unrecognised engine '$_LlmEngine' — keeping default provider" -ForegroundColor DarkGray
+if ($PlanOk -and $PlanEngine) {
+    # Resolver plan is authoritative for the LOCAL engine (AVI-S8.5 Stage 2):
+    # this cures the kokoro/piper voice->engine coupling (R1) and normalizes
+    # engine aliases like windows-sapi->sapi (F5), replacing the legacy heuristic
+    # below. An engine with no local Windows script (elevenlabs/macos) leaves the
+    # current provider in place.
+    $_PlanScript = Resolve-ProviderScriptForEngine -Engine $PlanEngine -HooksRoot $HooksDir
+    if ($_PlanScript) { $ProviderScript = $_PlanScript }
+}
+else {
+    # Legacy voice->engine heuristic — ONLY on the fallback path (no resolver
+    # plan). When a plan resolved, the resolver already coupled voice->engine
+    # correctly above, so this is skipped.
+    $_VoiceIsKokoro = $VoiceOverride -match '^[a-z]{2}_[a-z0-9_]+$'
+    if ($_VoiceIsKokoro) {
+        # A Kokoro-format voice forces the Kokoro engine regardless of the per-LLM
+        # ENGINE column or the global tts-provider.txt default.
+        $ProviderScript = "$HooksDir\play-tts-kokoro.ps1"
+    }
+    elseif ($_LlmEngine) {
+        # Accept both canonical Windows names and the cross-platform aliases the TUI
+        # writes (e.g. "piper" saved on a Linux/WSL install that is later read on
+        # Windows, or "sapi" as a short form).  Unknown values keep the global default.
+        # Mirror the global-provider switch: prefer the PS-5.1-compatible script name,
+        # fall back to the alternate name if the first doesn't exist on disk.
+        switch ($_LlmEngine) {
+            { $_ -in "windows-sapi", "sapi" } {
+                $ProviderScript = "$HooksDir\play-tts-sapi.ps1"
+                if (-not (Test-Path $ProviderScript)) { $ProviderScript = "$HooksDir\play-tts-windows-sapi.ps1" }
+            }
+            { $_ -in "windows-piper", "piper" } {
+                $ProviderScript = "$HooksDir\play-tts-piper.ps1"
+                if (-not (Test-Path $ProviderScript)) { $ProviderScript = "$HooksDir\play-tts-windows-piper.ps1" }
+            }
+            "soprano" { $ProviderScript = "$HooksDir\play-tts-soprano.ps1" }
+            "kokoro" { $ProviderScript = "$HooksDir\play-tts-kokoro.ps1" }
+            default {
+                Write-Host "[INFO] play-tts.ps1: Unrecognised engine '$_LlmEngine' — keeping default provider" -ForegroundColor DarkGray
+            }
         }
     }
 }
@@ -437,7 +556,20 @@ elseif ($_LlmEngine) {
 
 # --- Diagnostic output -------------------------------------------------------
 # Set AGENTVIBES_VERBOSE=1 in the shell environment to print routing state.
+# The bare `provider=`/`voice=`/`plan=` lines mirror play-tts.sh's verbose
+# DECISION echo so the resolved engine/voice can be characterization-tested
+# without producing real audio (see test/windows/play-tts-resolver.Tests.ps1).
 if ($env:AGENTVIBES_VERBOSE -eq "1") {
+    $_ProviderName = switch -Wildcard ($ProviderScript) {
+        "*play-tts-kokoro.ps1"  { "kokoro" }
+        "*soprano*"             { "soprano" }
+        "*piper*"               { "piper" }
+        "*sapi*"                { "sapi" }
+        default                 { Split-Path -Leaf $ProviderScript }
+    }
+    Write-Output "provider=$_ProviderName"
+    Write-Output "voice=$VoiceOverride"
+    Write-Output ("plan=" + $(if ($PlanOk) { "ok" } else { "fallback" }))
     Write-Host "[DEBUG] play-tts.ps1 LLM routing: llm=$llm | voice=$VoiceOverride | engine=$_LlmEngine | pretext=$_LlmPretext" -ForegroundColor DarkCyan
     Write-Host "[DEBUG] play-tts.ps1 LLM routing: reverb=$ReverbLevel | HasFfmpeg=$HasFfmpeg | BgEnabled=$BgEnabled | script=$ProviderScript" -ForegroundColor DarkCyan
 }
@@ -574,8 +706,9 @@ if (($BgEnabled -or $HasReverb) -and $HasFfmpeg) {
                 $BgTrackPath = Join-Path $TracksDir "agent_vibes_bachata_v1_loop.mp3"
             }
 
-            # Get volume (default 0.25) — per-message override takes precedence
-            $BgVolume = "0.25"
+            # Get volume (default 0.20) — per-message override takes precedence
+            # TODO(AVI-S8.6): generate this constant from the shared JSON source of truth.
+            $BgVolume = "0.20"
             $VolumeFile = "$ConfigDir\background-music-volume.txt"
             if (Test-Path $VolumeFile) {
                 $vol = (Get-Content $VolumeFile -Raw).Trim()

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

@@ -6,7 +6,7 @@
 
 param(
     [Parameter(Position = 0)]
-    [ValidateSet('list', 'switch', 'get')]
+    [ValidateSet('list', 'switch', 'get', 'replay')]
     [string]$Command = 'list',
 
     [Parameter(Position = 1)]
@@ -155,6 +155,102 @@ function Show-CurrentVoice {
     }
 }
 
+# Play an audio file without blocking the caller (mirrors voice-manager.sh's
+# `afplay "$AUDIO_FILE" &` / `paplay ... &` background playback). Prefers
+# ffplay (handles wav/mp3/aiff); falls back to System.Media.SoundPlayer
+# (.Play(), which is inherently async — wav only).
+function Start-ReplayPlayback {
+    param([string]$FilePath)
+
+    # Stay silent while the automated test suite is running (same convention
+    # as play-tts.ps1's Invoke-AudioPlay).
+    if (Test-Path (Join-Path $env:USERPROFILE ".agentvibes-tests-running")) { return }
+
+    $ffplayCmd = Get-Command ffplay -ErrorAction SilentlyContinue
+    if ($ffplayCmd) {
+        Start-Process -FilePath $ffplayCmd.Source `
+            -ArgumentList @("-autoexit", "-nodisp", "-loglevel", "quiet", $FilePath) `
+            -WindowStyle Hidden | Out-Null
+        return
+    }
+
+    try {
+        $player = New-Object System.Media.SoundPlayer $FilePath
+        $player.Play()
+    }
+    catch {
+        Write-Host "[WARN] Could not start playback: $_" -ForegroundColor Yellow
+    }
+}
+
+# Replay the Nth most recent TTS audio file (mirrors voice-manager.sh's
+# `replay` case: resolve the audio dir, validate N (1-10), pick the file by
+# most-recent-mtime, and play it in the background).
+function Replay-Audio {
+    param([string]$NArg)
+
+    $AudioDir = $null
+    if ($env:CLAUDE_PROJECT_DIR -and (Test-Path (Join-Path $env:CLAUDE_PROJECT_DIR ".claude"))) {
+        $AudioDir = Join-Path $env:CLAUDE_PROJECT_DIR ".claude\audio"
+    }
+    else {
+        # Walk up from cwd looking for a .claude directory (same fallback as voice-manager.sh).
+        # Use a plain string path throughout: Get-Location returns a PathInfo (.Path),
+        # but Get-Item returns a DirectoryInfo (no .Path) — mixing them made the second
+        # iteration do Join-Path $null and throw a terminating error.
+        $dirPath = (Get-Location).Path
+        while ($dirPath) {
+            $candidate = Join-Path $dirPath ".claude"
+            if (Test-Path $candidate) {
+                $AudioDir = Join-Path $candidate "audio"
+                break
+            }
+            $parent = Split-Path $dirPath -Parent
+            if (-not $parent -or $parent -eq $dirPath) { break }
+            $dirPath = $parent
+        }
+        if (-not $AudioDir) {
+            $AudioDir = Join-Path $ClaudeDir "audio"
+        }
+    }
+
+    $N = 1
+    if ($NArg) {
+        if ($NArg -notmatch '^\d+$') {
+            Write-Host "[ERROR] Invalid argument. Please use a number (1-10)" -ForegroundColor Red
+            exit 1
+        }
+        $N = [int]$NArg
+    }
+    if ($N -lt 1 -or $N -gt 10) {
+        Write-Host "[ERROR] Number out of range. Please choose 1-10" -ForegroundColor Red
+        exit 1
+    }
+
+    if (-not (Test-Path $AudioDir)) {
+        Write-Host "[ERROR] No audio history found" -ForegroundColor Red
+        Write-Host "Audio files are stored in: $AudioDir"
+        exit 1
+    }
+
+    $files = @(Get-ChildItem -Path $AudioDir -File -ErrorAction SilentlyContinue |
+        Where-Object { $_.Name -match '^tts-.*\.(wav|mp3|aiff)$' } |
+        Sort-Object LastWriteTime -Descending)
+
+    if ($files.Count -lt $N) {
+        Write-Host "[ERROR] Audio #$N not found in history" -ForegroundColor Red
+        Write-Host "Total audio files available: $($files.Count)"
+        exit 1
+    }
+
+    $target = $files[$N - 1]
+    Write-Host "[REPLAY] Replaying audio #${N}:" -ForegroundColor Cyan
+    Write-Host "   File: $($target.Name)"
+    Write-Host "   Path: $($target.FullName)"
+
+    Start-ReplayPlayback $target.FullName
+}
+
 # Main command routing
 switch ($Command) {
     'list' {
@@ -173,4 +269,8 @@ switch ($Command) {
     'get' {
         Show-CurrentVoice
     }
+
+    'replay' {
+        Replay-Audio $VoiceName
+    }
 }

package/.clawdbot/README.md

@@ -1,105 +1,105 @@
-# Clawdbot Integration
-
-AgentVibes TTS integration for Clawdbot - the AI assistant framework.
-
-## What is Clawdbot?
-
-Clawdbot is a powerful AI assistant framework that connects Claude AI to messaging platforms (WhatsApp, Telegram, Discord, etc.) and provides extensible skills.
-
-**Website**: https://clawd.bot
-**GitHub**: https://github.com/clawdbot/clawdbot
-
-## AgentVibes + Clawdbot
-
-This integration provides Clawdbot with professional TTS capabilities using AgentVibes:
-
-- **Free & Offline**: No API costs, works without internet
-- **50+ Voices**: Professional AI voices in 30+ languages
-- **Remote SSH Support**: Audio tunnels from server to local machine
-- **Zero Setup**: Automatic when AgentVibes is installed
-
-## Installation
-
-```bash
-npx agentvibes install
-```
-
-That's it! AgentVibes is ready to use.
-
-## Usage from Clawdbot
-
-Once installed, use AgentVibes for TTS:
-
-```bash
-npx agentvibes speak "Hello from Clawdbot"
-```
-
-## Features
-
-- **Automatic Detection**: Clawdbot automatically uses AgentVibes when available
-- **Voice Selection**: 50+ voices across 30+ languages
-- **SSH Tunneling**: Audio plays on local machine from remote servers
-- **Zero Config**: Works out of the box once AgentVibes is installed
-
-## Remote SSH Audio
-
-When running Clawdbot on a remote server, set up PulseAudio tunneling so audio plays on your local machine:
-
-**Quick Setup:**
-
-1. **Remote server** (`~/.bashrc`):
-```bash
-export PULSE_SERVER=tcp:localhost:14713
-```
-
-2. **Local machine** (`~/.ssh/config`):
-```
-Host your-server
-    RemoteForward 14713 localhost:14713
-```
-
-3. **Connect and test**:
-```bash
-ssh your-server
-agentvibes speak "Testing remote audio"
-```
-
-**Full guide**: https://github.com/paulpreibisch/AgentVibes/blob/master/docs/remote-audio-setup.md
-
-## Documentation
-
-- **Skill Documentation**: [skill/SKILL.md](skill/SKILL.md)
-- **AgentVibes Docs**: https://agentvibes.org
-- **Clawdbot Docs**: https://docs.clawd.bot
-
-## Architecture
-
-```
-Clawdbot Request
-    ↓
-AgentVibes Skill (this)
-    ↓
-AgentVibes CLI (agentvibes speak)
-    ↓
-Piper TTS Engine
-    ↓
-PulseAudio → SSH Tunnel → Local Speakers
-```
-
-## Development
-
-The skill is automatically packaged with AgentVibes npm releases. To update:
-
-1. Edit `skill/SKILL.md`
-2. Test with Clawdbot
-3. Commit to AgentVibes repo
-4. Publish new AgentVibes version
-
-## Support
-
-- **AgentVibes Issues**: https://github.com/paulpreibisch/AgentVibes/issues
-- **Clawdbot Issues**: https://github.com/clawdbot/clawdbot/issues
-
-## License
-
-Apache 2.0 - Same as AgentVibes
+# Clawdbot Integration
+
+AgentVibes TTS integration for Clawdbot - the AI assistant framework.
+
+## What is Clawdbot?
+
+Clawdbot is a powerful AI assistant framework that connects Claude AI to messaging platforms (WhatsApp, Telegram, Discord, etc.) and provides extensible skills.
+
+**Website**: https://clawd.bot
+**GitHub**: https://github.com/clawdbot/clawdbot
+
+## AgentVibes + Clawdbot
+
+This integration provides Clawdbot with professional TTS capabilities using AgentVibes:
+
+- **Free & Offline**: No API costs, works without internet
+- **50+ Voices**: Professional AI voices in 30+ languages
+- **Remote SSH Support**: Audio tunnels from server to local machine
+- **Zero Setup**: Automatic when AgentVibes is installed
+
+## Installation
+
+```bash
+npx agentvibes install
+```
+
+That's it! AgentVibes is ready to use.
+
+## Usage from Clawdbot
+
+Once installed, use AgentVibes for TTS:
+
+```bash
+npx agentvibes speak "Hello from Clawdbot"
+```
+
+## Features
+
+- **Automatic Detection**: Clawdbot automatically uses AgentVibes when available
+- **Voice Selection**: 50+ voices across 30+ languages
+- **SSH Tunneling**: Audio plays on local machine from remote servers
+- **Zero Config**: Works out of the box once AgentVibes is installed
+
+## Remote SSH Audio
+
+When running Clawdbot on a remote server, set up PulseAudio tunneling so audio plays on your local machine:
+
+**Quick Setup:**
+
+1. **Remote server** (`~/.bashrc`):
+```bash
+export PULSE_SERVER=tcp:localhost:14713
+```
+
+2. **Local machine** (`~/.ssh/config`):
+```
+Host your-server
+    RemoteForward 14713 localhost:14713
+```
+
+3. **Connect and test**:
+```bash
+ssh your-server
+agentvibes speak "Testing remote audio"
+```
+
+**Full guide**: https://github.com/paulpreibisch/AgentVibes/blob/master/docs/remote-audio-setup.md
+
+## Documentation
+
+- **Skill Documentation**: [skill/SKILL.md](skill/SKILL.md)
+- **AgentVibes Docs**: https://agentvibes.org
+- **Clawdbot Docs**: https://docs.clawd.bot
+
+## Architecture
+
+```
+Clawdbot Request
+    ↓
+AgentVibes Skill (this)
+    ↓
+AgentVibes CLI (agentvibes speak)
+    ↓
+Piper TTS Engine
+    ↓
+PulseAudio → SSH Tunnel → Local Speakers
+```
+
+## Development
+
+The skill is automatically packaged with AgentVibes npm releases. To update:
+
+1. Edit `skill/SKILL.md`
+2. Test with Clawdbot
+3. Commit to AgentVibes repo
+4. Publish new AgentVibes version
+
+## Support
+
+- **AgentVibes Issues**: https://github.com/paulpreibisch/AgentVibes/issues
+- **Clawdbot Issues**: https://github.com/clawdbot/clawdbot/issues
+
+## License
+
+Apache 2.0 - Same as AgentVibes