@adaptic/maestro 1.1.8 → 1.5.0

package/docs/guides/claudraband-sessions.md

@@ -0,0 +1,98 @@
+# Claudraband Persistent Sessions Guide
+
+Claudraband wraps Claude Code to add persistent sessions, daemon mode with an HTTP API, and programmatic session control. It turns Claude Code from an interactive TUI into a controllable backend service.
+
+## Why It Matters
+
+Maestro agents spawn background sessions via `scripts/spawn-session.sh` for complex tasks. The current spawner uses `claude -p` with a timeout — fire-and-forget, no resumption, no mid-flight control. Claudraband adds:
+
+- **Persistent sessions**: Run headless, disconnect, reconnect later
+- **Daemon mode**: HTTP API for spawning and managing sessions programmatically
+- **Prompt injection**: Send follow-up prompts to running sessions without restarting
+- **Session lifecycle management**: List, pause, resume, and terminate sessions
+
+This is particularly valuable for the backlog executor pattern, where long-running tasks may need mid-flight adjustments.
+
+## Technical Details
+
+- TypeScript wrapper around Claude Code
+- HTTP API in daemon mode (default port 7842)
+- ACP server for editor integration
+- Exposes a TypeScript library for custom tooling
+- npx-based — zero permanent installation
+
+## Installation
+
+### Via init-agent (recommended)
+
+If you ran `scripts/setup/init-agent.sh`, claudraband is pre-installed globally. Verify:
+
+```bash
+npx @halfwhey/claudraband --version
+```
+
+### Manual
+
+```bash
+# One-shot usage
+npx @halfwhey/claudraband "your prompt here"
+
+# Start daemon
+npx @halfwhey/claudraband serve --port 7842
+```
+
+## Usage Patterns
+
+### Daemon mode (recommended for Maestro)
+
+```bash
+# Start the daemon
+npx @halfwhey/claudraband serve --port 7842
+
+# Create a session
+curl -X POST http://localhost:7842/sessions \
+  -H "Content-Type: application/json" \
+  -d '{"prompt": "Research competitor X and write a brief"}'
+
+# List active sessions
+curl http://localhost:7842/sessions
+
+# Inject a follow-up prompt
+npx @halfwhey/claudraband prompt --session <id> "also check their latest SEC filing"
+
+# Terminate a session
+curl -X DELETE http://localhost:7842/sessions/<id>
+```
+
+### Direct usage (quick tasks)
+
+```bash
+npx @halfwhey/claudraband "Draft an email to the board about Q1 results"
+```
+
+### Integration with spawn-session.sh
+
+`scripts/spawn-session.sh` supports an optional `MAESTRO_SESSION_BACKEND` environment variable:
+
+- `MAESTRO_SESSION_BACKEND=claude` (default) — uses `claude -p` directly
+- `MAESTRO_SESSION_BACKEND=claudraband` — uses claudraband for persistent, resumable sessions
+
+When using the claudraband backend, sessions are registered with the daemon and can be listed, inspected, and controlled via the HTTP API.
+
+## Repository
+
+- GitHub: https://github.com/halfwhey/claudraband
+- License: MIT
+
+## Integration with Maestro
+
+Claudraband is installed as an optional session backend. The default behaviour (`claude -p`) is unchanged. To enable claudraband:
+
+1. Set `MAESTRO_SESSION_BACKEND=claudraband` in your `.env`
+2. Ensure the claudraband daemon is running (started automatically by launchd if configured via init-agent)
+3. Sessions spawned by the backlog executor will use claudraband automatically
+
+Benefits for the backlog executor:
+- **Resumable tasks**: If a session times out, it can be resumed rather than restarted
+- **Mid-flight control**: The orchestrator can inject follow-up prompts into running sessions
+- **Session inventory**: HTTP API provides visibility into all active sessions

package/docs/guides/clawteam-swarm.md

