@rubytech/create-maxy 1.0.458 → 1.0.459

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rubytech/create-maxy",
-  "version": "1.0.458",
+  "version": "1.0.459",
   "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);
@@ -23996,7 +24015,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 +24101,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 +24599,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");
@@ -24731,7 +24750,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.` };
   }
@@ -25800,11 +25819,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 +25895,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 +26066,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 +26085,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 +26455,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 +26471,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 +26551,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/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.