@rubytech/create-maxy 1.0.458 → 1.0.460

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rubytech/create-maxy",
-  "version": "1.0.458",
+  "version": "1.0.460",
   "description": "Install Maxy — AI for Productive People",
   "bin": {
     "create-maxy": "./dist/index.js"

package/payload/maxy/server.js

@@ -2852,8 +2852,8 @@ var serveStatic = (options = { root: "" }) => {
 
 // server/index.ts
 import { readFileSync as readFileSync19, existsSync as existsSync19, watchFile } from "fs";
-import { resolve as resolve16, join as join8, basename as basename2 } from "path";
-import { homedir as homedir2 } from "os";
+import { resolve as resolve16, join as join9, basename as basename2 } from "path";
+import { homedir as homedir3 } from "os";
 
 // app/api/health/route.ts
 import { existsSync as existsSync3, readFileSync as readFileSync3 } from "fs";
@@ -3135,7 +3135,8 @@ async function GET() {
 // app/lib/claude-agent.ts
 import Anthropic from "@anthropic-ai/sdk";
 import { spawn as spawn2 } from "child_process";
-import { resolve as resolve4 } from "path";
+import { resolve as resolve4, join as join3 } from "path";
+import { homedir as homedir2 } from "os";
 import { readFileSync as readFileSync5, readdirSync, existsSync as existsSync5, mkdirSync as mkdirSync2, createWriteStream, statSync as statSync2, unlinkSync } from "fs";
 
 // app/lib/vnc.ts
@@ -4679,7 +4680,8 @@ function fetchMcpToolsList(pluginDir) {
       env: {
         ...process.env,
         PLATFORM_ROOT: PLATFORM_ROOT3,
-        ACCOUNT_ID: "__toolslist__"
+        ACCOUNT_ID: "__toolslist__",
+        PLATFORM_PORT: process.env.PORT ?? "19200"
       }
     });
     let buffer = "";
@@ -5067,11 +5069,6 @@ function getMcpServers(accountId, enabledPlugins) {
       args: [resolve4(PLATFORM_ROOT3, "plugins/contacts/mcp/dist/index.js")],
       env: { ACCOUNT_ID: accountId, PLATFORM_ROOT: PLATFORM_ROOT3 }
     },
-    "telegram": {
-      command: "node",
-      args: [resolve4(PLATFORM_ROOT3, "plugins/telegram/mcp/dist/index.js")],
-      env: { ACCOUNT_ID: accountId, PLATFORM_ROOT: PLATFORM_ROOT3 }
-    },
     "whatsapp": {
       command: "node",
       args: [resolve4(PLATFORM_ROOT3, "plugins/whatsapp/mcp/dist/index.js")],
@@ -5082,11 +5079,6 @@ function getMcpServers(accountId, enabledPlugins) {
       args: [resolve4(PLATFORM_ROOT3, "plugins/admin/mcp/dist/index.js")],
       env: { ACCOUNT_ID: accountId, PLATFORM_ROOT: PLATFORM_ROOT3 }
     },
-    "cloudflare": {
-      command: "node",
-      args: [resolve4(PLATFORM_ROOT3, "plugins/cloudflare/mcp/dist/index.js")],
-      env: { PLATFORM_ROOT: PLATFORM_ROOT3 }
-    },
     "scheduling": {
       command: "node",
       args: [resolve4(PLATFORM_ROOT3, "plugins/scheduling/mcp/dist/index.js")],
@@ -5113,6 +5105,33 @@ function getMcpServers(accountId, enabledPlugins) {
       args: ["-y", "@playwright/mcp@latest", "--cdp-endpoint", "http://127.0.0.1:9222"]
     }
   };
+  if (process.env.TELEGRAM_PUBLIC_BOT_TOKEN) {
+    servers["telegram"] = {
+      command: "node",
+      args: [resolve4(PLATFORM_ROOT3, "plugins/telegram/mcp/dist/index.js")],
+      env: { ACCOUNT_ID: accountId, PLATFORM_ROOT: PLATFORM_ROOT3 }
+    };
+  } else {
+    console.error("[plugins] telegram MCP: skipped (no TELEGRAM_PUBLIC_BOT_TOKEN)");
+  }
+  let tunnelConfigured = false;
+  try {
+    const stateFile = join3(homedir2(), ".cloudflared", "tunnel.state");
+    if (existsSync5(stateFile)) {
+      const state = JSON.parse(readFileSync5(stateFile, "utf-8"));
+      tunnelConfigured = !!state?.tunnelId;
+    }
+  } catch {
+  }
+  if (!tunnelConfigured) {
+    servers["cloudflare"] = {
+      command: "node",
+      args: [resolve4(PLATFORM_ROOT3, "plugins/cloudflare/mcp/dist/index.js")],
+      env: { PLATFORM_ROOT: PLATFORM_ROOT3 }
+    };
+  } else {
+    console.error("[plugins] cloudflare MCP: skipped (tunnel already configured)");
+  }
   if (Array.isArray(enabledPlugins) && enabledPlugins.length > 0) {
     const pluginsDir = resolve4(PLATFORM_ROOT3, "plugins");
     let dirs;
@@ -9249,7 +9268,7 @@ async function POST8(req) {
 }
 
 // app/api/whatsapp/login/start/route.ts
-import { join as join3 } from "path";
+import { join as join4 } from "path";
 
 // app/lib/whatsapp/login.ts
 import { randomUUID as randomUUID5 } from "crypto";
@@ -9835,7 +9854,7 @@ async function POST9(req) {
     const body = await req.json().catch(() => ({}));
     const accountId = validateAccountId(body.accountId);
     const force = body.force ?? false;
-    const authDir = join3(MAXY_DIR, "credentials", "whatsapp", accountId);
+    const authDir = join4(MAXY_DIR, "credentials", "whatsapp", accountId);
     const result = await startLogin({ accountId, authDir, force });
     console.error(`[whatsapp:api] login/start result account=${accountId} hasQr=${!!result.qrRaw}${result.selfPhone ? ` phone=${result.selfPhone}` : ""}`);
     return Response.json(result);
@@ -23622,7 +23641,8 @@ var WhatsAppAccountSchema = external_exports.object({
   dmPolicy: DmPolicySchema.optional().describe("Who can message your public agent via WhatsApp DM. 'Open' lets anyone message. 'Allowlist' restricts to approved phone numbers. 'Disabled' blocks all public messages."),
   groupPolicy: GroupPolicySchema.optional().describe("Whether your agent responds in WhatsApp group chats. 'Open' enables group responses (subject to per-group activation). 'Allowlist' restricts to approved senders. 'Disabled' ignores all group messages."),
   selfChatMode: external_exports.boolean().optional().describe("Enable if the bot uses the owner's personal WhatsApp number (same phone for admin and bot). Changes how self-messages are routed."),
-  allowFrom: external_exports.array(external_exports.string()).optional().describe("Phone numbers (E.164 format, e.g. +44...) allowed to message via DM when policy is 'allowlist'. Add '*' to allow everyone."),
+  adminPhones: external_exports.array(external_exports.string()).optional().describe("Phone numbers (E.164) that route to the admin agent. Managed via add-admin-phone / remove-admin-phone."),
+  allowFrom: external_exports.array(external_exports.string()).optional().describe("Phone numbers allowed to message the public agent when DM policy is 'allowlist'. Add '*' for open access. Does not affect admin routing \u2014 use adminPhones for that."),
   groupAllowFrom: external_exports.array(external_exports.string()).optional().describe("Phone numbers allowed to trigger the agent in groups when group policy is 'allowlist'."),
   sendReadReceipts: external_exports.boolean().optional().default(true).describe("Whether to send read receipts (blue ticks) when messages are received. Disabling may feel less responsive but preserves privacy."),
   groups: external_exports.record(
@@ -23652,7 +23672,8 @@ var WhatsAppConfigSchema = external_exports.object({
   accounts: external_exports.record(external_exports.string(), WhatsAppAccountSchema.optional()).optional().describe("Per-account config keyed by account ID."),
   dmPolicy: DmPolicySchema.optional().default("disabled").describe("Who can message your public agent via WhatsApp DM. 'Open' lets anyone message. 'Allowlist' restricts to approved phone numbers. 'Disabled' blocks all public messages."),
   groupPolicy: GroupPolicySchema.optional().default("disabled").describe("Whether your agent responds in WhatsApp group chats. 'Open' enables group responses (subject to per-group activation). 'Allowlist' restricts to approved senders. 'Disabled' ignores all group messages."),
-  allowFrom: external_exports.array(external_exports.string()).optional().describe("Phone numbers (E.164 format, e.g. +44...) allowed to message via DM when policy is 'allowlist'. Add '*' to allow everyone."),
+  adminPhones: external_exports.array(external_exports.string()).optional().describe("Phone numbers (E.164) that route to the admin agent. Managed via add-admin-phone / remove-admin-phone."),
+  allowFrom: external_exports.array(external_exports.string()).optional().describe("Phone numbers allowed to message the public agent when DM policy is 'allowlist'. Add '*' for open access. Does not affect admin routing \u2014 use adminPhones for that."),
   groupAllowFrom: external_exports.array(external_exports.string()).optional().describe("Phone numbers allowed to trigger the agent in groups when group policy is 'allowlist'."),
   sendReadReceipts: external_exports.boolean().optional().default(true).describe("Whether to send read receipts (blue ticks) when messages are received. Disabling may feel less responsive but preserves privacy."),
   mediaMaxMb: external_exports.number().int().positive().optional().default(50).describe("Maximum file size in MB for media the agent will download and process."),
@@ -23833,18 +23854,16 @@ function resolveAccountConfig(config2, accountConfig) {
   return {
     dmPolicy: accountConfig?.dmPolicy ?? config2.dmPolicy ?? "disabled",
     groupPolicy: accountConfig?.groupPolicy ?? config2.groupPolicy ?? "disabled",
+    adminPhones: accountConfig?.adminPhones ?? config2.adminPhones ?? [],
     allowFrom: accountConfig?.allowFrom ?? config2.allowFrom ?? [],
     groupAllowFrom: accountConfig?.groupAllowFrom ?? config2.groupAllowFrom ?? [],
     selfChatMode: accountConfig?.selfChatMode ?? false
   };
 }
-function isAdminPhone(phone, allowFrom) {
+function isAdminPhone(phone, adminPhones) {
   const normalized = normalizeE164(phone);
   if (!normalized) return false;
-  return allowFrom.some((entry) => {
-    if (entry === "*") return false;
-    return phonesMatch(entry, normalized);
-  });
+  return adminPhones.some((entry) => phonesMatch(entry, normalized));
 }
 function checkDmAccess(params) {
   const { senderPhone, selfPhone } = params;
@@ -23852,7 +23871,7 @@ function checkDmAccess(params) {
   if (phonesMatch(senderPhone, selfPhone)) {
     return { allowed: true, reason: "self-phone", agentType: "admin" };
   }
-  if (isAdminPhone(senderPhone, cfg.allowFrom)) {
+  if (isAdminPhone(senderPhone, cfg.adminPhones)) {
     return { allowed: true, reason: "admin-binding", agentType: "admin" };
   }
   switch (cfg.dmPolicy) {
@@ -23893,10 +23912,7 @@ function checkGroupAccess(params) {
       return { allowed: true, reason: "group-policy-open", agentType: "public" };
     }
     case "allowlist": {
-      const inList = cfg.groupAllowFrom.some((entry) => phonesMatch(entry, senderPhone)) || cfg.allowFrom.some((entry) => {
-        if (entry === "*") return false;
-        return phonesMatch(entry, senderPhone);
-      });
+      const inList = cfg.groupAllowFrom.some((entry) => phonesMatch(entry, senderPhone)) || cfg.adminPhones.some((entry) => phonesMatch(entry, senderPhone));
       if (!inList) {
         return { allowed: false, reason: "not-in-group-allowlist", agentType: "public" };
       }
@@ -23996,7 +24012,7 @@ async function sendReadReceipt(sock, chatJid, messageIds, participant) {
 // app/lib/whatsapp/inbound/media.ts
 import { randomUUID as randomUUID6 } from "crypto";
 import { writeFile as writeFile2, mkdir as mkdir2 } from "fs/promises";
-import { join as join4 } from "path";
+import { join as join5 } from "path";
 import {
   downloadMediaMessage,
   downloadContentFromMessage,
@@ -24082,7 +24098,7 @@ async function downloadInboundMedia(msg, sock, opts) {
     await mkdir2(MEDIA_DIR, { recursive: true });
     const ext = mimeToExt(mimetype ?? "application/octet-stream");
     const filename = `${randomUUID6()}.${ext}`;
-    const filePath = join4(MEDIA_DIR, filename);
+    const filePath = join5(MEDIA_DIR, filename);
     await writeFile2(filePath, buffer);
     const sizeKB = (buffer.length / 1024).toFixed(0);
     console.error(`${TAG5} media downloaded type=${mimetype ?? "unknown"} size=${sizeKB}KB path=${filePath}`);
@@ -24580,7 +24596,7 @@ async function handleInboundMessage(conn, msg) {
 
 // app/lib/whatsapp/config-persist.ts
 import { readFileSync as readFileSync10, writeFileSync as writeFileSync6, existsSync as existsSync10 } from "fs";
-import { resolve as resolve9, join as join5 } from "path";
+import { resolve as resolve9, join as join6 } from "path";
 var TAG8 = "[whatsapp:config]";
 function configPath(accountDir) {
   return resolve9(accountDir, "account.json");
@@ -24604,6 +24620,25 @@ function reloadManagerConfig(accountDir) {
   }
 }
 var E164_PATTERN = /^\+\d{7,15}$/;
+function migrateAdminPhones(wa) {
+  if (wa.adminPhones !== void 0) return 0;
+  if (!Array.isArray(wa.allowFrom)) return 0;
+  const allowFrom = wa.allowFrom;
+  const phones = [];
+  const remaining = [];
+  for (const entry of allowFrom) {
+    if (E164_PATTERN.test(entry)) {
+      phones.push(entry);
+    } else {
+      remaining.push(entry);
+    }
+  }
+  if (phones.length === 0) return 0;
+  wa.adminPhones = phones;
+  wa.allowFrom = remaining;
+  console.error(`${TAG8} migrated ${phones.length} phone(s) from allowFrom to adminPhones`);
+  return phones.length;
+}
 function persistAfterPairing(accountDir, accountId, selfPhone) {
   try {
     const config2 = readConfig(accountDir);
@@ -24620,16 +24655,16 @@ function persistAfterPairing(accountDir, accountId, selfPhone) {
     }
     if (selfPhone) {
       const normalized = selfPhone.startsWith("+") ? selfPhone : `+${selfPhone}`;
-      if (!Array.isArray(wa.allowFrom)) {
-        wa.allowFrom = [];
+      if (!Array.isArray(wa.adminPhones)) {
+        wa.adminPhones = [];
       }
-      const allowFrom = wa.allowFrom;
-      if (!allowFrom.includes(normalized)) {
-        allowFrom.push(normalized);
-        console.error(`${TAG8} added selfPhone=${normalized} to allowFrom`);
+      const adminPhones = wa.adminPhones;
+      if (!adminPhones.includes(normalized)) {
+        adminPhones.push(normalized);
+        console.error(`${TAG8} added selfPhone=${normalized} to adminPhones`);
       }
     } else {
-      console.error(`${TAG8} skipping allowFrom \u2014 selfPhone is null account=${accountId}`);
+      console.error(`${TAG8} skipping adminPhones \u2014 selfPhone is null account=${accountId}`);
     }
     const parsed = WhatsAppConfigSchema.safeParse(wa);
     if (!parsed.success) {
@@ -24659,14 +24694,14 @@ function addAdminPhone(accountDir, phone) {
       config2.whatsapp = {};
     }
     const wa = config2.whatsapp;
-    if (!Array.isArray(wa.allowFrom)) {
-      wa.allowFrom = [];
+    if (!Array.isArray(wa.adminPhones)) {
+      wa.adminPhones = [];
     }
-    const allowFrom = wa.allowFrom;
-    if (allowFrom.includes(normalized)) {
+    const adminPhones = wa.adminPhones;
+    if (adminPhones.includes(normalized)) {
       return { ok: true, message: `Phone ${normalized} is already in the admin list.` };
     }
-    allowFrom.push(normalized);
+    adminPhones.push(normalized);
     const parsed = WhatsAppConfigSchema.safeParse(wa);
     if (!parsed.success) {
       const msg = parsed.error.issues.map((i) => `${i.path.join(".")}: ${i.message}`).join("; ");
@@ -24691,15 +24726,15 @@ function removeAdminPhone(accountDir, phone) {
       return { ok: true, message: `No WhatsApp config exists \u2014 nothing to remove.` };
     }
     const wa = config2.whatsapp;
-    if (!Array.isArray(wa.allowFrom)) {
+    if (!Array.isArray(wa.adminPhones)) {
       return { ok: true, message: `No admin phones configured \u2014 nothing to remove.` };
     }
-    const allowFrom = wa.allowFrom;
-    const idx = allowFrom.indexOf(normalized);
+    const adminPhones = wa.adminPhones;
+    const idx = adminPhones.indexOf(normalized);
     if (idx === -1) {
       return { ok: true, message: `Phone ${normalized} is not in the admin list.` };
     }
-    allowFrom.splice(idx, 1);
+    adminPhones.splice(idx, 1);
     const parsed = WhatsAppConfigSchema.safeParse(wa);
     if (!parsed.success) {
       const msg = parsed.error.issues.map((i) => `${i.path.join(".")}: ${i.message}`).join("; ");
@@ -24720,8 +24755,10 @@ function readAdminPhones(accountDir) {
   try {
     const config2 = readConfig(accountDir);
     const wa = config2.whatsapp;
-    if (!wa || !Array.isArray(wa.allowFrom)) return [];
-    return wa.allowFrom.filter((p) => typeof p === "string");
+    if (!wa) return [];
+    migrateAdminPhones(wa);
+    if (!Array.isArray(wa.adminPhones)) return [];
+    return wa.adminPhones.filter((p) => typeof p === "string");
   } catch {
     return [];
   }
@@ -24731,7 +24768,7 @@ function setPublicAgent(accountDir, slug) {
   if (!trimmed) {
     return { ok: false, error: "Agent slug cannot be empty." };
   }
-  const agentConfigPath = join5(accountDir, "agents", trimmed, "config.json");
+  const agentConfigPath = join6(accountDir, "agents", trimmed, "config.json");
   if (!existsSync10(agentConfigPath)) {
     return { ok: false, error: `Agent "${trimmed}" not found \u2014 no config.json at ${agentConfigPath}. Check the agent slug and try again.` };
   }
@@ -24772,6 +24809,57 @@ function getPublicAgent(accountDir) {
     return null;
   }
 }
+function updateConfig(accountDir, fields) {
+  const fieldNames = Object.keys(fields);
+  if (fieldNames.length === 0) {
+    return { ok: false, error: "No fields provided to update." };
+  }
+  try {
+    const config2 = readConfig(accountDir);
+    if (!config2.whatsapp || typeof config2.whatsapp !== "object") {
+      config2.whatsapp = {};
+    }
+    const wa = config2.whatsapp;
+    migrateAdminPhones(wa);
+    for (const [key, value] of Object.entries(fields)) {
+      wa[key] = value;
+    }
+    const parsed = WhatsAppConfigSchema.safeParse(wa);
+    if (!parsed.success) {
+      const msg = parsed.error.issues.map((i) => `${i.path.join(".")}: ${i.message}`).join("; ");
+      console.error(`${TAG8} update validation failed: ${msg}`);
+      return { ok: false, error: `Validation failed: ${msg}` };
+    }
+    config2.whatsapp = parsed.data;
+    writeConfig(accountDir, config2);
+    console.error(`${TAG8} updated fields=[${fieldNames.join(",")}]`);
+    reloadManagerConfig(accountDir);
+    return { ok: true, message: `Updated WhatsApp config: ${fieldNames.join(", ")}.` };
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    console.error(`${TAG8} updateConfig failed: ${msg}`);
+    return { ok: false, error: msg };
+  }
+}
+function getConfig(accountDir) {
+  try {
+    const config2 = readConfig(accountDir);
+    const wa = config2.whatsapp;
+    if (!wa) return null;
+    const migrated = migrateAdminPhones(wa);
+    if (migrated > 0) {
+      const parsed = WhatsAppConfigSchema.safeParse(wa);
+      if (parsed.success) {
+        config2.whatsapp = parsed.data;
+        writeConfig(accountDir, config2);
+        reloadManagerConfig(accountDir);
+      }
+    }
+    return wa;
+  } catch {
+    return null;
+  }
+}
 
 // app/api/whatsapp/login/wait/route.ts
 async function POST10(req) {
@@ -24958,7 +25046,7 @@ function serializeWhatsAppSchema() {
     "",
     "## Constraints (superRefine)",
     "",
-    '- `dmPolicy: "open"` requires `allowFrom` to include `"*"` (both top-level and per-account)',
+    '- `dmPolicy: "open"` requires `allowFrom` to include `"*"` (both top-level and per-account). This is a DM policy constraint \u2014 it does not affect admin phones, which live in the separate `adminPhones` field.',
     "- Account-level fields override top-level defaults when present"
   ].join("\n");
   return [topLevel, "", account, constraints].join("\n");
@@ -24968,7 +25056,7 @@ function serializeWhatsAppSchema() {
 async function POST14(req) {
   try {
     const body = await req.json().catch(() => ({}));
-    const { action, phone, slug, accountId } = body;
+    const { action, phone, slug, fields, accountId } = body;
     if (!action || typeof action !== "string") {
       return Response.json({ ok: false, error: 'Missing required field "action".' }, { status: 400 });
     }
@@ -25037,9 +25125,23 @@ async function POST14(req) {
           return Response.json({ ok: false, error: `Failed to fetch groups: ${String(err)}` });
         }
       }
+      case "update-config": {
+        if (!fields || typeof fields !== "object" || Array.isArray(fields)) {
+          return Response.json({ ok: false, error: 'Missing required field "fields" (object with config field names and values).' }, { status: 400 });
+        }
+        const result = updateConfig(account.accountDir, fields);
+        const fieldNames = Object.keys(fields);
+        console.error(`[whatsapp:api] config action=update-config fields=[${fieldNames.join(",")}] ok=${result.ok}`);
+        return Response.json(result, { status: result.ok ? 200 : 400 });
+      }
+      case "get-config": {
+        const waConfig = getConfig(account.accountDir);
+        console.error(`[whatsapp:api] config action=get-config`);
+        return Response.json({ ok: true, config: waConfig });
+      }
       default:
         return Response.json(
-          { ok: false, error: `Unknown action "${action}". Valid actions: add-admin-phone, remove-admin-phone, list-admin-phones, set-public-agent, get-public-agent, schema, list-groups.` },
+          { ok: false, error: `Unknown action "${action}". Valid actions: add-admin-phone, remove-admin-phone, list-admin-phones, set-public-agent, get-public-agent, update-config, get-config, schema, list-groups.` },
           { status: 400 }
         );
     }
@@ -25800,11 +25902,11 @@ async function GET7() {
 
 // app/api/admin/version/route.ts
 import { readFileSync as readFileSync17, existsSync as existsSync17 } from "fs";
-import { resolve as resolve14, join as join6 } from "path";
+import { resolve as resolve14, join as join7 } from "path";
 var PLATFORM_ROOT6 = process.env.MAXY_PLATFORM_ROOT ?? resolve14(process.cwd(), "..");
 var brandHostname = "maxy";
 var brandNpmPackage = "@rubytech/create-maxy";
-var brandJsonPath = join6(PLATFORM_ROOT6, "config", "brand.json");
+var brandJsonPath = join7(PLATFORM_ROOT6, "config", "brand.json");
 if (existsSync17(brandJsonPath)) {
   try {
     const brand = JSON.parse(readFileSync17(brandJsonPath, "utf-8"));
@@ -25876,11 +25978,11 @@ async function GET8() {
 // app/api/admin/version/upgrade/route.ts
 import { spawn as spawn4 } from "child_process";
 import { existsSync as existsSync18, statSync as statSync4, writeFileSync as writeFileSync11, readFileSync as readFileSync18, openSync as openSync2, closeSync as closeSync2 } from "fs";
-import { resolve as resolve15, join as join7 } from "path";
+import { resolve as resolve15, join as join8 } from "path";
 var PLATFORM_ROOT7 = process.env.MAXY_PLATFORM_ROOT ?? resolve15(process.cwd(), "..");
 var upgradePkg = "@rubytech/create-maxy";
 var upgradeHostname = "maxy";
-var brandPath = join7(PLATFORM_ROOT7, "config", "brand.json");
+var brandPath = join8(PLATFORM_ROOT7, "config", "brand.json");
 if (existsSync18(brandPath)) {
   try {
     const brand = JSON.parse(readFileSync18(brandPath, "utf-8"));
@@ -26047,7 +26149,7 @@ async function POST21() {
 
 // server/index.ts
 var PLATFORM_ROOT8 = process.env.MAXY_PLATFORM_ROOT || "";
-var BRAND_JSON_PATH = PLATFORM_ROOT8 ? join8(PLATFORM_ROOT8, "config", "brand.json") : "";
+var BRAND_JSON_PATH = PLATFORM_ROOT8 ? join9(PLATFORM_ROOT8, "config", "brand.json") : "";
 var BRAND = { productName: "Maxy", hostname: "maxy", configDir: ".maxy", domain: "getmaxy.com" };
 if (BRAND_JSON_PATH && !existsSync19(BRAND_JSON_PATH)) {
   console.error(`[brand] WARNING: brand.json not found at ${BRAND_JSON_PATH} \u2014 using Maxy defaults`);
@@ -26066,7 +26168,7 @@ var brandLoginOpts = {
   primaryHoverColor: BRAND.defaultColors?.primaryHover,
   primarySubtle: BRAND.defaultColors?.primarySubtle
 };
-var ALIAS_DOMAINS_PATH = join8(homedir2(), BRAND.configDir, "alias-domains.json");
+var ALIAS_DOMAINS_PATH = join9(homedir3(), BRAND.configDir, "alias-domains.json");
 function loadAliasDomains() {
   try {
     if (!existsSync19(ALIAS_DOMAINS_PATH)) return null;
@@ -26436,14 +26538,14 @@ function cachedHtml(file2) {
 }
 var brandedHtmlCache = /* @__PURE__ */ new Map();
 function loadBrandingCache(agentSlug) {
-  const configDir2 = join8(homedir2(), BRAND.configDir);
+  const configDir2 = join9(homedir3(), BRAND.configDir);
   try {
-    const accountJsonPath = join8(configDir2, "account.json");
+    const accountJsonPath = join9(configDir2, "account.json");
     if (!existsSync19(accountJsonPath)) return null;
     const account = JSON.parse(readFileSync19(accountJsonPath, "utf-8"));
     const accountId = account.accountId;
     if (!accountId) return null;
-    const cachePath = join8(configDir2, "branding-cache", accountId, `${agentSlug}.json`);
+    const cachePath = join9(configDir2, "branding-cache", accountId, `${agentSlug}.json`);
     if (!existsSync19(cachePath)) return null;
     return JSON.parse(readFileSync19(cachePath, "utf-8"));
   } catch {
@@ -26452,8 +26554,8 @@ function loadBrandingCache(agentSlug) {
 }
 function resolveDefaultSlug() {
   try {
-    const configDir2 = join8(homedir2(), BRAND.configDir);
-    const accountJsonPath = join8(configDir2, "account.json");
+    const configDir2 = join9(homedir3(), BRAND.configDir);
+    const accountJsonPath = join9(configDir2, "account.json");
     if (!existsSync19(accountJsonPath)) return null;
     const account = JSON.parse(readFileSync19(accountJsonPath, "utf-8"));
     return account.defaultAgent || null;
@@ -26532,7 +26634,7 @@ if (bootAccountConfig?.whatsapp) {
 }
 init({
   configDir: configDirForWhatsApp,
-  platformRoot: resolve16(process.env.MAXY_PLATFORM_ROOT ?? join8(__dirname, "..")),
+  platformRoot: resolve16(process.env.MAXY_PLATFORM_ROOT ?? join9(__dirname, "..")),
   accountConfig: bootAccountConfig,
   onMessage: async (msg) => {
     try {

package/payload/platform/plugins/email/PLUGIN.md

@@ -20,202 +20,28 @@ metadata: {"platform":{"optional":true,"recommended":true}}
 
 Manages the agent's own dedicated email account — IMAP for reading, SMTP for sending. Admin agent only.
 
-## Setup
+## Capabilities
 
-Collect email credentials via a form. Render this `form` component with `render-component`:
+- **Setup:** `email-setup` — collect credentials via rendered `form`, connect IMAP/SMTP. Supports alias addresses (`agentAddress`).
+- **Read inbox:** `email-read` — metadata only (UID, sender, subject, date). Supports pagination (`before_uid`), folders (`inbox`/`sent`), filtering by sender/date/subject.
+- **Search inbox:** `email-search` — live IMAP search by sender, subject, body keyword, date range.
+- **Send:** `email-send` — new outbound email.
+- **Reply:** `email-reply` — threaded reply to an existing email by `messageId`. Supports `replyAll`.
+- **Recall/history:** `email-graph-query` — search stored emails in Neo4j by natural language, sender, date, direction.
+- **Status:** `email-status` — connection health and configuration state.
+- **Auto-respond:** `email-auto-respond-config` — enable/disable automated public agent replies to inbound email.
+- **OTP:** `email-otp-extract` — poll for verification codes during service authentication.
 
-**Fields:**
+## Retrieval paths
 
-| name | label | type | required | placeholder |
-|------|-------|------|----------|-------------|
-| `email` | Email address | text | yes | user@example.com |
-| `password` | Password | text | yes | App password or account password |
-| `imapHost` | IMAP host | text | yes | imap.example.com |
-| `imapPort` | IMAP port | number | yes | 993 |
-| `imapSecurity` | IMAP security | select | yes | Options: `tls` (default), `starttls` |
-| `smtpHost` | SMTP host | text | yes | smtp.example.com |
-| `smtpPort` | SMTP port | number | yes | 587 |
-| `smtpSecurity` | SMTP security | select | yes | Options: `tls`, `starttls` (default) |
-| `agentAddress` | Agent email address (if different from login) | text | no | agent@yourdomain.com |
+- **Live inbox** (`email-read`, `email-search`) — real-time IMAP queries. Use for checking the inbox or reading recent messages.
+- **Graph history** (`email-graph-query`) — stored Email nodes in Neo4j. Use for recall, semantic search, email history questions.
+- **General knowledge** (`memory-search`) — cross-type knowledge graph. Use when the question spans all memory, not just emails.
 
-The `agentAddress` field is for catchall/alias setups where the authentication email differs from the address the agent operates as. Leave empty when they're the same.
+## References
 
-After form submission, pass all fields to `email-setup`. On success, confirm "credentials stored" and the inbox count. On failure, relay the diagnostic — the tool returns specific guidance (wrong password, connection refused, TLS mismatch).
+| Reference | Topics |
+|-----------|--------|
+| [email-reference.md](references/email-reference.md) | Setup form fields, pagination, filtering, replying, alias support, persistence, threading, screening, auto-respond, rate limiting, OTP integration |
 
-The agent never displays stored passwords. Never name or recommend specific email providers — the form collects the standard fields every provider gives its users.
-
-## Reading and Searching
-
-`email-read` and `email-search` return message metadata only: UID, sender, subject, and date. Body content is not included — present results as a message list without commenting on missing bodies.
-
-### Pagination
-
-Both tools return up to 50 messages per request (default 20). When more messages exist beyond the returned set, the response includes a `next_before_uid` value. Pass this value as the `before_uid` parameter on the next call to retrieve the next page of older messages. When `next_before_uid` is absent, all matching messages have been returned.
-
-### Folders
-
-Both tools accept a `folder` parameter: `"inbox"` (default) or `"sent"`. The Sent folder is discovered automatically via the IMAP server's special-use flags — no folder name guessing required.
-
-### Filtering
-
-Both tools support filtering by:
-- `sender` — sender address or domain
-- `to` — recipient address
-- `since` / `before` — ISO date range
-- `email-read` additionally supports `subjectPattern` (regex)
-- `email-search` additionally supports `subject` (text) and `body` (keyword)
-
-## Replying
-
-`email-reply` sends a reply to an existing email, threaded correctly in the recipient's mail client.
-
-The tool accepts the `messageId` of the email being replied to (visible in `email-read` output as the `Message-ID` field). It looks up the original email in the graph, sets `In-Reply-To` and `References` headers, derives the recipient from the original sender, and prepends `Re:` to the subject (stripping duplicate prefixes).
-
-- **Reply to sender:** Default behaviour — replies to the original sender only.
-- **Reply all:** Set `replyAll: true` to include all original recipients (TO + CC). The agent's own address is automatically excluded from the recipient list.
-- **Threading:** The reply appears in the same conversation thread in Gmail, Apple Mail, Outlook, and other RFC 2822-compliant clients.
-- **Prerequisite:** The original email must exist in the graph (stored by the background polling job). If the email hasn't been fetched yet, the tool returns a clear error.
-
-Use `email-reply` when responding to a received email. Use `email-send` for new outbound messages.
-
-## Alias Support
-
-When `agentAddress` is set and differs from the auth email:
-
-- **Sending:** emails are sent with the agent address as the From header. SMTP authentication still uses the auth email.
-- **Reading/searching:** only emails whose TO header contains the agent address are returned. The agent ignores emails to other addresses on the same mailbox.
-- **OTP extraction:** only OTPs addressed to the agent address are found.
-- **Status:** reports both the agent address and the auth email.
-
-When `agentAddress` is not set or matches the auth email, all tools behave as before — no filtering, From header uses the auth email.
-
-## Email Persistence
-
-Emails are automatically polled from IMAP and stored as `Email` nodes in the graph. This happens via a background cron job — no manual triggering needed.
-
-- **Polling:** After `email-setup` completes, the platform polls IMAP at the configured interval (default: every 5 minutes). Only emails addressed TO the agent's `agentAddress` are stored.
-- **Deduplication:** Each email is identified by its Message-ID header. Re-polling the same messages does not create duplicates, even if the agent's email address changes between poll cycles. A composite unique constraint on `(messageId, accountId)` provides database-level enforcement.
-- **Semantic search:** Stored emails are vector-indexed (subject + body preview), enabling natural-language search over email history via `email-graph-query`.
-- **Isolation:** Each agent sees only emails addressed to its own bound email address, even when sharing a catchall mailbox.
-
-## Email Threading
-
-Emails are linked into conversation threads via `REPLY_TO` graph edges. When an email has an `In-Reply-To` header, the platform looks up the parent email by `Message-ID` within the same account and creates an edge. Thread linking happens automatically during the polling cron job.
-
-- **Out-of-order delivery:** If a reply arrives before its parent, the edge is created later when the parent is stored (orphan back-fill).
-- **Thread context:** `email-read` and `email-search` include `Thread-Depth` (number of hops to the thread root) and `Thread-ID` (emailId of the root message) for any email that is part of a thread. Root emails (no parent) have no thread fields.
-- **Scope:** Thread edges never cross account boundaries — parent lookups are always scoped to the same account.
-
-## Auto-Respond Audit Trail
-
-When auto-respond sends a reply, the outbound message is stored as an `Email` node with `direction: "outbound"` and a `REPLY_TO` edge to the original inbound email. This creates a queryable audit trail of every automated reply — what the agent said, when, and to whom.
-
-Outbound email nodes have the same properties as inbound emails (subject, bodyPreview, fromAddress, toAddresses, timestamps) plus the `direction` property. They appear in thread traversals alongside inbound messages.
-
-### Agent-Email Binding
-
-Each email address is bound to exactly one agent. Each agent can have at most one email address. This is enforced during `email-setup`:
-
-- The `agentSlug` parameter identifies which agent owns this email address (defaults to `"admin"`)
-- If the address is already bound to a different agent, setup fails with a clear error naming the conflicting agent
-- The binding is on `agentAddress` (the identity the agent presents), not the auth email
-
-### Email Retrieval Paths
-
-Three retrieval paths exist for email data — each scoped to a different purpose:
-
-- **Live inbox** (`email-read`, `email-search`) — queries IMAP directly. Use for checking the inbox, reading recent messages, browsing folders, and real-time inbox state. Requires IMAP connectivity.
-- **Graph list/search** (`email-graph-query`) — queries stored Email nodes in Neo4j. Use for email history, recall, and semantic search ("what emails are in memory?", "find emails about cabbages", "what did Sarah send about the contract?"). Works without IMAP. Supports date/sender/direction filters and natural-language semantic matching.
-- **General knowledge** (`memory-search`) — searches the entire knowledge graph across all node types. Use when the user's question spans all memory, not just emails ("what do you know about contract renewals?").
-
-When the user asks about stored emails, email history, or email recall — use `email-graph-query`. When they ask to check the inbox or read specific recent messages — use the IMAP tools. When the question is broader than emails — use `memory-search`.
-
-## Inbound Email Screening
-
-Every inbound email is classified by Claude Haiku before entering Neo4j. The classifier examines `fromAddress`, `fromName`, `subject`, and the first 1024 characters of `bodyPreview`.
-
-### Verdicts
-
-| Verdict | Stored? | Embedding? | Auto-respond? | Graph query? |
-|---------|---------|------------|---------------|--------------|
-| `clean` | Yes | Yes | Yes | Yes |
-| `suspicious` | Yes (with `screeningReason`) | Yes | No | Yes |
-| `discarded` | Yes (with `screeningReason`) | No | No | No (list mode) |
-
-- **clean** — legitimate personal or business correspondence
-- **suspicious** — phishing indicators (urgency + credential requests, mismatched sender), prompt injection patterns, or classification failure (safe default)
-- **discarded** — obvious spam, marketing bulk mail, auto-generated notifications with no actionable content
-
-### Prompt injection flag
-
-When `promptInjectionFlag` is true (body contains instruction-like patterns targeting an AI agent), auto-respond skips the email entirely regardless of verdict. No reply is generated. The email is visible in Neo4j for admin review.
-
-### Failure handling
-
-If the Haiku API is unavailable (network, rate limit, auth failure), the email defaults to `suspicious`. The entire fetch batch is never blocked — each email is classified independently. API key absence causes all emails in the batch to default to `suspicious`.
-
-### Logs
-
-Classification verdicts are logged to `{accountDir}/logs/email-fetch.log` with per-email detail (fromAddress, verdict, reason, promptInjectionRisk) and batch summaries.
-
-## Security
-
-- Credentials stored as a file with restricted permissions — never in conversation
-- IMAP and SMTP connections require TLS or STARTTLS — plaintext is rejected
-- Only the agent's own dedicated account is accessed — never the user's personal email
-- Email nodes have `scope: "admin"` — never visible to public agents
-- Inbound emails are classified by Haiku before storage — prompt injection and phishing are flagged
-
-## Auto-Respond
-
-When enabled, a public agent automatically replies to incoming emails. A cron job polls the inbox for new messages and generates replies via the assigned agent.
-
-### Setup
-
-To enable auto-respond, call `email-auto-respond-config` with `enabled: true`. The tool requires an `agentSlug` — render a `single-select` component with available public agents so the admin can choose which agent handles responses. The tool returns the agent list when called without a slug.
-
-When called without an `agentSlug`, the tool returns available agents. Present these as a `single-select` component for the admin to choose from, then call the tool again with the selected slug.
-
-### Configuration
-
-- `enabled` — `true` to enable, `false` to disable
-- `agentSlug` — slug of the public agent that responds (required when enabling)
-- `pollIntervalMinutes` — how often to check for new emails (default: 5, range: 1–60)
-- `hourlyLimit` — maximum auto-replies per clock hour UTC (default: 20, range: 1–1000)
-- `dailyLimit` — maximum auto-replies per calendar day UTC (default: 100, range: 1–10000)
-
-### Behaviour
-
-- The cron job runs every minute. Each account's poll is skipped if the configured interval hasn't elapsed since the last poll.
-- Only emails addressed TO the agent's email address are processed (alias filtering applies).
-- Auto-replies, mailing list messages, and emails from the agent's own address are automatically skipped (RFC 3834 loop prevention).
-- Outgoing replies include `In-Reply-To` and `References` headers for correct threading, and `Auto-Submitted: auto-replied` to prevent loops with other auto-responders.
-- The subject line carries a single `Re:` prefix (no doubling).
-
-### Rate Limiting
-
-Per-account send caps prevent runaway auto-replies from spam waves, mailing list explosions, or deliberate attacks. Two independent limits:
-
-- **Hourly limit** (default 20) — resets at each UTC clock-hour boundary
-- **Daily limit** (default 100) — resets at midnight UTC
-
-When either limit is reached, remaining emails in the poll cycle are skipped (not replied to). Auto-respond is **not** disabled — counters reset naturally at the next boundary. A medium-priority admin Task is created to notify the admin.
-
-Within a single poll cycle, only one auto-reply is sent per unique sender address. This prevents reply storms when an automated sender delivers multiple messages. Sender deduplication is case-insensitive.
-
-### Circuit Breaker
-
-After 3 consecutive failures (IMAP errors, API failures, SMTP rejections), auto-respond is automatically disabled and a high-priority Task is created for the admin. The admin sees this task at the start of their next session and can re-enable auto-respond after resolving the issue.
-
-### Disabling
-
-Call `email-auto-respond-config` with `enabled: false`. This clears the agent assignment and resets the failure counter.
-
-## OTP Integration
-
-Other skills call `email-otp-extract` during service authentication (Anthropic OAuth, Cloudflare setup) with:
-- `sender` — expected sender domain
-- `subject_pattern` — optional regex for subject line
-- `timeout` — how long to poll (default 60s)
-
-The tool polls at short intervals, extracts the verification code, and returns it. On timeout, it returns a clear failure so the calling skill can ask the user to check manually.
+Load the reference via `plugin-read` when detailed configuration or behaviour information is needed.

package/payload/platform/plugins/email/references/email-reference.md

@@ -0,0 +1,203 @@
+# Email Reference
+
+Full reference for the email plugin. Load with `plugin-read` when detailed configuration or behaviour reference is needed.
+
+## Setup
+
+Collect email credentials via a form. Render this `form` component with `render-component`:
+
+**Fields:**
+
+| name | label | type | required | placeholder |
+|------|-------|------|----------|-------------|
+| `email` | Email address | text | yes | user@example.com |
+| `password` | Password | text | yes | App password or account password |
+| `imapHost` | IMAP host | text | yes | imap.example.com |
+| `imapPort` | IMAP port | number | yes | 993 |
+| `imapSecurity` | IMAP security | select | yes | Options: `tls` (default), `starttls` |
+| `smtpHost` | SMTP host | text | yes | smtp.example.com |
+| `smtpPort` | SMTP port | number | yes | 587 |
+| `smtpSecurity` | SMTP security | select | yes | Options: `tls`, `starttls` (default) |
+| `agentAddress` | Agent email address (if different from login) | text | no | agent@yourdomain.com |
+
+The `agentAddress` field is for catchall/alias setups where the authentication email differs from the address the agent operates as. Leave empty when they're the same.
+
+After form submission, pass all fields to `email-setup`. On success, confirm "credentials stored" and the inbox count. On failure, relay the diagnostic — the tool returns specific guidance (wrong password, connection refused, TLS mismatch).
+
+The agent never displays stored passwords. Never name or recommend specific email providers — the form collects the standard fields every provider gives its users.
+
+## Reading and Searching
+
+`email-read` and `email-search` return message metadata only: UID, sender, subject, and date. Body content is not included — present results as a message list without commenting on missing bodies.
+
+### Pagination
+
+Both tools return up to 50 messages per request (default 20). When more messages exist beyond the returned set, the response includes a `next_before_uid` value. Pass this value as the `before_uid` parameter on the next call to retrieve the next page of older messages. When `next_before_uid` is absent, all matching messages have been returned.
+
+### Folders
+
+Both tools accept a `folder` parameter: `"inbox"` (default) or `"sent"`. The Sent folder is discovered automatically via the IMAP server's special-use flags — no folder name guessing required.
+
+### Filtering
+
+Both tools support filtering by:
+- `sender` — sender address or domain
+- `to` — recipient address
+- `since` / `before` — ISO date range
+- `email-read` additionally supports `subjectPattern` (regex)
+- `email-search` additionally supports `subject` (text) and `body` (keyword)
+
+## Replying
+
+`email-reply` sends a reply to an existing email, threaded correctly in the recipient's mail client.
+
+The tool accepts the `messageId` of the email being replied to (visible in `email-read` output as the `Message-ID` field). It looks up the original email in the graph, sets `In-Reply-To` and `References` headers, derives the recipient from the original sender, and prepends `Re:` to the subject (stripping duplicate prefixes).
+
+- **Reply to sender:** Default behaviour — replies to the original sender only.
+- **Reply all:** Set `replyAll: true` to include all original recipients (TO + CC). The agent's own address is automatically excluded from the recipient list.
+- **Threading:** The reply appears in the same conversation thread in Gmail, Apple Mail, Outlook, and other RFC 2822-compliant clients.
+- **Prerequisite:** The original email must exist in the graph (stored by the background polling job). If the email hasn't been fetched yet, the tool returns a clear error.
+
+Use `email-reply` when responding to a received email. Use `email-send` for new outbound messages.
+
+## Alias Support
+
+When `agentAddress` is set and differs from the auth email:
+
+- **Sending:** emails are sent with the agent address as the From header. SMTP authentication still uses the auth email.
+- **Reading/searching:** only emails whose TO header contains the agent address are returned. The agent ignores emails to other addresses on the same mailbox.
+- **OTP extraction:** only OTPs addressed to the agent address are found.
+- **Status:** reports both the agent address and the auth email.
+
+When `agentAddress` is not set or matches the auth email, all tools behave as before — no filtering, From header uses the auth email.
+
+## Email Persistence
+
+Emails are automatically polled from IMAP and stored as `Email` nodes in the graph. This happens via a background cron job — no manual triggering needed.
+
+- **Polling:** After `email-setup` completes, the platform polls IMAP at the configured interval (default: every 5 minutes). Only emails addressed TO the agent's `agentAddress` are stored.
+- **Deduplication:** Each email is identified by its Message-ID header. Re-polling the same messages does not create duplicates, even if the agent's email address changes between poll cycles. A composite unique constraint on `(messageId, accountId)` provides database-level enforcement.
+- **Semantic search:** Stored emails are vector-indexed (subject + body preview), enabling natural-language search over email history via `email-graph-query`.
+- **Isolation:** Each agent sees only emails addressed to its own bound email address, even when sharing a catchall mailbox.
+
+## Email Threading
+
+Emails are linked into conversation threads via `REPLY_TO` graph edges. When an email has an `In-Reply-To` header, the platform looks up the parent email by `Message-ID` within the same account and creates an edge. Thread linking happens automatically during the polling cron job.
+
+- **Out-of-order delivery:** If a reply arrives before its parent, the edge is created later when the parent is stored (orphan back-fill).
+- **Thread context:** `email-read` and `email-search` include `Thread-Depth` (number of hops to the thread root) and `Thread-ID` (emailId of the root message) for any email that is part of a thread. Root emails (no parent) have no thread fields.
+- **Scope:** Thread edges never cross account boundaries — parent lookups are always scoped to the same account.
+
+## Auto-Respond Audit Trail
+
+When auto-respond sends a reply, the outbound message is stored as an `Email` node with `direction: "outbound"` and a `REPLY_TO` edge to the original inbound email. This creates a queryable audit trail of every automated reply — what the agent said, when, and to whom.
+
+Outbound email nodes have the same properties as inbound emails (subject, bodyPreview, fromAddress, toAddresses, timestamps) plus the `direction` property. They appear in thread traversals alongside inbound messages.
+
+### Agent-Email Binding
+
+Each email address is bound to exactly one agent. Each agent can have at most one email address. This is enforced during `email-setup`:
+
+- The `agentSlug` parameter identifies which agent owns this email address (defaults to `"admin"`)
+- If the address is already bound to a different agent, setup fails with a clear error naming the conflicting agent
+- The binding is on `agentAddress` (the identity the agent presents), not the auth email
+
+### Email Retrieval Paths
+
+Three retrieval paths exist for email data — each scoped to a different purpose:
+
+- **Live inbox** (`email-read`, `email-search`) — queries IMAP directly. Use for checking the inbox, reading recent messages, browsing folders, and real-time inbox state. Requires IMAP connectivity.
+- **Graph list/search** (`email-graph-query`) — queries stored Email nodes in Neo4j. Use for email history, recall, and semantic search ("what emails are in memory?", "find emails about cabbages", "what did Sarah send about the contract?"). Works without IMAP. Supports date/sender/direction filters and natural-language semantic matching.
+- **General knowledge** (`memory-search`) — searches the entire knowledge graph across all node types. Use when the user's question spans all memory, not just emails ("what do you know about contract renewals?").
+
+When the user asks about stored emails, email history, or email recall — use `email-graph-query`. When they ask to check the inbox or read specific recent messages — use the IMAP tools. When the question is broader than emails — use `memory-search`.
+
+## Inbound Email Screening
+
+Every inbound email is classified by Claude Haiku before entering Neo4j. The classifier examines `fromAddress`, `fromName`, `subject`, and the first 1024 characters of `bodyPreview`.
+
+### Verdicts
+
+| Verdict | Stored? | Embedding? | Auto-respond? | Graph query? |
+|---------|---------|------------|---------------|--------------|
+| `clean` | Yes | Yes | Yes | Yes |
+| `suspicious` | Yes (with `screeningReason`) | Yes | No | Yes |
+| `discarded` | Yes (with `screeningReason`) | No | No | No (list mode) |
+
+- **clean** — legitimate personal or business correspondence
+- **suspicious** — phishing indicators (urgency + credential requests, mismatched sender), prompt injection patterns, or classification failure (safe default)
+- **discarded** — obvious spam, marketing bulk mail, auto-generated notifications with no actionable content
+
+### Prompt injection flag
+
+When `promptInjectionFlag` is true (body contains instruction-like patterns targeting an AI agent), auto-respond skips the email entirely regardless of verdict. No reply is generated. The email is visible in Neo4j for admin review.
+
+### Failure handling
+
+If the Haiku API is unavailable (network, rate limit, auth failure), the email defaults to `suspicious`. The entire fetch batch is never blocked — each email is classified independently. API key absence causes all emails in the batch to default to `suspicious`.
+
+### Logs
+
+Classification verdicts are logged to `{accountDir}/logs/email-fetch.log` with per-email detail (fromAddress, verdict, reason, promptInjectionRisk) and batch summaries.
+
+## Security
+
+- Credentials stored as a file with restricted permissions — never in conversation
+- IMAP and SMTP connections require TLS or STARTTLS — plaintext is rejected
+- Only the agent's own dedicated account is accessed — never the user's personal email
+- Email nodes have `scope: "admin"` — never visible to public agents
+- Inbound emails are classified by Haiku before storage — prompt injection and phishing are flagged
+
+## Auto-Respond
+
+When enabled, a public agent automatically replies to incoming emails. A cron job polls the inbox for new messages and generates replies via the assigned agent.
+
+### Setup
+
+To enable auto-respond, call `email-auto-respond-config` with `enabled: true`. The tool requires an `agentSlug` — render a `single-select` component with available public agents so the admin can choose which agent handles responses. The tool returns the agent list when called without a slug.
+
+When called without an `agentSlug`, the tool returns available agents. Present these as a `single-select` component for the admin to choose from, then call the tool again with the selected slug.
+
+### Configuration
+
+- `enabled` — `true` to enable, `false` to disable
+- `agentSlug` — slug of the public agent that responds (required when enabling)
+- `pollIntervalMinutes` — how often to check for new emails (default: 5, range: 1–60)
+- `hourlyLimit` — maximum auto-replies per clock hour UTC (default: 20, range: 1–1000)
+- `dailyLimit` — maximum auto-replies per calendar day UTC (default: 100, range: 1–10000)
+
+### Behaviour
+
+- The cron job runs every minute. Each account's poll is skipped if the configured interval hasn't elapsed since the last poll.
+- Only emails addressed TO the agent's email address are processed (alias filtering applies).
+- Auto-replies, mailing list messages, and emails from the agent's own address are automatically skipped (RFC 3834 loop prevention).
+- Outgoing replies include `In-Reply-To` and `References` headers for correct threading, and `Auto-Submitted: auto-replied` to prevent loops with other auto-responders.
+- The subject line carries a single `Re:` prefix (no doubling).
+
+### Rate Limiting
+
+Per-account send caps prevent runaway auto-replies from spam waves, mailing list explosions, or deliberate attacks. Two independent limits:
+
+- **Hourly limit** (default 20) — resets at each UTC clock-hour boundary
+- **Daily limit** (default 100) — resets at midnight UTC
+
+When either limit is reached, remaining emails in the poll cycle are skipped (not replied to). Auto-respond is **not** disabled — counters reset naturally at the next boundary. A medium-priority admin Task is created to notify the admin.
+
+Within a single poll cycle, only one auto-reply is sent per unique sender address. This prevents reply storms when an automated sender delivers multiple messages. Sender deduplication is case-insensitive.
+
+### Circuit Breaker
+
+After 3 consecutive failures (IMAP errors, API failures, SMTP rejections), auto-respond is automatically disabled and a high-priority Task is created for the admin. The admin sees this task at the start of their next session and can re-enable auto-respond after resolving the issue.
+
+### Disabling
+
+Call `email-auto-respond-config` with `enabled: false`. This clears the agent assignment and resets the failure counter.
+
+## OTP Integration
+
+Other skills call `email-otp-extract` during service authentication (Anthropic OAuth, Cloudflare setup) with:
+- `sender` — expected sender domain
+- `subject_pattern` — optional regex for subject line
+- `timeout` — how long to poll (default 60s)
+
+The tool polls at short intervals, extracts the verification code, and returns it. On timeout, it returns a clear failure so the calling skill can ask the user to check manually.

package/payload/platform/plugins/whatsapp/mcp/dist/index.js

@@ -127,14 +127,25 @@ server.tool("whatsapp-send", "Send a WhatsApp message to a phone number or group
     }
 });
 // ─── whatsapp-config ──────────────────────────────────────────────────
-server.tool("whatsapp-config", "Manage WhatsApp configuration. Actions: add-admin-phone (register a phone as admin — messages from it route to admin agent), remove-admin-phone (demote to public routing), list-admin-phones (show current admin phones), set-public-agent (set which agent handles WhatsApp messages from non-admin phones — requires the agent slug), get-public-agent (show the currently configured public agent), schema (return all config field definitions — names, types, defaults, descriptions, constraints), list-groups (return WhatsApp groups the account belongs to — names, JIDs, participant counts). Phone numbers must be E.164 format (e.g. +441234567890).", {
-    action: z.enum(["add-admin-phone", "remove-admin-phone", "list-admin-phones", "set-public-agent", "get-public-agent", "schema", "list-groups"]).describe("The config action to perform"),
+server.tool("whatsapp-config", "Manage WhatsApp configuration. Actions: add-admin-phone (register a phone as admin — messages from it route to admin agent), remove-admin-phone (demote to public routing), list-admin-phones (show current admin phones), set-public-agent (set which agent handles WhatsApp messages from non-admin phones — requires the agent slug), get-public-agent (show the currently configured public agent), update-config (change any WhatsApp config field — pass field names and values in the fields parameter), get-config (return the full current WhatsApp config object), schema (return all config field definitions — names, types, defaults, descriptions, constraints), list-groups (return WhatsApp groups the account belongs to — names, JIDs, participant counts). Phone numbers must be E.164 format (e.g. +441234567890).", {
+    action: z.enum(["add-admin-phone", "remove-admin-phone", "list-admin-phones", "set-public-agent", "get-public-agent", "update-config", "get-config", "schema", "list-groups"]).describe("The config action to perform"),
     phone: z.string().optional().describe("Phone number in E.164 format (required for add/remove admin phone)"),
     slug: z.string().optional().describe("Agent slug (required for set-public-agent)"),
+    fields: z.string().optional().describe('JSON string of config fields to update (required for update-config, e.g. \'{"dmPolicy":"open","allowFrom":["*"]}\')'),
     accountId: z.string().optional().describe('Account ID for list-groups (default: "default")'),
-}, async ({ action, phone, slug, accountId }) => {
+}, async ({ action, phone, slug, fields, accountId }) => {
     try {
-        const result = await callApi("/api/whatsapp/config", "POST", { action, phone, slug, accountId });
+        // Parse fields JSON string for update-config
+        let parsedFields;
+        if (action === "update-config" && fields) {
+            try {
+                parsedFields = JSON.parse(fields);
+            }
+            catch {
+                return textResult('Invalid JSON in "fields" parameter. Expected a JSON object, e.g. {"dmPolicy":"open","allowFrom":["*"]}', true);
+            }
+        }
+        const result = await callApi("/api/whatsapp/config", "POST", { action, phone, slug, fields: parsedFields, accountId });
         if (!result.ok)
             return textResult(result.error ?? "Config operation failed.", true);
         if (action === "list-admin-phones") {
@@ -152,6 +163,12 @@ server.tool("whatsapp-config", "Manage WhatsApp configuration. Actions: add-admi
         if (action === "schema") {
             return textResult(result.text ?? "Schema unavailable.");
         }
+        if (action === "get-config") {
+            const waConfig = result.config;
+            if (!waConfig)
+                return textResult("No WhatsApp config found. Connect WhatsApp first.");
+            return textResult(JSON.stringify(waConfig, null, 2));
+        }
         if (action === "list-groups") {
             const groups = result.groups ?? [];
             if (groups.length === 0)

package/payload/platform/plugins/whatsapp/mcp/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACpE,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,MAAM,aAAa,GAAG,OAAO,CAAC,GAAG,CAAC,aAAa,CAAC;AAChD,IAAI,CAAC,aAAa,EAAE,CAAC;IACnB,MAAM,IAAI,KAAK,CAAC,4FAA4F,CAAC,CAAC;AAChH,CAAC;AACD,MAAM,QAAQ,GAAG,oBAAoB,aAAa,EAAE,CAAC;AAErD,MAAM,MAAM,GAAG,IAAI,SAAS,CAAC;IAC3B,IAAI,EAAE,eAAe;IACrB,OAAO,EAAE,OAAO;CACjB,CAAC,CAAC;AAEH,KAAK,UAAU,OAAO,CAAC,IAAY,EAAE,SAAyB,MAAM,EAAE,IAAc;IAClF,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,GAAG,QAAQ,GAAG,IAAI,EAAE,EAAE;QAC5C,MAAM;QACN,OAAO,EAAE,IAAI,CAAC,CAAC,CAAC,EAAE,cAAc,EAAE,kBAAkB,EAAE,CAAC,CAAC,CAAC,SAAS;QAClE,IAAI,EAAE,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,SAAS;KAC9C,CAAC,CAAC;IACH,OAAO,GAAG,CAAC,IAAI,EAAE,CAAC;AACpB,CAAC;AAED,SAAS,UAAU,CAAC,IAAY,EAAE,OAAO,GAAG,KAAK;IAC/C,OAAO;QACL,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAe,EAAE,IAAI,EAAE,CAAC;QAC1C,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KACtC,CAAC;AACJ,CAAC;AAED,0EAA0E;AAE1E,MAAM,CAAC,IAAI,CACT,sBAAsB,EACtB,qMAAqM,EACrM;IACE,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,iCAAiC,CAAC;IAC5E,KAAK,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,yCAAyC,CAAC;CAClF,EACD,KAAK,EAAE,EAAE,SAAS,EAAE,KAAK,EAAE,EAAE,EAAE;IAC7B,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,2BAA2B,EAAE,MAAM,EAAE,EAAE,SAAS,EAAE,KAAK,EAAE,CAAQ,CAAC;QAC/F,IAAI,MAAM,CAAC,KAAK;YAAE,OAAO,UAAU,CAAC,uBAAuB,MAAM,CAAC,KAAK,EAAE,EAAE,IAAI,CAAC,CAAC;QAEjF,IAAI,QAAQ,GAAG,MAAM,CAAC,OAAO,CAAC;QAC9B,IAAI,MAAM,CAAC,KAAK,EAAE,CAAC;YACjB,QAAQ,IAAI,4FAA4F,CAAC;YACzG,QAAQ,IAAI,eAAe,IAAI,CAAC,SAAS,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,EAAE,KAAK,EAAE,MAAM,CAAC,KAAK,EAAE,KAAK,EAAE,oBAAoB,EAAE,EAAE,CAAC,EAAE,CAAC;QAC/H,CAAC;QACD,IAAI,MAAM,CAAC,SAAS,EAAE,CAAC;YACrB,QAAQ,IAAI,mBAAmB,MAAM,CAAC,SAAS,EAAE,CAAC;QACpD,CAAC;QACD,OAAO,UAAU,CAAC,QAAQ,CAAC,CAAC;IAC9B,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,OAAO,UAAU,CAAC,uBAAuB,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,EAAE,IAAI,CAAC,CAAC;IACrG,CAAC;AACH,CAAC,CACF,CAAC;AAEF,0EAA0E;AAE1E,MAAM,CAAC,IAAI,CACT,qBAAqB,EACrB,wIAAwI,EACxI;IACE,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,iCAAiC,CAAC;IAC5E,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,sCAAsC,CAAC;CAClF,EACD,KAAK,EAAE,EAAE,SAAS,EAAE,SAAS,EAAE,EAAE,EAAE;IACjC,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,0BAA0B,EAAE,MAAM,EAAE,EAAE,SAAS,EAAE,SAAS,EAAE,CAAQ,CAAC;QAClG,IAAI,MAAM,CAAC,KAAK;YAAE,OAAO,UAAU,CAAC,sBAAsB,MAAM,CAAC,KAAK,EAAE,EAAE,IAAI,CAAC,CAAC;QAEhF,IAAI,QAAQ,GAAG,MAAM,CAAC,OAAO,CAAC;QAC9B,IAAI,MAAM,CAAC,SAAS,IAAI,MAAM,CAAC,SAAS,EAAE,CAAC;YACzC,QAAQ,IAAI,mBAAmB,MAAM,CAAC,SAAS,EAAE,CAAC;QACpD,CAAC;QACD,OAAO,UAAU,CAAC,QAAQ,CAAC,CAAC;IAC9B,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,OAAO,UAAU,CAAC,sBAAsB,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,EAAE,IAAI,CAAC,CAAC;IACpG,CAAC;AACH,CAAC,CACF,CAAC;AAEF,0EAA0E;AAE1E,MAAM,CAAC,IAAI,CACT,iBAAiB,EACjB,6IAA6I,EAC7I,EAAE,EACF,KAAK,IAAI,EAAE;IACT,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,sBAAsB,EAAE,KAAK,CAAQ,CAAC;QACnE,IAAI,MAAM,CAAC,KAAK;YAAE,OAAO,UAAU,CAAC,wBAAwB,MAAM,CAAC,KAAK,EAAE,EAAE,IAAI,CAAC,CAAC;QAElF,MAAM,QAAQ,GAAG,MAAM,CAAC,QAAQ,IAAI,EAAE,CAAC;QACvC,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC1B,OAAO,UAAU,CAAC,2EAA2E,CAAC,CAAC;QACjG,CAAC;QAED,MAAM,KAAK,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAM,EAAE,EAAE;YACpC,MAAM,MAAM,GAAG,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,gBAAgB,CAAC;YAC9D,MAAM,KAAK,GAAG,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,SAAS,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;YACrD,MAAM,IAAI,GAAG,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACxD,MAAM,KAAK,GAAG,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACrD,MAAM,OAAO,GAAG,CAAC,CAAC,iBAAiB,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,iBAAiB,sBAAsB,CAAC,CAAC,CAAC,EAAE,CAAC;YAC9F,OAAO,GAAG,CAAC,CAAC,SAAS,GAAG,IAAI,KAAK,MAAM,GAAG,KAAK,GAAG,KAAK,GAAG,OAAO,EAAE,CAAC;QACtE,CAAC,CAAC,CAAC;QAEH,OAAO,UAAU,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;IACtC,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,OAAO,UAAU,CAAC,wBAAwB,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,EAAE,IAAI,CAAC,CAAC;IACtG,CAAC;AACH,CAAC,CACF,CAAC;AAEF,0EAA0E;AAE1E,MAAM,CAAC,IAAI,CACT,qBAAqB,EACrB,iFAAiF,EACjF;IACE,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,+CAA+C,CAAC;CAC3F,EACD,KAAK,EAAE,EAAE,SAAS,EAAE,EAAE,EAAE;IACtB,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,0BAA0B,EAAE,MAAM,EAAE,EAAE,SAAS,EAAE,CAAQ,CAAC;QACvF,IAAI,MAAM,CAAC,KAAK;YAAE,OAAO,UAAU,CAAC,sBAAsB,MAAM,CAAC,KAAK,EAAE,EAAE,IAAI,CAAC,CAAC;QAChF,OAAO,UAAU,CAAC,qBAAqB,MAAM,CAAC,SAAS,iBAAiB,CAAC,CAAC;IAC5E,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,OAAO,UAAU,CAAC,sBAAsB,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,EAAE,IAAI,CAAC,CAAC;IACpG,CAAC;AACH,CAAC,CACF,CAAC;AAEF,0EAA0E;AAE1E,MAAM,CAAC,IAAI,CACT,eAAe,EACf,sHAAsH,EACtH;IACE,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,0CAA0C,CAAC;IACnE,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,sBAAsB,CAAC;IACjD,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,2CAA2C,CAAC;CACvF,EACD,KAAK,EAAE,EAAE,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,EAAE,EAAE;IAChC,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,oBAAoB,EAAE,MAAM,EAAE,EAAE,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,CAAQ,CAAC;QAC3F,IAAI,MAAM,CAAC,KAAK;YAAE,OAAO,UAAU,CAAC,gBAAgB,MAAM,CAAC,KAAK,EAAE,EAAE,IAAI,CAAC,CAAC;QAC1E,OAAO,UAAU,CAAC,4BAA4B,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,SAAS,MAAM,CAAC,SAAS,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;IACxG,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,OAAO,UAAU,CAAC,gBAAgB,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,EAAE,IAAI,CAAC,CAAC;IAC9F,CAAC;AACH,CAAC,CACF,CAAC;AAEF,yEAAyE;AAEzE,MAAM,CAAC,IAAI,CACT,iBAAiB,EACjB,wyBAAwyB,EACxyB;IACE,MAAM,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,iBAAiB,EAAE,oBAAoB,EAAE,mBAAmB,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,eAAe,EAAE,YAAY,EAAE,QAAQ,EAAE,aAAa,CAAC,CAAC,CAAC,QAAQ,CAAC,8BAA8B,CAAC;IACvN,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,oEAAoE,CAAC;IAC3G,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,4CAA4C,CAAC;IAClF,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,qHAAqH,CAAC;IAC7J,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,iDAAiD,CAAC;CAC7F,EACD,KAAK,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,EAAE,EAAE;IACnD,IAAI,CAAC;QACH,6CAA6C;QAC7C,IAAI,YAAiD,CAAC;QACtD,IAAI,MAAM,KAAK,eAAe,IAAI,MAAM,EAAE,CAAC;YACzC,IAAI,CAAC;gBACH,YAAY,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;YACpC,CAAC;YAAC,MAAM,CAAC;gBACP,OAAO,UAAU,CAAC,wGAAwG,EAAE,IAAI,CAAC,CAAC;YACpI,CAAC;QACH,CAAC;QAED,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,sBAAsB,EAAE,MAAM,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,YAAY,EAAE,SAAS,EAAE,CAAQ,CAAC;QAC9H,IAAI,CAAC,MAAM,CAAC,EAAE;YAAE,OAAO,UAAU,CAAC,MAAM,CAAC,KAAK,IAAI,0BAA0B,EAAE,IAAI,CAAC,CAAC;QAEpF,IAAI,MAAM,KAAK,mBAAmB,EAAE,CAAC;YACnC,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,IAAI,EAAE,CAAC;YACnC,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;gBAAE,OAAO,UAAU,CAAC,kEAAkE,CAAC,CAAC;YAC/G,OAAO,UAAU,CAAC,kBAAkB,MAAM,CAAC,GAAG,CAAC,CAAC,CAAS,EAAE,EAAE,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACxF,CAAC;QAED,IAAI,MAAM,KAAK,kBAAkB,EAAE,CAAC;YAClC,MAAM,SAAS,GAAG,MAAM,CAAC,IAAI,CAAC;YAC9B,IAAI,CAAC,SAAS;gBAAE,OAAO,UAAU,CAAC,8EAA8E,CAAC,CAAC;YAClH,OAAO,UAAU,CAAC,0BAA0B,SAAS,EAAE,CAAC,CAAC;QAC3D,CAAC;QAED,IAAI,MAAM,KAAK,QAAQ,EAAE,CAAC;YACxB,OAAO,UAAU,CAAC,MAAM,CAAC,IAAI,IAAI,qBAAqB,CAAC,CAAC;QAC1D,CAAC;QAED,IAAI,MAAM,KAAK,YAAY,EAAE,CAAC;YAC5B,MAAM,QAAQ,GAAG,MAAM,CAAC,MAAM,CAAC;YAC/B,IAAI,CAAC,QAAQ;gBAAE,OAAO,UAAU,CAAC,mDAAmD,CAAC,CAAC;YACtF,OAAO,UAAU,CAAC,IAAI,CAAC,SAAS,CAAC,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC;QACvD,CAAC;QAED,IAAI,MAAM,KAAK,aAAa,EAAE,CAAC;YAC7B,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,IAAI,EAAE,CAAC;YACnC,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;gBAAE,OAAO,UAAU,CAAC,+FAA+F,CAAC,CAAC;YAC5I,MAAM,KAAK,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,CAAM,EAAE,EAAE,CAAC,KAAK,CAAC,CAAC,IAAI,KAAK,CAAC,CAAC,gBAAgB,eAAe,CAAC,CAAC,GAAG,EAAE,CAAC,CAAC;YAC/F,OAAO,UAAU,CAAC,oBAAoB,MAAM,CAAC,MAAM,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QAChF,CAAC;QAED,OAAO,UAAU,CAAC,MAAM,CAAC,OAAO,IAAI,OAAO,CAAC,CAAC;IAC/C,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,OAAO,UAAU,CAAC,4BAA4B,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,EAAE,IAAI,CAAC,CAAC;IAC1G,CAAC;AACH,CAAC,CACF,CAAC;AAEF,0EAA0E;AAE1E,MAAM,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAC;AAC7C,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC"}

package/payload/platform/plugins/whatsapp/references/channels-whatsapp.md

@@ -30,7 +30,7 @@ The initial first-run wizard flow stays single-account. Multi-account is managed
 ```yaml
 channels:
   whatsapp:
-    allowFrom:
+    adminPhones:
       - "<admin-phone>"    # E.164 phone the user messages from
     accounts:
       default:
@@ -88,14 +88,14 @@ The platform enforces this at multiple levels:
 | Term | Definition | Code |
 |------|-----------|------|
 | **Self phone** | The WhatsApp account's own phone number (the phone that scanned the QR code). Self-chat only. | `phonesMatch(senderPhone, selfPhone)` in `access-control.ts` |
-| **Admin phones** | Phones with explicit non-wildcard entries in `allowFrom` in `account.json`. The user's personal phone must be registered here during setup — it is not auto-registered on QR link. | `isAdminPhone()` in `access-control.ts` — iterates `allowFrom`, skips `"*"` entries |
-| **Public/unknown** | Any phone that is not self and not in `allowFrom` (non-wildcard). Subject to DM policy gating. | Everything else in `checkDmAccess()` |
+| **Admin phones** | Phones listed in `adminPhones` in `account.json`. The user's personal phone is auto-registered on QR link; additional phones are added via `whatsapp-config action: "add-admin-phone"`. | `isAdminPhone()` in `access-control.ts` — iterates `adminPhones` |
+| **Public/unknown** | Any phone that is not self and not in `adminPhones`. Subject to DM policy gating. | Everything else in `checkDmAccess()` |
 
-**Critical distinction:** The *self phone* is the paired device's number (the WhatsApp account Maxy controls). The *admin phone* is the user's personal phone (the phone they message *from*). These are typically different numbers. If the user's personal phone is not in `allowFrom`, their messages route as public — not admin.
+**Critical distinction:** The *self phone* is the paired device's number (the WhatsApp account Maxy controls). The *admin phone* is the user's personal phone (the phone they message *from*). These are typically different numbers. If the user's personal phone is not in `adminPhones`, their messages route as public — not admin.
 
 **`dmPolicy` behaviour (per-account):**
 
-| Policy | Self phone | Admin phones (in `allowFrom`) | Public/unknown |
+| Policy | Self phone | Admin phones (in `adminPhones`) | Public/unknown |
 |--------|-----------|-------------------------------|----------------|
 | `"open"` | Allowed | Allowed | Allowed |
 | `"allowlist"` | Allowed | Allowed | Allowed only if in `allowFrom` (wildcard `"*"` counts) |
@@ -107,7 +107,7 @@ Admin phones always bypass DM policy — the `isAdminPhone()` check runs before
 
 **Key file:** `access-control.ts` — `checkDmAccess()` and `checkGroupAccess()`.
 
-**Config path:** Per-account at `whatsapp.accounts.{accountId}.dmPolicy` in `account.json`. Falls back to `whatsapp.dmPolicy`. Changes are conversational — the admin agent writes to config via the `account-update` tool.
+**Config path:** Per-account at `whatsapp.accounts.{accountId}.dmPolicy` in `account.json`. Falls back to `whatsapp.dmPolicy`. Changes are conversational — the admin agent writes to config via `whatsapp-config action: "update-config"`.
 
 For config field definitions (field names, types, valid values), use `whatsapp-config action: schema`.
 

package/payload/platform/plugins/whatsapp/skills/manage-whatsapp-config/SKILL.md

@@ -47,7 +47,7 @@ When the user wants to configure per-group settings:
 
 ## Writing changes
 
-After the user submits, write changes via `account-update` with `field: "whatsapp"` and the updated config object. Confirm what changed — name each setting that was modified and its new value.
+After the user submits, write changes via `whatsapp-config action: "update-config"` with the `fields` parameter containing a JSON object of the changed fields. Each field is merged individually — unchanged fields are left untouched. Confirm what changed — name each setting that was modified and its new value.
 
 ## Language
 

package/payload/platform/templates/agents/admin/IDENTITY.md

@@ -75,6 +75,10 @@ Any request to create, edit, clone, list, preview, or delete a public agent must
 
 Plugin installation, removal, and account settings changes are managed via conversation. Load the relevant skill via `plugin-read` (find its path in the manifest under `admin`).
 
+## WhatsApp Configuration
+
+When the user asks about WhatsApp settings, config, policies, or operational limits, load the manage-whatsapp-config skill via `plugin-read` (find its path in the manifest under `whatsapp`). The skill guides presenting config as an interactive form, not a text dump.
+
 ## Session Reset
 
 When the user asks to start a new session, clear the conversation, or start fresh, call `session-reset`. This compacts the current conversation to memory and clears the chat. Do not ask for confirmation. After calling the tool, do not say anything further — the UI clears and returns to idle.