@agent-native/core 0.7.14 → 0.7.15

package/docs/content/drop-in-agent.md

@@ -38,7 +38,7 @@ export default function Root() {
         "Draft a reply to the latest email",
         "Show me yesterday's signup numbers",
       ]}
-      sidebarWidth={420}
+      defaultSidebarWidth={420}
       position="right"
     >
       <YourApp />
@@ -57,7 +57,7 @@ That's it. The user now has a toggleable agent on every page — with chat histo
 - **`children`** — your app. Rendered in the main area; the sidebar overlays from the chosen side.
 - **`emptyStateText`** — greeting shown when the chat has no messages. Default: `"How can I help you?"`.
 - **`suggestions`** — starter prompts rendered as clickable chips when empty.
-- **`sidebarWidth`** — pixel width. Default: `380`.
+- **`defaultSidebarWidth`** — initial pixel width (mount-only; user resize and saved value override). Default: `380`.
 - **`position`** — `"left"` or `"right"`. Default: `"right"`.
 - **`defaultOpen`** — whether the sidebar starts open (desktop only). Default: `false`.
 

package/docs/content/messaging.md

@@ -5,233 +5,277 @@ description: "Talk to your agent from Slack, email, Telegram, or WhatsApp — sa
 
 # Messaging
 
-Talk to your agent from the platforms you already use. Send a Slack DM, reply to an email, message a Telegram bot, or ping over WhatsApp — same agent, same memory, same tools, same thread history as the web chat.
+Connect your agent to Slack, email, Telegram, or WhatsApp so you can chat with it from the apps you already use. It's the same agent — same memory, same tools, same threads — just reachable from more places.
 
-## Overview {#overview}
+> **Using the Dispatch template?** All of this is wired up for you in **Settings → Messaging**. Click to connect each platform — you don't need to read the rest of this page unless you're customizing or building your own template. See [Dispatch](/docs/template-dispatch).
 
-Messaging integrations let users reach their agent from external messaging platforms instead of opening the web UI. Whichever platform a message comes in on, the agent processes it with the same system prompt, the same actions, and the same database — and replies in the same thread.
+## What you can do {#what-you-can-do}
 
-Each integration works through webhooks. The platform delivers incoming messages over HTTP, the agent processes them in the background, and the response is posted back. No polling, no long-lived connections.
+- **Email your agent** at an address like `agent@yourcompany.com` — it replies in-thread, just like a coworker would.
+- **CC your agent** on a thread — it'll read along and jump in when you ask.
+- **DM the agent on Slack**, or `@mention` it in any channel.
+- **Message the agent on Telegram or WhatsApp** from your phone.
+- **Same agent, same memory.** Whatever you tell it on Slack is remembered when you email it later. The web chat and external messages share one thread history.
 
-> Note: this doc is specifically about platforms you can _message_ your agent over. Other kinds of integrations — Google Docs, OAuth providers, SQL databases, MCP servers, etc. — are covered in their own docs.
+## Set up Slack {#slack}
 
-## How it works {#how-it-works}
+### What you'll need
 
-The flow is the same for every platform:
+- A Slack workspace where you can install apps (admin access)
+- About 5 minutes
 
-1. A user sends a message on the external platform (Slack, email, Telegram, WhatsApp)
-2. The platform delivers the message to your app via a webhook at `/_agent-native/integrations/<platform>/webhook`
-3. The integrations plugin validates the request, extracts the message text and thread context, and maps it to an internal conversation thread
-4. The agent processes the message in the background using the same pipeline as the web chat
-5. The response is posted back to the external platform in the same thread
+### Steps
 
