@adaptic/maestro 1.1.7 → 1.4.1

package/docs/guides/webhook-relay-setup.md

@@ -0,0 +1,349 @@
+# Webhook Relay Setup Guide (Railway)
+
+How to deploy each agent's per-instance webhook relay to Railway. The relay is the canonical pattern for receiving inbound webhooks from Slack and Twilio without requiring a stable inbound connection from the Mac mini.
+
+**Prerequisites**: Complete the [Mac Mini Bootstrap](../runbooks/mac-mini-bootstrap.md). The agent needs:
+- A Slack app already created (see `slack-setup.md`) so we have `SLACK_SIGNING_SECRET`
+- A Twilio account (or sub-account) and number purchased so we have `TWILIO_AUTH_TOKEN`
+- Admin rights in the company's Railway workspace (e.g., "Adaptic")
+
+---
+
+## Why a relay?
+
+Maestro agents run on a Mac mini that doesn't have a stable public IP. External services need a permanent HTTPS URL for webhooks. Cloudflare Quick Tunnels work but the URL changes on restart, and named tunnels require Cloudflare DNS configuration.
+
+Railway gives every agent a permanent `*.up.railway.app` domain with HTTPS and zero infrastructure. The pattern: Slack/Twilio send to Railway → Railway buffers in memory → Mac mini polls Railway every 5 seconds → events land in `state/inbox/`.
+
+```
+┌─────────────┐                 ┌──────────────────────┐
+│   Slack     │──webhook──────▶│  {agent}-webhook-relay │
+│   Twilio    │                 │  (Railway, in {Org})   │
+└─────────────┘                 │  in-memory buffers     │
+                                └──────┬─────────────────┘
+                                       │ /events, /sms/messages, /whatsapp/messages
+                                       ▼
+                              ┌──────────────────┐
+                              │  Mac mini        │
+                              │  poll-relay.sh   │
+                              │  every 5 sec     │
+                              └────────┬─────────┘
+                                       ▼
+                              state/inbox/{slack,sms,whatsapp}/
+```
+
+---
+
+## 1. Source code
+
+The relay source is at `services/webhook-relay/` in every agent's repo (copied from the maestro framework at create time). It's a single ~250-line Node 20 HTTP server, no dependencies, deployable straight to Railway.
+
+```
+services/webhook-relay/
+├── server.mjs       # The HTTP server with all endpoints
+├── package.json     # Node 20+, type: module, no deps
+├── railway.json     # NIXPACKS builder, /health check, restart-on-failure
+├── .gitignore
+└── README.md
+```
+
+### Endpoints
+
+#### Webhook receivers (called by external services)
+
+| Path | Method | Caller | Notes |
+|---|---|---|---|
+| `/slack/events` | POST | Slack Events API | HMAC verified via `SLACK_SIGNING_SECRET`. Echoes `url_verification` challenges. |
+| `/sms` | POST | Twilio SMS | HMAC verified via `TWILIO_AUTH_TOKEN`. Returns empty TwiML. |
+| `/whatsapp` | POST | Twilio WhatsApp | Same. |
+| `/whatsapp/status` | POST | Twilio WhatsApp status callback | Same. |
+
+#### Drain endpoints (called by the local Mac mini)
+
+| Path | Method | Returns |
+|---|---|---|
+| `/events` | GET | All buffered Slack events, drains buffer |
+| `/sms/messages` | GET | All buffered SMS events, drains buffer |
+| `/whatsapp/messages` | GET | All buffered WhatsApp events |
+| `/whatsapp/statuses` | GET | All buffered WhatsApp delivery status events |
+| `/health` | GET | Service status, buffer sizes, signature flags |
+
+---
+
+## 2. Install Railway CLI
+
+```bash
+brew install railway 2>/dev/null || true
+railway --version  # should be 4.x
+```
+
+Then log in (interactive — opens browser):
+
+```bash
+railway login
+```
+
+Confirm with `railway whoami`. If you don't see the company workspace in `railway list`, ask an existing admin to grant you access.
+
+---
+
+## 3. Create the project
+
+Run from the agent's repo:
+
+```bash
+cd services/webhook-relay
+railway init --name {firstname-lower}-webhook-relay --workspace {Company}
+```
+
+For Lucas, this is `lucas-webhook-relay` in the `Adaptic` workspace.
+
+The CLI will print a project URL — note it for reference.
+
+---
+
+## 4. Deploy
+
+```bash
+railway up --service {firstname-lower}-webhook-relay --detach
+```
+
+This packages the local directory, uploads it to Railway, and triggers a Nixpacks build. Build typically takes 30–60 seconds. Watch the build logs in the URL the CLI prints.
+
+---
+
+## 5. Generate a public domain
+
+```bash
+railway domain --service {firstname-lower}-webhook-relay
+```
+
+Prints something like:
+```
+🚀 https://lucas-webhook-relay-production.up.railway.app
+```
+
+Save this URL — you'll use it everywhere.
+
+---
+
+## 6. Set environment variables
+
+```bash
+source ../../.env
+railway variables --service {firstname-lower}-webhook-relay \
+  --set "SLACK_SIGNING_SECRET=$SLACK_SIGNING_SECRET" \
+  --set "TWILIO_AUTH_TOKEN=$TWILIO_AUTH_TOKEN" \
+  --set "PUBLIC_HOSTNAME={firstname-lower}-webhook-relay-production.up.railway.app" \
+  --set "BUFFER_TTL_MS=600000" \
+  --set "MAX_BUFFER_SIZE=1000"
+```
+
+| Var | Required | Source | Purpose |
+|---|---|---|---|
+| `SLACK_SIGNING_SECRET` | yes | Slack app → Basic Information | HMAC verify Slack webhooks |
+| `TWILIO_AUTH_TOKEN` | yes | Twilio Console → Account | HMAC verify Twilio webhooks |
+| `PUBLIC_HOSTNAME` | yes | Railway domain (without https://) | Used in Twilio HMAC base string |
+| `BUFFER_TTL_MS` | no | default 600000 (10 min) | Drop events older than this |
+| `MAX_BUFFER_SIZE` | no | default 1000 | Max events per channel |
+| `POLL_AUTH_TOKEN` | no | (unset) | If set, GET endpoints require Bearer token |
+
+The `PORT` variable is provided automatically by Railway — don't set it.
+
+After setting variables, **trigger a redeploy** so the running container picks them up. The variables exist in the project but the running container was built with the previous values:
+
+```bash
+railway up --service {firstname-lower}-webhook-relay --detach
+```
+
+---
+
+## 7. Verify deployment
+
+```bash
+for i in 1 2 3 4 5 6 7 8 9 10 11 12; do
+  RESP=$(curl -sf -m 5 https://{firstname-lower}-webhook-relay-production.up.railway.app/health)
+  if echo "$RESP" | grep -q '"slack_signature":true' && echo "$RESP" | grep -q '"twilio_signature":true'; then
+    echo "✅ Relay live with signature verification"
+    break
+  fi
+  sleep 10
+done
+```
+
+Expected output of `/health`:
+
+```json
+{
+  "ok": true,
+  "service": "{firstname-lower}-webhook-relay",
+  "uptime_sec": 12.3,
+  "buffers": {
+    "slack": { "events": 0, "seen": 0 },
+    "sms": { "events": 0, "seen": 0 },
+    "whatsapp": { "events": 0, "seen": 0 },
+    "whatsapp_status": { "events": 0, "seen": 0 }
+  },
+  "config": {
+    "slack_signature": true,
+    "twilio_signature": true,
+    "poll_auth": false,
+    "buffer_ttl_ms": 600000,
+    "max_buffer_size": 1000
+  }
+}
+```
+
+If `slack_signature` or `twilio_signature` is `false`, the env vars didn't reach the running container — re-run `railway up`.
+
+---
+
+## 8. Configure external services to point at the relay
+
+### Slack Events Subscription
+
+Update via the App Manifest editor (more reliable than the events page):
+
+1. Navigate to `https://app.slack.com/app-settings/{TEAM_ID}/{APP_ID}/app-manifest`
+2. Read the JSON, add this block to `settings`:
+
+   ```json
+   "event_subscriptions": {
+     "request_url": "https://{firstname-lower}-webhook-relay-production.up.railway.app/slack/events",
+     "bot_events": [
+       "app_mention",
+       "message.channels",
+       "message.groups",
+       "message.im",
+       "message.mpim"
+     ]
+   }
+   ```
+
+3. Click **Save Changes**
+4. Navigate to `https://api.slack.com/apps/{APP_ID}/event-subscriptions` and click **Click here to verify** if the yellow banner appears
+5. **Reinstall the app** at `https://api.slack.com/apps/{APP_ID}/install-on-team` so the new event scopes activate
+
+### Twilio SMS webhook
+
+```bash
+RELAY_URL="https://{firstname-lower}-webhook-relay-production.up.railway.app"
+curl -s -u "$TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN" -X POST \
+  "https://api.twilio.com/2010-04-01/Accounts/$TWILIO_ACCOUNT_SID/IncomingPhoneNumbers/$TWILIO_PHONE_SID.json" \
+  --data-urlencode "SmsUrl=$RELAY_URL/sms" --data-urlencode "SmsMethod=POST"
+```
+
+### Twilio WhatsApp sandbox
+
+This requires a per-agent Twilio sub-account (the WhatsApp sandbox webhook is account-wide). See `docs/guides/twilio-subaccounts-setup.md`.
+
+Once you have the sub-account credentials, configure the sandbox via the Twilio Console UI (no API support):
+
+1. Navigate to `https://console.twilio.com/us1/develop/sms/try-it-out/whatsapp-learn?frameUrl=%2Fconsole%2Fsms%2Fwhatsapp%2Flearn`
+2. Click the **Sandbox settings** tab
+3. Set the inbound webhook URL to `https://{firstname-lower}-webhook-relay-production.up.railway.app/whatsapp` (HTTP POST)
+4. Set the status callback URL to `https://{firstname-lower}-webhook-relay-production.up.railway.app/whatsapp/status` (HTTP POST)
+5. Save
+
+---
+
+## 9. Local poll job
+
+The Mac mini runs a launchd job that polls the relay every 5 seconds. Install it:
+
+```bash
+# 1. Update scripts/poll-slack-events.sh — set EVENTS_URL to your relay's /events endpoint
+# 2. Update scripts/comms-monitor.sh — set RAILWAY_URL similarly
+# 3. Install the launchd plist:
+
+cat > scripts/local-triggers/plists/ai.adaptic.{firstname-lower}-poll-relay.plist <<EOF
+<?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>ai.adaptic.{firstname-lower}-poll-relay</string>
+    <key>ProgramArguments</key><array>
+        <string>/bin/bash</string>
+        <string>{REPO_ROOT}/scripts/poll-slack-events.sh</string>
+    </array>
+    <key>WorkingDirectory</key><string>{REPO_ROOT}</string>
+    <key>StartInterval</key><integer>5</integer>
+    <key>RunAtLoad</key><true/>
+    <key>StandardOutPath</key><string>{REPO_ROOT}/logs/polling/poll-relay-stdout.log</string>
+    <key>StandardErrorPath</key><string>{REPO_ROOT}/logs/polling/poll-relay-stderr.log</string>
+</dict>
+</plist>
+EOF
+
+cp scripts/local-triggers/plists/ai.adaptic.{firstname-lower}-poll-relay.plist ~/Library/LaunchAgents/
+launchctl load ~/Library/LaunchAgents/ai.adaptic.{firstname-lower}-poll-relay.plist
+launchctl list | grep poll-relay  # verify loaded
+```
+
+---
+
+## 10. End-to-end test
+
+1. Have a teammate (or yourself, from a separate Slack account) send a DM to the agent's bot in Slack, OR @-mention the bot in a public channel where the bot is a member
+2. Within ~5 seconds:
+   - `railway logs --service {firstname-lower}-webhook-relay` should show `[slack] buffered message...`
+   - `state/inbox/slack/` should contain a new YAML file
+   - `logs/polling/poll-relay-stdout.log` should show the inbox write
+3. The inbox processor (running as launchd `ai.adaptic.{firstname-lower}-inbox-processor`) picks up the YAML and routes it through the daemon
+
+---
+
+## Troubleshooting
+
+### `railway up` returns "Service not found"
+
+Run `railway add --service {firstname-lower}-webhook-relay` first to create the service container. The flag is required even when the project exists.
+
+### `railway init` returns "Unauthorized"
+
+Your Railway account doesn't have admin rights in the workspace. Ask an existing admin (or your principal) to grant you Admin role in the workspace's Members settings.
+
+### `slack_signature: false` in /health after deploy
+
+The env vars exist in the project but the running container was built before they were set. Re-run `railway up --service {firstname-lower}-webhook-relay --detach` to redeploy.
+
+### Slack URL verification fails with "URL didn't respond"
+
+The relay is reachable but signature verification fails. Causes:
+
+- `SLACK_SIGNING_SECRET` mismatch (check Slack app → Basic Information vs. Railway env var)
+- The relay is responding correctly to `url_verification` (returns the challenge), but Slack's caching layer hasn't flushed. Re-save the manifest, or click "Click here to verify" on the event subscriptions page.
+
+### Twilio webhook returns 401 "invalid signature"
+
+`PUBLIC_HOSTNAME` env var is wrong. It must match the actual host Twilio sends to (typically `{firstname-lower}-webhook-relay-production.up.railway.app`, no scheme, no trailing slash). Twilio includes the full URL in its signature base string.
+
+### Buffer fills up but Mac mini doesn't drain
+
+Check the launchd job:
+
+```bash
+launchctl list | grep poll-relay   # should show the label with a non-error exit code
+tail logs/polling/poll-relay-stderr.log
+```
+
+Also check `EVENTS_URL` in `scripts/poll-slack-events.sh` matches the deployed Railway domain.
+
+### The relay restarts and loses buffered events
+
+In-memory buffers are TTL'd at 10 minutes. If the relay restarts (Railway redeploy, instance recycle, OOM), buffered events are lost. The local Slack poller (`scripts/poller/slack-poller.mjs`) runs every 60 seconds as a fallback and will catch any missed channel/DM messages — at most a 60s gap. For SMS/WhatsApp this is acceptable because Twilio retries on failure.
+
+If you need persistence, add a Postgres or Redis service in the same Railway project and persist buffers there. Not currently necessary at our message volume.
+
+---
+
+## Why one service per agent?
+
+Each agent has its own Slack signing secret and Twilio account/sub-account. A shared relay would have to multiplex by header or path, which adds complexity and a single point of failure. Per-agent deployment is simpler, isolated, and gives independent scaling/restarts.
+
+## Related guides
+
+- [Slack Setup](slack-setup.md) — Slack app creation and OAuth
+- [Voice & SMS Setup](voice-sms-setup.md) — Twilio account, SMS handlers
+- [WhatsApp Setup](whatsapp-setup.md) — WhatsApp sandbox / production
+- [Twilio Subaccounts Setup](twilio-subaccounts-setup.md) — per-agent isolation for WhatsApp

package/docs/guides/whatsapp-setup.md

@@ -0,0 +1,282 @@
+# WhatsApp Setup Guide
+
+How to enable WhatsApp messaging for a Maestro agent: Twilio WhatsApp sandbox/production configuration, inbound webhook handler, outbound messaging (free-form and templates), media support, and Cloudflare tunnel exposure.
+
+**Prerequisites**: Complete the [Voice & SMS Setup](voice-sms-setup.md) sections 1.1–1.3 (Twilio account and credentials). WhatsApp uses the same Twilio account as SMS.
+
+---
+
+## Architecture Overview
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│  INBOUND                                                         │
+│                                                                   │
+│  WhatsApp user ──▶ Twilio Cloud ──▶ Cloudflare Tunnel           │
+│                     (webhook)        (port 3002)                 │
+│                                         │                        │
+│                                         ▼                        │
+│                                  whatsapp-handler.mjs            │
+│                                         │                        │
+│                                         ▼                        │
+│                             state/inbox/whatsapp/*.yaml          │
+│                             (inbox processor routes)             │
+├─────────────────────────────────────────────────────────────────┤
+│  OUTBOUND                                                        │
+│                                                                   │
+│  send-whatsapp.sh ──▶ Twilio Messages API ──▶ WhatsApp user     │
+│  (with dedup +         (whatsapp: prefix)                        │
+│   validation)                                                    │
+├─────────────────────────────────────────────────────────────────┤
+│  CONFIGURATION                                                   │
+│                                                                   │
+│  configure-whatsapp-sandbox.sh                                   │
+│  (prints manual steps for Twilio Console webhook setup)          │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 1. WhatsApp Modes
+
+Twilio offers two WhatsApp integration modes:
+
+| Mode | Use Case | Sender Number | Limitations |
+|---|---|---|---|
+| **Sandbox** | Testing and development | +1 415 523 8886 (shared Twilio number) | Recipients must opt-in by sending "join \<keyword\>" |
+| **Production** | Live operations | Agent's own Twilio number | Requires approved WhatsApp Business Account (WABA) |
+
+**Start with sandbox mode** — it's free and requires no approval. Switch to production when ready for live operations.
+
+---
+
+## 2. Sandbox Setup
+
+### 2.1 Activate the Sandbox
+
+1. Go to Twilio Console → Messaging → Try it Out → Send a WhatsApp Message
+2. Follow the on-screen instructions to activate the sandbox
+3. Note the **join keyword** (e.g. "join example-word")
+
+### 2.2 Add Recipients to Sandbox
+
+Each person who wants to message the agent must opt-in:
+
+1. Save +1 415 523 8886 as a WhatsApp contact
+2. Send the message: `join <keyword>` (the keyword from step 2.1)
+3. They'll receive a confirmation reply
+
+### 2.3 Configure Environment Variables
+
+Add to `.env`:
+
+```bash
+# WhatsApp mode
+WHATSAPP_MODE=sandbox
+
+# Twilio sandbox number (don't change)
+WHATSAPP_SANDBOX_NUMBER=+14155238886
+
+# Local port for webhook handler
+WHATSAPP_PORT=3002
+```
+
+---
+
+## 3. Production Setup
+
+### 3.1 Apply for WhatsApp Business Account
+
+1. Go to Twilio Console → Messaging → Senders → WhatsApp Senders
+2. Submit a request to connect your Twilio number as a WhatsApp Business sender
+3. This requires Meta/WhatsApp approval (can take days to weeks)
+
+### 3.2 Configure for Production
+
+Once approved, update `.env`:
+
+```bash
+WHATSAPP_MODE=production
+```
+
+In production mode, `send-whatsapp.sh` uses the agent's Twilio number instead of the sandbox number. Business-initiated messages (outside the 24-hour conversation window) require approved message templates.
+
+---
+
+## 4. Inbound — Webhook Handler
+
+### 4.1 Start the Handler
+
+```bash
+node scripts/whatsapp-handler.mjs
+```
+
+The handler listens on port 3002 (configurable via `WHATSAPP_PORT`) and provides:
+
+| Endpoint | Method | Purpose |
+|---|---|---|
+| `/whatsapp` | POST | Twilio inbound message webhook |
+| `/whatsapp/status` | POST | Delivery status callbacks |
+| `/health` | GET | Health check |
+
+### 4.2 How It Works
+
+1. Twilio receives a WhatsApp message to your number (or sandbox)
+2. Twilio POSTs to your webhook URL at `/whatsapp`
+3. Handler parses the message: strips `whatsapp:` prefix from From/To, extracts body, media
+4. Looks up sender in `config/caller-id-map.yaml` for identity and access level
+5. Writes a YAML inbox item to `state/inbox/whatsapp/`
+6. CEO messages create priority trigger files for immediate processing
+7. Returns empty TwiML (no auto-reply)
+
+### 4.3 Expose via Cloudflare Tunnel
+
+```bash
+# Start a tunnel to the WhatsApp handler
+cloudflared tunnel --url http://localhost:3002
+```
+
+Copy the generated URL (e.g. `https://random-words.trycloudflare.com`).
+
+### 4.4 Configure Twilio Webhook
+
+Use the configuration helper:
+
+```bash
+# Show current sandbox config
+./scripts/configure-whatsapp-sandbox.sh --status
+
+# Generate instructions for manual Twilio Console setup
+./scripts/configure-whatsapp-sandbox.sh --url https://your-tunnel-url.trycloudflare.com
+```
+
+The script prints manual steps since Twilio's WhatsApp sandbox webhooks must be configured in the Console:
+
+1. Go to Twilio Console → Messaging → Try it Out → WhatsApp → Sandbox Settings
+2. Set "When a message comes in": `https://your-tunnel-url/whatsapp` (HTTP POST)
+3. Set "Status callback URL": `https://your-tunnel-url/whatsapp/status` (HTTP POST)
+4. Save
+
+---
+
+## 5. Outbound — Sending Messages
+
+### 5.1 Free-Form Messages
+
+```bash
+# Sandbox mode (default)
+./scripts/send-whatsapp.sh --to "+971501234567" --body "Hello from the agent"
+
+# Production mode
+./scripts/send-whatsapp.sh --to "+971501234567" --body "Hello" --production
+```
+
+### 5.2 Template Messages
+
+For business-initiated messages outside the 24-hour window (production mode only):
+
+```bash
+./scripts/send-whatsapp.sh --to "+971501234567" --template "intro_greeting" --vars "AgentName,Company"
+```
+
+### 5.3 Media Messages
+
+```bash
+./scripts/send-whatsapp.sh --to "+971501234567" --body "Here's the report" --media "https://example.com/report.pdf"
+```
+
+### 5.4 Pre-Send Pipeline
+
+Outbound WhatsApp messages go through:
+
+1. **Content-hash dedup** (`outbound-dedup.sh`) — prevents identical concurrent sends
+2. **Factual validation** (`validate-outbound.py`) — blocks if critical issues found
+3. **Audit logging** — every send logged to `logs/whatsapp/` and `logs/audit/`
+
+---
+
+## 6. Process Management
+
+### 6.1 launchd Plist
+
+A template plist exists at `scripts/poller-launchd/ai.adaptic.sophie-whatsapp-handler.plist`. Copy and customize for your agent:
+
+```bash
+# Replace agent-specific values and install
+cp scripts/poller-launchd/ai.adaptic.sophie-whatsapp-handler.plist \
+   ~/Library/LaunchAgents/com.adaptic.AGENT.whatsapp-handler.plist
+
+# Edit the plist to update paths and labels
+# Then load:
+launchctl load ~/Library/LaunchAgents/com.adaptic.AGENT.whatsapp-handler.plist
+```
+
+### 6.2 Cloudflare Tunnel Persistence
+
+For production, configure a named tunnel (see [Voice & SMS Setup](voice-sms-setup.md) section 7.2) with an ingress rule for port 3002.
+
+---
+
+## 7. Testing
+
+| # | Test | How to Verify |
+|---|---|---|
+| 1 | Handler running | `curl http://localhost:3002/health` |
+| 2 | Tunnel accessible | `curl https://your-tunnel-url/health` |
+| 3 | Sandbox opt-in | Send "join \<keyword\>" from your phone to +1 415 523 8886 |
+| 4 | Inbound message | Send WhatsApp to sandbox; check `state/inbox/whatsapp/` |
+| 5 | Outbound message | `./scripts/send-whatsapp.sh --to "+YOUR_NUMBER" --body "Test"` |
+| 6 | Caller ID lookup | Inbound from known number should show correct name in YAML |
+| 7 | CEO priority | Message from principal should create priority trigger file |
+| 8 | Dedup working | Send identical outbound twice; second should `DEDUP_SKIP` |
+| 9 | Media outbound | Send with `--media` flag; verify media arrives |
+| 10 | Audit logging | Check `logs/whatsapp/` and `logs/audit/` for entries |
+
+---
+
+## 8. Troubleshooting
+
+### Sandbox: "Recipient has not opted in"
+
+Error code 63007 from Twilio means the recipient hasn't joined the sandbox:
+1. Have them send "join \<keyword\>" to +1 415 523 8886
+2. Verify the keyword matches what's shown in Twilio Console
+3. They must send from the exact WhatsApp number you're trying to reach
+
+### Messages not arriving at handler
+
+1. Check tunnel: `curl https://your-tunnel-url/health`
+2. Check Twilio webhook config matches your tunnel URL
+3. Check handler is running: `curl http://localhost:3002/health`
+4. Check handler logs: `tail -f logs/whatsapp-handler-stderr.log`
+
+### "Template not found" in production mode
+
+1. Templates must be approved by WhatsApp/Meta before use
+2. Verify template name matches exactly (case-sensitive)
+3. Verify template variables match the approved format
+
+### Media not sending
+
+1. Media URL must be publicly accessible (Twilio fetches it)
+2. Supported types: images (JPEG, PNG), documents (PDF), audio (OGG)
+3. Check Twilio's [media size limits](https://www.twilio.com/docs/whatsapp/guidance-whatsapp-media-messages)
+
+---
+
+## Key Files
+
+| File | Purpose |
+|---|---|
+| `scripts/send-whatsapp.sh` | Outbound WhatsApp sender (sandbox + production) |
+| `scripts/whatsapp-handler.mjs` | Inbound WhatsApp webhook handler |
+| `scripts/configure-whatsapp-sandbox.sh` | Sandbox webhook configuration helper |
+| `config/caller-id-map.yaml` | WhatsApp number → identity mapping |
+
+---
+
+## Related Documents
+
+- [Voice & SMS Setup](voice-sms-setup.md) — Twilio account setup, SMS, and voice calls
+- [Outbound Governance Setup](outbound-governance-setup.md) — Dedup and validation pipeline
+- [Poller & Daemon Setup](poller-daemon-setup.md) — How WhatsApp events integrate with the event loop

package/docs/runbooks/mac-mini-bootstrap.md

@@ -393,6 +393,17 @@ echo "=============================="
 - [ ] Log rotation configured
 - [ ] Health check runs cleanly
 - [ ] First morning brief generated successfully
+- [ ] (Optional) Voice/SMS configured -- see `docs/guides/voice-sms-setup.md`
+
+---
+
+## Optional: Voice & SMS Setup
+
+If this agent needs phone call or SMS capabilities (Slack huddle voice participation, inbound/outbound SMS via Twilio), follow the dedicated guide:
+
+**[Voice & SMS Setup Guide](../guides/voice-sms-setup.md)**
+
+This covers Twilio phone number purchase, inbound SMS webhook, outbound SMS, Slack huddle voice (Deepgram STT + ElevenLabs TTS), Cloudflare tunnel exposure, caller ID mapping, and launchd process management for the voice/SMS services.
 
 ---
 
@@ -400,5 +411,15 @@ Related documents:
 
 - `docs/runbooks/perpetual-operations.md` -- How the system runs continuously
 - `docs/runbooks/recovery-and-failover.md` -- Recovery procedures
+- `docs/guides/agent-persona-setup.md` -- Agent identity and configuration
+- `docs/guides/email-setup.md` -- Gmail IMAP and SMTP setup
+- `docs/guides/slack-setup.md` -- Slack app, tokens, and events
+- `docs/guides/whatsapp-setup.md` -- WhatsApp Business integration
+- `docs/guides/voice-sms-setup.md` -- Voice calls and SMS setup
+- `docs/guides/poller-daemon-setup.md` -- Event loop, daemon, triggers, watchdog
+- `docs/guides/outbound-governance-setup.md` -- Hooks, dedup, information barriers
+- `docs/guides/rag-context-setup.md` -- Search index and context retrieval
+- `docs/guides/pdf-generation-setup.md` -- Branded PDF documents
+- `docs/guides/media-generation-setup.md` -- AI-generated visual assets
 - `docs/workflows/executive-cadence.md` -- Full operating rhythm
 - `config/environment.yaml` -- Environment configuration reference

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adaptic/maestro",
-  "version": "1.1.7",
+  "version": "1.4.1",
   "description": "Maestro — Autonomous AI agent operating system. Deploy AI employees on dedicated Mac minis.",
   "type": "module",
   "bin": {
@@ -11,6 +11,7 @@
     "./tools": "./lib/tool-definitions.js",
     "./executor": "./lib/action-executor.js",
     "./singleton": "./lib/singleton.js",
+    "./tts": "./lib/tts.mjs",
     "./package.json": "./package.json"
   },
   "files": [