@adaptic/maestro 1.0.0

package/scripts/airtable-crm-populate.md

@@ -0,0 +1,99 @@
+# Airtable CRM Population — Execution Instructions for Sophie
+
+**When to run**: After Mehran creates the "Adaptic Pipeline" base on airtable.com.
+
+## Step 1: Find the Base ID
+
+```
+Use: mcp__claude_ai_Airtable__search_bases with searchQuery: "Adaptic Pipeline"
+Extract: baseId (format: appXXXXXXXXXXXXXX)
+```
+
+## Step 2: Create Table 1 — Investor Pipeline
+
+```
+Use: mcp__claude_ai_Airtable__create_table
+baseId: <from step 1>
+name: "Investor Pipeline"
+description: "LP and investor relationship tracking through fundraising funnel"
+fields:
+  - name: "Name", type: "singleLineText"
+  - name: "Type", type: "singleSelect", choices: LP, Family Office, Sovereign Wealth, Pension, Endowment, Fund of Funds, Other
+  - name: "Stage", type: "singleSelect", choices: Identified, Outreach, Meeting Scheduled, Meeting Completed, DD, Term Sheet, Committed, Declined
+  - name: "Contact Name", type: "singleLineText"
+  - name: "Contact Email", type: "email"
+  - name: "Relationship Warmth", type: "singleSelect", choices: Cold, Warm, Hot, Active
+  - name: "Last Contact Date", type: "date", format: iso
+  - name: "Notes", type: "multilineText"
+  - name: "Priority", type: "singleSelect", choices: Critical, High, Medium, Low
+  - name: "Owner", type: "singleSelect", choices: Mehran, Sophie, Hootan, Nima
+```
+
+## Step 3: Create Table 2 — M&A Targets
+
+```
+Use: mcp__claude_ai_Airtable__create_table
+baseId: <from step 1>
+name: "M&A Targets (Project Aether)"
+description: "Rollup acquisition target tracking — 9 targets across G0 verification pipeline"
+fields:
+  - name: "Firm Name", type: "singleLineText"
+  - name: "AUM (USD)", type: "currency", symbol: "$", precision: 0
+  - name: "Strategy", type: "singleSelect", choices: Equity L/S, Global Macro, Quantitative, Multi-Strategy, Event-Driven, Credit, Other
+  - name: "G0 Status", type: "singleSelect", choices: Pass, Flagged, Not Verified, Excluded
+  - name: "G0 Issues", type: "multilineText"
+  - name: "Jurisdiction", type: "singleLineText"
+  - name: "Key Person", type: "singleLineText"
+  - name: "Succession Risk", type: "singleSelect", choices: High, Medium, Low
+  - name: "Stage", type: "singleSelect", choices: G0 Verified, Outreach, Initial Meeting, DD, LOI, Signed, Declined
+  - name: "Notes", type: "multilineText"
+```
+
+## Step 4: Create Table 3 — Key Relationships
+
+```
+Use: mcp__claude_ai_Airtable__create_table
+baseId: <from step 1>
+name: "Key Relationships"
+description: "Strategic stakeholder relationship tracking — advisors, regulators, legal, investors, partners"
+fields:
+  - name: "Name", type: "singleLineText"
+  - name: "Organisation", type: "singleLineText"
+  - name: "Role", type: "singleLineText"
+  - name: "Relationship Type", type: "singleSelect", choices: Advisor, Regulator, Legal, Investor, Partner, Vendor, Candidate
+  - name: "Warmth", type: "singleSelect", choices: Cold, Warm, Hot, Active, Dormant
+  - name: "Last Contact", type: "date", format: iso
+  - name: "Next Action", type: "singleLineText"
+  - name: "Owner", type: "singleSelect", choices: Mehran, Sophie, Hootan, Nima
+```
+
+## Step 5: Populate M&A Targets (9 records)
+
+Use list_tables_for_base to get field IDs, then create_records_for_table.
+
+Records to create (from outputs/research/2026-04-03-g0-entity-verification.md):
+
+1. Sessa Capital | $3,300,000,000 | Equity L/S | Pass | US (NY) | John Eric Petry | Medium | G0 Verified | AUM ~25% lower than profiled; extreme LP concentration (5 clients)
+2. HG Vora Capital | $2,000,000,000 | Multi-Strategy | Pass | US (NY) | Parag Vora | Low | G0 Verified | AUM decline from peak; distressed credit less aligned with Adaptic systematic approach
+3. Cadian Capital | $4,500,000,000 | Equity L/S | Pass | US (NY) | Eric Bannasch | High | G0 Verified | AUM discrepancy (profiled $2B, verified $3.4-5.6B); needs Form ADV refresh
+4. Third Point | $21,000,000,000 | Multi-Strategy | Flagged | US (NY) | Daniel S. Loeb | Medium | G0 Verified | CRITICAL: Strategic pivot to insurance/reinsurance; no longer traditional hedge fund; AUM above sweet spot
+5. Quantedge Capital | $5,750,000,000 | Quantitative | Pass | Singapore | Leow Kah Shin / Chua Choong Tze | High | G0 Verified | LP base composition discrepancy; exceptional performance = high valuation expectations
+6. Rokos Capital | $21,000,000,000 | Global Macro | Flagged | UK (London) | Chris Rokos | Low | G0 Verified | CRITICAL: Fee increase + AUM cap + zero exit motivation; not viable for near-term acquisition
+7. Oasis Management | $1,250,000,000 | Multi-Strategy | Pass | KY/HK (Hong Kong) | Seth Fischer | High | G0 Verified | AUM unverifiable from public sources; historical SFC enforcement action (2011)
+8. Graham Capital | $18,000,000,000 | Quantitative | Flagged | US (CT) | Kenneth G. Tropin | High | G0 Verified | CRITICAL: AUM profiled as $3.2B, actually ~$18B; strongest succession signal across all targets
+9. Capula Investment | $32,000,000,000 | Global Macro | Flagged | UK (London) | Yan Huo / Masao Asai | Medium | G0 Verified | AUM $32B far above sweet spot; Dai-ichi Life 15% stake creates third-party entanglement
+
+## Step 6: Populate Key Relationships (4 records)
+
+1. DFSA | DFSA | Regulator | Regulator | Active | Mehran | Maintain regular touchpoints through submission process
+2. Shayan Kargarian | FTLab / New Genre Holdings | Managing Partner | Partner | Warm | Mehran | Follow up on GranMas meeting action items
+3. 10leaves | 10leaves | External Legal/Regulatory Advisor | Legal | Active | Sophie | Chase for review completion
+4. Lili Wang | TBD | TBD | TBD | TBD | Mehran | Clarify relationship context and strategic relevance
+
+## Step 7: Delete Default Table
+
+The base will come with a default "Table 1" — delete it after creating the 3 custom tables.
+
+## Step 8: Update Queue
+
+Update ib-20260403-004 status from blocked → resolved with completion history.

