agentvibes 2.0.17 → 2.0.18

package/.claude/activation-instructions

@@ -0,0 +1,54 @@
+# BMAD Agent Activation Instructions
+
+When a BMAD agent activates, follow these steps EXACTLY:
+
+## STEP 3.5a: Create BMAD Context File (CRITICAL)
+
+**IMMEDIATELY after agent identification, create the context file:**
+
+```bash
+echo "$AGENT_ID" > .bmad-agent-context
+```
+
+Where `$AGENT_ID` is one of:
+- `pm` (Product Manager)
+- `dev` (Developer)
+- `qa` (QA)
+- `architect` (Architect)
+- `po` (Product Owner)
+- `analyst` (Analyst)
+- `sm` (Scrum Master)
+- `ux-expert` (UX Expert)
+- `bmad-master` (BMAD Master)
+- `bmad-orchestrator` (Orchestrator)
+
+**Example:**
+```bash
+# For Product Manager agent
+echo "pm" > .bmad-agent-context
+```
+
+This file allows AgentVibes to:
+1. Detect which BMAD agent is active
+2. Look up the correct voice mapping
+3. Automatically speak questions using the agent's assigned voice
+
+## STEP 10: Clean Up on Exit
+
+**Before exiting the agent, remove the context file:**
+
+```bash
+rm -f .bmad-agent-context
+```
+
+This ensures voice switching only happens when an agent is active.
+
+## Why This Matters
+
+Without the `.bmad-agent-context` file:
+- AgentVibes cannot detect which agent is active
+- Questions won't be spoken automatically
+- Voice switching won't work
+- The BMAD voice plugin becomes non-functional
+
+**This is MANDATORY for BMAD voice integration to work!**

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

@@ -1 +1 @@
-20251016
+20251017

package/.claude/hooks/bmad-tts-injector.sh

@@ -1,9 +1,38 @@
 #!/bin/bash
 #
-# @fileoverview BMAD TTS Injection Manager
-# @context Automatically patches BMAD agent files to include AgentVibes TTS hooks
-# @architecture Modifies agent YAML activation-instructions to call play-tts.sh
-# @why Enables BMAD agents to speak their greetings and questions via TTS
+# File: .claude/hooks/bmad-tts-injector.sh
+#
+# AgentVibes - Finally, your AI Agents can Talk Back! Text-to-Speech WITH personality for AI Assistants!
+# Website: https://agentvibes.org
+# Repository: https://github.com/paulpreibisch/AgentVibes
+#
+# Co-created by Paul Preibisch with Claude AI
+# Copyright (c) 2025 Paul Preibisch
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+# DISCLAIMER: This software is provided "AS IS", WITHOUT WARRANTY OF ANY KIND,
+# express or implied. Use at your own risk. See the Apache License for details.
+#
+# ---
+#
+# @fileoverview BMAD TTS Injection Manager - Patches BMAD agents for TTS integration
+# @context Automatically modifies BMAD agent YAML files to include AgentVibes TTS capabilities
+# @architecture Injects TTS hooks into activation-instructions and core_principles sections
+# @dependencies bmad-core/agents/*.md files, play-tts.sh, bmad-voice-manager.sh
+# @entrypoints Called via bmad-tts-injector.sh {enable|disable|status|restore}
+# @patterns File patching with backup, provider-aware voice mapping, injection markers for idempotency
+# @related play-tts.sh, bmad-voice-manager.sh, .bmad-core/agents/*.md
 #
 
 set -e  # Exit on error

package/.claude/hooks/bmad-voice-manager.sh

@@ -1,10 +1,62 @@
 #!/bin/bash
