@adaptic/maestro 1.1.7 → 1.4.1

package/.claude/commands/init-maestro.md

@@ -297,7 +297,7 @@ Do NOT modify these sections (keep them exactly as they are, except for agent na
    - product-leader: product roadmap, user research, feature delivery, product-market fit, design system
    - operations-leader: process automation, operational efficiency, fund operations, organisational design, vendor management
 
-### Sub-agent 4: Update package.json and scripts
+### Sub-agent 4: Update package.json, scripts, and identity-baked content
 
 **Instruction to sub-agent:**
 
@@ -307,9 +307,57 @@ Do NOT modify these sections (keep them exactly as they are, except for agent na
    - Variable names like `SOPHIE_AI_DIR` -> `{UPPER_FIRSTNAME}_AI_DIR`
    - Path references like `/Users/sophie/sophie-ai` -> `/Users/{lowercase-firstname}/{repoSlug}`
    - LaunchD labels like `ai.adaptic.sophie-` -> `ai.adaptic.{lowercase-firstname}-`
+   - Pronouns: if the new agent's gender differs from the scaffolding template, update he/she/him/her/his/hers/himself/herself across system prompts, comments, and documentation. Be surgical — do NOT change pronouns inside generic regex patterns or third-party detection logic.
 
 3. **LaunchD plists** in `scripts/local-triggers/plists/` -- Update labels and paths in all `.plist` files.
 
+4. **Identity-baked content rewrites (CRITICAL — full overwrites, not grep-replace).** These files contain the agent's outbound identity (name, title, email, phone, signature) and MUST be fully rewritten with the new agent's values. Do not rely on grep-replace alone — read each file, then OVERWRITE it with content that uses these exact values:
+
+   - `firstName + lastName` (e.g., "Lucas Ferreira")
+   - `title` (e.g., "VP, Regulatory & Licensing")
+   - `email` (e.g., "lucas@adaptic.ai")
+   - `phone` (e.g., "+61 478 964 324" — use the spaced pretty form for human-facing display, the E.164 form for code)
+   - `companyName` (e.g., "Adaptic.ai")
+   - `companyAddress` (use the company's primary office address — typically Adaptic's DIFC office unless explicitly different)
+
+   **Files to rewrite:**
+
+   a. **`scripts/email-signature.html`** — The HTML signature appended to all outbound emails by `send-email.sh` and the Python send scripts. Must contain: name (bold, 14px), title (grey, 13px), Adaptic logo (`https://adaptic.ai/logo.png`), email, phone, company address line, full confidentiality disclaimer footer. Pattern matches the template in `~/maestro/scripts/email-signature.html` — use placeholders {{AGENT_NAME}}, {{AGENT_TITLE}}, {{AGENT_EMAIL}}, {{AGENT_PHONE}}, {{COMPANY_ADDRESS}} and substitute them.
+
+   b. **`scripts/email-signature-mehran.html`** — Principal's signature block (used by `send-email-as-mehran.py` or equivalent send-as-principal scripts). Update with the principal's values: `principal.fullName`, `principal.title`, `principal.email`. If the principal doesn't have a phone in config/agent.ts, omit the phone line.
+
+   c. **`scripts/send-email.sh`** — Hardcoded `From:` header and inline signature fallback. Update both. The From header should be in the form `"Lucas Ferreira" <lucas@adaptic.ai>`.
+
+   d. **`scripts/send-email-threaded.py`** — `USER`, `From` header construction, inline signature, argparse description. All must reflect the new agent.
+
+   e. **`scripts/send-email-with-attachment.py`** — Same as above.
+
+   f. **`scripts/pdf-generation/build-document.mjs`** — Default `author` value (used in PDF metadata) and the help text describing the default. Set to the new agent's full name.
+
+   g. **`scripts/pdf-generation/templates/memo.latex`** — Footer line "Prepared by ... Chief of Staff" — replace with "Prepared by {fullName}, {title}".
+
+   h. **`scripts/daemon/responder.mjs` `FALLBACK_PREAMBLE`** — System prompt that introduces the agent to Claude. Identity intro line must reference the new agent. Preserve the operational rules.
+
+   i. **`scripts/daemon/prompt-builder.mjs` `FALLBACK_PREAMBLE`** — Same treatment.
+
+   j. **`scripts/daemon/classifier.mjs` `SYSTEM_PROMPT`** — Identity intro line. Preserve everything else.
+
+   k. **`scripts/huddle/huddle-server.mjs` `HUDDLE_SYSTEM_PROMPT`** — Voice agent identity line.
+
+   l. **`scripts/spawn-session.sh`** — Sub-session bootstrap prompt that names the agent.
+
+   m. **`scripts/continuous-monitor.sh`** — Channel monitor agent prompt.
+
+   n. **`scripts/llm_email_dedup.py`, `scripts/comms-monitor.sh`, `scripts/archive-email.sh`, `scripts/poller/gmail-poller.mjs`, `scripts/poller/imap-client.mjs`** — Hardcoded `LUCAS_EMAIL`/`USER`/`gmail_user` constants. Set to the new agent's email.
+
+   o. **`scripts/{firstname}-inbox-poller.py`** — Rename file from `sophie-inbox-poller.py` (or current scaffolding name) to `{firstname}-inbox-poller.py`. Update internal `LUCAS_EMAIL` constant. Update any plist references to the new filename.
+
+   p. **`scripts/rag-indexer.py`, `scripts/user-context-search.py`** — Author docstring at the top. Set to the new agent's full name.
+
+   q. **`scripts/validate-outbound.py`** — Three test/regex references to "Sophie Nguyen" or `lookup_entity("Sophie Nguyen")`. Replace with the new agent's full name. Leave the generic third-party pronoun regex (around line 1007) UNCHANGED — it's a detector, not an identity reference.
+
+   **Verification step**: After rewrites, run `grep -rn "sophie@adaptic\|Sophie Nguyen\|Chief of Staff" scripts/ docs/business-synthesis/executive-operating-model.md 2>&1` and confirm only intentional peer references remain (Sophie Nguyen as a real Chief of Staff peer, NOT as the agent's own outbound identity). Report any remaining matches you couldn't safely auto-resolve so the main agent can decide.
+
 ### Sub-agent 5: Update agent definitions
 
 **Instruction to sub-agent:**
@@ -436,359 +484,556 @@ If yes, run:
 sudo ./scripts/setup/configure-macos.sh
 ```
 
-## Phase 4: Third-Party Service Configuration
+### Step 4: External SSD configuration (REQUIRED if /Volumes/{name}-SSD is mounted)
 
-Guide the user through setting up external integrations. Present this as a checklist — some steps can be automated, others require manual action.
+The maestro daemon and its launchd-spawned trigger jobs should write all runtime data — Claude Code per-cwd temp dirs, daemon logs, state, outputs, memory, knowledge — to an external SSD when one is available. This keeps the internal disk free for macOS and avoids wear on the system disk.
 
-### Classification of Setup Steps
+**Two macOS hurdles need to be cleared before the SSD redirect actually works for launchd-spawned processes:**
 
-**Automated (the wizard does it):**
-- Twilio WhatsApp sandbox configuration (if TWILIO_ACCOUNT_SID is in .env)
-- Cloudflare tunnel creation (via `cloudflared` CLI if installed)
-- ElevenLabs voice clone setup (via API if ELEVENLABS_API_KEY is in .env)
-- Railway service deployment (via `railway` CLI if installed)
+#### 4a. Enable file ownership on the volume
 
-**Guided (requires human action, wizard walks them through):**
-- Slack app creation and token generation
-- Gmail app password generation
-- Twilio phone number purchase
-- Parsec account login (first time only)
+By default, external volumes have Owners disabled, which makes file permissions advisory rather than enforced. The daemon's wrapper writes per-agent log files, and that requires real owners.
 
-### Step 1: Slack App Setup
+Detect the SSD and enable owners:
+
+```bash
+SSD_VOLUME=""
+for v in /Volumes/*-SSD /Volumes/*SSD* /Volumes/maestro-data; do
+  if [ -d "$v" ] && [ "$v" != "/Volumes/Macintosh HD" ]; then SSD_VOLUME="$v"; break; fi
+done
 
+if [ -n "$SSD_VOLUME" ]; then
+  # Tell the user we found an SSD and need sudo to enable owners
+  echo "Found external SSD at $SSD_VOLUME — enabling file ownership."
+  echo "Please run this in your terminal (it needs sudo):"
+  echo "  sudo diskutil enableOwnership \"$SSD_VOLUME\""
+  echo "Reply 'done' when complete."
+fi
 ```
-Let's set up Slack integration.
 
-IMPORTANT: You can reuse an existing Slack app across multiple agents in the
-same workspace. Each agent needs its own bot token and user token, but they
-can share the same app configuration.
+Wait for the user to confirm. Then verify:
 
-If you already have a Maestro Slack app configured:
-  → Just paste the bot token (xoxb-...) and user token (xoxp-...) below.
+```bash
+diskutil info "$SSD_VOLUME" | grep "Owners" | grep -q "Enabled" && echo "OK" || echo "FAIL"
+```
+
+#### 4b. Grant Full Disk Access to bash and node (TCC)
 
-If you need to create a new Slack app:
-  1. Go to https://api.slack.com/apps → "Create New App" → "From scratch"
-  2. Name it "Maestro - {AgentFirstName}" (or reuse existing "Maestro" app)
-  3. Under "OAuth & Permissions", add these BOT scopes:
-     - chat:write, chat:write.customize
-     - channels:read, channels:history
-     - groups:read, groups:history
-     - im:read, im:history, im:write
-     - users:read, users:read.email
-     - reactions:read, reactions:write
-     - files:read, files:write
-  4. Add these USER scopes:
-     - channels:history, groups:history, im:history
-     - search:read
-  5. Install the app to your workspace
-  6. Copy the Bot User OAuth Token (xoxb-...)
-  7. Copy the User OAuth Token (xoxp-...)
-  
-  For Slack Events API (real-time messages instead of polling):
-  8. Under "Event Subscriptions", enable events
-  9. Set Request URL to your Cloudflare tunnel URL + /slack/events
-  10. Subscribe to bot events: message.channels, message.groups, message.im,
-      app_mention, reaction_added
-  11. Copy the Signing Secret from "Basic Information"
+Even with owners enabled, **macOS TCC blocks launchd-spawned processes from writing to /Volumes/ unless the binary has Full Disk Access**. This is the single most common cause of "Operation not permitted" errors when you run a daemon under launchd that tries to write to an external volume.
+
+You cannot grant Full Disk Access programmatically without disabling SIP (which is unsafe). The user must do this via System Settings UI:
+
+```
+1. Open System Settings → Privacy & Security → Full Disk Access
+2. Click the + button
+3. Press Cmd+Shift+G to "Go to Folder", then enter:
+     /bin/bash
+   Press Enter, select 'bash', click Open
+4. Click + again, then:
+     /usr/bin/node     OR     ~/.nvm/versions/node/v24.11.1/bin/node
+   (whichever node binary the wrapper uses)
+5. Make sure both toggles are ON
 
-Paste your tokens when ready (or type "skip" to configure later):
-  Bot token (xoxb-...):
-  User token (xoxp-...):
-  Signing secret (optional):
+The toggles take effect immediately. No restart needed.
 ```
 
-Write the tokens to `.env` using the Edit tool.
+After the user confirms, test that launchd can now write to the SSD:
 
-**Answer to Slack app reusability question:** A single Slack app CAN serve multiple agents in the same workspace. The app defines scopes and event subscriptions; each workspace installation generates unique bot/user tokens. However, if you want separate bot identities (different names/avatars per agent), create one app per agent. The Event Subscriptions URL can only point to one server per app, so if multiple agents need real-time events, either use separate apps or a shared event router.
+```bash
+cat > /tmp/ssd-tcc-test.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.ssd-tcc-test</string>
+    <key>ProgramArguments</key><array>
+        <string>/bin/bash</string><string>-c</string>
+        <string>touch "$SSD_VOLUME/.tcc-test" && echo "ok=$?" > /tmp/ssd-tcc-result.log || echo "fail=$?" > /tmp/ssd-tcc-result.log</string>
+    </array>
+    <key>RunAtLoad</key><true/>
+</dict>
+</plist>
+EOF
+launchctl load /tmp/ssd-tcc-test.plist
+sleep 2
+cat /tmp/ssd-tcc-result.log
+launchctl unload /tmp/ssd-tcc-test.plist
+rm -f "$SSD_VOLUME/.tcc-test"
+```
+
+If you see `ok=0`, TCC is configured correctly and the daemon can use the SSD. If you see `fail=1`, TCC is still blocking — repeat the System Settings step and make sure the toggles are ON.
+
+#### 4c. Set up SSD layout and symlinks
 
-### Step 2: Gmail Setup
+```bash
+AGENT_NAME="$(grep firstName config/agent.ts | head -1 | sed 's/.*[\x27\"]\([a-zA-Z]*\)[\x27\"].*/\1/' | tr A-Z a-z)"
+SSD_AGENT_ROOT="$SSD_VOLUME/maestro/$AGENT_NAME"
+mkdir -p "$SSD_AGENT_ROOT"/{state,outputs,memory,knowledge,claude-tmp,logs,tmp}
+
+# Symlink runtime data dirs from the agent repo to the SSD.
+# IMPORTANT: do NOT symlink logs/ — launchd's StandardErrorPath cannot follow
+# symlinks to external volumes. The daemon's wrapper writes its own log file
+# directly to the SSD via shell redirection (see launchd-wrapper.sh).
+for d in state outputs memory knowledge; do
+  if [ -d "$d" ] && [ ! -L "$d" ]; then
+    rsync -a "$d/" "$SSD_AGENT_ROOT/$d/"
+    rm -rf "$d"
+    ln -sfn "$SSD_AGENT_ROOT/$d" "$d"
+  fi
+done
 
+# Create internal-disk logs/ as a real directory (NOT a symlink)
+mkdir -p logs/{daemon,polling,workflows,sessions,audit,security,evolution,huddle,infra,monitor,phone,sms,whatsapp,email,launchd,cloudflared}
 ```
-Let's set up Gmail.
 
-Each agent needs its own Gmail account and app password.
-(The poller connects via IMAP — not OAuth — so app passwords are simpler.)
+The wrapper scripts (`scripts/daemon/launchd-wrapper.sh` and `launchd-wrapper-generic.sh`) handle the runtime side: they detect the SSD, set `CLAUDE_CODE_TMPDIR`, and redirect daemon stdout/stderr to a log file on the SSD. They gracefully fall back to internal-disk paths if the SSD isn't writable (e.g. if TCC isn't granted yet).
 
-  1. Log into the agent's Google account ({agent.email})
-  2. Enable 2-Factor Authentication if not already enabled
-  3. Go to https://myaccount.google.com/apppasswords
-  4. Generate an app password for "Mail" on "Mac"
-  5. Copy the 16-character password (no spaces)
+#### 4d. Verify
 
-Paste the Gmail app password:
+```bash
+# Daemon should now be writing to the SSD log file
+launchctl unload ~/Library/LaunchAgents/ai.adaptic.${AGENT_NAME}-daemon.plist
+launchctl load   ~/Library/LaunchAgents/ai.adaptic.${AGENT_NAME}-daemon.plist
+sleep 4
+ls -la "$SSD_AGENT_ROOT/logs/daemon/" | tail -5
+ls -la "$SSD_AGENT_ROOT/state/inbox/" | tail -5
 ```
 
-Write to `.env` as `GMAIL_APP_PASSWORD`.
+You should see the daemon log file growing and inbox directories populating. If you don't, repeat steps 4a–4b (most often it's TCC).
 
-If the agent also monitors the principal's inbox:
-```
-Does {principalName} want this agent to monitor their inbox too?
-If yes, generate an app password for {principalEmail} using the same steps above.
+## Phase 4: Autonomous Service Configuration
 
-Paste the secondary Gmail app password (or "skip"):
-```
+This phase sets up all third-party integrations **autonomously**. Use Playwright MCP for web-based setup (Slack API portal, Twilio Console, Google Account, ElevenLabs, Deepgram) and Bash for local scripts. Only ask the user for input when genuinely required (existing credentials, 2FA codes, payment authorisation).
 
-Write to `.env` as `SECONDARY_GMAIL_APP_PASSWORD`.
+**Tooling:**
+- **Playwright MCP** (`mcp__plugin_playwright_playwright__browser_navigate`, `browser_click`, `browser_fill_form`, `browser_snapshot`, etc.) for all web UI interactions
+- **Bash** for local scripts, CLI tools, file writes, service starts
+- If a web UI requires authentication the agent doesn't have, ask the user to log in via `! open <url>` then resume automation once they confirm they're logged in
 
-### Step 3: Twilio Setup (Optional)
+**Implementation guides**: Each service has a detailed guide in `docs/guides/`. Follow the guide's steps exactly during setup. Reference the guide's troubleshooting section if something fails.
 
-```
-Does this agent need phone/SMS/WhatsApp capabilities? (yes/no)
-```
+### Step 0: Ask what services this agent needs
 
-If yes:
 ```
-Twilio setup:
-  1. Sign up at https://www.twilio.com/ (or use existing account)
-  2. From the Console dashboard, copy:
-     - Account SID (starts with AC...)
-     - Auth Token
-  3. Buy a phone number: Console → Phone Numbers → Buy a Number
-     - Select a number with SMS + Voice capabilities
-     - Copy the phone number (E.164 format, e.g., +15551234567)
-     - Copy the Phone SID (starts with PN...)
+Which services does this agent need? Select all that apply:
 
-Paste your Twilio credentials:
-  Account SID:
-  Auth Token:
-  Phone Number:
-  Phone SID:
-```
+  [1] Slack (messaging, events, typing indicators)
+  [2] Gmail (email send/receive via IMAP/SMTP)
+  [3] Twilio SMS (inbound/outbound text messaging)
+  [4] Twilio WhatsApp (inbound/outbound WhatsApp)
+  [5] Voice / Huddle (Deepgram STT + ElevenLabs TTS)
+  [6] Cloudflare Tunnels (public webhook URLs — needed if 3/4/5 selected)
+  [7] Gemini / Veo (AI image + video generation)
+  [8] All of the above
+  [9] Minimal (Slack + Gmail only)
 
-Write all to `.env`. Then offer to auto-configure:
-```
-Would you like me to configure the Twilio WhatsApp sandbox automatically? (yes/no)
+Which? (comma-separated numbers, or "all" / "minimal")
 ```
 
-If yes, run: `bash scripts/configure-whatsapp-sandbox.sh`
+Then execute each selected service. For services with existing credentials, ask the user to paste them. For new accounts, drive the web UI via Playwright.
+
+### Step 1: Slack — per `docs/guides/slack-setup.md`
+
+**If user has existing tokens:** ask for xoxb- and xoxp- tokens, write to `.env`.
+
+**If creating new app — execute via Playwright:**
+
+1. `browser_navigate` to `https://api.slack.com/apps`
+2. `browser_snapshot` to check auth — if not logged in, ask user: `! open https://api.slack.com/apps` and log in, then resume
+3. Click "Create New App" → "From scratch"
+4. `browser_fill_form` with app name "Maestro - {AgentFirstName}", select workspace
+5. Navigate to OAuth & Permissions
+6. Add Bot Token Scopes: `chat:write`, `chat:write.customize`, `channels:read`, `channels:history`, `groups:read`, `groups:history`, `im:read`, `im:history`, `im:write`, `users:read`, `users:read.email`, `reactions:read`, `reactions:write`, `files:read`, `files:write`
+7. Add User Token Scopes: `channels:history`, `groups:history`, `im:history`, `search:read`, `chat:write`
+8. Click "Install to Workspace" → authorize
+9. Extract Bot User OAuth Token (xoxb-...) and User OAuth Token (xoxp-...) from the page
+10. Navigate to Basic Information → extract Signing Secret
+11. Write `SLACK_BOT_TOKEN`, `SLACK_USER_TOKEN`, `SLACK_SIGNING_SECRET` to `.env`
+
+**Verify:**
+```bash
+source .env && curl -s -H "Authorization: Bearer $SLACK_USER_TOKEN" https://slack.com/api/auth.test | python3 -c "import json,sys; d=json.load(sys.stdin); print('Slack OK: ' + d.get('user','') if d.get('ok') else 'FAIL: ' + d.get('error',''))"
+```
 
-### Step 4: Cloudflare Tunnel (Optional)
+### Step 2: Gmail — per `docs/guides/email-setup.md`
 
+Gmail app passwords require 2FA interaction — ask user:
 ```
-Does this agent need a public URL for webhooks? (yes/no)
-(Required for: Slack Events API, Twilio voice callbacks, WhatsApp webhooks)
+Gmail setup: Please generate an app password:
+  1. Go to https://myaccount.google.com/apppasswords (or I can open it for you)
+  2. Generate a password for "Mail" on "Mac"
+  3. Paste the 16-character password here:
 ```
 
-If yes:
+After receiving the password:
+1. Write `GMAIL_APP_PASSWORD` to `.env`
+2. If monitoring principal's inbox, ask for secondary password → `SECONDARY_GMAIL_APP_PASSWORD`
+3. Install msmtp: `brew install msmtp 2>/dev/null || true`
+4. Write `~/.msmtprc` per guide § 1.4, set `chmod 600 ~/.msmtprc`
+
+**Verify:**
+```bash
+source .env && python3 -c "import imaplib,os; m=imaplib.IMAP4_SSL('imap.gmail.com'); m.login('${AGENT_EMAIL}', os.environ['GMAIL_APP_PASSWORD']); print('IMAP OK'); m.logout()"
 ```
-Cloudflare tunnel options:
 
-  1. Quick tunnel (free, URL changes on restart):
-     cloudflared tunnel --url http://localhost:3100
+### Step 3: Twilio (SMS + WhatsApp) — per `docs/guides/voice-sms-setup.md`, `docs/guides/whatsapp-setup.md`
 
-  2. Named tunnel (free, persistent URL — recommended):
-     cloudflared tunnel create {agent-name}
-     cloudflared tunnel route dns {agent-name} {agent-name}.yourdomain.com
+**If user has credentials:** ask for Account SID, Auth Token, Phone Number → write to `.env`.
 
-  3. Skip (configure manually later)
+**If creating new account — execute via Playwright:**
 
-Which option? (1/2/3)
-```
+1. `browser_navigate` to `https://www.twilio.com/console`
+2. `browser_snapshot` — if not logged in, ask user to log in via `! open https://www.twilio.com/login`
+3. Once authenticated, extract Account SID and Auth Token from Console dashboard
+4. Navigate to Phone Numbers → Buy a Number → search for SMS+Voice number in preferred country
+5. **Ask user to confirm the purchase** (payment authorisation)
+6. After purchase, extract phone number (E.164) and Phone SID
+7. Write `TWILIO_ACCOUNT_SID`, `TWILIO_AUTH_TOKEN`, `TWILIO_PHONE_NUMBER`, `TWILIO_PHONE_SID` to `.env`
 
-For option 1, run `cloudflared tunnel --url http://localhost:3100` and capture the URL.
-For option 2, guide through the DNS setup steps.
+**If SMS selected:** Configure webhook per guide:
+1. Navigate to Twilio Console → Phone Numbers → Active Numbers → select number
+2. Under Messaging → "A message comes in" → Webhook POST → `{tunnel_url}/sms`
+3. Enable geo-permissions: navigate to Messaging → Settings → Geo Permissions → enable needed countries
 
-### Step 5: Voice Integration (Optional)
+**If WhatsApp selected:** Configure sandbox per guide:
+1. `browser_navigate` to `https://console.twilio.com/us1/develop/sms/try-it-out/whatsapp-learn`
+2. Under Sandbox Settings → set webhook URL to `{tunnel_url}/whatsapp` POST
+3. Set Status Callback to `{tunnel_url}/whatsapp/status` POST
+4. Note and report the sandbox join keyword to the user
+5. Write `WHATSAPP_MODE=sandbox`, `WHATSAPP_PORT=3002` to `.env`
 
-```
-Does this agent need voice capabilities (phone calls, huddle participation)? (yes/no)
+### Step 4: Webhook Relay (Railway) — per `docs/guides/webhook-relay-setup.md`
+
+**This is the canonical pattern. Do NOT use Cloudflare Tunnels for new agents** — they were a transitional approach. Each agent gets its own Railway-deployed webhook relay. The local Mac mini polls the relay every 5 seconds and never needs an inbound tunnel.
+
+The relay handles:
+- `POST /slack/events` — Slack Events API (HMAC verified via SLACK_SIGNING_SECRET)
+- `POST /sms` — Twilio SMS inbound (HMAC verified via TWILIO_AUTH_TOKEN)
+- `POST /whatsapp` — Twilio WhatsApp inbound
+- `POST /whatsapp/status` — Twilio WhatsApp delivery status
+- `GET /events`, `/sms/messages`, `/whatsapp/messages` — drained by Mac mini poller
+- `GET /health` — service status
+
+**Source code** is already in the repo at `services/webhook-relay/` (copied from the maestro framework). It's a ~250-line Node 20 HTTP server, no dependencies, deployable straight to Railway.
+
+**Prerequisites:**
+- Railway CLI installed: `brew install railway 2>/dev/null || true`
+- User must run `railway login` once (interactive — opens browser)
+- User must have admin rights in the company's Railway workspace (e.g., "Adaptic")
+
+**Deploy steps (run from the agent's repo root):**
+
+```bash
+# 1. Create the project in the company's Railway workspace
+cd services/webhook-relay
+railway init --name {firstname-lower}-webhook-relay --workspace {Company}
+
+# 2. Add the service and deploy
+railway up --service {firstname-lower}-webhook-relay --detach
+
+# 3. Generate a public domain
+railway domain --service {firstname-lower}-webhook-relay
+# Captures: https://{firstname-lower}-webhook-relay-production.up.railway.app
+
+# 4. Set env vars (must include the agent's own SLACK_SIGNING_SECRET and TWILIO_AUTH_TOKEN)
+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"
+
+# 5. Trigger redeploy so the running container picks up the new env vars
+railway up --service {firstname-lower}-webhook-relay --detach
+
+# 6. Wait until /health returns slack_signature: true and twilio_signature: true
+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
 ```
 
-If yes:
+**Configure external services to point at the relay:**
+
+```bash
+# Twilio SMS webhook (uses Twilio API directly, no UI)
+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"
 ```
-Voice setup requires:
-  1. ElevenLabs API key (for text-to-speech)
-     → Sign up at https://elevenlabs.io/
-     → Copy your API key from Profile → API Keys
-  
-  2. Deepgram API key (for speech-to-text)
-     → Sign up at https://deepgram.com/
-     → Copy your API key from Console → API Keys
 
-  3. BlackHole virtual audio (for huddle participation)
-     → This will be installed by the audio setup script
+For **Slack Events Subscription**: use Playwright to update via the App Manifest editor (more reliable than the events page). Navigate to `https://app.slack.com/app-settings/{TEAM_ID}/{APP_ID}/app-manifest`, read the JSON via the CodeMirror instance, add this block to `settings`, and click Save Changes:
 
-Paste API keys:
-  ElevenLabs API key:
-  Deepgram API key:
+```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"
+  ]
+}
 ```
 
-Write to `.env`. Then run: `bash scripts/huddle/setup-audio.sh`
+After save, navigate to the Event Subscriptions page and check for the yellow "Click here to verify" button — click it. Then **reinstall the app** at `https://api.slack.com/apps/{APP_ID}/install-on-team` so the new event scopes activate.
+
+For **Twilio WhatsApp sandbox**: this requires a per-agent Twilio sub-account (see Phase 4 Step 3.5). Cannot share with other agents because the sandbox webhook is account-wide.
 
-### Step 6: Additional Services (Optional)
+**Update local poll script:**
 
+```bash
+# Edit scripts/poll-slack-events.sh and scripts/comms-monitor.sh
+# Set EVENTS_URL to https://{firstname-lower}-webhook-relay-production.up.railway.app/events
 ```
-Any additional services to configure?
-  1. OpenAI API key (supplemental model access)
-  2. Gemini API key (media generation)
-  3. Greptile API key (code search)
-  4. Done — skip remaining
 
-Which? (comma-separated numbers, or "done")
+**Install the launchd job that polls the relay every 5 seconds:**
+
+```bash
+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
+```
+
+**Add the relay URL block to `.env`:**
+
+```bash
+cat >> .env <<EOF
+
+# ─── RAILWAY WEBHOOK RELAY ──────────────────────────────────────────────────
+WEBHOOK_RELAY_URL=https://{firstname-lower}-webhook-relay-production.up.railway.app
+WEBHOOK_RELAY_SLACK_EVENTS=https://{firstname-lower}-webhook-relay-production.up.railway.app/slack/events
+WEBHOOK_RELAY_SMS_INBOUND=https://{firstname-lower}-webhook-relay-production.up.railway.app/sms
+WEBHOOK_RELAY_WHATSAPP_INBOUND=https://{firstname-lower}-webhook-relay-production.up.railway.app/whatsapp
+WEBHOOK_RELAY_POLL_EVENTS=https://{firstname-lower}-webhook-relay-production.up.railway.app/events
+WEBHOOK_RELAY_POLL_SMS=https://{firstname-lower}-webhook-relay-production.up.railway.app/sms/messages
+WEBHOOK_RELAY_POLL_WHATSAPP=https://{firstname-lower}-webhook-relay-production.up.railway.app/whatsapp/messages
+EOF
 ```
 
-For each, prompt for the API key and write to `.env`.
+**End-to-end test:**
 
-### Step 7: Service Verification
+1. Have Lucas (or any user) send a Slack message to a channel where the bot is a member, OR @-mention the bot in a public channel
+2. Within ~5 seconds, the local Mac mini should fetch the buffered event and write a YAML file to `state/inbox/slack/`
+3. The inbox processor picks it up and routes it
+4. Verify `railway logs --service {firstname-lower}-webhook-relay` shows `[slack] buffered ...`
 
-After all services are configured, run verification:
+### Step 5: Voice / Huddle — per `docs/guides/voice-sms-setup.md` § 5
 
+**API keys** — if user has them, paste directly. Otherwise, drive signup via Playwright:
+
+1. **ElevenLabs**: `browser_navigate` to `https://elevenlabs.io/` → sign up or log in → navigate to Profile → API Keys → extract key
+2. **Deepgram**: `browser_navigate` to `https://console.deepgram.com/` → sign up or log in → navigate to API Keys → create and extract key
+3. Write `ELEVENLABS_API_KEY`, `DEEPGRAM_API_KEY` to `.env`
+
+**Local setup:**
 ```bash
-npm run healthcheck
+bash scripts/huddle/setup-audio.sh          # Install BlackHole, sox, verify
+cd scripts/huddle && npm install && cd ../.. # Install huddle Node.js deps
+bash scripts/huddle/launch-slack.sh          # Launch Slack with CDP
 ```
 
-Report the results and flag any services that aren't configured.
+### Step 6: Media Generation — per `docs/guides/media-generation-setup.md`
 
-## Phase 5: Generate Agent README
+1. If user has Gemini key, paste directly. Otherwise: `browser_navigate` to `https://aistudio.google.com/apikey` → extract or create key
+2. Write `GEMINI_API_KEY` to `.env`
 
-Generate a comprehensive README.md for this agent's repository. This is NOT the Maestro framework README — it describes THIS specific agent.
+### Step 7: Additional Keys
 
-**Template structure:**
+Prompt for any remaining optional keys: `OPENAI_API_KEY`, `GREPTILE_API_KEY`. Write to `.env` or skip.
 
-```markdown
-# {repoName}
+## Phase 5: Subsystem Implementation & Verification
 
-**{fullName} — Autonomous {title} for {company}**
+After credentials are configured, this phase **autonomously implements and verifies** every subsystem by following each implementation guide's setup and test steps. This ensures the agent is actually operational — not just configured with API keys.
 
-Powered by [@adaptic/maestro](https://github.com/adapticai/maestro)
+**Execution:** Spawn parallel background agents for independent subsystems. Report results as a verification matrix. Do NOT proceed to Phase 6 until all selected subsystems pass (or user explicitly accepts failures).
 
----
-
-## Who is {firstName}?
+Tell the user:
+```
+Credentials configured. Now I'll set up and verify each subsystem end-to-end.
+This runs autonomously — I'll report results when complete.
+```
 
-{firstName} {lastName} is an autonomous AI agent operating as {title} at {company}.
-{companyDescription}. {firstName} runs 24/7 on a dedicated Mac mini ({machineName}),
-using Claude Code as the reasoning engine and orchestrating 30+ specialist sub-agents.
+### 5.1 Outbound Governance — `docs/guides/outbound-governance-setup.md`
 
-{firstName} reports to {principalFullName} ({principalTitle}) and operates with
-{describe autonomy level based on archetype}.
+Verify FIRST — all send scripts depend on this.
 
-## Capabilities
+1. Verify hooks registered in `.claude/settings.json` (PreToolUse for block-mcp-slack-send and pre-send-audit, PostToolUse for post-action-log, Stop for session-end-log)
+2. `chmod +x scripts/hooks/*.sh`
+3. Test dedup: generate key → acquire → verify CLAIMED → cleanup
+4. Test validate-outbound.py runs without crash
+5. Test disclosure_assessment.py runs without crash
 
-{Generate 8-12 bullet points based on the archetype and responsibilities.
-For executive-operator: comms management, briefs, hiring, strategic execution, etc.
-For technical-leader: code review, architecture decisions, engineering health, etc.
-For compliance-officer: regulatory tracking, filing management, audit readiness, etc.
-Tailor to the specific responsibilities gathered in Phase 1.}
+### 5.2 Email — `docs/guides/email-setup.md`
 
-## Architecture
+1. Test IMAP connectivity (if GMAIL_APP_PASSWORD set)
+2. Verify msmtp config exists: `test -f ~/.msmtprc`
+3. Verify email signature files: `test -f scripts/email-signature.html`
+4. `chmod +x scripts/send-email.sh`
 
-Built on the Maestro 5-tier agent architecture:
+### 5.3 Slack — `docs/guides/slack-setup.md`
 
-- **Tier 0**: {firstName} (Executive Cortex) — core identity and reasoning
-- **Tier 1**: {Generate 4-5 domain controllers relevant to the archetype}
-- **Tier 2**: 31 specialist sub-agents
-- **Tier 3**: Slack, Gmail, WhatsApp, Browser, Calendar
-- **Tier 4**: Decision Log, Risk Register, Knowledge Base
+1. Test token: `curl -s -H "Authorization: Bearer $SLACK_USER_TOKEN" https://slack.com/api/auth.test`
+2. Verify slack-send.sh uses xoxp- token (not xoxb-)
+3. Verify typing indicator exists: `test -f scripts/slack-typing.mjs`
+4. Verify MCP block hook: `test -f scripts/hooks/block-mcp-slack-send.sh`
 
-## Powered by Maestro
+### 5.4 SMS & WhatsApp — `docs/guides/voice-sms-setup.md`, `docs/guides/whatsapp-setup.md`
 
-This repo is an agent instance powered by the [@adaptic/maestro](https://www.npmjs.com/package/@adaptic/maestro) framework.
+1. Verify `config/caller-id-map.yaml` exists and has principal with `access_level: ceo`
+2. Start SMS handler, verify health: `curl http://localhost:3001/health`
+3. Start WhatsApp handler, verify health: `curl http://localhost:3002/health`
+4. `chmod +x scripts/send-sms.sh scripts/send-whatsapp.sh`
 
-Update framework:   npm update @adaptic/maestro && npm run upgrade
-Health check:       npm run healthcheck
-Emergency stop:     npm run emergency-stop
+### 5.5 Voice / Huddle — `docs/guides/voice-sms-setup.md` § 5
 
-## Operating Modes
+1. `bash scripts/huddle/setup-audio.sh --check`
+2. Verify huddle deps: `test -d scripts/huddle/node_modules`
+3. Verify Deepgram + ElevenLabs keys are set
 
-- **Reactive**: Polls Slack/Gmail/Calendar every 60s, classifies and dispatches
-- **Scheduled**: {morningBrief time} brief, midday sweep, {eveningWrap time} wrap, weekly cycles
-- **Proactive**: Backlog executor every 10 min, parallel agent execution
+### 5.6 Poller & Daemon — `docs/guides/poller-daemon-setup.md`
 
-## Commands
+1. Run poller once: `timeout 30 node scripts/poller/index.mjs`
+2. Verify daemon entry point: `head -5 scripts/daemon/maestro-daemon.mjs`
+3. Verify plists generated: `ls scripts/local-triggers/plists/*.plist | wc -l`
+4. Test emergency stop: `touch .emergency-stop` → run trigger → verify blocked → `rm .emergency-stop`
+5. Verify watchdog: `bash scripts/watchdog/memory-watchdog.sh --check`
 
-| Command | Purpose |
-|---------|---------|
-| npm run daemon | Start the main orchestrator |
-| npm run healthcheck | Verify all subsystems |
-| npm run emergency-stop | Halt all operations |
-| npm run resume | Resume after emergency stop |
-| npm run upgrade | Pull latest Maestro framework |
-| claude "/init-maestro" | Reconfigure agent identity |
+### 5.7 RAG & Context — `docs/guides/rag-context-setup.md`
 
-## Communication Governance
+1. Build search index: `python3 scripts/rag-indexer.py --full`
+2. Verify docs indexed: `python3 scripts/rag-indexer.py --stats`
+3. Test search: `python3 scripts/user-context-search.py --user unknown --query "adaptic" --max-results 1`
+4. Run test suite if available: `bash scripts/test-rag-search.sh`
 
-{Generate based on archetype:
-- executive-operator: broad autonomy with escalation for legal/financial commitments
-- technical-leader: autonomous on technical decisions, escalates on budget/headcount
-- compliance-officer: conservative, escalates on submissions and interpretations
-- etc.}
+### 5.8 PDF Generation — `docs/guides/pdf-generation-setup.md`
 
----
+1. `pandoc --version`
+2. Check XeLaTeX: `xelatex --version 2>/dev/null || ~/Library/TinyTeX/bin/universal-darwin/xelatex --version 2>/dev/null`
+3. Generate test PDF:
+   ```bash
+   echo "# Test\nGenerated by init-maestro." > /tmp/init-test.md
+   node scripts/pdf-generation/build-document.mjs --input /tmp/init-test.md --template memo --output /tmp/init-test.pdf
+   test -f /tmp/init-test.pdf && echo "PDF OK"
+   rm -f /tmp/init-test.md /tmp/init-test.pdf
+   ```
 
-{fullName} | {title} | {company} — Powered by [Maestro](https://github.com/adapticai/maestro)
-```
+### 5.9 Media Generation — `docs/guides/media-generation-setup.md`
 
-Write this README.md to the repo root, populated with all the gathered values.
+1. Verify Gemini key set
+2. List specs: `node scripts/media-generation/generate-assets.mjs --list`
+3. Verify client loads: `node -e "import('./scripts/media-generation/gemini-image-client.mjs').then(() => console.log('OK'))"`
 
-## Phase 6: Create GitHub Repository
+### 5.10 Verification Summary
 
-Ask the user whether they want to create a GitHub repo for this agent:
+Print results:
 
 ```
-Would you like me to create a GitHub repository for this agent? (yes/no)
+╔══════════════════════════════════════════════════════════════╗
+║  SUBSYSTEM VERIFICATION RESULTS                              ║
+╠══════════════════════════════════════════════════════════════╣
+║                                                              ║
+║  Outbound Governance   ✅ PASS    hooks, dedup, validation   ║
+║  Email (Gmail)         ✅ PASS    IMAP, SMTP, signatures     ║
+║  Slack                 ✅ PASS    tokens, send, typing        ║
+║  SMS (Twilio)          ✅ PASS    handler, send, caller-id   ║
+║  WhatsApp              ⏭️ SKIP    not selected                ║
+║  Voice / Huddle        ⏭️ SKIP    not selected                ║
+║  Poller & Daemon       ✅ PASS    poller, plists, watchdog    ║
+║  RAG & Context         ✅ PASS    index built, search works   ║
+║  PDF Generation        ✅ PASS    pandoc + xelatex OK         ║
+║  Media Generation      ⏭️ SKIP    not selected                ║
+║                                                              ║
+║  Overall: 7/7 selected subsystems PASS                       ║
+║                                                              ║
+║  Guides: docs/guides/ (for detailed testing & troubleshoot)  ║
+╚══════════════════════════════════════════════════════════════╝
 ```
 
-If yes:
+If any subsystem FAILS: diagnose via the guide's troubleshooting section, attempt one fix, re-run check. If still failing, report failure with specific error and ask user whether to continue or abort.
+
+## Phase 6: Generate Agent README
+
+Generate a comprehensive README.md for this agent's repository. This describes THIS specific agent, not the Maestro framework.
+
+Include all of the following sections populated with gathered values:
+
+1. **Title and tagline**: `{fullName} — Autonomous {title} for {company}`
+2. **Who is {firstName}?**: 3-4 sentence description of role, reporting line, autonomy level
+3. **Capabilities**: 8-12 bullet points based on archetype and responsibilities
+4. **Architecture**: 5-tier model with role-specific domain controllers
+5. **Subsystem Status**: Include the Phase 5 verification matrix
+6. **Operating Modes**: Reactive (polling), Scheduled (triggers), Proactive (backlog)
+7. **Commands**: npm run daemon, healthcheck, emergency-stop, resume, upgrade
+8. **Implementation Guides**: Table linking to all 10 guides in `docs/guides/`
+9. **Communication Governance**: Based on archetype autonomy model
+
+Write to repo root as `README.md`.
+
+## Phase 7: Create GitHub Repository
+
+Ask the user whether they want to create a GitHub repo:
 
 ```
-Repository setup:
-  1. GitHub organization or username? (default: adapticai)
-  2. Repository name? (default: {repoName}, e.g., "jacob-ai")
-  3. Visibility: private (recommended) or public? (default: private)
+Would you like me to create a GitHub repository for this agent? (yes/no)
 ```
 
-Then run:
-```bash
-gh repo create {org}/{repoName} --private --description "{fullName} — Autonomous {title} for {company} (powered by Maestro)"
-```
+If yes: ask for org/username (default: adapticai), repo name (default: {repoName}), visibility (default: private). Then:
 
-After creating the repo, set up git and push:
 ```bash
+gh repo create {org}/{repoName} --private --description "{fullName} — Autonomous {title} for {company} (powered by Maestro)"
 git remote add origin https://github.com/{org}/{repoName}.git
 git add -A
 git commit -m "Initialize {fullName} as {title} — powered by @adaptic/maestro"
 git push -u origin main
 ```
 
-If the user declines, skip this step and remind them to set up a repo manually later.
+## Phase 8: Final Verification
 
-## Phase 7: Final Verification
+### Step 1: Grep for stale agent references
 
-After ALL phases are complete, run these verification steps:
-
-### Step 1: Grep for old agent references
-
-Search critical files for any remaining references to the old agent's first name (case-insensitive). Check:
-- CLAUDE.md
-- config/agent.ts
-- config/environment.yaml
-- config/contacts.yaml
-- config/priorities.yaml
-- package.json
-- All files in schedules/triggers/
-- All agent.md files in agents/
-
-Report any stragglers and fix them.
+Search critical files for old agent name (case-insensitive): CLAUDE.md, config/agent.ts, config/*.yaml, package.json, schedules/triggers/*.md, agents/*/agent.md. Fix any stragglers.
 
 ### Step 2: Validate config/agent.ts
 
-Read `config/agent.ts` and verify it has valid TypeScript syntax and all fields are populated with the new values.
+Read and verify valid TypeScript, all fields populated with new values.
 
-### Step 3: Run health check
+### Step 3: Health check
 
 ```bash
 npm run healthcheck
 ```
 
-Report the results.
-
-### Step 4: Summary
-
-Print a completion summary:
+### Step 4: Completion Summary
 
 ```
-Maestro initialization complete.
+═══════════════════════════════════════════════════════════════
+  MAESTRO INITIALIZATION COMPLETE
+═══════════════════════════════════════════════════════════════
 
   Agent:       {fullName}, {title}
   Archetype:   {archetype}
@@ -796,41 +1041,38 @@ Maestro initialization complete.
   Principal:   {principalName}
   Machine:     {machineName}
 
-  Files modified:
-    - config/agent.ts (central identity config)
-    - CLAUDE.md (operating charter)
-    - README.md (agent-specific documentation)
-    - config/environment.yaml, contacts.yaml, priorities.yaml
-    - package.json
-    - agents/{agent-slug}/agent.md (+ 30 other agent definitions)
-    - schedules/triggers/ (13 trigger prompts)
+  Identity (Phase 2):       ✅ 8 parallel agents rewrote repo
+  Infrastructure (Phase 3): ✅ {N} launchd triggers installed
+  Services (Phase 4):       ✅ {list configured services}
+  Subsystems (Phase 5):     {include verification matrix}
+  README (Phase 6):         ✅ Agent-specific README generated
+  GitHub (Phase 7):         {repo URL or "skipped"}
 
-  Infrastructure:
-    - {N} launchd triggers installed
-    - Global Claude Code settings configured
-    - .env file created {with/without API keys}
+  ─────────────────────────────────────────────────────────
 
-  GitHub: https://github.com/{org}/{repoName} (if created)
+  Next steps:
+    1. Start the daemon:  npm run daemon
+    2. Monitor logs:      tail -f logs/daemon/$(date +%Y-%m-%d)-sessions.jsonl
+    3. Test a message:    Send a Slack DM to {firstName}
 
-  Verify everything:
-    1. Review changes: git diff
-    2. Check daemons: launchctl list | grep adaptic
-    3. Health check: npm run healthcheck
-    4. Start daemon: npm run daemon
+  Implementation guides:    docs/guides/
+═══════════════════════════════════════════════════════════════
 ```
 
-## Guidelines for the Wizard Conversation
+## Guidelines for the Wizard
 
 - Be warm and professional. This is a setup experience, not an interrogation.
-- Offer sensible defaults wherever possible. If the user says "defaults" for any field, use the archetype-appropriate default.
-- If the user provides all information upfront (e.g., as arguments to the command), skip the conversational steps and go straight to confirmation.
-- Always confirm before executing. The changes are extensive and hard to undo.
-- When spawning sub-agents, give each one the COMPLETE set of gathered values so they can work independently.
-- Sub-agents MUST run in parallel (use `run_in_background: true`) -- do not run them sequentially.
-- After all sub-agents finish, do the verification grep yourself (do not delegate it).
+- Offer sensible defaults wherever possible.
+- Always confirm before executing identity changes (Phase 2). Service configuration (Phase 4) and verification (Phase 5) execute autonomously after the user selects services.
+- Sub-agents MUST run in parallel (`run_in_background: true`).
+- **Autonomous execution is the default.** Only ask for input when you cannot proceed without it (credentials, 2FA, payment). Everything else — web UI navigation, script execution, file writes, verification — you do yourself.
+- **Use Playwright MCP** for web UIs: Slack API portal, Twilio Console, Google Account, ElevenLabs, Deepgram, Gemini.
+- **Use Bash** for local operations: scripts, installs, service starts, tests.
+- If Playwright fails (auth wall, CAPTCHA), fall back to asking user to do that specific step via `! open <url>`, then resume.
 
 ## Error Handling
 
-- If a sub-agent fails, report which one failed and what went wrong. Offer to retry just that sub-agent.
-- If the user wants to abort mid-wizard, confirm and exit cleanly.
-- If config/agent.ts cannot be read, warn that the repo may not be properly set up and suggest running `npx @adaptic/maestro create` first.
+- If a sub-agent fails, report which one and offer to retry.
+- If a Phase 5 subsystem verification fails, diagnose using the guide's troubleshooting section, attempt one fix, re-run. If still failing, report with specific error and ask whether to continue.
+- If user aborts mid-wizard, exit cleanly.
+- If config/agent.ts unreadable, suggest `npx @adaptic/maestro create` first.