package/scripts/archive-email.sh

@@ -0,0 +1,41 @@
+#!/bin/bash
+# archive-email.sh — Archive non-actionable Gmail messages via IMAP
+# Usage: ./scripts/archive-email.sh
+# Requires GMAIL_APP_PASSWORD environment variable
+set -e
+
+export GMAIL_APP_PASSWORD=nqinfcgnhzmjucho
+
+python3 << 'PYEOF'
+import imaplib
+import os
+
+user = "sophie@adaptic.ai"
+password = os.environ["GMAIL_APP_PASSWORD"]
+
+mail = imaplib.IMAP4_SSL("imap.gmail.com")
+mail.login(user, password)
+mail.select("INBOX")
+
+# Non-actionable sender domains to auto-archive
+junk_domains = [
+    "greptile.com", "gamma.app", "linear.app", "netlify.com",
+    "consensus.app", "zapier.com", "calendly.com", "jam.dev",
+    "send.zapier.com", "mail.consensus.app", "send.calendly.com",
+    "noreply@netlify.com", "hello@greptile.com", "hello@gamma.app",
+]
+
+archived = 0
+for domain in junk_domains:
+    status, messages = mail.search(None, f'(UNSEEN FROM "{domain}")')
+    if status == "OK" and messages[0]:
+        for num in messages[0].split():
+            mail.store(num, '+FLAGS', '\\Seen')
+            mail.copy(num, '"[Gmail]/All Mail"')
+            mail.store(num, '+FLAGS', '\\Deleted')
+            archived += 1
+
+mail.expunge()
+mail.logout()
+print(f"Archived {archived} non-actionable emails")
+PYEOF