@@ -0,0 +1,116 @@
+# ClawTeam Swarm Orchestration Guide
+
+ClawTeam is a CLI-native swarm orchestrator that uses git worktrees, tmux, and filesystem-based messaging to run multiple coding agents in parallel. It implements a leader/worker pattern where a leader agent manages task creation, dependency chains, spawning, monitoring, and merge.
+
+## Why It Matters
+
+When a coding task involves 2+ independent workstreams (e.g., frontend + backend, or multiple microservices), running agents sequentially is slow and wasteful. ClawTeam gives each agent its own git worktree — isolated branch, files, staging area, and process space — eliminating conflicts, corruption, and dependency collisions.
+
+## Key Capabilities
+
+- **Leader/worker pattern**: Leader agent manages task graph; workers execute independently
+- **Git worktree isolation**: Each worker gets its own worktree branch
+- **Filesystem messaging**: Point-to-point and broadcast messaging between agents
+- **Task dependencies**: Auto-unblocking when upstream tasks complete
+- **Kanban board**: Terminal and web dashboard for monitoring
+- **Multi-agent support**: Claude Code, Codex, Hermes, nanobot, OpenClaw
+
+## Technical Details
+
+- CLI-native and fully automatable (no GUI required)
+- tmux-based worker management
+- MIT licensed
+- Known gaps: task status sync can lag (needs leader-side verification), requires explicit model pinning
+
+## Installation
+
+### Via init-agent
+
+If you ran `scripts/setup/init-agent.sh` with `MAESTRO_ENABLE_SWARM=1`, ClawTeam was cloned and configured. Verify:
+
+```bash
+# Check ClawTeam is available
+which clawteam || ls ~/ClawTeam-OpenClaw/clawteam
+```
+
+### Manual
+
+```bash
+# Clone the repository
+git clone https://github.com/win4r/ClawTeam-OpenClaw.git ~/ClawTeam-OpenClaw
+
+# Ensure tmux is installed
+brew install tmux  # macOS
+```
+
+## Usage
+
+### Basic swarm launch
+
+```bash
+cd ~/your-repo
+clawteam start --leader claude --workers 3 --task "Implement user authentication"
+```
+
+### With task dependencies
+
+```bash
+clawteam start \
+  --leader claude \
+  --task-file tasks.yaml \
+  --workers 4 \
+  --model claude-opus-4-6
+```
+
+### Monitoring
+
+```bash
+# Terminal kanban
+clawteam board
+
+# Web dashboard
+clawteam dashboard --port 8080
+```
+
+### Filesystem messaging
+
+Workers communicate via an inbox system in the worktree root:
+
+```bash
+# Leader sends to worker-2
+echo "Priority change: focus on API endpoints first" > .clawteam/inbox/worker-2/msg-001.txt
+
+# Worker reads inbox
+cat .clawteam/inbox/self/*.txt
+```
+
+## Repository
+
+- GitHub: https://github.com/win4r/ClawTeam-OpenClaw
+- License: MIT
+
+## Integration with Maestro
+
+ClawTeam is an optional module for coding-heavy agents. It is not required for operational agents (Chief of Staff, Legal, Communications) but is valuable for:
+
+- **Engineering coordination agents** running parallel coding tasks
+- **Platform architecture agents** implementing across multiple packages
+- **Any agent** where a backlog item involves 2+ independent code changes
+
+### Routing rules
+
+The backlog executor can route items to ClawTeam when:
+1. The task involves code changes to 2+ independent files/packages
+2. The task is explicitly tagged as `swarm-eligible` in the queue
+3. The agent's config has `MAESTRO_ENABLE_SWARM=1`
+
+### Post-merge workflow
+
+After ClawTeam workers complete, the leader agent:
+1. Reviews all worker diffs
+2. Runs tests on each worktree branch
+3. Merges clean branches to the integration branch
+4. Produces a structured summary of changes
+5. Cleans up worktrees
+
+This maps naturally to Maestro's session output pattern (`outputs/sessions/{id}/output.md`).

package/docs/guides/code-review-graph-setup.md

@@ -0,0 +1,86 @@
+# Code-Review-Graph — Structural Knowledge Graph for Codebases
+
+Tree-sitter-based knowledge graph mapping functions, classes, imports, and call relationships. Provides MCP tools for blast-radius analysis, review context, architecture overview, and refactor planning.
+
+## Why It Matters
+
+When agents review PRs, plan refactors, or assess engineering health, they need structural understanding of the codebase — not just text search. Code-review-graph builds a persistent knowledge graph that auto-updates on file changes, providing:
+
+- **Blast-radius analysis** — What breaks if this function changes?
+- **Review context** — What other code depends on this change?
+- **Architecture overview** — How do modules connect?
+- **Semantic search** — Find related functions by call graph, not just name
+- **Refactor planning** — Map dependencies before restructuring
+
+## Installation
+
+### Via install-dev-tools (recommended)
+
+```bash
+./scripts/setup/install-dev-tools.sh --tool code-review-graph
+```
+
+### Manual
+
+```bash
+# Global install
+npm install -g code-review-graph
+
+# Or via npx (zero-install)
+npx code-review-graph
+```
+
+## MCP Server Configuration
+
+Add to your Claude Code MCP settings (`.claude/settings.json` or project-level):
+
+```json
+{
+  "mcpServers": {
+    "code-review-graph": {
+      "command": "npx",
+      "args": ["code-review-graph", "serve", "--port", "3848"],
+      "env": {
+        "CRG_REPO_PATH": "/path/to/your/repo"
+      }
+    }
+  }
+}
+```
+
+## Usage
+
+### Build the graph for a repo
+
+```bash
+npx code-review-graph index /path/to/repo
+```
+
+### Query via MCP tools (from Claude Code)
+
+Once configured as an MCP server, Claude Code gains these tools:
+- `blast_radius(file, function)` — Trace all callers and dependents
+- `review_context(diff)` — Generate review context from a diff
+- `architecture_overview()` — High-level module map
+- `semantic_search(query)` — Find related code by structural relationships
+
+### Standalone CLI
+
+```bash
+npx code-review-graph blast-radius --file src/lib/executor.js --function executeAction
+npx code-review-graph overview --repo ~/maestro
+```
+
+## Integration with Maestro
+
+Recommended for coding-oriented agents and workflows:
+- **Engineering health checks** — Use architecture overview to assess repo structure
+- **PR review agents** — Enrich review context with dependency information
+- **Refactoring tasks** — Plan changes with blast-radius awareness
+
+Optional for non-coding agents (operational, hiring, comms). Enable per-repo as needed.
+
+## Repository
+
+- License: Open source
+- Requires: Tree-sitter (bundled)

