@agent-native/core 0.92.12 → 0.94.0

package/corpus/core/docs/content/messaging.mdx

@@ -1,19 +1,25 @@
 ---
 title: "Messaging"
-description: "Talk to your agent from Slack, email, Telegram, or WhatsApp — same agent, same memory, same tools."
+description: "Talk to your agent from Slack, Microsoft Teams, Discord interactions, email, Telegram, or WhatsApp."
 ---
 
 # Messaging
 
-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.
+Connect your agent to Slack, Microsoft Teams, Discord interactions, email, Telegram, or WhatsApp. It's the same agent — same memory, same tools, same threads — just reachable from more places.
 
-> **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/dispatch) or the [Dispatch template reference](/docs/template-dispatch).
+<Callout tone="info">
+
+**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/dispatch) or the [Dispatch template reference](/docs/template-dispatch).
+
+</Callout>
 
 ## What you can do {#what-you-can-do}
 
 - **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 bot in Microsoft Teams** in an allowed tenant.
+- **Run a Discord slash command.** The built-in Discord adapter handles HTTP interactions; ordinary Discord messages require a separate Gateway runtime.
 - **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.
 - For one-way in-app alerts (bell icon, webhooks) see [Notifications](/docs/notifications).
@@ -24,6 +30,8 @@ Connect your agent to Slack, email, Telegram, or WhatsApp so you can chat with i
 <div class="msg-fanin">
   <div class="diagram-col">
     <div class="diagram-node">Slack</div>
+    <div class="diagram-node">Microsoft Teams</div>
+    <div class="diagram-node">Discord interactions</div>
     <div class="diagram-node">Email</div>
     <div class="diagram-node">Telegram</div>
     <div class="diagram-node">WhatsApp</div>
@@ -71,36 +79,132 @@ Connect your agent to Slack, email, Telegram, or WhatsApp so you can chat with i
 - A Slack workspace where you can install apps (admin access)
 - About 5 minutes
 
