qualia-framework 2.1.0

package/framework/scripts/cowork-mode.sh

@@ -0,0 +1,141 @@
+#!/bin/bash
+# Toggle between full Claude Code config and lean Cowork config
+# Usage: cowork-mode.sh on|off|status
+
+set -e
+
+CLAUDE_DIR="$HOME/.claude"
+CONFIG="$CLAUDE_DIR/settings.json"
+SKILLS_DIR="$CLAUDE_DIR/skills"
+ARCHIVE_DIR="$CLAUDE_DIR/skills-archive"
+BACKUP="$CLAUDE_DIR/.settings-full.json"
+LOCK="$CLAUDE_DIR/.cowork-mode"
+
+# Skills to archive in Cowork (heavy/project-specific)
+HEAVY_SKILLS=(
+    sakani-conventions
+    nestjs-backend
+    mobile-expo
+    financial-ledger
+    i18n-rtl
+    fcm-notifications
+    subscription-payments
+    voice-agent
+    zoho-workflow
+    skill-creator
+    deep-research
+    test-runner
+    git-worktree
+)
+
+# Plugins to disable in Cowork (keep: typescript-lsp, firecrawl, playwright)
+DISABLE_PLUGINS=(
+    "code-review@claude-plugins-official"
+    "skill-creator@claude-plugins-official"
+    "claude-md-management@claude-plugins-official"
+    "code-simplifier@claude-plugins-official"
+    "cowork-plugin-management@knowledge-work-plugins"
+    "supabase@claude-plugins-official"
+)
+
+# MCP servers to disable in Cowork (keep: supabase, firecrawl)
+DISABLE_MCP=(
+    "zohomcp"
+    "sentry"
+)
+
+on() {
+    if [ -f "$LOCK" ]; then
+        echo "Already in Cowork mode. Run 'cowork-mode.sh off' first."
+        exit 1
+    fi
+
+    echo "Switching to Cowork mode (lean config)..."
+
+    # Backup full settings
+    cp "$CONFIG" "$BACKUP"
+
+    # Archive heavy skills
+    mkdir -p "$ARCHIVE_DIR"
+    local count=0
+    for skill in "${HEAVY_SKILLS[@]}"; do
+        if [ -d "$SKILLS_DIR/$skill" ]; then
+            mv "$SKILLS_DIR/$skill" "$ARCHIVE_DIR/$skill"
+            count=$((count + 1))
+        fi
+    done
+
+    # Disable plugins and MCP servers
+    node -e "
+const fs = require('fs');
+const config = JSON.parse(fs.readFileSync(process.argv[1], 'utf8'));
+
+// Disable plugins
+const disablePlugins = process.argv.slice(3);
+for (const p of disablePlugins) {
+    if (config.enabledPlugins && config.enabledPlugins[p] !== undefined) {
+        config.enabledPlugins[p] = false;
+    }
+}
+
+// Filter MCP servers
+const disableMcp = process.argv[2].split(',').filter(Boolean);
+if (config.enabledMcpjsonServers) {
+    config.enabledMcpjsonServers = config.enabledMcpjsonServers.filter(s => !disableMcp.includes(s));
+}
+
+fs.writeFileSync(process.argv[1], JSON.stringify(config, null, 2));
+" "$CONFIG" "$(IFS=,; echo "${DISABLE_MCP[*]}")" "${DISABLE_PLUGINS[@]}"
+
+    # Mark as active
+    date > "$LOCK"
+
+    echo "Done. Archived $count skills, disabled ${#DISABLE_PLUGINS[@]} plugins, ${#DISABLE_MCP[@]} MCP servers."
+    echo ""
+    echo "Now restart Claude desktop app to pick up changes."
+    echo "Run 'cowork off' when done to restore full config."
+}
+
+off() {
+    if [ ! -f "$LOCK" ]; then
+        echo "Not in Cowork mode. Nothing to restore."
+        exit 1
+    fi
+
+    echo "Restoring full Claude Code config..."
+
+    # Restore skills from archive
+    if [ -d "$ARCHIVE_DIR" ]; then
+        for skill in "$ARCHIVE_DIR"/*/; do
+            [ -d "$skill" ] || continue
+            name=$(basename "$skill")
+            mv "$skill" "$SKILLS_DIR/$name"
+        done
+        rmdir "$ARCHIVE_DIR" 2>/dev/null || true
+    fi
+
+    # Restore full settings
+    if [ -f "$BACKUP" ]; then
+        mv "$BACKUP" "$CONFIG"
+    fi
+
+    rm "$LOCK"
+    echo "Done. Full config restored."
+    echo "Restart Claude desktop app to pick up changes."
+}
+
+status() {
+    if [ -f "$LOCK" ]; then
+        echo "Cowork mode: ON (since $(cat "$LOCK"))"
+        [ -d "$ARCHIVE_DIR" ] && echo "Archived skills: $(ls "$ARCHIVE_DIR" 2>/dev/null | wc -l)"
+    else
+        echo "Cowork mode: OFF (full config active)"
+    fi
+}
+
+case "${1:-status}" in
+    on)  on ;;
+    off) off ;;
+    status) status ;;
+    *)   echo "Usage: cowork-mode.sh [on|off|status]" ;;
+esac

package/framework/scripts/generate-project-claude-md.sh

@@ -0,0 +1,153 @@
+#!/bin/bash
+# Generate CLAUDE.md for all Qualia projects that don't have one
+# Run from your main dev machine: bash ~/.claude/scripts/generate-project-claude-md.sh
+
+set -euo pipefail
+shopt -s nullglob
+
+PROJECTS_BASE="$HOME/Projects"
+# Note: Projects confirmed at ~/Projects/ (not ~/Desktop/Projects/)
+DEPLOYMENT_MAP="$HOME/.claude/knowledge/deployment-map.md"
+CLIENT_PREFS="$HOME/.claude/knowledge/client-prefs.md"
+
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+CYAN='\033[0;36m'
+NC='\033[0m'
+
+GENERATED=0
+SKIPPED=0
+
+# Supabase refs from deployment-map.md
+declare -A SUPABASE_REFS=(
+  ["aibossbrainz"]="esymbjpzjjkffpfqukxw"
+  ["aquador"]="hznpuxplqgszbacxzbhv"
+  ["dababneh"]="toovladeybmlyzblqtbl"
+  ["faris"]="lrgwxcqqnhxvvrruepcv"
+  ["Hammah"]="ctcikdcjhxxqogwvtzrc"
+  ["maud"]="vspyxscitcuwnrhchskl"
+  ["mpm"]="llherorsfgbdyqkrrlpc"
+  ["sofiatesting"]="vceeheaxcrhmpqueudqx"
+  ["timo"]="qgaqvkmqterlljbegniu"
+  ["under"]="vvppyijxpgeeijiozlve"
+  ["vero"]="zskfdlqyzhkzefafqkpx"
+  ["Zaid"]="uoqiwidqlsoamtugioik"
+)
+
+generate_claude_md() {
+  local dir="$1"
+  local name=$(basename "$dir")
+  local category="$2"
+
+  # Skip if CLAUDE.md already exists
+  if [ -f "$dir/CLAUDE.md" ]; then
+    printf "${YELLOW}SKIP${NC} %s (already has CLAUDE.md)\n" "$name"
+    SKIPPED=$((SKIPPED + 1))
+    return
+  fi
+
+  # Skip if not a real project (no package.json and no src/)
+  if [ ! -f "$dir/package.json" ] && [ ! -d "$dir/src" ] && [ ! -f "$dir/requirements.txt" ]; then
+    return
+  fi
+
+  # Detect stack from package.json
+  local stack=""
+  local scripts=""
+  local nextjs_version=""
+  if [ -f "$dir/package.json" ]; then
+    nextjs_version=$(node -e "try{const p=require('$dir/package.json');console.log(p.dependencies?.next||p.devDependencies?.next||'')}catch(e){}" 2>/dev/null)
+    local has_supabase=$(node -e "try{const p=require('$dir/package.json');console.log(p.dependencies?.['@supabase/supabase-js']?'yes':'')}catch(e){}" 2>/dev/null)
+    local has_tailwind=$(node -e "try{const p=require('$dir/package.json');console.log(p.devDependencies?.tailwindcss||p.dependencies?.tailwindcss?'yes':'')}catch(e){}" 2>/dev/null)
+
+    stack="Next.js${nextjs_version:+ $nextjs_version}, React, TypeScript"
+    [ "$has_supabase" = "yes" ] && stack="$stack, Supabase"
+    [ "$has_tailwind" = "yes" ] && stack="$stack, Tailwind"
+
+    # Get npm scripts
+    scripts=$(node -e "try{const p=require('$dir/package.json');const s=p.scripts||{};Object.keys(s).forEach(k=>console.log('- \`npm run '+k+'\` — '+s[k]))}catch(e){}" 2>/dev/null)
+  fi
+
+  # Python project detection
+  if [ -f "$dir/requirements.txt" ]; then
+    stack="Python"
+    [ -f "$dir/pyproject.toml" ] && stack="$stack (pyproject)"
+  fi
+
+  # Supabase ref
+  local supa_ref="${SUPABASE_REFS[$name]:-}"
+  local supa_line=""
+  [ -n "$supa_ref" ] && supa_line="- **Supabase:** \`$supa_ref\`"
+
+  # Detect deploy target
+  local deploy_target="Vercel"
+  [ -f "$dir/wrangler.toml" ] || [ -f "$dir/wrangler.jsonc" ] && deploy_target="Cloudflare Workers"
+
+  # Detect domain from vercel.json
+  local domain=""
+  if [ -f "$dir/vercel.json" ]; then
+    domain=$(node -e "try{const v=require('$dir/vercel.json');console.log((v.alias||[])[0]||'')}catch(e){}" 2>/dev/null)
+  fi
+  [ -z "$domain" ] && domain="$name.vercel.app"
+
+  # Build the CLAUDE.md
+  cat > "$dir/CLAUDE.md" << CLAUDEMD
+# $name
+
+## Purpose
+$category project. <!-- UPDATE: Add one-line description -->
+
+## Stack
+$stack
+
+## Config
+- **Deploy:** $deploy_target at $domain
+${supa_line}
+
+## Commands
+${scripts:-"- \`npm run dev\` — local development
+- \`npm run build\` — production build"}
+
+## Notes
+<!-- Add project-specific gotchas, client preferences, known issues -->
+CLAUDEMD
+
+  printf "${GREEN}CREATED${NC} %s/CLAUDE.md\n" "$name"
+  GENERATED=$((GENERATED + 1))
+}
+
+echo ""
+printf "${CYAN}Scanning projects...${NC}\n"
+echo ""
+
+# Live Projects
+if [ -d "$PROJECTS_BASE/Live-Projects" ]; then
+  for dir in "$PROJECTS_BASE/Live-Projects"/*/; do
+    [ -d "$dir" ] && generate_claude_md "$dir" "Client website"
+  done
+fi
+
+# AI Agents
+if [ -d "$PROJECTS_BASE/aiagents" ]; then
+  for dir in "$PROJECTS_BASE/aiagents"/*/; do
+    [ -d "$dir" ] && generate_claude_md "$dir" "AI agent"
+  done
+fi
+
+# Voice
+if [ -d "$PROJECTS_BASE/voice" ]; then
+  for dir in "$PROJECTS_BASE/voice"/*/; do
+    [ -d "$dir" ] && generate_claude_md "$dir" "Voice agent"
+  done
+fi
+
+# Websites
+if [ -d "$PROJECTS_BASE/websites" ]; then
+  for dir in "$PROJECTS_BASE/websites"/*/; do
+    [ -d "$dir" ] && generate_claude_md "$dir" "Internal tool"
+  done
+fi
+
+echo ""
+printf "${CYAN}Done.${NC} Generated: ${GREEN}$GENERATED${NC} | Skipped: ${YELLOW}$SKIPPED${NC}\n"
+printf "Review the generated files and fill in the <!-- UPDATE --> placeholders.\n"

package/framework/scripts/load-test-webhook.js

@@ -0,0 +1,172 @@
+#!/usr/bin/env node
+/**
+ * Simple load testing for webhook endpoints
+ * Usage: node load-test-webhook.js <webhook-url> [concurrency=10] [total=100]
+ */
+
+const https = require('https');
+const http = require('http');
+
+async function loadTest(webhookUrl, concurrency = 10, totalRequests = 100) {
+  console.log(`🔥 Load testing ${webhookUrl}`);
+  console.log(`📊 Concurrency: ${concurrency}, Total: ${totalRequests}\n`);
+
+  const results = {
+    success: 0,
+    failed: 0,
+    times: [],
+    errors: []
+  };
+
+  const batches = Math.ceil(totalRequests / concurrency);
+
+  for (let batch = 0; batch < batches; batch++) {
+    const batchSize = Math.min(concurrency, totalRequests - batch * concurrency);
+    const promises = [];
+
+    console.log(`🚀 Batch ${batch + 1}/${batches} (${batchSize} requests)`);
+
+    for (let i = 0; i < batchSize; i++) {
+      promises.push(makeRequest(webhookUrl, batch * concurrency + i + 1));
+    }
+
+    const batchResults = await Promise.allSettled(promises);
+
+    for (const result of batchResults) {
+      if (result.status === 'fulfilled') {
+        results.success++;
+        results.times.push(result.value.duration);
+      } else {
+        results.failed++;
+        results.errors.push(result.reason.message);
+      }
+    }
+
+    // Brief pause between batches
+    if (batch < batches - 1) {
+      await sleep(100);
+    }
+  }
+
+  printResults(results, totalRequests);
+}
+
+function makeRequest(url, requestId) {
+  return new Promise((resolve, reject) => {
+    const startTime = Date.now();
+    const isHttps = url.startsWith('https');
+    const client = isHttps ? https : http;
+
+    // Sample WhatsApp webhook payload
+    const payload = JSON.stringify({
+      object: "whatsapp_business_account",
+      entry: [{
+        id: "123456789",
+        changes: [{
+          field: "messages",
+          value: {
+            messaging_product: "whatsapp",
+            metadata: { display_phone_number: "15551234567" },
+            contacts: [{ profile: { name: "Load Test User" }, wa_id: `loadtest${requestId}` }],
+            messages: [{
+              id: `loadtest_${requestId}_${Date.now()}`,
+              from: `loadtest${requestId}`,
+              timestamp: Math.floor(Date.now() / 1000).toString(),
+              type: "text",
+              text: { body: `Load test message ${requestId}` }
+            }]
+          }
+        }]
+      }]
+    });
+
+    const options = {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'Content-Length': Buffer.byteLength(payload),
+        'User-Agent': 'WhatsApp/2.0 LoadTest'
+      },
+      timeout: 10000
+    };
+
+    const req = client.request(url, options, (res) => {
+      let data = '';
+      res.on('data', chunk => data += chunk);
+      res.on('end', () => {
+        const duration = Date.now() - startTime;
+        if (res.statusCode >= 200 && res.statusCode < 300) {
+          resolve({ duration, statusCode: res.statusCode });
+        } else {
+          reject(new Error(`HTTP ${res.statusCode}: ${data}`));
+        }
+      });
+    });
+
+    req.on('error', (error) => {
+      reject(new Error(`Request failed: ${error.message}`));
+    });
+
+    req.on('timeout', () => {
+      req.destroy();
+      reject(new Error('Request timeout'));
+    });
+
+    req.write(payload);
+    req.end();
+  });
+}
+
+function printResults(results, totalRequests) {
+  console.log('\n📈 RESULTS');
+  console.log('=' .repeat(50));
+
+  const successRate = (results.success / totalRequests * 100).toFixed(1);
+  const avgTime = results.times.length ? (results.times.reduce((a, b) => a + b, 0) / results.times.length).toFixed(0) : 0;
+  const p95Time = results.times.length ? results.times.sort((a, b) => a - b)[Math.floor(results.times.length * 0.95)] : 0;
+
+  console.log(`✅ Success: ${results.success}/${totalRequests} (${successRate}%)`);
+  console.log(`❌ Failed: ${results.failed}/${totalRequests}`);
+  console.log(`⚡ Avg response: ${avgTime}ms`);
+  console.log(`📊 95th percentile: ${p95Time}ms`);
+
+  if (results.errors.length > 0) {
+    console.log('\n🚨 ERRORS');
+    const errorCounts = {};
+    results.errors.forEach(error => {
+      errorCounts[error] = (errorCounts[error] || 0) + 1;
+    });
+    Object.entries(errorCounts).forEach(([error, count]) => {
+      console.log(`   ${count}x ${error}`);
+    });
+  }
+
+  // Production readiness assessment
+  console.log('\n🎯 PRODUCTION READINESS');
+  if (successRate >= 95 && avgTime < 5000) {
+    console.log('✅ READY FOR PRODUCTION');
+  } else {
+    console.log('❌ NOT READY FOR PRODUCTION');
+    if (successRate < 95) console.log(`   - Success rate too low (${successRate}% < 95%)`);
+    if (avgTime >= 5000) console.log(`   - Response too slow (${avgTime}ms ≥ 5000ms)`);
+  }
+}
+
+function sleep(ms) {
+  return new Promise(resolve => setTimeout(resolve, ms));
+}
+
+// CLI execution
+if (require.main === module) {
+  const [webhookUrl, concurrency = 10, total = 100] = process.argv.slice(2);
+
+  if (!webhookUrl) {
+    console.error('Usage: node load-test-webhook.js <webhook-url> [concurrency=10] [total=100]');
+    process.exit(1);
+  }
+
+  loadTest(webhookUrl, parseInt(concurrency), parseInt(total))
+    .catch(console.error);
+}
+
+module.exports = { loadTest };