package/scripts/comms-monitor.sh

@@ -0,0 +1,285 @@
+#!/bin/bash
+# comms-monitor.sh — Unified communications monitor (Slack + Gmail)
+#
+# 1. Drain Slack events from Railway (channels, @mentions, reactions)
+# 2. Poll ALL DMs + threads via User Token API
+# 3. Poll Gmail (Sophie's inbox) via IMAP for new unread emails
+# 4. Write all new items to state/inbox/ for processing
+#
+# Run every 10 seconds via cron/launchd
+set -e
+
+source /Users/sophie/sophie-ai/.env
+export SLACK_USER_TOKEN
+export GMAIL_APP_PASSWORD
+
+INBOX_DIR="/Users/sophie/sophie-ai/state/inbox/slack"
+GMAIL_INBOX_DIR="/Users/sophie/sophie-ai/state/inbox/gmail"
+mkdir -p "$GMAIL_INBOX_DIR"
+RAILWAY_URL="https://slack-events-server-production.up.railway.app/events"
+SOPHIE_ID="U099N1JFPRQ"
+TRACKER_DIR="/Users/sophie/sophie-ai/state/slack-thread-tracker"
+mkdir -p "$INBOX_DIR" "$TRACKER_DIR"
+
+# ── Part 1: Drain Railway event buffer (channels, mentions, reactions) ──
+
+RAILWAY_EVENTS=$(curl -s --max-time 5 "$RAILWAY_URL" 2>/dev/null || echo '{"count":0}')
+RAILWAY_COUNT=$(echo "$RAILWAY_EVENTS" | python3 -c "import sys,json; print(json.load(sys.stdin).get('count',0))" 2>/dev/null)
+
+if [ "$RAILWAY_COUNT" != "0" ] && [ -n "$RAILWAY_COUNT" ]; then
+  echo "$RAILWAY_EVENTS" | python3 -c "
+import sys, json, os
+data = json.load(sys.stdin)
+inbox = '$INBOX_DIR'
+for event in data.get('events', []):
+    ts = event.get('received_at', '').replace(':', '-').replace('.', '-')
+    etype = event.get('event_type', 'unknown')
+    filename = f'{ts}-{etype}.json'
+    filepath = os.path.join(inbox, filename)
+    with open(filepath, 'w') as f:
+        json.dump(event, f, indent=2)
+    print(f'[RAILWAY] {etype} -> {filename}')
+"
+fi
+
+# ── Part 2 + 3: Scan ALL DMs (top-level + threads) from ALL users ──
+# Discovers every open DM conversation, checks for new messages and unanswered threads
+
+ACTIVE_THREADS_FILE="/Users/sophie/sophie-ai/state/slack-active-threads.json"
+
+python3 -c "
+import json, os, subprocess
+
+token = os.environ.get('SLACK_USER_TOKEN', '')
+sophie_id = '$SOPHIE_ID'
+inbox = '$INBOX_DIR'
+tracker = '$TRACKER_DIR'
+active_threads_file = '$ACTIVE_THREADS_FILE'
+
+if not token:
+    print('[ERROR] SLACK_USER_TOKEN not set')
+    exit(1)
+
+def api(endpoint):
+    resp = subprocess.run(
+        ['curl', '-s', '-H', f'Authorization: Bearer {token}', endpoint],
+        capture_output=True, text=True
+    )
+    try:
+        return json.loads(resp.stdout)
+    except:
+        return {}
+
+# Load active threads
+active_threads = {}  # channel -> set of thread_ts
+if os.path.exists(active_threads_file):
+    try:
+        with open(active_threads_file) as f:
+            active_threads = json.load(f)
+    except:
+        active_threads = {}
+
+# Step 1: Get all open DM conversations
+dm_list = api('https://slack.com/api/conversations.list?types=im&limit=100')
+if not dm_list.get('ok'):
+    print(f'[ERROR] conversations.list failed: {dm_list.get(\"error\")}')
+    exit(1)
+
+dm_channels = [c for c in dm_list.get('channels', []) if not c.get('is_archived')]
+
+for dm in dm_channels:
+    channel_id = dm['id']
+    other_user = dm.get('user', '')
+
+    # Skip DMs with ourselves
+    if other_user == sophie_id:
+        continue
+
+    # Get recent messages in this DM
+    history = api(f'https://slack.com/api/conversations.history?channel={channel_id}&limit=20')
+    if not history.get('ok'):
+        continue
+
+    messages = history.get('messages', [])
+    channel_threads = active_threads.get(channel_id, [])
+
+    for msg in messages:
+        user = msg.get('user', '')
+        ts = msg.get('ts', '')
+
+        # ── Check top-level messages (new DMs from others) ──
+        if user != sophie_id and ts:
+            tracker_file = os.path.join(tracker, ts)
+            if not os.path.exists(tracker_file):
+                record = {
+                    'received_at': ts,
+                    'event_type': 'dm',
+                    'slack_event': {
+                        'type': 'message',
+                        'user': user,
+                        'text': msg.get('text', ''),
+                        'ts': ts,
+                        'channel': channel_id,
+                    },
+                    'source': 'dm_poll',
+                }
+                filepath = os.path.join(inbox, f'{ts}-dm.json')
+                with open(filepath, 'w') as f:
+                    json.dump(record, f, indent=2)
+                with open(tracker_file, 'w') as f:
+                    f.write(ts)
+                print(f'[DM] from {user} in {channel_id} -> {ts}-dm.json')
+
+        # ── Collect threads to check ──
+        if msg.get('reply_count', 0) > 0:
+            thread_ts = msg.get('ts', '')
+            if thread_ts and thread_ts not in channel_threads:
+                channel_threads.append(thread_ts)
+
+    # ── Check threads for unanswered replies ──
+    for thread_ts in channel_threads:
+        thread_data = api(f'https://slack.com/api/conversations.replies?channel={channel_id}&ts={thread_ts}&limit=50')
+        if not thread_data.get('ok'):
+            continue
+
+        thread_msgs = thread_data.get('messages', [])
+        if len(thread_msgs) < 2:
+            continue
+
+        # Load per-thread cursor (timestamp of last processed reply)
+        cursor_file = os.path.join(tracker, f'{channel_id}_thread_{thread_ts}_cursor')
+        cursor_ts = ''
+        if os.path.exists(cursor_file):
+            with open(cursor_file) as cf:
+                cursor_ts = cf.read().strip()
+
+        # Process ALL replies newer than cursor, skipping Sophie's own messages
+        # Skip first message (index 0) as it's the thread parent, already handled as top-level
+        newest_processed_ts = cursor_ts
+        for reply in thread_msgs[1:]:
+            reply_ts = reply.get('ts', '')
+            reply_user = reply.get('user', '')
+
+            # Skip replies at or before the cursor
+            if cursor_ts and reply_ts <= cursor_ts:
+                continue
+
+            # Skip Sophie's own replies
+            if reply_user == sophie_id:
+                # Still advance cursor past Sophie's own messages
+                if reply_ts > newest_processed_ts:
+                    newest_processed_ts = reply_ts
+                continue
+
+            record = {
+                'received_at': reply_ts,
+                'event_type': 'thread_reply',
+                'slack_event': {
+                    'type': 'message',
+                    'user': reply_user,
+                    'text': reply.get('text', ''),
+                    'ts': reply_ts,
+                    'thread_ts': thread_ts,
+                    'channel': channel_id,
+                },
+                'source': 'dm_thread_scan',
+            }
+            filepath = os.path.join(inbox, f'{reply_ts}-thread_reply.json')
+            with open(filepath, 'w') as f:
+                json.dump(record, f, indent=2)
+            print(f'[DM-THREAD] reply from {reply_user} in {channel_id} thread {thread_ts} -> {reply_ts}-thread_reply.json')
+
+            if reply_ts > newest_processed_ts:
+                newest_processed_ts = reply_ts
+
+        # Update per-thread cursor to the newest reply we processed
+        if newest_processed_ts and newest_processed_ts != cursor_ts:
+            with open(cursor_file, 'w') as cf:
+                cf.write(newest_processed_ts)
+
+    # Update active threads for this channel (keep last 50)
+    active_threads[channel_id] = sorted(set(channel_threads), reverse=True)[:50]
+
+# Persist active threads
+with open(active_threads_file, 'w') as f:
+    json.dump(active_threads, f)
+"
+
+# ── Part 4: Poll Gmail via IMAP for unread emails ──
+
+python3 -c "
+import imaplib, email, json, os, hashlib
+from email.header import decode_header
+
+gmail_user = 'sophie@adaptic.ai'
+gmail_pass = os.environ.get('GMAIL_APP_PASSWORD', '')
+inbox_dir = '$GMAIL_INBOX_DIR'
+tracker_dir = '$TRACKER_DIR'
+
+if not gmail_pass:
+    exit(0)
+
+try:
+    mail = imaplib.IMAP4_SSL('imap.gmail.com')
+    mail.login(gmail_user, gmail_pass)
+    mail.select('INBOX')
+
+    status, data = mail.search(None, 'UNSEEN')
+    if status != 'OK' or not data[0]:
+        mail.logout()
+        exit(0)
+
+    msg_ids = data[0].split()
+
+    for mid in msg_ids[-10:]:  # Last 10 unread max per cycle
+        status, msg_data = mail.fetch(mid, '(BODY.PEEK[HEADER.FIELDS (FROM SUBJECT DATE MESSAGE-ID)])')
+        if status != 'OK':
+            continue
+
+        raw = msg_data[0][1]
+        msg = email.message_from_bytes(raw)
+
+        from_addr = msg.get('From', '')
+        subject = msg.get('Subject', '')
+        date = msg.get('Date', '')
+        message_id = msg.get('Message-ID', '')
+
+        # Decode subject if needed
+        if subject:
+            decoded = decode_header(subject)
+            subject = ''.join(
+                part.decode(enc or 'utf-8') if isinstance(part, bytes) else part
+                for part, enc in decoded
+            )
+
+        # Dedup via message-id hash
+        mid_hash = hashlib.md5((message_id or f'{from_addr}{subject}{date}').encode()).hexdigest()[:16]
+        tracker_file = os.path.join(tracker_dir, f'gmail-{mid_hash}')
+        if os.path.exists(tracker_file):
+            continue
+
+        record = {
+            'received_at': date,
+            'event_type': 'email',
+            'email': {
+                'from': from_addr,
+                'subject': subject,
+                'date': date,
+                'message_id': message_id,
+            },
+            'source': 'gmail_imap',
+        }
+
+        filepath = os.path.join(inbox_dir, f'{mid_hash}-email.json')
+        with open(filepath, 'w') as f:
+            json.dump(record, f, indent=2)
+
+        with open(tracker_file, 'w') as f:
+            f.write(mid_hash)
+
+        print(f'[GMAIL] {from_addr} — {subject[:50]}')
+
+    mail.logout()
+except Exception as e:
+    print(f'[GMAIL-ERROR] {e}')
+"

