@rubytech/create-maxy 1.0.460 → 1.0.462

package/package.json

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

package/payload/maxy/server.js

@@ -5102,7 +5102,7 @@ function getMcpServers(accountId, enabledPlugins) {
     // the always-on Chromium instance started by vnc.sh on display :99.
     "plugin_playwright_playwright": {
       command: "npx",
-      args: ["-y", "@playwright/mcp@latest", "--cdp-endpoint", "http://127.0.0.1:9222"]
+      args: ["-y", "@playwright/mcp@latest", "--cdp-endpoint", "http://127.0.0.1:9222", "--caps", "pdf"]
     }
   };
   if (process.env.TELEGRAM_PUBLIC_BOT_TOKEN) {
@@ -23691,6 +23691,282 @@ var WhatsAppConfigSchema = external_exports.object({
   });
 });
 
+// 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";
+var TAG4 = "[whatsapp:config]";
+function configPath(accountDir) {
+  return resolve9(accountDir, "account.json");
+}
+function readConfig(accountDir) {
+  const path2 = configPath(accountDir);
+  if (!existsSync10(path2)) throw new Error(`account.json not found at ${path2}`);
+  return JSON.parse(readFileSync10(path2, "utf-8"));
+}
+function writeConfig(accountDir, config2) {
+  const path2 = configPath(accountDir);
+  writeFileSync6(path2, JSON.stringify(config2, null, 2) + "\n", "utf-8");
+}
+function reloadManagerConfig(accountDir) {
+  try {
+    const config2 = readConfig(accountDir);
+    reloadConfig(config2);
+    console.error(`${TAG4} reloaded manager config`);
+  } catch (err) {
+    console.error(`${TAG4} manager config reload failed: ${String(err)}`);
+  }
+}
+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(`${TAG4} migrated ${phones.length} phone(s) from allowFrom to adminPhones`);
+  return phones.length;
+}
+function persistAfterPairing(accountDir, accountId, selfPhone) {
+  try {
+    const config2 = readConfig(accountDir);
+    if (!config2.whatsapp || typeof config2.whatsapp !== "object") {
+      config2.whatsapp = {};
+    }
+    const wa = config2.whatsapp;
+    if (!wa.accounts || typeof wa.accounts !== "object") {
+      wa.accounts = {};
+    }
+    const accounts = wa.accounts;
+    if (!accounts[accountId] || typeof accounts[accountId] !== "object") {
+      accounts[accountId] = { name: "Main" };
+    }
+    if (selfPhone) {
+      const normalized = selfPhone.startsWith("+") ? selfPhone : `+${selfPhone}`;
+      if (!Array.isArray(wa.adminPhones)) {
+        wa.adminPhones = [];
+      }
+      const adminPhones = wa.adminPhones;
+      if (!adminPhones.includes(normalized)) {
+        adminPhones.push(normalized);
+        console.error(`${TAG4} added selfPhone=${normalized} to adminPhones`);
+      }
+    } else {
+      console.error(`${TAG4} skipping adminPhones \u2014 selfPhone is null account=${accountId}`);
+    }
+    const parsed = WhatsAppConfigSchema.safeParse(wa);
+    if (!parsed.success) {
+      const msg = parsed.error.issues.map((i) => `${i.path.join(".")}: ${i.message}`).join("; ");
+      console.error(`${TAG4} validation failed after pairing: ${msg}`);
+      return { ok: false, error: `Validation failed: ${msg}` };
+    }
+    config2.whatsapp = parsed.data;
+    writeConfig(accountDir, config2);
+    console.error(`${TAG4} persisted after pairing account=${accountId} phone=${selfPhone ?? "null"}`);
+    reloadManagerConfig(accountDir);
+    return { ok: true };
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    console.error(`${TAG4} persist failed account=${accountId}: ${msg}`);
+    return { ok: false, error: msg };
+  }
+}
+function addAdminPhone(accountDir, phone) {
+  const normalized = phone.trim();
+  if (!E164_PATTERN.test(normalized)) {
+    return { ok: false, error: `Invalid phone format "${normalized}". Expected E.164 (e.g. +441234567890).` };
+  }
+  try {
+    const config2 = readConfig(accountDir);
+    if (!config2.whatsapp || typeof config2.whatsapp !== "object") {
+      config2.whatsapp = {};
+    }
+    const wa = config2.whatsapp;
+    migrateAdminPhones(wa);
+    if (!Array.isArray(wa.adminPhones)) {
+      wa.adminPhones = [];
+    }
+    const adminPhones = wa.adminPhones;
+    if (adminPhones.includes(normalized)) {
+      return { ok: true, message: `Phone ${normalized} is already in the admin list.` };
+    }
+    adminPhones.push(normalized);
+    const parsed = WhatsAppConfigSchema.safeParse(wa);
+    if (!parsed.success) {
+      const msg = parsed.error.issues.map((i) => `${i.path.join(".")}: ${i.message}`).join("; ");
+      return { ok: false, error: `Validation failed: ${msg}` };
+    }
+    config2.whatsapp = parsed.data;
+    writeConfig(accountDir, config2);
+    console.error(`${TAG4} added admin phone=${normalized}`);
+    reloadManagerConfig(accountDir);
+    return { ok: true, message: `Added ${normalized} as admin phone. Messages from this number will route to the admin agent.` };
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    console.error(`${TAG4} addAdminPhone failed: ${msg}`);
+    return { ok: false, error: msg };
+  }
+}
+function removeAdminPhone(accountDir, phone) {
+  const normalized = phone.trim();
+  try {
+    const config2 = readConfig(accountDir);
+    if (!config2.whatsapp || typeof config2.whatsapp !== "object") {
+      return { ok: true, message: `No WhatsApp config exists \u2014 nothing to remove.` };
+    }
+    const wa = config2.whatsapp;
+    migrateAdminPhones(wa);
+    if (!Array.isArray(wa.adminPhones)) {
+      return { ok: true, message: `No admin phones configured \u2014 nothing to remove.` };
+    }
+    const adminPhones = wa.adminPhones;
+    const idx = adminPhones.indexOf(normalized);
+    if (idx === -1) {
+      return { ok: true, message: `Phone ${normalized} is not in the admin list.` };
+    }
+    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("; ");
+      return { ok: false, error: `Validation failed: ${msg}` };
+    }
+    config2.whatsapp = parsed.data;
+    writeConfig(accountDir, config2);
+    console.error(`${TAG4} removed admin phone=${normalized}`);
+    reloadManagerConfig(accountDir);
+    return { ok: true, message: `Removed ${normalized} from admin phones. Messages from this number will now route to the public agent.` };
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    console.error(`${TAG4} removeAdminPhone failed: ${msg}`);
+    return { ok: false, error: msg };
+  }
+}
+function readAdminPhones(accountDir) {
+  try {
+    const config2 = readConfig(accountDir);
+    const wa = config2.whatsapp;
+    if (!wa) return [];
+    const migrated = migrateAdminPhones(wa);
+    if (migrated > 0) {
+      const parsed = WhatsAppConfigSchema.safeParse(wa);
+      if (parsed.success) {
+        config2.whatsapp = parsed.data;
+        writeConfig(accountDir, config2);
+        reloadManagerConfig(accountDir);
+      }
+    }
+    if (!Array.isArray(wa.adminPhones)) return [];
+    return wa.adminPhones.filter((p) => typeof p === "string");
+  } catch {
+    return [];
+  }
+}
+function setPublicAgent(accountDir, slug) {
+  const trimmed = slug.trim();
+  if (!trimmed) {
+    return { ok: false, error: "Agent slug cannot be empty." };
+  }
+  const agentConfigPath = join5(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.` };
+  }
+  try {
+    const config2 = readConfig(accountDir);
+    if (!config2.whatsapp || typeof config2.whatsapp !== "object") {
+      config2.whatsapp = {};
+    }
+    const wa = config2.whatsapp;
+    wa.publicAgent = trimmed;
+    const parsed = WhatsAppConfigSchema.safeParse(wa);
+    if (!parsed.success) {
+      const msg = parsed.error.issues.map((i) => `${i.path.join(".")}: ${i.message}`).join("; ");
+      return { ok: false, error: `Validation failed: ${msg}` };
+    }
+    config2.whatsapp = parsed.data;
+    writeConfig(accountDir, config2);
+    console.error(`${TAG4} publicAgent set to ${trimmed}`);
+    reloadManagerConfig(accountDir);
+    return { ok: true, message: `Public agent set to "${trimmed}". WhatsApp messages from non-admin phones will be handled by this agent.` };
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    console.error(`${TAG4} setPublicAgent failed: ${msg}`);
+    return { ok: false, error: msg };
+  }
+}
+function getPublicAgent(accountDir) {
+  try {
+    const config2 = readConfig(accountDir);
+    const wa = config2.whatsapp;
+    if (!wa) return null;
+    const slug = wa.publicAgent;
+    if (typeof slug === "string" && slug.trim()) {
+      return slug.trim();
+    }
+    return null;
+  } catch {
+    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(`${TAG4} update validation failed: ${msg}`);
+      return { ok: false, error: `Validation failed: ${msg}` };
+    }
+    config2.whatsapp = parsed.data;
+    writeConfig(accountDir, config2);
+    console.error(`${TAG4} 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(`${TAG4} 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);
+    const parsed = WhatsAppConfigSchema.safeParse(wa);
+    if (!parsed.success) return wa;
+    if (migrated > 0) {
+      config2.whatsapp = parsed.data;
+      writeConfig(accountDir, config2);
+      reloadManagerConfig(accountDir);
+    }
+    return parsed.data;
+  } catch {
+    return null;
+  }
+}
+
 // app/lib/whatsapp/normalize.ts
 var WHATSAPP_USER_JID_RE = /^(\d+)(?::\d+)?@s\.whatsapp\.net$/i;
 var WHATSAPP_LID_RE = /^(\d+)@lid$/i;
@@ -23976,7 +24252,7 @@ function isDuplicateInbound(key) {
 }
 
 // app/lib/whatsapp/outbound/send.ts
-var TAG4 = "[whatsapp:outbound]";
+var TAG5 = "[whatsapp:outbound]";
 async function sendTextMessage(sock, to, text, opts) {
   try {
     const jid = to.includes("@") ? to : toWhatsappJid(to);
@@ -23988,11 +24264,11 @@ async function sendTextMessage(sock, to, text, opts) {
     const messageId = result?.key?.id;
     if (messageId) {
       trackAgentSentMessage(messageId);
-      console.error(`${TAG4} sent text to=${jid} id=${messageId}`);
+      console.error(`${TAG5} sent text to=${jid} id=${messageId}`);
     }
     return { success: true, messageId: messageId ?? void 0 };
   } catch (err) {
-    console.error(`${TAG4} send failed to=${to}: ${String(err)}`);
+    console.error(`${TAG5} send failed to=${to}: ${String(err)}`);
     return { success: false, error: String(err) };
   }
 }
@@ -24012,13 +24288,13 @@ 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 join5 } from "path";
+import { join as join6 } from "path";
 import {
   downloadMediaMessage,
   downloadContentFromMessage,
   normalizeMessageContent as normalizeMessageContent2
 } from "@whiskeysockets/baileys";
-var TAG5 = "[whatsapp:media]";
+var TAG6 = "[whatsapp:media]";
 var MEDIA_DIR = "/tmp/maxy-media";
 function mimeToExt(mimetype) {
   const map2 = {
@@ -24074,47 +24350,47 @@ async function downloadInboundMedia(msg, sock, opts) {
       }
     );
     if (!buffer || buffer.length === 0) {
-      console.error(`${TAG5} primary download returned empty, trying direct fallback`);
+      console.error(`${TAG6} primary download returned empty, trying direct fallback`);
       const downloadable = getDownloadableContent(content);
       if (downloadable) {
         try {
           const stream = await downloadContentFromMessage(downloadable.downloadable, downloadable.mediaType);
           buffer = await streamToBuffer(stream);
         } catch (fallbackErr) {
-          console.error(`${TAG5} direct download fallback failed: ${String(fallbackErr)}`);
+          console.error(`${TAG6} direct download fallback failed: ${String(fallbackErr)}`);
         }
       }
     }
     if (!buffer || buffer.length === 0) {
-      console.error(`${TAG5} download failed: empty buffer for ${mimetype ?? "unknown"}`);
+      console.error(`${TAG6} download failed: empty buffer for ${mimetype ?? "unknown"}`);
       return void 0;
     }
     if (buffer.length > maxBytes) {
       const sizeMB = (buffer.length / (1024 * 1024)).toFixed(1);
       const limitMB = (maxBytes / (1024 * 1024)).toFixed(0);
-      console.error(`${TAG5} media too large type=${mimetype ?? "unknown"} size=${sizeMB}MB limit=${limitMB}MB`);
+      console.error(`${TAG6} media too large type=${mimetype ?? "unknown"} size=${sizeMB}MB limit=${limitMB}MB`);
       return void 0;
     }
     await mkdir2(MEDIA_DIR, { recursive: true });
     const ext = mimeToExt(mimetype ?? "application/octet-stream");
     const filename = `${randomUUID6()}.${ext}`;
-    const filePath = join5(MEDIA_DIR, filename);
+    const filePath = join6(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}`);
+    console.error(`${TAG6} media downloaded type=${mimetype ?? "unknown"} size=${sizeKB}KB path=${filePath}`);
     return {
       path: filePath,
       mimetype: mimetype ?? "application/octet-stream",
       size: buffer.length
     };
   } catch (err) {
-    console.error(`${TAG5} media download failed type=${mimetype ?? "unknown"} error=${String(err)}`);
+    console.error(`${TAG6} media download failed type=${mimetype ?? "unknown"} error=${String(err)}`);
     return void 0;
   }
 }
 
 // app/lib/whatsapp/inbound/debounce.ts
