@adaptic/maestro 1.1.7 → 1.4.1

package/docs/guides/slack-setup.md

@@ -0,0 +1,350 @@
+# Slack Setup Guide
+
+How to enable Slack integration for a Maestro agent: dedicated app creation, token configuration, message sending (with typing indicators), file uploads, emoji reactions, real-time events via Railway relay, and Slack CDP for huddle automation.
+
+> **Hard requirement: every agent gets its own dedicated Slack app.** Do NOT share a Slack app across agents. Each app has its own bot user, signing secret, OAuth tokens, and scope set. Sharing breaks identity (messages appear as the wrong agent), confuses signature verification on the webhook relay, and prevents per-agent revocation. The init-maestro wizard creates a new app for each agent via the Slack manifest API.
+
+**Prerequisites**: Complete the [Mac Mini Bootstrap](../runbooks/mac-mini-bootstrap.md). The agent needs a Slack workspace account with admin rights to create apps.
+
+---
+
+## Architecture Overview
+
+```
+┌──────────────────────────────────────────────────────────────────────┐
+│  INBOUND                                                              │
+│                                                                       │
+│  Slack workspace ──▶ slack-poller.mjs ──▶ state/inbox/slack/*.yaml   │
+│  (via xoxp- token)   (every 60s)          (inbox processor routes)   │
+│                                                                       │
+│  OR (real-time):                                                      │
+│  Slack Events API ──▶ slack-events-server.mjs ──▶ inbox / daemon     │
+│  (webhook)             (Socket Mode or HTTP)                          │
+├──────────────────────────────────────────────────────────────────────┤
+│  OUTBOUND                                                             │
+│                                                                       │
+│  ┌───────────────┐  ┌─────────────────┐  ┌──────────────────┐       │
+│  │ slack-send.sh  │  │ slack-upload-   │  │ slack-react.mjs  │       │
+│  │ (messages)     │  │ v2.py (files)   │  │ (emoji reactions)│       │
+│  └──────┬────────┘  └────────┬────────┘  └──────────────────┘       │
+│         │                    │                                        │
+│  ┌──────▼────────────────────▼──────────────────────────────────┐   │
+│  │  Pre-send pipeline:                                           │   │
+│  │  1. validate-outbound.py (factual checks)                     │   │
+│  │  2. slack-responded.sh   (atomic response dedup)              │   │
+│  │  3. pre_draft_lookup.py  (context enrichment)                 │   │
+│  │  4. slack-typing.mjs     (typing indicator)                   │   │
+│  │  5. markdown → mrkdwn    (format conversion)                  │   │
+│  └──────────────────────────────────────────────────────────────┘   │
+│         │                                                            │
+│         ▼                                                            │
+│    Slack Web API (chat.postMessage) via xoxp- User Token            │
+└──────────────────────────────────────────────────────────────────────┘
+```
+
+**Critical design decision**: All Slack messages are sent via the **User OAuth Token (xoxp-)**, not the Bot Token (xoxb-). Messages sent with the user token appear as the agent's Slack user account (e.g. "Sophie Nguyen"), not as a bot app. The `block-mcp-slack-send.sh` hook enforces this — MCP Slack sends are blocked because they add a "Sent using @Claude" label.
+
+---
+
+## 1. Slack App Creation
+
+### 1.1 Create a Slack App
+
+1. Go to https://api.slack.com/apps → **Create New App**
+2. Choose "From scratch"
+3. Name it (e.g. "Adaptic Agent") and select your workspace
+4. Note the **App ID** from Basic Information
+
+### 1.2 Configure OAuth Scopes
+
+Under **OAuth & Permissions** → **Scopes**, add:
+
+**Bot Token Scopes** (xoxb-):
+
+| Scope | Purpose |
+|---|---|
+| `chat:write` | Send messages |
+| `channels:read` | List channels |
+| `groups:read` | List private channels |
+| `im:read` | List DM conversations |
+| `users:read` | Look up user info |
+| `files:write` | Upload files |
+| `reactions:write` | Add emoji reactions |
+
+**User Token Scopes** (xoxp-):
+
+| Scope | Purpose |
+|---|---|
+| `channels:history` | Read channel messages |
+| `groups:history` | Read private channel messages |
+| `im:history` | Read DM messages |
+| `search:read` | Search messages |
+| `chat:write` | Send as user (primary send method) |
+| `files:write` | Upload as user |
+| `reactions:write` | React as user |
+
+### 1.3 Install the App
+
+1. Click **Install to Workspace**
+2. Authorize the requested permissions
+3. Copy both tokens:
+   - **Bot User OAuth Token** (starts with `xoxb-`)
+   - **User OAuth Token** (starts with `xoxp-`)
+
+### 1.4 Configure Environment Variables
+
+Add to `.env`:
+
+```bash
+# User token (xoxp-) — used for sending messages as the agent's user account
+SLACK_USER_TOKEN=xoxp-...
+
+# Bot token (xoxb-) — used for API calls that don't need user identity
+SLACK_BOT_TOKEN=xoxb-...
+
+# Optional: signing secret for Events API webhook verification
+SLACK_SIGNING_SECRET=...
+```
+
+---
+
+## 2. Sending Messages (`slack-send.sh`)
+
+The primary script for all Slack message sending.
+
+### 2.1 Usage
+
+```bash
+# Send to a channel
+./scripts/slack-send.sh "C1234567890" "Hello from the agent"
+
+# Reply in a thread
+./scripts/slack-send.sh "C1234567890" "Thread reply" --thread_ts "1234567890.123456"
+
+# With response dedup (prevents double-replying to the same message)
+./scripts/slack-send.sh "C1234567890" "Reply" --responding_to "1234567890.123456"
+
+# Skip typing indicator
+./scripts/slack-send.sh "C1234567890" "Quick message" --no-typing
+```
+
+### 2.2 Pre-Send Pipeline
+
+Every Slack send goes through this pipeline (in order):
+
+1. **Response dedup** (`slack-responded.sh`): If `--responding_to` is set, acquires an atomic mkdir-based lock to prevent concurrent sessions from replying to the same message
+2. **Typing indicator** (`slack-typing.mjs`): Shows "Agent is typing..." for a duration proportional to message length (1.5s–4s)
+3. **Pre-draft context lookup** (`pre_draft_lookup.py`): Looks up recipient in entity index (advisory, never blocks)
+4. **Factual validation** (`validate-outbound.py`): Checks for relationship claims, AI disclosure, scheduling errors — **blocks if critical issues found**
+5. **Markdown → mrkdwn conversion**: Converts standard Markdown (`**bold**`, `[link](url)`, `## heading`) to Slack's mrkdwn format (`*bold*`, `<url|link>`, `*heading*`)
+6. **Send via `chat.postMessage`**: Uses User OAuth Token
+
+### 2.3 Typing Indicators (`slack-typing.mjs`)
+
+Creates a natural feel by showing typing dots before messages arrive:
+
+- Duration scales with message length: <50 chars → 1.5s, 50-200 → 2.5s, 200-500 → 3s, >500 → 4s
+- Connects via WebSocket RTM API using the user token
+- Requires `rtm:stream` scope (degrades gracefully if missing — message sends without dots)
+- Disable globally: `SLACK_TYPING_ENABLED=0` in `.env`
+
+### 2.4 Response Deduplication (`slack-responded.sh`)
+
+Prevents the agent from sending multiple replies to the same message:
+
+- Uses atomic `mkdir` for race-safe locking (POSIX-guaranteed atomic)
+- Lock path: `state/locks/slack-responded/{channel}/{message_ts}/`
+- After send succeeds, records a preview of the sent message for audit
+- Lock TTL handled by `outbound-dedup-cleanup.sh`
+
+---
+
+## 3. File Uploads (`slack-upload-v2.py`)
+
+Uploads files to Slack channels or threads:
+
+```bash
+python3 scripts/slack-upload-v2.py --channel "C1234567890" --file /path/to/document.pdf --title "Q2 Board Pack"
+
+# Upload to a thread
+python3 scripts/slack-upload-v2.py --channel "C1234567890" --file report.pdf --thread_ts "1234567890.123456"
+```
+
+Uses Slack's v2 file upload API (`files.uploadV2`) which supports larger files and better threading.
+
+---
+
+## 4. Emoji Reactions (`slack-react.mjs`)
+
+Adds emoji reactions to messages:
+
+```bash
+node scripts/slack-react.mjs --channel "C1234567890" --timestamp "1234567890.123456" --emoji "white_check_mark"
+```
+
+Used by the agent to acknowledge messages (e.g. ✅ after processing a request).
+
+---
+
+## 5. Event Polling (`slack-poller.mjs`)
+
+### 5.1 How It Works
+
+The Slack poller runs as part of the main poller loop (every 60 seconds):
+
+1. Reads recent messages from monitored channels and DMs using `conversations.history`
+2. Filters for new messages since last poll (tracks last-seen timestamps)
+3. Writes new messages to `state/inbox/slack/` as YAML files
+4. Inbox processor classifies and routes each message
+
+### 5.2 Monitored Channels
+
+The poller monitors channels configured in the agent's operational setup. Typically:
+- All DM conversations
+- Channels where the agent is mentioned
+- Priority channels (CEO DM, team channels)
+
+### 5.3 Priority Detection
+
+CEO DMs and messages containing urgent keywords trigger immediate processing rather than waiting for the next inbox processor cycle.
+
+---
+
+## 6. Real-Time Events Server (`slack-events-server.mjs`)
+
+### 6.1 Overview
+
+For faster event detection than polling, the events server receives Slack events in real-time:
+
+```bash
+node scripts/slack-events-server.mjs
+```
+
+### 6.2 Control Script
+
+```bash
+# Start the events server
+./scripts/slack-events-ctl.sh start
+
+# Stop it
+./scripts/slack-events-ctl.sh stop
+
+# Check status
+./scripts/slack-events-ctl.sh status
+```
+
+### 6.3 Configuration
+
+Requires the Slack app to have **Event Subscriptions** enabled:
+
+1. Go to Slack App settings → Event Subscriptions → Enable Events
+2. Request URL: `https://your-tunnel-url/slack/events`
+3. Subscribe to events: `message.channels`, `message.groups`, `message.im`, `app_mention`
+4. The events server verifies requests using `SLACK_SIGNING_SECRET`
+
+---
+
+## 7. MCP Slack Send Block
+
+The `block-mcp-slack-send.sh` hook prevents sending via MCP Slack:
+
+```
+BLOCKED: Per CEO directive si-010 — do NOT use MCP Slack for sending.
+Use scripts/slack-send.sh with SLACK_USER_TOKEN instead.
+```
+
+**Why**: MCP Slack sends add a "Sent using @Claude" label to messages, breaking the agent's identity. All sends must go through `slack-send.sh` using the User OAuth Token so messages appear as the agent's Slack user account.
+
+This hook is registered in `.claude/settings.json` as a `PreToolUse` hook matching MCP Slack send tools.
+
+---
+
+## 8. Slack CDP (Chrome DevTools Protocol)
+
+For advanced Slack UI automation (huddle participation, keyboard shortcuts), the Slack desktop app is launched with CDP enabled:
+
+```bash
+./scripts/huddle/launch-slack.sh
+# or manually:
+/Applications/Slack.app/Contents/MacOS/Slack --remote-debugging-port=9222
+```
+
+See [Voice & SMS Setup](voice-sms-setup.md) for the full huddle voice infrastructure that builds on Slack CDP.
+
+---
+
+## 9. Testing
+
+| # | Test | How to Verify |
+|---|---|---|
+| 1 | Token validation | `curl -s -H "Authorization: Bearer $SLACK_USER_TOKEN" https://slack.com/api/auth.test \| jq .` |
+| 2 | Simple send | `./scripts/slack-send.sh "C_TEST_CHANNEL" "Test message"` |
+| 3 | Thread reply | Send with `--thread_ts` and verify it threads in Slack |
+| 4 | Typing indicator | Watch Slack while sending — "Agent is typing..." should appear |
+| 5 | Response dedup | Send same `--responding_to` twice; second should `DEDUP_SKIP` |
+| 6 | File upload | `python3 scripts/slack-upload-v2.py --channel C_TEST --file test.txt` |
+| 7 | Emoji reaction | `node scripts/slack-react.mjs --channel C_TEST --timestamp TS --emoji thumbsup` |
+| 8 | MCP block | Attempt MCP Slack send — should be blocked by hook |
+| 9 | Poller | Send a DM to the agent; check `state/inbox/slack/` |
+| 10 | Markdown conversion | Send message with `**bold**` and `[link](url)` — verify Slack renders correctly |
+
+---
+
+## 10. Troubleshooting
+
+### "invalid_auth" or "token_revoked" errors
+
+1. Regenerate tokens: Slack App → OAuth & Permissions → Reinstall to Workspace
+2. Verify token type: user sends need `xoxp-` token, not `xoxb-`
+3. Update `.env` with new tokens
+
+### Messages appearing as bot (not user)
+
+1. Verify `SLACK_USER_TOKEN` starts with `xoxp-` (not `xoxb-`)
+2. Check `slack-send.sh` is using `SLACK_USER_TOKEN` (line 12)
+3. Verify `block-mcp-slack-send.sh` hook is active in `.claude/settings.json`
+
+### Typing indicator not showing
+
+1. Check `rtm:stream` scope on user token (not available on all Slack plans)
+2. Verify `SLACK_TYPING_ENABLED` is not set to `0`
+3. Check `slack-typing.mjs` can connect: `node scripts/slack-typing.mjs C_TEST 2000`
+4. Degrades gracefully — messages still send without typing dots
+
+### Poller missing messages
+
+1. Verify channel access: agent's Slack account must be a member of monitored channels
+2. Check `conversations.history` scope is granted
+3. Check last-poll timestamp in poller state isn't in the future (clock sync issue)
+
+### Response dedup false positives
+
+1. Check lock directory: `ls state/locks/slack-responded/CHANNEL/`
+2. Clean stale locks: `./scripts/outbound-dedup-cleanup.sh`
+3. Locks should auto-expire — check TTL in `outbound-dedup.sh`
+
+---
+
+## Key Files
+
+| File | Purpose |
+|---|---|
+| `scripts/slack-send.sh` | Primary message sender (user token, typing, dedup, markdown) |
+| `scripts/slack-typing.mjs` | WebSocket RTM typing indicator |
+| `scripts/slack-react.mjs` | Add emoji reactions to messages |
+| `scripts/slack-upload-v2.py` | File upload (v2 API) |
+| `scripts/slack-responded.sh` | Atomic response deduplication |
+| `scripts/slack-events-server.mjs` | Real-time Slack events receiver |
+| `scripts/slack-events-ctl.sh` | Events server control (start/stop/status) |
+| `scripts/poll-slack-events.sh` | Legacy event polling script |
+| `scripts/hooks/block-mcp-slack-send.sh` | Blocks MCP Slack sends (enforces user token) |
+| `scripts/poller/slack-poller.mjs` | Slack channel/DM polling |
+
+---
+
+## Related Documents
+
+- [Voice & SMS Setup](voice-sms-setup.md) — Slack huddle voice via CDP
+- [Outbound Governance Setup](outbound-governance-setup.md) — Dedup and validation pipeline
+- [Poller & Daemon Setup](poller-daemon-setup.md) — How Slack polling integrates with the event loop
+- [Communications Policy](../governance/communications-policy.md) — Voice modes and approval rules for Slack

