@operor/core 0.1.0

package/src/Operor.ts

@@ -0,0 +1,2972 @@
+import EventEmitter from 'eventemitter3';
+import fs from 'fs/promises';
+import path from 'path';
+import yaml from 'js-yaml';
+import { Agent } from './Agent.js';
+import { InMemoryStore } from './InMemoryStore.js';
+import { KeywordIntentClassifier } from './KeywordIntentClassifier.js';
+import { GuardrailEngine } from './Guardrails.js';
+import { buildSystemPrompt } from './AgentLoader.js';
+import { AgentVersionStore } from './AgentVersionStore.js';
+import type { VersionSnapshot } from './AgentVersionStore.js';
+import type {
+  OperorConfig,
+  MessageProvider,
+  Skill,
+  IncomingMessage,
+  Customer,
+  Intent,
+  ConversationContext,
+  AgentConfig,
+  ConversationMessage,
+  MemoryStore,
+  IntentClassifier,
+  OutgoingMessage,
+} from './types.js';
+
+/**
+ * Truncate text at the last sentence boundary within maxLen.
+ * Falls back to last whitespace if no sentence-ending punctuation is found.
+ */
+function truncateAtSentence(text: string, maxLen: number): string {
+  if (text.length <= maxLen) return text;
+
+  const truncated = text.slice(0, maxLen);
+
+  // Try to find the last sentence-ending punctuation (. ! ? or Hebrew ׃)
+  const sentenceEnd = Math.max(
+    truncated.lastIndexOf('. '),
+    truncated.lastIndexOf('! '),
+    truncated.lastIndexOf('? '),
+    truncated.lastIndexOf('.\n'),
+    truncated.lastIndexOf('!\n'),
+    truncated.lastIndexOf('?\n'),
+  );
+
+  if (sentenceEnd > maxLen * 0.5) {
+    return truncated.slice(0, sentenceEnd + 1).trimEnd();
+  }
+
+  // Fall back to last whitespace
+  const lastSpace = truncated.lastIndexOf(' ');
+  if (lastSpace > maxLen * 0.5) {
+    return truncated.slice(0, lastSpace).trimEnd();
+  }
+
+  // Last resort: hard cut (no "..." appended)
+  return truncated.trimEnd();
+}
+
+/**
+ * Split text into chunks that fit within maxLen, breaking at paragraph
+ * boundaries (\n\n). Falls back to sentence splitting for oversized paragraphs.
+ */
+function splitIntoParagraphChunks(text: string, maxLen: number): string[] {
+  if (text.length <= maxLen) return [text];
+
+  const paragraphs = text.split(/\n\n+/);
+  const chunks: string[] = [];
+  let current = '';
+
+  for (const para of paragraphs) {
+    const candidate = current ? current + '\n\n' + para : para;
+
+    if (candidate.length <= maxLen) {
+      current = candidate;
+      continue;
+    }
+
+    // Adding this paragraph would exceed maxLen
+    if (current) {
+      chunks.push(current.trimEnd());
+      current = '';
+    }
+
+    // If the paragraph itself fits, start a new chunk with it
+    if (para.length <= maxLen) {
+      current = para;
+      continue;
+    }
+
+    // Single paragraph exceeds maxLen — split at sentence boundaries
+    let remaining = para;
+    while (remaining.length > maxLen) {
+      const piece = truncateAtSentence(remaining, maxLen);
+      chunks.push(piece.trimEnd());
+      remaining = remaining.slice(piece.length).trimStart();
+    }
+    if (remaining) {
+      current = remaining;
+    }
+  }
+
+  if (current) {
+    chunks.push(current.trimEnd());
+  }
+
+  return chunks.filter(Boolean);
+}
+
+interface PendingEdit {
+  agentName: string;
+  field: 'instructions' | 'identity' | 'soul';
+  section?: string;
+  content: string[];
+  createdAt: number;
+  state: 'capturing' | 'confirming';
+  newContent?: string;
+}
+
+interface PendingQuickstart {
+  step: 'question' | 'answer';
+  question?: string;
+  createdAt: number;
+}
+
+interface PendingSkillAdd {
+  skillName: string;
+  envVars: Record<string, string>;
+  pendingKeys: string[];
+  currentKey: string | null;
+  catalogEntry: any;
+  createdAt: number;
+}
+
+export class Operor extends EventEmitter {
+  private config: OperorConfig;
+  private providers: Map<string, MessageProvider> = new Map();
+  private agents: Map<string, Agent> = new Map();
+  private skills: Map<string, Skill> = new Map();
+  private memory: MemoryStore;
+  private intentClassifier: IntentClassifier;
+  private isRunning: boolean = false;
+  private messageBatches: Map<string, IncomingMessage[]> = new Map();
+  private batchTimers: Map<string, ReturnType<typeof setTimeout>> = new Map();
+  private batchWindowMs: number = 2000;
+  private autoAddAssistantMessages: boolean = true;
+  private pendingEdits: Map<string, PendingEdit> = new Map();
+  private pendingQuickstarts: Map<string, PendingQuickstart> = new Map();
+  private pendingSkillAdds: Map<string, PendingSkillAdd> = new Map();
+  private pendingFaqReplacements: Map<string, { question: string; answer: string; replaceId: string; expiresAt: number }> = new Map();
+  private versionStore: AgentVersionStore;
+
+  constructor(config: OperorConfig = {}) {
+    super();
+    this.config = config;
+    this.memory = config.memory || new InMemoryStore();
+    this.intentClassifier = config.intentClassifier || new KeywordIntentClassifier();
+    this.batchWindowMs = config.batchWindowMs ?? 2000;
+    this.autoAddAssistantMessages = config.autoAddAssistantMessages ?? true;
+    this.versionStore = new AgentVersionStore(config.agentsDir);
+    this.log('Operor initialized');
+
+    // Wire analytics collector (non-blocking)
+    if (config.analyticsCollector) {
+      config.analyticsCollector.attach(this);
+      this.log('Analytics collector attached');
+    }
+
+    // Wire copilot tracker (non-blocking)
+    if (config.copilotTracker) {
+      this.on('message:processed', (event: any) => {
+        config.copilotTracker!.maybeTrack({
+          query: event.message?.text,
+          channel: event.message?.channel || event.message?.provider,
+          customerPhone: event.message?.from,
+          response: event.response,
+        }).catch((err: any) => {
+          if (config.debug) console.warn('[Copilot] Tracking error:', err?.message);
+        });
+      });
+    }
+  }
+
+  /**
+   * Register a message provider (WhatsApp, Instagram, etc.)
+   */
+  async addProvider(provider: MessageProvider): Promise<void> {
+    this.log(`Adding provider: ${provider.name}`);
+
+    // Listen for incoming messages from this provider
+    provider.on('message', (message: IncomingMessage) => {
+      this.handleIncomingMessage(message).catch((error) => {
+        this.log(`Error handling message: ${error}`);
+        console.error('❌ Error in handleIncomingMessage:', error);
+        this.emit('error', { error, message });
+      });
+    });
+
+    this.providers.set(provider.name, provider);
+    this.log(`Provider added: ${provider.name}`);
+  }
+
+  /**
+   * Create and register an agent
+   */
+  createAgent(config: AgentConfig): Agent {
+    this.log(`Creating agent: ${config.name}`);
+    const agent = new Agent(config);
+    this.agents.set(agent.id, agent);
+    this.log(`Agent created: ${config.name} (${agent.id})`);
+    return agent;
+  }
+
+  /**
+   * Add a skill (MCP server, etc.)
+   */
+  async addSkill(skill: Skill): Promise<void> {
+    this.log(`Adding skill: ${skill.name}`);
+    await skill.initialize();
+    this.skills.set(skill.name, skill);
+    this.log(`Skill added: ${skill.name}`);
+  }
+
+  async removeSkill(name: string): Promise<void> {
+    const skill = this.skills.get(name);
+    if (skill) {
+      await skill.close();
+      this.skills.delete(name);
+      this.log(`Skill removed: ${name}`);
+    }
+  }
+
+  /**
+   * Start Operor
+   */
+  async start(): Promise<void> {
+    if (this.isRunning) {
+      throw new Error('Operor is already running');
+    }
+
+    this.log('Starting Operor...');
+
+    // Initialize memory store
+    await this.memory.initialize();
+
+    // Connect all providers
+    const providerConnections = Array.from(this.providers.values()).map((p) =>
+      p.connect()
+    );
+
+    await Promise.all(providerConnections);
+
+    this.isRunning = true;
+    this.log('✅ Operor started successfully');
+    this.emit('started');
+  }
+
+  /**
+   * Stop Operor
+   */
+  async stop(): Promise<void> {
+    if (!this.isRunning) return;
+
+    this.log('Stopping Operor...');
+
+    // Clear pending batch timers
+    for (const timer of this.batchTimers.values()) {
+      clearTimeout(timer);
+    }
+    this.batchTimers.clear();
+    this.messageBatches.clear();
+
+    // Disconnect all providers
+    const providerDisconnections = Array.from(this.providers.values()).map(
+      (p) => p.disconnect()
+    );
+
+    await Promise.all(providerDisconnections);
+
+    // Detach analytics collector
+    if (this.config.analyticsCollector?.detach) {
+      this.config.analyticsCollector.detach(this);
+    }
+
+    // Close memory store
+    await this.memory.close();
+
+    this.isRunning = false;
+    this.log('Operor stopped');
+    this.emit('stopped');
+  }
+
+  /**
+   * Handle incoming message from any provider
+   */
+  private async handleIncomingMessage(
+    message: IncomingMessage
+  ): Promise<void> {
+    this.log(`📱 Incoming message from ${message.from}: "${message.text}"`);
+
+    // Emit message event
+    this.emit('message:received', { message });
+
+    // Add to batch (include groupJid to prevent cross-group batching)
+    const groupJid = message.metadata?.groupJid;
+    const batchKey = groupJid
+      ? `${message.provider}:${message.from}:${groupJid}`
+      : `${message.provider}:${message.from}`;
+    if (!this.messageBatches.has(batchKey)) {
+      this.messageBatches.set(batchKey, []);
+    }
+    this.messageBatches.get(batchKey)!.push(message);
+
+    // Clear existing timer
+    const existingTimer = this.batchTimers.get(batchKey);
+    if (existingTimer) {
+      clearTimeout(existingTimer);
+    }
+
+    // Set new timer to process batch
+    const timer = setTimeout(() => {
+      this.processBatch(batchKey).catch((error) => {
+        this.log(`Error processing batch: ${error}`);
+        console.error('❌ Error in processBatch:', error);
+      });
+    }, this.batchWindowMs);
+
+    this.batchTimers.set(batchKey, timer);
+  }
+
+  /**
+   * Process a batch of messages from the same sender
+   */
+  private async processBatch(batchKey: string): Promise<void> {
+    const messages = this.messageBatches.get(batchKey);
+    if (!messages || messages.length === 0) return;
+
+    // Clear batch and timer
+    this.messageBatches.delete(batchKey);
+    this.batchTimers.delete(batchKey);
+
+    // Combine messages into one
+    const firstMessage = messages[0];
+    const combinedText = messages.map((m) => m.text).join('\n');
+    const combinedMessage: IncomingMessage = {
+      ...firstMessage,
+      text: combinedText,
+    };
+
+    if (messages.length > 1) {
+      this.log(`📦 Batched ${messages.length} messages: "${combinedText}"`);
+    }
+
+    // Pending quickstart interceptor — capture messages during /quickstart flow
+    if (this.config.trainingMode?.enabled) {
+      const pendingQs = this.pendingQuickstarts.get(combinedMessage.from);
+      if (pendingQs) {
+        const handled = await this.handlePendingQuickstart(combinedMessage, pendingQs);
+        if (handled) return;
+      }
+    }
+
+    // Pending skill add interceptor — capture env var values during /skill add flow
+    const pendingSkill = this.pendingSkillAdds.get(combinedMessage.from);
+    if (pendingSkill) {
+      const handled = await this.handlePendingSkillAdd(combinedMessage, pendingSkill);
+      if (handled) return;
+    }
+
+    // Pending edit interceptor — capture messages before training commands
+    if (this.config.trainingMode?.enabled) {
+      const pendingEdit = this.pendingEdits.get(combinedMessage.from);
+      if (pendingEdit) {
+        const handled = await this.handlePendingEdit(combinedMessage, pendingEdit);
+        if (handled) return;
+      }
+    }
+
+    // Pending FAQ replacement interceptor — handle "yes"/"no" for dedup prompt
+    if (this.config.trainingMode?.enabled) {
+      const faqKey = `faq_replace_${combinedMessage.from}`;
+      const pending = this.pendingFaqReplacements.get(faqKey);
+      if (pending && Date.now() < pending.expiresAt) {
+        const text = combinedMessage.text.trim().toLowerCase();
+        const kb = this.config.kb!;
+        const provider = this.providers.values().next().value;
+        const reply = async (t: string) => { if (provider) await provider.sendMessage(combinedMessage.from, t); };
+
+        this.pendingFaqReplacements.delete(faqKey);
+        if (text === 'yes') {
+          await kb.ingestFaq(pending.question, pending.answer, { forceReplace: true, replaceId: pending.replaceId });
+          await reply(`FAQ replaced:\nQ: ${pending.question}\nA: ${pending.answer}`);
+        } else {
+          await kb.ingestFaq(pending.question, pending.answer, { forceReplace: true });
+          await reply(`Both FAQs kept. New FAQ added:\nQ: ${pending.question}\nA: ${pending.answer}`);
+        }
+        return;
+      } else if (pending) {
+        this.pendingFaqReplacements.delete(faqKey); // expired
+      }
+    }
+
+    // Training mode interceptor — check before normal processing
+    if (this.config.trainingMode?.enabled) {
+      const senderPhone = combinedMessage.from;
+      // Normalize comparison: strip leading '+' from both sides so
+      // whitelist entry '+85253332683' matches from value '85253332683' and vice versa
+      const normalizePhone = (p: string) => p.replace(/^\+/, '');
+      const normalizedSender = normalizePhone(senderPhone);
+      const isWhitelisted = this.config.trainingMode.whitelist.some(
+        (w) => normalizePhone(w) === normalizedSender
+      );
+      if (isWhitelisted) {
+        const handled = await this.handleTrainingCommand(combinedMessage);
+        if (handled) return;
+        // Block unrecognized /commands from reaching the LLM (prevents hallucinated responses)
+        if (combinedMessage.text.trim().startsWith('/')) {
+          await this.sendMessage(combinedMessage.from, combinedMessage.provider, {
+            to: combinedMessage.from,
+            text: `Unknown command: ${combinedMessage.text.trim().split(/\s+/)[0]}\nType /help for available commands.`,
+          });
+          return;
+        }
+      }
+    }
+
+    try {
+      // Send typing indicator while processing
+      const provider = this.providers.get(combinedMessage.provider);
+      if (provider?.sendTypingIndicator) {
+        await provider.sendTypingIndicator(combinedMessage.from).catch(() => {});
+      }
+
+      // 1. Get or create customer
+      const customer = await this.getOrCreateCustomer(combinedMessage);
+
+      // 2. Load brief global history for intent classification (no agentId)
+      const globalHistory = await this.memory.getHistory(customer.id, 5);
+
+      // 3. Classify intent
+      const intentStart = Date.now();
+      const intent = await this.intentClassifier.classify(
+        combinedMessage.text,
+        Array.from(this.agents.values()).map(a => a.config),
+        globalHistory
+      );
+      this.log(`🧠 Intent: ${intent.intent} (confidence: ${intent.confidence}) in ${((Date.now() - intentStart) / 1000).toFixed(1)}s`);
+
+      // 4. Select appropriate agent (filtered by channel, sorted by priority)
+      const agent = this.selectAgent(intent, combinedMessage);
+
+      if (!agent) {
+        this.log('⚠️  No agent matched the intent');
+        await this.sendMessage(combinedMessage.from, combinedMessage.provider, {
+          to: combinedMessage.from,
+          text: "Sorry, I couldn't understand that. Could you rephrase?",
+        });
+        return;
+      }
+
+      this.log(`🤖 Agent selected: ${agent.name}`);
+
+      // 4b. Check input guardrails
+      const guardrails = agent.getConfig().guardrails;
+      if (guardrails) {
+        const guardrailEngine = new GuardrailEngine();
+        const inputCheck = guardrailEngine.checkInput(combinedMessage.text, guardrails);
+        if (!inputCheck.allowed) {
+          this.log(`🛡️ Guardrail blocked input: ${inputCheck.reason}`);
+          this.emit('guardrail:blocked', { message: combinedMessage, reason: inputCheck.reason, escalate: !!inputCheck.escalate });
+          const replyText = inputCheck.escalate
+            ? 'Let me connect you with a human agent for this.'
+            : "I'm not able to help with that topic. Is there something else I can assist you with?";
+          await this.sendMessage(combinedMessage.from, combinedMessage.provider, {
+            to: combinedMessage.from,
+            text: replyText,
+          });
+          return;
+        }
+      }
+
+      // 5. Load full agent-scoped history for processing context
+      const history = await this.memory.getHistory(customer.id, 50, agent.name);
+
+      // 6. Build context
+      const context: ConversationContext = {
+        customer,
+        history,
+        currentMessage: combinedMessage,
+        intent,
+      };
+
+      // 7. Process with agent
+      const response = await agent.process(context);
+
+      this.log(`✉️  Response generated in ${response.duration}ms`);
+
+      // 7b. Check output guardrails
+      const fullResponseText = response.text;
+      if (guardrails) {
+        const guardrailEngine = new GuardrailEngine();
+
+        // Handle maxResponseLength — split into multiple messages at paragraph boundaries
+        if (guardrails.maxResponseLength && response.text.length > guardrails.maxResponseLength) {
+          const chunks = splitIntoParagraphChunks(response.text, guardrails.maxResponseLength);
+          if (chunks.length > 1) {
+            this.log(`📨 Splitting long response (${response.text.length}/${guardrails.maxResponseLength}) into ${chunks.length} messages`);
+            // Send all chunks except the last one now
+            for (let i = 0; i < chunks.length - 1; i++) {
+              await this.sendMessage(combinedMessage.from, combinedMessage.provider, {
+                to: combinedMessage.from,
+                text: chunks[i],
+              });
+            }
+            // The last chunk goes through the normal send path (with any media attachment)
+            response.text = chunks[chunks.length - 1];
+          } else {
+            response.text = chunks[0];
+          }
+        }
+
+        // Check other guardrails (blocked topics, etc.) — exclude length from this check
+        const { maxResponseLength: _mrl, ...otherGuardrails } = guardrails;
+        const hasOtherGuardrails = otherGuardrails.blockedTopics?.length || otherGuardrails.escalationTriggers?.length;
+        if (hasOtherGuardrails) {
+          const outputCheck = guardrailEngine.checkOutput(response.text, otherGuardrails);
+          if (!outputCheck.allowed) {
+            this.log(`🛡️ Guardrail blocked output: ${outputCheck.reason}`);
+            this.emit('guardrail:output_blocked', { message: combinedMessage, reason: outputCheck.reason });
+            response.text = 'I apologize, but I\'m unable to provide that information.';
+          }
+        }
+      }
+
+      // Log tool calls
+      if (response.toolCalls) {
+        for (const toolCall of response.toolCalls) {
+          this.log(
+            `🔧 Tool: ${toolCall.name}(${JSON.stringify(toolCall.params)})`
+          );
+          if (toolCall.success) {
+            this.log(`   ✓ Success (${toolCall.duration}ms)`);
+          } else {
+            this.log(`   ✗ Failed: ${toolCall.error}`);
+          }
+        }
+      }
+
+      // 8. Send response
+      await this.sendMessage(combinedMessage.from, combinedMessage.provider, {
+        to: combinedMessage.from,
+        text: response.text,
+        ...(response.mediaBuffer && {
+          mediaBuffer: response.mediaBuffer,
+          mediaFileName: response.mediaFileName,
+          mediaMimeType: response.mediaMimeType,
+        }),
+      });
+
+      // Log what was actually sent
+      if (response.text) {
+        this.log(`📤 Sent: "${response.text.substring(0, 100)}${response.text.length > 100 ? '...' : ''}"`);
+      }
+
+      // 9. Update conversation history (add all batched messages)
+      for (const msg of messages) {
+        await this.memory.addMessage(customer.id, {
+          role: 'user',
+          content: msg.text,
+          timestamp: msg.timestamp,
+        }, agent.name);
+      }
+
+      // 10. Auto-add assistant message to history if enabled
+      if (this.autoAddAssistantMessages) {
+        await this.memory.addMessage(customer.id, {
+          role: 'assistant',
+          content: fullResponseText,
+          timestamp: Date.now(),
+          toolCalls: response.toolCalls,
+        }, agent.name);
+      }
+
+      // 11. Emit complete event
+      this.emit('message:processed', {
+        message: combinedMessage,
+        response,
+        agent: agent.name,
+        intent,
+        customer,
+        toolCalls: response.toolCalls,
+        duration: response.duration,
+        cost: response.cost,
+      });
+    } catch (error) {
+      this.log(`❌ Error processing message: ${error}`);
+      this.emit('error', { error, message: combinedMessage });
+
+      // Send error message to user
+      await this.sendMessage(combinedMessage.from, combinedMessage.provider, {
+        to: combinedMessage.from,
+        text: 'Sorry, something went wrong. Please try again.',
+      });
+    }
+  }
+
+  /**
+   * Get or create customer from message
+   */
+  private async getOrCreateCustomer(
+    message: IncomingMessage
+  ): Promise<Customer> {
+    let customer = await this.memory.getCustomerByPhone(message.from);
+
+    if (!customer) {
+      customer = {
+        id: `customer_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`,
+        phone: message.from,
+        name: message.from,
+        firstInteraction: new Date(),
+        lastInteraction: new Date(),
+      };
+
+      if (message.channel === 'whatsapp') {
+        customer.whatsappId = message.from;
+      }
+
+      await this.memory.upsertCustomer(customer);
+      this.log(`👤 New customer: ${customer.id}`);
+    } else {
+      customer.lastInteraction = new Date();
+      await this.memory.upsertCustomer(customer);
+    }
+
+    return customer;
+  }
+
+  /**
+   * Handle training commands from whitelisted users.
+   * Returns true if the message was a training command, false otherwise.
+   */
+  private async handleTrainingCommand(message: IncomingMessage): Promise<boolean> {
+    const text = message.text.trim();
+
+    // Must start with /
+    if (!text.startsWith('/')) return false;
+
+    const parts = text.split(/\s+/);
+    let command = parts[0].toLowerCase();
+    const args = parts.slice(1);
+
+    // Normalize aliases before validation
+    const commandAliases: Record<string, string> = { '/skill': '/skills' };
+    if (commandAliases[command]) command = commandAliases[command];
+
+    const validCommands = ['/teach', '/faq', '/kb', '/test', '/status', '/stats', '/help', '/learn-url', '/learn-site', '/learn-file', '/rebuild', '/review', '/export', '/import', '/instructions', '/identity', '/soul', '/config', '/done', '/cancel', '/whitelist', '/quickstart', '/skills', '/model', '/create-skill', '/update-skill', '/clear-history'];
+    if (!validCommands.includes(command)) return false;
+
+    this.log(`🎓 Training command: ${command} ${args.join(' ')}`);
+
+    // Emit training event for external handlers
+    this.emit('training:command', { command, args, message });
+
+    const reply = async (text: string) => {
+      await this.sendMessage(message.from, message.provider, {
+        to: message.from,
+        text,
+      });
+    };
+
+    const kb = this.config.kb;
+
+    if (command === '/help') {
+      const showAll = args[0] === 'all';
+
+      if (showAll) {
+        const helpLines = [
+          'Training commands:',
+          '  /teach <question> | <answer> — Add FAQ entry',
+          '  /learn-url <url> — Ingest a webpage into KB',
+          '  /learn-site <url> — Crawl and ingest a website',
+          '  /learn-file — Ingest an attached file (send with caption)',
+          '  /faq list — List all FAQ entries',
+          '  /faq search <query> — Search FAQ entries',
+          '  /faq delete <id> — Delete an FAQ entry',
+          '  /kb list [page] — List ingested documents (URLs, files)',
+          '  /export — Export KB bundle as YAML file',
+          '  /import — Import KB bundle from YAML file (send with caption)',
+          '  /import <url> — Import KB bundle from a URL',
+          '  /test <message> — Test KB response',
+          '  /rebuild — Rebuild all KB embeddings (after switching provider)',
+          '  /status — Show KB stats and bot status',
+          '  /stats — 7-day performance summary',
+          '  /stats today — Today\'s performance',
+          '  /stats kb — KB-specific analytics',
+          '  /help — Show quick help',
+          '  /help all — Show this full help message',
+        ];
+        helpLines.push('',
+          'Agent editor commands:',
+          '  /instructions — View instructions summary',
+          '  /instructions view [section] — View full or section',
+          '  /instructions edit [section] — Edit instructions',
+          '  /instructions history — Version history',
+          '  /instructions rollback [n] — Revert to version n',
+          '  /identity — View identity',
+          '  /identity edit — Edit identity',
+          '  /soul — View soul',
+          '  /soul edit — Edit soul',
+          '  /config show — View agent config',
+          '  /config set <key> <value> — Set config field',
+          '  /config add <key> <value> — Add to array field',
+          '  /config remove <key> <value> — Remove from array field',
+          '  /done — Finish editing (in edit mode)',
+          '  /cancel — Cancel editing',
+        );
+        if (this.config.copilotHandler) {
+          helpLines.push('  /review — Review unanswered questions (Copilot)');
+          helpLines.push('  /review help — See all review commands');
+        }
+        helpLines.push('',
+          'Admin commands:',
+          '  /whitelist — View whitelisted phone numbers',
+          '  /whitelist add <phone> — Add a phone number',
+          '  /whitelist remove <phone> — Remove a phone number',
+          '  /clear-history — Clear your conversation history',
+        );
+        helpLines.push('',
+          'Skills:',
+          '  /skills — List registered skills and tools',
+          '  /skills info <name> — Show skill details',
+          '  /skills catalog [category] — Browse available skills',
+          '  /skills add <name> — Install a skill from the catalog',
+          '  /skills remove <name> — Remove a skill',
+          '  /create-skill <name> | <instructions> — Create a prompt skill',
+          '  /update-skill <name> | <instructions> — Update a prompt skill',
+        );
+        helpLines.push('',
+          'Model management:',
+          '  /model — Show current LLM provider and model',
+          '  /model list — List available models per provider',
+          '  /model set <provider/model> — Switch LLM model',
+          '  /model key <provider> <key> — Add API key for a provider',
+        );
+        await reply(helpLines.join('\n'));
+      } else {
+        const quickLines = [
+          'Quick start:',
+          '  /teach <question> | <answer> — Add FAQ entry',
+          '  /test <message> — Test how your bot responds',
+          '  /status — Show bot status and KB stats',
+          '  /learn-url <url> — Ingest a webpage',
+          '  /learn-file — Ingest an attached document',
+          '  /skills — List registered skills and tools',
+          '  /skills catalog — Browse available skills',
+          '  /quickstart — Guided first FAQ setup',
+          '  /help all — See all commands',
+          '',
+          'Example: /teach What are your hours? | We\'re open 9am-5pm Mon-Fri',
+        ];
+        await reply(quickLines.join('\n'));
+      }
+      return true;
+    }
+
+    // /quickstart command — guided 3-step FAQ teaching
+    if (command === '/quickstart') {
+      if (!kb) {
+        await reply('Knowledge Base is not enabled. Set KB_ENABLED=true to use /quickstart.');
+        return true;
+      }
+      this.pendingQuickstarts.set(message.from, {
+        step: 'question',
+        createdAt: Date.now(),
+      });
+      await reply('Let\'s teach your agent its first FAQ!\n\nStep 1/3: What question do your customers ask?\n\n(Send the question, or /cancel to abort)');
+      return true;
+    }
+
+    // /whitelist command — does NOT require KB
+    if (command === '/whitelist') {
+      await this.handleWhitelistCommand(message, args, reply);
+      return true;
+    }
+
+    // /skills command — does NOT require KB
+    if (command === '/skills') {
+      await this.handleSkillsCommand(message, args, reply);
+      return true;
+    }
+
+    // /create-skill and /update-skill commands — do NOT require KB
+    if (command === '/create-skill') {
+      await this.handleCreateSkillCommand(message, args, reply);
+      return true;
+    }
+    if (command === '/update-skill') {
+      await this.handleUpdateSkillCommand(message, args, reply);
+      return true;
+    }
+
+    // Instruction editor commands — do NOT require KB
+    if (command === '/instructions' || command === '/identity' || command === '/soul' || command === '/config' || command === '/done' || command === '/cancel') {
+      try {
+        if (command === '/instructions') {
+          await this.handleInstructionsCommand(message, args, reply);
+        } else if (command === '/identity') {
+          await this.handleFieldViewOrEdit('identity', message, args, reply);
+        } else if (command === '/soul') {
+          await this.handleFieldViewOrEdit('soul', message, args, reply);
+        } else if (command === '/config') {
+          await this.handleConfigCommand(message, args, reply);
+        } else {
+          await reply('No active edit session. Use /instructions edit, /identity edit, or /soul edit to start.');
+        }
+      } catch (error: any) {
+        this.log(`Training command error: ${error.message}`);
+        await reply(`Error: ${error.message}`);
+      }
+      return true;
+    }
+
+    // /model command — does NOT require KB
+    if (command === '/model') {
+      try {
+        await this.handleModelCommand(args, reply);
+      } catch (error: any) {
+        this.log(`Training command error: ${error.message}`);
+        await reply(`Error: ${error.message}`);
+      }
+      return true;
+    }
+
+    // /clear-history command — does NOT require KB
+    if (command === '/clear-history') {
+      if (!this.memory?.clearHistory) {
+        await reply('Clear history is not supported by the current memory store.');
+        return true;
+      }
+      try {
+        const customer = await this.memory.getCustomerByPhone?.(message.from);
+        if (!customer) {
+          await reply('No conversation history found for your number.');
+          return true;
+        }
+        const { deletedCount } = await this.memory.clearHistory(customer.id);
+        await reply(`Cleared ${deletedCount} message(s) from your conversation history.`);
+      } catch (error: any) {
+        this.log(`Training command error: ${error.message}`);
+        await reply(`Error clearing history: ${error.message}`);
+      }
+      return true;
+    }
+
+    // All other commands require KB
+    if (!kb) {
+      await reply('Knowledge Base is not enabled. Set KB_ENABLED=true and configure embedding settings to use training commands.');
+      return true;
+    }
+
+    // Copilot /review command — delegate to copilot handler
+    if (command === '/review') {
+      if (this.config.copilotHandler) {
+        await this.config.copilotHandler.handleCommand(command, args.join(' '), message.from, reply);
+      } else {
+        await reply('Training Copilot is not available. If COPILOT_ENABLED=true is set, check startup logs for initialization errors.');
+      }
+      return true;
+    }
+
+    try {
+      if (command === '/teach') {
+        const raw = args.join(' ');
+        const sepIndex = raw.indexOf('|');
+        if (sepIndex === -1) {
+          await reply('Usage: /teach <question> | <answer>');
+          return true;
+        }
+        // Strip optional surrounding quotes so `/teach "q" | "a"` works the same as `/teach q | a`
+        const stripQuotes = (s: string) => s.replace(/^["']|["']$/g, '');
+        const question = stripQuotes(raw.slice(0, sepIndex).trim());
+        const answer = stripQuotes(raw.slice(sepIndex + 1).trim());
+        if (!question || !answer) {
+          await reply('Usage: /teach <question> | <answer>');
+          return true;
+        }
+        const doc = await kb.ingestFaq(question, answer);
+
+        // FAQ dedup: if similar FAQ exists, prompt admin to confirm replacement
+        if (doc.existingMatch) {
+          const match = doc.existingMatch;
+          // Store pending replacement info for this conversation
+          const pendingKey = `faq_replace_${msg.from}`;
+          this.pendingFaqReplacements.set(pendingKey, {
+            question,
+            answer,
+            replaceId: match.id,
+            expiresAt: Date.now() + 120_000, // 2 min TTL
+          });
+          await reply(
+            `Similar FAQ already exists (${(match.score * 100).toFixed(0)}% match):\n` +
+            `Q: ${match.question}\n` +
+            `A: ${match.answer}\n\n` +
+            `Reply "yes" to replace it with your new answer, or "no" to keep both.`
+          );
+          return true;
+        }
+
+        await reply(`FAQ added (${doc.id.slice(0, 8)}...):\nQ: ${question}\nA: ${answer}`);
+        // Warn if answer uses "you/your" which may sound wrong from the bot's perspective
+        const perspectivePattern = /\b(your name|you are\s+\w+|you work|you're\s+\w+)\b/i;
+        if (perspectivePattern.test(answer)) {
+          await reply(
+            '⚠️ Heads up: This answer uses "you/your" which may sound odd coming from the bot. '
+            + 'Consider rephrasing (e.g., "my name is..." instead of "your name is...").'
+          );
+        }
+      }
+
+      else if (command === '/faq') {
+        const subcommand = args[0]?.toLowerCase();
+
+        if (subcommand === 'list') {
+          const docs = await kb.listDocuments();
+          const faqs = docs.filter(d => d.sourceType === 'faq');
+          if (faqs.length === 0) {
+            await reply('No FAQ entries found.');
+          } else {
+            const lines = faqs.map(d =>
+              `[${d.id.slice(0, 8)}] ${d.title || d.content.slice(0, 60)}`
+            );
+            await reply(`FAQ entries (${faqs.length}):\n${lines.join('\n')}`);
+          }
+        }
+
+        else if (subcommand === 'search') {
+          const query = args.slice(1).join(' ');
+          if (!query) {
+            await reply('Usage: /faq search <query>');
+            return true;
+          }
+          const result = await kb.retrieve(query);
+          if (result.results.length === 0) {
+            await reply(`No results for "${query}".`);
+          } else {
+            const lines = result.results.slice(0, 5).map((r, i) =>
+              `${i + 1}. [${r.score.toFixed(2)}] ${r.document.title || r.chunk.content.slice(0, 60)}`
+            );
+            await reply(`Search results for "${query}":\n${lines.join('\n')}`);
+          }
+        }
+
+        else if (subcommand === 'delete') {
+          const id = args[1];
+          if (!id) {
+            await reply('Usage: /faq delete <id>');
+            return true;
+          }
+          // Support partial ID matching
+          const docs = await kb.listDocuments();
+          const match = docs.find(d => d.id === id || d.id.startsWith(id));
+          if (!match) {
+            await reply(`No document found with ID starting with "${id}".`);
+          } else {
+            await kb.deleteDocument(match.id);
+            await reply(`Deleted: ${match.title || match.id.slice(0, 8)}`);
+          }
+        }
+
+        else {
+          await reply('Usage: /faq list | /faq search <query> | /faq delete <id>');
+        }
+      }
+
+      else if (command === '/kb') {
+        const subcommand = args[0]?.toLowerCase();
+
+        if (subcommand === 'list') {
+          const page = parseInt(args[1]) || 1;
+          const PAGE_SIZE = 10;
+          const docs = await kb.listDocuments();
+          const nonFaq = docs.filter(d => d.sourceType !== 'faq');
+
+          if (nonFaq.length === 0) {
+            await reply('No KB documents found. Use /learn-url, /learn-site, or /learn-file to add content.');
+          } else {
+            const totalPages = Math.ceil(nonFaq.length / PAGE_SIZE);
+            const safePage = Math.max(1, Math.min(page, totalPages));
+            const slice = nonFaq.slice((safePage - 1) * PAGE_SIZE, safePage * PAGE_SIZE);
+
+            const lines = slice.map(d => {
+              const label = d.title || d.sourceUrl || d.fileName || d.content.slice(0, 60);
+              const truncLabel = label.length > 60 ? label.slice(0, 57) + '...' : label;
+              const source = d.sourceUrl
+                ? `\n  ${d.sourceUrl.length > 60 ? d.sourceUrl.slice(0, 57) + '...' : d.sourceUrl}`
+                : d.fileName ? `\n  ${d.fileName}` : '';
+              return `[${d.id.slice(0, 8)}] ${d.sourceType} — ${truncLabel}${source}`;
+            });
+
+            let header = `KB Documents (${nonFaq.length} total`;
+            if (totalPages > 1) header += `, page ${safePage}/${totalPages}`;
+            header += '):';
+
+            let msg = `${header}\n${lines.join('\n')}`;
+            if (totalPages > 1 && safePage < totalPages) {
+              msg += `\n\nSend /kb list ${safePage + 1} for next page.`;
+            }
+            await reply(msg);
+          }
+        } else {
+          await reply('Unknown /kb command. Available: /kb list');
+        }
+      }
+
+      else if (command === '/test') {
+        const query = args.join(' ');
+        if (!query) {
+          await reply('Usage: /test <message>');
+          return true;
+        }
+        const result = await kb.retrieve(query);
+        if (result.results.length === 0) {
+          await reply(`No KB match for: "${query}"`);
+        } else {
+          const top = result.results[0];
+          const matchType = result.isFaqMatch ? 'FAQ direct match' : 'KB search';
+          await reply(`Test: "${query}"\nMatch type: ${matchType}\nScore: ${top.score.toFixed(2)}\nContent: ${top.chunk.content.slice(0, 200)}`);
+        }
+      }
+
+      else if (command === '/stats') {
+        const analyticsStore = this.getAnalyticsStore();
+        if (!analyticsStore) {
+          await reply('Analytics is not enabled. Set ANALYTICS_ENABLED=true to track metrics.');
+          return true;
+        }
+
+        const subcommand = args[0]?.toLowerCase();
+
+        if (subcommand === 'kb') {
+          // KB-specific analytics
+          const now = Date.now();
+          const range = { from: now - 7 * 24 * 60 * 60 * 1000, to: now };
+          const kbStats = await analyticsStore.getKbStats(range);
+          const total = kbStats.totalQueries;
+
+          const lines = [
+            '📚 *KB Analytics (last 7 days)*',
+            '',
+            `🔍 ${total} total queries`,
+          ];
+
+          if (total > 0) {
+            const faqPct = kbStats.faqHitRate.toFixed(0);
+            const nonFaqCount = total - kbStats.faqHits;
+            const hybridPct = ((nonFaqCount / total) * 100).toFixed(0);
+            const missCount = kbStats.topMisses?.reduce((s: number, m: any) => s + m.count, 0) || 0;
+            const noMatchPct = ((missCount / total) * 100).toFixed(0);
+
+            lines.push(`⚡ FAQ fast-path: ${faqPct}%`);
+            lines.push(`🔄 Hybrid search: ${hybridPct}%`);
+            lines.push(`❌ No match: ${noMatchPct}%`);
+            lines.push(`📊 Avg top score: ${kbStats.avgTopScore.toFixed(2)}`);
+          }
+
+          if (kbStats.topFaqHits && kbStats.topFaqHits.length > 0) {
+            lines.push('');
+            lines.push('🎯 *Top FAQ hits:*');
+            for (const hit of kbStats.topFaqHits.slice(0, 5)) {
+              lines.push(`  ${hit.count}x — ${hit.intent}`);
+            }
+          }
+
+          if (kbStats.topMisses && kbStats.topMisses.length > 0) {
+            lines.push('');
+            lines.push('❓ *Top misses:*');
+            for (const miss of kbStats.topMisses.slice(0, 5)) {
+              lines.push(`  ${miss.count}x [${miss.avgScore.toFixed(2)}] — ${miss.intent}`);
+            }
+          }
+
+          await reply(lines.join('\n'));
+        } else {
+          // General stats — /stats or /stats today
+          const isToday = subcommand === 'today';
+          const now = Date.now();
+          const range = isToday
+            ? { from: new Date(new Date().setHours(0, 0, 0, 0)).getTime(), to: now }
+            : { from: now - 7 * 24 * 60 * 60 * 1000, to: now };
+
+          const summary = await analyticsStore.getSummary(range);
+          const label = isToday ? 'today' : 'last 7 days';
+
+          const noAnswerCount = Math.round((summary.noAnswerPct / 100) * summary.totalMessages);
+          const avgPerDay = Math.round(summary.avgPerDay);
+
+          const lines = [
+            `📊 *Bot Performance (${label})*`,
+            '',
+            `💬 ${summary.totalMessages} messages from ${summary.uniqueCustomers} customers`,
+          ];
+
+          if (!isToday && summary.totalMessages > 0 && summary.peakDay) {
+            const peakLabel = this.formatDayName(summary.peakDay);
+            lines.push(`📈 Avg ${avgPerDay}/day — busiest: ${peakLabel}`);
+          }
+
+          lines.push('');
+          lines.push(`✅ ${summary.kbAnsweredPct.toFixed(0)}% answered by KB`);
+          lines.push(`🤖 ${summary.llmFallbackPct.toFixed(0)}% needed LLM`);
+          lines.push(`❌ ${summary.noAnswerPct.toFixed(0)}% couldn't answer (${noAnswerCount} msgs)`);
+          lines.push('');
+          lines.push(`⚡ Avg response: ${(summary.avgResponseTime / 1000).toFixed(1)}s`);
+          lines.push(`🎯 FAQ hit rate: ${summary.faqHitRate.toFixed(0)}%`);
+          lines.push('');
+          lines.push(`👥 ${summary.newCustomers} new customers${isToday ? ' today' : ' this week'}`);
+          lines.push(`🔄 ${summary.returningCustomers} returning customers`);
+
+          if (summary.pendingReviews > 0) {
+            lines.push('');
+            lines.push(`📋 ${summary.pendingReviews} questions pending review`);
+            lines.push('→ /review to start teaching');
+          }
+
+          await reply(lines.join('\n'));
+        }
+      }
+
+      else if (command === '/status') {
+        const stats = await kb.getStats();
+        const statusLines = [
+          '📦 *Knowledge Base Status:*',
+          `  Documents: ${stats.documentCount}`,
+          `  Chunks: ${stats.chunkCount}`,
+          `  Embedding dimensions: ${stats.embeddingDimensions}`,
+          `  DB size: ${(stats.dbSizeBytes / 1024).toFixed(1)} KB`,
+        ];
+
+        // Append bot usage summary from analytics if available
+        const analyticsStore = this.getAnalyticsStore();
+        if (analyticsStore) {
+          try {
+            const summary = await analyticsStore.getSummary();
+            statusLines.push('');
+            statusLines.push('🤖 *Bot Status:*');
+            statusLines.push(`  Total messages processed: ${summary.totalMessages}`);
+            statusLines.push(`  Unique customers: ${summary.uniqueCustomers}`);
+            if (summary.pendingReviews > 0) {
+              statusLines.push(`  Pending reviews: ${summary.pendingReviews}`);
+            }
+            const uptime = process.uptime();
+            const uptimeStr = uptime >= 86400
+              ? `${Math.floor(uptime / 86400)}d ${Math.floor((uptime % 86400) / 3600)}h`
+              : uptime >= 3600
+                ? `${Math.floor(uptime / 3600)}h ${Math.floor((uptime % 3600) / 60)}m`
+                : `${Math.floor(uptime / 60)}m`;
+            statusLines.push(`  Uptime: ${uptimeStr}`);
+          } catch {
+            // Analytics query failed — skip silently
+          }
+        }
+
+        await reply(statusLines.join('\n'));
+      }
+
+      else if (command === '/learn-url') {
+        const url = args[0];
+        if (!url) {
+          await reply('Usage: /learn-url <url>');
+          return true;
+        }
+        if (!kb.ingestUrl) {
+          await reply('URL ingestion is not available. Ensure the KB runtime supports ingestUrl.');
+          return true;
+        }
+        try {
+          new URL(url);
+        } catch {
+          await reply(`Invalid URL: ${url}`);
+          return true;
+        }
+        await reply(`Ingesting URL: ${url}...`);
+        const result = await kb.ingestUrl(url);
+        const countLabel = (result as any).faqCount ? `${(result as any).faqCount} Q&A pairs` : `${result.chunks} chunks`;
+        await reply(`Done! Added "${result.title || url}" (${countLabel}).`);
+      }
+
+      else if (command === '/learn-site') {
+        const url = args[0];
+        if (!url) {
+          await reply('Usage: /learn-site <url>');
+          return true;
+        }
+        if (!kb.ingestSite) {
+          await reply('Site ingestion is not available. Ensure the KB runtime supports ingestSite.');
+          return true;
+        }
+        try {
+          new URL(url);
+        } catch {
+          await reply(`Invalid URL: ${url}`);
+          return true;
+        }
+        await reply(`Crawling site: ${url} (this may take a while)...`);
+        let lastProgressUpdate = 0;
+        const result = await kb.ingestSite(url, {
+          maxDepth: 2,
+          maxPages: 50,
+          onProgress: (crawled, total, pageUrl) => {
+            // Send progress update every 5 pages
+            if (crawled - lastProgressUpdate >= 5) {
+              lastProgressUpdate = crawled;
+              const shortUrl = pageUrl.length > 60 ? pageUrl.slice(0, 57) + '...' : pageUrl;
+              reply(`Crawling page ${crawled}/${total}: ${shortUrl}`);
+            }
+          },
+        });
+        await reply(`Done! Crawled ${result.documents} pages (${result.chunks} total chunks).`);
+      }
+
+      else if (command === '/learn-file') {
+        if (!kb.ingestFile) {
+          await reply('File ingestion is not available. Ensure the KB runtime supports ingestFile.');
+          return true;
+        }
+        if (!message.mediaBuffer || !message.mediaFileName) {
+          await reply('No file attached. Send a document (PDF, DOCX, TXT, CSV, etc.) with /learn-file as the caption.');
+          return true;
+        }
+        await reply(`Ingesting file: ${message.mediaFileName}...`);
+        const result = await kb.ingestFile(message.mediaBuffer, message.mediaFileName);
+        await reply(`Done! Added "${result.title || message.mediaFileName}" (${result.chunks} chunks).`);
+      }
+
+      else if (command === '/rebuild') {
+        if (!kb.rebuild) {
+          await reply('Rebuild is not available. Ensure the KB runtime supports rebuild.');
+          return true;
+        }
+        await reply('Rebuilding KB embeddings... This may take a while.');
+        const result = await kb.rebuild();
+        await reply([
+          'Rebuild complete!',
+          `  Documents: ${result.documentsRebuilt}`,
+          `  Chunks: ${result.chunksRebuilt}`,
+          `  Old dimensions: ${result.oldDimensions}`,
+          `  New dimensions: ${result.newDimensions}`,
+        ].join('\n'));
+      }
+
+      else if (command === '/export') {
+        await this.handleExportCommand(message, args);
+      }
+
+      else if (command === '/import') {
+        await this.handleImportCommand(message, args);
+      }
+
+    } catch (error: any) {
+      this.log(`Training command error: ${error.message}`);
+      await reply(`Error: ${error.message}`);
+    }
+
+    return true;
+  }
+
+  /**
+   * Handle /export command — generates YAML bundle and sends as file attachment
+   */
+  private async handleExportCommand(message: IncomingMessage, args: string[]): Promise<void> {
+    const kb = this.config.kb!;
+
+    const reply = async (text: string) => {
+      await this.sendMessage(message.from, message.provider, {
+        to: message.from,
+        text,
+      });
+    };
+
+    const replyWithFile = async (text: string, buffer: Buffer, fileName: string, mimeType: string) => {
+      await this.sendMessage(message.from, message.provider, {
+        to: message.from,
+        text,
+        mediaBuffer: buffer,
+        mediaFileName: fileName,
+        mediaMimeType: mimeType,
+      });
+    };
+
+    try {
+      await reply('Generating export bundle...');
+
+      // Gather KB data
+      const docs = await kb.listDocuments();
+      const faqs = docs.filter(d => d.sourceType === 'faq');
+      const nonFaqDocs = docs.filter(d => d.sourceType !== 'faq');
+
+      // Extract FAQ question/answer pairs
+      const faqEntries = faqs.map(d => {
+        const content = d.content;
+        const aIndex = content.indexOf('\nA: ');
+        if (aIndex !== -1 && content.startsWith('Q: ')) {
+          return {
+            question: content.slice(3, aIndex).trim(),
+            answer: content.slice(aIndex + 4).trim(),
+          };
+        }
+        // Fallback: use title as question, full content as answer
+        return { question: (d.title || content).trim(), answer: content.trim() };
+      });
+
+      // Extract document references (no full content — too large)
+      const documentRefs = nonFaqDocs.map(d => {
+        const ref: Record<string, any> = {
+          title: d.title || undefined,
+          sourceType: d.sourceType,
+        };
+        if (d.sourceUrl) ref.sourceUrl = d.sourceUrl;
+        if (d.fileName) ref.fileName = d.fileName;
+        return ref;
+      });
+
+      // Get first agent's config for metadata
+      const agentList = Array.from(this.agents.values());
+      const firstAgent = agentList[0];
+      const agentConfig = firstAgent?.getConfig();
+
+      // Build the export bundle
+      const bundle: Record<string, any> = {
+        version: 1,
+        exported_at: new Date().toISOString(),
+      };
+
+      if (agentConfig) {
+        const agentSection: Record<string, any> = { name: agentConfig.name };
+        if (agentConfig.purpose) agentSection.purpose = agentConfig.purpose;
+        if (agentConfig.triggers?.length) agentSection.triggers = agentConfig.triggers;
+        if (agentConfig.channels?.length) agentSection.channels = agentConfig.channels;
+        if (agentConfig.skills?.length) agentSection.skills = agentConfig.skills;
+        if (agentConfig.knowledgeBase != null) agentSection.knowledgeBase = agentConfig.knowledgeBase;
+        if (agentConfig.priority != null) agentSection.priority = agentConfig.priority;
+        if (agentConfig.escalateTo) agentSection.escalateTo = agentConfig.escalateTo;
+        if (agentConfig._rawInstructions) agentSection.instructions = agentConfig._rawInstructions;
+        if (agentConfig._rawIdentity) agentSection.identity = agentConfig._rawIdentity;
+        if (agentConfig._rawSoul) agentSection.soul = agentConfig._rawSoul;
+        bundle.agent = agentSection;
+
+        if (agentConfig.guardrails) {
+          const g: Record<string, any> = {};
+          if (agentConfig.guardrails.blockedTopics?.length) g.blockedTopics = agentConfig.guardrails.blockedTopics;
+          if (agentConfig.guardrails.systemRules?.length) g.systemRules = agentConfig.guardrails.systemRules;
+          if (agentConfig.guardrails.escalationTriggers?.length) g.escalationTriggers = agentConfig.guardrails.escalationTriggers;
+          if (agentConfig.guardrails.maxResponseLength) g.maxResponseLength = agentConfig.guardrails.maxResponseLength;
+          if (Object.keys(g).length > 0) bundle.guardrails = g;
+        }
+      }
+
+      bundle.faqs = faqEntries;
+      if (documentRefs.length > 0) {
+        bundle.documents = documentRefs;
+      }
+
+      // Include prompt skills from registered skills
+      const promptSkills = Array.from(this.skills.values())
+        .filter((s) => typeof (s as any).getContent === 'function')
+        .map((s) => {
+          const cfg = (s as any).getConfig?.() || {};
+          const entry: Record<string, any> = { name: s.name, content: (s as any).getContent() };
+          if (cfg.summary) entry.summary = cfg.summary;
+          if (cfg.tags?.length) entry.tags = cfg.tags;
+          if (cfg.author) entry.author = cfg.author;
+          return entry;
+        });
+      if (promptSkills.length > 0) {
+        bundle.promptSkills = promptSkills;
+      }
+
+      const yamlStr = '# operor-export-v1\n' + yaml.dump(bundle, { lineWidth: -1, noRefs: true });
+      const yamlBuffer = Buffer.from(yamlStr, 'utf-8');
+      const fileName = `operor-export-${new Date().toISOString().slice(0, 10)}.yaml`;
+
+      // Check if /export gist was requested
+      if (args[0]?.toLowerCase() === 'gist') {
+        const token = process.env.GITHUB_GIST_TOKEN;
+        if (!token) {
+          await reply('GitHub token not configured. Set GITHUB_GIST_TOKEN env var to use /export gist.');
+          return;
+        }
+        try {
+          const res = await fetch('https://api.github.com/gists', {
+            method: 'POST',
+            headers: {
+              'Authorization': `token ${token}`,
+              'Content-Type': 'application/json',
+              'Accept': 'application/vnd.github.v3+json',
+            },
+            body: JSON.stringify({
+              description: `Operor Export - ${new Date().toISOString().slice(0, 10)}`,
+              public: false,
+              files: { [fileName]: { content: yamlStr } },
+            }),
+          });
+          if (!res.ok) {
+            const errText = await res.text();
+            await reply(`GitHub Gist creation failed (${res.status}): ${errText.slice(0, 200)}`);
+            return;
+          }
+          const gist = await res.json() as { html_url: string; files: Record<string, { raw_url: string }> };
+          const rawUrl = gist.files[fileName]?.raw_url || gist.html_url;
+          await reply([
+            `Export published to GitHub Gist!`,
+            `${faqEntries.length} FAQs, ${documentRefs.length} document references.`,
+            ``,
+            `View: ${gist.html_url}`,
+            `Import URL: ${rawUrl}`,
+            ``,
+            `Share this URL with others: /import ${rawUrl}`,
+          ].join('\n'));
+        } catch (err: any) {
+          await reply(`Error creating GitHub Gist: ${err.message}`);
+        }
+        return;
+      }
+
+      // Send as file attachment
+      await replyWithFile(
+        `Export complete! ${faqEntries.length} FAQs, ${documentRefs.length} document references.`,
+        yamlBuffer,
+        fileName,
+        'text/yaml',
+      );
+    } catch (error: any) {
+      this.log(`Export error: ${error.message}`);
+      await reply(`Error: ${error.message}`);
+    }
+  }
+
+  /**
+   * Handle /import command — imports YAML bundle from file attachment or URL
+   */
+  private async handleImportCommand(message: IncomingMessage, args: string[]): Promise<void> {
+    const kb = this.config.kb!;
+
+    const reply = async (text: string) => {
+      await this.sendMessage(message.from, message.provider, {
+        to: message.from,
+        text,
+      });
+    };
+
+    try {
+      let yamlStr: string | null = null;
+
+      // Option 1: File attachment
+      if (message.mediaBuffer && message.mediaFileName) {
+        yamlStr = message.mediaBuffer.toString('utf-8');
+      }
+      // Option 2: URL argument
+      else if (args[0]) {
+        const url = args[0];
+        try {
+          new URL(url);
+        } catch {
+          await reply(`Invalid URL: ${url}`);
+          return;
+        }
+        await reply(`Fetching bundle from ${url}...`);
+        const res = await fetch(url);
+        if (!res.ok) {
+          await reply(`Failed to fetch URL (${res.status}): ${res.statusText}`);
+          return;
+        }
+        yamlStr = await res.text();
+      }
+      // No input provided
+      else {
+        await reply('Usage: /import <url> — or send a YAML file with /import as caption.');
+        return;
+      }
+
+      // Parse and validate YAML
+      let bundle: any;
+      try {
+        bundle = yaml.load(yamlStr);
+      } catch (err: any) {
+        await reply(`Invalid YAML: ${err.message}`);
+        return;
+      }
+
+      if (!bundle || typeof bundle !== 'object') {
+        await reply('Invalid bundle: expected a YAML object.');
+        return;
+      }
+
+      if (bundle.version !== 1) {
+        await reply(`Unsupported bundle version: ${bundle.version}. Expected version 1.`);
+        return;
+      }
+
+      const faqs = bundle.faqs;
+      if (!Array.isArray(faqs)) {
+        await reply('Invalid bundle: missing or invalid "faqs" array.');
+        return;
+      }
+
+      // Import FAQs
+      await reply(`Importing ${faqs.length} FAQs...`);
+      let imported = 0;
+      let skipped = 0;
+      for (const faq of faqs) {
+        const question = typeof faq.question === 'string' ? faq.question.trim() : '';
+        const answer = typeof faq.answer === 'string' ? faq.answer.trim() : '';
+        if (question && answer) {
+          await kb.ingestFaq(question, answer);
+          imported++;
+        } else {
+          skipped++;
+        }
+      }
+
+      // Summarize document references
+      const docRefs = Array.isArray(bundle.documents) ? bundle.documents : [];
+      const urlRefs = docRefs.filter((d: any) => d.sourceType === 'url' && d.sourceUrl);
+
+      const lines = [`Import complete! ${imported} FAQs imported.`];
+      if (skipped > 0) lines.push(`${skipped} FAQs skipped (missing question or answer).`);
+      if (docRefs.length > 0) {
+        lines.push(`${docRefs.length} document reference(s) found:`);
+        for (const ref of docRefs) {
+          if (ref.sourceUrl) {
+            lines.push(`  - ${ref.title || ref.sourceUrl} (${ref.sourceType})`);
+          } else if (ref.fileName) {
+            lines.push(`  - ${ref.fileName} (${ref.sourceType})`);
+          }
+        }
+        if (urlRefs.length > 0) {
+          lines.push(`\nTo re-ingest URLs, send /learn-url for each.`);
+        }
+      }
+
+      // Import agent instructions if present
+      const bundleAgent = bundle.agent;
+      if (bundleAgent && (bundleAgent.instructions || bundleAgent.identity || bundleAgent.soul)) {
+        const agentsDir = this.config.agentsDir;
+        const agentName = bundleAgent.name || 'support';
+
+        if (agentsDir) {
+          // Write agent files to disk
+          const agentDir = path.join(agentsDir, agentName);
+          await fs.mkdir(agentDir, { recursive: true });
+
+          // Reconstruct INSTRUCTIONS.md with YAML frontmatter
+          if (bundleAgent.instructions) {
+            const frontmatter: Record<string, any> = { name: agentName };
+            if (bundleAgent.purpose) frontmatter.purpose = bundleAgent.purpose;
+            if (bundleAgent.triggers?.length) frontmatter.triggers = bundleAgent.triggers;
+            if (bundleAgent.channels?.length) frontmatter.channels = bundleAgent.channels;
+            if (bundleAgent.skills?.length) frontmatter.skills = bundleAgent.skills;
+            if (bundleAgent.knowledgeBase != null) frontmatter.knowledgeBase = bundleAgent.knowledgeBase;
+            if (bundleAgent.priority != null) frontmatter.priority = bundleAgent.priority;
+            if (bundleAgent.escalateTo) frontmatter.escalateTo = bundleAgent.escalateTo;
+            if (bundle.guardrails) frontmatter.guardrails = bundle.guardrails;
+
+            const yamlFrontmatter = yaml.dump(frontmatter, { lineWidth: -1, noRefs: true }).trim();
+            const instructionsContent = `---\n${yamlFrontmatter}\n---\n\n${bundleAgent.instructions.trim()}\n`;
+            await fs.writeFile(path.join(agentDir, 'INSTRUCTIONS.md'), instructionsContent, 'utf-8');
+          }
+
+          if (bundleAgent.identity) {
+            await fs.writeFile(path.join(agentDir, 'IDENTITY.md'), bundleAgent.identity.trim() + '\n', 'utf-8');
+          }
+
+          if (bundleAgent.soul) {
+            await fs.writeFile(path.join(agentDir, 'SOUL.md'), bundleAgent.soul.trim() + '\n', 'utf-8');
+          }
+
+          lines.push(`Agent instructions written to ${agentDir}.`);
+        } else {
+          // No agentsDir — update the in-memory agent's config
+          const agentList = Array.from(this.agents.values());
+          const targetAgent = agentList.find(a => a.getConfig().name === agentName) || agentList[0];
+          if (targetAgent) {
+            // Mutate the agent's config directly — getConfig() returns a shallow copy,
+            // so we must use the public config property to persist changes.
+            if (bundleAgent.instructions) targetAgent.config._rawInstructions = bundleAgent.instructions;
+            if (bundleAgent.identity) targetAgent.config._rawIdentity = bundleAgent.identity;
+            if (bundleAgent.soul) targetAgent.config._rawSoul = bundleAgent.soul;
+            lines.push('Agent instructions applied in-memory.');
+          }
+        }
+      }
+
+      // Import prompt skills if present
+      if (Array.isArray(bundle.promptSkills) && bundle.promptSkills.length > 0) {
+        const mod = this.config.skillsModule;
+        if (mod) {
+          try {
+            const skillsConfig = mod.loadSkillsConfig();
+            let added = 0;
+            for (const ps of bundle.promptSkills) {
+              if (!ps.name || !ps.content) continue;
+              if (skillsConfig.skills.find((s: any) => s.name === ps.name)) continue;
+              skillsConfig.skills.push({ type: 'prompt', name: ps.name, content: ps.content, summary: ps.summary, tags: ps.tags, author: ps.author, enabled: true });
+              added++;
+            }
+            if (added > 0) {
+              mod.saveSkillsConfig(skillsConfig);
+              lines.push(`${added} prompt skill(s) imported to mcp.json.`);
+            }
+          } catch (err: any) {
+            lines.push(`Warning: failed to import prompt skills: ${err.message}`);
+          }
+        }
+      }
+
+      await reply(lines.join('\n'));
+    } catch (error: any) {
+      this.log(`Import error: ${error.message}`);
+      await reply(`Error: ${error.message}`);
+    }
+  }
+
+  /**
+   * Handle messages when sender has an active edit session.
+   */
+  private async handlePendingEdit(message: IncomingMessage, edit: PendingEdit): Promise<boolean> {
+    const text = message.text.trim();
+    const reply = async (t: string) => {
+      await this.sendMessage(message.from, message.provider, { to: message.from, text: t });
+    };
+
+    // Check TTL (2 minutes)
+    if (Date.now() - edit.createdAt > 120_000) {
+      this.pendingEdits.delete(message.from);
+      await reply('Edit session expired (2 min timeout). Start again with /instructions edit, /identity edit, or /soul edit.');
+      return true;
+    }
+
+    if (edit.state === 'confirming') {
+      if (text.toLowerCase() === 'yes') {
+        await this.applyEdit(message.from, edit, reply);
+      } else {
+        this.pendingEdits.delete(message.from);
+        await reply('Edit cancelled.');
+      }
+      return true;
+    }
+
+    // State: capturing
+    if (text === '/cancel') {
+      this.pendingEdits.delete(message.from);
+      await reply('Edit cancelled.');
+      return true;
+    }
+
+    if (text === '/done') {
+      const newContent = edit.content.join('\n');
+      const agent = this.getFirstAgent();
+      if (!agent) { await reply('No agent found.'); return true; }
+
+      const fieldMap = { instructions: '_rawInstructions', identity: '_rawIdentity', soul: '_rawSoul' } as const;
+      const current = (agent.config as any)[fieldMap[edit.field]] || '(empty)';
+
+      let currentDisplay = current;
+      let newDisplay = newContent;
+      if (edit.field === 'instructions' && edit.section) {
+        currentDisplay = this.extractSection(current, edit.section) || '(section not found)';
+        newDisplay = newContent;
+      }
+
+      // Truncate for display
+      const maxDisplay = 1500;
+      if (currentDisplay.length > maxDisplay) currentDisplay = currentDisplay.slice(0, maxDisplay) + '\n...';
+      if (newDisplay.length > maxDisplay) newDisplay = newDisplay.slice(0, maxDisplay) + '\n...';
+
+      edit.state = 'confirming';
+      await reply(`*CURRENT ${edit.field}${edit.section ? ` (${edit.section})` : ''}:*\n${currentDisplay}\n\n*NEW:*\n${newDisplay}\n\nSend "yes" to apply or anything else to cancel.`);
+      return true;
+    }
+
+    // Capture content
+    edit.content.push(text);
+    return true;
+  }
+
+  /**
+   * Apply a confirmed edit.
+   */
+  private async applyEdit(sender: string, edit: PendingEdit, reply: (t: string) => Promise<void>): Promise<void> {
+    this.pendingEdits.delete(sender);
+    const agent = this.getFirstAgent();
+    if (!agent) { await reply('No agent found.'); return; }
+
+    const newContent = edit.content.join('\n');
+    const fieldMap = { instructions: '_rawInstructions', identity: '_rawIdentity', soul: '_rawSoul' } as const;
+    const rawKey = fieldMap[edit.field];
+
+    // Save version before editing
+    await this.versionStore.saveVersion(edit.agentName, {
+      timestamp: new Date().toISOString(),
+      instructions: agent.config._rawInstructions,
+      identity: agent.config._rawIdentity,
+      soul: agent.config._rawSoul,
+      frontmatter: this.extractFrontmatter(agent.config),
+      editedBy: sender,
+      changeDescription: `Edit ${edit.field}${edit.section ? ` section "${edit.section}"` : ''}`,
+    });
+
+    // Apply edit
+    if (edit.field === 'instructions' && edit.section) {
+      const current = agent.config._rawInstructions || '';
+      agent.config._rawInstructions = this.replaceSection(current, edit.section, newContent);
+    } else {
+      (agent.config as any)[rawKey] = newContent;
+    }
+
+    // Rebuild system prompt
+    this.rebuildAgentSystemPrompt(agent);
+
+    // Write to disk if agentsDir configured
+    await this.writeAgentFiles(edit.agentName, agent);
+
+    await reply(`${edit.field} updated successfully.`);
+  }
+
+  /**
+   * Handle messages when sender has an active /quickstart session.
+   */
+  private async handlePendingQuickstart(message: IncomingMessage, qs: PendingQuickstart): Promise<boolean> {
+    const text = message.text.trim();
+    const reply = async (t: string) => {
+      await this.sendMessage(message.from, message.provider, { to: message.from, text: t });
+    };
+
+    // Check TTL (2 minutes)
+    if (Date.now() - qs.createdAt > 120_000) {
+      this.pendingQuickstarts.delete(message.from);
+      await reply('Quickstart session expired (2 min timeout). Send /quickstart to try again.');
+      return true;
+    }
+
+    if (text === '/cancel') {
+      this.pendingQuickstarts.delete(message.from);
+      await reply('Quickstart cancelled.');
+      return true;
+    }
+
+    const kb = this.config.kb;
+    if (!kb) {
+      this.pendingQuickstarts.delete(message.from);
+      await reply('Knowledge Base is not available.');
+      return true;
+    }
+
+    if (qs.step === 'question') {
+      qs.question = text;
+      qs.step = 'answer';
+      qs.createdAt = Date.now(); // reset TTL
+      await reply(`Got it!\n\nStep 2/3: What should the agent answer?\n\nQ: "${text}"\n\n(Send the answer, or /cancel to abort)`);
+      return true;
+    }
+
+    if (qs.step === 'answer') {
+      const question = qs.question!;
+      const answer = text;
+      this.pendingQuickstarts.delete(message.from);
+
+      // Step 3: auto-teach + auto-test
+      try {
+        const doc = await kb.ingestFaq(question, answer);
+        const result = await kb.retrieve(question);
+        const top = result.results[0];
+        const score = top ? top.score.toFixed(2) : 'N/A';
+        const matchType = result.isFaqMatch ? 'FAQ direct match' : 'KB search';
+
+        await reply([
+          'Step 3/3: Teaching & testing...',
+          '',
+          `FAQ added (${doc.id.slice(0, 8)}...)`,
+          `  Q: ${question}`,
+          `  A: ${answer}`,
+          '',
+          `Test result: ${matchType} (score: ${score})`,
+          '',
+          'Your agent just learned its first answer! Try sending the question as a regular message to see it in action.',
+          '',
+          'Next steps:',
+          '  /teach <question> | <answer> — add more FAQs',
+          '  /test <message> — test KB responses',
+          '  /help — see all commands',
+        ].join('\n'));
+      } catch (error: any) {
+        await reply(`Error during quickstart: ${error.message}`);
+      }
+      return true;
+    }
+
+    return false;
+  }
+
+  /**
+   * Add assistant response to conversation history (public API for manual use)
+   */
+  async addAssistantMessage(customerId: string, text: string, toolCalls?: any[]): Promise<void> {
+    await this.memory.addMessage(customerId, {
+      role: 'assistant',
+      content: text,
+      timestamp: Date.now(),
+      toolCalls,
+    });
+  }
+
+  private async handleInstructionsCommand(message: IncomingMessage, args: string[], reply: (t: string) => Promise<void>): Promise<void> {
+    const agent = this.getFirstAgent();
+    if (!agent) { await reply('No agent found.'); return; }
+    const sub = args[0]?.toLowerCase();
+    const raw = agent.config._rawInstructions || '';
+
+    if (sub === 'edit') {
+      const section = args.slice(1).join(' ') || undefined;
+      this.pendingEdits.set(message.from, {
+        agentName: agent.config.name, field: 'instructions', section,
+        content: [], createdAt: Date.now(), state: 'capturing',
+      });
+      const label = section ? `section "${section}"` : 'full instructions';
+      await reply(`Editing ${label}. Send your new content, then /done to apply or /cancel to abort. (2 min timeout)`);
+      return;
+    }
+
+    if (sub === 'view') {
+      const section = args.slice(1).join(' ') || undefined;
+      let content = section ? (this.extractSection(raw, section) || `Section "${section}" not found.`) : raw;
+      if (!content.trim()) { await reply('Instructions are empty.'); return; }
+      // Paginate at 2500 chars
+      if (content.length > 2500) {
+        await reply(content.slice(0, 2500) + '\n\n(truncated — send /instructions view again for full)');
+      } else {
+        await reply(content);
+      }
+      return;
+    }
+
+    if (sub === 'history') {
+      const history = await this.versionStore.getHistory(agent.config.name, 10);
+      if (history.length === 0) { await reply('No version history.'); return; }
+      const lines = history.map((v, i) =>
+        `${i}. ${v.timestamp} — ${v.changeDescription || 'no description'}${v.editedBy ? ` (by ${v.editedBy})` : ''}`
+      );
+      await reply(`Version history:\n${lines.join('\n')}`);
+      return;
+    }
+
+    if (sub === 'rollback') {
+      const n = args[1] != null ? parseInt(args[1]) : 0;
+      const version = await this.versionStore.getVersion(agent.config.name, n);
+      if (!version) { await reply(`Version ${n} not found.`); return; }
+
+      // Save current as new version before rollback
+      await this.versionStore.saveVersion(agent.config.name, {
+        timestamp: new Date().toISOString(),
+        instructions: agent.config._rawInstructions,
+        identity: agent.config._rawIdentity,
+        soul: agent.config._rawSoul,
+        frontmatter: this.extractFrontmatter(agent.config),
+        editedBy: message.from,
+        changeDescription: `Rollback to version ${n}`,
+      });
+
+      if (version.instructions !== undefined) agent.config._rawInstructions = version.instructions;
+      if (version.identity !== undefined) agent.config._rawIdentity = version.identity;
+      if (version.soul !== undefined) agent.config._rawSoul = version.soul;
+      this.rebuildAgentSystemPrompt(agent);
+      await this.writeAgentFiles(agent.config.name, agent);
+      await reply(`Rolled back to version ${n} (${version.timestamp}).`);
+      return;
+    }
+
+    // Default: summary — show sections list
+    if (!raw.trim()) { await reply('Instructions are empty.'); return; }
+    const sections = this.parseSections(raw);
+    if (sections.length === 0) {
+      await reply(`Instructions (${raw.length} chars):\n${raw.slice(0, 500)}${raw.length > 500 ? '\n...' : ''}`);
+    } else {
+      const lines = sections.map(s => `  ${s.heading} (${s.content.length} chars)`);
+      await reply(`Instructions sections:\n${lines.join('\n')}\n\nUse /instructions view [section] to see details.`);
+    }
+  }
+
+  private async handleFieldViewOrEdit(
+    field: 'identity' | 'soul', message: IncomingMessage, args: string[], reply: (t: string) => Promise<void>,
+  ): Promise<void> {
+    const agent = this.getFirstAgent();
+    if (!agent) { await reply('No agent found.'); return; }
+    const rawKey = field === 'identity' ? '_rawIdentity' : '_rawSoul';
+    const current = (agent.config as any)[rawKey] || '';
+
+    if (args[0]?.toLowerCase() === 'edit') {
+      this.pendingEdits.set(message.from, {
+        agentName: agent.config.name, field, content: [], createdAt: Date.now(), state: 'capturing',
+      });
+      await reply(`Editing ${field}. Send your new content, then /done to apply or /cancel to abort. (2 min timeout)`);
+      return;
+    }
+
+    // View
+    if (!current.trim()) { await reply(`${field} is empty.`); return; }
+    if (current.length > 2500) {
+      await reply(current.slice(0, 2500) + '\n\n(truncated)');
+    } else {
+      await reply(current);
+    }
+  }
+
+  private async handleConfigCommand(message: IncomingMessage, args: string[], reply: (t: string) => Promise<void>): Promise<void> {
+    const agent = this.getFirstAgent();
+    if (!agent) { await reply('No agent found.'); return; }
+    const sub = args[0]?.toLowerCase();
+
+    if (sub === 'show' || !sub) {
+      const c = agent.config;
+      const lines = [
+        `*Agent Config: ${c.name}*`,
+        `  purpose: ${c.purpose || '(not set)'}`,
+        `  triggers: ${c.triggers?.join(', ') || '(none)'}`,
+        `  channels: ${c.channels?.join(', ') || '(all)'}`,
+        `  skills: ${c.skills?.join(', ') || '(none)'}`,
+        `  knowledgeBase: ${c.knowledgeBase ?? false}`,
+        `  priority: ${c.priority ?? 0}`,
+        `  escalateTo: ${c.escalateTo || '(not set)'}`,
+      ];
+      if (c.guardrails) {
+        lines.push(`  maxResponseLength: ${c.guardrails.maxResponseLength ?? '(not set)'}`);
+        lines.push(`  blockedTopics: ${c.guardrails.blockedTopics?.join(', ') || '(none)'}`);
+        lines.push(`  escalationTriggers: ${c.guardrails.escalationTriggers?.join(', ') || '(none)'}`);
+        lines.push(`  systemRules: ${c.guardrails.systemRules?.length || 0} rules`);
+      }
+      await reply(lines.join('\n'));
+      return;
+    }
+
+    if (sub === 'set') {
+      const key = args[1];
+      const value = args.slice(2).join(' ');
+      if (!key || !value) { await reply('Usage: /config set <key> <value>'); return; }
+      await this.configSet(agent, key, value, message.from, reply);
+      return;
+    }
+
+    if (sub === 'add') {
+      const key = args[1];
+      const value = args.slice(2).join(' ');
+      if (!key || !value) { await reply('Usage: /config add <key> <value>'); return; }
+      await this.configArrayOp(agent, 'add', key, value, message.from, reply);
+      return;
+    }
+
+    if (sub === 'remove') {
+      const key = args[1];
+      const value = args.slice(2).join(' ');
+      if (!key || !value) { await reply('Usage: /config remove <key> <value>'); return; }
+      await this.configArrayOp(agent, 'remove', key, value, message.from, reply);
+      return;
+    }
+
+    await reply('Usage: /config show | /config set <key> <value> | /config add <key> <value> | /config remove <key> <value>');
+  }
+
+  private async handleModelCommand(args: string[], reply: (t: string) => Promise<void>): Promise<void> {
+    const llm = this.config.llmProvider;
+    if (!llm || !llm.getConfig) {
+      await reply('LLM provider not available. Configure LLM_PROVIDER and LLM_API_KEY first.');
+      return;
+    }
+
+    const sub = args[0]?.toLowerCase();
+
+    // /model or /model show — display current model
+    if (!sub || sub === 'show') {
+      const cfg = llm.getConfig();
+      const key = cfg.apiKey;
+      const masked = key ? key.slice(0, 6) + '...' + key.slice(-4) : '(not set)';
+      const lines = [
+        '*Current LLM Config*',
+        `  provider: ${cfg.provider}`,
+        `  model: ${cfg.model || '(default)'}`,
+        `  apiKey: ${masked}`,
+      ];
+      await reply(lines.join('\n'));
+      return;
+    }
+
+    // /model list — show available models
+    if (sub === 'list') {
+      if (!llm.getModelCatalog) {
+        await reply('Model catalog not available.');
+        return;
+      }
+      const { catalog, defaults } = llm.getModelCatalog();
+      const cfg = llm.getConfig();
+      const lines = ['*Available Models*', ''];
+      for (const [provider, models] of Object.entries(catalog)) {
+        const isCurrent = provider === cfg.provider;
+        const hasKey = isCurrent || !!llm.getApiKey?.(provider);
+        const marker = isCurrent ? ' (active)' : hasKey ? ' (key set)' : '';
+        lines.push(`*${provider}*${marker}`);
+        for (const m of models) {
+          const isDefault = m === (defaults[provider] || '');
+          const isActive = isCurrent && (cfg.model === m || (!cfg.model && isDefault));
+          const prefix = isActive ? '  → ' : '    ';
+          lines.push(`${prefix}${m}${isDefault ? ' (default)' : ''}`);
+        }
+        lines.push('');
+      }
+      await reply(lines.join('\n'));
+      return;
+    }
+
+    // /model set <provider/model> or /model set <model>
+    if (sub === 'set') {
+      const value = args.slice(1).join(' ').trim();
+      if (!value) {
+        await reply('Usage: /model set <provider/model> or /model set <model>');
+        return;
+      }
+
+      let provider: string | undefined;
+      let model: string;
+
+      if (value.includes('/')) {
+        const slashIdx = value.indexOf('/');
+        provider = value.slice(0, slashIdx);
+        model = value.slice(slashIdx + 1);
+      } else {
+        model = value;
+      }
+
+      const cfg = llm.getConfig();
+      const targetProvider = provider || cfg.provider;
+
+      // Validate provider
+      const validProviders = ['openai', 'anthropic', 'google', 'groq', 'ollama'];
+      if (!validProviders.includes(targetProvider)) {
+        await reply(`Unknown provider: ${targetProvider}\nValid: ${validProviders.join(', ')}`);
+        return;
+      }
+
+      // Check API key availability when switching providers
+      if (provider && provider !== cfg.provider) {
+        const key = llm.getApiKey?.(provider);
+        if (!key) {
+          await reply(`No API key for ${provider}. Use /model key ${provider} <key> first.`);
+          return;
+        }
+        llm.setConfig({ provider: provider as any, model, apiKey: key });
+      } else {
+        llm.setConfig({ model });
+      }
+
+      // Persist via memory store
+      const memory = this.config.memory;
+      if (memory?.setSetting) {
+        await memory.setSetting('llm_provider', targetProvider);
+        await memory.setSetting('llm_model', model);
+      }
+
+      await reply(`Model switched to *${targetProvider}/${model}*`);
+      return;
+    }
+
+    // /model key <provider> <key> — store API key
+    if (sub === 'key') {
+      const provider = args[1]?.toLowerCase();
+      const key = args[2];
+      if (!provider || !key) {
+        await reply('Usage: /model key <provider> <api-key>');
+        return;
+      }
+      const validProviders = ['openai', 'anthropic', 'google', 'groq', 'ollama'];
+      if (!validProviders.includes(provider)) {
+        await reply(`Unknown provider: ${provider}\nValid: ${validProviders.join(', ')}`);
+        return;
+      }
+      llm.setApiKey(provider, key);
+
+      // Persist
+      const memory = this.config.memory;
+      if (memory?.setSetting) {
+        await memory.setSetting(`llm_apikey_${provider}`, key);
+      }
+
+      const masked = key.slice(0, 6) + '...' + key.slice(-4);
+      await reply(`API key for *${provider}* saved: ${masked}`);
+      return;
+    }
+
+    await reply('Usage: /model | /model list | /model set <provider/model> | /model key <provider> <key>');
+  }
+
+  /**
+   * Select agent based on intent.
+   * Sorts by priority (higher first), then specificity (fewer triggers = more specific).
+   * Agents with triggers: ['*'] are treated as fallback (checked last).
+   */
+  private selectAgent(intent: Intent, message: IncomingMessage): Agent | null {
+    // Filter by channel first
+    const channelFiltered = Array.from(this.agents.values()).filter((agent) => {
+      const cfg = agent.getConfig();
+      if (cfg.channels && cfg.channels.length > 0) {
+        return cfg.channels.includes(message.channel) || cfg.channels.includes(message.provider);
+      }
+      return true;
+    });
+
+    // Separate wildcard fallback agents from specific agents
+    const specific: Agent[] = [];
+    const fallback: Agent[] = [];
+
+    for (const agent of channelFiltered) {
+      const cfg = agent.getConfig();
+      const triggers = cfg.triggers || [];
+      if (triggers.length === 1 && triggers[0] === '*') {
+        fallback.push(agent);
+      } else {
+        specific.push(agent);
+      }
+    }
+
+    // Sort by priority (higher first), then specificity (fewer triggers = more specific)
+    const sortByPriority = (a: Agent, b: Agent) => {
+      const pa = a.getConfig().priority ?? 0;
+      const pb = b.getConfig().priority ?? 0;
+      if (pb !== pa) return pb - pa;
+      const ta = a.getConfig().triggers?.length ?? 0;
+      const tb = b.getConfig().triggers?.length ?? 0;
+      return ta - tb;
+    };
+
+    specific.sort(sortByPriority);
+    fallback.sort(sortByPriority);
+
+    // Try specific agents first
+    for (const agent of specific) {
+      if (agent.matchesIntent(intent.intent)) {
+        return agent;
+      }
+    }
+
+    // Fall back to wildcard agents
+    for (const agent of fallback) {
+      return agent;
+    }
+
+    return null;
+  }
+
+  /**
+   * Send message via provider
+   */
+  private async sendMessage(
+    to: string,
+    providerName: string,
+    message: OutgoingMessage
+  ): Promise<void> {
+    const provider = this.providers.get(providerName);
+    if (!provider) {
+      throw new Error(`Provider not found: ${providerName}`);
+    }
+
+    await provider.sendMessage(to, message);
+  }
+
+  /**
+   * Get all agents
+   */
+  getAgents(): Agent[] {
+    return Array.from(this.agents.values());
+  }
+
+  /**
+   * Get all skills
+   */
+  getSkills(): Skill[] {
+    return Array.from(this.skills.values());
+  }
+
+  /**
+   * Check if running
+   */
+  isActive(): boolean {
+    return this.isRunning;
+  }
+
+  /**
+   * Get the analytics store (if configured) for querying metrics
+   */
+  getAnalyticsStore(): any {
+    return this.config.analyticsStore ?? null;
+  }
+
+  private async configSet(agent: Agent, key: string, value: string, sender: string, reply: (t: string) => Promise<void>): Promise<void> {
+    const scalarKeys: Record<string, (v: string) => any> = {
+      purpose: (v) => v,
+      maxResponseLength: (v) => parseInt(v),
+      priority: (v) => parseInt(v),
+      escalateTo: (v) => v,
+      knowledgeBase: (v) => v === 'true',
+    };
+    const parser = scalarKeys[key];
+    if (!parser) { await reply(`Unknown config key "${key}". Valid: ${Object.keys(scalarKeys).join(', ')}`); return; }
+
+    await this.versionStore.saveVersion(agent.config.name, {
+      timestamp: new Date().toISOString(),
+      instructions: agent.config._rawInstructions,
+      identity: agent.config._rawIdentity,
+      soul: agent.config._rawSoul,
+      frontmatter: this.extractFrontmatter(agent.config),
+      editedBy: sender,
+      changeDescription: `Set ${key} = ${value}`,
+    });
+
+    const parsed = parser(value);
+    if (key === 'maxResponseLength') {
+      agent.config.guardrails = agent.config.guardrails || {};
+      agent.config.guardrails.maxResponseLength = parsed;
+    } else {
+      (agent.config as any)[key] = parsed;
+    }
+
+    await this.writeAgentFrontmatter(agent.config.name, agent);
+    await reply(`Config updated: ${key} = ${value}`);
+  }
+
+  private async configArrayOp(agent: Agent, op: 'add' | 'remove', key: string, value: string, sender: string, reply: (t: string) => Promise<void>): Promise<void> {
+    const arrayKeys: Record<string, { get: () => string[], set: (v: string[]) => void }> = {
+      triggers: { get: () => agent.config.triggers || [], set: (v) => { agent.config.triggers = v; } },
+      channels: { get: () => agent.config.channels || [], set: (v) => { agent.config.channels = v; } },
+      skills: { get: () => agent.config.skills || [], set: (v) => { agent.config.skills = v; } },
+      blockedTopics: {
+        get: () => agent.config.guardrails?.blockedTopics || [],
+        set: (v) => { agent.config.guardrails = agent.config.guardrails || {}; agent.config.guardrails.blockedTopics = v; },
+      },
+      escalationTriggers: {
+        get: () => agent.config.guardrails?.escalationTriggers || [],
+        set: (v) => { agent.config.guardrails = agent.config.guardrails || {}; agent.config.guardrails.escalationTriggers = v; },
+      },
+      systemRules: {
+        get: () => agent.config.guardrails?.systemRules || [],
+        set: (v) => { agent.config.guardrails = agent.config.guardrails || {}; agent.config.guardrails.systemRules = v; },
+      },
+    };
+    const accessor = arrayKeys[key];
+    if (!accessor) { await reply(`Unknown array key "${key}". Valid: ${Object.keys(arrayKeys).join(', ')}`); return; }
+
+    await this.versionStore.saveVersion(agent.config.name, {
+      timestamp: new Date().toISOString(),
+      instructions: agent.config._rawInstructions,
+      identity: agent.config._rawIdentity,
+      soul: agent.config._rawSoul,
+      frontmatter: this.extractFrontmatter(agent.config),
+      editedBy: sender,
+      changeDescription: `${op} ${key}: ${value}`,
+    });
+
+    const arr = accessor.get();
+    if (op === 'add') {
+      if (!arr.includes(value)) arr.push(value);
+      accessor.set(arr);
+    } else {
+      accessor.set(arr.filter(v => v !== value));
+    }
+
+    // Rebuild system prompt if systemRules changed
+    if (key === 'systemRules') this.rebuildAgentSystemPrompt(agent);
+
+    await this.writeAgentFrontmatter(agent.config.name, agent);
+    await reply(`Config updated: ${op} "${value}" ${op === 'add' ? 'to' : 'from'} ${key}`);
+  }
+
+  private async handleWhitelistCommand(message: IncomingMessage, args: string[], reply: (t: string) => Promise<void>): Promise<void> {
+    const whitelist = this.config.trainingMode?.whitelist;
+    if (!whitelist) {
+      await reply('Training mode whitelist is not configured.');
+      return;
+    }
+
+    const normalizePhone = (p: string) => p.replace(/[\s\-+]/g, '');
+    const formatPhone = (p: string) => p.startsWith('+') ? p : `+${p}`;
+    const sub = args[0]?.toLowerCase();
+
+    if (!sub || sub === 'list') {
+      if (whitelist.length === 0) {
+        await reply('Whitelist is empty.');
+      } else {
+        const lines = whitelist.map(p => `  ${formatPhone(p)}`);
+        await reply(`Whitelisted numbers (${whitelist.length}):\n${lines.join('\n')}`);
+      }
+      return;
+    }
+
+    if (sub === 'add') {
+      const phone = args.slice(1).join('').trim();
+      if (!phone) {
+        await reply('Usage: /whitelist add <phone>');
+        return;
+      }
+      const normalized = normalizePhone(phone);
+      const alreadyExists = whitelist.some(w => normalizePhone(w) === normalized);
+      if (alreadyExists) {
+        await reply(`${formatPhone(phone)} is already whitelisted.`);
+        return;
+      }
+      whitelist.push(phone.startsWith('+') ? phone : `+${phone}`);
+      await this.persistWhitelist();
+      await reply(`Added ${formatPhone(phone)} to whitelist.`);
+      return;
+    }
+
+    if (sub === 'remove') {
+      const phone = args.slice(1).join('').trim();
+      if (!phone) {
+        await reply('Usage: /whitelist remove <phone>');
+        return;
+      }
+      const normalized = normalizePhone(phone);
+      const senderNormalized = normalizePhone(message.from);
+      if (normalized === senderNormalized) {
+        await reply('You cannot remove yourself from the whitelist.');
+        return;
+      }
+      const idx = whitelist.findIndex(w => normalizePhone(w) === normalized);
+      if (idx === -1) {
+        await reply(`${formatPhone(phone)} is not in the whitelist.`);
+        return;
+      }
+      whitelist.splice(idx, 1);
+      await this.persistWhitelist();
+      await reply(`Removed ${formatPhone(phone)} from whitelist.`);
+      return;
+    }
+
+    await reply('Usage: /whitelist | /whitelist add <phone> | /whitelist remove <phone>');
+  }
+
+  private async handleSkillsCommand(message: IncomingMessage, args: string[], reply: (t: string) => Promise<void>): Promise<void> {
+    const skills = Array.from(this.skills.values());
+    const sub = args[0]?.toLowerCase();
+
+    if (sub === 'info') {
+      const name = args.slice(1).join(' ').trim();
+      if (!name) {
+        await reply('Usage: /skills info <name>');
+        return;
+      }
+      const skill = this.skills.get(name);
+      if (!skill) {
+        const available = skills.map(s => s.name).join(', ') || 'none';
+        await reply(`Skill "${name}" not found. Available: ${available}`);
+        return;
+      }
+      const isPrompt = typeof (skill as any).getContent === 'function';
+      if (isPrompt) {
+        const cfg = (skill as any).getConfig?.() || {};
+        const content = (skill as any).getContent() || '';
+        const preview = content.length > 300 ? content.slice(0, 300) + '...' : content;
+        const lines = [
+          `📝 *Prompt Skill: ${skill.name}*`,
+          `  Status: ${skill.isReady() ? 'ready' : 'not ready'}`,
+          `  Type: prompt`,
+        ];
+        if (cfg.summary) lines.push(`  Summary: ${cfg.summary}`);
+        if (cfg.tags?.length) lines.push(`  Tags: ${cfg.tags.join(', ')}`);
+        if (cfg.author) lines.push(`  Author: ${cfg.author}`);
+        lines.push('', '  Content:', `  ${preview}`);
+        await reply(lines.join('\n'));
+      } else {
+        const tools = Object.values(skill.tools);
+        const lines = [
+          `🔧 *Skill: ${skill.name}*`,
+          `  Status: ${skill.isReady() ? 'ready' : 'not ready'}`,
+          `  Tools: ${tools.length}`,
+        ];
+        for (const tool of tools) {
+          lines.push('');
+          lines.push(`  *${tool.name}*`);
+          if (tool.description) lines.push(`    ${tool.description}`);
+          const params = Object.entries(tool.parameters);
+          if (params.length > 0) {
+            lines.push('    Parameters:');
+            for (const [pName, pDef] of params) {
+              const p = pDef as Record<string, any>;
+              const req = p.required ? ' (required)' : '';
+              const type = p.type ? ` [${p.type}]` : '';
+              lines.push(`      ${pName}${type}${req}${p.description ? ' — ' + p.description : ''}`);
+            }
+          }
+        }
+        await reply(lines.join('\n'));
+      }
+      return;
+    }
+
+    if (sub === 'catalog' || sub === 'browse') {
+      await this.handleSkillCatalog(args.slice(1), reply);
+      return;
+    }
+
+    if (sub === 'add') {
+      await this.handleSkillAdd(message, args.slice(1), reply);
+      return;
+    }
+
+    if (sub === 'remove') {
+      await this.handleSkillRemove(args.slice(1), reply);
+      return;
+    }
+
+    // Default: list all skills
+    if (skills.length === 0) {
+      await reply('No skills registered. Use /skills catalog to browse available skills, or /create-skill to create a prompt skill.');
+      return;
+    }
+    const lines = [`🔧 *Registered Skills (${skills.length}):*`];
+    for (const skill of skills) {
+      const status = skill.isReady() ? '✅' : '⏳';
+      const isPrompt = typeof (skill as any).getContent === 'function';
+      if (isPrompt) {
+        lines.push(`  ${status} 📝 ${skill.name} — prompt skill`);
+      } else {
+        const toolNames = Object.keys(skill.tools);
+        lines.push(`  ${status} ${skill.name} — ${toolNames.length} tool${toolNames.length !== 1 ? 's' : ''}: ${toolNames.join(', ')}`);
+      }
+    }
+    lines.push('');
+    lines.push('Use /skills info <name> for details, /skills catalog to browse, /skills add <name> to install, /create-skill to create a prompt skill.');
+    await reply(lines.join('\n'));
+  }
+
+  private async handleCreateSkillCommand(message: IncomingMessage, args: string[], reply: (t: string) => Promise<void>): Promise<void> {
+    // Usage: /create-skill <name> | <content>
+    const raw = args.join(' ');
+    const pipeIdx = raw.indexOf('|');
+    if (pipeIdx === -1 || !raw.trim()) {
+      await reply('Usage: /create-skill <name> | <instructions>\n\nExample: /create-skill sentiment-monitor | Monitor customer sentiment and flag negative interactions for review.');
+      return;
+    }
+
+    const name = raw.slice(0, pipeIdx).trim();
+    const content = raw.slice(pipeIdx + 1).trim();
+    if (!name || !content) {
+      await reply('Both name and content are required.\nUsage: /create-skill <name> | <instructions>');
+      return;
+    }
+
+    const mod = this.config.skillsModule;
+    if (!mod) {
+      await reply('Skills module not available. Make sure @operor/skills is installed.');
+      return;
+    }
+
+    try {
+      const config = mod.loadSkillsConfig();
+      const exists = config.skills.find((s: any) => s.name === name);
+      if (exists) {
+        await reply(`A skill named "${name}" already exists. Remove it first or choose a different name.`);
+        return;
+      }
+
+      const promptSkillConfig = { type: 'prompt' as const, name, content, enabled: true };
+      config.skills.push(promptSkillConfig);
+      mod.saveSkillsConfig(config);
+
+      // Auto-add skill to all agents' skills lists so it activates on hot-reload
+      const agents = Array.from(this.agents.values());
+      for (const agent of agents) {
+        const cfg = agent.getConfig();
+        if (cfg.skills && !cfg.skills.includes(name)) {
+          cfg.skills.push(name);
+          agent.config.skills = cfg.skills;
+        }
+      }
+
+      // Persist to INSTRUCTIONS.md frontmatter and save version snapshot
+      for (const agent of agents) {
+        await this.versionStore.saveVersion(agent.config.name, {
+          timestamp: new Date().toISOString(),
+          instructions: agent.config._rawInstructions,
+          identity: agent.config._rawIdentity,
+          soul: agent.config._rawSoul,
+          frontmatter: this.extractFrontmatter(agent.config),
+          editedBy: message.from,
+          changeDescription: `add skills: ${name}`,
+        });
+        await this.writeAgentFrontmatter(agent.config.name, agent);
+      }
+
+      await reply(`📝 Prompt skill "${name}" created and added to your agent(s).\nSaving to mcp.json triggers hot-reload — skill is now active.`);
+    } catch (err: any) {
+      await reply(`Failed to create skill: ${err.message}`);
+    }
+  }
+
+  private async handleUpdateSkillCommand(message: IncomingMessage, args: string[], reply: (t: string) => Promise<void>): Promise<void> {
+    // Usage: /update-skill <name> | <content>
+    const raw = args.join(' ');
+    const pipeIdx = raw.indexOf('|');
+    if (pipeIdx === -1 || !raw.trim()) {
+      await reply('Usage: /update-skill <name> | <instructions>\n\nExample: /update-skill sentiment-monitor | Updated instructions for monitoring sentiment.');
+      return;
+    }
+
+    const name = raw.slice(0, pipeIdx).trim();
+    const content = raw.slice(pipeIdx + 1).trim();
+    if (!name || !content) {
+      await reply('Both name and content are required.\nUsage: /update-skill <name> | <instructions>');
+      return;
+    }
+
+    const mod = this.config.skillsModule;
+    if (!mod) {
+      await reply('Skills module not available. Make sure @operor/skills is installed.');
+      return;
+    }
+
+    try {
+      const config = mod.loadSkillsConfig();
+      const existing = config.skills.find((s: any) => s.name === name);
+      if (!existing) {
+        await reply(`Skill "${name}" not found. Use /skills to list registered skills.`);
+        return;
+      }
+      if (existing.type !== 'prompt') {
+        await reply(`Skill "${name}" is not a prompt skill (type: ${existing.type}). Only prompt skills can be updated with this command.`);
+        return;
+      }
+
+      existing.content = content;
+      mod.saveSkillsConfig(config);
+
+      // Save version snapshot
+      const agents = Array.from(this.agents.values());
+      for (const agent of agents) {
+        await this.versionStore.saveVersion(agent.config.name, {
+          timestamp: new Date().toISOString(),
+          instructions: agent.config._rawInstructions,
+          identity: agent.config._rawIdentity,
+          soul: agent.config._rawSoul,
+          frontmatter: this.extractFrontmatter(agent.config),
+          editedBy: message.from,
+          changeDescription: `update skill: ${name}`,
+        });
+      }
+
+      await reply(`📝 Prompt skill "${name}" updated.\nSaving to mcp.json triggers hot-reload — changes are now active.`);
+    } catch (err: any) {
+      await reply(`Failed to update skill: ${err.message}`);
+    }
+  }
+
+  private async handleSkillCatalog(args: string[], reply: (t: string) => Promise<void>): Promise<void> {
+    const mod = this.config.skillsModule;
+    if (!mod) {
+      await reply('Skill catalog is not available. Make sure @operor/skills is installed.');
+      return;
+    }
+    const catalog = mod.loadSkillCatalog();
+
+    const filter = args[0]?.toLowerCase();
+    const validCategories = ['commerce', 'payments', 'crm', 'support', 'marketing', 'search', 'communication', 'productivity'];
+
+    let entries = catalog.skills as any[];
+    let categoryFilter: string | undefined;
+    if (filter) {
+      if (validCategories.includes(filter)) {
+        categoryFilter = filter;
+        entries = entries.filter((s: any) => s.category === filter);
+      } else {
+        // Text search fallback across name, description, category
+        entries = entries.filter((s: any) =>
+          s.name?.toLowerCase().includes(filter) ||
+          s.description?.toLowerCase().includes(filter) ||
+          s.category?.toLowerCase().includes(filter) ||
+          s.displayName?.toLowerCase().includes(filter)
+        );
+      }
+    }
+
+    if (entries.length === 0) {
+      await reply(filter ? `No skills found matching "${filter}".` : 'Skill catalog is empty.');
+      return;
+    }
+
+    // Group by category
+    const grouped: Record<string, any[]> = {};
+    for (const entry of entries) {
+      const cat = entry.category || 'other';
+      if (!grouped[cat]) grouped[cat] = [];
+      grouped[cat].push(entry);
+    }
+
+    const lines = [`📦 *Skill Catalog (${entries.length} skills):*`];
+    for (const [cat, catSkills] of Object.entries(grouped)) {
+      lines.push('');
+      lines.push(`*${cat.charAt(0).toUpperCase() + cat.slice(1)}:*`);
+      for (const s of catSkills) {
+        const installed = this.skills.has(s.name) ? ' ✅' : '';
+        const badge = s.maturity === 'official' ? ' 🏷️' : '';
+        const typeTag = s.type === 'prompt' ? ' 📝' : '';
+        lines.push(`  ${s.displayName || s.name}${badge}${typeTag}${installed} — ${s.description}`);
+        lines.push(`    → /skills add ${s.name}`);
+      }
+    }
+    lines.push('');
+    if (!categoryFilter) {
+      lines.push(`Filter by category: /skills catalog <${validCategories.join('|')}>`);
+    }
+    await reply(lines.join('\n'));
+  }
+
+  private async handleSkillAdd(message: IncomingMessage, args: string[], reply: (t: string) => Promise<void>): Promise<void> {
+    const name = args[0]?.trim();
+    if (!name) {
+      await reply('Usage: /skills add <name>\n\nBrowse available skills with /skills catalog');
+      return;
+    }
+
+    // Check if already installed (runtime or mcp.json)
+    if (this.skills.has(name)) {
+      await reply(`Skill "${name}" is already installed and active.`);
+      return;
+    }
+
+    // Look up in catalog
+    const mod = this.config.skillsModule;
+    if (!mod) {
+      await reply('Skill catalog is not available. Make sure @operor/skills is installed.');
+      return;
+    }
+
+    // Also check mcp.json for already-configured skills
+    const root = this.config.projectRoot;
+    const existingConfig = mod.loadSkillsConfig(root);
+    if (existingConfig.skills.some((s: any) => s.name === name)) {
+      await reply(`Skill "${name}" already exists in mcp.json. Restart to activate.`);
+      return;
+    }
+    const catalog = mod.loadSkillCatalog();
+    const entry = mod.findSkillInCatalog(catalog, name);
+    if (!entry) {
+      // Suggest similar skills
+      const allNames = catalog.skills.map((s: any) => s.name);
+      const suggestions = allNames.filter((n: string) =>
+        n.includes(name) || name.includes(n)
+      );
+      const msg = suggestions.length > 0
+        ? `Skill "${name}" not found. Did you mean: ${suggestions.join(', ')}?`
+        : `Skill "${name}" not found in catalog. Use /skills catalog to browse available skills.`;
+      await reply(msg);
+      return;
+    }
+
+    // Prompt skills install directly — no env vars or tools
+    if (entry.type === 'prompt') {
+      await reply(`📝 *Adding prompt skill: ${entry.displayName}*\n  ${entry.description}\n\nInstalling...`);
+      await this.installSkillFromCatalog(entry, {}, reply);
+      return;
+    }
+
+    // Show skill info
+    const envKeys = Object.keys(entry.envVars || {});
+    const requiredKeys = envKeys.filter((k: string) => entry.envVars[k].required);
+
+    const lines = [
+      `📦 *Adding: ${entry.displayName}*`,
+      `  ${entry.description}`,
+      `  Category: ${entry.category} | Maturity: ${entry.maturity}`,
+      `  Tools: ${(entry.tools || []).map((t: any) => t.name).join(', ')}`,
+    ];
+
+    if (entry.docsUrl) {
+      lines.push(`  Docs: ${entry.docsUrl}`);
+    }
+
+    if (requiredKeys.length === 0) {
+      // No env vars needed — install directly
+      await reply(lines.join('\n') + '\n\nNo API keys required. Installing...');
+      await this.installSkillFromCatalog(entry, {}, reply);
+      return;
+    }
+
+    // Start env var capture flow
+    lines.push('');
+    lines.push('*Required API keys:*');
+    for (const key of requiredKeys) {
+      const spec = entry.envVars[key];
+      lines.push(`  ${key} — ${spec.description}${spec.placeholder ? ` (e.g. ${spec.placeholder})` : ''}`);
+    }
+    lines.push('');
+    lines.push(`Please send the value for *${requiredKeys[0]}*:`);
+    lines.push('(Send "cancel" to abort)');
+
+    this.pendingSkillAdds.set(message.from, {
+      skillName: name,
+      envVars: {},
+      pendingKeys: [...requiredKeys],
+      currentKey: requiredKeys[0],
+      catalogEntry: entry,
+      createdAt: Date.now(),
+    });
+
+    await reply(lines.join('\n'));
+  }
+
+  private async handlePendingSkillAdd(message: IncomingMessage, pending: PendingSkillAdd): Promise<boolean> {
+    const reply = async (text: string) => {
+      await this.sendMessage(message.from, message.provider, { to: message.from, text });
+    };
+
+    // Timeout after 5 minutes
+    if (Date.now() - pending.createdAt > 5 * 60 * 1000) {
+      this.pendingSkillAdds.delete(message.from);
+      await reply('Skill add session expired (5 min timeout). Send /skills add <name> to try again.');
+      return true;
+    }
+
+    const text = message.text.trim();
+
+    if (text.toLowerCase() === 'cancel' || text.toLowerCase() === '/cancel') {
+      this.pendingSkillAdds.delete(message.from);
+      await reply('Skill installation cancelled.');
+      return true;
+    }
+
+    if (!pending.currentKey) {
+      this.pendingSkillAdds.delete(message.from);
+      return false;
+    }
+
+    // Store the value for the current key
+    pending.envVars[pending.currentKey] = text;
+    pending.pendingKeys.shift();
+
+    if (pending.pendingKeys.length > 0) {
+      // Ask for next key
+      pending.currentKey = pending.pendingKeys[0];
+      const spec = pending.catalogEntry.envVars[pending.currentKey];
+      await reply(`Got it. Now send the value for *${pending.currentKey}*:${spec?.placeholder ? ` (e.g. ${spec.placeholder})` : ''}`);
+      return true;
+    }
+
+    // All keys collected — install
+    this.pendingSkillAdds.delete(message.from);
+    await reply('All keys received. Installing skill...');
+    await this.installSkillFromCatalog(pending.catalogEntry, pending.envVars, reply);
+    return true;
+  }
+
+  private async installSkillFromCatalog(entry: any, envVars: Record<string, string>, reply: (t: string) => Promise<void>): Promise<void> {
+    try {
+      const mod = this.config.skillsModule;
+      if (!mod) { await reply('Skill catalog is not available.'); return; }
+      const config = mod.catalogEntryToConfig(entry);
+
+      // Merge actual env var values into the config
+      if (config.env && Object.keys(envVars).length > 0) {
+        for (const [key, value] of Object.entries(envVars)) {
+          config.env[key] = value;
+        }
+      }
+
+      // Save to mcp.json
+      const root = this.config.projectRoot;
+      const skillsConfig = mod.loadSkillsConfig(root);
+      const existingIdx = skillsConfig.skills.findIndex((s: any) => s.name === config.name);
+      if (existingIdx >= 0) {
+        skillsConfig.skills[existingIdx] = config;
+      } else {
+        skillsConfig.skills.push(config);
+      }
+      mod.saveSkillsConfig(skillsConfig, root);
+
+      // Add skill to all agents' skills lists and persist to INSTRUCTIONS.md
+      const agents = Array.from(this.agents.values());
+      for (const agent of agents) {
+        const cfg = agent.getConfig();
+        if (cfg.skills && !cfg.skills.includes(config.name)) {
+          cfg.skills.push(config.name);
+          agent.config.skills = cfg.skills;
+        }
+        await this.writeAgentFrontmatter(agent.config.name, agent);
+      }
+
+      await reply(`✅ *${entry.displayName}* added to mcp.json and enabled.\n\nRestart the agent to activate the skill, or use /reload if available.`);
+    } catch (err: any) {
+      await reply(`Failed to install skill: ${err.message}`);
+    }
+  }
+
+  private async handleSkillRemove(args: string[], reply: (t: string) => Promise<void>): Promise<void> {
+    const name = args[0]?.trim();
+    if (!name) {
+      await reply('Usage: /skills remove <name>');
+      return;
+    }
+
+    try {
+      const mod = this.config.skillsModule;
+      if (!mod) { await reply('Skill catalog is not available.'); return; }
+      const root = this.config.projectRoot;
+      const skillsConfig = mod.loadSkillsConfig(root);
+      const idx = skillsConfig.skills.findIndex((s: any) => s.name === name);
+
+      if (idx < 0) {
+        const available = skillsConfig.skills.map((s: any) => s.name).join(', ') || 'none';
+        await reply(`Skill "${name}" not found in mcp.json. Configured: ${available}`);
+        return;
+      }
+
+      skillsConfig.skills.splice(idx, 1);
+      mod.saveSkillsConfig(skillsConfig, root);
+
+      // Remove from runtime if loaded
+      if (this.skills.has(name)) {
+        await this.removeSkill(name);
+      }
+
+      // Remove skill from all agents' skills lists and persist to INSTRUCTIONS.md
+      const agents = Array.from(this.agents.values());
+      for (const agent of agents) {
+        const cfg = agent.getConfig();
+        if (cfg.skills) {
+          const skillIdx = cfg.skills.indexOf(name);
+          if (skillIdx >= 0) {
+            cfg.skills.splice(skillIdx, 1);
+            agent.config.skills = cfg.skills;
+          }
+        }
+        await this.writeAgentFrontmatter(agent.config.name, agent);
+      }
+
+      await reply(`✅ Skill "${name}" removed from mcp.json.`);
+    } catch (err: any) {
+      await reply(`Failed to remove skill: ${err.message}`);
+    }
+  }
+
+  private async persistWhitelist(): Promise<void> {
+    const whitelist = this.config.trainingMode?.whitelist;
+    if (!whitelist) return;
+    if (this.memory.setSetting) {
+      await this.memory.setSetting('training_whitelist', whitelist.join(','));
+    }
+  }
+
+  /**
+   * Format a date string (YYYY-MM-DD) to a day name (e.g. "Monday")
+   */
+  private formatDayName(dateStr: string): string {
+    try {
+      const d = new Date(dateStr + 'T00:00:00');
+      return d.toLocaleDateString('en-US', { weekday: 'long' });
+    } catch {
+      return dateStr;
+    }
+  }
+
+  /**
+   * Log helper
+   */
+  private getFirstAgent(): Agent | null {
+    const agents = Array.from(this.agents.values());
+    return agents[0] ?? null;
+  }
+
+  private rebuildAgentSystemPrompt(agent: Agent): void {
+    agent.config.systemPrompt = buildSystemPrompt({
+      identity: agent.config._rawIdentity || null,
+      soul: agent.config._rawSoul || null,
+      body: agent.config._rawInstructions || '',
+      userContext: null,
+      guardrails: agent.config.guardrails,
+    });
+  }
+
+  private async writeAgentFiles(agentName: string, agent: Agent): Promise<void> {
+    const agentsDir = this.config.agentsDir;
+    if (!agentsDir) return;
+    const agentDir = path.join(agentsDir, agentName);
+    await fs.mkdir(agentDir, { recursive: true });
+
+    // Write INSTRUCTIONS.md with frontmatter
+    const fm = this.extractFrontmatter(agent.config);
+    const yamlFm = yaml.dump(fm, { lineWidth: -1, noRefs: true }).trim();
+    const body = agent.config._rawInstructions || '';
+    await fs.writeFile(path.join(agentDir, 'INSTRUCTIONS.md'), `---\n${yamlFm}\n---\n\n${body.trim()}\n`, 'utf-8');
+
+    if (agent.config._rawIdentity) {
+      await fs.writeFile(path.join(agentDir, 'IDENTITY.md'), agent.config._rawIdentity.trim() + '\n', 'utf-8');
+    }
+    if (agent.config._rawSoul) {
+      await fs.writeFile(path.join(agentDir, 'SOUL.md'), agent.config._rawSoul.trim() + '\n', 'utf-8');
+    }
+  }
+
+  private async writeAgentFrontmatter(agentName: string, agent: Agent): Promise<void> {
+    const agentsDir = this.config.agentsDir;
+    if (!agentsDir) return;
+    const agentDir = path.join(agentsDir, agentName);
+    await fs.mkdir(agentDir, { recursive: true });
+    const fm = this.extractFrontmatter(agent.config);
+    const yamlFm = yaml.dump(fm, { lineWidth: -1, noRefs: true }).trim();
+    const body = agent.config._rawInstructions || '';
+    await fs.writeFile(path.join(agentDir, 'INSTRUCTIONS.md'), `---\n${yamlFm}\n---\n\n${body.trim()}\n`, 'utf-8');
+  }
+
+  private extractSection(text: string, sectionName: string): string | null {
+    const sections = this.parseSections(text);
+    const match = sections.find(s => s.heading.toLowerCase().includes(sectionName.toLowerCase()));
+    return match?.content || null;
+  }
+
+  private replaceSection(text: string, sectionName: string, newContent: string): string {
+    const sections = this.parseSections(text);
+    const idx = sections.findIndex(s => s.heading.toLowerCase().includes(sectionName.toLowerCase()));
+    if (idx === -1) return text;
+    sections[idx].content = newContent;
+    return sections.map(s => `${s.heading}\n\n${s.content}`).join('\n\n');
+  }
+
+  private parseSections(text: string): Array<{ heading: string; content: string }> {
+    const lines = text.split('\n');
+    const sections: Array<{ heading: string; content: string }> = [];
+    let currentHeading: string | null = null;
+    let currentContent: string[] = [];
+
+    for (const line of lines) {
+      if (line.match(/^##\s+/)) {
+        if (currentHeading) {
+          sections.push({ heading: currentHeading, content: currentContent.join('\n').trim() });
+        }
+        currentHeading = line;
+        currentContent = [];
+      } else if (currentHeading) {
+        currentContent.push(line);
+      }
+    }
+
+    if (currentHeading) {
+      sections.push({ heading: currentHeading, content: currentContent.join('\n').trim() });
+    }
+
+    return sections;
+  }
+
+  private extractFrontmatter(config: AgentConfig): Record<string, any> {
+    const fm: Record<string, any> = { name: config.name };
+    if (config.purpose) fm.purpose = config.purpose;
+    if (config.triggers?.length) fm.triggers = config.triggers;
+    if (config.channels?.length) fm.channels = config.channels;
+    if (config.skills?.length) fm.skills = config.skills;
+    if (config.knowledgeBase != null) fm.knowledgeBase = config.knowledgeBase;
+    if (config.priority != null) fm.priority = config.priority;
+    if (config.escalateTo) fm.escalateTo = config.escalateTo;
+    if (config.guardrails) fm.guardrails = config.guardrails;
+    return fm;
+  }
+
+  private log(message: string): void {
+    if (this.config.debug) {
+      console.log(`[Operor] ${message}`);
+    }
+  }
+}