agentvibes 4.6.5 → 4.6.6

package/.claude/github-star-reminder.txt

@@ -1 +1 @@
-20260329
+20260403

package/.clawdbot/skill/SKILL.md

@@ -1,241 +1,237 @@
----
-name: agentvibes
-description: 🎤 AgentVibes Voice Management - Manage your text-to-speech voices across multiple providers (Piper TTS, Piper, macOS Say). Switch voices, preview audio, manage providers, add custom voices, and control TTS output.
----
-
-# 🎤 AgentVibes Voice Management
-
-Manage your text-to-speech voices across multiple providers (Piper TTS, Piper, macOS Say).
-
----
-
-## Available Commands
-
-### Voice Control
-
-#### /agent-vibes:mute
-Mute all TTS output (persists across sessions)
-
-- Creates a mute flag that silences all voice output
-- Shows 🔇 indicator when TTS would have played
-
-```bash
-/agent-vibes:mute
-```
-
-#### /agent-vibes:unmute
-Unmute TTS output
-
-- Removes mute flag and restores voice output
-
-```bash
-/agent-vibes:unmute
-```
-
-#### /agent-vibes:list [first|last] [N]
-List all available voices, with optional filtering
-
-```bash
-/agent-vibes:list                    # Show all voices
-/agent-vibes:list first 5            # Show first 5 voices
-/agent-vibes:list last 3             # Show last 3 voices
-```
-
-#### /agent-vibes:preview [first|last] [N]
-Preview voices by playing audio samples
-
-```bash
-/agent-vibes:preview                 # Preview first 3 voices
-/agent-vibes:preview 5               # Preview first 5 voices
-/agent-vibes:preview last 5          # Preview last 5 voices
-```
-
-#### /agent-vibes:switch <voice_name>
-Switch to a different default voice
-
-```bash
-/agent-vibes:switch en_US-amy-medium
-/agent-vibes:switch en_GB-alan-medium
-/agent-vibes:switch fr_FR-siwis-medium
-```
-
-#### /agent-vibes:get
-Display the currently selected voice
-
-```bash
-/agent-vibes:get
-```
-
-#### /agent-vibes:add <name> <voice_id>
-Add a new custom voice from your Piper TTS account
-
-```bash
-/agent-vibes:add "My Voice" abc123xyz456
-```
-
-See [Getting Voice IDs](#getting-voice-ids-piper-tts) section below.
-
-#### /agent-vibes:replay [N]
-Replay recently played TTS audio
-
-```bash
-/agent-vibes:replay                  # Replay last audio
-/agent-vibes:replay 1                # Replay most recent
-/agent-vibes:replay 2                # Replay second-to-last
-/agent-vibes:replay 3                # Replay third-to-last
-```
-
-Keeps last 10 audio files in history.
-
-#### /agent-vibes:set-pretext <word>
-Set a prefix word/phrase for all TTS messages
-
-```bash
-/agent-vibes:set-pretext AgentVibes  # All TTS starts with "AgentVibes:"
-/agent-vibes:set-pretext "Project Alpha" # Custom phrase
-/agent-vibes:set-pretext ""          # Clear pretext
-```
-
-Saved locally in `.agentvibes/config/agentvibes.json`
-
----
-
-## Provider Management
-
-#### /agent-vibes:provider list
-Show all available TTS providers
-
-```bash
-/agent-vibes:provider list
-```
-
-#### /agent-vibes:provider switch <name>
-Switch between providers
-
-```bash
-/agent-vibes:provider switch piper    # Piper TTS - Free, offline, 50+ voices
-/agent-vibes:provider switch macos    # macOS Say - Native macOS voices (Mac only)
-```
-
-#### /agent-vibes:provider info <name>
-Get details about a specific provider
-
-```bash
-/agent-vibes:provider info piper
-/agent-vibes:provider info macos
-```
-
----
-
-## Providers
-
-| Provider | Platform | Cost | Voices | Quality |
-|----------|----------|------|--------|---------|
-| **Piper TTS** | All platforms (Linux, macOS, WSL) | Free | 50+ in 30+ languages | ⭐⭐⭐⭐ |
-| **macOS Say** | macOS only | Free (built-in) | 100+ system voices | ⭐⭐⭐⭐ |
-
-**On macOS**, the native `say` provider is automatically detected and recommended!
-
----
-
-## Getting Voice IDs (Piper TTS)
-
-To add your own custom Piper TTS voices:
-
-1. Go to https://piper.io/app/voice-library
-2. Select or create a voice
-3. Copy the voice ID (15-30 character alphanumeric string)
-4. Use `/agent-vibes:add` to add it:
-
-```bash
-/agent-vibes:add "My Custom Voice" xyz789abc123def456
-```
-
----
-
-## Default Voices
-
-### Piper TTS (Free & Offline)
-
-**English (US):**
-- en_US-lessac-medium (default male voice)
-- en_US-amy-medium (friendly female)
-- en_US-ryan-high (high quality male)
-- en_US-libritts-high (multiple speakers)
-
-**English (UK):**
-- en_GB-alan-medium (British male)
-- en_GB-jenny_dioco-medium (British female)
-
-**Romance Languages:**
-- es_ES-davefx-medium (Spanish - Spain)
-- es_MX-claude-high (Spanish - Mexico)
-- fr_FR-siwis-medium (French female)
-- fr_FR-gilles-low (French male)
-- it_IT-riccardo-x_low (Italian male)
-- pt_BR-faber-medium (Portuguese - Brazilian)
-
-**Germanic Languages:**
-- de_DE-thorsten-medium (German male)
-- de_DE-eva_k-x_low (German female)
-
-**Asian Languages:**
-- ja_JP-ayanami-medium (Japanese female)
-- zh_CN-huayan-x_low (Chinese female)
-- ko_KR-kss-medium (Korean female)
-
-### macOS Say (100+ Built-in)
-- Samantha
-- Alex
-- Daniel
-- Victoria
-- Karen
-- Moira
-- And 100+ more system voices
-
----
-
-## Quick Examples
-
-### Switch to a different voice
-```bash
-/agent-vibes:switch en_US-lessac-medium    # Clear male voice
-/agent-vibes:switch en_US-ryan-high        # High quality male
-/agent-vibes:switch en_GB-alan-medium      # British male
-```
-
-### Preview before choosing
-```bash
-/agent-vibes:preview 5                     # Preview first 5 voices
-/agent-vibes:preview last 3                # Preview last 3 voices
-```
-
-### Add your custom Piper voice
-```bash
-/agent-vibes:add "My Voice" abc123xyz456
-/agent-vibes:switch My Voice
-```
-
-### Switch providers
-```bash
-/agent-vibes:provider switch macos    # Use native macOS voices
-/agent-vibes:provider switch piper    # Switch back to Piper
-```
-
-### Mute/Unmute
-```bash
-/agent-vibes:mute                     # Silent mode
-/agent-vibes:unmute                   # Restore voice
-```
-
----
-
-## Tips & Tricks
-
-- **Preview first**: Always use `/agent-vibes:preview` before switching to a new voice
-- **Provider switching**: Some voices are only available on specific providers
-- **Voice history**: Use `/agent-vibes:replay` to hear the last 10 TTS messages
-- **Custom pretext**: Set a pretext to brand all your responses (e.g., "AgentVibes:")
-- **Mute for focus**: Use `/agent-vibes:mute` during intensive work sessions
-
-Enjoy your TTS experience! 🎵
+---
+name: agentvibes
+description: 🎤 AgentVibes TTS for Claude Code & OpenClaw — Switch voices, set personality, control speed, background music, language learning mode, reverb/effects, and more. Free offline TTS with 914+ Piper voices across 30+ languages. Works on Windows (SAPI/Piper), macOS (Say/Piper), Linux, and Android/Termux. No account or API key required.
+---
+
+# 🎤 AgentVibes Voice Management
+
+Professional text-to-speech for Claude Code and OpenClaw. Free, offline, no account required.
+
+**Providers:** Piper TTS (914+ voices, all platforms) · macOS Say (built-in) · Windows SAPI (zero setup) · Soprano (neural)
+
+---
+
+## Voice Commands
+
+### /agent-vibes:switch \<voice_name\>
+Switch to a different voice.
+
+```bash
+/agent-vibes:switch en_US-amy-medium
+/agent-vibes:switch en_GB-alan-medium
+/agent-vibes:switch fr_FR-siwis-medium
+```
+
+### /agent-vibes:list [first|last] [N]
+List available voices.
+
+```bash
+/agent-vibes:list                    # Show all voices
+/agent-vibes:list first 5            # Show first 5
+/agent-vibes:list last 3             # Show last 3
+```
+
+### /agent-vibes:preview [first|last] [N]
+Preview voices with audio samples.
+
+```bash
+/agent-vibes:preview                 # Preview first 3 voices
+/agent-vibes:preview 5               # Preview first 5
+/agent-vibes:preview last 5          # Preview last 5
+```
+
+### /agent-vibes:sample \<voice_name\>
+Play a sample of a specific voice.
+
+```bash
+/agent-vibes:sample en_US-ryan-high
+```
+
+### /agent-vibes:get
+Show the currently active voice.
+
+### /agent-vibes:set-favorite-voice
+Mark current voice as your favorite.
+
+---
+
+## Personality & Style
+
+### /agent-vibes:personality [name|list|add|edit|get|reset]
+Set a personality style for TTS output.
+
+```bash
+/agent-vibes:personality list          # Show available personalities
+/agent-vibes:personality sarcastic     # Switch to sarcastic style
+/agent-vibes:personality dramatic      # Switch to dramatic style
+/agent-vibes:personality reset         # Back to default
+```
+
+### /agent-vibes:set-pretext \<phrase\>
+Add a spoken prefix before every TTS message.
+
+```bash
+/agent-vibes:set-pretext "AgentVibes"   # Speaks "AgentVibes: ..." before each message
+/agent-vibes:set-pretext ""              # Clear pretext
+```
+
+---
+
+## Speed & Effects
+
+### /agent-vibes:set-speed \<speed\>
+Control speech rate (0.5x – 3.0x).
+
+```bash
+/agent-vibes:set-speed 1.0             # Normal speed
+/agent-vibes:set-speed 1.5             # 50% faster
+/agent-vibes:set-speed 0.8             # Slower
+```
+
+### /agent-vibes:effects [reverb|echo|pitch|eq|reset]
+Configure voice effects.
+
+```bash
+/agent-vibes:effects reverb hall       # Hall reverb
+/agent-vibes:effects reverb none       # No reverb
+/agent-vibes:effects reset             # Clear all effects
+```
+
+---
+
+## Background Music
+
+### /agent-vibes:background-music [on|off|status|list|switch]
+Toggle or change background music played under TTS.
+
+```bash
+/agent-vibes:background-music on       # Enable background music
+/agent-vibes:background-music off      # Disable
+/agent-vibes:background-music list     # Show available tracks
+/agent-vibes:background-music switch jazz  # Switch to jazz track
+```
+
+---
+
+## Verbosity
+
+### /agent-vibes:verbosity [low|medium|high]
+Control how much Claude speaks while working.
+
+```bash
+/agent-vibes:verbosity low             # Brief acknowledgments only
+/agent-vibes:verbosity medium          # Key decisions (default)
+/agent-vibes:verbosity high            # Full reasoning
+```
+
+---
+
+## Mute / Replay
+
+### /agent-vibes:mute / /agent-vibes:unmute
+Silence or restore TTS output (persists across sessions).
+
+### /agent-vibes:replay [N]
+Replay recent audio (last 10 kept).
+
+```bash
+/agent-vibes:replay                    # Replay last audio
+/agent-vibes:replay 2                  # Replay second-to-last
+```
+
+---
+
+## Language & Learning
+
+### /agent-vibes:language \<lang\>
+Set your native language.
+
+```bash
+/agent-vibes:language english
+/agent-vibes:language japanese
+```
+
+### /agent-vibes:learn [on|off]
+Enable language learning mode — Claude speaks in both your native and target language.
+
+```bash
+/agent-vibes:learn on
+/agent-vibes:learn off
+```
+
+### /agent-vibes:translate \<text\>
+Translate and speak text in the target language.
+
+---
+
+## Provider Management
+
+### /agent-vibes:provider [list|switch|info]
+
+```bash
+/agent-vibes:provider list
+/agent-vibes:provider switch piper     # Piper TTS (free, offline, 914+ voices)
+/agent-vibes:provider switch macos     # macOS Say (Mac only)
+/agent-vibes:provider switch sapi      # Windows SAPI (Windows only, zero setup)
+/agent-vibes:provider switch soprano   # Soprano (neural)
+```
+
+---
+
+## Providers
+
+| Provider | Platform | Cost | Voices |
+|----------|----------|------|--------|
+| **Piper TTS** | All platforms | Free, offline | 914+ in 30+ languages |
+| **macOS Say** | macOS only | Free (built-in) | 100+ system voices |
+| **Windows SAPI** | Windows only | Free (built-in) | System voices, zero setup |
+| **Soprano** | All platforms | Free | Neural voices |
+
+---
+
+## Miscellaneous
+
+### /agent-vibes:whoami
+Show current AgentVibes configuration.
+
+### /agent-vibes:version
+Show installed version.
+
+### /agent-vibes:update
+Update AgentVibes to the latest version.
+
+### /agent-vibes:show / /agent-vibes:hide
+Show or hide the AgentVibes status indicator.
+
+### /agent-vibes:cleanup / /agent-vibes:clean
+Remove cached audio files.
+
+---
+
+## Default Voices (Piper TTS — Free & Offline)
+
+**English (US):** en_US-lessac-medium · en_US-amy-medium · en_US-ryan-high · en_US-libritts-high (914 speakers)
+
+**English (UK):** en_GB-alan-medium · en_GB-jenny_dioco-medium
+
+**French:** fr_FR-siwis-medium · fr_FR-gilles-low
+
+**German:** de_DE-thorsten-medium · de_DE-eva_k-x_low
+
+**Spanish:** es_ES-davefx-medium · es_MX-claude-high
+
+**Japanese:** ja_JP-ayanami-medium · **Chinese:** zh_CN-huayan-x_low · **Korean:** ko_KR-kss-medium
+
+**+ 900 more** across 30+ languages. All voices are downloaded from [HuggingFace](https://huggingface.co/rhasspy/piper-voices) — no account required.
+
+---
+
+## Tips
+
+- **Preview first**: Use `/agent-vibes:preview` before committing to a voice
+- **Verbosity**: Set to `low` for focused work, `high` for full narration
+- **BMAD party mode**: Each agent gets their own voice, music, and personality
+- **Replay**: Use `/agent-vibes:replay` to re-hear the last 10 responses
+- **Speed**: Combine with personality for a fully custom TTS character
+
+Enjoy your TTS experience! 🎵

package/CLAUDE.md

@@ -121,6 +121,35 @@ except (PermissionError, UnicodeDecodeError, OSError) as e:
     return default_value
 ```
 
+## Blessed TUI Color Rules (CRITICAL)
+
+Paul's terminal does **not** render hex colors — they all fall back to white. Always use **named ANSI colors**.
+
+### Two coloring mechanisms — use the right one:
+
+**1. Content tags (`tags: true` on the widget) — for text elements:**
+```js
+blessed.text({
+  tags: true,
+  content: `{yellow-fg}some text{/yellow-fg}  {magenta-fg}other text{/magenta-fg}`,
+  style: { bg: COLORS.headerBg },
+});
+```
+- ✅ Works: `{yellow-fg}`, `{cyan-fg}`, `{magenta-fg}`, `{white-fg}`, `{green-fg}`, `{blue-fg}`
+- ❌ Broken: `{#ffff00-fg}`, `{#90a4ae-fg}` — hex tags render as white
+
+**2. Style objects — for list `selected`, `item`, widget `style`:**
+```js
+style: {
+  selected: { bg: 'blue', fg: 'yellow' },   // ✅ named only
+  item: { fg: 'white' },
+}
+```
+- ✅ Works: `'yellow'`, `'blue'`, `'cyan'`, `'magenta'`, `'green'`, `'white'`
+- ❌ Broken: `'#ffff00'`, `'#4a148c'` — hex in style objects renders as white
+
+**Direct screen children render tags correctly.** Elements parented to a `blessed.box` with `tags: false` may not render tags even if the child has `tags: true` — attach directly to `this.screen` instead (same pattern as tab bar items).
+
 ## Code Quality Standards
 
 - ✅ **Error handling:** No silent failures - always handle errors explicitly

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**: v4.6.5
+**Author**: Paul Preibisch ([@997Fire](https://x.com/997Fire)) | **Version**: v4.6.6
 
 ---
 
@@ -28,6 +28,7 @@
 | **Use with OpenClaw** | [OpenClaw Integration](#-openclaw-integration) |
 | **Use natural language** | [MCP Setup](docs/mcp-setup.md) |
 | **Switch voices** | [Voice Library](docs/voice-library.md) |
+| **Configure BMAD Party Mode** (agents with unique voices) | [BMAD Plugin & Party Mode](#-bmad-plugin) |
 | **Fix issues** (git-lfs? MCP tokens? Read this!) | [Troubleshooting](docs/troubleshooting.md) & [FAQ](#-frequently-asked-questions-faq) |
 
 ---
@@ -40,11 +41,16 @@ Whether you're coding in Claude Code, chatting in Claude Desktop, or running Ope
 
 ---
 
+## 🧭 NEW IN v4.6.6 — Natural TUI Navigation
+
+The Settings TUI now flows the way you'd expect. Down moves top-to-bottom through header → sub-tabs → content → footer. Left/Right switches sub-tabs and moves between footer buttons. Up from content returns to the active sub-tab — not always Voice. The Language tab has a proper scrollable list. Readme falls back to the AgentVibes package README when no local one exists. Escape from the installer no longer gets stuck.
+
+---
+
 ## 🔧 NEW IN v4.6.5 — Line Endings, TUI Non-Interactive Hint, Release Process
 
 - **`.gitattributes`** — enforces `LF` for shell scripts/JS/JSON/markdown, `CRLF` for PowerShell; stops `bin/` files showing as modified on Windows
 - **TUI non-interactive hint** — installer header now shows a two-tone hint on row 2: `Skip this UI?` (dim) + `npx agentvibes install --non-interactive` (brighter), matching the `[piper] [en_US-ryan-high]` footer aesthetic
-- **Release process** — mandatory human approval + privacy scan checkpoint before any `git push` or `npm publish`
 
 ---
 
@@ -452,7 +458,7 @@ All 50+ Piper voices AgentVibes provides are sourced from Hugging Face's open-so
   - [🖥️ SSH Receiver](#️-agentvibes-receiver--remote-audio-streaming) - Stream audio from headless servers
   - [💬 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) - v4.6.5 — gitattributes, party mode voice fix, macOS CI fixes
+- [📰 Latest Release](#-latest-release) - v4.6.6 — TUI navigation & UX polish
 - [🪟 Windows Setup Guide for Claude Desktop](mcp-server/WINDOWS_SETUP.md) - Complete Windows installation with WSL & Python
 
 ### AgentVibes MCP (Natural Language Control)
@@ -498,9 +504,9 @@ All 50+ Piper voices AgentVibes provides are sourced from Hugging Face's open-so
 
 ## 📰 Latest Release
 
-**[v4.6.5 - Patch Release](https://github.com/paulpreibisch/AgentVibes/releases/tag/v4.6.5)**
+**[v4.6.6 - Natural TUI Navigation](https://github.com/paulpreibisch/AgentVibes/releases/tag/v4.6.6)**
 
-Infrastructure and tooling improvements: consistent line endings via `.gitattributes`, `bin/` execute bits preserved, and a standardized release process with mandatory human approval and privacy scan checkpoints before any push.
+The Settings TUI now navigates the way you'd expect — arrow keys flow naturally through the interface, the Language tab has a proper scrollable list, and the Readme tab always has something useful to show.
 
 ### 🐛 Recent Fixes (v4.6.3 / v4.6.4)
 
@@ -1174,6 +1180,14 @@ The BMAD plugin detects when you activate a BMAD agent (e.g., `/BMad:agents:pm`)
 
 **Version Support**: AgentVibes supports both BMAD v4 and v6-alpha installations. Version detection is automatic - just install BMAD and AgentVibes will detect and configure itself correctly!
 
+### 🎭 Party Mode — Screenshots
+
+Open the **BMad** tab in the AgentVibes TUI (`npx agentvibes`) to configure which voice each agent uses:
+
+![BMAD Party Mode Tab](docs/installation-screenshots/screenshot-bmad-party-mode.png)
+
+> 📸 **Don't have a screenshot yet?** Run `npx agentvibes`, switch to the **BMad** tab, and take a screenshot — then save it as `docs/installation-screenshots/screenshot-bmad-party-mode.png`.
+
 ### 🔊 TTS Injection: How It Works
 
 BMAD uses a **loosely-coupled injection system** for voice integration. BMAD source files contain placeholder markers that AgentVibes replaces with speaking instructions during installation:

package/RELEASE_NOTES.md

@@ -1,5 +1,24 @@
 # AgentVibes Release Notes
 
+## 🧭 v4.6.6 — Natural TUI Navigation
+
+**Release Date:** April 2026
+
+### Improvements
+
+The Settings TUI now navigates the way you'd expect. Arrow keys flow naturally top-to-bottom through the interface — main header → sub-tab bar → content → footer — with no surprising jumps or dead ends.
+
+- **Down from the main header** lands on the active sub-tab bar item, so you're always oriented before pressing further.
+- **Down through content** moves row-by-row within the current tab, reaching Full Preview and the Save buttons at the bottom. It no longer auto-jumps to the next sub-tab.
+- **Up from the first content row** returns you to the current sub-tab (not always Voice).
+- **Left/Right in the sub-tab bar** is the natural way to switch between Voice, Effects, Personality, Output, and Language tabs.
+- **Left/Right in the footer** moves between Full Preview, Save Globally, Save Locally, and Cancel Changes.
+- **Language tab** now has a proper scrollable list — arrow down to enter it, Up/Down to select a language, Enter to apply, Down past the last item to reach the footer.
+- **Readme tab** falls back to the AgentVibes package README when opened in a project folder that has no README of its own.
+- **Escape from the installer** now navigates cleanly to Settings instead of getting stuck.
+
+---
+
 ## 🔧 v4.6.5 — Patch Release
 
 **Release Date:** April 2026
@@ -16,7 +35,6 @@
 
 - **`bin/` execute bits restored** — Re-indexed `bin/agent-vibes`, `bin/agentvibes-voice-browser.js`, `bin/mcp-server.js`, and `bin/test-bmad-pr` to ensure consistent line endings; verified all four retain `chmod +x` (`100755` mode).
 
-- **Standardized release process** — `/release` command now documents a privacy scan checkpoint: confirm no API keys, no personal info (email, phone, personal port numbers), before committing. CI must be green before releasing.
 
 ### User Impact
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "agentvibes",
-  "version": "4.6.5",
+  "version": "4.6.6",
   "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": [

package/src/console/tabs/agents-tab.js

@@ -124,7 +124,7 @@ const COLORS = {
   sectionHdr: '#7b1fa2',
   labelFg:    '#e3f2fd',
   valueFg:    '#ffff00',
-  activeFg:   '#ce93d8',
+
   btnDefault: '#6a1b9a',
   btnFocus:   '#2e7d32',  // Green — focused/selected
   btnFocusFg: '#ffffff',
@@ -304,7 +304,7 @@ ${_tl('bmadDesc')}
       fg: COLORS.labelFg,
       bg: COLORS.contentBg,
       border: { fg: COLORS.borderFg },
-      selected: { bg: '#4a148c', fg: COLORS.activeFg, bold: true },
+      selected: { bg: 'blue', fg: 'yellow' },
       item: { fg: COLORS.labelFg },
     },
   });
@@ -681,7 +681,7 @@ ${_tl('bmadDesc')}
         fg: COLORS.labelFg,
         bg: COLORS.contentBg,
         border: { fg: '#4a148c' },
-        selected: { bg: '#4a148c', fg: COLORS.activeFg, bold: true },
+        selected: { bg: 'blue', fg: 'yellow' },
         item: { fg: COLORS.labelFg },
       },
     });
@@ -1529,7 +1529,7 @@ ${_tl('bmadDesc')}
         fg: COLORS.labelFg,
         bg: COLORS.contentBg,
         border: { fg: COLORS.btnFocus },
-        selected: { bg: '#4a148c', fg: COLORS.activeFg, bold: true },
+        selected: { bg: 'blue', fg: 'yellow' },
         item: { fg: COLORS.labelFg },
       },
     });

package/src/console/tabs/install-tab.js

@@ -942,13 +942,10 @@ export function createInstallTab(screen, services) {
       _screen--;
       _showCurrentScreen();
     } else {
-      box.hide();
-      screen.render();
-      // Defer so the escape keypress event finishes propagating before focus changes.
-      // Calling focusMainTabBar() synchronously here would set focus to the tab bar
-      // item mid-event, causing its own key(['escape']) handler to fire in the same
-      // emission and call onFocus() → re-focus a button inside the now-hidden box.
-      if (typeof focusMainTabBar === 'function') setTimeout(() => focusMainTabBar(), 0);
+      // User pressed Escape at the first screen — they want out of the installer.
+      // Switch to Settings so they can configure without being stuck on the install tab.
+      // (focusMainTabBar would re-focus the install tab item, which loops back here.)
+      setTimeout(() => navigationService?.switchTab('settings'), 0);
     }
   });
 

package/src/console/tabs/readme-tab.js

@@ -146,9 +146,12 @@ export function createReadmeTab(screen, services) {
   // Load README.md
 
   function _loadReadme() {
+    // Package root — works whether installed globally (node_modules/.bin) or run from source
+    const pkgRoot = path.resolve(new URL(import.meta.url).pathname, '..', '..', '..', '..');
     const candidates = [
       path.resolve(process.cwd(), 'README.md'),
       path.resolve(process.cwd(), 'readme.md'),
+      path.resolve(pkgRoot, 'README.md'),  // AgentVibes package README fallback
     ];
     for (const p of candidates) {
       if (fs.existsSync(p)) {

package/src/console/tabs/settings-tab.js

@@ -1760,37 +1760,57 @@ export function createSettingsTab(screen, services) {
     style: { fg: COLORS.valueFg, bg: COLORS.contentBg },
   });
 
-  let _langListIdx = 0;
-
-  const languageList = blessed.box({
+  // Visible list height — cap at 10 rows (fits standard 24-row terminals with headers)
+  const LANG_LIST_HEIGHT = Math.min(SUPPORTED_LANGUAGES.length, 10);
+
+  // blessed.list: natively focusable, handles selection highlight, scrolling.
+  // keys:true needed so keypress events propagate to the element (keyable=true).
+  // We immediately removeAllListeners('keypress') to strip blessed's built-in up/down nav —
+  // our manual .key() handlers (registered on 'key down'/'key up') are the sole navigators.
+  const languageList = blessed.list({
     parent: box,
     top: 7,
     left: 4,
-    width: 40,
-    height: Math.min(SUPPORTED_LANGUAGES.length + 2, 12),
-    tags: true,
-    content: '',
-    style: { fg: COLORS.labelFg, bg: COLORS.contentBg },
+    width: 44,
+    height: LANG_LIST_HEIGHT + 2,  // +2 for border
+    keys: true,
+    mouse: true,
+    tags: false,
+    items: SUPPORTED_LANGUAGES.map(l => l.name),
+    style: {
+      selected: { bg: 'green', fg: 'white', bold: true },
+      item: { fg: 'white' },
+      border: { fg: 'cyan' },
+      focus: { border: { fg: 'yellow' } },
+    },
+    border: { type: 'line' },
+    scrollable: true,
+    scrollbar: { style: { bg: 'blue' } },
   });
+  // Strip blessed's built-in keypress nav (up/down/j/k/etc.) — our .key() handlers take over.
+  // .key() registers on 'key <name>' events (not 'keypress'), so they survive this removal.
+  languageList.removeAllListeners('keypress');
 
-  function _renderLangList() {
-    const lines = SUPPORTED_LANGUAGES.map((l, i) =>
-      i === _langListIdx
-        ? `{green-fg}► ${l.name}{/green-fg}`
-        : `  ${l.name}`
-    );
-    languageList.setContent(lines.join('\n'));
-  }
+  // Hint shown below the list
+  const langHint = blessed.text({
+    parent: box,
+    top: 7 + LANG_LIST_HEIGHT + 3,
+    left: 4,
+    content: '{gray-fg}↑↓ navigate · Enter to apply{/gray-fg}',
+    tags: true,
+    style: { bg: COLORS.contentBg },
+  });
 
+  // Apply button — kept for mouse users; keyboard users just press Enter on the list
   const langApplyBtn = _createButton(box, screen, '✓ Apply Language', COLORS, () => {
-    const selected = SUPPORTED_LANGUAGES[_langListIdx];
+    const selected = SUPPORTED_LANGUAGES[languageList.selected ?? 0];
     if (selected && services.languageService) {
       services.languageService.setLang(selected.value);
       refreshLanguageDisplay();
       _showNotice(screen, `Language: ${selected.name}`);
     }
   }, { bg: '#2e7d32' });
-  langApplyBtn.top = 7 + Math.min(SUPPORTED_LANGUAGES.length + 2, 12) + 1;
+  langApplyBtn.top = 7 + LANG_LIST_HEIGHT + 5;
   langApplyBtn.left = 4;
 
   function refreshLanguageDisplay() {
@@ -1798,19 +1818,11 @@ export function createSettingsTab(screen, services) {
     const found = SUPPORTED_LANGUAGES.find(l => l.value === currentLang);
     languageCurrentValue.setContent(found ? found.name : currentLang);
     const idx = SUPPORTED_LANGUAGES.findIndex(l => l.value === currentLang);
-    if (idx >= 0) _langListIdx = idx;
-    _renderLangList();
+    if (idx >= 0) languageList.select(idx);
     screen.render();
   }
 
-  // Key navigation for language list
-  box.key(['up', 'down'], (ch, key) => {
-    if (_activeSubTab !== 'language') return;
-    if (key.name === 'up') _langListIdx = Math.max(0, _langListIdx - 1);
-    if (key.name === 'down') _langListIdx = Math.min(SUPPORTED_LANGUAGES.length - 1, _langListIdx + 1);
-    _renderLangList();
-    screen.render();
-  });
+  // Key navigation wired after _navigateRow is defined (see below)
 
   // -------------------------------------------------------------------------
   // Display state + button-level focus navigation (story 7.6)
@@ -1847,8 +1859,7 @@ export function createSettingsTab(screen, services) {
     language: [
       languageSectionHeader,
       languageCurrentLabel, languageCurrentValue,
-      languageList,
-      langApplyBtn,
+      languageList, langHint, langApplyBtn,
     ],
   };
 
@@ -1858,7 +1869,7 @@ export function createSettingsTab(screen, services) {
     effects:     [[reverbChangeBtn, reverbTestBtn], [trackChangeBtn, musicToggleBtn, musicTestBtn], [volumeChangeBtn]],
     personality: [[verbosityChangeBtn], [personalityChangeBtn, personalityTestBtn], [introEditBtn, introClearBtn]],
     output:      [[audioDstChangeBtn], [audioSshEditBtn, audioStreamModeBtn]],
-    language:    [[langApplyBtn]],
+    language:    [[languageList], [langApplyBtn]],
   };
 
   const _subTabItemsArray = SUB_TABS.map(id => _subTabItemsMap[id]);
@@ -1906,7 +1917,7 @@ export function createSettingsTab(screen, services) {
 
   const _buttons = [
     _subTabItemsMap.voice, _subTabItemsMap.effects,
-    _subTabItemsMap.personality, _subTabItemsMap.output,
+    _subTabItemsMap.personality, _subTabItemsMap.output, _subTabItemsMap.language,
     switchBtn, changeBtn, playBtn,
     reverbChangeBtn, reverbTestBtn,
     trackChangeBtn, musicToggleBtn, musicTestBtn,
@@ -1914,6 +1925,7 @@ export function createSettingsTab(screen, services) {
     verbosityChangeBtn, personalityChangeBtn, personalityTestBtn,
     introEditBtn, introClearBtn,
     audioDstChangeBtn, audioSshEditBtn, audioStreamModeBtn,
+    languageList, langApplyBtn,
     fullPreviewBtn,
     saveGloballyBtn, saveLocallyBtn, cancelChangesBtn,
   ];
@@ -2030,74 +2042,6 @@ export function createSettingsTab(screen, services) {
       return;
     }
 
-    // _rows layout: [0]=sub-tab bar, [1..lastContent]=per-tab rows, then 3 shared bottom rows
-    const BOTTOM_ROWS = 2; // [fullPreviewBtn], [saveGlobally+saveLocally+cancelChanges]
-    const lastContentIdx = _rows.length - BOTTOM_ROWS - 1;
-
-    // Cross-tab forward: ↓ from the effective last visible content row → jump to next sub-tab
-    if (delta > 0 && rowIdx >= 1 && rowIdx <= lastContentIdx) {
-      let isEffectiveLast = true;
-      for (let r = rowIdx + 1; r <= lastContentIdx; r++) {
-        if (_isRowVisible(_rows[r])) { isEffectiveLast = false; break; }
-      }
-      if (isEffectiveLast) {
-        const tabIdx = SUB_TABS.indexOf(_activeSubTab);
-        if (tabIdx < SUB_TABS.length - 1) {
-          const nextTab = SUB_TABS[tabIdx + 1];
-          _showSubTab(nextTab, true);
-          const firstRow = _rowsBySubTab[nextTab].find(row => _isRowVisible(row));
-          if (firstRow) {
-            const btn = _firstVisibleBtn(firstRow);
-            _currentIdx = _buttons.indexOf(btn);
-            _focusButton(btn);
-            return;
-          }
-        }
-        // On the last sub-tab: fall through to normal (go to fullPreviewBtn)
-      }
-    }
-
-    // Cross-tab backward: ↑ from first content row (row 1) → jump to previous sub-tab's last row
-    if (delta < 0 && rowIdx === 1) {
-      const tabIdx = SUB_TABS.indexOf(_activeSubTab);
-      if (tabIdx > 0) {
-        const prevTab = SUB_TABS[tabIdx - 1];
-        _showSubTab(prevTab, true);
-        const prevRows = _rowsBySubTab[prevTab];
-        let lastRow = null;
-        for (let i = prevRows.length - 1; i >= 0; i--) {
-          if (_isRowVisible(prevRows[i])) { lastRow = prevRows[i]; break; }
-        }
-        if (lastRow) {
-          const btn = _firstVisibleBtn(lastRow);
-          _currentIdx = _buttons.indexOf(btn);
-          _focusButton(btn);
-          return;
-        }
-      }
-      // First sub-tab: fall through (goes to sub-tab bar at row 0)
-    }
-
-    // In the bottom save row: ↓ navigates to the next visible sibling within the row
-    // rather than wrapping to row 0 (sub-tab bar) via modulo.
-    const lastRowIdx = _rows.length - 1;
-    if (delta > 0 && rowIdx === lastRowIdx) {
-      const row = _rows[lastRowIdx];
-      const posInRow = row.indexOf(focused);
-      for (let i = posInRow + 1; i < row.length; i++) {
-        if (!row[i].hidden) {
-          _currentIdx = _buttons.indexOf(row[i]);
-          _focusButton(row[i]);
-          return;
-        }
-      }
-      // Last sibling in the row — wrap up to sub-tab bar (row 0)
-      const topBtn = _firstVisibleBtn(_rows[0]);
-      _currentIdx = _buttons.indexOf(topBtn);
-      _focusButton(topBtn);
-      return;
-    }
-
     // Skip rows where ALL buttons are hidden (e.g. SSH alias row when destination is local).
     // Use _firstVisibleBtn so we land on the first visible button in a mixed row.
     let attempts = 0;
@@ -2105,17 +2049,56 @@ export function createSettingsTab(screen, services) {
       rowIdx = (rowIdx + delta + _rows.length) % _rows.length;
       attempts++;
     } while (!_isRowVisible(_rows[rowIdx]) && attempts < _rows.length);
-    const btn = _firstVisibleBtn(_rows[rowIdx]);
+    // When landing on the sub-tab bar (row 0), focus the ACTIVE sub-tab item, not the first one
+    const btn = rowIdx === 0
+      ? (_subTabItemsMap[_activeSubTab] ?? _firstVisibleBtn(_rows[0]))
+      : _firstVisibleBtn(_rows[rowIdx]);
     _currentIdx = _buttons.indexOf(btn);
     _focusButton(btn);
   }
 
   for (const btn of _buttons) {
-    btn.key(['down'],   () => _navigateRow(1));
-    btn.key(['up'],     () => _navigateRow(-1));
+    btn.key(['down'], () => {
+      if (btn === languageList) return;  // languageList has its own boundary-aware down handler
+      _navigateRow(1);
+    });
+    btn.key(['up'], () => {
+      if (btn === languageList) return;  // languageList has its own boundary-aware up handler
+      _navigateRow(-1);
+    });
     btn.key(['escape'], () => { if (typeof focusMainTabBar === 'function') setTimeout(() => focusMainTabBar(), 0); });
   }
 
+  // Language list — fully manual navigation (keys:false on the list disables blessed's built-in
+  // so only our handlers run, giving us clean boundary detection without double-move issues).
+  languageList.key(['down'], () => {
+    const cur = languageList.selected ?? 0;
+    if (cur >= SUPPORTED_LANGUAGES.length - 1) {
+      _navigateRow(1);  // past last item → Apply button
+    } else {
+      languageList.select(cur + 1);
+      screen.render();
+    }
+  });
+  languageList.key(['up'], () => {
+    const cur = languageList.selected ?? 0;
+    if (cur <= 0) {
+      _navigateRow(-1);  // past first item → sub-tab bar
+    } else {
+      languageList.select(cur - 1);
+      screen.render();
+    }
+  });
+  languageList.key(['enter', 'return', 'space'], () => {
+    const selected = SUPPORTED_LANGUAGES[languageList.selected ?? 0];
+    if (selected && services.languageService) {
+      services.languageService.setLang(selected.value);
+      refreshLanguageDisplay();
+      _showNotice(screen, `Language: ${selected.name}`);
+    }
+  });
+  languageList.key(['escape'], () => { if (typeof focusMainTabBar === 'function') setTimeout(() => focusMainTabBar(), 0); });
+
   // ← / → within content rows — uses _buttonGroups (static); sub-tab bar has its own wiring
   const _rows = [];  // populated dynamically by _showSubTab()
 
@@ -2129,8 +2112,9 @@ export function createSettingsTab(screen, services) {
     [introEditBtn, introClearBtn],
     [audioDstChangeBtn],
     [audioSshEditBtn, audioStreamModeBtn],
-    [fullPreviewBtn],
-    [saveGloballyBtn, saveLocallyBtn, cancelChangesBtn],
+    [languageList],
+    [langApplyBtn],
+    [fullPreviewBtn, saveGloballyBtn, saveLocallyBtn, cancelChangesBtn],
   ];
 
   for (const row of _buttonGroups) {
@@ -2425,9 +2409,12 @@ export function createSettingsTab(screen, services) {
     },
 
     onFocus() {
+      // Land on the active sub-tab bar item so the user can ↑↓ from there.
       // Use _focusButton (not raw .focus()) so olines get invalidated before render,
       // preventing the ghost-duplicate-row artifact on initial tab activation.
-      _focusButton(_buttons[_currentIdx]);
+      const activeSubTabItem = _subTabItemsMap[_activeSubTab];
+      _currentIdx = _buttons.indexOf(activeSubTabItem);
+      _focusButton(activeSubTabItem);
     },
 
     onBlur() {

package/src/installer.js

@@ -5352,6 +5352,12 @@ Troubleshooting:
       await fs.writeFile(langConfigPath, lang, { mode: 0o600 });
     }
 
+    // Default translation to auto: syncs with BMAD communication_language if set, otherwise no translation
+    const translateFile = path.join(claudeDir, 'tts-translate-to.txt');
+    try { await fs.access(translateFile); } catch {
+      await fs.writeFile(translateFile, 'auto', { mode: 0o600 });
+    }
+
     // Apply verbosity, personality, pretext
     await fs.writeFile(path.join(claudeDir, 'tts-verbosity.txt'), userConfig.verbosity);
     if (userConfig.personality && userConfig.personality !== 'none') {

package/.claude/config/background-music-enabled.txt

@@ -1 +0,0 @@
-true