package/docs/guides/twilio-subaccounts-setup.md

@@ -0,0 +1,223 @@
+# Twilio Sub-Accounts Setup Guide
+
+How to create a dedicated Twilio sub-account for each Maestro agent under a single parent Twilio account. This is required for per-agent WhatsApp segregation because the **Twilio WhatsApp Sandbox webhook is account-wide** — only one URL per Twilio account.
+
+**Prerequisites**: A parent Twilio account already exists (the company's root account). You have its `Account SID` and `Auth Token`.
+
+---
+
+## Why sub-accounts?
+
+Each agent runs as a separate identity (Lucas, Jacob, Sophie, etc.) and needs:
+
+- Its own phone number (for SMS)
+- Its own WhatsApp sandbox webhook URL (the constraint)
+- Its own auth token (so the agent's webhook relay can verify Twilio HMAC signatures independently)
+- Its own usage logs and cost attribution
+
+Sub-accounts give you all of this while still rolling up to the parent account for billing.
+
+| Constraint | Sharing parent account | Per-agent sub-account |
+|---|---|---|
+| WhatsApp sandbox webhook | One URL for ALL agents — only the latest agent's webhook works | Each agent has their own sandbox + webhook |
+| Phone numbers | Mixed across agents on one account | Each agent has their own |
+| Auth Token | Shared — every agent's relay can verify everything (security risk) | Per-agent token, isolated verification |
+| Cost attribution | Aggregated — hard to attribute to a specific agent | Sub-account usage rolls up but is separately reportable |
+| Suspension | Suspending the parent kills all agents | Suspend just the affected agent |
+
+---
+
+## 1. Create the sub-account
+
+Run from the agent's repo (or anywhere with `TWILIO_PARENT_ACCOUNT_SID` and `TWILIO_PARENT_AUTH_TOKEN` set):
+
+```bash
+TWILIO_PARENT_ACCOUNT_SID=AC...         # parent
+TWILIO_PARENT_AUTH_TOKEN=...            # parent
+AGENT_NAME="lucas-ferreira-adaptic"     # whatever friendly name you want
+
+curl -s -u "$TWILIO_PARENT_ACCOUNT_SID:$TWILIO_PARENT_AUTH_TOKEN" -X POST \
+  "https://api.twilio.com/2010-04-01/Accounts.json" \
+  --data-urlencode "FriendlyName=$AGENT_NAME" \
+  | python3 -m json.tool
+```
+
+Capture from the response:
+
+- `sid` — the new sub-account SID (starts with `AC...`)
+- `auth_token` — the sub-account's auth token (use this for HMAC verification on the agent's webhook relay)
+- `owner_account_sid` — confirms it's a child of the parent account
+
+Save both to the agent's `.env`:
+
+```bash
+# Lucas's dedicated Twilio sub-account
+TWILIO_ACCOUNT_SID=ACf2...               # the new sub-account SID
+TWILIO_AUTH_TOKEN=c1da...                # the new sub-account auth token
+
+# Parent account — only used for sub-account management API calls
+TWILIO_PARENT_ACCOUNT_SID=AC36...
+TWILIO_PARENT_AUTH_TOKEN=af86...
+```
+
+---
+
+## 2. Buy a phone number under the sub-account
+
+Search for available numbers:
+
+```bash
+source .env
+curl -s -u "$TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN" \
+  "https://api.twilio.com/2010-04-01/Accounts/$TWILIO_ACCOUNT_SID/AvailablePhoneNumbers/US/Local.json?AreaCode=628&SmsEnabled=true&VoiceEnabled=true&PageSize=5"
+```
+
+Buy one (irreversible — costs ~$1.15/mo + per-message charges):
+
+```bash
+PHONE="+16283454599"
+curl -s -u "$TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN" -X POST \
+  "https://api.twilio.com/2010-04-01/Accounts/$TWILIO_ACCOUNT_SID/IncomingPhoneNumbers.json" \
+  --data-urlencode "PhoneNumber=$PHONE" \
+  --data-urlencode "FriendlyName=Lucas Ferreira - Adaptic"
+```
+
+Save the returned `sid` (starts with `PN...`) to `.env` as `TWILIO_PHONE_SID`.
+
+### Transferring an existing number from the parent
+
+If the agent already has a number under the parent account that you want to move to the sub-account:
+
+```bash
+PARENT_SID="AC36..."          # parent account SID
+PARENT_AUTH="af86..."         # parent account auth token
+PHONE_SID="PN1eb30e..."       # the number to move
+SUBACCOUNT_SID="ACf2..."      # destination sub-account
+
+curl -s -u "$PARENT_SID:$PARENT_AUTH" -X POST \
+  "https://api.twilio.com/2010-04-01/Accounts/$PARENT_SID/IncomingPhoneNumbers/$PHONE_SID.json" \
+  --data-urlencode "AccountSid=$SUBACCOUNT_SID"
+```
+
+The number, all its webhook configuration, and message history move to the sub-account in one API call.
+
+---
+
+## 3. Configure the SMS webhook
+
+After the sub-account owns the number, configure the SMS webhook to point at the agent's Railway webhook relay:
+
+```bash
+source .env
+RELAY_URL="https://${AGENT_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"
+```
+
+---
+
+## 4. Configure the WhatsApp sandbox
+
+This is the whole reason we use sub-accounts. Each sub-account has its own independent WhatsApp sandbox.
+
+**Important**: WhatsApp sandbox webhook configuration is **UI-only** — Twilio does not expose an API for this. You must use Playwright or the user must configure it manually.
+
+1. Log in to the Twilio Console (the sandbox UI uses a different login session than the API)
+2. **Switch to the sub-account** via the account selector top-left (the dropdown shows all sub-accounts under the parent)
+3. Navigate to: `https://console.twilio.com/us1/develop/sms/try-it-out/whatsapp-learn?frameUrl=%2Fconsole%2Fsms%2Fwhatsapp%2Flearn`
+4. Click **Sandbox settings** tab
+5. Set the inbound webhook URL: `https://{firstname}-webhook-relay-production.up.railway.app/whatsapp`
+6. Set the status callback URL: `https://{firstname}-webhook-relay-production.up.railway.app/whatsapp/status`
+7. Set both methods to HTTP POST
+8. Save
+
+Note the **sandbox join code** shown on the page (e.g. `join follow-arm`). Users must send `join {code}` from their WhatsApp to `+1 415 523 8886` to enroll their number for testing with this agent's sandbox.
+
+### Production WhatsApp (post-sandbox)
+
+For production WhatsApp (real WABA business number, not the shared sandbox number), each sub-account can register its own WABA. This requires Facebook Business verification per sub-account — Twilio provides a self-sign-up flow at https://www.twilio.com/docs/whatsapp/self-sign-up. Same pattern: each agent's sub-account → its own WABA → its own webhook URL.
+
+---
+
+## 5. Update the Railway webhook relay
+
+The agent's relay verifies Twilio HMAC signatures using the sub-account's auth token (NOT the parent's). After creating the sub-account, update the Railway env var:
+
+```bash
+source .env
+cd services/webhook-relay
+railway variables --service ${AGENT_FIRSTNAME_LOWER}-webhook-relay \
+  --set "TWILIO_AUTH_TOKEN=$TWILIO_AUTH_TOKEN"
+railway up --service ${AGENT_FIRSTNAME_LOWER}-webhook-relay --detach
+```
+
+Wait until `/health` reports `twilio_signature: true` again.
+
+---
+
+## 6. Add to init-maestro Phase 4
+
+When `/init-maestro` runs Phase 4 Service Configuration, the Twilio step should:
+
+1. Check whether `TWILIO_PARENT_ACCOUNT_SID` is set in `.env` (from a previous agent's setup or org config)
+2. If yes: create a sub-account for this agent via the API (Step 1 above), then bypass the "buy new account" flow
+3. If no: this is the first agent in the org — use `TWILIO_ACCOUNT_SID` as both parent and main, and document that future agents will need sub-accounts under it
+4. Buy a phone number under the sub-account
+5. Configure SMS webhook → Railway
+6. (Manual or Playwright) Configure WhatsApp sandbox → Railway
+
+---
+
+## Verification
+
+```bash
+# 1. Sub-account exists and is active
+source .env
+curl -s -u "$TWILIO_PARENT_ACCOUNT_SID:$TWILIO_PARENT_AUTH_TOKEN" \
+  "https://api.twilio.com/2010-04-01/Accounts/$TWILIO_ACCOUNT_SID.json" \
+  | python3 -m json.tool
+
+# 2. Phone number is owned by the sub-account
+curl -s -u "$TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN" \
+  "https://api.twilio.com/2010-04-01/Accounts/$TWILIO_ACCOUNT_SID/IncomingPhoneNumbers.json"
+
+# 3. SMS webhook points at Railway
+curl -s -u "$TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN" \
+  "https://api.twilio.com/2010-04-01/Accounts/$TWILIO_ACCOUNT_SID/IncomingPhoneNumbers/$TWILIO_PHONE_SID.json" \
+  | python3 -c "import sys,json; d=json.load(sys.stdin); print('SMS URL:', d.get('sms_url'))"
+
+# 4. Send a test SMS using the sub-account credentials
+bash scripts/send-sms.sh --to "+1...your_test_number" --body "Sub-account test from {AgentName}"
+
+# 5. Send a WhatsApp message after joining the sandbox
+bash scripts/send-whatsapp.sh --to "whatsapp:+1...your_number" --body "WhatsApp test from {AgentName}"
+```
+
+---
+
+## Closing / suspending a sub-account
+
+When an agent is decommissioned:
+
+```bash
+source .env
+curl -s -u "$TWILIO_PARENT_ACCOUNT_SID:$TWILIO_PARENT_AUTH_TOKEN" -X POST \
+  "https://api.twilio.com/2010-04-01/Accounts/$TWILIO_ACCOUNT_SID.json" \
+  --data-urlencode "Status=closed"
+```
+
+Closing is irreversible. Use `Status=suspended` for temporary suspension (can be reactivated).
+
+Before closing, decide what to do with the agent's phone number:
+- Transfer back to the parent account (if you want to retain the number for re-use)
+- Release it (Twilio will free up the number, you stop being charged)
+
+---
+
+## Related guides
+
+- [Webhook Relay Setup](webhook-relay-setup.md) — How the Railway relay uses `TWILIO_AUTH_TOKEN` to verify HMAC signatures
+- [Voice & SMS Setup](voice-sms-setup.md) — End-to-end SMS pipeline
+- [WhatsApp Setup](whatsapp-setup.md) — Sandbox vs production WhatsApp