fluxy-bot 0.15.0 → 0.15.2

package/supervisor/channels/whatsapp.ts

@@ -0,0 +1,297 @@
+/**
+ * WhatsApp channel provider using Baileys (WhiskeySockets).
+ * Handles connection, QR code flow, message send/receive, and auth persistence.
+ */
+
+import makeWASocket, {
+  useMultiFileAuthState,
+  makeCacheableSignalKeyStore,
+  fetchLatestWaWebVersion,
+  DisconnectReason,
+  Browsers,
+  type WASocket,
+  type BaileysEventMap,
+} from '@whiskeysockets/baileys';
+import fs from 'fs';
+import path from 'path';
+import QRCode from 'qrcode';
+import pino from 'pino';
+import { DATA_DIR } from '../../shared/paths.js';
+import { log } from '../../shared/logger.js';
+import type { ChannelProvider, ChannelStatus, ChannelType } from './types.js';
+
+const AUTH_DIR = path.join(DATA_DIR, 'channels', 'whatsapp', 'auth');
+
+/** Callback when a new message arrives */
+export type OnWhatsAppMessage = (sender: string, senderName: string | undefined, text: string, fromMe: boolean) => void;
+
+export class WhatsAppChannel implements ChannelProvider {
+  readonly type: ChannelType = 'whatsapp';
+
+  private sock: WASocket | null = null;
+  private connected = false;
+  private qrData: string | null = null;
+  private qrSvg: string | null = null;
+  private onMessage: OnWhatsAppMessage;
+  private onStatusChange: (status: ChannelStatus) => void;
+  private reconnectTimer: ReturnType<typeof setTimeout> | null = null;
+  private intentionalDisconnect = false;
+
+  /** Maps LID JIDs to phone JIDs (WhatsApp uses LIDs internally for self-chat) */
+  private lidToPhoneMap = new Map<string, string>();
+  /** Our own phone JID (number@s.whatsapp.net) */
+  private ownPhoneJid: string | null = null;
+
+  constructor(
+    onMessage: OnWhatsAppMessage,
+    onStatusChange: (status: ChannelStatus) => void,
+  ) {
+    this.onMessage = onMessage;
+    this.onStatusChange = onStatusChange;
+  }
+
+  async connect(): Promise<void> {
+    this.intentionalDisconnect = false;
+    await this.connectInternal();
+  }
+
+  async disconnect(): Promise<void> {
+    this.intentionalDisconnect = true;
+    if (this.reconnectTimer) {
+      clearTimeout(this.reconnectTimer);
+      this.reconnectTimer = null;
+    }
+    if (this.sock) {
+      this.sock.end(undefined);
+      this.sock = null;
+    }
+    this.connected = false;
+    this.qrData = null;
+    this.qrSvg = null;
+    this.emitStatus();
+  }
+
+  async sendMessage(to: string, text: string): Promise<void> {
+    if (!this.sock || !this.connected) {
+      log.warn('[whatsapp] Cannot send — not connected');
+      return;
+    }
+    // Normalize: ensure JID format (number@s.whatsapp.net)
+    const jid = to.includes('@') ? to : `${to.replace(/[^0-9]/g, '')}@s.whatsapp.net`;
+    await this.sock.sendMessage(jid, { text });
+    log.info(`[whatsapp] Sent message to ${jid}`);
+  }
+
+  getStatus(): ChannelStatus {
+    return {
+      channel: 'whatsapp',
+      connected: this.connected,
+      info: {
+        hasQr: !!this.qrData,
+        hasCredentials: this.hasCredentials(),
+        phoneNumber: this.sock?.user?.id?.split(':')[0] || null,
+      },
+    };
+  }
+
+  getQrCode(): string | null {
+    return this.qrSvg;
+  }
+
+  hasCredentials(): boolean {
+    return fs.existsSync(path.join(AUTH_DIR, 'creds.json'));
+  }
+
+  /** Delete stored credentials (for re-auth / logout) */
+  async deleteCredentials(): Promise<void> {
+    try {
+      if (fs.existsSync(AUTH_DIR)) {
+        fs.rmSync(AUTH_DIR, { recursive: true, force: true });
+      }
+    } catch (err: any) {
+      log.warn(`[whatsapp] Failed to delete credentials: ${err.message}`);
+    }
+  }
+
+  // ── Internal ──
+
+  /** Translate a JID from LID format to phone format if possible */
+  private translateJid(jid: string): string {
+    // If it's already a phone JID, return as-is
+    if (jid.endsWith('@s.whatsapp.net')) return jid;
+
+    // Check LID map
+    const mapped = this.lidToPhoneMap.get(jid);
+    if (mapped) return mapped;
+
+    // If it's a LID JID and we know our own phone, and this looks like a self-chat LID
+    // LID JIDs typically end with @lid or have a long numeric format
+    if (this.ownPhoneJid && (jid.includes('@lid') || jid.match(/^\d{15,}@/))) {
+      log.info(`[whatsapp] Unmapped LID ${jid} — assuming self-chat, using own phone JID`);
+      this.lidToPhoneMap.set(jid, this.ownPhoneJid);
+      return this.ownPhoneJid;
+    }
+
+    return jid;
+  }
+
+  /** Build the LID-to-phone mapping from sock.user */
+  private buildLidMap() {
+    if (!this.sock?.user) return;
+
+    const user = this.sock.user;
+    // user.id is "phone:device@s.whatsapp.net" — extract phone
+    const phone = user.id.split(':')[0];
+    this.ownPhoneJid = `${phone}@s.whatsapp.net`;
+
+    // user.lid (if available) is the LID JID
+    if ((user as any).lid) {
+      this.lidToPhoneMap.set((user as any).lid, this.ownPhoneJid);
+      log.info(`[whatsapp] LID map: ${(user as any).lid} → ${this.ownPhoneJid}`);
+    }
+  }
+
+  private async connectInternal(): Promise<void> {
+    // Ensure auth directory exists
+    fs.mkdirSync(AUTH_DIR, { recursive: true });
+
+    const { state, saveCreds } = await useMultiFileAuthState(AUTH_DIR);
+
+    // Suppress Baileys' noisy logging
+    const logger = pino({ level: 'silent' }) as any;
+
+    let version: [number, number, number] | undefined;
+    try {
+      const result = await fetchLatestWaWebVersion({});
+      version = result.version;
+    } catch {
+      log.warn('[whatsapp] Could not fetch latest WA version — using default');
+    }
+
+    const sock = makeWASocket({
+      auth: {
+        creds: state.creds,
+        keys: makeCacheableSignalKeyStore(state.keys, logger),
+      },
+      version,
+      browser: Browsers.macOS('Chrome'),
+      printQRInTerminal: false,
+      logger,
+      generateHighQualityLinkPreview: false,
+    });
+
+    this.sock = sock;
+
+    // Persist credential updates
+    sock.ev.on('creds.update', saveCreds);
+
+    // Connection state changes
+    sock.ev.on('connection.update', async (update) => {
+      const { connection, lastDisconnect, qr } = update;
+
+      // QR code received — render to SVG
+      if (qr) {
+        this.qrData = qr;
+        try {
+          this.qrSvg = await QRCode.toString(qr, { type: 'svg' });
+        } catch {
+          this.qrSvg = null;
+        }
+        log.info('[whatsapp] QR code generated — waiting for scan');
+        this.emitStatus();
+      }
+
+      if (connection === 'open') {
+        this.connected = true;
+        this.qrData = null;
+        this.qrSvg = null;
+        this.buildLidMap();
+        log.ok(`[whatsapp] Connected as ${sock.user?.id}`);
+        this.emitStatus();
+      }
+
+      if (connection === 'close') {
+        this.connected = false;
+        this.qrData = null;
+        this.qrSvg = null;
+
+        const statusCode = (lastDisconnect?.error as any)?.output?.statusCode;
+        const reason = DisconnectReason[statusCode] || `code ${statusCode}`;
+        log.warn(`[whatsapp] Disconnected: ${reason}`);
+
+        if (this.intentionalDisconnect) return;
+
+        // Logged out (401) — credentials are invalid, user must re-scan
+        if (statusCode === DisconnectReason.loggedOut) {
+          log.warn('[whatsapp] Logged out — credentials cleared. Re-scan QR to reconnect.');
+          await this.deleteCredentials();
+          this.emitStatus();
+          return;
+        }
+
+        // Any other disconnect — try to reconnect
+        log.info('[whatsapp] Reconnecting in 5s...');
+        this.reconnectTimer = setTimeout(() => this.connectInternal(), 5000);
+      }
+    });
+
+    // Incoming messages
+    sock.ev.on('messages.upsert', (m: BaileysEventMap['messages.upsert']) => {
+      if (m.type !== 'notify') return;
+
+      for (const msg of m.messages) {
+        // Skip status broadcasts and protocol messages
+        if (msg.key.remoteJid === 'status@broadcast') continue;
+        if (!msg.message) continue;
+
+        // Extract text from various message types
+        const text = this.extractText(msg.message);
+        if (!text) continue;
+
+        const fromMe = msg.key.fromMe || false;
+        const rawSender = msg.key.remoteJid || '';
+
+        // Translate LID JIDs to phone JIDs
+        const sender = this.translateJid(rawSender);
+        const pushName = msg.pushName || undefined;
+
+        log.info(`[whatsapp] Message from ${sender} (raw=${rawSender}, fromMe=${fromMe}): ${text.slice(0, 80)}`);
+
+        this.onMessage(sender, pushName, text, fromMe);
+      }
+    });
+  }
+
+  /** Extract text content from a Baileys message object */
+  private extractText(message: any): string | null {
+    if (!message) return null;
+
+    // Direct text
+    if (message.conversation) return message.conversation;
+    if (message.extendedTextMessage?.text) return message.extendedTextMessage.text;
+
+    // Image/video/document captions
+    if (message.imageMessage?.caption) return message.imageMessage.caption;
+    if (message.videoMessage?.caption) return message.videoMessage.caption;
+    if (message.documentMessage?.caption) return message.documentMessage.caption;
+
+    // View-once wrappers
+    if (message.viewOnceMessage?.message) return this.extractText(message.viewOnceMessage.message);
+    if (message.viewOnceMessageV2?.message) return this.extractText(message.viewOnceMessageV2.message);
+
+    // Ephemeral wrapper
+    if (message.ephemeralMessage?.message) return this.extractText(message.ephemeralMessage.message);
+
+    // Edited message
+    if (message.editedMessage?.message) return this.extractText(message.editedMessage.message);
+    if (message.protocolMessage?.editedMessage?.message) {
+      return this.extractText(message.protocolMessage.editedMessage.message);
+    }
+
+    return null;
+  }
+
+  private emitStatus() {
+    this.onStatusChange(this.getStatus());
+  }
+}