package/framework/scripts/say.py

@@ -0,0 +1,236 @@
+#!/usr/bin/env python3
+"""
+Smart TTS wrapper with ElevenLabs best practices.
+- Filters code, errors, and system noise
+- Normalizes text for natural speech (numbers, URLs, abbreviations)
+- Only speaks natural conversation
+
+Usage: echo "message" | say.py  OR  say.py "message"
+"""
+
+import sys
+import os
+import re
+import subprocess
+import tempfile
+import warnings
+
+warnings.filterwarnings("ignore")
+
+# ============================================================================
+# CONFIGURATION
+# ============================================================================
+
+VOLUME = 50       # 0-100, set to 0 to mute completely
+MAX_LENGTH = 500  # Max characters to speak
+MIN_LENGTH = 2    # Min characters
+MAX_NEWLINES = 4  # Max newlines allowed
+
+# Patterns that indicate non-conversational content (reject if matched)
+REJECT_PATTERNS = [
+    r'```',                        # Code blocks
+    r'^\s*import\s+',              # Import statements
+    r'^\s*export\s+',              # Export statements
+    r'^\s*const\s+\w+\s*=',        # JS variable declarations
+    r'^\s*let\s+\w+\s*=',          # JS let declarations
+    r'^\s*var\s+\w+\s*=',          # JS var declarations
+    r'^\s*function\s+\w+\s*\(',    # JS function definitions
+    r'^\s*def\s+\w+\s*\(',         # Python functions
+    r'^\s*class\s+\w+',            # Class definitions
+    r'^\s*async\s+',               # Async declarations
+    r'^\s*await\s+',               # Await expressions
+    r'\{\s*\n',                    # Opening braces with newline (code)
+    r'^\s*<[a-zA-Z]',              # HTML/JSX tags
+    r'^\s*\d+[→│\|]\s*',           # Line number prefixes (file reads)
+    r'node_modules',               # Path noise
+    r'\.tsx?:\d+',                 # File:line references (file.ts:123)
+    r'\.jsx?:\d+',                 # File:line references (file.js:123)
+    r'\.py:\d+',                   # Python file:line references
+    r'Error:|error:|ERROR|ERR!',   # Error messages
+    r'Warning:|warning:|WARN',     # Warnings
+    r'^\s*at\s+\w+\s*\(',          # Stack traces
+    r'Traceback \(most recent',    # Python tracebacks
+    r'^\s*\$\s+',                  # Shell prompts
+    r'^\s*>\s+',                   # REPL prompts
+    r'npm\s+(ERR|WARN|notice)',    # npm messages
+    r'^\s*[-*]\s+`',               # Markdown list with code
+    r'^\s*\d+\.\s+`',              # Numbered list with code
+    r'\|\s*\w+\s*\|',              # Markdown tables
+    r'={3,}|_{3,}|-{3,}',          # Markdown separators
+]
+
+# ============================================================================
+# TEXT NORMALIZATION (ElevenLabs best practices)
+# ============================================================================
+
+def normalize_numbers(text: str) -> str:
+    """Convert numbers to speakable format."""
+    # Simple number to words for common cases
+    number_words = {
+        '0': 'zero', '1': 'one', '2': 'two', '3': 'three', '4': 'four',
+        '5': 'five', '6': 'six', '7': 'seven', '8': 'eight', '9': 'nine',
+        '10': 'ten', '11': 'eleven', '12': 'twelve'
+    }
+
+    # Handle percentages: 50% -> fifty percent
+    text = re.sub(r'(\d+)%', lambda m: f"{m.group(1)} percent", text)
+
+    # Handle simple standalone small numbers
+    for num, word in number_words.items():
+        text = re.sub(rf'\b{num}\b', word, text)
+
+    return text
+
+def normalize_urls(text: str) -> str:
+    """Convert URLs to speakable format or remove."""
+    # Remove full URLs - they're not speakable
+    text = re.sub(r'https?://[^\s]+', '', text)
+    # Simplify file paths
+    text = re.sub(r'[~/][\w/.-]+\.(py|sh|js|ts|json|md)', 'the script', text)
+    return text
+
+def expand_abbreviations(text: str) -> str:
+    """Expand common abbreviations for clearer speech."""
+    abbreviations = {
+        r'\bTTS\b': 'text to speech',
+        r'\bAPI\b': 'A P I',
+        r'\bURL\b': 'U R L',
+        r'\bUI\b': 'U I',
+        r'\bAI\b': 'A I',
+        r'\bOK\b': 'okay',
+        r'\bok\b': 'okay',
+        r'\bconfig\b': 'configuration',
+        r'\brepo\b': 'repository',
+        r'\binfo\b': 'information',
+        r'\bdocs?\b': 'documentation',
+        r'\bauth\b': 'authentication',
+        r'\benv\b': 'environment',
+    }
+    for pattern, replacement in abbreviations.items():
+        text = re.sub(pattern, replacement, text, flags=re.IGNORECASE)
+    return text
+
+def clean_for_speech(text: str) -> str:
+    """Clean and normalize text for natural speech."""
+    # Remove markdown formatting
+    text = re.sub(r'\*\*([^*]+)\*\*', r'\1', text)  # Bold
+    text = re.sub(r'\*([^*]+)\*', r'\1', text)      # Italic
+    text = re.sub(r'`([^`]+)`', r'\1', text)        # Inline code
+    text = re.sub(r'#{1,6}\s*', '', text)           # Headers
+
+    # Remove special characters that don't speak well
+    text = re.sub(r'[→│\|•]', ' ', text)
+    text = re.sub(r'[\[\]]', '', text)              # Square brackets
+
+    # Normalize whitespace
+    text = re.sub(r'\s+', ' ', text)
+
+    # Apply normalizations
+    text = normalize_urls(text)
+    text = expand_abbreviations(text)
+    text = normalize_numbers(text)
+
+    return text.strip()
+
+# ============================================================================
+# FILTERING
+# ============================================================================
+
+def should_speak(text: str) -> bool:
+    """Return True if text is natural conversation worth speaking."""
+    text = text.strip()
+
+    # Length checks
+    if len(text) < MIN_LENGTH or len(text) > MAX_LENGTH:
+        return False
+
+    # Too many newlines = probably not conversation
+    if text.count('\n') > MAX_NEWLINES:
+        return False
+
+    # Check reject patterns
+    for pattern in REJECT_PATTERNS:
+        if re.search(pattern, text, re.MULTILINE | re.IGNORECASE):
+            return False
+
+    return True
+
+# ============================================================================
+# SPEECH OUTPUT
+# ============================================================================
+
+def speak(text: str):
+    """Speak text via ElevenLabs with optimized settings."""
+    if VOLUME <= 0:
+        return
+
+    try:
+        from elevenlabs import ElevenLabs
+    except ImportError:
+        print("elevenlabs not installed", file=sys.stderr)
+        return
+
+    api_key = os.environ.get("ELEVEN_API_KEY")
+    voice_id = os.environ.get("ELEVEN_VOICE_ID", "PB6BdkFkZLbI39GHdnbQ")
+
+    if not api_key:
+        return
+
+    client = ElevenLabs(api_key=api_key)
+
+    # Clean text for speech
+    clean_text = clean_for_speech(text)
+
+    if not clean_text or len(clean_text) < MIN_LENGTH:
+        return
+
+    try:
+        audio = client.text_to_speech.convert(
+            voice_id=voice_id,
+            text=clean_text,
+            model_id="eleven_turbo_v2_5",  # Fast, good quality
+        )
+
+        with tempfile.NamedTemporaryFile(suffix=".mp3", delete=False) as f:
+            for chunk in audio:
+                f.write(chunk)
+            f.flush()
+            temp_path = f.name
+
+        # Play audio
+        try:
+            subprocess.run(
+                ["mpv", "--no-video", "--really-quiet", "--volume=50", temp_path],
+                check=True,
+                capture_output=True
+            )
+        except FileNotFoundError:
+            try:
+                subprocess.run(
+                    ["ffplay", "-nodisp", "-autoexit", "-loglevel", "quiet", "-volume", "50", temp_path],
+                    check=True,
+                    capture_output=True
+                )
+            except FileNotFoundError:
+                print("No audio player found (mpv or ffplay)", file=sys.stderr)
+
+        os.unlink(temp_path)
+
+    except Exception as e:
+        # Silently fail - don't interrupt workflow
+        pass
+
+# ============================================================================
+# MAIN
+# ============================================================================
+
+if __name__ == "__main__":
+    if len(sys.argv) > 1:
+        text = " ".join(sys.argv[1:])
+    else:
+        text = sys.stdin.read()
+
+    text = text.strip()
+
+    if should_speak(text):
+        speak(text)