+#
+# File: .claude/hooks/bmad-voice-manager.sh
+#
+# AgentVibes - Finally, your AI Agents can Talk Back! Text-to-Speech WITH personality for AI Assistants!
+# Website: https://agentvibes.org
+# Repository: https://github.com/paulpreibisch/AgentVibes
+#
+# Co-created by Paul Preibisch with Claude AI
+# Copyright (c) 2025 Paul Preibisch
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+# DISCLAIMER: This software is provided "AS IS", WITHOUT WARRANTY OF ANY KIND,
+# express or implied, including but not limited to the warranties of
+# merchantability, fitness for a particular purpose and noninfringement.
+# In no event shall the authors or copyright holders be liable for any claim,
+# damages or other liability, whether in an action of contract, tort or
+# otherwise, arising from, out of or in connection with the software or the
+# use or other dealings in the software.
+#
+# ---
+#
+# @fileoverview BMAD Voice Plugin Manager - Maps BMAD agents to unique TTS voices
+# @context Enables each BMAD agent to have its own distinct voice for multi-agent sessions
+# @architecture Markdown table-based voice mapping with enable/disable flag, auto-detection of BMAD
+# @dependencies .claude/plugins/bmad-voices.md (voice mappings), bmad-tts-injector.sh, .bmad-core/ (BMAD installation)
+# @entrypoints Called by /agent-vibes:bmad commands, auto-enabled on BMAD detection
+# @patterns Plugin architecture, auto-enable on dependency detection, state backup/restore on toggle
+# @related bmad-tts-injector.sh, .claude/plugins/bmad-voices.md, .bmad-agent-context file
 
 PLUGIN_DIR=".claude/plugins"
 PLUGIN_FILE="$PLUGIN_DIR/bmad-voices.md"
 ENABLED_FLAG="$PLUGIN_DIR/bmad-voices-enabled.flag"
 