-`User (Slack/Email/Telegram/WhatsApp)` → `Webhook` → `Agent Processing` → `Response posted back`
+1. Go to **[api.slack.com/apps](https://api.slack.com/apps)** and click **Create New App** → **From scratch**. Name it (e.g. "Agent") and pick your workspace.
+2. In the left sidebar, open **OAuth & Permissions**. Under **Bot Token Scopes**, add:
+   - `chat:write` — lets the agent send messages
+   - `app_mentions:read` — lets the agent see when it's @-mentioned (optional)
+   - `im:history` — lets the agent read DMs sent to it
+3. Click **Install to Workspace** at the top of that page. Slack will give you a **Bot User OAuth Token** that starts with `xoxb-`. Copy it.
+4. Go to **Basic Information** in the sidebar and copy the **Signing Secret**.
+5. Open your app's settings (or your hosting provider's environment variable panel) and paste:
+   - `SLACK_BOT_TOKEN` — the `xoxb-…` token
+   - `SLACK_SIGNING_SECRET` — the signing secret
+6. Back in Slack, open **Event Subscriptions**, toggle it on, and paste this Request URL:
 
-## Setup {#setup}
+   ```text
+   https://your-app.example.com/_agent-native/integrations/slack/webhook
+   ```
 
-The integrations plugin auto-mounts when no custom version exists in your template. To customize it, create a plugin file:
+   Then under **Subscribe to bot events**, add `message.im` (for DMs) and optionally `app_mention` (for channel mentions). Save.
 
-```ts
-// server/plugins/integrations.ts
-import { createIntegrationsPlugin } from "@agent-native/core/server";
-import { scriptRegistry } from "../../agent.config";
+7. Send your bot a DM in Slack. It should reply.
 
-export default createIntegrationsPlugin({
-  actions: scriptRegistry,
-  systemPrompt: "You are a helpful assistant...",
-});
-```
+### Tips
 
-The plugin registers webhook routes for each enabled platform under `/_agent-native/integrations/`. Which platforms are active depends on which environment variables are configured.
+- **Channel mentions** — the bot only responds in channels when it's @-mentioned, to avoid noise.
+- **DMs** — every DM is treated as a private conversation with the agent.
+- **Same identity, all channels** — if a Slack user has the same email as a registered user in your app, the agent treats them as the same person.
 
-## Dispatch as the orchestrator {#dispatch}
+## Set up Telegram {#telegram}
 
-Messaging integrations are most powerful when set up in the **Dispatch template** (`templates/dispatch/`). Dispatch is a central control plane that:
+### What you'll need
 
-- Receives inbound messages from every configured platform (Slack, email, Telegram, WhatsApp) in one place
-- Delegates domain-specific work to specialist agents over the [A2A protocol](/docs/a2a-protocol) via the `call-agent` action
-- Sends the result back to the original platform in the same thread
+- The Telegram app on your phone
+- About 3 minutes
 
-The pattern is one inbox, many specialist agents. A user emails the Dispatch agent "make me a slide deck about Q3" → Dispatch delegates to the slides agent → the slides agent returns a URL → Dispatch emails the user back with the link. Same flow for analytics queries, calendar invites, content drafts, anything else you have a specialist agent for.
+### Steps
 