package/docs/guides/self-optimization-pattern.md

@@ -0,0 +1,82 @@
+# Self-Optimization Pattern — AutoAgent-Inspired Framework
+
+Standardized pattern for agents to autonomously improve their own configuration, prompts, tools, and routing via benchmark-driven iteration.
+
+## Origin
+
+Derived from AutoAgent (https://github.com/kevinrgu/autoagent) and Karpathy's autoresearch pattern. Adapted for Maestro's Node.js/Claude Code stack.
+
+## Pattern Overview
+
+```
+1. Define a scoring rubric (what "better" means)
+2. Run the current configuration against test scenarios
+3. Score the results
+4. Propose a modification (prompt tweak, tool change, routing rule)
+5. Run the modification against the same scenarios
+6. Compare scores — keep if better, revert if worse
+7. Log the experiment and repeat
+```
+
+## Implementation in Maestro
+
+### Directory structure
+
+Each agent that uses self-optimization maintains:
+
+```
+self-optimization/
+  program.md          # Current optimization targets and rubrics
+  experiments.jsonl   # Log of all experiments (timestamp, change, before/after scores)
+  scenarios/          # Test scenarios with expected outcomes
+    scenario-001.yaml
+    scenario-002.yaml
+```
+
+### Scoring rubrics
+
+Define rubrics per optimization target:
+
+```yaml
+# self-optimization/program.md
+targets:
+  - name: response-quality
+    metric: llm-as-judge score (1-10)
+    weight: 0.4
+  - name: latency
+    metric: seconds to first response
+    weight: 0.3
+  - name: accuracy
+    metric: factual correctness rate
+    weight: 0.3
+```
+
+### Experiment log format
+
+```jsonl
+{"ts":"2026-04-18T12:00:00Z","target":"response-quality","change":"Added chain-of-thought to classifier prompt","before":6.2,"after":7.8,"kept":true}
+{"ts":"2026-04-18T12:30:00Z","target":"latency","change":"Reduced context window by 40%","before":4.1,"after":2.3,"kept":true}
+```
+
+### When to run
+
+- **Quarterly self-assessment** — Formal optimization cycle
+- **After incidents** — Target the specific failure mode
+- **Self-evolution reflection** — End-of-session check for optimization candidates
+
+### Safety
+
+- All changes are logged to `logs/evolution/`
+- High-risk changes (identity, permissions, external comms rules) require CEO approval
+- Reverts are automatic if score degrades
+- Classification follows `docs/superpowers/specs/2026-04-02-phase0-operational-foundation-design.md`
+
+## Applicability
+
+This pattern is most valuable for:
+- **Classifier prompts** — Improving message routing accuracy
+- **Response templates** — Better quality and tone matching
+- **Tool selection** — More efficient tool use per task type
+- **Queue prioritisation** — Better ranking of actionable items
+
+Not recommended for: identity configuration, compliance rules, security policies (these are fixed, not optimised).

package/docs/guides/slack-setup.md

@@ -1,8 +1,10 @@
 # Slack Setup Guide
 
-How to enable Slack integration for a Maestro agent: app creation, token configuration, message sending (with typing indicators), file uploads, emoji reactions, event polling, real-time events server, and Slack CDP for huddle automation.
+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.
 
-**Prerequisites**: Complete the [Mac Mini Bootstrap](../runbooks/mac-mini-bootstrap.md). The agent needs a Slack workspace account.
+> **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.
 
 ---
 

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