-# Auto-enable plugin if BMAD is detected
+# AI NOTE: Auto-enable pattern - When BMAD is detected via .bmad-core/install-manifest.yaml,
+# automatically enable the voice plugin to provide seamless multi-agent voice support.
+# This avoids requiring manual plugin activation after BMAD installation.
+
+# @function auto_enable_if_bmad_detected
+# @intent Automatically enable BMAD voice plugin when BMAD framework is detected
+# @why Provide seamless integration - users shouldn't need to manually enable voice mapping
+# @param None
+# @returns None
+# @exitcode 0=auto-enabled, 1=not enabled (already enabled or BMAD not detected)
+# @sideeffects Creates enabled flag file, creates plugin directory
+# @edgecases Only auto-enables if plugin not already enabled, silent operation
+# @calledby get_agent_voice
+# @calls mkdir, touch
 auto_enable_if_bmad_detected() {
     # Check if BMAD is installed
     if [[ -f ".bmad-core/install-manifest.yaml" ]] && [[ ! -f "$ENABLED_FLAG" ]]; then
@@ -16,7 +68,16 @@ auto_enable_if_bmad_detected() {
     return 1
 }
 
-# Parse markdown table to get voice mapping
+# @function get_agent_voice
+# @intent Retrieve TTS voice assigned to specific BMAD agent
+# @why Each BMAD agent needs unique voice for multi-agent conversation differentiation
+# @param $1 {string} agent_id - BMAD agent identifier (pm, dev, qa, architect, etc.)
+# @returns Echoes voice name to stdout, empty string if plugin disabled or agent not found
+# @exitcode Always 0
+# @sideeffects May auto-enable plugin if BMAD detected
+# @edgecases Returns empty string if plugin disabled/missing, parses markdown table syntax
+# @calledby bmad-tts-injector.sh, play-tts.sh when BMAD agent is active
+# @calls auto_enable_if_bmad_detected, grep, awk, sed
 get_agent_voice() {
     local agent_id="$1"
 
@@ -41,7 +102,16 @@ get_agent_voice() {
     echo "$voice"
 }
 
-# Get personality for agent
+# @function get_agent_personality
+# @intent Retrieve TTS personality assigned to specific BMAD agent
+# @why Agents may have distinct speaking styles (friendly, professional, energetic, etc.)
+# @param $1 {string} agent_id - BMAD agent identifier
+# @returns Echoes personality name to stdout, empty string if not found
+# @exitcode Always 0
+# @sideeffects None
+# @edgecases Returns empty string if plugin file missing, parses column 5 of markdown table
+# @calledby bmad-tts-injector.sh for personality-aware voice synthesis
+# @calls grep, awk, sed
 get_agent_personality() {
     local agent_id="$1"
 
@@ -57,12 +127,31 @@ get_agent_personality() {
     echo "$personality"
 }
 
-# Check if plugin is enabled
+# @function is_plugin_enabled
+# @intent Check if BMAD voice plugin is currently enabled
+# @why Allow conditional logic based on plugin state
+# @param None
+# @returns Echoes "true" or "false" to stdout
+# @exitcode Always 0
+# @sideeffects None
+# @edgecases None
+# @calledby show_status, enable_plugin, disable_plugin
+# @calls None (file existence check)
 is_plugin_enabled() {
     [[ -f "$ENABLED_FLAG" ]] && echo "true" || echo "false"
 }
 
-# Enable plugin
+# @function enable_plugin
+# @intent Enable BMAD voice plugin and backup current voice settings
+# @why Allow users to switch to per-agent voices while preserving original configuration
+# @param None
+# @returns None
+# @exitcode Always 0
+# @sideeffects Creates flag file, backs up current voice/personality/sentiment to .bmad-previous-settings
+# @sideeffects Creates activation-instructions file for BMAD agents, calls bmad-tts-injector.sh
+# @edgecases Handles missing settings files gracefully with defaults
+# @calledby Main command dispatcher with "enable" argument
+# @calls mkdir, cat, source, list_mappings, bmad-tts-injector.sh
 enable_plugin() {
     mkdir -p "$PLUGIN_DIR"
 
@@ -193,7 +282,16 @@ ACTIVATION_EOF
     fi
 }
 
-# Disable plugin
+# @function disable_plugin
+# @intent Disable BMAD voice plugin and restore previous voice settings
+# @why Allow users to return to single-voice mode with their original configuration
+# @param None
+# @returns None
+# @exitcode Always 0
+# @sideeffects Removes flag file, restores settings from backup, calls bmad-tts-injector.sh disable
+# @edgecases Handles missing backup file gracefully, warns user if no backup exists
+# @calledby Main command dispatcher with "disable" argument
+# @calls source, rm, echo, bmad-tts-injector.sh
 disable_plugin() {
     BACKUP_FILE="$PLUGIN_DIR/.bmad-previous-settings"
 
@@ -250,7 +348,16 @@ disable_plugin() {
     fi
 }
 
-# List all mappings
+# @function list_mappings
+# @intent Display all BMAD agent-to-voice mappings in readable format
+# @why Help users see which voice is assigned to each agent
+# @param None
+# @returns None
+# @exitcode 0=success, 1=plugin file not found
+# @sideeffects Writes formatted output to stdout
+# @edgecases Parses markdown table format, skips header and separator rows
+# @calledby enable_plugin, show_status, main command dispatcher with "list"
+# @calls grep, sed, echo
 list_mappings() {
     if [[ ! -f "$PLUGIN_FILE" ]]; then
         echo "❌ Plugin file not found: $PLUGIN_FILE"
@@ -271,7 +378,18 @@ list_mappings() {
     done
 }
 
-# Set voice for agent
+# @function set_agent_voice
+# @intent Update voice and personality mapping for specific BMAD agent
+# @why Allow customization of agent voices to user preferences
+# @param $1 {string} agent_id - BMAD agent identifier
+# @param $2 {string} voice - New voice name
+# @param $3 {string} personality - New personality (optional, defaults to "normal")
+# @returns None
+# @exitcode 0=success, 1=plugin file not found or agent not found
+# @sideeffects Modifies plugin file, creates .bak backup
+# @edgecases Validates agent exists before updating
+# @calledby Main command dispatcher with "set" argument
+# @calls grep, sed
 set_agent_voice() {
     local agent_id="$1"
     local voice="$2"
@@ -294,7 +412,16 @@ set_agent_voice() {
     echo "✅ Updated $agent_id → $voice [$personality]"
 }
 
-# Show status
+# @function show_status
+# @intent Display plugin status, BMAD detection, and current voice mappings
+# @why Provide comprehensive overview of plugin state for troubleshooting
+# @param None
+# @returns None
+# @exitcode Always 0
+# @sideeffects Writes status information to stdout
+# @edgecases Checks for BMAD installation via manifest file
+# @calledby Main command dispatcher with "status" argument
+# @calls is_plugin_enabled, list_mappings
 show_status() {
     # Check for BMAD installation
     local bmad_installed="false"
@@ -317,7 +444,16 @@ show_status() {
     list_mappings
 }
 
-# Edit plugin file
+# @function edit_plugin
+# @intent Open plugin configuration file for manual editing
+# @why Allow advanced users to modify voice mappings directly
+# @param None
+# @returns None
+# @exitcode 0=success, 1=plugin file not found
+# @sideeffects Displays file path and instructions
+# @edgecases Does not actually open editor, just provides guidance
+# @calledby Main command dispatcher with "edit" argument
+# @calls echo
 edit_plugin() {
     if [[ ! -f "$PLUGIN_FILE" ]]; then
         echo "❌ Plugin file not found: $PLUGIN_FILE"

package/.claude/hooks/check-output-style.sh

@@ -1,15 +1,58 @@
 #!/bin/bash
 #
-# @fileoverview Output Style Detection for AgentVibes
-# @context Detects if agent-vibes output style is active
-# @architecture Helper for slash commands to warn users
-# @why Voice commands won't work without agent-vibes output style
+# File: .claude/hooks/check-output-style.sh
 #
+# AgentVibes - Finally, your AI Agents can Talk Back! Text-to-Speech WITH personality for AI Assistants!
+# Website: https://agentvibes.org
+# Repository: https://github.com/paulpreibisch/AgentVibes
+#
+# Co-created by Paul Preibisch with Claude AI
+# Copyright (c) 2025 Paul Preibisch
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+# DISCLAIMER: This software is provided "AS IS", WITHOUT WARRANTY OF ANY KIND,
+# express or implied, including but not limited to the warranties of
+# merchantability, fitness for a particular purpose and noninfringement.
+# In no event shall the authors or copyright holders be liable for any claim,
+# damages or other liability, whether in an action of contract, tort or
+# otherwise, arising from, out of or in connection with the software or the
+# use or other dealings in the software.
+#
+# ---
+#
+# @fileoverview Output Style Detection - Detects if Agent Vibes output style is active in Claude Code
+# @context Voice commands require the Agent Vibes output style to work properly with automatic TTS
+# @architecture Heuristic detection using environment variables and file system checks
+# @dependencies CLAUDECODE environment variable, .claude/output-styles/agent-vibes.md file
+# @entrypoints Called by slash commands to warn users if output style is incorrect
+# @patterns Environment-based detection, graceful degradation with helpful error messages
+# @related .claude/output-styles/agent-vibes.md, Claude Code output style system
 
-# Check if we're in a Claude Code session with agent-vibes output style
-# This is a heuristic check - we can't directly detect the output style,
-# but we can check if TTS commands would work
+# AI NOTE: Output style detection is heuristic-based because Claude Code does not expose
+# the active output style via environment variables. We check for CLAUDECODE env var and
+# the presence of the agent-vibes.md output style file as indicators.
 
+# @function check_output_style
+# @intent Detect if Agent Vibes output style is likely active in Claude Code session
+# @why Voice commands depend on output style hooks that automatically invoke TTS
+# @param None
+# @returns None
+# @exitcode 0=likely using agent-vibes style, 1=not using or cannot detect
+# @sideeffects None (read-only checks)
+# @edgecases Cannot directly detect output style, relies on CLAUDECODE env var and file presence
+# @calledby Main execution block, slash command validation
+# @calls None (direct environment and file checks)
 check_output_style() {
   # Strategy: Check if this script is being called from within a Claude response
   # If CLAUDECODE env var is set, we're in Claude Code
@@ -36,7 +79,16 @@ check_output_style() {
   return 0
 }
 
-# Show warning if output style is not agent-vibes
+# @function show_output_style_warning
+# @intent Display helpful warning about enabling Agent Vibes output style
+# @why Users need guidance on how to enable automatic TTS narration
+# @param None
+# @returns None
+# @exitcode Always 0
+# @sideeffects Writes warning message to stdout
+# @edgecases None
+# @calledby Main execution block when check_output_style fails
+# @calls echo
 show_output_style_warning() {
   echo ""
   echo "⚠️  Voice commands require the Agent Vibes output style"

package/.claude/hooks/github-star-reminder.sh

@@ -1,10 +1,43 @@
 #!/bin/bash
 #
-# @fileoverview GitHub Star Reminder System
-# @context Shows a gentle reminder once per day to star the repo
-# @architecture Tracks last reminder date in a timestamp file
-# @why Encourage users to support the project without being annoying
+# File: .claude/hooks/github-star-reminder.sh
 #
+# AgentVibes - Finally, your AI Agents can Talk Back! Text-to-Speech WITH personality for AI Assistants!
+# Website: https://agentvibes.org
+# Repository: https://github.com/paulpreibisch/AgentVibes
+#
+# Co-created by Paul Preibisch with Claude AI
+# Copyright (c) 2025 Paul Preibisch
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+# DISCLAIMER: This software is provided "AS IS", WITHOUT WARRANTY OF ANY KIND,
+# express or implied, including but not limited to the warranties of
+# merchantability, fitness for a particular purpose and noninfringement.
+# In no event shall the authors or copyright holders be liable for any claim,
+# damages or other liability, whether in an action of contract, tort or
+# otherwise, arising from, out of or in connection with the software or the
+# use or other dealings in the software.
+#
+# ---
+#
+# @fileoverview GitHub Star Reminder System - Gentle daily reminder to star repository
+# @context Shows a once-per-day reminder to encourage users to support the project without being annoying
+# @architecture Timestamp-based tracking using daily date comparison in a state file
+# @dependencies date command for timestamp generation
+# @entrypoints Called by play-tts.sh router on every TTS execution, sourced or executed directly
+# @patterns Rate-limiting via file-based state, graceful degradation, user-opt-out support
+# @related .claude/github-star-reminder.txt (state file), .claude/github-star-reminder-disabled.flag (opt-out)
 
 # Determine config directory (project-local or global)
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
@@ -20,7 +53,16 @@ fi
 
 GITHUB_REPO="https://github.com/paulpreibisch/AgentVibes"
 
-# Check if reminders are disabled
+# @function is_reminder_disabled
+# @intent Check if GitHub star reminders have been disabled by the user
+# @why Respect user preferences and provide opt-out mechanism for reminders
+# @param None
+# @returns None
+# @exitcode 0=reminders disabled, 1=reminders enabled
+# @sideeffects Reads flag files from local/global .claude directories
+# @edgecases Checks both flag file and "disabled" text in reminder file for backward compatibility
+# @calledby should_show_reminder
+# @calls cat for reading reminder file content
 is_reminder_disabled() {
   # Check for disable flag file
   local disable_file_local="$CLAUDE_DIR/github-star-reminder-disabled.flag"
@@ -41,7 +83,16 @@ is_reminder_disabled() {
   return 1  # Not disabled
 }
 
-# Check if we should show the reminder
+# @function should_show_reminder
+# @intent Determine if reminder should be displayed based on date and disable status
+# @why Implement once-per-day rate limiting to avoid annoying users
+# @param None
+# @returns None
+# @exitcode 0=should show, 1=should not show
+# @sideeffects Reads .claude/github-star-reminder.txt for last reminder date
+# @edgecases Shows reminder if file doesn't exist (first run), compares YYYYMMDD format dates
+# @calledby Main execution block
+# @calls is_reminder_disabled, cat, date
 should_show_reminder() {
   # Check if disabled first
   if is_reminder_disabled; then
@@ -65,7 +116,16 @@ should_show_reminder() {
   return 1
 }
 
-# Show the reminder
+# @function show_reminder
+# @intent Display friendly GitHub star reminder with opt-out instructions
+# @why Encourage community support while being respectful and non-intrusive
+# @param None
+# @returns None
+# @exitcode Always 0
+# @sideeffects Updates reminder file with current date, writes to stdout
+# @edgecases None
+# @calledby Main execution block when should_show_reminder returns true
+# @calls date, echo
 show_reminder() {
   echo ""
   echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"

package/.claude/hooks/language-manager.sh

@@ -1,6 +1,38 @@
 #!/bin/bash
-# Language Manager for AgentVibes
-# Manages language settings and multilingual voice selection
+#
+# File: .claude/hooks/language-manager.sh
+#
+# AgentVibes - Finally, your AI Agents can Talk Back! Text-to-Speech WITH personality for AI Assistants!
+# Website: https://agentvibes.org
+# Repository: https://github.com/paulpreibisch/AgentVibes
+#
+# Co-created by Paul Preibisch with Claude AI
+# Copyright (c) 2025 Paul Preibisch
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+# DISCLAIMER: This software is provided "AS IS", WITHOUT WARRANTY OF ANY KIND,
+# express or implied. Use at your own risk. See the Apache License for details.
+#
+# ---
+#
+# @fileoverview Language Manager - Manages multilingual TTS with 30+ language support
+# @context Enables TTS in multiple languages with provider-specific voice recommendations (ElevenLabs multilingual vs Piper native)
+# @architecture Dual-map system: ELEVENLABS_VOICES and PIPER_VOICES for provider-aware voice selection
+# @dependencies provider-manager.sh for active provider detection, .claude/tts-language.txt for state
+# @entrypoints Called by /agent-vibes:language commands, play-tts-*.sh for voice resolution
+# @patterns Provider abstraction, language-to-voice mapping, backward compatibility with legacy LANGUAGE_VOICES
+# @related play-tts-elevenlabs.sh, play-tts-piper.sh, provider-manager.sh, learn-manager.sh
 
 # Determine target .claude directory based on context
 # Priority:

package/.claude/hooks/learn-manager.sh

@@ -1,6 +1,38 @@
 #!/bin/bash
-# Language Learning Mode Manager for AgentVibes
-# Handles dual-language TTS for language learning
+#
+# File: .claude/hooks/learn-manager.sh
+#
+# AgentVibes - Finally, your AI Agents can Talk Back! Text-to-Speech WITH personality for AI Assistants!
+# Website: https://agentvibes.org
+# Repository: https://github.com/paulpreibisch/AgentVibes
+#
+# Co-created by Paul Preibisch with Claude AI
+# Copyright (c) 2025 Paul Preibisch
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+# DISCLAIMER: This software is provided "AS IS", WITHOUT WARRANTY OF ANY KIND,
+# express or implied. Use at your own risk. See the Apache License for details.
+#
+# ---
+#
+# @fileoverview Language Learning Mode Manager - Enables dual-language TTS for immersive learning
+# @context Speaks responses in both main language (English) and target language (Spanish, French, etc.) for language practice
+# @architecture Manages main/target language pairs with voice mappings, auto-configures recommended voices per language
+# @dependencies play-tts.sh (dual invocation), language-manager.sh (voice recommendations), .claude/tts-*.txt state files
+# @entrypoints Called by /agent-vibes:learn commands to enable/disable learning mode
+# @patterns Dual-voice orchestration, auto-configuration, greeting on activation, provider-aware voice selection
+# @related language-manager.sh, play-tts.sh, .claude/tts-learn-mode.txt, .claude/tts-target-language.txt
 
 set -e
 

package/.claude/hooks/personality-manager.sh

@@ -1,5 +1,38 @@
 #!/bin/bash
-# Personality manager for AgentVibes - adds character to TTS messages
+#
+# File: .claude/hooks/personality-manager.sh
+#
+# AgentVibes - Finally, your AI Agents can Talk Back! Text-to-Speech WITH personality for AI Assistants!
+# Website: https://agentvibes.org
+# Repository: https://github.com/paulpreibisch/AgentVibes
+#
+# Co-created by Paul Preibisch with Claude AI
+# Copyright (c) 2025 Paul Preibisch
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+# DISCLAIMER: This software is provided "AS IS", WITHOUT WARRANTY OF ANY KIND,
+# express or implied. Use at your own risk. See the Apache License for details.
+#
+# ---
+#
+# @fileoverview Personality Manager - Adds character and emotional style to TTS voices
+# @context Enables voices to have distinct personalities (flirty, sarcastic, pirate, etc.) with provider-aware voice assignment
+# @architecture Markdown-based personality templates with provider-specific voice mappings (ElevenLabs vs Piper)
+# @dependencies .claude/personalities/*.md files, voice-manager.sh, play-tts.sh, provider-manager.sh
+# @entrypoints Called by /agent-vibes:personality slash commands
+# @patterns Template-based configuration, provider abstraction, random personality support
+# @related .claude/personalities/*.md, voice-manager.sh, .claude/tts-personality.txt
 
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 PERSONALITIES_DIR="$SCRIPT_DIR/../personalities"