package/supervisor/fluxy-agent.ts

@@ -122,6 +122,8 @@ export async function startFluxyAgentQuery(
   savedFiles?: SavedFile[],
   names?: { botName: string; humanName: string },
   recentMessages?: RecentMessage[],
+  /** Override system prompt (used for customer-facing channel messages via SUPPORT.md) */
+  supportPrompt?: string,
 ): Promise<void> {
   const oauthToken = await getClaudeAccessToken();
   if (!oauthToken) {
@@ -130,13 +132,31 @@ export async function startFluxyAgentQuery(
   }
 
   const abortController = new AbortController();
-  const basePrompt = readSystemPrompt(names?.botName, names?.humanName);
   const memoryFiles = readMemoryFiles();
 
-  // Build enriched system prompt with memory files and conversation history
-  let enrichedPrompt = basePrompt;
+  // Build enriched system prompt — use support prompt for customer-facing channels
+  let enrichedPrompt: string;
+  if (supportPrompt) {
+    // Customer-facing: use the skill's SUPPORT.md as the base prompt
+    enrichedPrompt = supportPrompt;
+    enrichedPrompt += `\n\n---\n# Your Identity\n\n## MYSELF.md\n${memoryFiles.myself}`;
+    enrichedPrompt += `\n\n## MEMORY.md\n${memoryFiles.memory}`;
+  } else {
+    // Human-facing: use the full main system prompt
+    const basePrompt = readSystemPrompt(names?.botName, names?.humanName);
+    enrichedPrompt = basePrompt;
+    enrichedPrompt += `\n\n---\n# Your Memory Files\n\n## MYSELF.md\n${memoryFiles.myself}\n\n## MYHUMAN.md\n${memoryFiles.myhuman}\n\n## MEMORY.md\n${memoryFiles.memory}\n\n---\n# Your Config Files\n\n## PULSE.json\n${memoryFiles.pulse}\n\n## CRONS.json\n${memoryFiles.crons}`;
+  }
 
-  enrichedPrompt += `\n\n---\n# Your Memory Files\n\n## MYSELF.md\n${memoryFiles.myself}\n\n## MYHUMAN.md\n${memoryFiles.myhuman}\n\n## MEMORY.md\n${memoryFiles.memory}\n\n---\n# Your Config Files\n\n## PULSE.json\n${memoryFiles.pulse}\n\n## CRONS.json\n${memoryFiles.crons}`;
+  // Inject channel config so the agent knows about active channels
+  try {
+    const { loadConfig: loadCfg } = await import('../shared/config.js');
+    const cfg = loadCfg();
+    const channels = (cfg as any).channels;
+    if (channels) {
+      enrichedPrompt += `\n\n---\n# Channel Config\n\`\`\`json\n${JSON.stringify(channels, null, 2)}\n\`\`\``;
+    }
+  } catch {}
 
   if (recentMessages?.length) {
     enrichedPrompt += `\n\n---\n# Recent Conversation\n${formatConversationHistory(recentMessages)}`;

package/supervisor/index.ts

@@ -19,6 +19,7 @@ import { startViteDevServers, stopViteDevServers } from './vite-dev.js';
 import { startScheduler, stopScheduler } from './scheduler.js';
 import { execSync, spawn as cpSpawn } from 'child_process';
 import crypto from 'crypto';
+import { ChannelManager } from './channels/manager.js';
 
 const DIST_FLUXY = path.join(PKG_DIR, 'dist-fluxy');
 
@@ -304,6 +305,14 @@ export async function startSupervisor() {
     'GET /api/portal/totp/status',
     'GET /api/portal/login/totp',
     'POST /api/portal/devices/revoke',
+    'GET /api/channels/status',
+    'GET /api/channels/whatsapp/qr',
+    'GET /api/channels/whatsapp/qr-page',
+    'POST /api/channels/whatsapp/connect',
+    'POST /api/channels/whatsapp/disconnect',
+    'POST /api/channels/whatsapp/logout',
+    'POST /api/channels/whatsapp/configure',
+    'POST /api/channels/send',
   ];
 
   function isExemptRoute(method: string, url: string): boolean {
@@ -366,6 +375,163 @@ export async function startSupervisor() {
       return;
     }
 
+    // ── Channel API routes (handled by supervisor, not worker) ──
+    if (req.url?.startsWith('/api/channels')) {
+      const channelPath = req.url.split('?')[0];
+      res.setHeader('Content-Type', 'application/json');
+      res.setHeader('Cache-Control', 'no-store, no-cache, must-revalidate');
+
+      // GET /api/channels/status — all channel statuses
+      if (req.method === 'GET' && channelPath === '/api/channels/status') {
+        res.writeHead(200);
+        res.end(JSON.stringify(channelManager.getStatuses()));
+        return;
+      }
+
+      // GET /api/channels/whatsapp/qr — raw QR SVG data
+      if (req.method === 'GET' && channelPath === '/api/channels/whatsapp/qr') {
+        const qr = channelManager.getQrCode('whatsapp');
+        res.writeHead(200);
+        res.end(JSON.stringify({ qr }));
+        return;
+      }
+
+      // GET /api/channels/whatsapp/qr-page — standalone QR scanning page
+      if (req.method === 'GET' && channelPath === '/api/channels/whatsapp/qr-page') {
+        res.setHeader('Content-Type', 'text/html');
+        const qr = channelManager.getQrCode('whatsapp');
+        const status = channelManager.getStatus('whatsapp');
+        const connected = status?.connected || false;
+        res.writeHead(200);
+        res.end(`<!DOCTYPE html><html><head><meta charset="UTF-8"><meta name="viewport" content="width=device-width,initial-scale=1">
+<title>WhatsApp QR</title>
+<style>
+  body{background:#222122;color:#fff;font-family:system-ui,-apple-system,sans-serif;display:flex;flex-direction:column;align-items:center;justify-content:center;height:100dvh;margin:0}
+  .qr-container{background:#fff;border-radius:16px;padding:24px;max-width:300px}
+  .qr-container svg{width:100%;height:auto}
+  .status{margin-top:20px;font-size:14px;opacity:0.7}
+  .connected{color:#4ade80;font-size:18px;font-weight:600}
+</style></head><body>
+${connected
+  ? '<div class="connected">Connected!</div><p class="status">WhatsApp is linked. You can close this page.</p>'
+  : qr
+    ? `<div class="qr-container">${qr}</div><p class="status">Scan with WhatsApp to link</p>`
+    : '<p class="status">Starting WhatsApp... Refresh in a moment.</p>'}
+${!connected ? '<script>setTimeout(()=>location.reload(),4000)</script>' : ''}
+</body></html>`);
+        return;
+      }
+
+      // POST /api/channels/whatsapp/connect — start WhatsApp connection (triggers QR)
+      if (req.method === 'POST' && channelPath === '/api/channels/whatsapp/connect') {
+        (async () => {
+          try {
+            // Enable WhatsApp in config
+            const cfg = loadConfig();
+            if (!cfg.channels) cfg.channels = {};
+            if (!cfg.channels.whatsapp) cfg.channels.whatsapp = { enabled: true, mode: 'channel' };
+            cfg.channels.whatsapp.enabled = true;
+            saveConfig(cfg);
+
+            await channelManager.connectWhatsApp();
+            res.writeHead(200);
+            res.end(JSON.stringify({ ok: true }));
+          } catch (err: any) {
+            res.writeHead(500);
+            res.end(JSON.stringify({ error: err.message }));
+          }
+        })();
+        return;
+      }
+
+      // POST /api/channels/whatsapp/disconnect — disconnect WhatsApp
+      if (req.method === 'POST' && channelPath === '/api/channels/whatsapp/disconnect') {
+        (async () => {
+          try {
+            await channelManager.disconnectChannel('whatsapp');
+            const cfg = loadConfig();
+            if (cfg.channels?.whatsapp) cfg.channels.whatsapp.enabled = false;
+            saveConfig(cfg);
+            res.writeHead(200);
+            res.end(JSON.stringify({ ok: true }));
+          } catch (err: any) {
+            res.writeHead(500);
+            res.end(JSON.stringify({ error: err.message }));
+          }
+        })();
+        return;
+      }
+
+      // POST /api/channels/whatsapp/logout — disconnect + delete credentials
+      if (req.method === 'POST' && channelPath === '/api/channels/whatsapp/logout') {
+        (async () => {
+          try {
+            await channelManager.logoutWhatsApp();
+            const cfg = loadConfig();
+            if (cfg.channels?.whatsapp) cfg.channels.whatsapp.enabled = false;
+            saveConfig(cfg);
+            res.writeHead(200);
+            res.end(JSON.stringify({ ok: true }));
+          } catch (err: any) {
+            res.writeHead(500);
+            res.end(JSON.stringify({ error: err.message }));
+          }
+        })();
+        return;
+      }
+
+      // POST /api/channels/whatsapp/configure — set mode + admins
+      if (req.method === 'POST' && channelPath === '/api/channels/whatsapp/configure') {
+        let body = '';
+        req.on('data', (chunk: Buffer) => { body += chunk.toString(); });
+        req.on('end', () => {
+          try {
+            const data = JSON.parse(body);
+            const cfg = loadConfig();
+            if (!cfg.channels) cfg.channels = {};
+            if (!cfg.channels.whatsapp) cfg.channels.whatsapp = { enabled: true, mode: 'channel' };
+            if (data.mode) cfg.channels.whatsapp.mode = data.mode;
+            if (data.admins !== undefined) cfg.channels.whatsapp.admins = data.admins;
+            saveConfig(cfg);
+            res.writeHead(200);
+            res.end(JSON.stringify({ ok: true, config: cfg.channels.whatsapp }));
+          } catch (err: any) {
+            res.writeHead(400);
+            res.end(JSON.stringify({ error: err.message }));
+          }
+        });
+        return;
+      }
+
+      // POST /api/channels/send — send a message via any channel
+      if (req.method === 'POST' && channelPath === '/api/channels/send') {
+        let body = '';
+        req.on('data', (chunk: Buffer) => { body += chunk.toString(); });
+        req.on('end', async () => {
+          try {
+            const { channel, to, text } = JSON.parse(body);
+            if (!channel || !to || !text) {
+              res.writeHead(400);
+              res.end(JSON.stringify({ error: 'Missing channel, to, or text' }));
+              return;
+            }
+            await channelManager.sendMessage(channel, to, text);
+            res.writeHead(200);
+            res.end(JSON.stringify({ ok: true }));
+          } catch (err: any) {
+            res.writeHead(500);
+            res.end(JSON.stringify({ error: err.message }));
+          }
+        });
+        return;
+      }
+
+      // Fallback for unknown channel routes
+      res.writeHead(404);
+      res.end(JSON.stringify({ error: 'Not found' }));
+      return;
+    }
+
     // API routes → handled in-process by worker Express app
     if (req.url?.startsWith('/api')) {
       // Internal supervisor calls (workerApi) bypass auth — they carry a per-process secret
@@ -1046,6 +1212,33 @@ export async function startSupervisor() {
     getModel: () => loadConfig().ai.model,
   });
 
+  // Initialize channel manager (WhatsApp, Telegram, etc.)
+  const channelManager = new ChannelManager({
+    broadcastFluxy,
+    workerApi,
+    restartBackend: async () => {
+      resetBackendRestarts();
+      await stopBackend();
+      spawnBackend(backendPort);
+    },
+    getModel: () => loadConfig().ai.model,
+  });
+
+  // Broadcast channel status changes to all connected chat clients
+  channelManager.onStatusChange((status) => {
+    broadcastFluxy('channel:status', status);
+    // Also broadcast QR code updates
+    if (status.info?.hasQr) {
+      const qr = channelManager.getQrCode(status.channel);
+      if (qr) broadcastFluxy('channel:qr', { channel: status.channel, qr });
+    }
+  });
+
+  // Auto-init channels (will connect WhatsApp if previously configured)
+  channelManager.init().catch((err) => {
+    log.warn(`[channels] Init failed: ${err.message}`);
+  });
+
   // Watch workspace files for changes — auto-restart backend
   // Catches edits from VS Code, CLI, or any external tool.
   // During agent turns, defers to bot:done (avoids mid-turn restarts).
@@ -1250,6 +1443,7 @@ export async function startSupervisor() {
   // Shutdown
   const shutdown = async () => {
     log.info('Shutting down...');
+    await channelManager.disconnectAll();
     stopScheduler();
     backendWatcher.close();
     workspaceWatcher.close();

package/worker/prompts/fluxy-system-prompt.txt

@@ -202,6 +202,94 @@ Complex cron tasks can have detailed instruction files in `tasks/{cron-id}.md`.
 
 ---
 
+## Channels (WhatsApp, Telegram, etc.)
+
+You can communicate through messaging channels beyond the chat bubble. Currently supported: **WhatsApp**.
+
+### CRITICAL: How WhatsApp Responses Work
+
+**Your text response IS the WhatsApp reply.** When you receive a message tagged with `[WhatsApp | ...]`, the supervisor takes whatever you respond with and sends it directly to WhatsApp. You do NOT need to use curl or `/api/channels/send` to reply — just respond normally as if you're talking to the person.
+
+**Do NOT use `/api/channels/send` to reply to incoming WhatsApp messages.** That endpoint is ONLY for proactive messages (during pulse, cron, or when you want to initiate a conversation). If you use it to reply, the person will get duplicate messages.
+
+**Adjust your style for WhatsApp:** Keep messages shorter and more conversational than chat. No markdown headers, no code blocks unless asked. Think texting, not email.
+
+### Channel Config
+
+Your channel configuration is injected below (if any channels are configured). It comes from `~/.fluxy/config.json` — a file OUTSIDE your workspace that the supervisor manages.
+
+### How Channels Work
+
+When a message arrives via WhatsApp, the supervisor wraps it with context:
+```
+[WhatsApp | 5511999888777 | customer | Alice]
+Hi, I'd like to schedule an appointment.
+```
+
+The format is: `[Channel | phone | role | name (optional)]`
+
+- **role=admin**: This is your human or an authorized admin. Use your normal personality, full capabilities, main system prompt.
+- **role=customer**: This is someone else messaging. You're in **support mode** — follow the instructions from your active skill's SUPPORT.md.
+
+### WhatsApp Modes
+
+**Channel Mode** (default): Your human's own WhatsApp number. Only self-chat triggers you — messages from other people are completely ignored. This is "just talk to me" mode.
+
+**Business Mode**: Fluxy has its own dedicated number. Numbers in the `admins` array get admin access (main system prompt). Everyone else is a customer (support prompt).
+
+### Setting Up WhatsApp
+
+When your human asks to configure WhatsApp:
+1. Start the connection: `curl -s -X POST http://localhost:3000/api/channels/whatsapp/connect`
+2. Tell them to open the QR page: `http://localhost:3000/api/channels/whatsapp/qr-page` (or create a dashboard page that embeds it)
+3. They scan the QR with their WhatsApp app
+4. The default mode is **channel** (self-chat only)
+
+To switch to **business mode** with admin numbers:
+```bash
+curl -s -X POST http://localhost:3000/api/channels/whatsapp/configure \
+  -H "Content-Type: application/json" \
+  -d '{"mode":"business","admins":["+17865551234","+5511999887766"]}'
+```
+
+### Sending Proactive Messages
+
+To INITIATE a WhatsApp message (during pulse, cron, or when you want to reach out first):
+```bash
+curl -s -X POST http://localhost:3000/api/channels/send \
+  -H "Content-Type: application/json" \
+  -d '{"channel":"whatsapp","to":"5511999888777","text":"Your appointment is confirmed for tomorrow at 2pm."}'
+```
+
+**Remember:** This is ONLY for starting new conversations or sending unprompted messages. When replying to an incoming message, just respond normally — the supervisor handles delivery.
+
+### Customer Conversation Logs
+
+When you finish a conversation with a **customer** via WhatsApp, save a summary to `whatsapp/{phone}.md`:
+- Key details from the conversation
+- Outcome (appointment scheduled, question answered, etc.)
+- Any follow-ups needed
+- Timestamp
+
+This is your memory of that customer. Next time they message, read their file first.
+
+### Channel API Reference
+
+| Endpoint | Method | Purpose |
+|----------|--------|---------|
+| `/api/channels/status` | GET | List all channel statuses |
+| `/api/channels/whatsapp/qr` | GET | Get current QR code SVG |
+| `/api/channels/whatsapp/qr-page` | GET | Standalone QR scanning page |
+| `/api/channels/whatsapp/connect` | POST | Start WhatsApp (triggers QR if needed) |
+| `/api/channels/whatsapp/disconnect` | POST | Disconnect WhatsApp |
+| `/api/channels/whatsapp/logout` | POST | Disconnect + delete credentials |
+| `/api/channels/whatsapp/configure` | POST | Set mode + admins array |
+| `/api/channels/send` | POST | Send proactive message via any channel |
+
+All endpoints are on `http://localhost:3000`.
+
+---
+
 ## Dashboard Linking
 
 When your human gives you a claim code (format: XXXX-XXXX-XXXX-XXXX) to link you to their fluxy.bot dashboard, read your relay token from `~/.fluxy/config.json` (field: `relay.token`) and verify it: `curl -s -X POST https://api.fluxy.bot/api/claim/verify -H "Content-Type: application/json" -H "Authorization: Bearer <relay_token>" -d '{"code":"<THE_CODE>"}'`. Tell your human whether it succeeded or failed.

package/workspace/client/src/App.tsx

@@ -161,7 +161,7 @@ export default function App() {
             <Route path="*" element={<DashboardPage />} />
           </Routes>
         </DashboardLayout>
-        <WorkspaceTour />
+        <WorkspaceTour disabled={showOnboard} />
       </ErrorBoundary>
 
       {showOnboard && (