-var TAG6 = "[whatsapp:debounce]";
+var TAG7 = "[whatsapp:debounce]";
 function createInboundDebouncer(opts) {
   const { debounceMs, buildKey, onFlush, onError } = opts;
   const pending = /* @__PURE__ */ new Map();
@@ -24126,7 +24402,7 @@ function createInboundDebouncer(opts) {
     pending.delete(key);
     const batchSize = batch.entries.length;
     try {
-      console.error(`${TAG6} debounce flush key=${key} batchSize=${batchSize}`);
+      console.error(`${TAG7} debounce flush key=${key} batchSize=${batchSize}`);
       const result = onFlush(batch.entries);
       if (result && typeof result.catch === "function") {
         result.catch(onError);
@@ -24184,7 +24460,7 @@ function createInboundDebouncer(opts) {
 }
 
 // app/lib/whatsapp/manager.ts
-var TAG7 = "[whatsapp:manager]";
+var TAG8 = "[whatsapp:manager]";
 var MAX_RECONNECT_ATTEMPTS = 10;
 var connections = /* @__PURE__ */ new Map();
 var configDir = null;
@@ -24193,7 +24469,7 @@ var onInboundMessage = null;
 var initialized = false;
 async function init(opts) {
   if (initialized) {
-    console.error(`${TAG7} already initialized`);
+    console.error(`${TAG8} already initialized`);
     return;
   }
   configDir = opts.configDir;
@@ -24201,20 +24477,20 @@ async function init(opts) {
   loadConfig(opts.accountConfig);
   const accountIds = listCredentialAccountIds(configDir);
   if (accountIds.length === 0) {
-    console.error(`${TAG7} init: no stored WhatsApp credentials found`);
+    console.error(`${TAG8} init: no stored WhatsApp credentials found`);
     initialized = true;
     return;
   }
-  console.error(`${TAG7} init: found ${accountIds.length} credentialed account(s): ${accountIds.join(", ")}`);
+  console.error(`${TAG8} init: found ${accountIds.length} credentialed account(s): ${accountIds.join(", ")}`);
   initialized = true;
   for (const accountId of accountIds) {
     const accountCfg = whatsAppConfig.accounts?.[accountId];
     if (accountCfg?.enabled === false) {
-      console.error(`${TAG7} skipping disabled account=${accountId}`);
+      console.error(`${TAG8} skipping disabled account=${accountId}`);
       continue;
     }
     startConnection(accountId).catch((err) => {
-      console.error(`${TAG7} failed to auto-start account=${accountId}: ${formatError(err)}`);
+      console.error(`${TAG8} failed to auto-start account=${accountId}: ${formatError(err)}`);
     });
   }
 }
@@ -24223,7 +24499,7 @@ async function startConnection(accountId) {
   const authDir = resolveAuthDir(configDir, accountId);
   const hasAuth = await authExists(authDir);
   if (!hasAuth) {
-    console.error(`${TAG7} no credentials for account=${accountId}`);
+    console.error(`${TAG8} no credentials for account=${accountId}`);
     return;
   }
   await stopConnection(accountId);
@@ -24258,11 +24534,11 @@ async function stopConnection(accountId) {
       conn.sock.ev.removeAllListeners("creds.update");
       conn.sock.ws?.close?.();
     } catch (err) {
-      console.warn(`${TAG7} socket cleanup error during stop account=${accountId}: ${String(err)}`);
+      console.warn(`${TAG8} socket cleanup error during stop account=${accountId}: ${String(err)}`);
     }
   }
   connections.delete(accountId);
-  console.error(`${TAG7} stopped account=${accountId}`);
+  console.error(`${TAG8} stopped account=${accountId}`);
 }
 function getStatus() {
   return Array.from(connections.values()).map((conn) => ({
@@ -24301,13 +24577,13 @@ async function registerLoginSocket(accountId, sock, authDir) {
   connections.set(accountId, conn);
   try {
     await sock.sendPresenceUpdate("available");
-    console.error(`${TAG7} presence set to available account=${accountId}`);
+    console.error(`${TAG8} presence set to available account=${accountId}`);
   } catch (err) {
-    console.error(`${TAG7} presence update failed account=${accountId}: ${String(err)}`);
+    console.error(`${TAG8} presence update failed account=${accountId}: ${String(err)}`);
   }
   monitorInbound(conn);
   watchForDisconnect(conn);
-  console.error(`${TAG7} registered login socket for account=${accountId} phone=${selfId.e164 ?? "unknown"}`);
+  console.error(`${TAG8} registered login socket for account=${accountId} phone=${selfId.e164 ?? "unknown"}`);
 }
 function reloadConfig(accountConfig) {
   loadConfig(accountConfig);
@@ -24317,22 +24593,24 @@ async function shutdown() {
   const ids = Array.from(connections.keys());
   await Promise.all(ids.map((id) => stopConnection(id)));
   initialized = false;
-  console.error(`${TAG7} shutdown complete`);
+  console.error(`${TAG8} shutdown complete`);
 }
 function loadConfig(accountConfig) {
   try {
     const raw2 = accountConfig?.whatsapp;
     if (raw2 && typeof raw2 === "object") {
-      const parsed = WhatsAppConfigSchema.safeParse(raw2);
+      const wa = raw2;
+      migrateAdminPhones(wa);
+      const parsed = WhatsAppConfigSchema.safeParse(wa);
       if (parsed.success) {
         whatsAppConfig = parsed.data;
       } else {
-        console.error(`${TAG7} config validation failed: ${parsed.error.message}`);
+        console.error(`${TAG8} config validation failed: ${parsed.error.message}`);
         whatsAppConfig = {};
       }
     }
   } catch (err) {
-    console.error(`${TAG7} config load error: ${String(err)}`);
+    console.error(`${TAG8} config load error: ${String(err)}`);
     whatsAppConfig = {};
   }
 }
@@ -24340,13 +24618,13 @@ async function connectWithReconnect(conn) {
   const maxAttempts = MAX_RECONNECT_ATTEMPTS;
   while (!conn.abortController.signal.aborted) {
     try {
-      console.error(`${TAG7} connecting account=${conn.accountId} attempt=${conn.reconnectAttempts}`);
+      console.error(`${TAG8} connecting account=${conn.accountId} attempt=${conn.reconnectAttempts}`);
       const sock = await createWaSocket({
         authDir: conn.authDir,
         silent: true
       });
       conn.sock = sock;
-      console.error(`${TAG7} socket created account=${conn.accountId} \u2014 waiting for connection`);
+      console.error(`${TAG8} socket created account=${conn.accountId} \u2014 waiting for connection`);
       await waitForConnection(sock);
       const selfId = readSelfId(conn.authDir);
       conn.connected = true;
@@ -24356,12 +24634,12 @@ async function connectWithReconnect(conn) {
       conn.reconnectAttempts = 0;
       conn.lastError = void 0;
       conn.lidMapping = sock.signalRepository?.lidMapping ?? null;
-      console.error(`${TAG7} connected account=${conn.accountId} phone=${selfId.e164 ?? "unknown"}`);
+      console.error(`${TAG8} connected account=${conn.accountId} phone=${selfId.e164 ?? "unknown"}`);
       try {
         await sock.sendPresenceUpdate("available");
-        console.error(`${TAG7} presence set to available account=${conn.accountId}`);
+        console.error(`${TAG8} presence set to available account=${conn.accountId}`);
       } catch (err) {
-        console.error(`${TAG7} presence update failed account=${conn.accountId}: ${String(err)}`);
+        console.error(`${TAG8} presence update failed account=${conn.accountId}: ${String(err)}`);
       }
       if (conn.debouncer) {
         conn.debouncer.destroy();
@@ -24376,19 +24654,19 @@ async function connectWithReconnect(conn) {
       conn.sock = null;
       const classification = classifyDisconnect(err);
       conn.lastError = classification.message;
-      console.error(`${TAG7} disconnect account=${conn.accountId}: ${classification.kind} \u2014 ${classification.message}`);
+      console.error(`${TAG8} disconnect account=${conn.accountId}: ${classification.kind} \u2014 ${classification.message}`);
       if (!classification.shouldRetry) {
-        console.error(`${TAG7} terminal disconnect for account=${conn.accountId}, stopping reconnection`);
+        console.error(`${TAG8} terminal disconnect for account=${conn.accountId}, stopping reconnection`);
         return;
       }
       conn.reconnectAttempts++;
       if (conn.reconnectAttempts > maxAttempts) {
-        console.error(`${TAG7} max retries exceeded for account=${conn.accountId}`);
+        console.error(`${TAG8} max retries exceeded for account=${conn.accountId}`);
         conn.lastError = `Max reconnect attempts (${maxAttempts}) exceeded`;
         return;
       }
       const delay = computeBackoff(conn.reconnectAttempts);
-      console.error(`${TAG7} reconnecting account=${conn.accountId} in ${delay}ms (attempt ${conn.reconnectAttempts}/${maxAttempts})`);
+      console.error(`${TAG8} reconnecting account=${conn.accountId} in ${delay}ms (attempt ${conn.reconnectAttempts}/${maxAttempts})`);
       await new Promise((resolve17) => {
         const timer = setTimeout(resolve17, delay);
         conn.abortController.signal.addEventListener("abort", () => {
@@ -24418,11 +24696,11 @@ function watchForDisconnect(conn) {
   conn.sock.ev.on("connection.update", (update) => {
     if (update.connection === "close") {
       if (connections.get(conn.accountId) !== conn) return;
-      console.error(`${TAG7} socket disconnected for account=${conn.accountId}`);
+      console.error(`${TAG8} socket disconnected for account=${conn.accountId}`);
       conn.connected = false;
       conn.sock = null;
       connectWithReconnect(conn).catch((err) => {
-        console.error(`${TAG7} reconnection failed for account=${conn.accountId}: ${formatError(err)}`);
+        console.error(`${TAG8} reconnection failed for account=${conn.accountId}: ${formatError(err)}`);
       });
     }
   });
@@ -24431,7 +24709,7 @@ function monitorInbound(conn) {
   if (!conn.sock || !onInboundMessage) return;
   const sock = conn.sock;
   const debounceMs = whatsAppConfig.accounts?.[conn.accountId]?.debounceMs ?? whatsAppConfig.debounceMs ?? 0;
-  console.error(`${TAG7} monitorInbound started account=${conn.accountId} debounceMs=${debounceMs}`);
+  console.error(`${TAG8} monitorInbound started account=${conn.accountId} debounceMs=${debounceMs}`);
   conn.debouncer = createInboundDebouncer({
     debounceMs,
     buildKey: (payload) => {
@@ -24444,7 +24722,7 @@ function monitorInbound(conn) {
         onInboundMessage(entries[0]);
         return;
       }
-      console.error(`${TAG7} debounce: combining ${entries.length} messages account=${conn.accountId} from=${entries[0].senderPhone}`);
+      console.error(`${TAG8} debounce: combining ${entries.length} messages account=${conn.accountId} from=${entries[0].senderPhone}`);
       const last = entries[entries.length - 1];
       const mediaEntry = entries.find((e) => e.mediaPath);
       const combinedText = entries.map((e) => e.text).filter(Boolean).join("\n");
@@ -24457,7 +24735,7 @@ function monitorInbound(conn) {
       });
     },
     onError: (err) => {
-      console.error(`${TAG7} debounce flush error account=${conn.accountId}: ${String(err)}`);
+      console.error(`${TAG8} debounce flush error account=${conn.accountId}: ${String(err)}`);
     }
   });
   sock.ev.on("messages.upsert", async (upsert) => {
@@ -24466,7 +24744,7 @@ function monitorInbound(conn) {
       try {
         await handleInboundMessage(conn, msg);
       } catch (err) {
-        console.error(`${TAG7} inbound handler error account=${conn.accountId}: ${String(err)}`);
+        console.error(`${TAG8} inbound handler error account=${conn.accountId}: ${String(err)}`);
       }
     }
   });
@@ -24476,31 +24754,31 @@ async function handleInboundMessage(conn, msg) {
   const remoteJid = msg.key.remoteJid;
   if (!remoteJid) return;
   if (remoteJid === "status@broadcast") {
-    console.error(`${TAG7} drop: status broadcast account=${conn.accountId}`);
+    console.error(`${TAG8} drop: status broadcast account=${conn.accountId}`);
     return;
   }
   if (!msg.message) {
-    console.error(`${TAG7} drop: empty message account=${conn.accountId} from=${remoteJid}`);
+    console.error(`${TAG8} drop: empty message account=${conn.accountId} from=${remoteJid}`);
     return;
   }
   const dedupKey = `${conn.accountId}:${remoteJid}:${msg.key.id}`;
   if (isDuplicateInbound(dedupKey)) {
-    console.error(`${TAG7} drop: duplicate account=${conn.accountId} key=${dedupKey}`);
+    console.error(`${TAG8} drop: duplicate account=${conn.accountId} key=${dedupKey}`);
     return;
   }
   if (msg.key.fromMe) {
     if (msg.key.id && isAgentSentMessage(msg.key.id)) {
-      console.error(`${TAG7} drop: echo suppression account=${conn.accountId} msgId=${msg.key.id}`);
+      console.error(`${TAG8} drop: echo suppression account=${conn.accountId} msgId=${msg.key.id}`);
       return;
     }
     const extracted2 = extractMessage(msg);
     if (!extracted2.text) {
-      console.error(`${TAG7} owner reply skipped \u2014 no text content account=${conn.accountId}`);
+      console.error(`${TAG8} owner reply skipped \u2014 no text content account=${conn.accountId}`);
       return;
     }
     const isGroup2 = isGroupJid(remoteJid);
     const senderPhone2 = conn.selfPhone ?? "owner";
-    console.error(`${TAG7} owner reply mirrored to session from=${senderPhone2} account=${conn.accountId}`);
+    console.error(`${TAG8} owner reply mirrored to session from=${senderPhone2} account=${conn.accountId}`);
     const reply2 = async (text) => {
       const currentSock = conn.sock;
       if (!currentSock) throw new Error("WhatsApp disconnected \u2014 cannot reply");
@@ -24521,7 +24799,7 @@ async function handleInboundMessage(conn, msg) {
   }
   const extracted = extractMessage(msg);
   if (!extracted.text && !extracted.mediaType) {
-    console.error(`${TAG7} drop: no text or media account=${conn.accountId} from=${remoteJid}`);
+    console.error(`${TAG8} drop: no text or media account=${conn.accountId} from=${remoteJid}`);
     return;
   }
   let mediaResult;
@@ -24531,7 +24809,7 @@ async function handleInboundMessage(conn, msg) {
       maxBytes: maxMb * 1024 * 1024
     });
     if (!mediaResult) {
-      console.error(`${TAG7} media download returned undefined account=${conn.accountId} type=${extracted.mediaType} from=${remoteJid}`);
+      console.error(`${TAG8} media download returned undefined account=${conn.accountId} type=${extracted.mediaType} from=${remoteJid}`);
     }
   }
   const isGroup = isGroupJid(remoteJid);
@@ -24559,7 +24837,7 @@ async function handleInboundMessage(conn, msg) {
     });
   }
   console.error(
-    `${TAG7} inbound account=${conn.accountId} from=${senderPhone} group=${isGroup} access=${accessResult.allowed ? "allowed" : "blocked"}(${accessResult.reason}) agent=${accessResult.agentType}` + (extracted.mediaType ? ` media=${extracted.mediaType}` : "") + (mediaResult ? ` mediaPath=${mediaResult.path}` : "") + (extracted.quotedMessage ? ` replyTo=${extracted.quotedMessage.id}` : "")
+    `${TAG8} inbound account=${conn.accountId} from=${senderPhone} group=${isGroup} access=${accessResult.allowed ? "allowed" : "blocked"}(${accessResult.reason}) agent=${accessResult.agentType}` + (extracted.mediaType ? ` media=${extracted.mediaType}` : "") + (mediaResult ? ` mediaPath=${mediaResult.path}` : "") + (extracted.quotedMessage ? ` replyTo=${extracted.quotedMessage.id}` : "")
   );
   if (!accessResult.allowed) return;
   const sendReceipts = whatsAppConfig.accounts?.[conn.accountId]?.sendReadReceipts ?? whatsAppConfig.sendReadReceipts ?? true;
@@ -24594,273 +24872,6 @@ 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 join6 } from "path";
-var TAG8 = "[whatsapp:config]";
-function configPath(accountDir) {
-  return resolve9(accountDir, "account.json");
-}
-function readConfig(accountDir) {
-  const path2 = configPath(accountDir);
-  if (!existsSync10(path2)) throw new Error(`account.json not found at ${path2}`);
-  return JSON.parse(readFileSync10(path2, "utf-8"));
-}
-function writeConfig(accountDir, config2) {
-  const path2 = configPath(accountDir);
-  writeFileSync6(path2, JSON.stringify(config2, null, 2) + "\n", "utf-8");
-}
-function reloadManagerConfig(accountDir) {
-  try {
-    const config2 = readConfig(accountDir);
-    reloadConfig(config2);
-    console.error(`${TAG8} reloaded manager config`);
-  } catch (err) {
-    console.error(`${TAG8} manager config reload failed: ${String(err)}`);
-  }
-}
-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);
-    if (!config2.whatsapp || typeof config2.whatsapp !== "object") {
-      config2.whatsapp = {};
-    }
-    const wa = config2.whatsapp;
-    if (!wa.accounts || typeof wa.accounts !== "object") {
-      wa.accounts = {};
-    }
-    const accounts = wa.accounts;
-    if (!accounts[accountId] || typeof accounts[accountId] !== "object") {
-      accounts[accountId] = { name: "Main" };
-    }
-    if (selfPhone) {
-      const normalized = selfPhone.startsWith("+") ? selfPhone : `+${selfPhone}`;
-      if (!Array.isArray(wa.adminPhones)) {
-        wa.adminPhones = [];
-      }
-      const adminPhones = wa.adminPhones;
-      if (!adminPhones.includes(normalized)) {
-        adminPhones.push(normalized);
-        console.error(`${TAG8} added selfPhone=${normalized} to adminPhones`);
-      }
-    } else {
-      console.error(`${TAG8} skipping adminPhones \u2014 selfPhone is null account=${accountId}`);
-    }
-    const parsed = WhatsAppConfigSchema.safeParse(wa);
-    if (!parsed.success) {
-      const msg = parsed.error.issues.map((i) => `${i.path.join(".")}: ${i.message}`).join("; ");
-      console.error(`${TAG8} validation failed after pairing: ${msg}`);
-      return { ok: false, error: `Validation failed: ${msg}` };
-    }
-    config2.whatsapp = parsed.data;
-    writeConfig(accountDir, config2);
-    console.error(`${TAG8} persisted after pairing account=${accountId} phone=${selfPhone ?? "null"}`);
-    reloadManagerConfig(accountDir);
-    return { ok: true };
-  } catch (err) {
-    const msg = err instanceof Error ? err.message : String(err);
-    console.error(`${TAG8} persist failed account=${accountId}: ${msg}`);
-    return { ok: false, error: msg };
-  }
-}
-function addAdminPhone(accountDir, phone) {
-  const normalized = phone.trim();
-  if (!E164_PATTERN.test(normalized)) {
-    return { ok: false, error: `Invalid phone format "${normalized}". Expected E.164 (e.g. +441234567890).` };
-  }
-  try {
-    const config2 = readConfig(accountDir);
-    if (!config2.whatsapp || typeof config2.whatsapp !== "object") {
-      config2.whatsapp = {};
-    }
-    const wa = config2.whatsapp;
-    if (!Array.isArray(wa.adminPhones)) {
-      wa.adminPhones = [];
-    }
-    const adminPhones = wa.adminPhones;
-    if (adminPhones.includes(normalized)) {
-      return { ok: true, message: `Phone ${normalized} is already in the admin list.` };
-    }
-    adminPhones.push(normalized);
-    const parsed = WhatsAppConfigSchema.safeParse(wa);
-    if (!parsed.success) {
-      const msg = parsed.error.issues.map((i) => `${i.path.join(".")}: ${i.message}`).join("; ");
-      return { ok: false, error: `Validation failed: ${msg}` };
-    }
-    config2.whatsapp = parsed.data;
-    writeConfig(accountDir, config2);
-    console.error(`${TAG8} added admin phone=${normalized}`);
-    reloadManagerConfig(accountDir);
-    return { ok: true, message: `Added ${normalized} as admin phone. Messages from this number will route to the admin agent.` };
-  } catch (err) {
-    const msg = err instanceof Error ? err.message : String(err);
-    console.error(`${TAG8} addAdminPhone failed: ${msg}`);
-    return { ok: false, error: msg };
-  }
-}
-function removeAdminPhone(accountDir, phone) {
-  const normalized = phone.trim();
-  try {
-    const config2 = readConfig(accountDir);
-    if (!config2.whatsapp || typeof config2.whatsapp !== "object") {
-      return { ok: true, message: `No WhatsApp config exists \u2014 nothing to remove.` };
-    }
-    const wa = config2.whatsapp;
-    if (!Array.isArray(wa.adminPhones)) {
-      return { ok: true, message: `No admin phones configured \u2014 nothing to remove.` };
-    }
-    const adminPhones = wa.adminPhones;
-    const idx = adminPhones.indexOf(normalized);
-    if (idx === -1) {
-      return { ok: true, message: `Phone ${normalized} is not in the admin list.` };
-    }
-    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("; ");
-      return { ok: false, error: `Validation failed: ${msg}` };
-    }
-    config2.whatsapp = parsed.data;
-    writeConfig(accountDir, config2);
-    console.error(`${TAG8} removed admin phone=${normalized}`);
-    reloadManagerConfig(accountDir);
-    return { ok: true, message: `Removed ${normalized} from admin phones. Messages from this number will now route to the public agent.` };
-  } catch (err) {
-    const msg = err instanceof Error ? err.message : String(err);
-    console.error(`${TAG8} removeAdminPhone failed: ${msg}`);
-    return { ok: false, error: msg };
-  }
-}
-function readAdminPhones(accountDir) {
-  try {
-    const config2 = readConfig(accountDir);
-    const wa = config2.whatsapp;
-    if (!wa) return [];
-    migrateAdminPhones(wa);
-    if (!Array.isArray(wa.adminPhones)) return [];
-    return wa.adminPhones.filter((p) => typeof p === "string");
-  } catch {
-    return [];
-  }
-}
-function setPublicAgent(accountDir, slug) {
-  const trimmed = slug.trim();
-  if (!trimmed) {
-    return { ok: false, error: "Agent slug cannot be empty." };
-  }
-  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.` };
-  }
-  try {
-    const config2 = readConfig(accountDir);
-    if (!config2.whatsapp || typeof config2.whatsapp !== "object") {
-      config2.whatsapp = {};
-    }
-    const wa = config2.whatsapp;
-    wa.publicAgent = trimmed;
-    const parsed = WhatsAppConfigSchema.safeParse(wa);
-    if (!parsed.success) {
-      const msg = parsed.error.issues.map((i) => `${i.path.join(".")}: ${i.message}`).join("; ");
-      return { ok: false, error: `Validation failed: ${msg}` };
-    }
-    config2.whatsapp = parsed.data;
-    writeConfig(accountDir, config2);
-    console.error(`${TAG8} publicAgent set to ${trimmed}`);
-    reloadManagerConfig(accountDir);
-    return { ok: true, message: `Public agent set to "${trimmed}". WhatsApp messages from non-admin phones will be handled by this agent.` };
-  } catch (err) {
-    const msg = err instanceof Error ? err.message : String(err);
-    console.error(`${TAG8} setPublicAgent failed: ${msg}`);
-    return { ok: false, error: msg };
-  }
-}
-function getPublicAgent(accountDir) {
-  try {
-    const config2 = readConfig(accountDir);
-    const wa = config2.whatsapp;
-    if (!wa) return null;
-    const slug = wa.publicAgent;
-    if (typeof slug === "string" && slug.trim()) {
-      return slug.trim();
-    }
-    return null;
-  } catch {
-    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) {
   try {

package/payload/platform/plugins/admin/skills/skill-builder/SKILL.md

@@ -46,6 +46,8 @@ Ask what rules the agent should follow when using this skill:
 
 Not every skill needs all of these. Only include what's relevant.
 
+If the skill involves generating PDFs or print-ready documents, load `references/pdf-generation.md` for the constraints on HTML layout and the `browser_pdf_save` rendering path.
+
 ## Step 4: Decide on References
 
 If the skill has detailed procedures, templates, or data formats, those belong in `references/` files — not inline in SKILL.md.

package/payload/platform/plugins/admin/skills/skill-builder/references/pdf-generation.md

@@ -0,0 +1,30 @@
+# PDF Generation in Skills
+
+When a skill needs to produce a PDF, the output is always a two-stage process: the skill authors the HTML, and the browser-specialist renders it to PDF via the `browser_pdf_save` MCP tool.
+
+## The rule
+
+Never instruct the agent to write or execute raw Node.js scripts (e.g. `require('playwright')`, `page.pdf()`, `npx playwright`). Playwright is not in the Node.js module path — these scripts fail with MODULE_NOT_FOUND, waste tool calls searching the filesystem, and produce hardcoded paths that break on reinstall.
+
+Instead, skills that produce PDFs should:
+
+1. **Build the HTML** — the skill's behaviour section describes what the document contains and how it's structured. The agent writes the HTML file using standard file tools.
+2. **Delegate rendering to browser-specialist** — the agent asks the browser-specialist to navigate to the HTML file and call `browser_pdf_save` to produce the PDF. The specialist has Playwright access through governed MCP tools; the admin agent does not.
+
+## Print-ready HTML constraints
+
+HTML intended for PDF output must follow print-ready layout patterns. The most common failures when agents design their own pagination are rigid fixed-height page divs (causing whitespace gaps) and `position: fixed` hacks for headers/footers (causing overlap and duplication).
+
+**Continuous flow layout** — content flows naturally. Use `@page` margin rules for page margins, not wrapper divs with fixed heights. Use `page-break-inside: avoid` on logical units (cards, tables, stat groups) and `page-break-before: always` on major section dividers.
+
+**Page numbers and running footers** — use `@page` margin boxes (`@bottom-center { content: counter(page); }`), not JavaScript or position-fixed elements.
+
+**Dark backgrounds in print** — browsers strip background colours by default. Add `print-color-adjust: exact; -webkit-print-color-adjust: exact;` to dark elements in `@media print`.
+
+**Cover and back pages** — full-bleed pages use `height: 100vh; page-break-after: always;` in `@media print` with zero `@page` margins (via `@page :first` for covers, named pages for back pages).
+
+**Glassmorphism and backdrop-filter** — these do not survive browser print rendering. Any section using glassmorphism needs a pre-rendered PNG fallback image that is hidden on screen and shown only in `@media print`.
+
+## What the skill file should contain
+
+The skill's SKILL.md describes the document's purpose and structure. A `references/` file holds the HTML template or content specification. The skill should state that PDF rendering is delegated to browser-specialist — it should not contain Playwright code, npm commands, or file path assumptions about the Playwright installation.

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

@@ -42,7 +42,7 @@ Accounts are linked via QR in the Channels UI. Outbound routing (`src/web/outbou
 
 | Target | Account | Reason |
 |--------|---------|--------|
-| Admin/allowFrom phones | Account with admin binding | Admin's registered number |
+| Admin phones | Account with admin binding | Admin's registered number |
 | Self-chat | Account with selfChatMode | Admin talking to themselves |
 | Group messages | Account that is a group member | Whichever is in the group |
 | Customer DMs | Account with open DM policy | Dedicated agent number |

package/payload/platform/plugins/whatsapp/skills/connect-whatsapp/SKILL.md

@@ -68,7 +68,7 @@ Admin phone registration and public agent selection persist across relinks — n
 - **QR expired** — generate a new one with `whatsapp-login-start`
 - **Phone not scanning** — ensure the phone has internet, WhatsApp is updated, and the user is in Linked Devices
 - **Keeps disconnecting** — check `whatsapp-status` for error details. A 401 means re-link is needed. Repeated transient errors suggest network issues on the device.
-- **Messages routing as public** — the user's personal phone is not in `allowFrom`. Call `whatsapp-config` with `action: "add-admin-phone"` and the user's phone number to register it.
+- **Messages routing as public** — the user's personal phone is not in `adminPhones`. Call `whatsapp-config` with `action: "add-admin-phone"` and the user's phone number to register it.
 
 ## Language
 

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

@@ -17,22 +17,42 @@ Call `whatsapp-status` first — if no WhatsApp account is connected, direct the
 
 ## Presenting settings
 
-Call `whatsapp-config action: schema` to get field definitions with descriptions, types, defaults, and constraints. Use the Description column from the schema output as the `description` field on each form field — do not improvise descriptions.
+Call `whatsapp-config action: schema` to get field definitions with descriptions, and `whatsapp-config action: get-config` to get current values. Use the Description column from the schema output as the `description` field on each form field — do not improvise descriptions.
 
-Group related settings logically when presenting:
+### Admin phones
 
-1. **Messaging policies** — dmPolicy, groupPolicy, allowFrom, groupAllowFrom
-2. **Operational limits** — mediaMaxMb, textChunkLimit, debounceMs
-3. **Behaviour** — sendReadReceipts, ackReaction
-4. **Account settings** — name, enabled, selfChatMode
-5. **Group configuration** — groups (per-group activation)
+Before the form, call `whatsapp-config action: list-admin-phones` and display the result. Admin phones are managed via `add-admin-phone` / `remove-admin-phone` — they are not editable in this form.
 
-Present settings as a `render-component` form with:
-- `description` on every field (from schema output)
-- `defaultValue` showing the current value or the schema default
-- Rich option labels with descriptions for enum fields (e.g. dmPolicy options should explain what "open", "allowlist", and "disabled" each mean)
+### Form fields
 
-Before the user submits, summarise what each default does — the user should understand the implications of keeping defaults, not just see them pre-filled.
+Present settings as a `render-component` form. Each field must have a unique `name` matching the schema field name (used as the state key and the `update-config` field key), a `type`, a `label` (plain English), and a `description` (from schema output). For selects, specify `options`. For all fields, set `defaultValue` from `get-config` (current value) or the schema default.
+
+**Messaging policies:**
+
+- `dmPolicy` (`select`): label "Who can message your agent (DMs)", options:
+  - `open` — "Open — anyone can message"
+  - `allowlist` — "Allowlist — only approved numbers"
+  - `disabled` — "Disabled — no public DMs"
+- `groupPolicy` (`select`): label "Group message handling", options:
+  - `open` — "Always — respond to all group messages"
+  - `allowlist` — "Allowlist — only in approved groups"
+  - `disabled` — "Disabled — ignore all group messages"
+
+**Behaviour:**
+
+- `sendReadReceipts` (`select`): label "Blue ticks (read receipts)", options:
+  - `true` — "On — contacts see read receipts"
+  - `false` — "Off — no read receipts"
+
+**Operational limits:**
+
+- `mediaMaxMb` (`number`): label "Media size limit (MB)"
+- `textChunkLimit` (`number`): label "Message chunk limit (characters)"
+- `debounceMs` (`number`): label "Message batching delay (ms)"
+
+### Submit
+
+The form's `submitMessage` must map the field values back to `update-config` field names: `Save these WhatsApp settings: {{json}}` — where `{{json}}` produces the JSON object with field names as keys (e.g. `{ "dmPolicy": "open", "mediaMaxMb": 50, ... }`).
 
 ## Group configuration
 
@@ -51,9 +71,11 @@ After the user submits, write changes via `whatsapp-config action: "update-confi
 
 ## Language
 
-Use plain English:
-- "Who can message your agent" not "dmPolicy"
-- "Message batching delay" not "debounceMs"
-- "Media size limit" not "mediaMaxMb"
-- "Blue ticks" not "sendReadReceipts"
-- Group names, not JIDs
+Plain English goes in `label` — schema field names go in `name`. The `name` property is the machine key (must match the schema exactly); the `label` is what the user reads. Examples:
+
+- `name: "dmPolicy"`, `label: "Who can message your agent (DMs)"`
+- `name: "debounceMs"`, `label: "Message batching delay (ms)"`
+- `name: "mediaMaxMb"`, `label: "Media size limit (MB)"`
+- `name: "sendReadReceipts"`, `label: "Blue ticks (read receipts)"`
+
+Group names (not JIDs) in all user-facing text.

package/payload/platform/templates/specialists/agents/browser-specialist.md

@@ -3,7 +3,7 @@ name: browser-specialist
 description: "Web browser tasks — visiting websites, filling forms, clicking buttons, and reading page content. Delegate when a task requires controlling the browser."
 summary: "Browses the web on your behalf — visiting websites, filling in forms, and extracting information. For example, when you need to sign up for a service, check a competitor's pricing page, or set up an online account."
 model: claude-sonnet-4-6
-tools: mcp__plugin_playwright_playwright__browser_navigate, mcp__plugin_playwright_playwright__browser_navigate_back, mcp__plugin_playwright_playwright__browser_snapshot, mcp__plugin_playwright_playwright__browser_take_screenshot, mcp__plugin_playwright_playwright__browser_click, mcp__plugin_playwright_playwright__browser_fill, mcp__plugin_playwright_playwright__browser_fill_form, mcp__plugin_playwright_playwright__browser_type, mcp__plugin_playwright_playwright__browser_press_key, mcp__plugin_playwright_playwright__browser_hover, mcp__plugin_playwright_playwright__browser_select_option, mcp__plugin_playwright_playwright__browser_wait_for, mcp__plugin_playwright_playwright__browser_handle_dialog, mcp__plugin_playwright_playwright__browser_evaluate, mcp__plugin_playwright_playwright__browser_console_messages, mcp__plugin_playwright_playwright__browser_resize, mcp__plugin_playwright_playwright__browser_tabs, mcp__plugin_playwright_playwright__browser_close, mcp__admin__api-key-store
+tools: mcp__plugin_playwright_playwright__browser_navigate, mcp__plugin_playwright_playwright__browser_navigate_back, mcp__plugin_playwright_playwright__browser_snapshot, mcp__plugin_playwright_playwright__browser_take_screenshot, mcp__plugin_playwright_playwright__browser_click, mcp__plugin_playwright_playwright__browser_fill, mcp__plugin_playwright_playwright__browser_fill_form, mcp__plugin_playwright_playwright__browser_type, mcp__plugin_playwright_playwright__browser_press_key, mcp__plugin_playwright_playwright__browser_hover, mcp__plugin_playwright_playwright__browser_select_option, mcp__plugin_playwright_playwright__browser_wait_for, mcp__plugin_playwright_playwright__browser_handle_dialog, mcp__plugin_playwright_playwright__browser_evaluate, mcp__plugin_playwright_playwright__browser_console_messages, mcp__plugin_playwright_playwright__browser_resize, mcp__plugin_playwright_playwright__browser_tabs, mcp__plugin_playwright_playwright__browser_close, mcp__plugin_playwright_playwright__browser_pdf_save, mcp__admin__api-key-store
 ---
 
 # Browser Specialist