@adaptic/maestro 1.1.6 → 1.1.8

package/docs/guides/voice-sms-setup.md

@@ -0,0 +1,698 @@
+# Voice & SMS Setup Guide
+
+How to enable real-time voice calls (Slack huddles) and SMS messaging for a Maestro agent. This guide covers the full stack: Twilio phone number, inbound/outbound SMS, Slack huddle voice participation (Deepgram STT + ElevenLabs TTS), Cloudflare tunnel exposure, caller ID mapping, and voice transcript parsing.
+
+**Prerequisites**: Complete the [Mac Mini Bootstrap](../runbooks/mac-mini-bootstrap.md) and [Agent Persona Setup](agent-persona-setup.md) first. This guide assumes the agent repo is scaffolded and `/init-maestro` Phase 0–3 are done.
+
+---
+
+## Architecture Overview
+
+The voice/SMS stack has three layers:
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  Layer 1: SMS (Twilio)                                       │
+│  ┌──────────────┐    ┌──────────────────┐    ┌────────────┐ │
+│  │ Twilio Cloud  │───▶│ Cloudflare Tunnel │───▶│ sms-handler│ │
+│  │  (webhooks)   │    │  (port 3001)      │    │  .mjs      │ │
+│  └──────────────┘    └──────────────────┘    └─────┬──────┘ │
+│                                                     │        │
+│                                               state/inbox/   │
+│                                               sms/*.yaml     │
+├─────────────────────────────────────────────────────────────┤
+│  Layer 2: Slack Huddle Voice                                 │
+│  ┌──────────┐   ┌───────────┐   ┌──────────────────────┐   │
+│  │  Slack    │◀─▶│  CDP      │◀─▶│  huddle-controller   │   │
+│  │  Desktop  │   │  (9222)   │   │  .mjs                │   │
+│  └────┬─────┘   └───────────┘   └──────────────────────┘   │
+│       │                                                      │
+│  ┌────▼──────────────────────────────────────────────────┐  │
+│  │  BlackHole 2ch (capture)  ←→  Deepgram STT            │  │
+│  │  BlackHole 16ch (playback) ←→  ElevenLabs TTS         │  │
+│  │                    audio-bridge.mjs                     │  │
+│  └────────────────────────────────────────────────────────┘  │
+├─────────────────────────────────────────────────────────────┤
+│  Layer 3: Transcript Processing                              │
+│  ┌────────────────────┐   ┌─────────────────────────────┐   │
+│  │ parse-voice-       │──▶│ state/inbox/voice/*.yaml    │   │
+│  │ transcript.mjs     │   │ (action items, priorities)   │   │
+│  └────────────────────┘   └─────────────────────────────┘   │
+└─────────────────────────────────────────────────────────────┘
+```
+
+**Data flow summary**:
+- **SMS in**: Twilio → Cloudflare tunnel → `sms-handler.mjs` (port 3001) → inbox YAML → inbox processor
+- **SMS out**: Agent calls `scripts/send-sms.sh` → Twilio REST API → recipient phone
+- **Voice in**: Slack huddle audio → BlackHole 2ch → sox → Deepgram STT → transcript
+- **Voice out**: Claude response → ElevenLabs TTS → sox → BlackHole 16ch → Slack huddle mic
+- **Voice post-call**: Transcript summary → `parse-voice-transcript.mjs` → inbox YAML → action routing
+
+---
+
+## 1. Twilio Account & Phone Number
+
+### 1.1 Create a Twilio Account
+
+1. Sign up at https://www.twilio.com/ (pay-as-you-go, no minimum commitment)
+2. Verify your email and phone number
+3. From the Twilio Console dashboard, copy:
+   - **Account SID** (starts with `AC`)
+   - **Auth Token** (click to reveal)
+
+### 1.2 Purchase a Phone Number
+
+1. Go to Twilio Console → Phone Numbers → Buy a Number
+2. Search for a number with **both SMS and Voice capabilities** enabled
+3. Select a number in a region appropriate for your agent's primary contacts
+4. Note the number in E.164 format (e.g., `+15551234567`)
+
+**Tip**: US numbers are cheapest (~$1.15/month). If your contacts are international, check Twilio's [geo-permissions](https://console.twilio.com/us1/develop/sms/settings/geo-permissions) and enable the countries you need for inbound/outbound SMS.
+
+### 1.3 Configure Environment Variables
+
+Add to your agent's `.env`:
+
+```bash
+# Twilio credentials
+TWILIO_ACCOUNT_SID=ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+TWILIO_AUTH_TOKEN=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+TWILIO_PHONE_NUMBER=+15551234567
+TWILIO_PHONE_SID=PNxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx   # Optional: from Phone Numbers → your number
+```
+
+### 1.4 Enable Geo-Permissions (International SMS)
+
+If your agent needs to send/receive SMS to/from international numbers:
+
+1. Go to Twilio Console → Messaging → Settings → Geo Permissions
+2. Enable each country where your contacts have phone numbers
+3. **Critical for UAE**: Enable "United Arab Emirates" if your principal or contacts use UAE numbers
+
+---
+
+## 2. SMS — Inbound (Webhook Handler)
+
+The inbound SMS handler (`scripts/sms-handler.mjs`) receives Twilio webhook POSTs and writes messages to the agent's inbox for processing.
+
+### 2.1 How It Works
+
+1. Twilio receives an SMS to your agent's phone number
+2. Twilio sends an HTTP POST to your configured webhook URL
+3. `sms-handler.mjs` parses the message, looks up the sender in `config/caller-id-map.yaml`
+4. Creates a YAML file in `state/inbox/sms/` with sender identity, access level, and priority
+5. Returns empty TwiML (prevents Twilio from auto-replying)
+6. CEO messages automatically create priority trigger files for immediate processing
+
+### 2.2 Start the SMS Handler
+
+```bash
+# Start the handler (default port 3001)
+node scripts/sms-handler.mjs
+
+# Or with a custom port
+SMS_PORT=3005 node scripts/sms-handler.mjs
+```
+
+Verify it's running:
+
+```bash
+curl http://localhost:3001/health
+# Expected: {"status":"ok","uptime":...}
+```
+
+### 2.3 Expose via Cloudflare Tunnel
+
+The handler runs locally — Twilio needs a public URL to reach it. Use Cloudflare's free quick tunnels:
+
+```bash
+# Install cloudflared if not already present
+brew install cloudflared
+
+# Start a tunnel to the SMS handler
+cloudflared tunnel --url http://localhost:3001
+```
+
+Cloudflared prints a public URL like `https://random-words-here.trycloudflare.com`. Copy this URL.
+
+**Important**: Quick tunnels generate a new URL each time. For production stability, set up a [named tunnel](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/get-started/) with a fixed subdomain.
+
+### 2.4 Configure Twilio Webhook
+
+1. Go to Twilio Console → Phone Numbers → Active Numbers → your number
+2. Under **Messaging** → "A message comes in":
+   - Set to **Webhook**
+   - URL: `https://your-tunnel-url.trycloudflare.com/sms`
+   - Method: **HTTP POST**
+3. Click **Save configuration**
+
+### 2.5 Test Inbound SMS
+
+Send an SMS to your agent's Twilio number from your phone. Check:
+
+```bash
+# Verify the message landed in the inbox
+ls state/inbox/sms/
+
+# Check the SMS logs
+cat logs/sms/$(date +%Y-%m-%d)/*.jsonl | tail -1 | jq .
+```
+
+---
+
+## 3. SMS — Outbound
+
+Outbound SMS uses `scripts/send-sms.sh`, a shell wrapper around Twilio's REST API with built-in deduplication and audit logging.
+
+### 3.1 Send an SMS
+
+```bash
+./scripts/send-sms.sh --to "+1234567890" --body "Hello from your agent"
+```
+
+Options:
+
+| Flag     | Description                                    | Required |
+|----------|------------------------------------------------|----------|
+| `--to`   | Recipient phone number (E.164 format)          | Yes      |
+| `--body` | Message text                                   | Yes      |
+| `--from` | Sender number (defaults to `$TWILIO_PHONE_NUMBER`) | No   |
+
+### 3.2 Deduplication
+
+The send script integrates with `scripts/outbound-dedup.sh` to prevent duplicate sends when multiple sessions are running concurrently. This is automatic — no configuration needed.
+
+### 3.3 Audit Trail
+
+Every outbound SMS is logged to two locations:
+
+- `logs/sms/YYYY-MM-DD/YYYY-MM-DD-sms.jsonl` — SMS-specific log
+- `logs/audit/YYYY-MM-DD-actions.jsonl` — Global audit trail
+
+---
+
+## 4. Caller ID Mapping
+
+Both the SMS handler and voice transcript parser use `config/caller-id-map.yaml` to identify callers and assign access levels. This file is a **security boundary** — it determines what information the agent can share with each caller.
+
+### 4.1 Create the Caller ID Map
+
+If your agent was scaffolded with `npx @adaptic/maestro create`, a template exists at `config/caller-id-map.yaml`. If not, create one:
+
+```yaml
+# config/caller-id-map.yaml
+#
+# Maps phone numbers, Slack IDs, and emails to user identities with access levels.
+# Used by: sms-handler.mjs, parse-voice-transcript.mjs, user-context-search.py
+#
+# Access levels:
+#   ceo        — Full access to all paths (memory, knowledge, state, outputs, docs, logs)
+#   leadership — Company knowledge + docs + research/briefs + own interaction logs
+#   partner    — Public knowledge + research + own interaction logs
+#   default    — Public company knowledge only (knowledge/sources/)
+
+users:
+  # Principal (the person the agent reports to)
+  principal-name:
+    name: "Full Name"
+    phone: ["+1XXXXXXXXXX"]
+    whatsapp: ["+1XXXXXXXXXX"]
+    slack_id: "UXXXXXXXXXX"
+    email: "name@company.com"
+    access_level: ceo
+
+  # Add team members, partners, and other contacts below
+  # team-member:
+  #   name: "Team Member Name"
+  #   phone: []
+  #   slack_id: "UXXXXXXXXXX"
+  #   email: "member@company.com"
+  #   access_level: leadership
+```
+
+### 4.2 Access Level Reference
+
+| Level        | Accessible Paths                                                            | Typical Recipients              |
+|--------------|-----------------------------------------------------------------------------|----------------------------------|
+| `ceo`        | Everything: memory/, knowledge/, state/, outputs/, docs/, logs/, all interactions | CEO / principal                 |
+| `leadership` | knowledge/ (company), docs/, research/briefs, own interaction logs          | C-suite, directors, senior team |
+| `partner`    | knowledge/sources/ (public), research, own interaction logs                 | JV partners, advisors           |
+| `default`    | knowledge/sources/ only (public company knowledge)                          | Unknown callers, vendors        |
+
+### 4.3 Hot Reload
+
+The SMS handler reloads `caller-id-map.yaml` every 60 seconds automatically. No restart needed when adding contacts.
+
+---
+
+## 5. Voice — Slack Huddle Infrastructure
+
+The voice stack enables the agent to join Slack huddles, listen via STT, reason via Claude, and speak via TTS. This requires virtual audio routing and three API integrations.
+
+### 5.1 Install Audio Dependencies
+
+Run the setup script:
+
+```bash
+cd scripts/huddle
+./setup-audio.sh
+```
+
+This installs:
+
+| Component         | Install Method       | Purpose                                          |
+|-------------------|----------------------|--------------------------------------------------|
+| BlackHole 2ch     | `brew install blackhole-2ch`  | Captures Slack's speaker output (what others say) |
+| BlackHole 16ch    | `brew install blackhole-16ch` | Carries TTS output to Slack's mic (what agent says) |
+| sox               | `brew install sox`            | Audio capture and playback between devices        |
+| SwitchAudioSource | `brew install switchaudio-osx`| Lists and verifies audio devices                  |
+
+**Why two BlackHole devices?** Using separate virtual audio devices for capture (2ch) and playback (16ch) prevents feedback loops. If the same device were used for both, the agent would hear its own TTS output, transcribe it, and respond to itself in an infinite loop.
+
+### 5.2 Configure Slack Audio
+
+Open Slack → Preferences → Audio & Video:
+
+| Setting      | Value            | Purpose                                      |
+|--------------|------------------|----------------------------------------------|
+| Speaker      | BlackHole 2ch    | Routes huddle audio to the capture pipeline  |
+| Microphone   | BlackHole 16ch   | Routes TTS output into the huddle            |
+
+**Note**: System audio (built-in speakers/mic) remains unchanged. Only Slack's audio is rerouted.
+
+### 5.3 Verify Audio Setup
+
+```bash
+# Check all devices are present
+./scripts/huddle/setup-audio.sh --check
+
+# Test capture and playback
+./scripts/huddle/setup-audio.sh --test
+```
+
+### 5.4 Configure Voice API Keys
+
+Add to `.env`:
+
+```bash
+# Speech-to-text (Deepgram)
+# Sign up: https://deepgram.com/ (free tier: 200 hours/year)
+DEEPGRAM_API_KEY=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+
+# Text-to-speech (ElevenLabs)
+# Sign up: https://elevenlabs.io/ (free tier available)
+ELEVENLABS_API_KEY=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+```
+
+### 5.5 Launch Slack with CDP
+
+The huddle controller automates Slack via Chrome DevTools Protocol. Slack must be launched with remote debugging enabled:
+
+```bash
+# Launch Slack with CDP on port 9222
+./scripts/huddle/launch-slack.sh
+
+# Or manually:
+/Applications/Slack.app/Contents/MacOS/Slack --remote-debugging-port=9222
+```
+
+Add this to your agent's launchd configuration or Login Items so Slack always starts with CDP enabled.
+
+### 5.6 Install Huddle Dependencies
+
+```bash
+cd scripts/huddle
+npm install
+```
+
+This installs `ws` (WebSocket client for CDP), `@anthropic-ai/sdk`, and `dotenv`.
+
+### 5.7 Start the Huddle Server
+
+```bash
+# Start and listen for huddle invitations
+node scripts/huddle/huddle-server.mjs
+
+# Join a specific channel's huddle
+node scripts/huddle/huddle-server.mjs --join general
+
+# Initiate a huddle with someone
+node scripts/huddle/huddle-server.mjs --call mehran
+```
+
+The huddle server:
+1. Connects to Slack via CDP (port 9222)
+2. Listens for huddle invitations
+3. On join: starts the audio bridge (Deepgram STT ↔ Claude reasoning ↔ ElevenLabs TTS)
+4. On huddle end: saves transcript, routes action items to queues
+
+### 5.8 Audio Bridge Configuration
+
+The audio bridge supports two capture modes (set via environment variable):
+
+| Mode       | Env Variable                    | How It Works                                    | When to Use              |
+|------------|--------------------------------|-------------------------------------------------|--------------------------|
+| `webaudio` | `HUDDLE_CAPTURE_MODE=webaudio` | Injects ScriptProcessorNode via CDP (echo-free) | Default, recommended     |
+| `sox`      | `HUDDLE_CAPTURE_MODE=sox`      | Captures from BlackHole 2ch via sox              | Fallback if CDP fails    |
+
+Optional environment variables:
+
+```bash
+HUDDLE_CAPTURE_DEVICE="BlackHole 2ch"     # sox capture device name
+HUDDLE_PLAYBACK_DEVICE="BlackHole 16ch"   # sox playback device name
+HUDDLE_CAPTURE_WS_PORT=3201               # WebSocket port for webaudio capture
+HUDDLE_EVENTS_PORT=3200                    # HTTP port for huddle event API
+HUDDLE_USE_API=0                           # Set to 1 to use Anthropic API instead of Claude CLI
+```
+
+---
+
+## 6. Voice Transcript Processing
+
+After a huddle ends, the transcript is posted to Slack. The transcript parser extracts structured action items for queue routing.
+
+### 6.1 How It Works
+
+`scripts/parse-voice-transcript.mjs` processes transcript summaries and:
+
+1. Identifies the caller from the phone number (via hardcoded map — keep in sync with `caller-id-map.yaml`)
+2. Extracts caller statements from "Caller said:" blocks
+3. Classifies each statement using regex pattern matching across 6 categories:
+   - Direct requests ("I need...", "Can you...", "Please...")
+   - Imperative verbs (take, send, create, update, schedule)
+   - Questions implying action ("What are our options for...?")
+   - Decisions/directives ("We should...", "Let's...")
+   - Time-sensitive signals (today, urgent, ASAP, emergency)
+   - Follow-up triggers (references to previous conversations)
+4. Assigns priority: `critical` (urgent/emergency), `high` (today/priority), `medium` (this week)
+5. Detects topic shifts and groups statements by topic
+6. CEO callers get automatic priority boost (medium → high)
+
+### 6.2 Usage
+
+The parser is called by the inbox processor when it detects a voice transcript message in Slack. It can also be used standalone:
+
+```bash
+# Test with a transcript file
+node scripts/parse-voice-transcript.mjs < transcript.txt
+
+# Run the test suite
+node scripts/test-voice-parser.mjs
+```
+
+### 6.3 Updating Known Callers
+
+The parser has a hardcoded `KNOWN_CALLERS` map at the top of the file. When adding a new contact, update both:
+
+1. `config/caller-id-map.yaml` — for SMS handler and RAG access
+2. `scripts/parse-voice-transcript.mjs` → `KNOWN_CALLERS` — for transcript caller identification
+
+---
+
+## 7. Process Management
+
+In production, the SMS handler and huddle server run as persistent background processes alongside the poller and daemon.
+
+### 7.1 launchd Plists
+
+Create launchd agents for persistent process management. These ensure the services restart automatically after crashes or reboots.
+
+**SMS Handler** (`~/Library/LaunchAgents/com.adaptic.<agent>.sms-handler.plist`):
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
+  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+    <key>Label</key>
+    <string>com.adaptic.AGENT_NAME.sms-handler</string>
+    <key>ProgramArguments</key>
+    <array>
+        <string>/opt/homebrew/bin/node</string>
+        <string>scripts/sms-handler.mjs</string>
+    </array>
+    <key>WorkingDirectory</key>
+    <string>/Users/AGENT_USER/AGENT_REPO</string>
+    <key>RunAtLoad</key>
+    <true/>
+    <key>KeepAlive</key>
+    <true/>
+    <key>StandardOutPath</key>
+    <string>/Users/AGENT_USER/AGENT_REPO/logs/sms-handler-stdout.log</string>
+    <key>StandardErrorPath</key>
+    <string>/Users/AGENT_USER/AGENT_REPO/logs/sms-handler-stderr.log</string>
+    <key>EnvironmentVariables</key>
+    <dict>
+        <key>PATH</key>
+        <string>/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin</string>
+    </dict>
+    <key>ThrottleInterval</key>
+    <integer>10</integer>
+</dict>
+</plist>
+```
+
+**Huddle Server** (`~/Library/LaunchAgents/com.adaptic.<agent>.huddle-server.plist`):
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
+  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+    <key>Label</key>
+    <string>com.adaptic.AGENT_NAME.huddle-server</string>
+    <key>ProgramArguments</key>
+    <array>
+        <string>/opt/homebrew/bin/node</string>
+        <string>scripts/huddle/huddle-server.mjs</string>
+    </array>
+    <key>WorkingDirectory</key>
+    <string>/Users/AGENT_USER/AGENT_REPO</string>
+    <key>RunAtLoad</key>
+    <true/>
+    <key>KeepAlive</key>
+    <true/>
+    <key>StandardOutPath</key>
+    <string>/Users/AGENT_USER/AGENT_REPO/logs/huddle-server-stdout.log</string>
+    <key>StandardErrorPath</key>
+    <string>/Users/AGENT_USER/AGENT_REPO/logs/huddle-server-stderr.log</string>
+    <key>EnvironmentVariables</key>
+    <dict>
+        <key>PATH</key>
+        <string>/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin</string>
+    </dict>
+    <key>ThrottleInterval</key>
+    <integer>10</integer>
+</dict>
+</plist>
+```
+
+Replace `AGENT_NAME`, `AGENT_USER`, and `AGENT_REPO` with your agent's values.
+
+Load the plists:
+
+```bash
+launchctl load ~/Library/LaunchAgents/com.adaptic.AGENT_NAME.sms-handler.plist
+launchctl load ~/Library/LaunchAgents/com.adaptic.AGENT_NAME.huddle-server.plist
+```
+
+### 7.2 Cloudflare Tunnel Persistence
+
+For production, set up a named Cloudflare tunnel so the webhook URL doesn't change on restart:
+
+```bash
+# Authenticate (one-time)
+cloudflared tunnel login
+
+# Create a named tunnel
+cloudflared tunnel create agent-webhooks
+
+# Configure routes in ~/.cloudflared/config.yml
+cat > ~/.cloudflared/config.yml << 'EOF'
+tunnel: <TUNNEL_ID>
+credentials-file: /Users/AGENT_USER/.cloudflared/<TUNNEL_ID>.json
+
+ingress:
+  - hostname: sms.agent.yourdomain.com
+    service: http://localhost:3001
+  - hostname: whatsapp.agent.yourdomain.com
+    service: http://localhost:3002
+  - service: http_status:404
+EOF
+
+# Run the tunnel
+cloudflared tunnel run agent-webhooks
+```
+
+Create a launchd plist for the tunnel as well, following the same pattern as the SMS handler plist.
+
+---
+
+## 8. Testing
+
+### 8.1 SMS End-to-End Test
+
+| # | Test                            | How to Verify                                         |
+|---|---------------------------------|-------------------------------------------------------|
+| 1 | Send SMS to agent's number      | Check `state/inbox/sms/` for new YAML file            |
+| 2 | Verify caller ID lookup         | YAML file should contain correct sender name + level  |
+| 3 | Verify CEO priority detection   | CEO messages should create priority trigger file       |
+| 4 | Send outbound SMS               | `./scripts/send-sms.sh --to "+1..." --body "test"`    |
+| 5 | Verify dedup                    | Send identical outbound twice quickly; second skips    |
+| 6 | Verify audit log                | Check `logs/audit/YYYY-MM-DD-actions.jsonl`           |
+| 7 | Unknown sender handling         | SMS from unknown number should get `default` access    |
+
+### 8.2 Voice End-to-End Test
+
+| # | Test                            | How to Verify                                         |
+|---|---------------------------------|-------------------------------------------------------|
+| 1 | Audio setup                     | `./scripts/huddle/setup-audio.sh --check`             |
+| 2 | Audio capture/playback          | `./scripts/huddle/setup-audio.sh --test`              |
+| 3 | CDP connection                  | Huddle server logs "CDP connected" on start           |
+| 4 | Join huddle                     | `node scripts/huddle/huddle-server.mjs --call <user>` |
+| 5 | STT working                     | Server logs transcribed speech within ~2 seconds       |
+| 6 | TTS working                     | Agent's voice is audible in the huddle                |
+| 7 | Transcript saved                | Check `logs/huddle/` for transcript file              |
+| 8 | Action items extracted          | Run parser on transcript; verify structured output     |
+
+### 8.3 Voice Transcript Parser Test
+
+```bash
+node scripts/test-voice-parser.mjs
+```
+
+This runs the parser against sample transcripts and validates extraction accuracy.
+
+---
+
+## 9. Troubleshooting
+
+### SMS handler not receiving messages
+
+1. **Check tunnel is running**: `curl https://your-tunnel-url/health`
+2. **Check Twilio webhook config**: Twilio Console → Phone Numbers → your number → Messaging → webhook URL must match tunnel
+3. **Check geo-permissions**: Twilio Console → Messaging → Settings → Geo Permissions → sender's country enabled
+4. **Check handler is listening**: `curl http://localhost:3001/health`
+5. **Check logs**: `tail -f logs/sms-handler-stderr.log`
+
+### Outbound SMS fails
+
+1. **Check Twilio credentials**: `echo $TWILIO_ACCOUNT_SID` should start with `AC`
+2. **Check phone number format**: Must be E.164 (`+` prefix, country code, no spaces)
+3. **Check Twilio balance**: Low balance prevents sends
+4. **Check dedup**: If you see `DEDUP_SKIP`, the same message was recently sent
+
+### Audio devices not found
+
+1. **Run setup**: `./scripts/huddle/setup-audio.sh`
+2. **Restart after install**: BlackHole may require a system restart after first install
+3. **Verify devices**: `SwitchAudioSource -a` should list both BlackHole 2ch and 16ch
+4. **Check Slack audio settings**: Slack Preferences → Audio & Video → verify speaker = BlackHole 2ch, mic = BlackHole 16ch
+
+### Huddle server can't connect to Slack
+
+1. **Check Slack is running with CDP**: `curl http://localhost:9222/json/version` should return Slack version info
+2. **Relaunch Slack**: `./scripts/huddle/launch-slack.sh`
+3. **Check CDP port**: Ensure no other Electron app (VS Code, etc.) is claiming port 9222
+
+### Echo in huddles (agent hears itself)
+
+1. **Switch capture mode**: Set `HUDDLE_CAPTURE_MODE=webaudio` in `.env` (this bypasses BlackHole for inbound capture, using CDP-injected audio capture instead)
+2. **Verify audio routing**: BlackHole 2ch should be Slack's speaker only; system speaker should remain on built-in
+
+### Deepgram not transcribing
+
+1. **Check API key**: Verify `DEEPGRAM_API_KEY` is set and valid
+2. **Check audio signal**: `./scripts/huddle/setup-audio.sh --test` should show non-zero bytes captured
+3. **Check WebSocket**: Audio bridge logs should show "Deepgram connected"
+4. **Check model**: Default is `nova-2` — verify your Deepgram plan supports it
+
+### ElevenLabs TTS not working
+
+1. **Check API key**: Verify `ELEVENLABS_API_KEY` is set and valid
+2. **Check voice ID**: Default voice and model are configured in audio-bridge.mjs — verify they match your ElevenLabs account
+3. **Check playback device**: `sox -n -t coreaudio "BlackHole 16ch" synth 1 sine 440` should play without error
+4. **Check quota**: Free tier has limited characters per month
+
+---
+
+## 10. Security Considerations
+
+### Caller Authentication
+
+- All inbound SMS senders are looked up in `caller-id-map.yaml` before processing
+- Unknown numbers receive `default` (most restrictive) access level
+- The agent never shares internal state, logs, or memory with unknown callers
+- Phone number spoofing is possible — do not treat SMS as a secure authentication channel for high-risk actions
+
+### Twilio Request Validation
+
+When `TWILIO_ACCOUNT_SID` and `TWILIO_AUTH_TOKEN` are set, the SMS handler can validate that incoming webhooks genuinely come from Twilio. This prevents third parties from injecting fake messages by POSTing to your webhook URL.
+
+### Tunnel Security
+
+- Quick tunnels (random URLs) provide security-through-obscurity but the URL can leak
+- Named tunnels with Cloudflare Access provide proper authentication
+- Consider adding IP allowlisting in Cloudflare if your Twilio traffic comes from known IPs
+
+### Voice Data
+
+- Audio is processed in real-time and not stored permanently (only transcripts are kept)
+- Deepgram processes audio on their servers — review their [data handling policy](https://deepgram.com/privacy)
+- ElevenLabs processes text on their servers — review their [privacy policy](https://elevenlabs.io/privacy)
+- All voice transcripts are logged locally in `logs/huddle/`
+
+---
+
+## Quick Reference
+
+### Ports
+
+| Service           | Default Port | Env Variable            |
+|-------------------|-------------|-------------------------|
+| SMS Handler       | 3001        | `SMS_PORT`              |
+| WhatsApp Handler  | 3002        | `WHATSAPP_PORT`         |
+| Huddle Events API | 3200        | `HUDDLE_EVENTS_PORT`    |
+| Audio Capture WS  | 3201        | `HUDDLE_CAPTURE_WS_PORT`|
+| Slack CDP         | 9222        | (launch flag)           |
+
+### Environment Variables (Voice/SMS)
+
+| Variable                   | Required For   | Description                              |
+|---------------------------|----------------|------------------------------------------|
+| `TWILIO_ACCOUNT_SID`     | SMS            | Twilio account identifier                 |
+| `TWILIO_AUTH_TOKEN`       | SMS            | Twilio authentication token               |
+| `TWILIO_PHONE_NUMBER`    | SMS            | Agent's Twilio phone number (E.164)       |
+| `TWILIO_PHONE_SID`       | SMS (optional) | Phone number SID for advanced features    |
+| `DEEPGRAM_API_KEY`       | Voice          | Deepgram STT API key                      |
+| `ELEVENLABS_API_KEY`     | Voice          | ElevenLabs TTS API key                    |
+| `SMS_PORT`               | SMS (optional) | Override default SMS handler port         |
+| `HUDDLE_CAPTURE_MODE`    | Voice (optional)| `webaudio` (default) or `sox`            |
+| `HUDDLE_USE_API`         | Voice (optional)| Set `1` to use Anthropic API vs CLI      |
+
+### Key Files
+
+| File                                 | Purpose                                        |
+|--------------------------------------|-------------------------------------------------|
+| `scripts/sms-handler.mjs`           | Inbound SMS webhook handler                     |
+| `scripts/send-sms.sh`               | Outbound SMS sender with dedup                  |
+| `scripts/huddle/setup-audio.sh`     | Audio device installation and verification      |
+| `scripts/huddle/launch-slack.sh`    | Launch Slack with CDP enabled                   |
+| `scripts/huddle/start-call.mjs`     | Initiate a Slack huddle with a contact          |
+| `scripts/huddle/huddle-server.mjs`  | Main huddle orchestrator                        |
+| `scripts/huddle/huddle-controller.mjs` | Slack CDP automation for huddle UI           |
+| `scripts/huddle/audio-bridge.mjs`   | Bidirectional STT/TTS audio pipeline            |
+| `scripts/parse-voice-transcript.mjs`| Extract action items from call transcripts      |
+| `config/caller-id-map.yaml`         | Phone → identity mapping with access levels     |
+
+---
+
+## Related Documents
+
+- [Mac Mini Bootstrap](../runbooks/mac-mini-bootstrap.md) — Full machine setup
+- [Agent Persona Setup](agent-persona-setup.md) — Identity and configuration
+- [Perpetual Operations](../runbooks/perpetual-operations.md) — How the system runs 24/7
+- [Communications Policy](../governance/communications-policy.md) — Voice modes and approval rules
+- [System Architecture](../architecture/system-architecture.md) — Overall system design