agentvibes 5.5.0 → 5.6.1

package/README.md

@@ -11,7 +11,7 @@
 [![Publish](https://github.com/paulpreibisch/AgentVibes/actions/workflows/publish.yml/badge.svg)](https://github.com/paulpreibisch/AgentVibes/actions/workflows/publish.yml)
 [![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
 
-**Author**: Paul Preibisch ([@997Fire](https://x.com/997Fire)) | **Version**: v5.5
+**Author**: Paul Preibisch ([@997Fire](https://x.com/997Fire)) | **Version**: v5.6.1
 
 ---
 
@@ -40,13 +40,22 @@ Whether you're coding in Claude Code, chatting in Claude Desktop, using Warp Ter
 
 ---
 
-## 🌟 NEW IN v5.5 — Per-LLM Audio Routing
+## 🌟 NEW IN v5.6.1 — Hermes Agent Integration
+
+AgentVibes now speaks for **[Hermes Agent](https://github.com/NousResearch/hermes-agent)** — the self-hosted, self-improving AI assistant. Two production-ready skills ship in `docs/hermes/skills/`:
+
+- **`hermes-agentvibes-hook`** — Auto-speaks every Hermes response via AgentVibes TTS. Fires on `agent:end`, strips markdown, rate-limits, and ships with full SSH MITM protection
+- **`agentvibes-target`** — Teaches Hermes to send any text to your speakers on demand, supporting laptop and Android targets
+
+Also in this release: Windows PS5.1 compatibility fixes for `play-tts.ps1`, modal/hotkey repairs, and BMAD tab now shows all agents.
+
+## v5.5 — Per-LLM Audio Routing
 
 Give **each LLM its own voice, pretext, and music** — Claude Code, Copilot, and Codex can all sound different without touching global settings.
 
 - Add `llm:<name>|...|voice|pretext|engine` rows to `audio-effects.cfg`
 - MCP server auto-detects which LLM is calling and passes `--llm <key>`
-- Configure via **Setup → Default → Configure** in the TUI
+- Configure via **Setup tab → Configure** in the TUI
 
 Also fixed: Windows installer crash (`spinner.info is not a function`) on **reinstall** with an older global AgentVibes install.
 
@@ -54,34 +63,20 @@ Also fixed: Windows installer crash (`spinner.info is not a function`) on **rein
 
 ## v5.4 — TUI Installer, Spinner Fix & Dependency Cleanup
 
-### 🎤 Agent Vibes v1.0 Voice Browser
-
-**🎤 Browse, Sample & Install 914 Voices in Real-Time**
-
-```bash
-npx agentvibes-voice-browser
-```
+### 🎤 Voice Browser — Browse, Sample & Install 914 Voices
 
-The new **AgentVibes Voice Browser** is an interactive console application that lets you:
+**Built right into the TUI — accessible via Setup → Configure → Voice**
 
-- 🎧 **Hear Before You Choose** - Real-time audio sampling with one keypress
-- ⭐ **Mark Your Favorites** - Build your personal voice collection
-- 🔍 **Smart Search** - Filter by name, personality, accent, or gender
-- 📦 **One-Click Install** - Press 'I' to instantly switch to any voice
-- 🎨 **Beautiful Interface** - Stunning terminal UI powered by blessed.js
+- 🎧 **Hear Before You Choose** - Press Space to preview any voice instantly
+- ⭐ **Mark Your Favorites** - Thumbs up/down with `+` / `-`
+- 🔍 **Alpha Jump** - Press any letter to jump to names starting with it
+- 📦 **One-Click Select** - Press Enter to set as your voice
+- 🎨 **Beautiful Interface** - Stunning terminal UI built into AgentVibes
 
 **914 Total Voices:**
 - 904 High-Quality Piper TTS Speakers (libritts-high model)
 - 10 Hand-Curated Personality Voices
 
-**Perfect for:**
-- Finding your ideal AI voice
-- Exploring voice characteristics
-- Quick voice switching
-- Building favorite collections
-
-Launch now: `npx agentvibes-voice-browser`
-
 ---
 
 ### 💬 Intro Text (Pretext) - Your Personal AI Branding
@@ -132,9 +127,11 @@ Configure now: `npx agentvibes config intro-text`
 **Upload your own background music with battle-tested security!**
 
 ```bash
-npx agentvibes config music
+npx agentvibes   # press M for Music tab
 ```
 
+![AgentVibes Music Tab](https://raw.githubusercontent.com/paulpreibisch/AgentVibes/master/docs/installation-screenshots/screenshot-music.png)
+
 Replace the default background tracks with your own audio files for complete sonic branding.
 
 **Supported Formats:**
@@ -252,10 +249,10 @@ All 50+ Piper voices AgentVibes provides are sourced from Hugging Face's open-so
 - [📋 Prerequisites](#-prerequisites) - What you actually need (Node.js + optional tools)
 - [✨ What is AgentVibes?](#-what-is-agentvibes) - Overview & key features
 - [🌟 NEW FEATURE HIGHLIGHTS](#-new-feature-highlights) - **START HERE!**
-  - [🎤 Voice Browser v1.0](#-agent-vibes-v10-voice-browser) - Browse & sample 914 voices
+  - [🎤 Voices Tab](#-voices-tab) - Browse & sample 914 voices in the TUI
   - [💬 Intro Text](#-intro-text-pretext---your-personal-ai-branding) - Custom TTS prefixes
   - [🎵 Custom Background Music](#-custom-background-music---complete-audio-control) - Upload your own tracks
-- [📰 Latest Release](#-latest-release) - v3.6.0 "Voice Explorer" with Voice Browser, Friendly Names, Custom Music
+- [📰 Latest Release](#-latest-release) - v5.5.0 with Per-LLM Audio Routing, Windows Installer Resilience
 - [🪟 Windows Setup Guide for Claude Desktop](mcp-server/WINDOWS_SETUP.md) - Complete Windows installation with WSL & Python
 
 ### AgentVibes MCP (Natural Language Control)
@@ -265,7 +262,7 @@ All 50+ Piper voices AgentVibes provides are sourced from Hugging Face's open-so
   - [For Claude Code](docs/mcp-setup.md#for-claude-code) - Project-specific setup
 
 ### Core Features
-- [🎤 AgentVibes Voice Browser](#-agentvibes-voice-browser) - **Browse and sample 914 voices interactively**
+- [🎤 Voices Tab](#-voices-tab) - **Browse and sample 914 voices in the TUI**
 - [🎤 Commands Reference](#-commands-reference) - All available commands
 - [🎙️ Verbosity Control](#%EF%B8%8F-verbosity-control) - Control how much Claude speaks (low/medium/high)
 - [🎭 Personalities vs Sentiments](#-personalities-vs-sentiments) - Two systems explained
@@ -303,20 +300,17 @@ All 50+ Piper voices AgentVibes provides are sourced from Hugging Face's open-so
 
 **[v3.6.0 - "Voice Explorer" Release](https://github.com/paulpreibisch/AgentVibes/releases/tag/v3.6.0)** 🎉
 
-### 🎤 AgentVibes Voice Browser
+### 🎤 Voices Tab — Browse & Sample 914 Voices
 
-**Browse and sample 914 voices in real-time!**
+**Built into the TUI — launch with `npx agentvibes` then press V**
 
-```bash
-npx agentvibes-voice-browser
-```
+![AgentVibes Voices Tab](https://raw.githubusercontent.com/paulpreibisch/AgentVibes/master/docs/installation-screenshots/screenshot-voices.png)
 
-Interactive console browser with:
-- 🎧 Real-time voice sampling - hear before you choose
+- 🎧 Real-time voice sampling - press Space to hear before you choose
 - ⭐ Favorite system - mark your top voices
 - 🔍 Search & filter - find voices by personality, accent, gender
-- 📦 One-click install - install directly from browser
-- 🎨 Beautiful UI - stunning console interface
+- 📦 One-click select - press Enter to install directly
+- 🎨 Beautiful UI - built into the AgentVibes TUI
 
 **914 Total Voices:**
 - 904 Piper speaker variations (libritts-high)
@@ -379,8 +373,8 @@ npx agentvibes config music
 # Install AgentVibes
 npx agentvibes install
 
-# Launch Voice Browser
-npx agentvibes-voice-browser
+# Browse voices in the TUI
+npx agentvibes  # press V for Voices tab
 ```
 
 **🐞 Bug Fixes in v3.6.0:**
@@ -432,6 +426,12 @@ Just say "Switch to Aria voice" or "Speak in Spanish" instead of typing commands
 npx agentvibes install
 ```
 
+![AgentVibes Setup Tab — LLM Providers](https://raw.githubusercontent.com/paulpreibisch/AgentVibes/master/docs/installation-screenshots/screenshot-setup.png)
+
+Click **Configure** on any LLM to set its voice, pretext, reverb, and music:
+
+![AgentVibes Configure Claude Code Audio](https://raw.githubusercontent.com/paulpreibisch/AgentVibes/master/docs/installation-screenshots/screenshot-configure.png)
+
 ### 2️⃣ Choose Provider (Auto-Detected)
 - **macOS**: Native `say` provider (100+ voices) ✨
 - **Linux/WSL**: Piper TTS (50+ free voices) 🎙️
@@ -457,39 +457,37 @@ macOS ships with bash 3.2 (from 2007). After this, everything works perfectly!
 
 ---
 
-## 🎤 AgentVibes Voice Browser
+## 🎤 Voice Browser
 
-**The easiest way to find your perfect voice!**
-
-### Launch the Browser
+**914 voices — browse, preview, and select right inside the TUI.**
 
 ```bash
-npx agentvibes-voice-browser
+npx agentvibes   # Setup tab → Configure → Voice  (or press V for global voice)
 ```
 
+![AgentVibes Voice Browser](https://raw.githubusercontent.com/paulpreibisch/AgentVibes/master/docs/installation-screenshots/screenshot-voice-browser.png)
+
 ### Features
 
 - **914 Voices** - Browse 904 Piper speakers + 10 curated voices
-- **Real-Time Sampling** - Press ENTER to hear any voice instantly
-- **Favorite System** - Mark favorites for quick access
-- **Smart Search** - Filter by name, personality, accent, or gender
-- **One-Click Install** - Press 'I' to install and switch to a voice
-- **Beautiful UI** - Stunning console interface with blessed.js
+- **Real-Time Sampling** - Press Space to hear any voice instantly
+- **Favorite System** - Thumbs up `+` / thumbs down `-` for quick filtering
+- **Alpha Jump** - Press any letter key to jump to that part of the list
+- **One-Click Select** - Press Enter to install and switch to a voice
+- **Beautiful UI** - Stunning console interface built into AgentVibes
 
 ### Keyboard Shortcuts
 
 | Key | Action |
 |-----|--------|
-| **ENTER** | Play voice sample |
-| **I** | Install/Select voice for AgentVibes |
-| **F** | Toggle favorite |
-| **/** | Search voices |
-| **ESC** | Clear search / Back |
+| **Space** | Preview voice sample |
+| **Enter** | Select/Install voice |
+| **+** | Thumbs up (favorite) |
+| **-** | Thumbs down |
+| **PgUp / PgDn** | Page through list |
 | **↑/↓** | Navigate list |
-| **G** | Jump to top |
-| **Shift+G** | Jump to bottom |
-| **H** | Show help |
-| **Q** | Quit |
+| **a-z** | Jump to names starting with letter |
+| **Esc** | Cancel / close |
 
 ### Voice Categories
 
@@ -505,13 +503,13 @@ npx agentvibes-voice-browser
 
 ### Finding Your Perfect Voice
 
-1. **Launch browser:** `npx agentvibes-voice-browser`
-2. **Search by trait:** Press `/` and type "friendly" or "professional"
-3. **Sample voices:** Navigate with arrows, press ENTER to hear
-4. **Mark favorites:** Press 'F' on voices you like
-5. **Install:** Press 'I' to set as your AgentVibes voice
+1. **Open voice browser:** Setup tab → Configure → navigate to Voice → Enter
+2. **Jump alphabetically:** Press a letter key to jump to that name
+3. **Sample voices:** Navigate with arrows, press Space to hear
+4. **Mark favorites:** Press `+` on voices you like
+5. **Select:** Press Enter to set as your voice
 
-**Pro Tip:** Use the search to find voices matching your project's mood!
+**Pro Tip:** Use PgUp/PgDn to page quickly through 900+ voices!
 
 [↑ Back to top](#-table-of-contents)
 
@@ -860,18 +858,13 @@ AgentVibes provides **50+ slash commands** and **natural language MCP equivalent
 
 **[→ View Complete Command Reference](docs/commands.md)** - All voice, system, personality, sentiment, language, and BMAD commands with MCP equivalents
 
-### Voice Browser Commands
+### Voices Tab Commands
 
 ```bash
-# Launch voice browser
-npx agentvibes-voice-browser
-
-# Or use global command (if installed globally)
-agentvibes-voice-browser
+# Launch the TUI and open Voices tab
+npx agentvibes  # then press V
 ```
 
-**MCP Equivalent:** Currently CLI-only (no MCP command)
-
 ### Intro Text Commands
 
 ```bash
@@ -1010,7 +1003,7 @@ Every task acknowledgment plays **twice** - first in English, then in your targe
 
 ## 🗣️ Voice Library
 
-**NEW in v3.6.0:** Use the **[AgentVibes Voice Browser](#-agentvibes-voice-browser)** to browse, sample, and install from 914 voices! Launch with `npx agentvibes-voice-browser`.
+**Browse voices in the TUI:** Run `npx agentvibes` and press **V** to open the **[Voices Tab](#-voices-tab)** — browse, sample, and install from 914 voices without leaving your terminal.
 
 ### Friendly Voice Names
 
@@ -1052,13 +1045,11 @@ 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 Tab — Assign a Voice to Every Agent
 
-![BMAD Party Mode Tab](docs/installation-screenshots/screenshot-bmad-party-mode.png)
+Open the **BMad** tab in the AgentVibes TUI (`npx agentvibes` → press **B**) to configure which voice, reverb, and pretext each BMAD agent uses:
 
-> 📸 **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`.
+![AgentVibes BMad Tab](https://raw.githubusercontent.com/paulpreibisch/AgentVibes/master/docs/installation-screenshots/screenshot-bmad.png)
 
 ### 🔊 TTS Injection: How It Works
 
@@ -1882,10 +1873,10 @@ Both do the exact same thing - MCP is more convenient, slash commands are more t
 - **Optional**: sox (audio effects), ffmpeg (background music, padding)
 - All TTS generation works without optional dependencies - they just enhance the experience
 
-### Voice Browser & New Features
+### Voices Tab & New Features
 
-**Q: How do I use the Voice Browser?**
-**A:** Simply run `npx agentvibes-voice-browser` and you'll see an interactive console with 914 voices. Use arrow keys to navigate, ENTER to sample voices, 'I' to install, 'F' to favorite, and '/' to search.
+**Q: How do I browse and select voices?**
+**A:** Run `npx agentvibes` and press **V** to open the Voices tab. Use arrow keys to navigate, Space to preview voices, Enter to select/install, F to favorite, and / to search.
 
 **Q: What are friendly voice names?**
 **A:** Instead of technical IDs like `en_US-ryan-high`, you can now use simple names like "Ryan" when switching voices. All 904+ voices have friendly names matched to their characteristics.
@@ -1903,7 +1894,7 @@ Both do the exact same thing - MCP is more convenient, slash commands are more t
 **A:** No! You can type "ryan", "Ryan", or "RYAN" - they all work. The voice resolution is case-insensitive.
 
 **Q: Can I favorite voices without installing them?**
-**A:** Yes! In the Voice Browser, press 'F' to mark any voice as a favorite. Favorites are saved and you can filter to show only favorites later.
+**A:** Yes! In the Voices tab, press 'F' to mark any voice as a favorite. Favorites are saved and you can filter to show only favorites later.
 
 **Q: Does custom music work with all TTS providers?**
 **A:** Yes! Custom background music works with Piper TTS, Soprano, macOS Say, and Windows SAPI.

package/RELEASE_NOTES.md

@@ -1,5 +1,66 @@
 # AgentVibes Release Notes
 
+## 🤖 v5.6.1 — Hermes Agent Integration & Windows PS5.1 Fixes
+
+**Released:** 2026-05-01
+
+### 🎉 Hermes Agent Integration (New!)
+
+AgentVibes now officially supports **[Hermes Agent](https://github.com/NousResearch/hermes-agent)** — the self-hosted, self-improving AI assistant. Two production-ready Hermes skills ship in `docs/hermes/skills/`:
+
+**`hermes-agentvibes-hook`** — Auto-speaks every Hermes response via AgentVibes
+- Fires on every `agent:end` event (Telegram, Discord, CLI, etc.)
+- Strips markdown, code blocks, emoji before speaking
+- Truncates at word boundaries, rate-limits to prevent queue flooding
+- MITM-safe SSH with `StrictHostKeyChecking=accept-new` + persistent `known_hosts`
+- Full logging to `tts-hook.log` for debugging
+
+**`agentvibes-target`** — Teaches Hermes to send any text to your speakers on demand
+- Base64 JSON payload over SSH (same ForceCommand architecture as the Windows receiver)
+- Supports Windows and Android targets
+- Detailed troubleshooting guide included
+
+**Install:** Copy the skill to your Hermes home and restart the gateway:
+```bash
+cp -r docs/hermes/skills/tts/hermes-agentvibes-hook ~/.hermes/skills/tts/
+hermes gateway restart
+```
+
+### 🐛 Windows PS5.1 Bug Fixes
+
+- **play-tts.ps1 PS5.1 compatibility** — Fixed three regressions from v5.6.0 rebase:
+  replaced PS7 null-conditional (`?.`) with PS5.1-compatible if/else, added UTF-8 BOM so
+  em-dash literals aren't mangled by CP1252, restored piper provider alias and
+  `AGENTVIBES_TEXT_FILE` sentinel lost in merge
+- **Modal & hotkey fixes** — Modal escape key, navigation hotkeys, Q+Caps Lock, and voice
+  preview error handling all repaired
+- **BMAD tab** — Now shows all agents regardless of module
+
+---
+
+## 📸 v5.6.0 — TUI Screenshots & Documentation Cleanup
+
+**Released:** 2026-04-28
+
+### 📸 TUI Screenshots Added
+
+Added real screenshots of every major TUI tab to the README:
+
+- **Setup tab** — LLM Providers screen (Claude Code, Copilot, Codex, Default)
+- **Configure dialog** — Per-LLM audio config (voice, pretext, reverb, music)
+- **Voice Browser** — Select Voice dialog with alpha-jump, thumbs up/down, 914 voices
+- **Music tab** — Built-in tracks list with preview and toggle
+- **BMad tab** — Agent voice assignment (voice, reverb, music, pretext per agent)
+
+### 🧹 Documentation Cleanup
+
+- Removed all `npx agentvibes-voice-browser` references (tool retired, replaced by TUI)
+- Renamed "Voice Browser" section to reflect TUI-native access via Setup → Configure → Voice
+- All image paths now use absolute GitHub raw URLs (renders correctly on npmjs.com)
+- Fixed BMad section placeholder screenshot replaced with real screenshot
+
+---
+
 ## 🎵 v5.5.0 — Per-LLM Audio Routing & Windows Installer Resilience
 
 **Released:** 2026-04-27

package/bin/agent-vibes

@@ -1,40 +1,40 @@
 #!/usr/bin/env node
-
-/**
- * AgentVibes - Beautiful ElevenLabs TTS voice commands for Claude Code
- * This file ensures proper execution when run via npx
- */
-
-import { execFileSync } from 'node:child_process';
-import path from 'node:path';
-import fs from 'node:fs';
-import { fileURLToPath } from 'node:url';
-
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = path.dirname(__filename);
-
-// Check if we're running in an npx temporary directory
-const isNpxExecution = __dirname.includes('_npx') || __dirname.includes('.npm');
-
-// Get CLI arguments
-const arguments_ = process.argv.slice(2);
-
-// Route through the TUI console (agentvibes.js) which handles install/config/etc
-const installerPath = path.join(__dirname, 'agentvibes.js');
-
-if (!fs.existsSync(installerPath)) {
-  console.error('Error: Could not find installer.js at', installerPath);
-  console.error('Current directory:', __dirname);
-  process.exit(1);
-}
-
-try {
-  // Security: Use execFileSync with array args to prevent command injection
-  // Arguments are passed as array elements, not string interpolation
-  execFileSync('node', [installerPath, ...arguments_], {
-    stdio: 'inherit',
-    cwd: path.dirname(__dirname),
-  });
-} catch (error) {
-  process.exit(error.status || 1);
-}
+
+/**
+ * AgentVibes - Beautiful ElevenLabs TTS voice commands for Claude Code
+ * This file ensures proper execution when run via npx
+ */
+
+import { execFileSync } from 'node:child_process';
+import path from 'node:path';
+import fs from 'node:fs';
+import { fileURLToPath } from 'node:url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+// Check if we're running in an npx temporary directory
+const isNpxExecution = __dirname.includes('_npx') || __dirname.includes('.npm');
+
+// Get CLI arguments
+const arguments_ = process.argv.slice(2);
+
+// Route through the TUI console (agentvibes.js) which handles install/config/etc
+const installerPath = path.join(__dirname, 'agentvibes.js');
+
+if (!fs.existsSync(installerPath)) {
+  console.error('Error: Could not find installer.js at', installerPath);
+  console.error('Current directory:', __dirname);
+  process.exit(1);
+}
+
+try {
+  // Security: Use execFileSync with array args to prevent command injection
+  // Arguments are passed as array elements, not string interpolation
+  execFileSync('node', [installerPath, ...arguments_], {
+    stdio: 'inherit',
+    cwd: path.dirname(__dirname),
+  });
+} catch (error) {
+  process.exit(error.status || 1);
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "agentvibes",
-  "version": "5.5.0",
+  "version": "5.6.1",
   "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/bmad-detector.js

@@ -1,71 +1,71 @@
-import path from 'node:path';
-import fs from 'node:fs/promises';
-import yaml from 'js-yaml';
-
-/**
- * Detect BMAD installation and version
- * @param {string} targetDir - Directory to check
- * @returns {Promise<Object>} Detection result with version info
- */
-export async function detectBMAD(targetDir) {
-  // Check v6 first (newer version) - support both .bmad and bmad paths
-  // Try .bmad (standard path with dot prefix) first
-  let v6Manifest = path.join(targetDir, '.bmad/_cfg/manifest.yaml');
-  let bmadPath = '.bmad';
-
-  try {
-    await fs.access(v6Manifest);
-  } catch {
-    // Try bmad (alternative path without dot prefix)
-    v6Manifest = path.join(targetDir, 'bmad/_cfg/manifest.yaml');
-    bmadPath = 'bmad';
-    try {
-      await fs.access(v6Manifest);
-    } catch {
-      // Neither path found, continue to v4 check
-      bmadPath = null;
-    }
-  }
-
-  if (bmadPath) {
-    try {
-      const manifestContent = await fs.readFile(v6Manifest, 'utf8');
-      const manifest = yaml.load(manifestContent);
-
-      return {
-        version: 6,
-        detailedVersion: manifest.installation?.version || '6.0.0-alpha.x',
-        manifestPath: v6Manifest,
-        configPath: path.join(targetDir, bmadPath, 'core/config.yaml'),
-        bmadPath: path.join(targetDir, bmadPath),
-        installed: true
-      };
-    } catch {}
-  }
-
-  // Check v4 (legacy)
-  const v4Manifest = path.join(targetDir, '.bmad-core/install-manifest.yaml');
-  try {
-    await fs.access(v4Manifest);
-    return {
-      version: 4,
-      detailedVersion: '4.x',
-      manifestPath: v4Manifest,
-      configPath: path.join(targetDir, '.bmad-core/config.yaml'),
-      bmadPath: path.join(targetDir, '.bmad-core'),
-      installed: true
-    };
-  } catch {}
-
-  // Not installed
-  return { version: null, installed: false };
-}
-
-/**
- * Get BMAD configuration file path for detected version
- * @param {Object} detection - Result from detectBMAD()
- * @returns {string|null} Path to config.yaml or null
- */
-export function getBMADConfigPath(detection) {
-  return detection.installed ? detection.configPath : null;
-}
+import path from 'node:path';
+import fs from 'node:fs/promises';
+import yaml from 'js-yaml';
+
+/**
+ * Detect BMAD installation and version
+ * @param {string} targetDir - Directory to check
+ * @returns {Promise<Object>} Detection result with version info
+ */
+export async function detectBMAD(targetDir) {
+  // Check v6 first (newer version) - support both .bmad and bmad paths
+  // Try .bmad (standard path with dot prefix) first
+  let v6Manifest = path.join(targetDir, '.bmad/_cfg/manifest.yaml');
+  let bmadPath = '.bmad';
+
+  try {
+    await fs.access(v6Manifest);
+  } catch {
+    // Try bmad (alternative path without dot prefix)
+    v6Manifest = path.join(targetDir, 'bmad/_cfg/manifest.yaml');
+    bmadPath = 'bmad';
+    try {
+      await fs.access(v6Manifest);
+    } catch {
+      // Neither path found, continue to v4 check
+      bmadPath = null;
+    }
+  }
+
+  if (bmadPath) {
+    try {
+      const manifestContent = await fs.readFile(v6Manifest, 'utf8');
+      const manifest = yaml.load(manifestContent);
+
+      return {
+        version: 6,
+        detailedVersion: manifest.installation?.version || '6.0.0-alpha.x',
+        manifestPath: v6Manifest,
+        configPath: path.join(targetDir, bmadPath, 'core/config.yaml'),
+        bmadPath: path.join(targetDir, bmadPath),
+        installed: true
+      };
+    } catch {}
+  }
+
+  // Check v4 (legacy)
+  const v4Manifest = path.join(targetDir, '.bmad-core/install-manifest.yaml');
+  try {
+    await fs.access(v4Manifest);
+    return {
+      version: 4,
+      detailedVersion: '4.x',
+      manifestPath: v4Manifest,
+      configPath: path.join(targetDir, '.bmad-core/config.yaml'),
+      bmadPath: path.join(targetDir, '.bmad-core'),
+      installed: true
+    };
+  } catch {}
+
+  // Not installed
+  return { version: null, installed: false };
+}
+
+/**
+ * Get BMAD configuration file path for detected version
+ * @param {Object} detection - Result from detectBMAD()
+ * @returns {string|null} Path to config.yaml or null
+ */
+export function getBMADConfigPath(detection) {
+  return detection.installed ? detection.configPath : null;
+}