package/scripts/configure-whatsapp-sandbox.sh

@@ -0,0 +1,201 @@
+#!/bin/bash
+# configure-whatsapp-sandbox.sh — Configure Twilio WhatsApp Sandbox webhook URLs
+#
+# This script queries the current Cloudflare tunnel URL and configures the Twilio
+# WhatsApp Sandbox to route inbound messages to Sophie's local whatsapp-handler.mjs.
+#
+# Usage:
+#   ./scripts/configure-whatsapp-sandbox.sh                    # Auto-detect tunnel URL
+#   ./scripts/configure-whatsapp-sandbox.sh --url <tunnel-url> # Use specific URL
+#   ./scripts/configure-whatsapp-sandbox.sh --serverless       # Use Twilio Serverless URL
+#   ./scripts/configure-whatsapp-sandbox.sh --status           # Show current sandbox config
+#
+# Environment variables (from .env):
+#   TWILIO_ACCOUNT_SID  — Twilio account SID
+#   TWILIO_AUTH_TOKEN   — Twilio auth token
+set -e
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+SOPHIE_AI="$(dirname "$SCRIPT_DIR")"
+
+if [ -f "$SOPHIE_AI/.env" ]; then
+  source "$SOPHIE_AI/.env"
+fi
+
+# Twilio WhatsApp Sandbox API endpoint
+# The sandbox config is managed via the Twilio REST API under the account's messaging sandbox
+SANDBOX_API_URL="https://api.twilio.com/2010-04-01/Accounts/${TWILIO_ACCOUNT_SID}/Sandbox.json"
+
+# Default URLs
+SERVERLESS_URL="https://sophie-webhooks-2805-production.twil.io/whatsapp-reply"
+TUNNEL_URL=""
+MODE=""
+
+# Parse arguments
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --url)
+      TUNNEL_URL="$2"
+      MODE="tunnel"
+      shift 2
+      ;;
+    --serverless)
+      MODE="serverless"
+      shift
+      ;;
+    --status)
+      MODE="status"
+      shift
+      ;;
+    -h|--help)
+      echo "Usage: configure-whatsapp-sandbox.sh [OPTIONS]"
+      echo ""
+      echo "Options:"
+      echo "  --url <url>    Use this URL as the webhook base (e.g., https://xyz.trycloudflare.com)"
+      echo "  --serverless   Use Twilio Serverless URL (stable, no tunnel dependency)"
+      echo "  --status       Show current sandbox configuration"
+      echo "  -h             Show this help"
+      echo ""
+      echo "If no option given, auto-detects Cloudflare tunnel URL."
+      exit 0
+      ;;
+    *)
+      echo "ERROR: Unknown argument: $1" >&2
+      exit 1
+      ;;
+  esac
+done
+
+# Validate credentials
+if [ -z "$TWILIO_ACCOUNT_SID" ]; then
+  echo "ERROR: TWILIO_ACCOUNT_SID not set" >&2
+  exit 1
+fi
+
+if [ -z "$TWILIO_AUTH_TOKEN" ]; then
+  echo "ERROR: TWILIO_AUTH_TOKEN not set" >&2
+  exit 1
+fi
+
+# Show current sandbox config
+if [ "$MODE" = "status" ]; then
+  echo "Fetching current WhatsApp Sandbox configuration..."
+  echo ""
+
+  # The sandbox config is at a different endpoint for WhatsApp
+  # Twilio WhatsApp sandbox settings are at:
+  # https://api.twilio.com/2010-04-01/Accounts/{SID}/Sandbox.json
+  RESPONSE=$(curl -s \
+    -u "${TWILIO_ACCOUNT_SID}:${TWILIO_AUTH_TOKEN}" \
+    "https://api.twilio.com/2010-04-01/Accounts/${TWILIO_ACCOUNT_SID}/Sandbox.json" 2>/dev/null || echo "")
+
+  if [ -n "$RESPONSE" ]; then
+    echo "Sandbox API Response:"
+    echo "$RESPONSE" | python3 -m json.tool 2>/dev/null || echo "$RESPONSE"
+  else
+    echo "No sandbox config returned. The sandbox may need to be activated first in Twilio Console."
+    echo ""
+    echo "To activate:"
+    echo "  1. Go to https://console.twilio.com/us1/develop/sms/try-it-out/whatsapp-learn"
+    echo "  2. Follow the on-screen instructions"
+    echo "  3. Note the sandbox join keyword"
+  fi
+  exit 0
+fi
+
+# Determine webhook URL
+if [ "$MODE" = "serverless" ]; then
+  WEBHOOK_URL="$SERVERLESS_URL"
+  STATUS_URL=""
+  echo "Using Twilio Serverless URL: $WEBHOOK_URL"
+elif [ -n "$TUNNEL_URL" ]; then
+  # Strip trailing slash
+  TUNNEL_URL="${TUNNEL_URL%/}"
+  WEBHOOK_URL="${TUNNEL_URL}/whatsapp"
+  STATUS_URL="${TUNNEL_URL}/whatsapp/status"
+  echo "Using provided tunnel URL: $TUNNEL_URL"
+else
+  # Auto-detect Cloudflare tunnel URL
+  echo "Auto-detecting Cloudflare tunnel URL..."
+
+  # Try to find the tunnel URL from cloudflared process
+  # Quick tunnels print their URL to stderr on startup
+  TUNNEL_LOG=$(ps aux | grep cloudflared | grep -v grep | head -1)
+
+  if [ -z "$TUNNEL_LOG" ]; then
+    echo "ERROR: No Cloudflare tunnel detected. Start one with:" >&2
+    echo "  cloudflared tunnel --url http://localhost:3002" >&2
+    echo "" >&2
+    echo "Or use --serverless flag to use the Twilio Serverless URL instead." >&2
+    exit 1
+  fi
+
+  echo "Cloudflare tunnel process detected."
+  echo ""
+  echo "NOTE: Quick tunnels (trycloudflare.com) get a random URL on each restart."
+  echo "The tunnel URL cannot be reliably auto-detected from the process."
+  echo ""
+  echo "Please provide the tunnel URL manually:"
+  echo "  ./scripts/configure-whatsapp-sandbox.sh --url https://xyz.trycloudflare.com"
+  echo ""
+  echo "Or check the Cloudflare tunnel output for the URL."
+  echo "Or use --serverless for a stable URL via Twilio Serverless."
+  exit 1
+fi
+
+echo ""
+echo "Configuring WhatsApp Sandbox webhooks..."
+echo "  Inbound webhook: $WEBHOOK_URL"
+if [ -n "$STATUS_URL" ]; then
+  echo "  Status callback: $STATUS_URL"
+fi
+
+# Update sandbox configuration
+# Note: Twilio's sandbox webhook configuration is typically done via the Console.
+# The REST API approach depends on the sandbox type.
+# For WhatsApp specifically, webhook config is in the Twilio Console under:
+#   Messaging > Try it Out > Send a WhatsApp message > Sandbox Settings
+#
+# However, we can try the REST API:
+
+echo ""
+echo "========================================"
+echo "  MANUAL STEPS REQUIRED"
+echo "========================================"
+echo ""
+echo "Twilio WhatsApp Sandbox webhook URLs must be configured in the Console:"
+echo ""
+echo "1. Go to: https://console.twilio.com/us1/develop/sms/try-it-out/whatsapp-learn"
+echo "2. Scroll to 'Sandbox Configuration' section"
+echo "3. Set these values:"
+echo ""
+echo "   WHEN A MESSAGE COMES IN:"
+echo "     URL: $WEBHOOK_URL"
+echo "     Method: HTTP POST"
+echo ""
+if [ -n "$STATUS_URL" ]; then
+  echo "   STATUS CALLBACK URL:"
+  echo "     URL: $STATUS_URL"
+  echo "     Method: HTTP POST"
+  echo ""
+fi
+echo "4. Click Save"
+echo ""
+echo "5. Note the JOIN CODE shown on the page"
+echo "   Users must send 'join <code>' to +1 415 523 8886 on WhatsApp"
+echo ""
+echo "========================================"
+echo ""
+echo "Once configured, test with:"
+echo "  ./scripts/send-whatsapp.sh --to \"+971585291799\" --body \"WhatsApp sandbox test from Sophie\""
+
+# Log this action
+LOG_DIR="$SOPHIE_AI/logs/audit"
+mkdir -p "$LOG_DIR"
+LOG_FILE="$LOG_DIR/$(date +%Y-%m-%d)-actions.jsonl"
+
+LOG_ENTRY=$(cat <<LOGEOF
+{"timestamp":"$(date -u +%Y-%m-%dT%H:%M:%S.000Z)","agent":"configure-whatsapp-sandbox","action":"sandbox_config_instructions_generated","webhook_url":"${WEBHOOK_URL}","status_url":"${STATUS_URL:-none}","mode":"${MODE}"}
+LOGEOF
+)
+echo "$LOG_ENTRY" >> "$LOG_FILE"