-### Steps
+### Managed Add to Slack
+
+Managed OAuth is the recommended setup for Dispatch and multi-workspace apps.
+Each install gets its own encrypted bot-token bundle and health record, and
+Slack workspace, app, channel, and thread IDs are part of the conversation key.
+
+1. In **Settings → Messaging**, select **Agent manifest** to download the
+   host-specific `agent-native-slack-manifest.json`, then create or update your
+   Slack app at **[api.slack.com/apps](https://api.slack.com/apps)** by importing
+   it from **App Manifest**. The manifest enables Slack's current `agent_view`
+   experience plus a writable App Home **Messages** tab for direct messages.
+   Slack app icons are not part of the manifest. Under **Basic Information →
+   Display Information**, upload the Agent Native icon so the Agents picker
+   matches the product; you can use the app's public `icon-512.svg` as the source
+   and convert it to a Slack-supported upload format if needed.
+2. Verify that the manifest requests these exact **Bot Token Scopes** under
+   **OAuth & Permissions**:
 
-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
-   - `assistant:write` — optional; lets Slack show native "is thinking..." status in assistant threads
-   - `users:read.email` — optional; helps templates such as Mail verify Slack sender email for draft-queue identity
-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
-   - `SLACK_ALLOWED_TEAM_IDS` — recommended in production; comma-separated Slack workspace/team IDs allowed to send events
-   - `SLACK_ALLOWED_API_APP_IDS` — recommended for multi-workspace apps; comma-separated Slack app IDs allowed to use this signing secret
-6. Back in Slack, open **Event Subscriptions**, toggle it on, and paste this Request URL:
+   ```text
+   assistant:write
+   app_mentions:read
+   channels:history
+   channels:read
+   chat:write
+   files:read
+   groups:history
+   groups:read
+   im:history
+   im:read
+   mpim:history
+   mpim:read
+   pins:read
+   reactions:read
+   users:read
+   users:read.email
+   ```
+
+3. Add this **OAuth Redirect URL**:
+
+   ```text
+   https://your-app.example.com/_agent-native/integrations/slack/oauth/callback
+   ```
+
+4. Turn on **Event Subscriptions**, set the **Request URL**, and subscribe to
+   `app_home_opened`, `app_context_changed`, `app_mention`, `message.channels`,
+   `message.groups`, `message.im`, and `message.mpim`:
 
    ```text
    https://your-app.example.com/_agent-native/integrations/slack/webhook
    ```
 
-   Then under **Subscribe to bot events**, add `message.im` (for DMs) and optionally `app_mention` (for channel mentions). Save.
+5. Turn on **Interactivity & Shortcuts** and set its **Request URL**:
+
+   ```text
+   https://your-app.example.com/_agent-native/integrations/slack/interactions
+   ```
 
-7. Send your bot a DM in Slack. It should reply.
+6. Configure `SLACK_CLIENT_ID`, `SLACK_CLIENT_SECRET`, and
+   `SLACK_SIGNING_SECRET` on your app. Then open **Settings → Messaging** and
+   click **Add to Slack**. Only an organization owner or admin can create a
+   shared workspace install.
+7. Reinstall the Slack app after applying or changing the manifest, scopes,
+   events, Agent view, or Messages tab so the installation receives the updated
+   permissions and surfaces.
+
+In the current Agent view, `app_home_opened` detects when someone opens the
+Messages tab, `app_context_changed` provides the Slack surface they are viewing,
+and `message.im` delivers their direct messages. Slack owners and admins can hide
+installed agents for the workspace or organization, and each member can hide an
+agent from their own top bar. If the install succeeds but the agent is not
+visible there, check those Slack display controls or open it from **Tools →
+Apps**.
+
+The OAuth entry and callback endpoints are
+`/_agent-native/integrations/slack/oauth/install` and
+`/_agent-native/integrations/slack/oauth/callback`. Slack access and refresh
+tokens remain server-side. The canonical manifest leaves Slack token rotation
+disabled.
+Use the install health control in Messaging settings to test or disconnect a
+workspace.
+
+### Legacy single-workspace setup
+
+For a private, single-workspace deployment, you can still install the app
+manually and configure `SLACK_BOT_TOKEN` plus `SLACK_SIGNING_SECRET`.
+`SLACK_ALLOWED_TEAM_IDS` and `SLACK_ALLOWED_API_APP_IDS` are recommended in
+production. The environment token is a compatibility fallback; managed installs
+take precedence.
+
+### Slack-native collaboration
+
+- **Active thread steering.** Start in a channel with an `@mention`. While that
+  exact task is queued or running, ordinary replies in its Slack thread continue
+  the task without another mention. Inactive threads and general channel chatter
+  do not invoke the agent. DMs remain direct invocations.
+- **Bounded native context.** Before execution, the adapter loads a bounded
+  slice of the Slack thread plus channel, sender, reaction, and file metadata.
+  It keeps file references and permalinks, never raw file bodies, in durable
+  integration state.
+- **Live work card.** Slack's streaming task surface shows the plan, tool and
+  delegated-agent progress, and final answer. The requester can cancel a running
+  task or approve/deny a gated action from signed, single-use controls.
+  `assistant:write` enables Agent View context events; `chat:write` powers
+  replies and live status updates.
+- **Personal and channel identity.** A personal Slack DM is accepted only for a
+  verified Agent Native organization member or a Slack identity already linked
+  to that member. Configured channels instead run as the channel's explicit
+  service principal, with separate channel policies and budgets, so shared tools
+  and connections do not silently inherit the latest speaker's personal access.
+- **Explicit channel memory.** Channel memory is isolated by authorized
+  conversation scope. The agent saves or removes it only when someone explicitly
+  asks; ordinary conversation is not auto-memorized.
+- **Channel routines.** A recurring job created from Slack keeps its origin
+  scope, destination, thread, workspace, and optional model, then delivers its
+  scheduled result back to that Slack conversation.
+- **Governance.** Messaging settings expose configured-channel controls for
+  guest access, Slack Connect, service principals, default models, and budgets.
+  Daily or monthly organization, requester, and channel budgets are reserved
+  before a run and settled from actual usage. Audit and usage records keep
+  platform, workspace, channel, requester, task, run, source URL, and model
+  lineage.
 
 ### Optional: app unfurls
 
 Slack app unfurls let an app replace Slack's normal link preview with a richer
-preview. Clips uses this for Loom-style playable video previews.
+preview. Clips uses this for playable async screen-recording previews.
 
 Add these extra bot scopes when your app needs unfurls:
 
@@ -123,11 +227,59 @@ and `link_shared` events to the Clips unfurl handler.
 
 ### Tips
 
-- **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.
+- **Channel mentions** — use an @mention to start work. Unmentioned replies are accepted only while that exact thread has active work.
+- **DMs** — accepted personal DMs are private conversations and require a verified organization member or linked Slack identity.
+- **Identity** — personal DMs require a verified Agent Native organization member or an already linked Slack identity. Configured channels use a separate service principal, policy, and budget.
 - **Production allowlists** — set `SLACK_ALLOWED_TEAM_IDS` and, for shared Slack apps, `SLACK_ALLOWED_API_APP_IDS` so a valid signing secret cannot be reused by an unexpected workspace.
-- **Clips app unfurls** — installable Agent-Native Clips for Slack uses `SLACK_CLIENT_ID`, `SLACK_CLIENT_SECRET`, `SLACK_SIGNING_SECRET`, and `/api/slack/oauth/callback`. Each connected Slack workspace gets its own encrypted bot token in `app_secrets`; `SLACK_BOT_TOKEN` is only a legacy single-workspace fallback.
+- **Clips app unfurls** — Clips can share the managed Slack app credentials, but a Slack app has only one Events API Request URL; route `link_shared` to Clips when chat and unfurls share an app.
+
+## Set up Microsoft Teams {#microsoft-teams}
+
+The built-in Teams adapter uses the Bot Framework activity endpoint. Incoming
+JWTs are validated with Microsoft's `botframework-connector`, including issuer,
+audience, signed service URL, and Teams channel endorsement checks.
+
+1. Create a Microsoft Entra app registration and Azure Bot resource.
+2. Configure:
+   - `MICROSOFT_TEAMS_APP_ID`
+   - `MICROSOFT_TEAMS_APP_PASSWORD`
+   - `MICROSOFT_TEAMS_APP_TENANT_ID` for a single-tenant registration
+   - `MICROSOFT_TEAMS_ALLOWED_TENANT_IDS` as a comma-separated production allowlist
+3. Set the Azure Bot messaging endpoint to:
+
+   ```text
+   https://your-app.example.com/_agent-native/integrations/microsoft-teams/webhook
+   ```
+
+4. Add the Microsoft Teams channel to the bot and install it in an allowlisted tenant.
+
+Replies use the signed `serviceUrl`, conversation ID, and activity ID from the
+inbound activity. Proactive sends without an inbound conversation reference are
+not currently supported.
+
+## Set up Discord interactions {#discord}
+
+Discord supports HTTP interactions and persistent Gateway events. The built-in
+adapter implements **HTTP interactions only**: slash commands are verified with
+Discord's Ed25519 signature, acknowledged with a deferred type-5 response, and
+completed by editing the original interaction response. It does not claim to
+receive ordinary server messages or DMs.
+
+1. Create a Discord application and configure:
+   - `DISCORD_APPLICATION_ID`
+   - `DISCORD_PUBLIC_KEY`
+2. Set **Interactions Endpoint URL** to:
+
+   ```text
+   https://your-app.example.com/_agent-native/integrations/discord/webhook
+   ```
+
+3. Register a chat-input command with a string prompt option and install the
+   command for the intended server or users.
+
+Discord requires the initial response within 3 seconds. Interaction tokens are
+valid for 15 minutes and are stored only in the active queue payload; terminal
+queue rows erase that payload.
 
 ## Set up Telegram {#telegram}
 
@@ -142,6 +294,7 @@ and `link_shared` events to the Clips unfurl handler.
 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
+   - `TELEGRAM_WEBHOOK_SECRET` — a random secret used to authenticate webhook deliveries
 4. After deploying, register the webhook by `POST`ing to your app at:
 
    ```text
@@ -152,6 +305,10 @@ and `link_shared` events to the Clips unfurl handler.
 
 5. Find your bot in Telegram (search for the username BotFather gave you) and send it a message.
 
+Telegram forum topics and private-chat topics keep `message_thread_id` in the
+canonical conversation identity. Replies preserve both the topic and the
+inbound message through Bot API `reply_parameters`.
+
 ## Set up Email {#email}
 
 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.
@@ -232,6 +389,7 @@ Email is the most powerful integration — your agent gets its own address, repl
    - `WHATSAPP_ACCESS_TOKEN` — your access token
    - `WHATSAPP_PHONE_NUMBER_ID` — the phone number ID
    - `WHATSAPP_VERIFY_TOKEN` — the random string you picked
+   - `WHATSAPP_APP_SECRET` — the Meta app secret used to verify webhook HMAC signatures
 6. Back in Meta's WhatsApp config, open the webhook section and set:
 
    ```text
@@ -243,6 +401,8 @@ Email is the most powerful integration — your agent gets its own address, repl
 
 7. Send a WhatsApp message to the bot's phone number.
 
+Replies quote the inbound WhatsApp message using its `wamid` when available.
+
 ## Use Dispatch as your agent's central inbox {#dispatch}
 
 If you're running multiple agent-native apps (mail, calendar, analytics, etc.), the recommended pattern is to set up messaging on **[Dispatch](/docs/dispatch)** (see also the [template reference](/docs/template-dispatch)) and let it route work to your domain apps over [A2A](/docs/a2a-protocol).
@@ -415,6 +575,8 @@ Which platforms are active depends on which env vars are set. The plugin registe
 
 ```text
 /_agent-native/integrations/slack/webhook
+/_agent-native/integrations/microsoft-teams/webhook
+/_agent-native/integrations/discord/webhook
 /_agent-native/integrations/telegram/webhook
 /_agent-native/integrations/whatsapp/webhook
 /_agent-native/integrations/email/webhook
@@ -428,14 +590,20 @@ POST /_agent-native/integrations/telegram/setup
 
 ### Environment variables {#env-vars}
 
-| Platform | Required                                                                     | Optional                                              |
-| -------- | ---------------------------------------------------------------------------- | ----------------------------------------------------- |
-| Slack    | `SLACK_BOT_TOKEN`, `SLACK_SIGNING_SECRET`                                    | `SLACK_ALLOWED_TEAM_IDS`, `SLACK_ALLOWED_API_APP_IDS` |
-| 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` | —                                                     |
+| Platform        | Required                                                                                                                                                                    | Optional                                              |
+| --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------- |
+| Slack           | `SLACK_SIGNING_SECRET`, plus either `SLACK_CLIENT_ID`+`SLACK_CLIENT_SECRET` ([managed OAuth](#slack), recommended) or `SLACK_BOT_TOKEN` ([legacy single-workspace](#slack)) | `SLACK_ALLOWED_TEAM_IDS`, `SLACK_ALLOWED_API_APP_IDS` |
+| Microsoft Teams | `MICROSOFT_TEAMS_APP_ID`, `MICROSOFT_TEAMS_APP_PASSWORD`, `MICROSOFT_TEAMS_ALLOWED_TENANT_IDS`                                                                              | `MICROSOFT_TEAMS_APP_TENANT_ID`                       |
+| Discord         | `DISCORD_APPLICATION_ID`, `DISCORD_PUBLIC_KEY`                                                                                                                              | —                                                     |
+| Telegram        | `TELEGRAM_BOT_TOKEN`, `TELEGRAM_WEBHOOK_SECRET`                                                                                                                             | —                                                     |
+| 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`, `WHATSAPP_APP_SECRET`                                                                         | —                                                     |
 
-All credentials live in env vars — never the database, never source code. Use the sidebar settings UI or your hosting provider's env panel.
+For Slack, `SLACK_BOT_TOKEN`, `SLACK_CLIENT_ID`, and `SLACK_CLIENT_SECRET` are each individually optional at the adapter level — only `SLACK_SIGNING_SECRET` is unconditionally required — because either credential set satisfies setup. Use managed OAuth (`SLACK_CLIENT_ID`/`SLACK_CLIENT_SECRET`) for Dispatch and multi-workspace apps; `SLACK_BOT_TOKEN` is the compatibility path for a single-workspace deployment installed by hand. See [Set up Slack](#slack) above for both flows.
+
+Integration credentials resolve from the integration owner's scoped secrets first (user, org, then workspace), with deployment env vars available as a local or deliberate single-tenant fallback. The setup UI saves scoped secrets; use deployment configuration only when you intentionally want one shared integration identity. Values are never returned to the browser or stored in source code.
+
+The built-in runtime adapters are **Slack**, **Microsoft Teams**, **Discord interactions**, **Telegram**, **WhatsApp Cloud API**, and **provider-webhook email** (Resend or SendGrid). Discord support is interaction-only; ordinary Discord message ingestion is not included.
 
 ### Threading and identity {#threading-and-identity}
 
@@ -443,8 +611,10 @@ Each external conversation maps to a persistent thread in the agent-native datab
 
 - **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.
+- **Microsoft Teams** → tenant + team/channel + Bot Framework conversation.
+- **Discord interaction** → application + guild/DM + channel.
+- **Telegram chat** → one thread per chat and `message_thread_id` topic.
+- **WhatsApp conversation** → business phone-number ID + sender number.
 - **Email** → threading derived from `Message-ID` / `In-Reply-To` / `References` headers.
 
 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.
@@ -454,6 +624,8 @@ External threads appear in the web UI alongside web-originated threads, tagged w
 Every incoming webhook is signature-verified before processing:
 
 - **Slack** — HMAC-SHA256 of the body using `SLACK_SIGNING_SECRET`, checked against the `X-Slack-Signature` header. The first time you save a Request URL in Slack's Event Subscriptions panel, Slack POSTs a `url_verification` challenge to it; the framework's adapter detects this and replies with the `challenge` value automatically, so the URL flips green in Slack without any extra work on your end.
+- **Microsoft Teams** — Microsoft Bot Framework JWT verification, including signing keys, issuer, app audience, service URL claim, channel endorsement, and tenant allowlist.
+- **Discord** — Ed25519 verification over the timestamp plus exact raw body. Invalid PING probes return 401.
 - **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.
@@ -465,7 +637,7 @@ The email adapter also enforces:
 
 ### Proactive sends {#proactive-sends}
 
-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 package at `packages/dispatch/src/actions/send-platform-message.ts` and you can copy/adapt it for any template.
+The agent can send messages on its own initiative through the Dispatch `send-platform-message` action for `"slack"`, `"telegram"`, or `"email"`. Microsoft Teams requires a saved Bot Framework conversation reference, Discord interaction tokens expire, and the WhatsApp adapter does not implement template-message proactive sends, so those three are reply-only.
 
 ### Custom adapters {#custom-adapters}
 
@@ -481,13 +653,20 @@ import type {
 import type { EnvKeyConfig } from "@agent-native/core/server";
 
 const myAdapter: PlatformAdapter = {
-  platform: "discord",
-  label: "Discord",
+  platform: "my-chat",
+  label: "My Chat",
+  capabilities: {
+    replyText: true,
+    proactiveMessages: false,
+    nativeThreads: true,
+    contextualReplies: true,
+    deferredWebhookResponse: false,
+  },
 
   // Env keys this adapter needs (rendered in the settings UI)
   getRequiredEnvKeys(): EnvKeyConfig[] {
     return [
-      { key: "DISCORD_BOT_TOKEN", label: "Discord Bot Token", required: true },
+      { key: "MY_CHAT_BOT_TOKEN", label: "My Chat Bot Token", required: true },
     ];
   },
 
@@ -499,18 +678,21 @@ const myAdapter: PlatformAdapter = {
 
   // Validate the webhook request signature
   async verifyWebhook(event: H3Event): Promise<boolean> {
-    // Validate signature headers; return true if authentic
-    return true;
+    // Implement the provider's documented signature/JWT verification here.
+    // Fail closed; never ship `return true` as a placeholder.
+    throw new Error("Webhook verification is not implemented");
   },
 
   // Parse the webhook payload into a normalized IncomingMessage.
   // Return null to silently ignore the event (bot messages, edits, etc.).
   async parseIncomingMessage(event: H3Event): Promise<IncomingMessage | null> {
     return {
-      platform: "discord",
+      platform: "my-chat",
       externalThreadId: "channel-or-thread-id",
       text: "the user's message",
-      senderId: "discord-user-id",
+      senderId: "my-chat-user-id",
+      threadRef: "provider-thread-id",
+      replyRef: "provider-message-id",
       platformContext: { channelId: "channel-id" },
       timestamp: Date.now(),
     };
@@ -538,15 +720,21 @@ const myAdapter: PlatformAdapter = {
   // baseUrl is the app's public URL, used for status checks that need it.
   async getStatus(baseUrl?: string) {
     return {
-      platform: "discord",
-      label: "Discord",
+      platform: "my-chat",
+      label: "My Chat",
       enabled: true,
-      configured: !!process.env.DISCORD_BOT_TOKEN,
+      configured: !!process.env.MY_CHAT_BOT_TOKEN,
     };
   },
 };
 ```
 
+If the provider requires an immediate response, implement
+`getImmediateWebhookResponse(incoming)`. Keep short-lived delivery credentials
+in `incoming.responseContext`, not `platformContext`; terminal queue rows erase
+the active payload. The response is returned only after verification and a
+durable queue insert.
+
 Register it in your integrations plugin:
 
 ```ts
@@ -557,7 +745,7 @@ export default createIntegrationsPlugin({
 });
 ```
 
-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.
+Reference implementations live in `packages/core/src/integrations/adapters/`. See `microsoft-teams.ts` for official JWT validation and token caching, `discord.ts` for signed deferred interactions, and `telegram.ts` or `whatsapp.ts` for native reply references.
 
 ### Reliability via Dispatch + A2A continuations {#reliability}
 
@@ -572,9 +760,11 @@ This means a multi-app workspace fronted by Dispatch is more resilient than a si
 - **Don't rely on dedup memory across cold starts.** The dedup key lives in the SQL `(platform, external_event_key)` unique index, not an in-process Map. If you replace the queue, keep the SQL-level dedup or duplicate Slack retries will trigger duplicate agent runs.
 - **Keep the self-webhook URL reachable.** The processor URL is built from `APP_URL` / `URL` / `DEPLOY_URL` / `BETTER_AUTH_URL`, falling back to the inbound request headers. On preview deploys with rewritten hostnames, set one of these explicitly or the dispatch will hit a 404.
 
-### See also {#see-also}
+## What's next {#whats-next}
 
 - [Dispatch](/docs/dispatch) — concept overview for using a central inbox across apps
 - [Dispatch template reference](/docs/template-dispatch) — recommended central inbox for multi-app workspaces
 - [A2A Protocol](/docs/a2a-protocol) — how Dispatch delegates work to other agents, including continuation recovery
+- [Workflow Connectors](/docs/automation-connectors) — pre-configured n8n/Zapier-style workflow invocation, distinct from a chat platform integration
+- [Security](/docs/security) — credential scoping and the webhook signature-verification model
 - [Agent Mentions](/docs/agent-mentions) — `@`-mentioning agents inside the web chat

package/corpus/core/docs/content/multi-app-workspace.mdx

@@ -5,7 +5,11 @@ description: "Host many agent-native apps in one monorepo with shared auth, RBAC
 
 # Multi-App Workspaces
 
-> **Which workspace doc?** This page covers the **deployment shape** — one monorepo, many apps, shared auth and a unified deploy. For what a workspace _is_ (the customization layer: `AGENTS.md`, `LEARNINGS.md`, personal memory, skills, custom agents) see [Workspace](/docs/workspace); for governance (who reviews, approves, and owns what) see [Workspace Governance](/docs/workspace-management).
+<Callout tone="info">
+
+**Which workspace doc?** This page covers the **deployment shape** — one monorepo, many apps, shared auth and a unified deploy. For what a workspace _is_ (the customization layer: `AGENTS.md`, `LEARNINGS.md`, personal memory, skills, custom agents) see [Workspace](/docs/workspace); for governance (who reviews, approves, and owns what) see [Workspace Governance](/docs/workspace-management).
+
+</Callout>
 
 When vibe-coding an internal tool takes an afternoon, you don't stop at one. A team ends up with a CRM, a support inbox, a dashboard, an ops console — ten small apps, each scaffolded independently. That's great until you need to change something in all of them.
 
@@ -259,9 +263,7 @@ A few onboarding flows are workspace-aware out of the box:
 - **Builder `/cli-auth`**: clicking "Connect Builder" from any app writes `BUILDER_PRIVATE_KEY` and friends to scoped DB secrets, so every app can resolve the connection without sharing a deploy-global key.
 - **Compatibility key route** (`POST /_agent-native/env-vars`): older onboarding forms still call this route name, but it now saves values as scoped DB secrets. Pass `scope: "workspace"` to share with the active org, or omit it for a per-user key.
 
-## Shared credentials {#shared-credentials}
-
-Apps in the same workspace point at the same `DATABASE_URL` by default, so framework credential storage can make a credential available to every app without per-app config. Use `@agent-native/core/credentials` directly, or add a thin helper in `packages/shared` if your workspace wants a stricter naming convention.
+This works because every app in the same workspace points at the same `DATABASE_URL` by default, so framework credential storage (`@agent-native/core/credentials`) makes a credential available to every app without per-app config. Add a thin helper in `packages/shared` if your workspace wants a stricter naming convention.
 
 ## Shared design tokens {#design-tokens}
 
@@ -284,87 +286,12 @@ Brand colors, typography, spacing scales, and any shared component classes can l
 
 ## Deployment {#deployment}
 
-You have two options: **unified deploy** (the default for workspaces) or per-app independent deploy.
-
-### Unified deploy (recommended)
+You have two options: **unified deploy** (the default for workspaces) or per-app independent deploy. [Deployment — Workspace Deploy](/docs/deployment#workspace-deploy) covers the full command, per-preset details (Cloudflare, Netlify, Vercel), and a diagram of the shape; the tradeoff:
 
-One command builds every app in the workspace and ships them behind a single origin, one path per app:
-
-```bash
-npx @agent-native/core@latest deploy
-# https://your-agents.com/mail/*       → apps/mail
-# https://your-agents.com/calendar/*   → apps/calendar
-# https://your-agents.com/forms/*      → apps/forms
-```
+- **Unified deploy (recommended)** — `npx @agent-native/core@latest deploy` builds every app in the workspace and ships them behind a single origin, one path per app (`your-agents.com/mail/*`, `/calendar/*`, ...). Being on the same origin is where the real payoff lives: a shared login session (log into any app, every app is logged in), zero-config cross-app A2A (`@mail` tagging `@calendar` is a same-origin fetch — no CORS, no JWT signing between siblings), and one DNS record, cert, and CDN cache to manage.
+- **Per-app independent deploy** — prefer each app on its own domain (`mail.company.com`, `calendar.company.com`)? Every app in the workspace is still an independent deployable — `cd apps/mail && npx @agent-native/core@latest build` behaves exactly like a standalone scaffold. Cross-app A2A then goes through the standard JWT-signed path with a shared `A2A_SECRET`. Cross-domain SSO between separately-deployed apps is handled by identity federation with Dispatch as the hub — see [Cross-App SSO](/docs/cross-app-sso); the unified single-origin deploy avoids needing it. For a self-hosted VPS or Docker Compose setup on one origin instead, see [Deployment — Self-hosted workspace with Docker Compose](/docs/deployment#workspace-docker-compose).
 
-Each app is built with `APP_BASE_PATH=/<name>` and `VITE_APP_BASE_PATH=/<name>` and emitted through the selected Nitro preset. Cloudflare Pages is the default preset and uses a dispatcher worker at `dist/_worker.js` plus `_routes.json`. Netlify is supported with `npx @agent-native/core@latest deploy --preset netlify`; it emits app functions under `.netlify/functions-internal/<app>-server` and generated redirects that leave static assets unforced so the CDN serves files first. Vercel is supported with `npx @agent-native/core@latest deploy --preset vercel`; it writes a root `.vercel/output` bundle using Vercel's Build Output API.
-
-<Diagram id="doc-block-sntrhp" title="Unified deploy: one origin, one path per app" summary="Every app ships behind a single origin, so login sessions and cross-app A2A are free.">
-
-```html
-<div class="deploy">
-  <div class="diagram-box accent">
-    your-agents.com<br /><small class="diagram-muted"
-      >one DNS record &middot; one cert &middot; one CDN</small
-    >
-  </div>
-  <div class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</div>
-  <div class="deploy-apps">
-    <div class="diagram-box">/mail/*</div>
-    <div class="diagram-box">/calendar/*</div>
-    <div class="diagram-box">/forms/*</div>
-  </div>
-  <div class="diagram-pill ok">
-    shared login cookie on the apex &bull; same-origin A2A, no CORS
-  </div>
-</div>
-```
-
-```css
-.deploy {
-  display: flex;
-  align-items: center;
-  gap: 14px;
-  flex-wrap: wrap;
-}
-.deploy .deploy-apps {
-  display: flex;
-  flex-direction: column;
-  gap: 8px;
-}
-.deploy .diagram-arrow {
-  font-size: 24px;
-}
-.deploy .diagram-pill {
-  flex-basis: 100%;
-}
-```
-
-</Diagram>
-
-Being on the **same origin** is where the real payoff lives:
-
-- **Shared login session.** Better Auth sets its cookie on the apex domain, so logging into any app logs you into every app. No cross-domain SSO dance.
-- **Zero-config cross-app A2A.** `@mail` tagging `@calendar` becomes a same-origin fetch — no CORS, no JWT signing between siblings. External A2A still uses JWT as today.
-- **One DNS record, one cert, one CDN cache.**
-
-Publish the `dist/` output:
-
-```bash
-wrangler pages deploy dist
-```
-
-For Netlify:
-
-```bash
-npx @agent-native/core@latest deploy --preset netlify --build-only
-```
-
-For Vercel Git deployments, set the build command to:
-
-```bash
-npx @agent-native/core@latest deploy --preset vercel --build-only
-```
+Whichever you pick, point every app at the same `DATABASE_URL` for cross-app state out of the box: one set of user accounts, one set of organizations, one set of shared settings. The shared package itself is never deployed standalone — pnpm symlinks it into each app's `node_modules/` at build time.
 
 ### Public app routes
 
@@ -395,18 +322,6 @@ For mostly internal apps with a few public pages, leave the audience internal an
 
 These settings only affect read-only page navigation. Framework tools, agent chat, A2A, vault access, and arbitrary APIs stay authenticated unless the app explicitly declares public prefixes with `createAuthPlugin({ publicPaths: [...] })`.
 
-### Per-app independent deploy
-
-Prefer each app on its own domain (`mail.company.com`, `calendar.company.com`)? Every app in the workspace is still an independent deployable — `cd apps/mail && npx @agent-native/core@latest build` behaves exactly like a standalone scaffold. Cross-app A2A then goes through the standard JWT-signed path with a shared `A2A_SECRET`. Cross-domain SSO between separately-deployed apps is handled by identity federation with Dispatch as the hub — see [Cross-App SSO](/docs/cross-app-sso); the unified single-origin deploy avoids needing it.
-
-For a self-hosted VPS or Docker Compose setup on one origin, build and run one container per app with its own path prefix (`APP_BASE_PATH=/mail`, `APP_BASE_PATH=/calendar`, ...), then route those prefixes through a reverse proxy. See [Deployment — Self-hosted workspace with Docker Compose](/docs/deployment#workspace-docker-compose) for the Dockerfile and compose example.
-
-### Shared database, shared credentials
-
-Whatever you pick, point every app at the same `DATABASE_URL` for cross-app state out of the box: one set of user accounts, one set of organizations, one set of shared settings. If each app has its own database, the workspace pattern still works — you just lose that shared-state story.
-
-The shared package itself is never deployed standalone. It's a `workspace:*` dep that pnpm symlinks into each app's `node_modules/`, so every app transparently bundles whatever it needs at build time.
-
 ## Out of scope (for now) {#out-of-scope}
 
 The workspace pattern is intentionally narrow. A few things it deliberately doesn't handle yet:
@@ -415,7 +330,7 @@ The workspace pattern is intentionally narrow. A few things it deliberately does
 - **Publishing shared code to private npm.** The shared package is `workspace:*` only; multi-repo sharing via a private registry is doable but not scaffolded.
 - **Opinionated component library.** `packages/shared` is where _you_ put shared components. The framework doesn't force shadcn/ui or any other system into that slot.
 
-## See also {#see-also}
+## What's next {#whats-next}
 
 - [Workspace](/docs/workspace) — the customization layer (`AGENTS.md`, `LEARNINGS.md`, personal memory, skills, custom agents) every app in the workspace shares.
 - [Workspace Governance](/docs/workspace-management) — branching, CODEOWNERS, PR review across many apps in one repo.

package/corpus/core/docs/content/multi-tenancy.mdx

@@ -17,7 +17,7 @@ A fresh `npx @agent-native/core@latest create` scaffold already ships with:
 - **Org switching** — the session tracks the active org (`session.orgId`), and switching it changes the data the user and agent see.
 - **Per-org data isolation** — every query is automatically scoped to the active org.
 
-If you're evaluating agent-native for a CRM, project tracker, support inbox, or any team tool, the multi-tenant foundation is already there. All first-party templates are multi-tenant — see [Cloneable SaaS templates](/docs/cloneable-saas) for the list.
+If you're evaluating agent-native for a CRM, project tracker, support inbox, or any team tool, the multi-tenant foundation is already there. All first-party templates are multi-tenant — see [Templates](/docs/cloneable-saas) for the list.
 
 <Diagram id="doc-block-1nlyz0h" title="Org membership and isolation" summary={"Users join organizations as owner/admin/member. Every ownable row carries the org_id of the tenant that owns it, and no row leaks across the boundary."}>
 
@@ -117,8 +117,8 @@ Tenant data is isolated by an `org_id` column (added by `ownableColumns()`), and
 
 This is the same pipeline used for per-user scoping. For the SQL-level mechanics, the `ownableColumns()` contract, and the `accessFilter` / `resolveAccess` / `assertAccess` guards, see [Security → Data Scoping](/docs/security#data-scoping) — the single source of truth for the scoping pipeline.
 
-## Related docs {#related}
+## What's next {#related}
 
-- [Authentication](/docs/authentication#organizations) — sessions, social providers, and the org-management surface
-- [Security → Data Scoping](/docs/security#data-scoping) — SQL-level isolation, the `ownableColumns()` contract, and access guards
-- [Multi-App Workspace](/docs/multi-app-workspace) — hosting multiple agent-native apps in one monorepo with shared auth and RBAC
+- [**Authentication**](/docs/authentication#organizations) — sessions, social providers, and the org-management surface
+- [**Security — Data Scoping**](/docs/security#data-scoping) — SQL-level isolation, the `ownableColumns()` contract, and access guards
+- [**Multi-App Workspace**](/docs/multi-app-workspace) — hosting multiple agent-native apps in one monorepo with shared auth and RBAC