fluxy-bot 0.15.0 → 0.15.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fluxy-bot",
-  "version": "0.15.0",
+  "version": "0.15.1",
   "releaseNotes": [
     "1. react router implemented",
     "2. new workspace design",
@@ -55,6 +55,7 @@
     "@clack/prompts": "^1.1.0",
     "@tailwindcss/vite": "^4.2.0",
     "@vitejs/plugin-react": "^6.0.1",
+    "@whiskeysockets/baileys": "^7.0.0-rc.9",
     "better-sqlite3": "^12.6.2",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",

package/scripts/install.ps1

@@ -244,6 +244,17 @@ function Install-Fluxy {
     } catch {}
     Pop-Location
 
+    # Install workspace dependencies (rebuilds native modules for this platform)
+    $wsDir = Join-Path $FLUXY_HOME "workspace"
+    if (Test-Path (Join-Path $wsDir "package.json")) {
+        Write-Down "Installing workspace dependencies..."
+        Push-Location $wsDir
+        try {
+            & $NPM install --omit=dev 2>$null
+        } catch {}
+        Pop-Location
+    }
+
     # Verify
     $cliPath = Join-Path $FLUXY_HOME "bin\cli.js"
     if (-not (Test-Path $cliPath)) {

package/scripts/install.sh

@@ -203,6 +203,12 @@ install_fluxy() {
   printf "  ${BLUE}↓${RESET}  Installing dependencies...\n"
   (cd "$FLUXY_HOME" && "$NPM" install --omit=dev 2>/dev/null)
 
+  # Install workspace dependencies (rebuilds native modules for this platform)
+  if [ -f "$FLUXY_HOME/workspace/package.json" ]; then
+    printf "  ${BLUE}↓${RESET}  Installing workspace dependencies...\n"
+    (cd "$FLUXY_HOME/workspace" && "$NPM" install --omit=dev 2>/dev/null)
+  fi
+
   # Verify
   if [ ! -f "$FLUXY_HOME/bin/cli.js" ]; then
     printf "  ${RED}✗${RESET}  Installation failed\n"

package/shared/config.ts

@@ -1,6 +1,14 @@
 import fs from 'fs';
 import { paths, DATA_DIR } from './paths.js';
 
+export interface ChannelConfig {
+  enabled: boolean;
+  /** 'shared' = user's own number, 'dedicated' = Fluxy has its own number */
+  mode: 'shared' | 'dedicated';
+  /** The human/owner's phone number (used for role resolution in dedicated mode) */
+  humanPhone?: string;
+}
+
 export interface BotConfig {
   port: number;
   username: string;
@@ -25,6 +33,9 @@ export interface BotConfig {
     privateKey: string;
     address: string;
   };
+  channels?: {
+    whatsapp?: ChannelConfig;
+  };
   tunnelUrl?: string;
 }
 

package/supervisor/channels/manager.ts

@@ -0,0 +1,393 @@
+/**
+ * Channel Manager — orchestrates multi-channel messaging.
+ *
+ * Responsibilities:
+ * - Manages channel providers (WhatsApp, Telegram, etc.)
+ * - Resolves sender role (human vs customer)
+ * - Routes inbound messages to the agent with appropriate system prompt
+ * - Routes outbound messages from agent/API back to channels
+ * - Manages parallel agent instances for customer conversations
+ */
+
+import fs from 'fs';
+import path from 'path';
+import { loadConfig } from '../../shared/config.js';
+import { WORKSPACE_DIR } from '../../shared/paths.js';
+import { log } from '../../shared/logger.js';
+import { startFluxyAgentQuery, type RecentMessage } from '../fluxy-agent.js';
+import { WhatsAppChannel } from './whatsapp.js';
+import type { ChannelConfig, ChannelProvider, ChannelStatus, ChannelType, InboundMessage, SenderRole } from './types.js';
+
+const MAX_CONCURRENT_AGENTS = 5;
+
+interface ChannelManagerOpts {
+  broadcastFluxy: (type: string, data: any) => void;
+  workerApi: (path: string, method?: string, body?: any) => Promise<any>;
+  restartBackend: () => void;
+  getModel: () => string;
+}
+
+interface ActiveAgentQuery {
+  sender: string;
+  channel: ChannelType;
+  abortController?: AbortController;
+}
+
+export class ChannelManager {
+  private providers = new Map<ChannelType, ChannelProvider>();
+  private opts: ChannelManagerOpts;
+  private activeAgents = new Map<string, ActiveAgentQuery>();
+  private messageQueue: InboundMessage[] = [];
+  private statusListeners: ((status: ChannelStatus) => void)[] = [];
+
+  constructor(opts: ChannelManagerOpts) {
+    this.opts = opts;
+  }
+
+  /** Initialize channels based on config */
+  async init(): Promise<void> {
+    const config = loadConfig();
+    const channelConfigs = (config as any).channels as Record<string, ChannelConfig> | undefined;
+
+    if (!channelConfigs?.whatsapp?.enabled) {
+      log.info('[channels] WhatsApp not enabled — skipping');
+      return;
+    }
+
+    log.info('[channels] Initializing WhatsApp channel...');
+    const whatsapp = new WhatsAppChannel(
+      (sender, senderName, text, fromMe) => this.handleInboundMessage('whatsapp', sender, senderName, text, fromMe),
+      (status) => this.handleStatusChange(status),
+    );
+    this.providers.set('whatsapp', whatsapp);
+
+    // Auto-connect if credentials exist (previously linked)
+    if (whatsapp.hasCredentials()) {
+      try {
+        await whatsapp.connect();
+      } catch (err: any) {
+        log.warn(`[channels] WhatsApp auto-connect failed: ${err.message}`);
+      }
+    }
+  }
+
+  /** Start WhatsApp connection (triggers QR flow if no credentials) */
+  async connectWhatsApp(): Promise<void> {
+    let provider = this.providers.get('whatsapp');
+    if (!provider) {
+      // Create provider on-demand if not initialized
+      const whatsapp = new WhatsAppChannel(
+        (sender, senderName, text, fromMe) => this.handleInboundMessage('whatsapp', sender, senderName, text, fromMe),
+        (status) => this.handleStatusChange(status),
+      );
+      this.providers.set('whatsapp', whatsapp);
+      provider = whatsapp;
+    }
+    await provider.connect();
+  }
+
+  /** Disconnect a specific channel */
+  async disconnectChannel(type: ChannelType): Promise<void> {
+    const provider = this.providers.get(type);
+    if (provider) {
+      await provider.disconnect();
+      this.providers.delete(type);
+    }
+  }
+
+  /** Disconnect all channels */
+  async disconnectAll(): Promise<void> {
+    for (const [, provider] of this.providers) {
+      await provider.disconnect();
+    }
+    this.providers.clear();
+  }
+
+  /** Send a message via a specific channel */
+  async sendMessage(channel: ChannelType, to: string, text: string): Promise<void> {
+    const provider = this.providers.get(channel);
+    if (!provider) throw new Error(`Channel ${channel} not available`);
+    await provider.sendMessage(to, text);
+  }
+
+  /** Get status of all channels */
+  getStatuses(): ChannelStatus[] {
+    return Array.from(this.providers.values()).map((p) => p.getStatus());
+  }
+
+  /** Get status of a specific channel */
+  getStatus(type: ChannelType): ChannelStatus | null {
+    return this.providers.get(type)?.getStatus() || null;
+  }
+
+  /** Get QR code SVG for a channel */
+  getQrCode(type: ChannelType): string | null {
+    return this.providers.get(type)?.getQrCode() || null;
+  }
+
+  /** Register a listener for status changes (used for WS broadcasting) */
+  onStatusChange(listener: (status: ChannelStatus) => void) {
+    this.statusListeners.push(listener);
+  }
+
+  /** Delete WhatsApp credentials and disconnect */
+  async logoutWhatsApp(): Promise<void> {
+    const provider = this.providers.get('whatsapp') as WhatsAppChannel | undefined;
+    if (provider) {
+      await provider.disconnect();
+      await provider.deleteCredentials();
+      this.providers.delete('whatsapp');
+    }
+  }
+
+  // ── Internal ──
+
+  private handleStatusChange(status: ChannelStatus) {
+    for (const listener of this.statusListeners) {
+      listener(status);
+    }
+  }
+
+  /** Resolve sender role based on channel config */
+  private resolveRole(channel: ChannelType, sender: string, fromMe: boolean): SenderRole {
+    const config = loadConfig();
+    const channelConfigs = (config as any).channels as Record<string, ChannelConfig> | undefined;
+    const channelConfig = channelConfigs?.[channel];
+
+    if (!channelConfig) return 'customer';
+
+    if (channelConfig.mode === 'shared') {
+      // Shared number mode: fromMe messages are from the human
+      return fromMe ? 'human' : 'customer';
+    }
+
+    // Dedicated number mode: check if sender matches human's phone
+    if (channelConfig.humanPhone) {
+      const senderPhone = sender.replace(/@.*/, '').replace(/[^0-9]/g, '');
+      const humanPhone = channelConfig.humanPhone.replace(/[^0-9]/g, '');
+      if (senderPhone === humanPhone) return 'human';
+    }
+
+    return 'customer';
+  }
+
+  /** Handle an incoming message from any channel */
+  private async handleInboundMessage(
+    channel: ChannelType,
+    sender: string,
+    senderName: string | undefined,
+    text: string,
+    fromMe: boolean,
+  ) {
+    const role = this.resolveRole(channel, sender, fromMe);
+
+    const message: InboundMessage = {
+      channel,
+      sender: sender.replace(/@.*/, ''),
+      senderName,
+      role,
+      text,
+      rawSender: sender,
+    };
+
+    log.info(`[channels] Inbound ${channel} | ${message.sender} | role=${role} | "${text.slice(0, 60)}"`);
+
+    if (role === 'human') {
+      await this.handleHumanMessage(message);
+    } else {
+      await this.handleCustomerMessage(message);
+    }
+  }
+
+  /** Handle message from the human/owner — mirrors to chat conversation */
+  private async handleHumanMessage(msg: InboundMessage) {
+    const { workerApi, broadcastFluxy, getModel } = this.opts;
+    const model = getModel();
+
+    // Get or create the human's WhatsApp conversation (mirrored with chat)
+    let convId: string | undefined;
+    try {
+      const ctx = await workerApi('/api/context/current');
+      if (ctx.conversationId) {
+        convId = ctx.conversationId;
+      } else {
+        const conv = await workerApi('/api/conversations', 'POST', {
+          title: `WhatsApp`,
+          model,
+        });
+        convId = conv.id;
+        await workerApi('/api/context/set', 'POST', { conversationId: convId });
+      }
+    } catch (err: any) {
+      log.warn(`[channels] Failed to get/create conversation: ${err.message}`);
+      return;
+    }
+
+    // Save user message to DB
+    try {
+      await workerApi(`/api/conversations/${convId}/messages`, 'POST', {
+        role: 'user',
+        content: msg.text,
+        meta: { model, channel: msg.channel },
+      });
+    } catch (err: any) {
+      log.warn(`[channels] DB persist error: ${err.message}`);
+    }
+
+    // Broadcast to chat clients (mirroring)
+    broadcastFluxy('chat:sync', {
+      conversationId: convId,
+      message: { role: 'user', content: msg.text, timestamp: new Date().toISOString() },
+    });
+
+    // Fetch agent/user names and recent messages
+    let botName = 'Fluxy', humanName = 'Human';
+    let recentMessages: RecentMessage[] = [];
+    try {
+      const [status, recentRaw] = await Promise.all([
+        workerApi('/api/onboard/status'),
+        workerApi(`/api/conversations/${convId}/messages/recent?limit=20`),
+      ]);
+      botName = status.agentName || 'Fluxy';
+      humanName = status.userName || 'Human';
+      if (Array.isArray(recentRaw)) {
+        const filtered = recentRaw.filter((m: any) => m.role === 'user' || m.role === 'assistant');
+        if (filtered.length > 0) {
+          recentMessages = filtered.slice(0, -1).map((m: any) => ({
+            role: m.role as 'user' | 'assistant',
+            content: m.content,
+          }));
+        }
+      }
+    } catch {}
+
+    // Run agent with main system prompt (same as chat)
+    const channelContext = `[WhatsApp | ${msg.sender} | human]\n`;
+
+    startFluxyAgentQuery(
+      convId,
+      channelContext + msg.text,
+      model,
+      (type, eventData) => {
+        if (type === 'bot:response' && eventData.content) {
+          // Send response back via WhatsApp
+          this.sendMessage(msg.channel, msg.rawSender, eventData.content).catch((err) => {
+            log.warn(`[channels] Failed to send WhatsApp reply: ${err.message}`);
+          });
+
+          // Save to DB
+          workerApi(`/api/conversations/${convId}/messages`, 'POST', {
+            role: 'assistant',
+            content: eventData.content,
+            meta: { model },
+          }).catch(() => {});
+        }
+
+        // Mirror streaming to chat clients
+        if (type === 'bot:token' || type === 'bot:response' || type === 'bot:typing' || type === 'bot:tool') {
+          broadcastFluxy(type, eventData);
+        }
+
+        if (type === 'bot:done' && eventData.usedFileTools) {
+          this.opts.restartBackend();
+        }
+      },
+      undefined,
+      undefined,
+      { botName, humanName },
+      recentMessages,
+    );
+  }
+
+  /** Handle message from a customer — runs support agent in parallel */
+  private async handleCustomerMessage(msg: InboundMessage) {
+    const agentKey = `${msg.channel}:${msg.sender}`;
+
+    // Check concurrent limit
+    if (this.activeAgents.size >= MAX_CONCURRENT_AGENTS && !this.activeAgents.has(agentKey)) {
+      // Queue the message
+      log.info(`[channels] Max concurrent agents reached — queuing message from ${msg.sender}`);
+      this.messageQueue.push(msg);
+      return;
+    }
+
+    const { workerApi, getModel } = this.opts;
+    const model = getModel();
+
+    // Load support system prompt from skill
+    const supportPrompt = this.loadSupportPrompt();
+
+    // Fetch agent/user names
+    let botName = 'Fluxy', humanName = 'Human';
+    try {
+      const status = await workerApi('/api/onboard/status');
+      botName = status.agentName || 'Fluxy';
+      humanName = status.userName || 'Human';
+    } catch {}
+
+    // Build channel context
+    const channelContext = `[WhatsApp | ${msg.sender} | customer${msg.senderName ? ` | ${msg.senderName}` : ''}]\n`;
+    const convId = `channel-${agentKey}-${Date.now()}`;
+
+    this.activeAgents.set(agentKey, { sender: msg.sender, channel: msg.channel });
+
+    startFluxyAgentQuery(
+      convId,
+      channelContext + msg.text,
+      model,
+      (type, eventData) => {
+        if (type === 'bot:response' && eventData.content) {
+          // Send response back via WhatsApp
+          this.sendMessage(msg.channel, msg.rawSender, eventData.content).catch((err) => {
+            log.warn(`[channels] Failed to send customer reply: ${err.message}`);
+          });
+        }
+
+        if (type === 'bot:done') {
+          this.activeAgents.delete(agentKey);
+
+          if (eventData.usedFileTools) {
+            this.opts.restartBackend();
+          }
+
+          // Process queued messages
+          this.processQueue();
+        }
+      },
+      undefined,
+      undefined,
+      { botName, humanName },
+      undefined,
+      supportPrompt,
+    );
+  }
+
+  /** Load customer-facing system prompt from skills */
+  private loadSupportPrompt(): string | undefined {
+    // Look for SUPPORT.md in any skill directory
+    const skillsDir = path.join(WORKSPACE_DIR, 'skills');
+    try {
+      for (const entry of fs.readdirSync(skillsDir, { withFileTypes: true })) {
+        if (!entry.isDirectory()) continue;
+        const supportPath = path.join(skillsDir, entry.name, 'SUPPORT.md');
+        if (fs.existsSync(supportPath)) {
+          const content = fs.readFileSync(supportPath, 'utf-8').trim();
+          if (content) {
+            log.info(`[channels] Loaded support prompt from skill: ${entry.name}`);
+            return content;
+          }
+        }
+      }
+    } catch {}
+    return undefined;
+  }
+
+  /** Process queued messages when an agent slot frees up */
+  private processQueue() {
+    while (this.messageQueue.length > 0 && this.activeAgents.size < MAX_CONCURRENT_AGENTS) {
+      const queued = this.messageQueue.shift()!;
+      log.info(`[channels] Processing queued message from ${queued.sender}`);
+      this.handleCustomerMessage(queued);
+    }
+  }
+}

package/supervisor/channels/types.ts

@@ -0,0 +1,57 @@
+/**
+ * Shared types for the multi-channel messaging system.
+ */
+
+export type ChannelType = 'whatsapp' | 'telegram';
+export type SenderRole = 'human' | 'customer';
+
+export interface ChannelConfig {
+  enabled: boolean;
+  /** 'shared' = user's own number, 'dedicated' = Fluxy has its own number */
+  mode: 'shared' | 'dedicated';
+  /** The human/owner's phone number (used for role resolution in dedicated mode) */
+  humanPhone?: string;
+}
+
+export interface InboundMessage {
+  channel: ChannelType;
+  /** Sender identifier (phone number / JID) */
+  sender: string;
+  /** Sender display name if available */
+  senderName?: string;
+  /** Resolved role of the sender */
+  role: SenderRole;
+  /** Message text content */
+  text: string;
+  /** Raw sender JID (channel-specific format) */
+  rawSender: string;
+}
+
+export interface OutboundMessage {
+  channel: ChannelType;
+  to: string;
+  text: string;
+}
+
+export interface ChannelStatus {
+  channel: ChannelType;
+  connected: boolean;
+  /** Additional info like phone number, QR state, etc. */
+  info?: Record<string, any>;
+}
+
+export interface ChannelProvider {
+  readonly type: ChannelType;
+  /** Start the channel connection (may trigger QR flow) */
+  connect(): Promise<void>;
+  /** Disconnect and clean up */
+  disconnect(): Promise<void>;
+  /** Send a text message */
+  sendMessage(to: string, text: string): Promise<void>;
+  /** Get current connection status */
+  getStatus(): ChannelStatus;
+  /** Get current QR code data (base64 SVG) or null if not in QR state */
+  getQrCode(): string | null;
+  /** Whether auth credentials exist (previously connected) */
+  hasCredentials(): boolean;
+}

package/supervisor/channels/whatsapp.ts

@@ -0,0 +1,252 @@
+/**
+ * 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; // raw QR string data
+  private qrSvg: string | null = null;  // SVG rendered QR
+  private onMessage: OnWhatsAppMessage;
+  private onStatusChange: (status: ChannelStatus) => void;
+  private reconnectTimer: ReturnType<typeof setTimeout> | null = null;
+  private intentionalDisconnect = false;
+
+  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 ──
+
+  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;
+        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 sender = msg.key.remoteJid || '';
+        const pushName = msg.pushName || undefined;
+
+        log.info(`[whatsapp] Message from ${sender} (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: 'shared' };
+            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 + human phone
+      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: 'shared' };
+            if (data.mode) cfg.channels.whatsapp.mode = data.mode;
+            if (data.humanPhone !== undefined) cfg.channels.whatsapp.humanPhone = data.humanPhone;
+            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,73 @@ 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**.
+
+### 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=human**: This is YOUR human (the owner). 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.
+
+### 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. Once connected, configure the mode:
+   - **Shared number** (default): Your human's own WhatsApp. Messages they send to themselves trigger you.
+   - **Dedicated number**: A separate phone/SIM for you. Configure with: `curl -s -X POST http://localhost:3000/api/channels/whatsapp/configure -H "Content-Type: application/json" -d '{"mode":"dedicated","humanPhone":"+1234567890"}'`
+
+### Sending Messages
+
+To send a WhatsApp message (during pulse, cron, or any time):
+```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."}'
+```
+
+### 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 + human phone number |
+| `/api/channels/send` | POST | Send 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/skills/whatsapp-support/.claude-plugin/plugin.json

@@ -0,0 +1,5 @@
+{
+  "name": "whatsapp-support",
+  "description": "WhatsApp customer support skill — handles incoming customer messages with a friendly support persona",
+  "version": "0.1.0"
+}

package/workspace/skills/whatsapp-support/SKILL.md

@@ -0,0 +1,21 @@
+# WhatsApp Support Skill
+
+This skill enables customer support via WhatsApp.
+
+## Setup
+
+1. Ask your human to configure WhatsApp: `curl -s -X POST http://localhost:3000/api/channels/whatsapp/connect`
+2. Direct them to scan the QR code at `http://localhost:3000/api/channels/whatsapp/qr-page`
+3. Once connected, configure the mode if needed (shared or dedicated number)
+
+## Sending Messages
+
+```bash
+curl -s -X POST http://localhost:3000/api/channels/send \
+  -H "Content-Type: application/json" \
+  -d '{"channel":"whatsapp","to":"PHONE_NUMBER","text":"Your message here"}'
+```
+
+## Customer Logs
+
+After each customer conversation, save a summary to `whatsapp/{phone}.md` so you remember them next time.

package/workspace/skills/whatsapp-support/SUPPORT.md

@@ -0,0 +1,38 @@
+# Support Mode
+
+You are a friendly and helpful assistant responding to a customer via WhatsApp. You are NOT talking to your human/owner — you are talking to someone who reached out for help.
+
+## Your Behavior
+
+- Be warm, professional, and concise — this is WhatsApp, not email. Keep messages short.
+- Greet the customer by name if you know it (check `whatsapp/{phone}.md` for past interactions).
+- Answer questions based on what you know from your memory files and any skill documents.
+- If you don't know the answer, say so honestly and offer to have the owner follow up.
+- Never reveal internal system details, file paths, or technical architecture.
+- Never run destructive commands or modify critical files during customer interactions.
+
+## What You Can Do
+
+- Answer FAQs and general questions
+- Provide information from files in your workspace
+- Look up data from your backend API (`/app/api/*`)
+- Send follow-up messages via the channel API
+
+## What You Should NOT Do
+
+- Share pricing or make commitments you're not sure about — defer to the owner
+- Access or share other customers' information
+- Run commands that modify the system (no Write/Edit to critical files)
+
+## Conversation Flow
+
+1. Greet the customer
+2. Understand what they need
+3. Help them or let them know the owner will follow up
+4. After the conversation, save a summary to `whatsapp/{phone}.md`
+
+## Message Style
+
+- Use short paragraphs (1-2 sentences max per message)
+- Use emojis sparingly — one or two is fine, don't overdo it
+- Be direct — WhatsApp users expect quick responses

package/workspace/skills/code-reviewer/.claude-plugin/plugin.json

@@ -1,5 +0,0 @@
-{
-  "name": "code-reviewer",
-  "version": "1.0.0",
-  "description": "Reviews code changes and provides improvement suggestions."
-}

package/workspace/skills/code-reviewer/SKILL.md

@@ -1,36 +0,0 @@
----
-name: code-reviewer
-description: Reviews code changes, provides suggestions for improvement, identifies bugs, and enforces best practices. Use this skill when the user asks you to review code, check for issues, suggest improvements, or audit changes before committing.
----
-
-# Code Reviewer
-
-## Overview
-This skill helps review code in the Fluxy workspace — identifying bugs, suggesting improvements, and enforcing best practices for the React + Express stack.
-
-## When to Activate
-- User asks to "review", "check", or "audit" code
-- User asks for feedback on their changes
-- User asks about code quality, best practices, or potential issues
-
-## Review Checklist
-
-### Frontend (React + Tailwind)
-1. Component structure: proper use of props, state, and effects
-2. Performance: unnecessary re-renders, missing memoization
-3. Accessibility: semantic HTML, ARIA attributes, keyboard navigation
-4. Styling: consistent use of Tailwind classes, responsive design
-5. Error handling: error boundaries, loading states, fallbacks
-
-### Backend (Express + SQLite)
-1. Route structure: proper HTTP methods, status codes, error responses
-2. Input validation: sanitize user input, check required fields
-3. Database: parameterized queries, proper error handling
-4. Security: no exposed secrets, proper auth checks
-5. Performance: avoid N+1 queries, use appropriate indexes
-
-## Output Format
-When reviewing code, provide:
-- **Issues**: Bugs or potential problems (with severity)
-- **Suggestions**: Improvements that would help (with rationale)
-- **Praise**: Things done well (reinforces good patterns)

package/workspace/skills/daily-standup/.claude-plugin/plugin.json

@@ -1,5 +0,0 @@
-{
-  "name": "daily-standup",
-  "version": "1.0.0",
-  "description": "Generates daily standup summaries from recent workspace activity."
-}

package/workspace/skills/daily-standup/SKILL.md

@@ -1,42 +0,0 @@
----
-name: daily-standup
-description: Generates daily standup summaries by analyzing recent file changes, git history, and workspace activity. Use this skill when the user asks for a standup update, daily summary, progress report, or wants to know what changed recently.
----
-
-# Daily Standup
-
-## Overview
-This skill generates concise daily standup reports by examining recent changes in the Fluxy workspace — git commits, file modifications, and project activity.
-
-## When to Activate
-- User asks for a "standup", "daily update", or "progress report"
-- User asks "what changed recently?" or "what did I work on?"
-- User wants a summary of recent activity
-
-## How to Generate a Standup
-
-1. **Check git log** for recent commits (last 24 hours or since last standup)
-2. **Check modified files** using git status and diff
-3. **Identify patterns**: new features, bug fixes, refactors, documentation
-
-## Output Format
-
-### Daily Standup — {date}
-
-**Completed:**
-- List of completed work items based on commits and changes
-
-**In Progress:**
-- Uncommitted changes or partially completed work
-
-**Blockers:**
-- Any issues identified from error logs or failing tests
-
-**Next Steps:**
-- Suggested priorities based on the current state of the project
-
-## Rules
-1. Keep it concise — no more than 2-3 bullet points per section
-2. Focus on what matters — skip trivial changes like formatting
-3. Use plain language — avoid overly technical jargon
-4. Link to specific files when helpful

package/workspace/skills/workspace-helper/.claude-plugin/plugin.json

@@ -1,5 +0,0 @@
-{
-  "name": "workspace-helper",
-  "version": "1.0.0",
-  "description": "Helps manage and understand the Fluxy workspace structure."
-}

package/workspace/skills/workspace-helper/SKILL.md

@@ -1,55 +0,0 @@
----
-name: workspace-helper
-description: Helps manage and understand the Fluxy workspace structure. Use this skill whenever the user asks about the project layout, file organization, where things are, how the workspace is structured, or needs help navigating the codebase. Also use when the user asks to scaffold new components, pages, or API routes.
----
-
-# Workspace Helper
-
-## Overview
-This skill helps navigate and manage the Fluxy workspace — a full-stack app with a React + Vite + Tailwind frontend and an Express backend.
-
-## Workspace Structure
-
-```
-workspace/
-  client/                 React + Vite + Tailwind frontend
-    index.html            HTML shell, PWA manifest
-    src/
-      main.tsx            React DOM entry
-      App.tsx             Root component with error boundary
-      components/         UI components
-  backend/
-    index.ts              Express server (port 3004, accessed at /app/api/*)
-  .env                    Environment variables for the backend
-  app.db                  SQLite database for workspace data
-  files/                  Uploaded file storage (audio, images, documents)
-```
-
-## Key Rules
-
-1. The **frontend** is served by Vite with HMR — changes are picked up instantly
-2. The **backend** runs on port 3004, proxied through `/app/api/*` — the `/app/api` prefix is stripped, so define routes as `/health` not `/app/api/health`
-3. The backend auto-restarts when you edit files
-4. You may ONLY modify files inside the `workspace/` directory
-5. NEVER touch `supervisor/`, `worker/`, `shared/`, or `bin/`
-
-## When Adding New Pages
-
-1. Create the component in `client/src/components/`
-2. Add a route in `client/src/App.tsx`
-3. Use Tailwind for styling — no separate CSS files needed
-
-## When Adding New API Routes
-
-1. Add the route in `backend/index.ts`
-2. Remember: routes are relative (e.g., `app.get('/my-route', ...)`)
-3. The frontend calls them at `/app/api/my-route`
-4. Use the existing `app.db` SQLite database if persistence is needed
-
-## When Asked "Where is X?"
-
-Read the relevant files to find the answer. Start with:
-- Frontend components: `client/src/components/`
-- App entry: `client/src/App.tsx`
-- Backend routes: `backend/index.ts`
-- Environment config: `.env`