-You don't have to use Dispatch — any template that mounts the integrations plugin can receive messages — but Dispatch is the recommended home for messaging because it can route across your whole agent fleet.
+1. Open Telegram and message **[@BotFather](https://t.me/BotFather)**.
+2. Send `/newbot` and follow the prompts to name your bot. BotFather will reply with an **HTTP API token**. Copy it.
+3. In your app's environment variables, set:
+   - `TELEGRAM_BOT_TOKEN` — the token from BotFather
+4. After deploying, register the webhook by `POST`ing to your app at:
 
-See [Dispatch template](/docs/template-dispatch) and [A2A protocol](/docs/a2a-protocol) for details.
+   ```text
+   POST https://your-app.example.com/_agent-native/integrations/telegram/setup
+   ```
 
-## Slack {#slack}
+   This tells Telegram to send messages to your app's webhook. You only need to do this once per deployment.
 
-### 1. Create a Slack app
+5. Find your bot in Telegram (search for the username BotFather gave you) and send it a message.
 
-Go to [api.slack.com/apps](https://api.slack.com/apps) and create a new app. Under **OAuth & Permissions**, add the following bot token scopes:
+## Set up Email {#email}
 
-- `chat:write` — send messages
-- `app_mentions:read` — receive @-mentions (optional)
+Email is the most powerful integration — your agent gets its own address, replies in-thread, can be CC'd on conversations, and uses the sender's email as their identity. No `/link` command needed.
 
-### 2. Enable Event Subscriptions
+### What you'll need
 
-Under **Event Subscriptions**, set the Request URL to:
+- A domain you control (or you can use a free Resend subdomain — see below)
+- An account with **Resend** or **SendGrid** to handle inbound + outbound mail
+- About 10 minutes
 
-```text
-https://your-app.example.com/_agent-native/integrations/slack/webhook
-```
+### Steps (with Resend — easiest)
 
-Subscribe to the `message.im` bot event (and optionally `app_mention` for channel mentions).
+1. Sign up at **[resend.com](https://resend.com)**. The free tier is enough to get started.
+2. Pick how the agent's email address will look:
+   - **Easiest:** use a free `<your-slug>.resend.app` address — no DNS needed.
+   - **Branded:** add a custom domain (like `yourcompany.com`) in Resend's **Domains** page and follow the DNS steps.
+3. In Resend, open **Webhooks** → **Add Endpoint** and point it at:
 
-### 3. Set environment variables
+   ```text
+   https://your-app.example.com/_agent-native/integrations/email/webhook
+   ```
 
-```bash
-SLACK_BOT_TOKEN=xoxb-your-bot-token
-SLACK_SIGNING_SECRET=your-signing-secret
-```
+   Subscribe to the **`email.received`** event. Resend will give you a signing secret — copy it.
 
-The bot token is found under **OAuth & Permissions** after installing the app to your workspace. The signing secret is under **Basic Information**.
+4. In your app's environment variables, set:
+   - `EMAIL_AGENT_ADDRESS` — the address the agent receives mail at (e.g. `agent@yourcompany.com`)
+   - `RESEND_API_KEY` — your Resend API key
+   - `EMAIL_INBOUND_WEBHOOK_SECRET` — the signing secret from Resend (recommended; used for signature verification)
 
-## Email {#email}
+5. Send an email to the agent's address. It'll reply in the same thread.
 
-The email adapter receives inbound mail via Resend or SendGrid webhooks and replies in-thread using standard `Message-ID` / `In-Reply-To` / `References` headers. Sender email addresses are treated as identities — if a user emails the agent from `alice@acme.com`, that maps directly to the workspace user with that email.
+### Steps (with SendGrid)
 
-Adapter file: `packages/core/src/integrations/adapters/email.ts`
+1. Sign up at **[sendgrid.com](https://sendgrid.com)**.
+2. Add the MX record for your domain so inbound mail flows to SendGrid:
+   ```text
+   MX  yourcompany.com  →  mx.sendgrid.net  (priority 10)
+   ```
+3. Open **Settings → Inbound Parse**, click **Add Host & URL**, and set the destination to:
 
-### 1. Set environment variables
+   ```text
+   https://your-app.example.com/_agent-native/integrations/email/webhook
+   ```
 
-```bash
-EMAIL_AGENT_ADDRESS=agent@your-domain.com
-# Configure ONE of these (Resend or SendGrid):
-RESEND_API_KEY=re_...
-SENDGRID_API_KEY=SG...
-# Optional — recommended for production:
-EMAIL_INBOUND_WEBHOOK_SECRET=your-shared-secret
-```
+4. Set environment variables:
+   - `EMAIL_AGENT_ADDRESS` — the address the agent receives at
+   - `SENDGRID_API_KEY` — your SendGrid API key
+   - `EMAIL_INBOUND_WEBHOOK_SECRET` — optional Svix signing secret if you've configured signed webhooks
 
-`EMAIL_AGENT_ADDRESS` is the address users send mail to. Set either `RESEND_API_KEY` _or_ `SENDGRID_API_KEY` — whichever provider you use. `EMAIL_INBOUND_WEBHOOK_SECRET` enables Svix signature verification (Resend) or basic-auth / `x-webhook-secret` header verification (SendGrid).
+5. Send an email to the agent's address.
 
-### 2. Configure the webhook URL
+### Tips
 
-```text
-https://your-app.example.com/_agent-native/integrations/email/webhook
-```
+- **CC the agent** to bring it into a thread. When the agent is CC'd it will reply-all so the whole thread sees the response.
+- **Threading just works** — the agent uses standard `Message-ID` / `In-Reply-To` / `References` headers, so replies stay in the right thread in any email client.
+- **Identity is the sender's email.** If `alice@acme.com` emails the agent, that _is_ her identity — no link or signup flow.
+- **Rich responses** — markdown in the agent's response is rendered as HTML in the email.
+- **Allowed domains** — restrict who can email the agent by setting `allowedDomains` in the integration's config; messages from other domains are dropped.
+- **Rate limit** — 20 inbound messages per hour per sender.
 
-### 3. Provider setup — Resend
+## Set up WhatsApp {#whatsapp}
 
-Two options for the agent address:
+### What you'll need
 
-- **Free `<slug>.resend.app` address** — no DNS setup required. Pick a slug in the Resend dashboard and your agent gets `agent@<slug>.resend.app`.
-- **Custom domain** — add MX records pointing to Resend per the dashboard's instructions.
+- A Meta (Facebook) developer account
+- A phone number you can dedicate to the bot
+- About 15 minutes (Meta's setup has the most steps)
 
-Then in the Resend dashboard:
+### Steps
 
-1. Go to **Webhooks** → **Add Endpoint**
-2. Set the URL to `https://your-app.example.com/_agent-native/integrations/email/webhook`
-3. Subscribe to the `email.received` event
-4. Copy the signing secret into `EMAIL_INBOUND_WEBHOOK_SECRET`
+1. Go to the **[Meta Developer Portal](https://developers.facebook.com/)**, click **Create App**, and pick the **Business** type.
+2. Add the **WhatsApp** product to your app and configure a phone number to use as the sender.
+3. From the WhatsApp setup page, grab:
+   - **Access token** (the temporary one is fine for testing; generate a permanent token before going live)
+   - **Phone number ID**
+4. Pick any random string to use as a verify token — you'll enter the same value in two places below.
+5. In your app's environment variables, set:
+   - `WHATSAPP_ACCESS_TOKEN` — your access token
+   - `WHATSAPP_PHONE_NUMBER_ID` — the phone number ID
+   - `WHATSAPP_VERIFY_TOKEN` — the random string you picked
+6. Back in Meta's WhatsApp config, open the webhook section and set:
 
-### 3. Provider setup — SendGrid
+   ```text
+   Callback URL:  https://your-app.example.com/_agent-native/integrations/whatsapp/webhook
+   Verify token:  the same random string you set as WHATSAPP_VERIFY_TOKEN
+   ```
 
-1. In your DNS, add an MX record for the agent's domain pointing to `mx.sendgrid.net` (priority 10)
-2. In the SendGrid dashboard, go to **Settings** → **Inbound Parse** → **Add Host & URL**
-3. Set the host to your domain and the destination URL to `https://your-app.example.com/_agent-native/integrations/email/webhook`
-4. (Recommended) Set basic auth or a custom `x-webhook-secret` header matching `EMAIL_INBOUND_WEBHOOK_SECRET`
+   Subscribe to the `messages` field.
 
-### Threading and CC behavior
+7. Send a WhatsApp message to the bot's phone number.
 
-- **Threading** uses the standard email headers: the agent's reply sets `In-Reply-To` to the inbound `Message-ID` and accumulates the `References` chain. Most clients (Gmail, Outlook, Apple Mail) thread the conversation automatically.
-- **Direct vs CC'd** — the adapter detects whether the agent was in `To` (directly addressed) or `Cc` (overheard). When CC'd, the agent's reply goes to all original recipients (reply-all). The Dispatch system prompt also instructs the agent to only respond when input is clearly being requested, so it stays out of the way on threads it's only copied on.
-- **Identity** — the sender's email address is the identity. It maps directly to a workspace user with that email; the agent acts on behalf of that user.
+## Use Dispatch as your agent's central inbox {#dispatch}
 
-### Rich responses
+If you're running multiple agent-native apps (mail, calendar, analytics, etc.), the recommended pattern is to set up messaging on the **[Dispatch template](/docs/template-dispatch)** and let it route work to your domain apps over [A2A](/docs/a2a-protocol).
 
-Agent replies render as HTML email. The adapter converts markdown to HTML (headings, lists, links, bold, inline code, paragraphs) and wraps it in a minimal styled template, with a plain-text fallback. So tables, bullet lists, and links from the agent come through as proper rich email — not raw markdown.
+Why this is nice:
 
-### Rate limiting and allowed domains
+- **One agent, one inbox.** All your channels (Slack, email, Telegram, WhatsApp) flow into Dispatch. You only set up integrations once.
+- **Dispatch delegates.** Ask "summarize last week's signups" — Dispatch calls the analytics agent. Ask "draft a reply to Alice" — Dispatch calls the mail agent.
+- **Clicks, not config.** Dispatch's **Settings → Messaging** page has connect buttons for every platform with the env-var fields built in.
 
-- **Rate limit** — 20 inbound messages per sender per hour, enforced in-memory per process. Excess messages are dropped.
-- **Allowed domains** — the `integration_configs` row for `email` accepts an optional `allowedDomains: string[]`. When set, only senders whose domain is in the list are accepted. Use this to restrict the agent to a specific company or tenant.
+If you don't need an orchestrator, any single template can wire up messaging directly using the env vars on this page.
 
-### Proactive sends
+---
 
-The agent can email users on its own (not just reply) by calling the `send-platform-message` action with `platform: "email"`. Useful for digest emails, alerts, or follow-ups from automations and recurring jobs.
+## For developers {#for-developers}
 
-## Telegram {#telegram}
+Everything below is the technical reference. If you've finished the setup steps above, you can stop here unless you're customizing the integration plugin or building your own adapter.
 
-### 1. Create a bot
+### How it works {#how-it-works}
 
-Message [@BotFather](https://t.me/BotFather) on Telegram and use the `/newbot` command. You will receive a bot token.
+Each platform talks to your app via a standard HTTP webhook:
 
-### 2. Set environment variables
+1. A user sends a message on Slack/Telegram/WhatsApp/email.
+2. The platform `POST`s to `/_agent-native/integrations/<platform>/webhook`.
+3. The integrations plugin verifies the signature, parses the message, and maps it to an internal conversation thread.
+4. The agent runs the same pipeline as the web chat — same system prompt, same actions, same tools.
+5. The response is posted back to the platform in the same thread.
 
-```bash
-TELEGRAM_BOT_TOKEN=your-bot-token
+```text
+User → Platform webhook → Verify → Parse → Agent runs → Response posted back
 ```
 
-### 3. Register the webhook
+No polling, no long-lived connections. Inbound and outbound conversations live in the same SQL thread, so you can continue a Slack DM from the web UI or vice versa.
 
-After deploying your app, call the setup endpoint to register the webhook with Telegram:
+### The integrations plugin {#plugin}
 
-```text
-// The integrations plugin exposes a setup endpoint
-POST /_agent-native/integrations/telegram/setup
+The plugin auto-mounts when no custom version exists. To customize, create:
 
-// This calls Telegram's setWebhook API pointing to:
-// https://your-app.example.com/_agent-native/integrations/telegram/webhook
-```
+```ts
+// server/plugins/integrations.ts
+import { createIntegrationsPlugin } from "@agent-native/core/server";
+import { scriptRegistry } from "../../agent.config";
 
-You can also register the webhook manually using the Telegram Bot API if you prefer.
+export default createIntegrationsPlugin({
+  actions: scriptRegistry,
+  systemPrompt: "You are a helpful assistant...",
+});
+```
 
-## WhatsApp {#whatsapp}
+Which platforms are active depends on which env vars are set. The plugin registers webhook routes for each one under `/_agent-native/integrations/`.
 
-### 1. Set up the WhatsApp Cloud API
+### Webhook URLs {#webhook-urls}
 
-Go to the [Meta Developer Portal](https://developers.facebook.com/), create an app, and enable the WhatsApp product. Configure a phone number for your business.
+```text
+/_agent-native/integrations/slack/webhook
+/_agent-native/integrations/telegram/webhook
+/_agent-native/integrations/whatsapp/webhook
+/_agent-native/integrations/email/webhook
+```
 
-### 2. Set environment variables
+Telegram also exposes a one-time setup endpoint:
 
-```bash
-WHATSAPP_ACCESS_TOKEN=your-access-token
-WHATSAPP_VERIFY_TOKEN=your-verify-token
-WHATSAPP_PHONE_NUMBER_ID=your-phone-number-id
+```text
+POST /_agent-native/integrations/telegram/setup
 ```
 
-The verify token is a string you choose — Meta uses it during webhook verification. The access token and phone number ID come from the Meta Developer Portal.
+### Environment variables {#env-vars}
 
-### 3. Configure the webhook
+| Platform | Required                                                                     | Optional                       |
+| -------- | ---------------------------------------------------------------------------- | ------------------------------ |
+| Slack    | `SLACK_BOT_TOKEN`, `SLACK_SIGNING_SECRET`                                    | —                              |
+| Telegram | `TELEGRAM_BOT_TOKEN`                                                         | —                              |
+| Email    | `EMAIL_AGENT_ADDRESS`, plus one of `RESEND_API_KEY` or `SENDGRID_API_KEY`    | `EMAIL_INBOUND_WEBHOOK_SECRET` |
+| WhatsApp | `WHATSAPP_ACCESS_TOKEN`, `WHATSAPP_VERIFY_TOKEN`, `WHATSAPP_PHONE_NUMBER_ID` | —                              |
 
-In the Meta Developer Portal, set the webhook URL to:
+All credentials live in env vars — never the database, never source code. Use the sidebar settings UI or your hosting provider's env panel.
 
-```text
-https://your-app.example.com/_agent-native/integrations/whatsapp/webhook
-```
+### Threading and identity {#threading-and-identity}
 
-Subscribe to the `messages` webhook field.
+Each external conversation maps to a persistent thread in the agent-native database:
 
-## Configuration {#configuration}
+- **Slack DM** → one thread per Slack user.
+- **Slack channel @mention** → one thread per channel.
+- **Telegram chat** → one thread per Telegram chat.
+- **WhatsApp conversation** → one thread per WhatsApp number.
+- **Email** → threading derived from `Message-ID` / `In-Reply-To` / `References` headers.
 
-Integrations can be managed from the settings UI in the sidebar. Each platform shows its connection status and webhook URL. You can enable/disable individual integrations without removing environment variables.
+External threads appear in the web UI alongside web-originated threads, tagged with their source platform. Identity resolution: when a Slack/email user matches a registered user (typically by email), they're linked to that account.
 
-The webhook URLs follow a consistent pattern:
+### Security {#security}
 
-```text
-/_agent-native/integrations/<platform>/webhook
+Every incoming webhook is signature-verified before processing:
 
-# Examples:
-/_agent-native/integrations/slack/webhook
-/_agent-native/integrations/email/webhook
-/_agent-native/integrations/telegram/webhook
-/_agent-native/integrations/whatsapp/webhook
-```
+- **Slack** — HMAC-SHA256 of the body using `SLACK_SIGNING_SECRET`, checked against the `X-Slack-Signature` header.
+- **Telegram** — secret token set when registering the webhook.
+- **WhatsApp** — Meta's verification challenge (using `WHATSAPP_VERIFY_TOKEN`) plus payload signature.
+- **Email** — Svix-style signature verification when `EMAIL_INBOUND_WEBHOOK_SECRET` is set (Resend and SendGrid both use this format). If the secret is unset, the webhook is accepted but a warning is logged.
 
-## Thread continuity {#thread-continuity}
+The email adapter also enforces:
 
-Conversations from external platforms are mapped to internal threads. Each Slack DM, email thread, Telegram chat, or WhatsApp conversation becomes a persistent thread in the agent-native database. This means:
+- **Allowed domains** — optional `allowedDomains` array in the integration's `integration_configs` row; senders outside the list are dropped.
+- **Rate limit** — in-memory limiter at 20 inbound messages per sender per hour.
 
-- The agent retains context across messages in the same external conversation
-- External conversations appear in the web UI alongside web-originated threads, tagged with their source platform
-- You can continue a conversation that started in Slack from the web UI, or vice versa
+### Proactive sends {#proactive-sends}
 
-For email specifically, threading uses the `Message-ID`, `In-Reply-To`, and `References` headers — the oldest Message-ID in the References chain is treated as the thread root, matching Gmail's behavior.
+The agent can send messages on its own initiative (notifications, reminders, scheduled summaries) by calling the `send-platform-message` action with a `platform` field of `"slack"`, `"telegram"`, `"whatsapp"`, or `"email"`. The action lives in the Dispatch template at `actions/send-platform-message.ts` and you can copy/adapt it for any template.
 
-## Custom adapters {#custom-adapters}
+### Custom adapters {#custom-adapters}
 
-To add support for a new messaging platform, implement the `PlatformAdapter` interface:
+To add a new messaging platform, implement the `PlatformAdapter` interface:
 
 ```ts
 import type { PlatformAdapter } from "@agent-native/core/server";
@@ -239,12 +283,12 @@ import type { PlatformAdapter } from "@agent-native/core/server";
 const myAdapter: PlatformAdapter = {
   platform: "discord",
 
-  // Verify the incoming webhook request is authentic
+  // Verify the incoming webhook is authentic
   verifyRequest(request: Request): Promise<boolean> {
     // Validate signature headers
   },
 
-  // Extract the message text and thread context from the webhook payload
+  // Extract the message text and thread context
   parseMessage(body: unknown): Promise<{
     text: string;
     threadId: string;
@@ -254,14 +298,14 @@ const myAdapter: PlatformAdapter = {
     // Parse platform-specific payload
   },
 
-  // Send the agent's response back to the platform
+  // Post the agent's response back
   sendResponse(threadId: string, text: string): Promise<void> {
-    // Call the platform's API to post the message
+    // Call the platform's API
   },
 };
 ```
 
-Register your adapter in the integrations plugin config:
+Register it in your integrations plugin:
 
 ```ts
 export default createIntegrationsPlugin({
@@ -271,14 +315,10 @@ export default createIntegrationsPlugin({
 });
 ```
 
-## Security {#security}
-
-Every incoming webhook is verified before processing:
+Reference implementations live in `packages/core/src/integrations/adapters/` (`slack.ts`, `telegram.ts`, `whatsapp.ts`, `email.ts`) — the email adapter is the most complete example, including signature verification, threading, rate limiting, and HTML rendering.
 
-- **Slack** — HMAC-SHA256 signature verification using `SLACK_SIGNING_SECRET`. The `X-Slack-Signature` header is checked against the request body.
-- **Email (Resend)** — Svix signature verification using `EMAIL_INBOUND_WEBHOOK_SECRET`, with a 5-minute replay window.
-- **Email (SendGrid)** — basic auth or `x-webhook-secret` header matching `EMAIL_INBOUND_WEBHOOK_SECRET`. Plus optional `allowedDomains` filtering on the sender.
-- **Telegram** — requests are validated by checking the secret token set during webhook registration via the Telegram Bot API.
-- **WhatsApp** — Meta's webhook verification challenge (using `WHATSAPP_VERIFY_TOKEN`) and payload signature validation.
+### See also {#see-also}
 
-All platform credentials (tokens, secrets, API keys) are stored as environment variables and never persisted in the database or source code. Use the settings UI or your deployment platform's env var management to configure them.
+- [Dispatch template](/docs/template-dispatch) — recommended central inbox for multi-app workspaces
+- [A2A Protocol](/docs/a2a-protocol) — how Dispatch delegates work to other agents
+- [Agent Mentions](/docs/agent-mentions) — `@`-mentioning agents inside the web chat